Difference between revisions of "Modding:generator API (0.9.9.7)"

Latest revision as of 04:02, 10 June 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.

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])
	Tile Handling Functions
Table	generator.create_translation(Table code)
Tile	generator.tile_new(string map, Table translation)
void	generator.tile_place(Coord where, Tile what)
void	generator.place_tile(Table translation, string tile, integer x, integer y)
void	generator.place_dungen_tile(Table code, Tile tile, Coord where)
void	generator.place_symmetry_quad(string tile, Table translation)
void	generator.place_proto_map(Coord where, string proto_map, string proto_key, Table code)
	Room Handling Functions
void	generator.add_room(Area room, string [class])
void	generator.add_rooms()
Room	generator.get_room(integer min_size, integer max_x, integer max_y, integer max_area, string [class])
integer, integer	generator.get_endpoints(Coord where, boolean horiz, CellSet what)
void	generator.handle_rooms(integer count, boolean no_monsters)
	Generation Algorithm Functions
void	generator.run_drunkard_walk(Area where, Coord start, integer steps, CellID fill, CellSet [ignore], boolean [stop_at_edge])
void	generator.drunkard_walks(integer amount, integer steps, CellID fill, CellSet [ignore], boolean [stop_at_edge], Area [where])
void	generator.contd_drunkard_walks(integer amount, integer steps, CellID fill, CellSet edges1, CellSet edges2, CellSet [ignore], boolean [stop_at_edge])
void	generator.warehouse_fill(CellSet fill, Area where, integer size, integer count, integer special_chance, CellSet special)
void	generator.place_blob(Coord start, integer size, CellID cell)
	Generator Helper Functions
<value>, <value>	generator.roll_pair(Table list)
integer	generator.being_weight()
integer	generator.item_amount()
void	generator.horiz_river(CellID cell, integer width, boolean [bridge])
void	generator.vert_river(CellID cell, integer width, boolean bridge, integer position) generator.vert_river(CellID cell, integer width, boolean bridge, Coord position)
void	generator.generate_rivers(boolean allow_horiz, boolean allow_more)
void	generator.generate_fluids(Area [where])
void	generator.generate_barrels()
void	generator.generate_stairs()
void	generator.generate_special_stairs()
void	generator.place_player()
void	generator.run(Generator gen)
void	generator.reset()
	Dungeon Generation Functions
void	generator.generate_tiled()
void	generator.maze_dungeon(CellID floor, CellID wall, integer granularity, integer tries, integer min_size, integer max_size)
void	generator.generate_caves_dungeon()
void	generator.generate_caves_2_dungeon()
void	generator.generate_lava_dungeon()
	Event Handler Functions
void	generator.roll_event()
void	generator.setup_flood_event(integer direction, integer step, CellID cell)
void	generator.setup_deadly_air_event(integer step)
void	generator.setup_explosion_event(integer step, integer size, integer dice, integer [content]) generator.setup_explosion_event(integer step, Table size, integer dice, integer [content])
void	generator.setup_targeted_event(integer step)

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: 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.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 change 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.

Tile Handling Functions


generator.create_translation(Table code) → Table

Parses a translation table. Refer to this (will be linked soon) for more information.

code: The translation table.

Returns: A parsed translation table.


generator.tile_new(string map, Table translation) → Tile

Creates a new tile object.

map: A multi-line string containing the arrangement of the tile using the translation to convert the characters to cells. Refer to this (will be linked soon) for more information.

translation: A table with to be used with the map argument. Refer to this (will be linked soon) for more information.

Returns: The new tile object.


generator.tile_place(Coord where, Tile what)

Places the cells of the tile on the map.

where: The coordinate that the upper-left of the tile should reside at.

what: The tile object that will be placed.


generator.place_tile(Table translation, string tile, integer x, integer y)

Combines the tile_new and tile_place functions together, by placing a tile using a string and translation table.

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 containing the arrangement of the tile using the translation to convert the characters to cells. Refer to this (will be linked soon) for more information.

x: The X position that the tile will be placed at.

y: The Y position that the tile will be placed at.


generator.place_dungen_tile(Table code, Tile tile, Coord where)

Places an entire tile, including beings and items in the translation, on the map.

code: The translation table. Refer to this (will be linked soon) for more information.

tile: A multi-line string containing the arrangement of the tile using the translation to convert the characters to cells and indicate the positions of the beings and items. Refer to this (will be linked soon) for more information.

where: The coordinate the tile will be placed at.


generator.place_symmetry_quad(string tile, Table translation)

Takes a tile object and places it in all four corners. The tile object should be setup for the upper left corner and will be mirrored to the other corners. The tiles are placed one space from the map edge.

tile: A multi-line string containing the arrangement of the tile using the translation to convert the characters to cells and indicate the positions of the beings and items. Refer to this (will be linked soon) for more information.

translation: The translation table. Refer to this (will be linked soon) for more information.


generator.place_proto_map(Coord where, string proto_map, string proto_key, Table code)

Creates a map using multiple tile sets.

where: The upper-left position of the map where the tiles will be layout from.

proto_map: A string indicating the arrangement of the different pieces of the map. e.g., "ABCD", will lay out 4 different tiles with A on the far left and D on the far right.

proto_key: A table containing, for each character in proto_map, a table of the possible tiles for that section.

code: The translation table for all the tile possibilities. Refer to this (will be linked soon) for more information. All tiles use the same translation table.

Room Handling Functions


generator.add_room(Area room, string [class])

Marks an area that can become a special room.

room: The area of the room. This includes the walls.

class: Optional. A string used to denote which room generators can be used on this room. If omitted, the class used is "closed".


generator.add_rooms()

Finds all the areas that can be rooms on a map and adds them to the appropriate meta-map tables.


generator.get_room(integer min_size, integer max_x, integer max_y, integer max_area, string class) → Room

Selects a room given certain criteria.

min_size: The smallest X and Y dimensions the room can be.

max_x: The maximum width of the room.

max_y: The maximum height of the room.

max_area: The largest area the room can be.

class: Optional. The string denoting which room classes are valid for this room generator. If omitted, "any" is used, which does not restrict the selection of rooms.


generator.get_endpoints(Coord where, boolean horiz, CellSet what) → integer, integer

Finds the ends of a line of cells.

where: The starting coordinate.

horiz: True checks horizontally. False checks vertically.

what: The cell(s) that make up the line to check. The functions stops at the first cell not in this list.

Returns: Two integers. If horiz is True, these are the X positions the line stops at. If horiz is False, these are the Y positions the line stops at.


generator.handle_rooms(integer count, boolean no_monsters)

Runs the rooms selection and setup process for a map.

count: The number of rooms to attempt to place.

no_monsters: True will exclude room generators that place monsters. False will not.

Generation Algorithm Functions


generator.run_drunkard_walk(Area where, Coord start, integer steps, CellID fill, CellSet [ignore], boolean [stop_at_edge], Area where)

Runs an algorithm that walks to random adjacent spaces.

where: The area that the algorithm will run in. If the algorithm tries to leave the area, it will stop early or will be pushed back in the area (stop_at_edge will determine which of these happen).

start: The location the algorithm will begin at.

steps: The number of steps the algorithm will take. The number of spaces covered by the algorithm will be at most this number.

fill: The cell that will be placed at each location the algorithm hits.

ignore: Optional. If specified, the algorithm will not place the fill cell in any location that has one of the cell(s) specified. If omitted, no locations are ignored.

