Difference between revisions of "Modding:generator API"

From DoomRL Wiki

Jump to: navigation, search
(Adding MORE functions. A few fixes. Still under construction)
(Adding the rest of the advanced cell functions, still under construction.)
Line 50: Line 50:
 
   |{{modarg|void}}|{{moddef|list|fill_edges|dot||CellID|what}}
 
   |{{modarg|void}}|{{moddef|list|fill_edges|dot||CellID|what}}
 
   |{{modarg|Table}}|{{moddef|list|each|dot||CellID|what|Area|[where]}}
 
   |{{modarg|Table}}|{{moddef|list|each|dot||CellID|what|Area|[where]}}
 +
  |{{modarg|void}}|{{moddef|list|set_blood|dot||Area|[where]|boolean|[value]|CellID|[what]}}
 +
  |{{modarg|void}}|{{moddef|list|set_permanence|dot||Area|[where]|boolean|[value]|CellID|[what]}}
 +
  |{{modarg|Table}}|{{moddef|list|cell_set|dot||CellSet|cells}}
 +
  |{{modarg|void}}|{{moddef|list|restore_walls|dot||CellID|wallCell|boolean|keepFluids}}
 +
  |{{modarg|void}}|{{moddef|list|plot_line|dot||Coord|where|boolean|horiz|CellID|cell|CellSet|block}}
 +
  |{{modarg|void}}|{{moddef|list|plot_lines|dot||Coord|where|Area|larea|boolean|horiz|CellID|cell|CellSet|block}}
 +
  |{{modarg|void}}|{{moddef|list|scatter|dot||Area|where|CellID|good|CellID|fill|integer|count}}
 +
  |{{modarg|void}}|{{moddef|list|scatter_blood|dot||Area|where|CellID|[good]|integer|count}}
 +
  |{{modarg|void}}|{{moddef|list|scatter_put|dot||Area|where|Table|translation|String|tile|CellID|good|integer|count}}
 +
  |{{modarg|void}}|{{moddef|list|transmute|dot||CellID|to|CellSet|from|Area|[where]}}
 +
  |{{modarg|void}}|{{moddef|list|transmute_marker|dot||Flag|marker|CellID|To|Area|[where]}}
 +
 
 
   |}}
 
   |}}
 
|}
 
|}
Line 196: Line 208:
 
:''where'': ''Optional.'' The area to restrict the search to.
 
:''where'': ''Optional.'' The area to restrict the search to.
 
:'''Returns''': A table containing a list of [[Modding:Coord|Coord]] objects.
 
:'''Returns''': A table containing a list of [[Modding:Coord|Coord]] objects.
 +
----
 +
;{{moddef|desc|set_blood|dot||Area|[where]|boolean|[value]|CellID|[what]}}
 +
Adds blood to the map or removes blood from it.
 +
:''where'': ''Optional.'' The area to affect.  If omitted, the entire map will selected.
 +
:''value'': ''Optional.'' ''True'' adds blood.  ''False'' removes it.  If omitted, the default is to add blood.
 +
:''what'': ''Optional.'' If provided, only locations containing the given cell are affected.  If omitted, all cells in the area are affected.
 +
----
 +
;{{moddef|desc|set_permanence|dot||Area|[where]|boolean|[value]|CellID|[what]}}
 +
Makes cell permanent or removes their permanence.
 +
:''where'': ''Optional.'' The area to affect.  If omitted, the entire map will be selected.
 +
:''value'': ''Optional.'' ''True'' adds permanence.  ''False'' removes it.  If omitted, the default is to add permanence.
 +
:''what'': ''Optional.'' If provided, only locations containing the given cell are affected.  If omitted, wall cells (which includes crate cells) are affected.
 +
----
 +
;{{moddef|desc|cell_set|dot|Table|CellSet|cells}}
 +
Creates a cell group.
 +
:''cells'': A list of cells to add to the group.
 +
:'''Returns''': A cell group table.
 +
----
 +
;{{moddef|desc|restore_walls|dot||CellID|wallCell|boolean|keepFluids}}
 +
Fixes the edge walls of the map.
 +
:''wallCell'': The cell to fill the edge of the map with.
 +
