Modding:Cell
From DoomRL Wiki
| Notice | |
| This article discusses modding for DoomRL version 0.9.9.4. This version is unreleased, so details are subject to change. For information about 0.9.9.3 modding, try looking here | |
Cells are what make up the game world. You walk over them, open them, travel down their stairs, and blow up their barrels. Unlinke beings and items, cells aren't instantiated. All cells of a given type are exactly the same except for hp and light flags both of which must be accessed through the Level API.
Prototype
Once a cell is registered, changing the lua object will have no effect on how the cell operates (although it can affect some of the APIs). The exception to this is that hooks can be redefined (although which hooks are present can't be changed). Cell prototypes are declared by passing a table with the desired properties and hooks to the global Cells function. Required properties are underlined. Cells prototypes are stored in a global table called cells that can be indexed by string id or numeric id.
| Cell Prototype | ||
| string | name | This is the name of the cell that is displayed in game messages. |
| string | id | This is the string id that is used to reference the cell prototype internally. (A numeric id called nid is generated automatically.) The default is the first word of the name in all lowercase. |
| string | ascii | This should be a single character string. It is used to display cells on the map. |
| string | asciilow | If the ascii property is not once of the standard visible ASCII characters, then asciilow should be one of these standard characters to accomodate players that don't have support for an extended character selection. Whether or not to use asciilow is configurable by the player in config.lua. |
| integer | spirte | This indicates the sprite used to represent the cell in the graphical version. Use 0 to indicate no sprite. |
| Color | color | This is the color used to draw the cell when it is in the player's line-of-sight. The default is LIGHTGRAY. |
| Color | color_dark | This is the color used to draw the cell when it has been explored, but is not in the player's line-of-sight. The default is DARKGRAY. |
| string | color_id | If this is defined, then for the purposes of user color configuration, this is the cell's ID. Use this to force several cells to have the same color even if the user tries to redefine them. |
| integer | effect | This is a multi-purpose cell property. Currently it is only used to specify the corresponding being ID for corpses (as 100 plus the being ID). As most corpses are generated automatically, most modders won't need to worry about this. The default is 0. |
| integer | armor | This is the amount of armor the cell has. All damage to the cell is reduced by this value (regardless of damage type, although some damage types may not affect the cell at all; see CF_FRAGILE). This can reduce damage to 0. If the cell's armor is 0, then it cannot be destroyed by damage. The default is 0. |
| integer | hp | This is the initial amount of hp for the cell. If the cell is damaged, the hp for that particular cell (not the prototype) is reduced, and the cell isn't destroyed until it drops to 0. Cells with 0 hp must still be damaged to be destroyed. Be careful: changing cells after the beginning of the level doesn't usually update cells' current hp. The default is 0. |
| Cell Flag list | flags | The flags in this list will be included in the cell's flag set. A property called flag_set is automatically created containing these flags in set format. The default is an empty list. |
| Cell ID | bloodto | If defined, then the cell will transmute to the given new cell when it is affected by blood. This must be a string id. |
| Cell ID | destroyto | If the cell is destroyed, it will transmute to the given new cell. This must be a string id. The default is "floor". |
| Cellset | set | The cellsets are groupings for cells. They aren't used very much. Most notably, beings will only leave corpses on cells in CELLSET_FLOORS. By default, the cell won't be included in a set. |
Engine Hooks
Although these hooks should be defined with a coord as the first argument, they are immediately translated into a new function that has x and y as its first two arguments. This is important when replacing the hooks after the fact or calling the hooks manually. For all hooks, the first argument is the coord of the cell that caused the hook.
| Cell Hooks | |
| void | OnEnter(Coord c, Being enterer) |
| void | OnExit(Coord c) |
| void | OnAct(Coord c, Being actor) |
| string | OnDescribe(Coord c) |
| void | OnDestroy(Coord c) |
- OnEnter(Coord c, Being enterer)
- This hooks is called at the beginning of a being's turn if it is standing on the cell. (This triggers even if the being hasn't moved since its last turn.)
- OnExit(Coord c)
- This hook is called if the player uses the descend stairs action on the cell. That action is only allowed if this hook is defined. This hook also allows saving which is designed to work it the hook moves the player to the next level.
- OnAct(Coord c, Being actor)
- This hook is called when a being opens or closes a cell. Opening and closing must be allowed by the CF_OPENABLE and CF_CLOSEABLE flags respectively.
- OnDescribe(Coord c) → string
- If this hook is defined, then it is used instead of the cell name for in game messages.
- OnDestroy(Coord c)
- This hook is called after a cell is destroyed. (The hook for the previous cell is used even though the cell has already been transmuted to the destroyto value.)