stop_at_edge: Optional. If True, the algorithm will end early if it moves past the end of the area. If False, the algorithm will clamp to the area (any moves to outside the area get moved back in the area). If omitted, the default is to clamp.


generator.drunkard_walks(integer amount, integer steps, CellID fill, CellSet [ignore], boolean [stop_at_edge], Area [where])

Runs multiple "drunken walk" algorithms.

amount: The number of times to perform the algorithm.

steps: The number of steps each run of the algorithm will take. The number of spaces covered by the algorithm will be at most the amount times the number of steps.

fill: The cell that will be placed at each location the algorithm hits.

ignore: Optional. If specified, the algorithm will not place the fill cell in any location that has one of the cell(s) specified. If omitted, no locations are ignored.

stop_at_edge: Optional. If True, the algorithm will end early if it moves past the end of the area. If False, the algorithm will clamp to the area (any moves to outside the area get moved back in the area). If omitted, the default is to clamp.

where: Optional. The area the algorithm will run in. If the algorithm tries to leave the area, it will stop early or will be pushed back in the area (stop_at_edge will determine which of these happen). If omitted, the default is entire area minus the very edge.


generator.contd_drunkard_walks(integer amount, integer steps, CellID fill, CellSet edges1, CellSet edges2, CellSet [ignore], boolean [stop_at_edge])

Runs multiple "drunken walk" algorithms starting at a space that doesn't have certain cells around it.

amount: The number of times to perform the algorithm.

steps: The number of steps each run of the algorithm will take. The number of spaces covered by the algorithm will be at most the amount times the number of steps.

fill: The cell that will be placed at each location the algorithm hits.

edges1: The algorithm will not start on a space with a cell listed here next to it.

edges2: The algorithm will not start on a space with a cell listed here next to it.

ignore: Optional. If specified, the algorithm will not place the fill cell in any location that has one of the cell(s) specified. If omitted, no locations are ignored.

stop_at_edge: Optional. If True, the algorithm will end early if it moves past the end of the area. If False, the algorithm will clamp to the area (any moves to outside the area get moved back in the area). If omitted, the default is to clamp.


generator.warehouse_fill(CellID fill, Area where, integer [size], integer [count], integer [special_chance], CellID [special])

Fills an area with random squares of cells.

fill: The cell(s) to use for each square. If a list is given, one is chosen at random for each square.

where: The area to fill.

size: Optional. The size of the squares to use. If omitted, the default is 2.

count: Optional. The number of attempts. If omitted, the default is 50.

special_chance: Optional. A number indicating the probability of using a special list of cells to fill the square with instead of the fill list. The roll used for the chance is based on the size parameter. A number from 1 to (100 * size) is chosen for each square and if the roll is less than the special_chance number, the special cell set is used to fill the square instead. If omitted, all squares will be filled from the fill set.

special: Optional. The list of cells to use if the special set is to be used, based on special_chance. If omitted, all squares will be filled from the fill set.


generator.place_blob(Coord start, integer size, CellID cell)

Fills an area by expanding to random edge coordinates.

start: The position to start the blob at.

size: The number of spaces to expand the blob to.

cell: The cell to fill the blob area with.

Generator Helper Functions


generator.roll_pair(Table list) → <value>, <value>

Takes a list of values of any type and returns two different values randomly from the list.

list: The list to choose from.

Returns: Two different values. If the list only contains one choice, it will be returned, but only once.


generator.being_weight()

Gets the total danger level for the current dungeon level. Returns: The danger level for the current dungeon level. This value is calcuated using the current difficulty and level.danger_level.


generator.item_amount()

Gets the number of items to drop for the current dungeon level. Returns: The number of items to drop for the current dungeon level.


generator.horiz_river(CellID cell, integer width, boolean [bridge])

Places a horizontal river on the map.

cell: The cell to use for the river. It does not have to be a fluid cell.

width: The width of the river.

bridge: Optional. If True, a 2 space wide bridge will be placed at a random coordinate on the river. If False, no bridge will be placed. If omitted, the default is to not place a bridge.


generator.vert_river(CellID cell, integer width, boolean bridge, integer [position])

generator.vert_river(CellID cell, integer width, boolean bridge, Coord [position])

Places a vertical river on the map.

cell: The cell to use for the river. It does not have to be a fluid cell.

width: The width of the river.

bridge: Optional. If True, a 2 space wide bridge will be placed at a random coordinate on the river. If False, no bridge will be placed. If omitted, the default is to not place a bridge.

NOTE: Because of a bug, a bridge will always be placed on the river, even if this value is set to False or omitted.

position: A coordinate or an integer. If an integer is supplied, this is the X position of the river's left edge. If a coordinate is supplied, the river will start at this coordinate. If omitted, the river's left edge will be selected from between X = 19 to 58.


generator.generate_rivers(boolean allow_horiz, boolean allow_more)

Creates rivers based on normal DoomRL river generation.

allow_horiz: True allows horizontal rivers to be generated. False will prevent the generation of horizontal rivers.

allow_more: True allows multiple vertical rivers. False will prevent more than one vertical river from being placed.


generator.generate_fluids(Area [where])

Creates fluids based on normal DoomRL fluid generation.

where: Optional. The area to generate fluids in. If omitted, the area used will be the entire map minus the very edge.


generator.generate_barrels()

Creates barrels based on normal DoomRL barrel generation.


generator.generate_stairs()

Creates the normal staircase based on normal DoomRL stair generation.


generator.generate_special_stairs()

Creates the special staircase based on normal DoomRL special stair generation. Whether a special staircase is placed depends on the level.special_exit value.


generator.place_player()

Places the player on a random empty space.


generator.run(Generator gen)

Runs a generator object. These are stored in the generators table.

gen: The generator object to run.


generator.reset()

Resets the map.

Dungeon Generation Functions


generator.generate_tiled()

Creates a tiled dungeon, also known as a "normal" dungeon. This only creates the layout, it does not place beings, items, stairs, barrels, or the player.


generator.maze_dungeon(CellID floor, CellID wall, integer granularity, integer tries, integer min_size, integer max_size)

Creates a maze dungeon. This only creates the layout, it does not place beings, items, stairs, barrels, or the player.

floor: The cell to use for the floor of the maze.

wall: The cell to use for the wall of the maze.

granularity: This denotes the size of the maze's paths.

tries: Number of attempts to place a new wall in the maze.

min_size: The smallest possible size of a wall.

max_size: The largest possible size of a wall.


generator.generate_caves_dungeon()

Runs the generation script for the cave dungeon. This is an all inclusive function, it also places all beings and items.


generator.generate_caves_2_dungeon()

Runs the generation script for the cave-city dungeon. This is an all inclusive function, it also places all beings and items.


generator.generate_lava_dungeon()

Runs the generation script for the lava dungeon. This is an all inclusive function, it also places all beings and items.

Event Handler Functions


generator.roll_event()

Picks an event from the events table and sets it up.


generator.setup_flood_event(integer direction, integer step, CellID cell)

Runs the setup script for the flood event.

direction: Use 1 to flood from the left. Use -1 to flood from the right.

step: Number of turns (0.1 second intervals) between each flood step.

cell: The cell to flood with. This does not have to be a fluid cell.


generator.setup_deadly_air_event(integer step)

Runs the setup script for the deadly air event.

step: Number of turns between each "chill" (loss of HP).


generator.setup_explosion_event(integer step, integer size, integer dice, integer [content])

generator.setup_explosion_event(integer step, Table size, integer dice, integer [content])

Runs the setup script for the explosion event.