:''keepFluids'': ''True'' to maintain any fluid tiles on the edge of the map.  ''False'' to overwrite them.
 +
----
 +
;{{moddef|desc|plot_line|dot||Coord|where|boolean|horiz|CellID|cell|CellSet|block}}
 +
Splits an area into two at the indicated location.
 +
:''where'': The starting point.
 +
:''horiz'': ''True'' draws along the indicated X position of the ''where'' coordinate.  ''False'' draws along the indicated Y position of the ''where'' coordinate.
 +
:''cell'': The cell that will be used to split the area.
 +
:''block'': The cell(s) that block the line plotting.  The drawn line will stop before hitting a coordinate with one of these cells.
 +
----
 +
;{{moddef|desc|plot_lines|dot||Coord|where|Area|larea|boolean|horiz|CellID|cell|CellSet|block}}
 +
Splits an area into two at the indicated location.
 +
:''where'': The starting point.
 +
:''larea'': The boundaries of the line.  The line will not extend past the edge of the area.
 +
:''horiz'': ''True''draws along the indicated X position of the ''where'' coordinate.  ''False'' draws along the indicated Y position of the ''where'' coordinate.
 +
:''cell'': The cell that will be used to split the area.
 +
:''block'': The cell(s) that block the line plotting.  The drawn line will stop before hitting a coordinate with one of these cells.
 +
----
 +
;{{moddef|desc|scatter|dot||Area|where|CellID|good|CellID|fill|integer|count}}
 +
Randomly places a certain cell around the map.
 +
:''where'': The area to scatter the cell in.
 +
:''good'': Only this locations with this cell will be changed by the function.
 +
:''fill'': The cell to scatter around the area.
 +
:''count'': The number to attempt to place.  If the chosen location is not ''good'', then it will not cha it.  The final number placed may be less than ''count'' (or even 0), but never more.
 +
----
 +
;{{moddef|desc|scatter_blood|dot||Area|where|CellID|[good]|integer|count}}
 +
Randomly adds blood in an area.
 +
:''where'': The area to scatter blood in.
 +
:''good'': ''Optional.'' If defined, only locations with this cell will have blood added.  If omitted, any location my have blood added.
 +
:''count'': The number of attempts.  On each attempt, a random cell in the area will be chosen to have blood added.  The number of cell that will end up bloody may be less than ''count'' (or even 0), but never more.
 +
----
 +
;{{moddef|desc|scatter_put|dot||Area|where|Table|translation|String|tile|CellID|good|integer|count}}
 +
Randomly adds a specified tile (a defined arrangement of cells) around the map.
 +
:''where'': The area to scatter the tile in.  The tiles will only be placed in locations entirely within the area.
 +
:''translation'': A table with to be used with the ''tile'' argument.  Refer to this (will be linked soon) for more information.
 +
:''tile'': A multi-line string, one row of the tile per line, that lays out the arrangment of the cells.  Refer to this (will be linked soon) for more information
 +
:''good'': Only locations with this cell will be valid for the tile placement.  If any coordinates of the selected placement area are not ''good'', the tile will not be placed at that location.
 +
:''count'': The number of tiles to try to place.  The placement will continue until this many have been placed, or 10,000 attempts have been made, whichever comes first.
 +
----
 +
;{{moddef|desc|transmute|dot||CellID|to|CellSet|from|Area|[where]}}
 +
Changes all of one cell on the map to another cell.
 +
:''to'': The cell that will replace the existing cells.
 +
:''from'': The cell(s) that will be replaced.
 +
:''where'': ''Optional.'' If specified, only cells in the area are changed.  If omitted, the function will change cells across the entire map.
 +
----
 +
{{moddef|desc|transmute_marker|dot||Flag|marker|CellID|To|Area|[where]}}
 +
Changes all positions on the map that have a specified LightFlag (a named constant starting with "LF", no underscore) to another cell.
 +
:''marker'': The LightFlag to check for.  Only cells with this flag will be changed.
 +
:''to'': The cell that will replace the existing cells.
 +
:''where'': ''Optional.'' If specified, only cells in the area are changed.  If omitted, the function will change cells across the entire map.
 
