Difference between revisions of "Modding:Cell"

From DoomRL Wiki

Jump to: navigation, search
m (removed 0994 warning)
m (and some more)
Line 2: Line 2:
  
 
== Prototype ==
 
== 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.
 
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.
{|style="border: 2px solid darkred; border-spacing: 0; font-size: 90%; margin: 0.25em 0.5em;"
+
 
|colspan=3 style="background: darkred; color: yellow; font-size: 120%; text-align: center"|'''Cell Prototype'''
+
{|class="wikitable" style="border: 2px solid darkred; border-spacing: 0; font-size: 90%; margin: 0.25em 0.5em;"
|-
+
! colspan="3" style="background: darkred; color: yellow; font-size: 120%; text-align: center"|Cell Prototype
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|'''string'''
+
{{Table3Col
|style="vertical-align:top; padding-right: 2ex;"|<span style="text-decoration:underline;">name</span>
+
  |es=background: #333;
|This is the name of the cell that is displayed in game messages.
+
  |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px;
|-style="background: #333;"
+
  |c2=vertical-align:top; padding:0px 2px;
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|'''string'''
+
  |c3=padding:0px 2px;
|style="vertical-align:top; padding-right: 2ex;"|id
+
  |'''string'''|<u>name</u>|This is the name of the cell that is displayed in game messages.
|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'''|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'''|<u>ascii</u>|This should be a single character string. It is used to display cells on the map.
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|'''string'''
+
  |'''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.
|style="vertical-align:top; padding-right: 2ex;"|<span style="text-decoration:underline;">ascii</span>
+
  |'''integer'''|<u>sprite</u>|This indicates the sprite used to represent the cell in the graphical version. Use 0 to indicate no sprite.
|This should be a single character string. It is used to display cells on the map.
+
  |[[Modding:Constants#Colors|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.
|-style="background: #333;"
+
  |[[Modding:Constants#Colors|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.
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|'''string'''
+
  |'''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.
|style="vertical-align:top; padding-right: 2ex;"|asciilow
+
  |'''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 [[Modding:Being#Prototype|generated automatically]], most modders won't need to worry about this. The default is 0.
|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'''|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.
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|'''integer'''
+
  |[[Modding:Constants#Cell Flags|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.
|style="vertical-align:top; padding-right: 2ex;"|<span style="text-decoration:underline;">spirte</span>
+
  |[[Modding:Cell|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.
|This indicates the sprite used to represent the cell in the graphical version. Use 0 to indicate no sprite.
+
  |[[Modding:Cell|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".
|-style="background: #333;"
+
  |[[Modding:Constants#Cellsets|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.
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|[[Modding:Constants#Colors|Color]]
+
  |}}
|style="vertical-align:top; padding-right: 2ex;"|color
+
|This is the color used to draw the cell when it is in the player's line-of-sight. The default is LIGHTGRAY.
+
|-
+
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|[[Modding:Constants#Colors|Color]]
+
|style="vertical-align:top; padding-right: 2ex;"|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.
+
|-style="background: #333;"
+
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|'''string'''
+
|style="vertical-align:top; padding-right: 2ex;"|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.
+
|-
+
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|'''integer'''
+
|style="vertical-align:top; padding-right: 2ex;"|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 [[Modding:Being#Prototype|generated automatically]], most modders won't need to worry about this. The default is 0.
+
|-style="background: #333;"
+
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|'''integer'''
+
|style="vertical-align:top; padding-right: 2ex;"|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.
+
|-
+
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|'''integer'''
+
|style="vertical-align:top; padding-right: 2ex;"|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.
+
|-style="background: #333;"
+
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|[[Modding:Constants#Cell Flags|Cell Flag]] '''list'''
+
|style="vertical-align:top; padding-right: 2ex;"|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.
+
|-
+
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|[[Modding:Cell|Cell ID]]
+
|style="vertical-align:top; padding-right: 2ex;"|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.
+
|-style="background: #333;"
+
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|[[Modding:Cell|Cell ID]]
+
|style="vertical-align:top; padding-right: 2ex;"|destroyto
+
|If the cell is destroyed, it will transmute to the given new cell. This must be a string id. The default is "floor".
+
|-
+
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|[[Modding:Constants#Cellsets|Cellset]]
+
|style="vertical-align:top; padding-right: 2ex;"|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 ==
 
  
 +
== 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.
 
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.
{|style="border: 2px solid darkred; border-spacing: 0; font-size: 90%; margin: 0.25em 0.5em;"
+
 
|colspan=2 style="background: darkred; color: yellow; font-size: 120%; text-align: center"|'''Cell Hooks'''
+
{|class="wikitable" style="border: 2px solid darkred; border-spacing: 0; font-size: 90%; margin: 0.25em 0.5em;"
|-
+
! colspan="2" style="background: darkred; color: yellow; font-size: 120%; text-align: center"|Cell Hooks
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|'''void'''
+
{{Table2Col
|[[#cell_OnEnter|OnEnter]]([[Modding:Coord|Coord]] c, [[Modding:Being|Being]] enterer)  
+
  |es=background: #333;
|-style="background: #333;"
+
  |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px;
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|'''void'''
+
  |c2=padding:0px 2px;
|[[#cell_OnExit|OnExit]]([[Modding:Coord|Coord]] c)  
+
  |'''void'''|[[#cell_OnEnter|OnEnter]]([[Modding:Coord|Coord]] c, [[Modding:Being|Being]] enterer)  
|-
+
  |'''void'''|[[#cell_OnExit|OnExit]]([[Modding:Coord|Coord]] c)  
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|'''void'''
+
  |'''void'''|[[#cell_OnAct|OnAct]]([[Modding:Coord|Coord]] c, [[Modding:Being|Being]] actor)  
|[[#cell_OnAct|OnAct]]([[Modding:Coord|Coord]] c, [[Modding:Being|Being]] actor)  
+
  |'''string'''|[[#cell_OnDescribe|OnDescribe]]([[Modding:Coord|Coord]] c)  
|-style="background: #333;"
+
  |'''void'''|[[#cell_OnDestroy|OnDestroy]]([[Modding:Coord|Coord]] c)
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|'''string'''
+
  |}}
|[[#cell_OnDescribe|OnDescribe]]([[Modding:Coord|Coord]] c)  
+
|-
+
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|'''void'''
+
|[[#cell_OnDestroy|OnDestroy]]([[Modding:Coord|Coord]] c)  
+
 
|}
 
|}
  

Revision as of 20:27, 19 October 2011

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.

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