Modding:Cell

From DoomRL Wiki

Revision as of 16:21, 18 July 2013 by Rabinowitz (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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. Overlays are drawn OVER a base tile.
CF_MULTISPRITE This flag is related to the graphical version. Cells which have rotations (walls being the main example) need this flag.
CF_STICKWALL This flag is related to the graphical version. When a multisprite wall is calculating its rotations it takes stickwalls into account. That way wall-like cells (such as doors) will be attached to the multisprite walls correctly.
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.)
CF_RAISABLE

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.)
Personal tools