----
 
----

Revision as of 07:23, 22 April 2013

This page is currently under construction.

The generator holds all of the ever-present functions used to create the random maps in DoomRL. It also contains a variety of helper functions, many of them useful if not vital to the creation of intricate and meticulous game design.

Contents

API

Please note that the type "integer" indicates an numeric value without a decimal part. It does not indicate the range of acceptable values.

The argument type "CellID" may be the numeric or string ID of a cell.

The argument type "CellSet" may be the numeric ID, string ID, or a list of numeric and/or string IDs.

The argument type "Flags" expects a list of flag constants of the indicated type.

An argument name in [square brackets] is an optional one. The function description will indicate how the function operates if it is omitted.

Generator API Function List

Generator Interface - Functions
Basic Cell Handling Functions
integer generator.get_cell(Coord loc)
string generator.get_cell_id(Coord loc)
integer generator.fast_get_cell(integer x, integer y)
void generator.set_cell(Coord loc, CellID what)
void generator.fast_set_cell(integer x, integer y, integer what)
Map Checking Functions
integer generator.around(Coord where, CellSet what)
integer generator.cross_around(Coord where, CellSet what)
boolean generator.is_empty(Coord where, Flags reqs)
boolean generator.is_empty_area(Area where, Flags reqs)
boolean generator.scan(Area where, CellID good)
Map Searching Functions
Coord generator.drop_coord(Coord where, Flags reqs)
Coord generator.find_coord(CellSet what, Area [where])
Coord generator.random_coord(Area [where])
Coord generator.find_random_coord(CellSet what, Area [where])
Coord generator.find_empty_coord(CellSet what, Flags reqs, Area [where])
Coord generator.random_empty_coord(Flags reqs, Area [where])
Coord generator.find_random_empty_coord(CellSet what, Flags reqs, Area [where])
Coord generator.safe_empty_coord(Area [where])
Coord generator.standard_empty_coord()
Advanced Cell Handling Functions
void generator.fill(CellID what, Area [where])
void generator.fill_pattern(Area where, boolean horiz, Table line1, Table [line2])
void generator.fill_edges(CellID what)
Table generator.each(CellID what, Area [where])
void generator.set_blood(Area [where], boolean [value], CellID [what])
void generator.set_permanence(Area [where], boolean [value], CellID [what])
Table generator.cell_set(CellSet cells)
void generator.restore_walls(CellID wallCell, boolean keepFluids)
void generator.plot_line(Coord where, boolean horiz, CellID cell, CellSet block)
void generator.plot_lines(Coord where, Area larea, boolean horiz, CellID cell, CellSet block)
void generator.scatter(Area where, CellID good, CellID fill, integer count)
void generator.scatter_blood(Area where, CellID [good], integer count)
void generator.scatter_put(Area where, Table translation, String tile, CellID good, integer count)
void generator.transmute(CellID to, CellSet from, Area [where])
void generator.transmute_marker(Flag marker, CellID To, Area [where])


Basic Cell Handling Functions

generator.get_cell(Coord loc) → integer

Gets the Numeric ID (NID) of the cell at a given map position.

loc: The coordinates of the cell to get.
Returns: The NID of the cell.
generator.get_cell_id(Coord loc) → string

Gets the ID of the cell at a given map position.

loc: The coordinates of the cell to get.
Returns: The string ID of the cell.
generator.fast_get_cell(integer x, integer y) → integer

Gets the Numeric ID (NID) of the cell at a given map position.

x: The X position of the cell to get.
y: The Y position of the cell to get.
Returns: The NID of the cell.
generator.set_cell(Coord loc, CellID what)

Assigns a cell to a map position.

loc: The coordinates of the position to set.
what: The ID of the cell to assign to the position.
generator.fast_set_cell(integer x, integer y, integer what)

Assigns a cell to a map position.

x: The X position of the cell to set.
y: The Y position of the cell to set.
what: The NID (string IDs not allowed) of the cell to assign to the position.

Map Checking Functions

generator.around(Coord where, CellSet what) → integer

Checks the positions adjacent to a location (including diagonally adjacent) and returns the number of cells that match one of the indicated cell IDs.

