Difference between revisions of "Modding:generator API"
From DoomRL Wiki
Shark20061 (Talk | contribs) (Adding more functions. Still under construction.) |
Shark20061 (Talk | contribs) (Adding MORE functions. A few fixes. Still under construction) |
||
| Line 33: | Line 33: | ||
|{{modarg|integer}}|{{moddef|list|cross_around|dot||Coord|where|CellSet|what}} | |{{modarg|integer}}|{{moddef|list|cross_around|dot||Coord|where|CellSet|what}} | ||
|{{modarg|boolean}}|{{moddef|list|is_empty|dot||Coord|where|Flags|reqs}} | |{{modarg|boolean}}|{{moddef|list|is_empty|dot||Coord|where|Flags|reqs}} | ||
| − | |{{modarg|boolean}}|{{moddef|list|is_empty_area|dot||Area|where|Flags|reqs}} | + | |{{modarg|boolean}}|{{moddef|list|is_empty_area|dot||Area|where|Flags|reqs}} |
|{{modarg|boolean}}|{{moddef|list|scan|dot||Area|where|CellID|good}} | |{{modarg|boolean}}|{{moddef|list|scan|dot||Area|where|CellID|good}} | ||
||'''[[#Map Searching Functions|Map Searching Functions]]''' | ||'''[[#Map Searching Functions|Map Searching Functions]]''' | ||
| + | |{{modarg|Coord}}|{{moddef|list|drop_coord|dot||Coord|where|Flags|reqs}} | ||
|{{modarg|Coord}}|{{moddef|list|find_coord|dot||CellSet|what|Area|[where]}} | |{{modarg|Coord}}|{{moddef|list|find_coord|dot||CellSet|what|Area|[where]}} | ||
|{{modarg|Coord}}|{{moddef|list|random_coord|dot||Area|[where]}} | |{{modarg|Coord}}|{{moddef|list|random_coord|dot||Area|[where]}} | ||
| Line 44: | Line 45: | ||
|{{modarg|Coord}}|{{moddef|list|safe_empty_coord|dot||Area|[where]}} | |{{modarg|Coord}}|{{moddef|list|safe_empty_coord|dot||Area|[where]}} | ||
|{{modarg|Coord}}|{{moddef|list|standard_empty_coord|dot}} | |{{modarg|Coord}}|{{moddef|list|standard_empty_coord|dot}} | ||
| + | ||'''[[#Advanced Cell Handling Functions|Advanced Cell Handling Functions]]''' | ||
| + | |{{modarg|void}}|{{moddef|list|fill|dot||CellID|what|Area|[where]}} | ||
| + | |{{modarg|void}}|{{moddef|list|fill_pattern|dot||Area|where|boolean|horiz|Table|line1|Table|[line2]}} | ||
| + | |{{modarg|void}}|{{moddef|list|fill_edges|dot||CellID|what}} | ||
| + | |{{modarg|Table}}|{{moddef|list|each|dot||CellID|what|Area|[where]}} | ||
|}} | |}} | ||
|} | |} | ||
=== Basic Cell Handling Functions === | === Basic Cell Handling Functions === | ||
| − | ;{{moddef|desc|get_cell|dot||Coord|loc}} | + | ;{{moddef|desc|get_cell|dot|integer|Coord|loc}} |
Gets the Numeric ID (NID) of the [[Modding:Cell|cell]] at a given map position. | Gets the Numeric ID (NID) of the [[Modding:Cell|cell]] at a given map position. | ||
:''loc'': The coordinates of the cell to get. | :''loc'': The coordinates of the cell to get. | ||
:'''Returns''': The NID of the cell. | :'''Returns''': The NID of the cell. | ||
---- | ---- | ||
| − | ;{{moddef|desc|get_cell_id|dot||Coord|loc}} | + | ;{{moddef|desc|get_cell_id|dot|string|Coord|loc}} |
Gets the ID of the [[Modding:Cell|cell]] at a given map position. | Gets the ID of the [[Modding:Cell|cell]] at a given map position. | ||
:''loc'': The coordinates of the cell to get. | :''loc'': The coordinates of the cell to get. | ||
:'''Returns''': The string ID of the cell. | :'''Returns''': The string ID of the cell. | ||
---- | ---- | ||
| − | ;{{moddef|desc|fast_get_cell|dot||integer|x|integer|y}} | + | ;{{moddef|desc|fast_get_cell|dot|integer|integer|x|integer|y}} |
Gets the Numeric ID (NID) of the [[Modding:Cell|cell]] at a given map position. | Gets the Numeric ID (NID) of the [[Modding:Cell|cell]] at a given map position. | ||
:''x'': The X position of the cell to get. | :''x'': The X position of the cell to get. | ||
| Line 65: | Line 71: | ||
---- | ---- | ||
;{{moddef|desc|set_cell|dot||Coord|loc|CellID|what}} | ;{{moddef|desc|set_cell|dot||Coord|loc|CellID|what}} | ||
| − | Assigns a | + | Assigns a [[Modding:Cell|cell]] to a map position. |
:''loc'': The coordinates of the position to set. | :''loc'': The coordinates of the position to set. | ||
:''what'': The ID of the cell to assign to the position. | :''what'': The ID of the cell to assign to the position. | ||
---- | ---- | ||
;{{moddef|desc|fast_set_cell|dot||integer|x|integer|y|integer|what}} | ;{{moddef|desc|fast_set_cell|dot||integer|x|integer|y|integer|what}} | ||
| − | Assigns a | + | Assigns a [[Modding:Cell|cell]] to a map position. |
:''x'': The X position of the cell to set. | :''x'': The X position of the cell to set. | ||
:''y'': The Y 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. | :''what'': The NID (string IDs not allowed) of the cell to assign to the position. | ||
| + | ---- | ||
=== Map Checking Functions === | === Map Checking Functions === | ||
| − | ;{{moddef|desc|around|dot||Coord|where|CellSet|what}} | + | ;{{moddef|desc|around|dot|integer|Coord|where|CellSet|what}} |
Checks the positions adjacent to a location (including diagonally adjacent) and returns the number of cells that match one of the indicated cell IDs. | 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. | :''where'': The coordinate to check around. The coordinate sent in this way is not checked, only adjacent cells are. | ||
| Line 81: | Line 88: | ||
:'''Returns''': The number of cells (from 0 to 8) that matched one of the ''what'' cell IDs. | :'''Returns''': The number of cells (from 0 to 8) that matched one of the ''what'' cell IDs. | ||
---- | ---- | ||
| − | ;{{moddef|desc|cross_around|dot||Coord|where|CellSet|what}} | + | ;{{moddef|desc|cross_around|dot|integer|Coord|where|CellSet|what}} |
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. | 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. | :''where'': The coordinates to check around. The coordinate sent in this way is not checked, only adjacent cells are. | ||
| Line 87: | Line 94: | ||
:'''Returns''': The number of cells (from 0 to 4) that matched one of the ''what'' cell IDs. | :'''Returns''': The number of cells (from 0 to 4) that matched one of the ''what'' cell IDs. | ||
---- | ---- | ||
| − | ;{{moddef|desc|is_empty|dot||Coord|where|Flags|reqs}} | + | ;{{moddef|desc|is_empty|dot|boolean|Coord|where|Flags|reqs}} |
Checks to see if the indicated cell is "empty", defining "empty" based on a list of criteria. | Checks to see if the indicated cell is "empty", defining "empty" based on a list of criteria. | ||
:''where'': The position to check. | :''where'': The position to check. | ||
| Line 93: | Line 100: | ||
:'''Returns''': ''True'' if the cell satisfies all of the conditions indicated in ''reqs'', ''False'' otherwise. | :'''Returns''': ''True'' if the cell satisfies all of the conditions indicated in ''reqs'', ''False'' otherwise. | ||
---- | ---- | ||
| − | ;{{moddef|desc|is_empty_area|dot||Area|where|Flags|reqs}} | + | ;{{moddef|desc|is_empty_area|dot|boolean|Area|where|Flags|reqs}} |
Checks to see if the indicated area is "empty", defining "empty" based on a list of criteria. | Checks to see if the indicated area is "empty", defining "empty" based on a list of criteria. | ||
:''where'': The area to check. | :''where'': The area to check. | ||
| Line 99: | Line 106: | ||
:'''Returns''': ''True'' if every cell in the area satisfies all of the conditions indicated in ''reqs'', ''False'' otherwise. | :'''Returns''': ''True'' if every cell in the area satisfies all of the conditions indicated in ''reqs'', ''False'' otherwise. | ||
---- | ---- | ||
| − | ;{{moddef|desc|scan|dot||Area|where|CellID|good}} | + | ;{{moddef|desc|scan|dot|boolean|Area|where|CellID|good}} |
Checks to see if the entire area is filled with a certain cell. | Checks to see if the entire area is filled with a certain cell. | ||
:''where'': The area to check. | :''where'': The area to check. | ||
:''good'': The cell to look for. | :''good'': The cell to look for. | ||
:'''Returns''': ''True'' if all cells in the area are ''good'', ''False'' otherwise. | :'''Returns''': ''True'' if all cells in the area are ''good'', ''False'' otherwise. | ||
| + | ---- | ||
=== Map Searching Functions === | === Map Searching Functions === | ||
| − | ;{{moddef|desc|find_coord|dot||CellSet|what|Area|[where]}} | + | ;{{moddef|desc|drop_coord|dot|Coord|Coord|where|Flags|reqs}} |
| + | 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 [[Modding:Being|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. | ||
| + | ---- | ||
| + | ;{{moddef|desc|find_coord|dot|Coord|CellSet|what|Area|[where]}} | ||
Searches the map for the first coordinate containing one of the indicated cell IDs. | Searches the map for the first coordinate containing one of the indicated cell IDs. | ||
:''what'': The cell(s) to search for. | :''what'': The cell(s) to search for. | ||
| Line 111: | Line 125: | ||
:'''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. | :'''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. | ||
---- | ---- | ||
| − | ;{{moddef|desc|random_coord|dot||Area|[where]}} | + | ;{{moddef|desc|random_coord|dot|Coord|Area|[where]}} |
Searches for a random coordinate within the specified area. | 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. | :''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. | :'''Returns''': A random coordinate. | ||
---- | ---- | ||
| − | ;{{moddef|desc|find_random_coord|dot||CellSet|what|Area|[where]}} | + | ;{{moddef|desc|find_random_coord|dot|Coord|CellSet|what|Area|[where]}} |
Searches for a random coordinate within the specified area that contains one of the specified cell IDs. | Searches for a random coordinate within the specified area that contains one of the specified cell IDs. | ||
:''what'': The cell(s) to search for. | :''what'': The cell(s) to search for. | ||
| Line 122: | Line 136: | ||
:'''Returns''': A random coordinate that meets the supplied criteria. | :'''Returns''': A random coordinate that meets the supplied criteria. | ||
---- | ---- | ||
| − | ;{{moddef|desc|find_empty_coord|dot||CellSet|what|Flags|reqs|Area|[where]}} | + | ;{{moddef|desc|find_empty_coord|dot|Coord|CellSet|what|Flags|reqs|Area|[where]}} |
Searches the map for the first "empty" coordinate containing one of the indicated cell IDs, defining "empty" based on a list of criteria. | 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. | :''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 | + | :''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 [[Modding:Being|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. | :''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. | :'''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. | ||
---- | ---- | ||
| − | ;{{moddef|desc|random_empty_coord|dot||Flags|reqs|Area|[where]}} | + | ;{{moddef|desc|random_empty_coord|dot|Coord|Flags|reqs|Area|[where]}} |
Searches the map for a random coordinate that is "empty", defining "empty" based on a list of criteria. | 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 | + | :''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 [[Modding:Being|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. | :''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. | :'''Returns''': A random coordinate that meets the supplied criteria. | ||
---- | ---- | ||
| − | ;{{moddef|desc|find_random_empty_coord|dot||CellSet|what|Flags|reqs|Area|[where]}} | + | ;{{moddef|desc|find_random_empty_coord|dot|Coord|CellSet|what|Flags|reqs|Area|[where]}} |
Searches the map for a random "empty" coordinate containing one of the indicated cell IDs, defining "empty" based on a list of criteria. | 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. | :''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 | + | :''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 [[Modding:Being|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. | :''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. | :'''Returns''': A random coordinate that meets the supplied criteria. | ||
---- | ---- | ||
| − | ;{{moddef|desc|random_square|dot||CellSet|what}} | + | ;{{moddef|desc|random_square|dot|Coord|CellSet|what}} |
Searches for a random 3x3 area containing only specified cells. | Searches for a random 3x3 area containing only specified cells. | ||
:''what'': The cell(s) to search for. | :''what'': The cell(s) to search for. | ||
:'''Returns''': The center coordinate of the random 3x3 area. | :'''Returns''': The center coordinate of the random 3x3 area. | ||
---- | ---- | ||
| − | ;{{moddef|desc|safe_empty_coord|dot||Area|[where]}} | + | ;{{moddef|desc|safe_empty_coord|dot|Coord|Area|[where]}} |
Searches for a random coordinate that meets certain predetermined criteria. | 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). | 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 | + | :''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. | :'''Returns''': A random coordinate that meets the criteria. | ||
---- | ---- | ||
| − | ;{{moddef|desc|standard_empty_coord|dot}} | + | ;{{moddef|desc|standard_empty_coord|dot|Coord}} |
Searches for a random coordinate that meets certain predetermined criteria. | 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). | 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. | :'''Returns''': A random coordinate that meets the criteria. | ||
| + | ---- | ||
| + | === Advanced Cell Handling Functions === | ||
| + | ;{{moddef|desc|fill|dot||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. | ||
| + | ---- | ||
| + | ;{{moddef|desc|fill_pattern|dot||Area|where|boolean|horiz|string|Table|line1|Table|[line2]}} | ||
| + | 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. | ||
| + | ---- | ||
| + | ;{{moddef|desc|fill_edges|dot||CellID|what}} | ||
| + | Fills the edges of the map with the given cell. | ||
| + | :''what'': The cell to fill with. | ||
| + | ---- | ||
| + | ;{{moddef|desc|each|dot|Table|CellID|what|Area|[where]}} | ||
| + | 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 [[Modding:Coord|Coord]] objects. | ||
---- | ---- | ||
Revision as of 02:37, 21 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]) |
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.
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
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
