Modding:Cell
From DoomRL Wiki
Revision as of 20:08, 31 January 2012 by Game Hunter (Talk | contribs)
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 | sprite | 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. |
Cell Flags
| Cell Flags | |
| CF_BLOCKMOVE | Cells with this flag block movement and projectiles. |
| CF_BLOCKLOS | Cells with this flag block vision. |
| CF_CORPSE | This flag is set for autogenerated corpses. Only cells with this flag can be ressurected. The being created by resurrection can be specified by setting the cell's effect parameter to 100 + being.id. Note that the "corpse" cell does not have this flag. To include this cell, use Level.is_corpse. |
| CF_NOCHANGE | Currently, this flag is only checked by the map powerups. The map powerups reveal cells with this flag (as well as CF_BLOCKMOVE cells). |
| CF_NORUN | The run command (not the run tactic) will stop the player before he steps on a cell with this flag. |
| CF_PUSHABLE | Cells with this flag can be pushed (like barrels in DoomRL). Pushing is mostly hard-coded. |
| CF_FRAGILE | Cells with this flag can be destroyed by any damage type (assuming they have HP or armor) whereas cells cannot usually be damaged by bullet, melee, shrapnel, or piercing damage. |
| CF_HAZARD | This flag should be set for cells that are dangerous to step on. The AI will usually avoid these tiles. This flag is also used with the EF_NOHARM empty flag. |
| CF_OVERLAY | This flag is related to the graphical version. |
| CF_MULTISPRITE | This flag is related to the graphical version. |
| CF_STICKWALL | This flag is related to the graphical version. |
| CF_LIQUID | This flag is used to mark liquid cells (water, acid, lava). Currently, it is only checked by Level.flood which will flood over CELLSET_FLOORS cells and CF_LIQUID cells. |
| CF_OPENABLE | This flag indicates that the cell can be opened. What happens when the cells is opened is determined by the cell's OnAct hook. |
| CF_CLOSABLE | As CF_OPENABLE, but for the close command. |
| CF_RUNSTOP | Cells with this flag will stop the player's run when the player is orthogonally adjacent. Contrast with CF_NORUN. |
| CF_NUKABLE | Cells with this flag will be destroyed be a nuke even if they are normally not destructible. |
| CF_CRITICAL | Cells with this flag should usually not be altered or destroyed be the game. It is currently only checked by the flooding level event. Stairs have this flag. |
| CF_HIGHLIGHT | This flag determines whether the light or dark color variant is used when a StatusEffect overlay is being applied. |
| CF_BLOODY | When a being walks on one of these cells, its feet won't become less bloody. (See CF_BLOODY.) |
| CF_VBLOODY | When a being walks on one of these cells, its feet will become bloody and it will temporarily leave a trail of blood. |
| CF_STAIRS | Stairs are marked with this flag. (New stairs cells should include this.) |
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.)