where: The coordinate to check around. The coordinate sent in this way is not checked, only adjacent cells are.
what: The cell(s) to check for.
Returns: The number of cells (from 0 to 8) that matched one of the what cell IDs.
generator.cross_around(Coord where, CellSet what) → integer

Checks the positions adjacent to a location (but not diagonally adjacent) and returns the number of cells that match one of the indicated cell IDs.

where: The coordinates to check around. The coordinate sent in this way is not checked, only adjacent cells are.
what: The cell(s) to check for.
Returns: The number of cells (from 0 to 4) that matched one of the what cell IDs.
generator.is_empty(Coord where, Flags reqs) → boolean

Checks to see if the indicated cell is "empty", defining "empty" based on a list of criteria.

where: The position to check.
reqs: A list of EmptyFlags (named numeric constants that start with EF_) indicating which types of objects or properties the position cannot have. For example, if the flag EF_NOBEINGS is sent, the function only returns true if the map position does not contain a being. See Modding:Constants#Empty_Flags for more information.
Returns: True if the cell satisfies all of the conditions indicated in reqs, False otherwise.
generator.is_empty_area(Area where, Flags reqs) → boolean

Checks to see if the indicated area is "empty", defining "empty" based on a list of criteria.

where: The area to check.
reqs: A list of EmptyFlags (named numeric constants that start with EF_) indicating which types of objects or properties the area cannot have. For example, if the flag EF_NOBEINGS is sent, the function only returns true if the area does not contain a being. See Modding:Constants#Empty_Flags for more information.
Returns: True if every cell in the area satisfies all of the conditions indicated in reqs, False otherwise.
generator.scan(Area where, CellID good) → boolean

Checks to see if the entire area is filled with a certain cell.

where: The area to check.
good: The cell to look for.
Returns: True if all cells in the area are good, False otherwise.

Map Searching Functions

generator.drop_coord(Coord where, Flags reqs) → Coord

Finds the nearest "empty" coordinate to a given coordinate, defining "empty" based on a list of criteria.

where: The coordinate to try. If this coordinate is "empty", this coordinate will be returned.
reqs: A list of EmptyFlags (named numeric constants that start with EF_) indicating which types of objects or properties the coordinate cannot have. For example, if the flag EF_NOBEINGS is sent, the function only returns a coordinate that does not contain a being. See Modding:Constants#Empty_Flags for more information.
Returns: The nearest coordinate the satisfies the criteria. If the supplied coordinate meets the criteria, that coordinate will be returned. If not a nearby, random, coordinate will be checked.
generator.find_coord(CellSet what, Area [where]) → Coord

Searches the map for the first coordinate containing one of the indicated cell IDs.

what: The cell(s) to search for.
where: Optional. The area to restrict the search to. If omitted, the coordinate can be picked from anywhere on the map.
Returns: The coordinates of the first position that contains one of the what cell IDs. The map is checked row by row starting from the top, going from left to right across each row.
generator.random_coord(Area [where]) → Coord

Searches for a random coordinate within the specified area.

where: Optional. The area to restrict the coordinate to. If omitted, the coordinate can be picked from anywhere on the map.
Returns: A random coordinate.
generator.find_random_coord(CellSet what, Area [where]) → Coord

Searches for a random coordinate within the specified area that contains one of the specified cell IDs.

what: The cell(s) to search for.
where : Optional. The area to restrict the search to. If omitted, the coordinate can be picked from anywhere on the map.
Returns: A random coordinate that meets the supplied criteria.
generator.find_empty_coord(CellSet what, Flags reqs, Area [where]) → Coord

Searches the map for the first "empty" coordinate containing one of the indicated cell IDs, defining "empty" based on a list of criteria.

what: The cell(s) to search for.
reqs: A list of EmptyFlags (named numeric constants that start with EF_) indicating which types of objects or properties the coordinate cannot have. For example, if the flag EF_NOBEINGS is sent, the function only returns a coordinate that does not contain a being. See Modding:Constants#Empty_Flags for more information.
where: Optional. The area to restrict the search to. If omitted, the coordinate can be picked from anywhere on the map.
Returns: The coordinates of the first position that meets the supplied criteria. The map is checked row by row starting from the top, going from left to right across each row.
generator.random_empty_coord(Flags reqs, Area [where]) → Coord