step: Number of turns between each explosion.

size: Either a number or a table of two numbers. Indicates the size of each explosion. If a table is supplied, the size is randomly chosen between the range supplied each time an explosion is created.

dice: Number of d6 dice to use for the damage roll.

content: Optional. The content to place in any space where the damage to a space is more than 20 points. If omitted, nothing will placed.


generator.setup_targeted_event(integer step)

Runs the setup script for the targeting event.

step: Number of turns between each monster teleport.

Difference between revisions of "Modding:generator API (0.9.9.7)"

From DoomRL Wiki

Latest revision as of 04:02, 10 June 2013

Contents

API

Generator API Function List

Basic Cell Handling Functions

Map Checking Functions

Map Searching Functions

Advanced Cell Handling Functions

Tile Handling Functions

Room Handling Functions

Generation Algorithm Functions

Generator Helper Functions

Dungeon Generation Functions

Event Handler Functions

Views

Personal tools

Navigation

Search

Toolbox

@@ Line 1: / Line 1: @@
+''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.
 == 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 [[Modding:Constants|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 ===
 {|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"|'''Level Interface'''
+  ! colspan="2" style="background: darkred; color: yellow; font-size: 120%; text-align: center"|'''Generator Interface - Functions'''
   {{Table2Col
    |es=background: #333;
    |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px;
    |c2=padding:0px 2px;
-   |{{modarg|Coord}}|{{moddef|list|safe_empty_coord|dot}}
+  ||'''[[#Basic Cell Handling Functions|Basic Cell Handling Functions]]'''
-   |{{modarg|Coord}}|{{moddef|list|standard_empty_coord|dot}}
+  |{{modarg|integer}}|{{moddef|list|get_cell|dot||Coord|loc}}
-   |{{modarg|void}}|{{moddef|list|set_permanence|dot||Area|ar|boolean|val|Cell|tile}}
+  |{{modarg|string}}|{{moddef|list|get_cell_id|dot||Coord|loc}}
-   |{{modarg|void}}|{{moddef|list|setup_ice_event|dot}}
+  |{{modarg|integer}}|{{moddef|list|fast_get_cell|dot||integer|x|integer|y}}
-   |{{modarg|void}}|{{moddef|list|setup_perma_event|dot}}
+  |{{modarg|void}}|{{moddef|list|set_cell|dot||Coord|loc|CellID|what}}
-   |{{modarg|void}}|{{moddef|list|setup_alarm_event|dot}}
+  |{{modarg|void}}|{{moddef|list|fast_set_cell|dot||integer|x|integer|y|integer|what}}
-   |{{modarg|void}}|{{moddef|list|setup_deadly_air_event|dot||integer|step}}
+  ||'''[[#Map Checking Functions|Map Checking Functions]]'''
-   |{{modarg|void}}|{{moddef|list|setup_nuke_event|dot||integer|minutes}}
+  |{{modarg|integer}}|{{moddef|list|around|dot||Coord|where|CellSet|what}}
-   |{{modarg|void}}|{{moddef|list|setup_flood_event|dot||integer|direction|integer|step|Cell|cell|boolean|pure}}
+  |{{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_area|dot||Area|where|Flags|reqs}}
+  |{{modarg|boolean}}|{{moddef|list|scan|dot||Area|where|CellID|good}}
+  ||'''[[#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|random_coord|dot||Area|[where]}}
+  |{{modarg|Coord}}|{{moddef|list|find_random_coord|dot||CellSet|what|Area|[where]}}
+  |{{modarg|Coord}}|{{moddef|list|find_empty_coord|dot||CellSet|what|Flags|reqs|Area|[where]}}
+  |{{modarg|Coord}}|{{moddef|list|random_empty_coord|dot||Flags|reqs|Area|[where]}}
+  |{{modarg|Coord}}|{{moddef|list|find_random_empty_coord|dot||CellSet|what|Flags|reqs|Area|[where]}}
+   |{{modarg|Coord}}|{{moddef|list|safe_empty_coord|dot||Area|[where]}}
+   |{{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]}}
+  |{{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]}}
+  ||'''[[#Tile Handling Functions|Tile Handling Functions]]'''
+  |{{modarg|Table}}|{{moddef|list|create_translation|dot||Table|code}}
+  |{{modarg|Tile}}|{{moddef|list|tile_new|dot||string|map|Table|translation}}
+   |{{modarg|void}}|{{moddef|list|tile_place|dot||Coord|where|Tile|what}}
+   |{{modarg|void}}|{{moddef|list|place_tile|dot||Table|translation|string|tile|integer|x|integer|y}}
+   |{{modarg|void}}|{{moddef|list|place_dungen_tile|dot||Table|code|Tile|tile|Coord|where}}
+  |{{modarg|void}}|{{moddef|list|place_symmetry_quad|dot||string|tile|Table|translation}}
+  |{{modarg|void}}|{{moddef|list|place_proto_map|dot||Coord|where|string|proto_map|string|proto_key|Table|code}}
+  ||'''[[#Room Handling Functions|Room Handling Functions]]'''
+  |{{modarg|void}}|{{moddef|list|add_room|dot||Area|room|string|[class]}}
+  |{{modarg|void}}|{{moddef|list|add_rooms|dot}}
+  |{{modarg|Room}}|{{moddef|list|get_room|dot||integer|min_size|integer|max_x|integer|max_y|integer|max_area|string|[class]}}
+  |{{modarg|integer, integer}}|{{moddef|list|get_endpoints|dot||Coord|where|boolean|horiz|CellSet|what}}
+   |{{modarg|void}}|{{moddef|list|handle_rooms|dot||integer|count|boolean|no_monsters}}
+  ||'''[[#Generation Algorithm Functions|Generation Algorithm Functions]]'''
+  |{{modarg|void}}|{{moddef|list|run_drunkard_walk|dot||Area|where|Coord|start|integer|steps|CellID|fill|CellSet|[ignore]|boolean|[stop_at_edge]}}
+  |{{modarg|void}}|{{moddef|list|drunkard_walks|dot||integer|amount|integer|steps|CellID|fill|CellSet|[ignore]|boolean|[stop_at_edge]|Area|[where]}}
+  |{{modarg|void}}|{{moddef|list|contd_drunkard_walks|dot||integer|amount|integer|steps|CellID|fill|CellSet|edges1|CellSet|edges2|CellSet|[ignore]|boolean|[stop_at_edge]}}
+  |{{modarg|void}}|{{moddef|list|warehouse_fill|dot||CellSet|fill|Area|where|integer|size|integer|count|integer|special_chance|CellSet|special}}
+  |{{modarg|void}}|{{moddef|list|place_blob|dot||Coord|start|integer|size|CellID|cell}}
+  ||'''[[#Generator Helper Functions|Generator Helper Functions]]'''
+  |{{modarg|<value>, <value>}}|{{moddef|list|roll_pair|dot||Table|list}}
    |{{modarg|integer}}|{{moddef|list|being_weight|dot}}
    |{{modarg|integer}}|{{moddef|list|item_amount|dot}}
-   |{{modarg|void}}|{{moddef|list|restore_walls|dot||Cell|wall_cell|boolean|keep_fluids}}
+   |{{modarg|void}}|{{moddef|list|horiz_river|dot||CellID|cell|integer|width|boolean|[bridge]}}
-  |{{modarg|Cellset list}}|{{moddef|list|cell_set|dot||list|list}}
+   |{{modarg|void}}|{{moddef|list|vert_river|dot||CellID|cell|integer|width|boolean|bridge|integer|position}}
-   |{{modarg|void}}|{{moddef|list|horiz_river|dot||Cell|cell|integer|width|boolean|bridge}}
+{{moddef|list|vert_river|dot||CellID|cell|integer|width|boolean|bridge|Coord|position}}
-  |{{modarg|void}}|{{moddef|list|vert_river|dot||Cell|cell|integer|width|boolean|bridge|Coord|pos}}
    |{{modarg|void}}|{{moddef|list|generate_rivers|dot||boolean|allow_horiz|boolean|allow_more}}
-   |{{modarg|void}}|{{moddef|list|drunkard_walk|dot||Coord|start|integer|steps|Cell|cell|Cell list|ignore|boolean|break_on_edge}}
+   |{{modarg|void}}|{{moddef|list|generate_fluids|dot||Area|[where]}}
-  |{{modarg|void}}|{{moddef|list|drunkard_walks|dot||integer|amount|integer|steps|Cell|cell|Cell list|ignore|boolean|break_on_edge|Area|drunk_area}}
-  |{{modarg|void}}|{{moddef|list|contd_drunkard_walks|dot||integer|amount|integer|steps|Cell|cell|Coord|edges1|Coord|edges2|Cell list|ignore|boolean|break_on_edge}}
-  |{{modarg|void}}|{{moddef|list|plot_lines|dot||Coord|where|Area|larea|boolean|horiz|Cell|cell|Cell list|block}}
-  |{{modarg|void}}|{{moddef|list|maze_dungeon|dot|Cell|floor_cell|Cell|wall_cell|integer|granularity|integer|tries|integer|minl|integer|maxl}}
-  |{{modarg|void}}|{{moddef|list|warehouse_fill|dot||Cell|wall_cell|Area|fill_area|integer|box_size|integer|amount}}
-  |{{modarg|void}}|{{moddef|list|warehouse_dungeon|dot}}
-  |{{modarg|void}}|{{moddef|list|add_room|dot||Area|room}}
-  |{{modarg|boolean}}|{{moddef|list|add_rooms|dot}}
-  |{{modarg|Room}}|{{moddef|list|get_room|dot||integer|min_size|integer|max_x|integer|max_y}}
-  |{{modarg|void}}|{{moddef|list|generate_tiled|dot}}
-  |{{modarg|void}}|{{moddef|list|generate_warehouse_dungeon|dot}}
-  |{{modarg|void}}|{{moddef|list|generate_tiled_arena_dungeon|dot}}
-  |{{modarg|void}}|{{moddef|list|generate_city_dungeon|dot}}
-  |{{modarg|void}}|{{moddef|list|generate_maze_dungeon|dot}}
-  |{{modarg|void}}|{{moddef|list|generate_archi_dungeon|dot}}
-  |{{modarg|void}}|{{moddef|list|generate_caves_dungeon|dot}}
-  |{{modarg|void}}|{{moddef|list|generate_arena_dungeon|dot}}
-  |{{modarg|void}}|{{moddef|list|generate_fluids|dot||Area|drunk_area}}
    |{{modarg|void}}|{{moddef|list|generate_barrels|dot}}
    |{{modarg|void}}|{{moddef|list|generate_stairs|dot}}
    |{{modarg|void}}|{{moddef|list|generate_special_stairs|dot}}
-  |{{modarg|void}}|{{moddef|list|generate_lever_room|dot}}
-  |{{modarg|void}}|{{moddef|list|generate_teleport_room|dot}}
-  |{{modarg|void}}|{{moddef|list|generate_ammo_room|dot}}
-  |{{modarg|void}}|{{moddef|list|generate_basain|dot}}
-  |{{modarg|void}}|{{moddef|list|generate_warehouse_room|dot}}
-  |{{modarg|void}}|{{moddef|list|generate_vault|dot}}
-  |{{modarg|void}}|{{moddef|list|add_room_feature|dot||boolean|no_monsters}}
-  |{{modarg|void}}|{{moddef|list|handle_rooms|dot||boolean|no_monsters}}
    |{{modarg|void}}|{{moddef|list|place_player|dot}}
-   |{{modarg|void}}|{{moddef|list|roll_event|dot}}
+   |{{modarg|void}}|{{moddef|list|run|dot||Generator|gen}}
    |{{modarg|void}}|{{moddef|list|reset|dot}}
+  ||'''[[#Dungeon Generation Functions|Dungeon Generation Functions]]'''
+  |{{modarg|void}}|{{moddef|list|generate_tiled|dot}}
+  |{{modarg|void}}|{{moddef|list|maze_dungeon|dot||CellID|floor|CellID|wall|integer|granularity|integer|tries|integer|min_size|integer|max_size}}
+  |{{modarg|void}}|{{moddef|list|generate_caves_dungeon|dot}}
+  |{{modarg|void}}|{{moddef|list|generate_caves_2_dungeon|dot}}
+  |{{modarg|void}}|{{moddef|list|generate_lava_dungeon|dot}}
+  ||'''[[#Event Handler Functions|Event Handler Functions]]'''
+  |{{modarg|void}}|{{moddef|list|roll_event|dot}}
+  |{{modarg|void}}|{{moddef|list|setup_flood_event|dot||integer|direction|integer|step|CellID|cell}}
+  |{{modarg|void}}|{{moddef|list|setup_deadly_air_event|dot||integer|step}}
+  |{{modarg|void}}|{{moddef|list|setup_explosion_event|dot||integer|step|integer|size|integer|dice|integer|[content]}}
+{{moddef|list|setup_explosion_event|dot||integer|step|Table|size|integer|dice|integer|[content]}}
+  |{{modarg|void}}|{{moddef|list|setup_targeted_event|dot||integer|step}}
    |}}
 |}
-;{{moddef|desc|safe_empty_coord|dot}}
+=== Basic Cell Handling Functions ===
-:Gives a coordinate that satisfies all [[Modding:Constants#Empty Flags|empty flags]]. If one cannot be found, another attempt is made that excludes EF_NOSAFE; if one still cannot be found, another attempt is made that additionally excludes EF_NOSTAIRS and EF_NOHARM.
+;{{moddef|desc|get_cell|dot|integer|Coord|loc}}
+Gets the Numeric ID (NID) of the [[Modding:Cell|cell]] at a given map position.
+:''loc'': The coordinates of the cell to get.
+:'''Returns''': The NID of the cell.
 ----
-;{{moddef|desc|standard_empty_coord|dot}}
+;{{moddef|desc|get_cell_id|dot|string|Coord|loc}}
-:Gives a coordinate that satisfies all empty flags other than EF_NOSAFE.
+Gets the ID of the [[Modding:Cell|cell]] at a given map position.
+:''loc'': The coordinates of the cell to get.
+:'''Returns''': The string ID of the cell.
 ----
-;{{moddef|desc|set_permanence}}|dot||Area|ar|boolean|val|Cell|tile}}
+;{{moddef|desc|fast_get_cell|dot|integer|integer|x|integer|y}}
-:Adds the "frozen" level event to the map and records it in the mortem history. Levels with the frozen event change all walls into ice walls and all fluids into water.
+Gets the Numeric ID (NID) of the [[Modding:Cell|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.
 ----
-;{{moddef|desc|setup_ice_event|dot}}
+;{{moddef|desc|set_cell|dot||Coord|loc|CellID|what}}
-:Adds the "frozen" level event to the map and records it in the mortem history. Levels with the frozen event change all walls into ice walls and all fluids into water.
+Assigns a [[Modding:Cell|cell]] to a map position.
+:''loc'': The coordinates of the position to set.
+:''what'': The ID of the cell to assign to the position.
 ----
-;{{moddef|desc|setup_perma_event|dot}}
+;{{moddef|desc|fast_set_cell|dot||integer|x|integer|y|integer|what}}
-:Adds the "sturdy" level event to the map and records it in the mortem history. Levels with the sturdy event set all wall tiles to be permanent.
+Assigns a [[Modding:Cell|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.
 ----
-;{{moddef|desc|setup_alarm_event|dot}}
+=== Map Checking Functions ===
-:Adds the "alarm" level event to the map and records it in the mortem history. Levels with the alarm event set all non-player beings' [[Modding:Constants|Being Flags|BF_HUNTING]] flag to true.
+;{{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.
+:''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.
 ----
-;{{moddef|desc|setup_deadly_air_event|dot||integer|step}}
+;{{moddef|desc|cross_around|dot|integer|Coord|where|CellSet|what}}
-:Adds the "deadly air" event to the map and records it in the mortem history. Levels with the deadly air event cause all beings to lose hit points every '''step''' turns.
+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.
 ----
-;{{moddef|desc|setup_nuke_event|dot||integer|minutes}}
+;{{moddef|desc|is_empty|dot|boolean|Coord|where|Flags|reqs}}
-:Adds the "armed nuke" event to the map and records it in the mortem history. Levels with the armed nuke event begin with a [[thermonuclear bomb]] set at the player's starting position, which will explode in ''minutes'' game minutes.
+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 [[Modding:Being|being]].  See [[Modding:Constants#Empty_Flags]] for more information.
+:'''Returns''': ''True'' if the cell satisfies all of the conditions indicated in ''reqs'', ''False'' otherwise.
 ----
-;{{moddef|desc|setup_flood_event|dot||integer|direction|integer|step|Cell|cell|boolean|pure}}
+;{{moddef|desc|is_empty_area|dot|boolean|Area|where|Flags|reqs}}
-:Adds the "flood" event to the map and records it in the mortem history. Levels with the flood event are slowly filled with a fluid: ''direction'' determines whether the floor travels from the right (-1) or from the left (+1); every ''step'' turns, ''cell'' will replace all tiles in a next column to be flooded. Setting ''pure'' to false will move the player and stairs to opposite sides of the map, with the player nearest the flood.
+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 [[Modding:Being|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.
 ----
-;{{moddef|desc|being_weight|dot|integer}}
+;{{moddef|desc|scan|dot|boolean|Area|where|CellID|good}}
-:Gives a value equal to the difficulty-adjusted weight of beings for a given danger level. These are the results used for the base game's monster generation parameters.
+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.
 ----
-;{{moddef|desc|item_amount|dot|integer}}
+=== Map Searching Functions ===
-:Gives a value equal to the number of items spawned for a given danger level. On level types where the this amount isn't preset, this is the result used for the base game's item generation parameters.
+;{{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|restore_walls|dot||Cell|wall_cell|boolean|keep_fluids}}
+;{{moddef|desc|find_coord|dot|Coord|CellSet|what|Area|[where]}}
-:Sets all cells on the edge of the map to ''wall_cell''. If ''keep_fluids'' is set to true, fluid tiles will be maintained but set as permanent.
+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.
 ----
-;{{moddef|desc|cell_set|dot|Cellset list|list|list}}
+;{{moddef|desc|random_coord|dot|Coord|Area|[where]}}
-:Creates a cellset for all cells in ''list''. The returned list functions just like any [[Modding:Constants#Cellsets|CELLSET constant]].
+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.
 ----
-;{{moddef|desc|horiz_river|dot||Cell|cell|integer|width|boolean|bridge}}
+;{{moddef|desc|find_random_coord|dot|Coord|CellSet|what|Area|[where]}}
-:Adds a horizontal river to the map, created using ''cell'' tiles. ''width'' sets the tile-width of the river. If ''bridge'' is set to true, a non-fluid floor bridge will be created on the river.
+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.
 ----
-;{{moddef|desc|vert_river|dot||Cell|cell|integer|width|boolean|bridge|Coord|pos}}
+;{{moddef|desc|find_empty_coord|dot|Coord|CellSet|what|Flags|reqs|Area|[where]}}
-;{{moddef|desc|vert_river|dot||Cell|cell|integer|width|boolean|bridge|integer|pos}}
+Searches the map for the first "empty" coordinate containing one of the indicated cell IDs, defining "empty" based on a list of criteria.
-:Adds a vertical river to the map, created using ''cell'' tiles. ''width'' sets the tile-width of the river, and ''pos'' sets the starting position of the river. If ''pos'' is given as an integer, then the starting y-coordinate of the river is at the top of the map. If ''bridge'' is set to true, a non-fluid floor bridge will be created on the river.
+:''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 [[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.
+:'''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|generate_rivers|dot||boolean|allow_horiz|boolean|allow_more}}
+;{{moddef|desc|random_empty_coord|dot|Coord|Flags|reqs|Area|[where]}}
-:Generates a random number of horizontal and vertical rivers on the map. See [[Fluids#Rivers|Rivers]] for more information. The fluid type varies with map depth.
+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 [[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.
+:'''Returns''': A random coordinate that meets the supplied criteria.
 ----
-;{{moddef|desc|drunkard_walk|dot||Coord|start|integer|steps|Cell|cell|Cell list|ignore|boolean|break_on_edge}}
+;{{moddef|desc|find_random_empty_coord|dot|Coord|CellSet|what|Flags|reqs|Area|[where]}}
-:Generates ''cell'' tiles according to a drunken walk algorithm. It travels ''steps'' times, starting at the coordinate ''start''. Any cells in ''ignore'' will not be set over but the algorithm will still continue. If ''break_on_edge'' is set to true, the drunken walk will stop if it hits a map border: otherwise it will continue, clamping cells within the map as necessary.
+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 [[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.
+:'''Returns''': A random coordinate that meets the supplied criteria.
 ----
-;{{moddef|desc|drunkard_walks|dot||integer|amount|integer|steps|Cell|cell|Cell list|ignore|boolean|break_on_edge|Area|drunk_area}}
+;{{moddef|desc|random_square|dot|Coord|CellSet|what}}
-:As Generator.drunkard_walk, but repeated ''amount'' times. Additionally, rather than specifically a starting position, all walks are chosen from a random coordinate within ''drunk_area''.
+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.
 ----
-;{{moddef|desc|contd_drunkard_walks|dot||integer|amount|integer|steps|Cell|cell|Coord|edges1|Coord|edges2|Cell list|ignore|boolean|break_on_edge}}
+;{{moddef|desc|safe_empty_coord|dot|Coord|Area|[where]}}
-:As Generator.drunkard_walks, but rather than limiting the walk's starting position, the walk will stop prematurely if it has reached the x- or y-coordinates of both ''edges1'' and ''edges2''.
+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.
 ----
-;{{moddef|desc|plot_lines|dot||Coord|where|Area|larea|boolean|horiz|Cell|cell|Cell list|block}}
+;{{moddef|desc|standard_empty_coord|dot|Coord}}
-:Generates a line of ''cell'' tiles on the map, starting at ''where'' and extending to the boundaries of ''larea''. ''horiz'' set to true will produce horizontal lines: otherwise it will produce vertical lines. If a cell from ''block'' is found, the line will end prematurely at the end on which it was blocked.
+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.
 ----
-;{{moddef|desc|maze_dungeon|dot|Cell|floor_cell|Cell|wall_cell|integer|granularity|integer|tries|integer|minl|integer|maxl}}
+=== Advanced Cell Handling Functions ===
-:Generates a map-wide maze, using ''wall_cell'' as the wall tiles and ''floor_cell'' as the floor tiles. Wall corridors are at least ''minl'' tiles apart and at most ''maxl'' tiles apart: ''granularity'' sets a rough complexity of the map. The number of walls attempted to be made is equal to ''tries''.
+;{{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|warehouse_fill|dot||Cell|wall_cell|Area|fill_area|integer|box_size|integer|amount}}
+;{{moddef|desc|fill_pattern|dot||Area|where|boolean|horiz|string|Table|line1|Table|[line2]}}
-:Generates ''wall_cell'' tiles in the shape of a square within ''fill_area''. ''boxsize'' sets the size of the side of a box, and ''amount'' sets the number of tries for boxes to be added.
+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|warehouse_dungeon|dot}}
+;{{moddef|desc|fill_edges|dot||CellID|what}}
-:Generates a map-wide warehouse setting. Warehouse dungeons are divided into three large rooms, each attempting 50 tries with boxes of side length 3.
+Fills the edges of the map with the given cell.
+:''what'': The cell to fill with.
 ----
-;{{moddef|desc|add_room|dot||Area|room}}
+;{{moddef|desc|each|dot|Table|CellID|what|Area|[where]}}
-:Adds ''room'' to the Generator.room_list and Generator.room_meta lists. This is used in conjunction with room generation functions.
+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.
 ----
-;{{moddef|desc|add_rooms|dot|boolean}}
+;{{moddef|desc|set_blood|dot||Area|[where]|boolean|[value]|CellID|[what]}}
-:As Generator.add_room, but locates all rooms on the map and adds them to Generator.room_list and Generator.room_meta instead.
+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|get_room|dot|Room|integer|min_size|integer|max_x|integer|max_y}}
+;{{moddef|desc|set_permanence|dot||Area|[where]|boolean|[value]|CellID|[what]}}
-:Finds a room that contains at least ''min_size'' in both height and width, and has a width and height no bigger than ''max_x'' and ''max_y'', respectively.
+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|generate_tiled|dot}}
+;{{moddef|desc|cell_set|dot|Table|CellSet|cells}}
-:Generates a "normal" map. Normal levels are divided randomly into rectangular rooms.
+Creates a cell group.
+:''cells'': A list of cells to add to the group.
+:'''Returns''': A cell group table.
 ----
-;{{moddef|desc|generate_warehouse_dungeon|dot}}
+;{{moddef|desc|restore_walls|dot||CellID|wallCell|boolean|keepFluids}}
-:Builds a "warehouse" level. This includes everything necessary to be played as a typical random level.
+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|generate_tiled_arena_dungeon|dot}}
+;{{moddef|desc|plot_line|dot||Coord|where|boolean|horiz|CellID|cell|CellSet|block}}
-:Builds a "single-monster" level. This includes everything necessary to be played as a typical random level.
+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|generate_city_dungeon|dot}}
+;{{moddef|desc|plot_lines|dot||Coord|where|Area|larea|boolean|horiz|CellID|cell|CellSet|block}}
-:Builds a "city" level. This includes everything necessary to be played as a typical random level.
+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|generate_maze_dungeon|dot}}
+;{{moddef|desc|scatter|dot||Area|where|CellID|good|CellID|fill|integer|count}}
-:Builds a "maze" level. This includes everything necessary to be played as a typical random level.
+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 change it.  The final number placed may be less than ''count'' (or even 0), but never more.
 ----
-;{{moddef|desc|generate_archi_dungeon|dot}}
+;{{moddef|desc|scatter_blood|dot||Area|where|CellID|[good]|integer|count}}
-:Builds an "archi" level. This includes everything necessary to be played as a typical random level.
+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|generate_caves_dungeon|dot}}
+;{{moddef|desc|scatter_put|dot||Area|where|Table|translation|string|tile|CellID|good|integer|count}}
-:Builds a "cave" level. This includes everything necessary to be played as a typical random level.
+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|generate_arena_dungeon|dot}}
+;{{moddef|desc|transmute|dot||CellID|to|CellSet|from|Area|[where]}}
-:Builds an "arena" level. This includes everything necessary to be played as a typical random level.
+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|generate_fluids|dot||Area|drunk_area}}
+;{{moddef|desc|transmute_marker|dot||Flag|marker|CellID|To|Area|[where]}}
-:Generates all non-river fluids on the map using drunken walks, within ''drunk_area''. The fluid type varies with danger level.
+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.
+----
+=== Tile Handling Functions ===
+;{{moddef|desc|create_translation|dot|Table|Table|code}}
+Parses a translation table.  Refer to this (will be linked soon) for more information.
+:''code'': The translation table.
+:'''Returns''': A parsed translation table.
+----
+;{{moddef|desc|tile_new|dot|Tile|string|map|Table|translation}}
+Creates a new tile object.
+:''map'': A multi-line string containing the arrangement of the tile using the ''translation'' to convert the characters to cells.  Refer to this (will be linked soon) for more information.
+:''translation'': A table with to be used with the ''map'' argument.  Refer to this (will be linked soon) for more information.
+:'''Returns''': The new tile object.
+----
+;{{moddef|desc|tile_place|dot||Coord|where|Tile|what}}
+Places the cells of the tile on the map.
+:''where'': The coordinate that the upper-left of the tile should reside at.
+:''what'': The tile object that will be placed.
+----
+;{{moddef|desc|place_tile|dot||Table|translation|string|tile|integer|x|integer|y}}
+Combines the tile_new and tile_place functions together, by placing a tile using a string and translation table.
+:''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 containing the arrangement of the tile using the ''translation'' to convert the characters to cells.  Refer to this (will be linked soon) for more information.
+:''x'': The X position that the tile will be placed at.
+:''y'': The Y position that the tile will be placed at.
+----
+;{{moddef|desc|place_dungen_tile|dot||Table|code|Tile|tile|Coord|where}}
+Places an entire tile, including beings and items in the translation, on the map.
+:''code'': The translation table.  Refer to this (will be linked soon) for more information.
+:''tile'': A multi-line string containing the arrangement of the tile using the ''translation'' to convert the characters to cells and indicate the positions of the beings and items.  Refer to this (will be linked soon) for more information.
+:''where'': The coordinate the tile will be placed at.
+----
+;{{moddef|desc|place_symmetry_quad|dot||string|tile|Table|translation}}
+Takes a tile object and places it in all four corners.  The tile object should be setup for the upper left corner and will be mirrored to the other corners.  The tiles are placed one space from the map edge.
+:''tile'': A multi-line string containing the arrangement of the tile using the ''translation'' to convert the characters to cells and indicate the positions of the beings and items.  Refer to this (will be linked soon) for more information.
+:''translation'': The translation table.  Refer to this (will be linked soon) for more information.
+----
+;{{moddef|desc|place_proto_map|dot||Coord|where|string|proto_map|string|proto_key|Table|code}}
+Creates a map using multiple tile sets.
+:''where'': The upper-left position of the map where the tiles will be layout from.
+:''proto_map'': A string indicating the arrangement of the different pieces of the map.  e.g., "ABCD", will lay out 4 different tiles with A on the far left and D on the far right.
+:''proto_key'': A table containing, for each character in ''proto_map'', a table of the possible tiles for that section.
+:''code'': The translation table for all the tile possibilities.  Refer to this (will be linked soon) for more information.  All tiles use the same translation table.
+----
+=== Room Handling Functions ===
+;{{moddef|desc|add_room|dot||Area|room|string|[class]}}
+Marks an area that can become a special room.
+:''room'': The area of the room.  This includes the walls.
+:''class'': ''Optional.'' A string used to denote which room generators can be used on this room.  If omitted, the class used is "closed".
+----
+;{{moddef|desc|add_rooms|dot}}
+Finds all the areas that can be rooms on a map and adds them to the appropriate meta-map tables.
+----
+;{{moddef|desc|get_room|dot|Room|integer|min_size|integer|max_x|integer|max_y|integer|max_area|string|class}}
+Selects a room given certain criteria.
+:''min_size'': The smallest X and Y dimensions the room can be.
+:''max_x'': The maximum width of the room.
+:''max_y'': The maximum height of the room.
+:''max_area'': The largest area the room can be.
+:''class'': ''Optional.'' The string denoting which room classes are valid for this room generator.  If omitted, "any" is used, which does not restrict the selection of rooms.
+----
+;{{moddef|desc|get_endpoints|dot|integer, integer|Coord|where|boolean|horiz|CellSet|what}}
+Finds the ends of a line of cells.
+:''where'': The starting coordinate.
+:''horiz'': ''True'' checks horizontally.  ''False'' checks vertically.
+:''what'': The cell(s) that make up the line to check.  The functions stops at the first cell '''not''' in this list.
+:'''Returns''': Two integers.  If ''horiz'' is ''True'', these are the X positions the line stops at.  If ''horiz'' is ''False'', these are the Y positions the line stops at.
+----
+;{{moddef|desc|handle_rooms|dot||integer|count|boolean|no_monsters}}
+Runs the rooms selection and setup process for a map.
+:''count'': The number of rooms to attempt to place.
+:''no_monsters'': ''True'' will exclude room generators that place monsters.  ''False'' will not.
+----
+=== Generation Algorithm Functions ===
+;{{moddef|desc|run_drunkard_walk|dot||Area|where|Coord|start|integer|steps|CellID|fill|CellSet|[ignore]|boolean|[stop_at_edge]|Area|where}}
+Runs an algorithm that walks to random adjacent spaces.
+:''where'': The area that the algorithm will run in.  If the algorithm tries to leave the area, it will stop early or will be pushed back in the area (''stop_at_edge'' will determine which of these happen).
+:''start'': The location the algorithm will begin at.
+:''steps'': The number of steps the algorithm will take.  The number of spaces covered by the algorithm will be at most this number.
+:''fill'': The cell that will be placed at each location the algorithm hits.
+:''ignore'': ''Optional.'' If specified, the algorithm will not place the ''fill'' cell in any location that has one of the cell(s) specified.  If omitted, no locations are ignored.
+:''stop_at_edge'': ''Optional.'' If ''True'', the algorithm will end early if it moves past the end of the area.  If ''False'', the algorithm will clamp to the area (any moves to outside the area get moved back in the area).  If omitted, the default is to clamp.
+----
+;{{moddef|desc|drunkard_walks|dot||integer|amount|integer|steps|CellID|fill|CellSet|[ignore]|boolean|[stop_at_edge]|Area|[where]}}
+Runs multiple "drunken walk" algorithms.
+:''amount'': The number of times to perform the algorithm.
+:''steps'': The number of steps each run of the algorithm will take.  The number of spaces covered by the algorithm will be at most the ''amount'' times the number of ''steps''.
+:''fill'': The cell that will be placed at each location the algorithm hits.
+:''ignore'': ''Optional.'' If specified, the algorithm will not place the ''fill'' cell in any location that has one of the cell(s) specified.  If omitted, no locations are ignored.
+:''stop_at_edge'': ''Optional.'' If ''True'', the algorithm will end early if it moves past the end of the area.  If ''False'', the algorithm will clamp to the area (any moves to outside the area get moved back in the area).  If omitted, the default is to clamp.
+:''where'': ''Optional.'' The area the algorithm will run in.  If the algorithm tries to leave the area, it will stop early or will be pushed back in the area (''stop_at_edge'' will determine which of these happen).  If omitted, the default is entire area minus the very edge.
+----
+;{{moddef|desc|contd_drunkard_walks|dot||integer|amount|integer|steps|CellID|fill|CellSet|edges1|CellSet|edges2|CellSet|[ignore]|boolean|[stop_at_edge]}}
+Runs multiple "drunken walk" algorithms starting at a space that doesn't have certain cells around it.
+:''amount'': The number of times to perform the algorithm.
+:''steps'': The number of steps each run of the algorithm will take.  The number of spaces covered by the algorithm will be at most the ''amount'' times the number of ''steps''.
+:''fill'': The cell that will be placed at each location the algorithm hits.
+:''edges1'': The algorithm will not start on a space with a cell listed here next to it.
+:''edges2'': The algorithm will not start on a space with a cell listed here next to it.
+:''ignore'': ''Optional.'' If specified, the algorithm will not place the ''fill'' cell in any location that has one of the cell(s) specified.  If omitted, no locations are ignored.
+:''stop_at_edge'': ''Optional.'' If ''True'', the algorithm will end early if it moves past the end of the area.  If ''False'', the algorithm will clamp to the area (any moves to outside the area get moved back in the area).  If omitted, the default is to clamp.
+----
+;{{moddef|desc|warehouse_fill|dot||CellID|fill|Area|where|integer|[size]|integer|[count]|integer|[special_chance]|CellID|[special]}}
+Fills an area with random squares of cells.
+:''fill'': The cell(s) to use for each square.  If a list is given, one is chosen at random for each square.
+:''where'': The area to fill.
+:''size'': ''Optional.'' The size of the squares to use. If omitted, the default is 2.
+:''count'': ''Optional.'' The number of attempts. If omitted, the default is 50.
+:''special_chance'': ''Optional.'' A number indicating the probability of using a special list of cells to fill the square with instead of the ''fill'' list.  The roll used for the chance is based on the ''size'' parameter.  A number from 1 to (100 * ''size'') is chosen for each square and if the roll is less than the special_chance number, the ''special'' cell set is used to fill the square instead. If omitted, all squares will be filled from the ''fill'' set.
+:''special'': ''Optional.'' The list of cells to use if the special set is to be used, based on ''special_chance''. If omitted, all squares will be filled from the ''fill'' set.
+----
+;{{moddef|desc|place_blob|dot||Coord|start|integer|size|CellID|cell}}
+Fills an area by expanding to random edge coordinates.
+:''start'': The position to start the blob at.
+:''size'': The number of spaces to expand the blob to.
+:''cell'': The cell to fill the blob area with.
+----
+=== Generator Helper Functions ===
+;{{moddef|desc|roll_pair|dot|<value>, <value>|Table|list}}
+Takes a list of values of any type and returns two different values randomly from the list.
+:''list'': The list to choose from.
+:'''Returns''': Two different values.  If the list only contains one choice, it will be returned, but only once.
+----
+;{{moddef|desc|being_weight|dot}}
+Gets the total danger level for the current dungeon level.
+'''Returns''': The danger level for the current dungeon level.  This value is calcuated using the current difficulty and ''level.danger_level''.
+----
+;{{moddef|desc|item_amount|dot}}
+Gets the number of items to drop for the current dungeon level.
+'''Returns''': The number of items to drop for the current dungeon level.
+----
+;{{moddef|desc|horiz_river|dot||CellID|cell|integer|width|boolean|[bridge]}}
+Places a horizontal river on the map.
+:''cell'': The cell to use for the river.  It does not have to be a fluid cell.
+:''width'': The width of the river.
+:''bridge'': ''Optional.'' If ''True'', a 2 space wide bridge will be placed at a random coordinate on the river.  If ''False'', no bridge will be placed.  If omitted, the default is to not place a bridge.
+----
+;{{moddef|desc|vert_river|dot||CellID|cell|integer|width|boolean|bridge|integer|[position]}}
+;{{moddef|desc|vert_river|dot||CellID|cell|integer|width|boolean|bridge|Coord|[position]}}
+Places a vertical river on the map.
+:''cell'': The cell to use for the river.  It does not have to be a fluid cell.
+:''width'': The width of the river.
+:''bridge'': ''Optional.'' If ''True'', a 2 space wide bridge will be placed at a random coordinate on the river.  If ''False'', no bridge will be placed.  If omitted, the default is to not place a bridge.
+:: NOTE: Because of a bug, a bridge will always be placed on the river, even if this value is set to ''False'' or omitted.
+:''position'':  A coordinate or an integer.  If an integer is supplied, this is the X position of the river's left edge.  If a coordinate is supplied, the river will start at this coordinate.  If omitted, the river's left edge will be selected from between X = 19 to 58.
+----
+;{{moddef|desc|generate_rivers|dot||boolean|allow_horiz|boolean|allow_more}}
+Creates rivers based on normal DoomRL river generation.
+:''allow_horiz'': ''True'' allows horizontal rivers to be generated.  ''False'' will prevent the generation of horizontal rivers.
+:''allow_more'': ''True'' allows multiple vertical rivers.  ''False'' will prevent more than one vertical river from being placed.
+----
+;{{moddef|desc|generate_fluids|dot||Area|[where]}}
+Creates fluids based on normal DoomRL fluid generation.
+:''where'': ''Optional.'' The area to generate fluids in.  If omitted, the area used will be the entire map minus the very edge.
 ----
 ;{{moddef|desc|generate_barrels|dot}}
-:Generates all barrels on the map, The barrel type varies with danger level.
+Creates barrels based on normal DoomRL barrel generation.
 ----
 ;{{moddef|desc|generate_stairs|dot}}
-:Generates stairs on the map.
+Creates the normal staircase based on normal DoomRL stair generation.
 ----
 ;{{moddef|desc|generate_special_stairs|dot}}
-:Generates special stairs on the map, if a special level exists at the current map depth.
+Creates the special staircase based on normal DoomRL special stair generation.  Whether a special staircase is placed depends on the level.special_exit value.
 ----
-;{{moddef|desc|generate_lever_room|dot}}
+;{{moddef|desc|place_player|dot}}
-:Finds a room of appropriate size and adjusts it into a lever room.
+Places the player on a random empty space.
 ----
-;{{moddef|desc|generate_teleport_room|dot}}
+;{{moddef|desc|run|dot||Generator|gen}}
-:Finds a room of appropriate size and adjusts it into a teleporter room.
+Runs a generator object.  These are stored in the generators table.
+:''gen'': The generator object to run.
 ----
-;{{moddef|desc|generate_ammo_room|dot}}
+;{{moddef|desc|reset|dot}}
-:Finds a room of appropriate size and adjusts it into an ammo room. The type of ammo varies with danger level.
+Resets the map.
 ----
-;{{moddef|desc|generate_basain|dot}}
+=== Dungeon Generation Functions ===
-:Finds a room of appropriate size and adjusts it into a room filled with fluid.
+;{{moddef|desc|generate_tiled|dot}}
+Creates a tiled dungeon, also known as a "normal" dungeon.  This only creates the layout, it does not place beings, items, stairs, barrels, or the player.
 ----
-;{{moddef|desc|generate_warehouse_room|dot}}
+;{{moddef|desc|maze_dungeon|dot||CellID|floor|CellID|wall|integer|granularity|integer|tries|integer|min_size|integer|max_size}}
-:Finds a room of appropriate size and adjusts it into a room with boxes (as Generator.warehouse_fill).
+Creates a maze dungeon.  This only creates the layout, it does not place beings, items, stairs, barrels, or the player.
+:''floor'': The cell to use for the floor of the maze.
+:''wall'': The cell to use for the wall of the maze.
+:''granularity'': This denotes the size of the maze's paths.
+:''tries'': Number of attempts to place a new wall in the maze.
+:''min_size'': The smallest possible size of a wall.
+:''max_size'': The largest possible size of a wall.
 ----
-;{{moddef|desc|generate_vault|dot}}
+;{{moddef|desc|generate_caves_dungeon|dot}}
-:Finds a room of appropriate size and adjust it into a vault. The monsters, items, and type of vault vary with danger level.
+Runs the generation script for the cave dungeon.  This is an all inclusive function, it also places all beings and items.
 ----
-;{{moddef|desc|add_room_feature|dot||boolean|no_monsters}}
+;{{moddef|desc|generate_caves_2_dungeon|dot}}
-:Randomly selects a room generation function to be added to the map. ''no_monsters'' set to true excludes the possibility of a vault room being generated.
+Runs the generation script for the cave-city dungeon.  This is an all inclusive function, it also places all beings and items.
 ----
-;{{moddef|desc|handle_rooms|dot||boolean|no_monsters}}
+;{{moddef|desc|generate_lava_dungeon|dot}}
-:Generates up to seven special rooms on the map and restores walls that were otherwise removed as a result of the room generation.
+Runs the generation script for the lava dungeon.  This is an all inclusive function, it also places all beings and items.
-----
-;{{moddef|desc|place_player|dot}}
-:Adds to player to the map.
 ----
+=== Event Handler Functions ===
 ;{{moddef|desc|roll_event|dot}}
-:Randomly select a level event function to be added to the map.
+Picks an event from the events table and sets it up.
+----
+;{{moddef|desc|setup_flood_event|dot||integer|direction|integer|step|CellID|cell}}
+Runs the setup script for the flood event.
+:''direction'': Use 1 to flood from the left.  Use -1 to flood from the right.
+:''step'': Number of turns (0.1 second intervals) between each flood step.
+:''cell'': The cell to flood with.  This does not have to be a fluid cell.
+----
+;{{moddef|desc|setup_deadly_air_event|dot||integer|step}}
+Runs the setup script for the deadly air event.
+:''step'': Number of turns between each "chill" (loss of HP).
+----
+;{{moddef|desc|setup_explosion_event|dot||integer|step|integer|size|integer|dice|integer|[content]}}
+;{{moddef|desc|setup_explosion_event|dot||integer|step|Table|size|integer|dice|integer|[content]}}
+Runs the setup script for the explosion event.
+:''step'': Number of turns between each explosion.
+:''size'': Either a number or a table of two numbers.  Indicates the size of each explosion.  If a table is supplied, the size is randomly chosen between the range supplied each time an explosion is created.
+:''dice'': Number of d6 dice to use for the damage roll.
+:''content'': ''Optional.'' The content to place in any space where the damage to a space is more than 20 points.  If omitted, nothing will placed.
+----
+;{{moddef|desc|setup_targeted_event|dot||integer|step}}
+Runs the setup script for the targeting event.
+:''step'': Number of turns between each monster teleport.
 ----
-;{{moddef|desc|reset|dot}}
-:Clears all generation properties and hooks, and changes the map into one bordered with the level style's walls and otherwise filled with the level style's floors.