Searches the map for a random coordinate that is "empty", defining "empty" based on a list of criteria.

reqs: A list of EmptyFlags (named numeric constants that start with EF_) indicating which types of objects or properties the random coordinate cannot have. For example, if the flag EF_NOBEINGS is sent, the function only returns a coordinate that does not contain a being. See Modding:Constants#Empty_Flags for more information.
where: Optional. The area to restrict the search to. If omitted, the coordinate can be picked from anywhere on the map.
Returns: A random coordinate that meets the supplied criteria.
generator.find_random_empty_coord(CellSet what, Flags reqs, Area [where]) → Coord

Searches the map for a random "empty" coordinate containing one of the indicated cell IDs, defining "empty" based on a list of criteria.

what: The cell(s) to search for.
reqs: A list of EmptyFlags (named numeric constants that start with EF_) indicating which types of objects or properties the random coordinate cannot have. For example, if the flag EF_NOBEINGS is sent, the function only returns a coordinate that does not contain a being. See Modding:Constants#Empty_Flags for more information.
where: Optional. The area to restrict the search to. If omitted, the coordinate can be picked from anywhere on the map.
Returns: A random coordinate that meets the supplied criteria.
generator.random_square(CellSet what) → Coord

Searches for a random 3x3 area containing only specified cells.

what: The cell(s) to search for.
Returns: The center coordinate of the random 3x3 area.
generator.safe_empty_coord(Area [where]) → Coord

Searches for a random coordinate that meets certain predetermined criteria.

The function will try to find a coordinate that does not contain a being, item, staircase, wall, harmful terrain, spawning restrictions (cells marked with LF_NOSPAWN), and is more than 5 spaces from the player (EF_NOBEINGS, EF_NOITEMS, EF_NOSTAIRS, EF_NOBLOCK, EF_NOHARM, EF_NOSPAWN, and EF_NOSAFE). If a valid space isn't found, the function will ignore distance from the player (EF_NOSAFE). If a valid space still can't be found, the function will ignore stairs and harmful terrain (EF_NOSTAIRS and EF_NOHARM).

where: Optional. The area to restrict the initial pass to. If a valid coordinate is not found within the area after ignoring stairs and harmful terrain, the search is restarted and expanded automatically to the entire map. If omitted, the entire map will be searched.
Returns: A random coordinate that meets the criteria.
generator.standard_empty_coord() → Coord

Searches for a random coordinate that meets certain predetermined criteria.

The function will search for a coordinate that does not contain a being, item, staircase, wall, harmful terrain, or spawning restrictions (EF_NOBEINGS, EF_NOITEMS, EF_NOSTAIRS, EF_NOBLOCK, EF_NOHARM, and EF_NOSPAWN).

Returns: A random coordinate that meets the criteria.

Advanced Cell Handling Functions

generator.fill(CellID what, Area [where])

Fills an area of the map with a given cell.

what: The cell to fill with.
where: Optional. The area to fill with the cell. If omitted, the entire map will be filled.
generator.fill_pattern(Area where, boolean horiz, string Table, line1 Table, )

Fills an area of the map with a pattern of cells.

where: The area to fill.
horiz: If True, the pattern will fill each row left to right, then move to the next row down in the area. If False, the pattern will fill each column top to bottom, then move to the next column right in the area.
line1: The pattern to fill with. If the pattern is shorter than the area size, the pattern will loop. The pattern does not restart at the end of a row or column.
line2: Optional. If given, each time the end of row (if horiz is True) or column (if horiz is False) is reached, the function will switch to filling with the other pattern. That is, the first row will use line1 then the second will use line2, then the third will use line1 again, etc.
generator.fill_edges(CellID what)

Fills the edges of the map with the given cell.

what: The cell to fill with.
generator.each(CellID what, Area [where]) → Table

Searches for a cell and returns a table containing every location it was found.

what: The cell to search for.
where: Optional. The area to restrict the search to.
Returns: A table containing a list of Coord objects.
generator.set_blood(Area [where], boolean [value], CellID [what])

Adds blood to the map or removes blood from it.

where: Optional. The area to affect. If omitted, the entire map will selected.
value: Optional. True adds blood. False removes it. If omitted, the default is to add blood.
what: Optional. If provided, only locations containing the given cell are affected. If omitted, all cells in the area are affected.
generator.set_permanence(Area [where], boolean [value], CellID [what])

Makes cell permanent or removes their permanence.

where: Optional. The area to affect. If omitted, the entire map will be selected.
value: Optional. True adds permanence. False removes it. If omitted, the default is to add permanence.
what: Optional. If provided, only locations containing the given cell are affected. If omitted, wall cells (which includes crate cells) are affected.
generator.cell_set(CellSet cells) → Table

Creates a cell group.

cells: A list of cells to add to the group.
Returns: A cell group table.
generator.restore_walls(CellID wallCell, boolean keepFluids)

Fixes the edge walls of the map.

wallCell: The cell to fill the edge of the map with.
keepFluids: True to maintain any fluid tiles on the edge of the map. False to overwrite them.
generator.plot_line(Coord where, boolean horiz, CellID cell, CellSet block)

Splits an area into two at the indicated location.

where: The starting point.
horiz: True draws along the indicated X position of the where coordinate. False draws along the indicated Y position of the where coordinate.
cell: The cell that will be used to split the area.
block: The cell(s) that block the line plotting. The drawn line will stop before hitting a coordinate with one of these cells.
generator.plot_lines(Coord where, Area larea, boolean horiz, CellID cell, CellSet block)

Splits an area into two at the indicated location.

where: The starting point.
larea: The boundaries of the line. The line will not extend past the edge of the area.
horiz: Truedraws along the indicated X position of the where coordinate. False draws along the indicated Y position of the where coordinate.
cell: The cell that will be used to split the area.
block: The cell(s) that block the line plotting. The drawn line will stop before hitting a coordinate with one of these cells.
generator.scatter(Area where, CellID good, CellID fill, integer count)

Randomly places a certain cell around the map.

where: The area to scatter the cell in.
good: Only this locations with this cell will be changed by the function.
fill: The cell to scatter around the area.
count: The number to attempt to place. If the chosen location is not good, then it will not cha it. The final number placed may be less than count (or even 0), but never more.
generator.scatter_blood(Area where, CellID [good], integer count)

Randomly adds blood in an area.

where: The area to scatter blood in.
good: Optional. If defined, only locations with this cell will have blood added. If omitted, any location my have blood added.
count: The number of attempts. On each attempt, a random cell in the area will be chosen to have blood added. The number of cell that will end up bloody may be less than count (or even 0), but never more.
generator.scatter_put(Area where, Table translation, String tile, CellID good, integer count)

Randomly adds a specified tile (a defined arrangement of cells) around the map.

where: The area to scatter the tile in. The tiles will only be placed in locations entirely within the area.
translation: A table with to be used with the tile argument. Refer to this (will be linked soon) for more information.
tile: A multi-line string, one row of the tile per line, that lays out the arrangment of the cells. Refer to this (will be linked soon) for more information
good: Only locations with this cell will be valid for the tile placement. If any coordinates of the selected placement area are not good, the tile will not be placed at that location.
count: The number of tiles to try to place. The placement will continue until this many have been placed, or 10,000 attempts have been made, whichever comes first.
generator.transmute(CellID to, CellSet from, Area [where])

Changes all of one cell on the map to another cell.

to: The cell that will replace the existing cells.
from: The cell(s) that will be replaced.
where: Optional. If specified, only cells in the area are changed. If omitted, the function will change cells across the entire map.

generator.transmute_marker(Flag marker, CellID To, Area [where])

Changes all positions on the map that have a specified LightFlag (a named constant starting with "LF", no underscore) to another cell.

marker: The LightFlag to check for. Only cells with this flag will be changed.
to: The cell that will replace the existing cells.
where: Optional. If specified, only cells in the area are changed. If omitted, the function will change cells across the entire map.
Retrieved from "https://drl.chaosforge.org/w/index.php?title=Modding:generator_API&oldid=2516"
Personal tools