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

Revision as of 15:01, 24 May 2013

This page is currently under construction.

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 types "Flag" and "Flags" expect a single flag constant of the indicated type, and a list of such flag constants, respectively.

The argument type "any" means any lua type.

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

Table Parameters

Some of the functions in the Level API take a parameter in a special table format. Those functions have a parameter type of *ParamTable*. When calling these functions, the keys of the table given as the argument must exactly match the names given, although they may appear in any order. Details for which keys are looked for are provided in the function's description. Additional keys specified in these tables will be ignored.

Level API Function List

Level Interface - Functions
	Level Object Functions
string	get_id()
integer	get_uid()
string	get_type()
Area	get_area()
object	get_parent()
integer	get_child_count()
table	children(string filter)
table	children_in_range(Coord where, integer range, string filter)
void	destroy()
	Level Property Functions
void	add_property(any key, any val)
any	get_property(any key)
boolean	has_property(any key)
void	remove_property(any key)
void	set_property(any key, any value)
	Cell Level Functions
CellID	get_cell(Coord where)
integer	raw_get_cell(integer x, integer y)
void	set_cell(Coord where, CellID what)
void	raw_set_cell(integer x, integer y, integer what)
integer	get_hp(Coord where)
void	set_hp(Coord where, integer new_hp)
boolean	get_light_flag(Flag what, Coord [where])
void void	set_light_flag(Flag what, boolean [value], Coord [where]) set_light_flag(Flag what, boolean [value], Area [where])
boolean	is_visible(Coord a)
boolean	eye_contact(Coord a, Coord b)
boolean	is_empty(Coord where, Flags reqs)
boolean	is_empty_area(Area where, Flags reqs)
	Being Level Functions
table	beings()
table	beings_in_range(Coord where, integer range)
Being	get_being(Coord where)
Being	drop_being(Being what, Coord where)
void	drop_being_ext(Being being, Coord where)
void	clear_being(Coord where, boolean silent)
table	get_being_table(integer [danger], table [weights], table [reqs], integer [dmod])
void	flood_monster(*ParamTable* args)
void	flood_monsters(*ParamTable* args)
BeingID	roll_being(*ParamTable* args)
void	summon(BeingID id, integer [count]) summon(*ParamTable* args)
	Item Level Functions
table	items()
table	items_in_range(Coord where, integer range)
Item	get_item(Coord where)
Item	drop_item(string what, Coord where, boolean [onfloor]) drop_item(table what, Coord where, boolean [onfloor])
void	drop_item_ext(table item, Coord where) drop_item_ext(string item, Coord where)
void	try_destroy_item(Coord where)
table	get_item_table(integer [dlevel], table [weights], table [reqs])
void	flood_items(integer amount) flood_items(*ParamTable* args)
ItemID	roll_item(*ParamTable* args)
Item	drop(ItemID id, integer [count])
Item	area_drop(Area where, ItemID id, integer [count], boolean [onfloor])
	Miscellanous Functions
void	explosion(Coord where, integer size, integer delay, integer dice, integer sides, Color color, SoundID [sound_id], DamageType [type], ExplosionFlags [flags], CellID [content])
void	flood(CellID tile, Area flood_area)
boolean	is_corpse(Coord c)
void	nuke()
void	play_sound(SoundID sound_id, Coord where)
void	player(integer x, integer y)
boolean	push_cell(Coord c, Coord target, boolean [quiet])
void	recalc_fluids()
void	register_hook(string hookname, any func)

Level Object Functions


get_id() → string

Gets the ID of the level.

Returns: The string ID of the level.


get_uid() → integer

Gets the unique ID (UID) of the level.

Returns: The numeric ID of the level.


get_type() → string

Gets the type of this object.

Returns: The string "level".


get_area() → Area

Gets the level's entire area.

Returns: An Area object encompassing the entire map.


get_parent() → object

Gets the parent of this object.

Returns: Nil. Level has no parent object.


get_child_count() → integer

Gets the number of children this object is the parent of. All beings and items on the level are children of the level object.

Returns: Total number of beings and items on the map (being count will include the player).


children()

Gets a table containing each child object of level. All beings and items on the level are children of the level object.

Returns: A table of all beings and items on the map.


destroy()

Destroys the level object. You should not call this in your lua script.

Level Property Functions


add_property(any key, any value)

Adds a user-defined property to the level object.

key: The value to refer to the property by.

value: The corresponding value of the property.


get_property(any key) → any

Retrieves the value of a user-defined property.

key: The property's key value, defined when it was added.

Returns: The current value of the property.


has_property(any key) → boolean

Checks to see if the given property exists.

key: The property key to check for.

Returns: True if the property exists, False if it does not.


remove_property(any key)

Removes a property from the level object.

key: The key of the property to remove.


set_property(any key, any value)

Assigns a new value to an existing property.

key: The key of the property to change.

value: The new value to assign to the property.

Cell Level Functions


get_cell(Coord where) → CellID

Gets the cell at a specific map coordinate.

where: The location to get.

Returns: The ID of the cell at the location.


raw_get_cell(integer x, integer y) → integer

Gets the cell ID at a specific map coordinate.

x: The X position of the coordinate to get.

y: The Y position of the coordinate to get.

Returns: The numeric ID of the cell at the coordinates.


set_cell(Coord where, CellID what)

Assigns a new cell to a map coordinate.

where: The location to change.

what: The cell to assign to the location.


raw_set_cell(integer x, integer y, integer what)

Assigns a new cell to a map coordinate.

x: The X position of the location to change.

y: The Y position of the location to change.

what: The numeric ID of the cell to assign.


get_hp(Coord where) → integer

Gets the HP of the cell at the specified location.

where: The coordinate to get the HP amount from.

Returns: The amount of HP the cell has.


set_hp(Coord where, integer new_hp)

Sets the HP of the cell at the specified location.

where: The coordinate to set.

new_hp: The new HP value to set for the coordinate.


get_light_flag(Flag what, Coord where) → boolean

Checks a cell for a certain light flag.

what: The LightFlag (named constant that starts with LF) to check for. Refer to this for more info.

where: The location to check.

Returns: True if the flag is set. False if it is not.


set_light_flag(Flag what, boolean [value], Coord [where])

set_light_flag(Flag what, boolean [value], Area [where])

Sets or unsets a LightFlag at a specified location or specified locations.

what: The LightFlag (named constant that starts with LF) to check for. Refer to this for more info.

value: Optional. True to set the flag, False to unset it. If omitted, the default is to set the flag.

where: Optional. The coordinate or area to change. If an area is supplied, all cells in the area will have the flag set or unset. If omitted, the entire map will have the flag set or unset.


is_visible(Coord a) → boolean

Determines if the player can see this space.

a: The space to check.

Returns: True if the player can see it, False if the player cannot.


eye_contact(Coord a, Coord b) → boolean

Checks to see if two spaces can see each other. This check uses the monster vision algorithm, which is stricter than the player's vision algorithm.

a: The first space to check.

b: The second space to check.

Returns: True if the spaces are visible to each other, False if not.


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.


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.

Being Level Functions


beings() → table

Gets a table containing all of the beings on the level.

Returns: A table containing all beings on the level.


beings_in_range(Coord where, integer range) → table

Gets a table containing all of the beings within a certain distance of a location.

where: The location to search around.

range: The distance away from the location to get beings from.

Returns: A table containing the beings close enough to the location specified.


get_being(Coord where) → Being

Gets the being at the specified coordinate.

where: The location to get the being from.

Returns: The being at the location.


drop_being(BeingID what, Coord where) → Being

Places a being on the map.

what: The id of the being to place.

where: The location to attempt to drop the being. If there is already a being at that location, the being will be dropped nearby.

Returns: A reference to the being dropped.


drop_being_ext(BeingID being, Coord where)

Places a being on the map with modifications.

being: A BeingID, or a table whose first field is a BeingID, followed by the changes to the beings properties in the form field = new_value.

where: The location to attempt to drop the being. If there is already a being at that location, the being will be dropped nearby.


clear_being(Coord where, boolean silent)

Removes a being from the map.

where: The location to remove the being from.

silent: If true, the being will be removed without making any sounds or causing any messages. If false, the being will act as though they were killed (complete with message and sound).


get_being_table(integer [dlevel], table [weights], table [reqs], integer [dmod]) → table

Gets a weight table for beings and being groups, using the indicated criteria.

dlevel: Optional. The depth to pull the list of beings for. Only beings and groups that have an equal or smaller min_level and an equal or larger max_level will be selected. The dmod parameter also modifies which beings will be picked. If omitted, the current danger level (which is usually the current depth) is used.

weights: Optional. A table containing modifiers to weights. The keys of the table are ids, flags, or blueprint fields to look for. For example, "former" will match the being with the id "former" (that is, Former Humans). Suppling a being flag (such as BF_BOSS or BF_ENVIROSAFE) will look for that flag in the being prototype's flag list. Suppling a blueprint field will match all beings that have that field in their blueprint table, provided that the value of the field isn't nil, false, or 0. Each matched being will have its weight multiplied by the value supplied for that key. For example, "former" = 2 will double the weight value of Former Humans, while "former" = 0.5 will halve it. If a being matches multiple entries, all are applied. (for example, the table {BF_ENVIROSAFE = 2, "pain" = 2} will match Pain Elementals twice -- since both apply a double modifier to weight, Pain Elementals will now have 4 times the weight.) If omitted, no modifications are made to weights.

reqs: Optional. A table containing requirements to check for. Only beings that meet all of the requirements will be included in the resulting weight table. The keys of the table are blueprint fields that must be matched. The value for each key in the table is either a single value, which only beings whose blueprint field key has the value supplied will match, or a table of values, which will match beings that have one or more of the supplied values if the value of the blueprint field isn't a table itself, or all of the values if it is. For example, if the reqs table is { id = "former" } , it will match Former Human (since its id is "former"). If the reqs table has { id = {"former", "sergeant", "captain" } }, Former Human, Former Sergeant, and Former Captain will be matched. If the reqs table has { flags = { BF_BOSS, BF_ENVIROSAFE } }, this will return all the beings with both the enviro-safe flag and the boss flag (since the flags blueprint field is a table itself). If omitted, no beings or groups are excluded (aside from those already excluded by the dlevel and dmod parameters).

dmod: The current dlevel is adjusted by the value here for the min_level check. This allows beings with a higher min_level to be selected on an earlier depth (if positive), or exclude beings with a higher min_level for extra levels (if negative). In other words, this enables monsters to spawn "out of depth". If omitted, the default is 3 if difficulty is medium (HMP), 6 if difficulty is hard or very hard (UV and N!), and 0 otherwise.

Returns: A weight table object.


flood_monster(*ParamTable* args)

Places one or more of a single type of monster on the level.

args: A table that looks for the following keys:

id: The ID of the being to place.

danger: The total amount of danger points worth of this monster to place. This field is optional if count is set. If both danger and count are set, the function will stop placing monsters when either danger or count is reached.

count: The number of monsters to place. This field is optional if danger is set. If both danger and count are set, the function will stop placing monsters when either danger or count is reached.

flags: Optional. A list of EmptyFlags that determines where monsters are allowed to be placed. If omitted, the default list is { EF_NOBEINGS, EF_NOBLOCK, EF_NOHARM, EF_NOSPAWN }.


flood_monsters(*ParamTable* args)

Places monsters on the level.

args: A table that looks for the following keys:

danger: The total amount of danger points worth of monsters to place. This field is optional if amount is set. If both danger and amount are set, the function will stop placing monsters when either danger or amount is reached.

amount: The number of monsters to place. This field is optional if danger is set. If both danger and amount are set, the function will stop placing monsters when either danger or amount is reached.

flags: Optional. A list of EmptyFlags that determines where monsters are allowed to be placed. If omitted, the default list is { EF_NOBEINGS, EF_NOBLOCK, EF_NOHARM, EF_NOSPAWN }.

reqs: Optional. See get_being_table for more info about this parameter.


roll_being(*ParamTable* args) → BeingID

Picks an ID for a being out of a list.

args: A table that looks for the following keys:

list: A table with BeingIDs as keys and the weight for the being as the value. If this key is supplied, all other keys are ignored.

These next 4 keys create a being list using get_being_table if the list parameter is omitted. The ID will be selected from the resulting weight table. It will not pick a group.

level: See the danger parameter for get_being_table.

weights: See the weights parameter for get_being_table.

diffmod: See the dmod parameter for get_being_table.

reqs: See the reqs parameter for get_being_table.


summon(BeingID id, integer [count])

Places a given number of a single being onto the map.

id: The ID of the being to place.

count: Optional. The number of that being to place. If omitted, only one being will be placed.


summon(*ParamTable* args)

Places a given number of a single being onto the map.

args: A table that looks for the following keys:

id: The ID of the being to place.

count: Optional. The number of that being to place. If omitted, only one being will be placed.

cell: Optional. A cell or set of cells that are valid locations for placement of the being(s). If omitted, the beings can be placed on any cell.

area: Optional. The area the beings can spawn in. If omitted, the area used is the entire map.

empty: Optional. A list of EmptyFlags that determines where monsters are allowed to be placed. If omitted, the default list is { EF_NOBEINGS, EF_NOBLOCK, EF_NOHARM, EF_NOSPAWN } if cell is omitted, and { EF_NOBEINGS, EF_NOBLOCK } if cell is supplied.

Item Level Functions


items() → table

Gets a table containing all of the items on the level.

Returns: A table containing all items on the level.


items_in_range(Coord where, integer range) → table

Gets a table containing all of the items within a certain distance of a location.

where: The location to search around.

range: The distance away from the location to search around.

Returns: A table containing all of the items within range of the location.


get_item(Coord where) → Item

Gets the item at a location.

where: The location to retrieve the item from.

Returns: A reference to the Item at the location.


drop_item(string what, Coord where, boolean [onfloor]) → Item

drop_item(Item what, Coord where, boolean [onfloor]) → Item

Places an item on the map.

what: The item to place. Either a string containing the ID of the item or a table representing an existing item.

where: The location to place the item. If occupied, the nearest available location will be chosen.

onfloor: Optional. If true, will apply the difficulty modifier to an ammo item that is placed. If false, the ammo item is placed with the given amount of ammo. If omitted, the default is false. This argument has no effect on non-ammo items.

Returns: A reference to the dropped item.


drop_item_ext(table item, Coord where)

drop_item_ext(string item, Coord where)

Places an item with modifications on the map.

what: The item to place. Either a string containing the ID of the item or a table with the ItemID string as it's first value, followed by a table containing entries in the form of "item_property" = new_value as the second value.

where: The location to place the item at. If occupied, the nearest available location will be chosen.


try_destroy_item(Coord where)

Attempts to destroy the item in a specified location. This function will not destroy the item if the item has the flag IF_NODESTROY or IF_UNIQUE. To guarantee destruction of an item, call the item's :destroy() method.

where: The location of the item to try to destroy.


get_item_table(integer [dlevel], table [weights], table [reqs]) → table

Gets a weight table for items, using the indicated criteria.

dlevel: Optional. The depth to pull the list of items for. If omitted, the value in level.danger_level is used.

weights: Optional. A table containing modifiers to weights. The keys of the table are ids, flags, or blueprint fields to look for. For example, "smed" will match Small Med-Packs. Suppling an item flag (such as IF_UNIQUE or IF_SHOTGUN, or an ITEMTYPE value) will look for that flag in the item prototype's flag list. Suppling a blueprint field will match all items that have that field in their blueprint table, provided that the value isn't nil, false, or 0. Each matched item will have its weight multiplied by the value supplied for that key. For example, "smed" = 2 will double the weight of Small Med-Packs, while "smed" = 0.5 will halve it. If an item matches multiple entries, all are applied. (For example, the table {IF_UNIQUE = 2, "uberarmor" = 2} will match Berserker Armor twice -- since both apply a double modifier to weight, Berserker Armor would have 4 times the weight.) If omitted, no modifications are made to weights.

reqs: Optional. A table containing requirements to check for. Only items that meet all of the requirements will be included in the resulting weight table. The keys of the table are blueprint fields that must be matched. The value for each key in the table is either a single value, which only items whose blueprint field key has the value supplied will match, or a table of values, which will match items that have one or more of the supplied values if the value of the blueprint field isn't a table itself, or all of the values if it is. For example, if the reqs table is { id = "smed" }, it will match Small Med-Packs (since its id is "smed"). If the reqs table has { id = {"smed", "lmed", "phase", "hphase" }, it will match Small Med-Packs, Large Med-Packs, Phase Devices, and Homing Phase Devices. If the reqs table has { flags = {IF_UNIQUE, IF_SHOTGUN} }, this will match all unique shotguns (since the flags blueprint field is a table itself). If omitted, no items are excluded (aside from those already excluded by other factors, such as the dlevel parameter).

NOTE: This function has a hidden limitation when trying to generate exotics and uniques. The function will not pick exotics if the danger_level of the level is less then the current difficulty (where ITYTD = 1 and N! = 5). The function will not pick uniques if the danger_level of the level is less than 3 more than the current difficulty (where ITYTD = 1 and N! = 5). If you need to generate exotics or uniques before the indicated danger_level, you can add the needed items to the resulting table yourself using the :add(<object>) method on the returned weight table object. Other functions that use this function (such as flood_items and roll_item) will also have this behavior.

Returns: A weight table object.


flood_items(integer amount)

Places several different items on the level, using the default criteria.

amount: The number of items to place on the level.


flood_items(*ParamTable* args)

Places several different items on the level, using specific criteria.

args: A table that looks for the following keys:

amount: The number of items to place on the level.

level, weights, reqs: All optional. See the get_item_table function for more info.


roll_item(*ParamTable* args)

Picks an item at random using specified criteria.

args: A table that looks for the following keys:

level: Optional. Sent to get_item_table as the dlevel parameter. Refer to get_item_table for more info.

type: Optional. A table containing one or more ITEMTYPE values. If supplied, only items that have one of the indicated types will be selected. If omitted, any item type can be picked.

weights: Optional. Sent to get_item_table as the weights parameter. Refer to get_item_table for more info.

reqs: Optional. Sent to get_item_table as the reqs parameter. Refer to get_item_table for more info.

unique_mod: Optional. A multiplier to the weights of all unique items. If omitted, 1 is used.

exotic_mod: Optional. A multiplier to the weights of all exotic items. If omitted, 1 is used.

special_mod: Optional. A multiplier to the weights of all exotic and unique items. Combines with unique_mod and exotic_mod. If omitted, 1 is used.

Returns: The ID of the rolled item.


drop(ItemID id, integer [count]) → Item

Places one or more of a specific item on the map.

id: The ID of the item to place.

count: Optional. The number of the item to place. If omitted, only 1 item will be placed.

Returns: A reference to the last item placed.


area_drop(Area where, ItemID id, integer [count], boolean [onfloor]) → Item

Places one or more of a specific item on the map in an area.

where: The area to confine the item drops to.

id: The Id of the item to place.

count: Optional. The number of the item to place. If omitted, only 1 item will be placed.

onfloor: Optional. If true, will apply the difficulty modifier to an ammo item that is placed. If false, the ammo item is placed with the given amount of ammo. If omitted, the default is false. This argument has no effect on non-ammo items.

Returns: A reference to the last item placed.

Miscellanous Functions


explosion(Coord where, integer size, integer delay, integer dice, integer sides, Color color, SoundID [sound_id], DamageType [type], ExplosionFlags [flags], CellID [content])

Creates an explosion on the map.

where: The location for the center of the explosion.

size: The size of the explosion. If greater than 8, the explosion will be visible in all cells, including cells that are not currently in the player's vision.

delay: The amount of time (in milliseconds) that each step of the explosion will take.

dice: The number of dice to use for the damage. Enter 0 to prevent the explosion from dealing damage (for decoration explosions).

sides: The number of sides for each die to use for the damage. Enter 0 to prevent the explosion from dealing damage (for decoration explosions).

color: Optional. The color of the explosion. Not all colors will show. If omitted, a RED explosion will be used.

sound_id: Optional. The ID of the sound to use for this explosion. If omitted, no sound is used.

type: Optional. The type of damage this explosion deals. If omitted, the default is DAMAGE_FIRE.

flags: Optional. A list of ExplosionFlags that will modify what the explosion applies to or how it applies. If omitted, no modifications are made to the explosion.

content: Optional. The cell to fill cells in the explosion area with if the explosion hits a cell for more than 20 damage. If omitted, cells will not changed.


flood(CellID tile, Area flood_area)

Replaces non-wall tiles in an area with a different tile.

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

flood_area: The area to fill.


is_corpse(Coord c) → boolean

Indicates if a coordinate has a corpse cell or not.

c: The location to check.

Returns: True if the coordinate is a corpse, False if it is not.


nuke()

Instantly nukes a level.


play_sound(SoundID sound_id, Coord where)

Plays a sound on the map.

sound_id: The id of the sound to play.

where: The location to play the sound at.


player(integer x, integer y)

Set the position of the player on the map.

x: The x coordinate of the position to move the player to.

y: The y coordinate of the position to move the player to.


push_cell(Coord c, Coord target, boolean [quiet])

Attempts to move a cell to a new location. (Swaps two cells.)

c: The source coordinate.

target: The destination coordinate.

quiet: Optional. If True, messages about success or failure as well as sounds that would play on success or failure are all suppressed. If False, sounds and messages will happen as it would normally. If omitted, the default is False.


recalc_fluids()

Recalculates fluid edges.


register_hook(hookname <any>, ) → string

Registers a hook with this object.

hookname: The name of the hook to register.

func: The function to assign to the hook.

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

From DoomRL Wiki

Revision as of 15:01, 24 May 2013

Contents

API

Table Parameters

Level API Function List

Level Object Functions

Level Property Functions

Cell Level Functions

Being Level Functions

Item Level Functions

Miscellanous Functions

Views

Personal tools

Navigation

Search

Toolbox

@@ Line 1: / Line 1: @@
-This page is pending.  The below is a dump from earlier versions.
+''This page is currently under construction.''
 == API ==
-{{drltable|Level Interface|2|{{Table2Col
-   |es=background: #333;
+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 types "Flag" and "Flags" expect a single [[Modding:Constants|flag constant]] of the indicated type, and a list of such flag constants, respectively.
+The argument type "any" means any lua type.
+An argument name in [square brackets] is an optional one.  The function description will indicate how the function operates if it is omitted.
+=== Table Parameters ===
+Some of the functions in the Level API take a parameter in a special table format.  Those functions have a parameter type of *ParamTable*.  When calling these functions, the keys of the table given as the argument must '''exactly''' match the names given, although they may appear in any order.  Details for which keys are looked for are provided in the function's description.  Additional keys specified in these tables will be ignored.
+=== Level 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 - Functions'''
+ {{Table2Col
+   |es=background: #333;
    |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px;
    |c2=padding:0px 2px;
-   |{{modarg|value}}|{{moddef|list|property_get|dot||string|property}}
+  ||'''[[#Level Object Functions|Level Object Functions]]'''
-   |{{modarg|void}}|{{moddef|list|property_set|dot|string|property|value|value}}
+   |{{modarg|string}}|{{moddef|list|get_id|col}}
-   |{{modarg|boolean}}|{{moddef|list|flag_get|dot||Level Flag|flag}}
+   |{{modarg|integer}}|{{moddef|list|get_uid|col}}
-   |{{modarg|void}}|{{moddef|list|flag_set|dot||Level Flag|flag|boolean|value}}
+   |{{modarg|string}}|{{moddef|list|get_type|col}}
-   |{{modarg|value}}|{{moddef|list|roll_weight|dot||list|list|integer|sum}}
+   |{{modarg|Area}}|{{moddef|list|get_area|col}}
-   |{{modarg|integer}}|{{moddef|list|weight_list_sum|dot||list|list}}
+   |{{modarg|object}}|{{moddef|list|get_parent|col}}
-   |{{modarg|void}}|{{moddef|list|place_tile|dot||table|translation|string|tile|integer|x|integer|y}}
+  |{{modarg|integer}}|{{moddef|list|get_child_count|col}}
-   |{{modarg|void}}|{{moddef|list|player|dot||integer|x|integer|y}}
+   |{{modarg|table}}|{{moddef|list|children|col||string|filter}}
-   |{{modarg|integer}}|{{moddef|list|result|dot||integer|value}}
+   |{{modarg|table}}|{{moddef|list|children_in_range|col||Coord|where|integer|range|string|filter}}
-   |{{modarg|boolean}}|{{moddef|list|eye_contact|dot||Coord|c1|Coord|c2}}
+   |{{modarg|void}}|{{moddef|list|destroy|col}}
-   |{{modarg|boolean}}|{{moddef|list|is_visible|dot||Coord|position}}
+  ||'''[[#Level Property Functions|Level Property Functions]]'''
-   |{{modarg|void}}|{{moddef|list|nuke|dot}}
+   |{{modarg|void}}|{{moddef|list|add_property|col||any|key|any|val}}
-   |{{modarg|void}}|{{moddef|list|explosion|dot||Coord|position|integer|radius|integer|delay|integer|damage_dice|integer|damage_sides|Color|color|Sound ID|sound|DamageType|damagetype|ExplosionFlag List|flags|Cell ID|content}}
+   |{{modarg|any}}|{{moddef|list|get_property|col||any|key}}
-   ||'''Cell-specific functions'''
+   |{{modarg|boolean}}|{{moddef|list|has_property|col||any|key}}
-   |{{modarg|boolean}}|{{moddef|list|light_flag_get|dot||Coord|position|LightFlag|flag}}
+   |{{modarg|void}}|{{moddef|list|remove_property|col||any|key}}
-   |{{modarg|void}}|{{moddef|list|light_flag_set|dot||Coord|position|LightFlag|flag|boolean|value}}
+   |{{modarg|void}}|{{moddef|list|set_property|col||any|key|any|value}}
-   |{{modarg|integer}}|{{moddef|list|hp_get|dot||Coord|position}}
+   ||'''[[#Cell Level Functions|Cell Level Functions]]'''
-   |{{modarg|void}}|{{moddef|list|hp_set|dot||Coord|position|integer|value}}
+   |{{modarg|CellID}}|{{moddef|list|get_cell|col||Coord|where}}
-   |{{modarg|boolean}}|{{moddef|list|is_corpse|dot||Coord|position}}
+   |{{modarg|integer}}|{{moddef|list|raw_get_cell|col||integer|x|integer|y}}
-   |{{modarg|boolean}}|{{moddef|list|scan|dot||Area|scan_area|Cell ID|good}}
+   |{{modarg|void}}|{{moddef|list|set_cell|col||Coord|where|CellID|what}}
-   |{{modarg|void}}|{{moddef|list|fill|dot||Cell ID|cell|Area|fill_area}}
+   |{{modarg|void}}|{{moddef|list|raw_set_cell|col||integer|x|integer|y|integer|what}}
-   |{{modarg|void}}|{{moddef|list|flood|dot||Cell ID|tile|Area|flood_area}}
+   |{{modarg|integer}}|{{moddef|list|get_hp|col||Coord|where}}
-   |{{modarg|void}}|{{moddef|list|scatter|dot||Area|scatter_area|Cell ID|good|Cell ID|fill|integer|count}}
+   |{{modarg|void}}|{{moddef|list|set_hp|col||Coord|where|integer|new_hp}}
-   |{{modarg|void}}|{{moddef|list|scatter_put|dot||Area|scatter_area|table|translation|string|tile|Cell ID|good|integer|count}}
+   |{{modarg|boolean}}|{{moddef|list|get_light_flag|col||Flag|what|Coord|[where]}}
-   |{{modarg|boolean}}|{{moddef|list|push_cell|dot||Coord|c|Coord|target|boolean|quiet}}
+   |{{modarg|void}}
-   ||'''Being-specific functions'''
+{{modarg|void}}|{{moddef|list|set_light_flag|col||Flag|what|boolean|[value]|Coord|[where]}}
-   |{{modarg|Being}}|{{moddef|list|get_being|dot||integer|index}}
+{{moddef|list|set_light_flag|col||Flag|what|boolean|[value]|Area|[where]}}
-   |{{modarg|Being}}|{{moddef|list|get_being_by_uid|dot||integer|uid}}
+   |{{modarg|boolean}}|{{moddef|list|is_visible|col||Coord|a}}
-   |{{modarg|Being}}|{{moddef|list|drop_being|dot||Being ID|bid|Coord|position}}
+   |{{modarg|boolean}}|{{moddef|list|eye_contact|col||Coord|a|Coord|b}}
-   |{{modarg|void}}|{{moddef|list|drop_being_ext|dot||table|being|Coord|position}}
+  |{{modarg|boolean}}|{{moddef|list|is_empty|col||Coord|where|Flags|reqs}}
-   |{{modarg|Being}}|{{moddef|list|summon|dot||Being ID|bid|integer|count}}
+   |{{modarg|boolean}}|{{moddef|list|is_empty_area|col||Area|where|Flags|reqs}}
-   |{{modarg|Being}}|{{moddef|list|area_summon|dot||Area|where|Being ID|bid|integer|count}}
+   ||'''[[#Being Level Functions|Being Level Functions]]'''
-   |{{modarg|void}}|{{moddef|list|clear_being|dot||Coord|position}}
+   |{{modarg|table}}|{{moddef|list|beings|col}}
-   |{{modarg|list}}, {{modarg|integer}}|{{moddef|list|get_being_list|dot}}
+  |{{modarg|table}}|{{moddef|list|beings_in_range|col||Coord|where|integer|range}}
-   |[[Modding:Being|Being ID]]|{{moddef|list|random_being|dot}}
+   |{{modarg|Being}}|{{moddef|list|get_being|col||Coord|where}}
-   |{{modarg|void}}|{{moddef|list|flood_monster|dot||Being ID|bid|integer|amount}}
+   |{{modarg|Being}}|{{moddef|list|drop_being|col||Being|what|Coord|where}}
-   |{{modarg|void}}|{{moddef|list|flood_monsters|dot||integer|amount}}
+   |{{modarg|void}}|{{moddef|list|drop_being_ext|col||Being|being|Coord|where}}
-   |{{modarg|Being iterator}}|{{moddef|list|beings|dot}}
+   |{{modarg|void}}|{{moddef|list|clear_being|col||Coord|where|boolean|silent}}
-   |{{modarg|Being iterator}}|{{moddef|list|beings_in_range|dot||Coord|position|integer|range}}
+   |{{modarg|table}}|{{moddef|list|get_being_table|col||integer|[danger]|table|[weights]|table|[reqs]|integer|[dmod]}}
-  ||'''Item-specific functions'''
+   |{{modarg|void}}|{{moddef|list|flood_monster|col||*ParamTable*|args}}
-   |{{modarg|Item}}|{{moddef|list|get_item|dot||integer|index}}
+   |{{modarg|void}}|{{moddef|list|flood_monsters|col||*ParamTable*|args}}
-   |{{modarg|Item}}|{{moddef|list|get_item_by_uid|dot||integer|uid}}
+  |{{modarg|BeingID}}|{{moddef|list|roll_being|col||*ParamTable*|args}}
-   |{{modarg|Item}}|{{moddef|list|drop_item|dot||Item ID|iid|Coord|position}}
+   |{{modarg|void}}|{{moddef|list|summon|col||BeingID|id|integer|[count]}}
-   |{{modarg|void}}|{{moddef|list|drop_item_ext|dot||table|item|Coord|position}}
+{{moddef|list|summon|col||*ParamTable*|args}}
-   |{{modarg|Item}}|{{moddef|list|drop|dot||Item ID|iid|integer|count}}
+  ||'''[[#Item Level Functions|Item Level Functions]]'''
-   |{{modarg|Item}}|{{moddef|list|area_drop|dot||Area|where|Item ID|iid|integer|count}}
+  |{{modarg|table}}|{{moddef|list|items|col}}
-   |{{modarg|void}}|{{moddef|list|try_destroy_item|dot||Coord|c}}
+   |{{modarg|table}}|{{moddef|list|items_in_range|col||Coord|where|integer|range}}
-   |{{modarg|list}}, {{modarg|integer}}|{{moddef|list|get_item_list|dot||integer|max_level|integer|unique_mult}}
+   |{{modarg|Item}}|{{moddef|list|get_item|col||Coord|where}}
-   |[[Modding:Item|Item ID]]|{{moddef|list|roll_item_type|dot||ItemType list|itypes|integer|max_level|integer|unique_mod}}
+   |{{modarg|Item}}|{{moddef|list|drop_item|col||string|what|Coord|where|boolean|[onfloor]}}
-   |[[Modding:Item|Item ID]]|{{moddef|list|roll_item|dot||integer|max_level|integer|unique_mod}}
+{{moddef|list|drop_item|col||table|what|Coord|where|boolean|[onfloor]}}
-   |{{modarg|void}}|{{moddef|list|flood_items|dot||integer|amount|}}
+   |{{modarg|void}}|{{moddef|list|drop_item_ext|col||table|item|Coord|where}}
-   |{{modarg|Item iterator}}|{{moddef|list|items|dot}}
+{{moddef|list|drop_item_ext|col||string|item|Coord|where}}
-   |{{modarg|Item iterator}}|{{moddef|list|items_in_range|dot||Coord|position|integer|range}}
+   |{{modarg|void}}|{{moddef|list|try_destroy_item|col||Coord|where}}
-   }}
+   |{{modarg|table}}|{{moddef|list|get_item_table|col||integer|[dlevel]|table|[weights]|table|[reqs]}}
-}}
+   |{{modarg|void}}|{{moddef|list|flood_items|col||integer|amount}}
+{{moddef|list|flood_items|col||*ParamTable*|args}}
-{{moddef|desc|property_get|dot|value|string|property}}
+   |{{modarg|ItemID}}|{{moddef|list|roll_item|col||*ParamTable*|args}}
-:Gets the value of the given level property. It is preferred to use the Lua dot indexing syntax instead.
+   |{{modarg|Item}}|{{moddef|list|drop|col||ItemID|id|integer|[count]}}
+   |{{modarg|Item}}|{{moddef|list|area_drop|col||Area|where|ItemID|id|integer|[count]|boolean|[onfloor]}}
+  ||'''[[#Miscellanous Functions|Miscellanous Functions]]'''
+   |{{modarg|void}}|{{moddef|list|explosion|col||Coord|where|integer|size|integer|delay|integer|dice|integer|sides|Color|color|SoundID|[sound_id]|DamageType|[type]|ExplosionFlags|[flags]|CellID|[content]}}
+   |{{modarg|void}}|{{moddef|list|flood|col||CellID|tile|Area|flood_area}}
+  |{{modarg|boolean}}|{{moddef|list|is_corpse|col||Coord|c}}
+   |{{modarg|void}}|{{moddef|list|nuke|col}}
+  |{{modarg|void}}|{{moddef|list|play_sound|col||SoundID|sound_id|Coord|where}}
+   |{{modarg|void}}|{{moddef|list|player|col||integer|x|integer|y}}
+   |{{modarg|boolean}}|{{moddef|list|push_cell|col||Coord|c|Coord|target|boolean|[quiet]}}
+   |{{modarg|void}}|{{moddef|list|recalc_fluids|col}}
+   |{{modarg|void}}|{{moddef|list|register_hook|col||string|hookname|any|func}}
+   |}}
+|}
+=== Level Object Functions ===
+;{{moddef|desc|get_id|col|string}}
+Gets the ID of the level.
+:'''Returns''': The string ID of the level.
+----
+;{{moddef|desc|get_uid|col|integer}}
+Gets the unique ID (UID) of the level.
+:'''Returns''': The numeric ID of the level.
+----
+;{{moddef|desc|get_type|col|string}}
+Gets the type of this object.
+:'''Returns''': The string "level".
+----
+;{{moddef|desc|get_area|col|Area}}
+Gets the level's entire area.
+:'''Returns''': An [[Modding:Area|Area]] object encompassing the entire map.
+----
+;{{moddef|desc|get_parent|col|object}}
+Gets the parent of this object.
+:'''Returns''': Nil.  Level has no parent object.
+----
+;{{moddef|desc|get_child_count|col|integer}}
+Gets the number of children this object is the parent of.  All beings and items on the level are children of the level object.
+:'''Returns''': Total number of beings and items on the map (being count will include the player).
+----
+;{{moddef|desc|children|col}}
+Gets a table containing each child object of level.  All beings and items on the level are children of the level object.
+:'''Returns''': A table of all beings and items on the map.
+----
+;{{moddef|desc|destroy|col}}
+Destroys the level object.  ''You should not call this in your lua script.''
+----
+=== Level Property Functions ===
+;{{moddef|desc|add_property|col||any|key|any|value}}
+Adds a user-defined property to the level object.
+:''key'': The value to refer to the property by.
+:''value'': The corresponding value of the property.
 ----
-{{moddef|desc|property_set|dot|string|property|value|value}}
+;{{moddef|desc|get_property|col|any|any|key}}
-:Sets the given level property to the given value. It is preferred to use the Lua dot indexing syntax instead.
+Retrieves the value of a user-defined property.
+:''key'': The property's key value, defined when it was added.
+:'''Returns''': The current value of the property.
 ----
-{{moddef|desc|flag_get|dot|boolean|Level Flag|flag}}
+;{{moddef|desc|has_property|col|boolean|any|key}}
-;Level.flags&#091;[[Modding:Constants#Level Flags|Level Flag]] flag] &rarr; '''boolean'''
+Checks to see if the given property exists.
-:Determines the current state of the given level flag.
+:''key'': The property key to check for.
+:'''Returns''': ''True'' if the property exists, ''False'' if it does not.
 ----
-{{moddef|desc|flag_set|dot||Level Flag|flag|boolean|value}}
+;{{moddef|desc|remove_property|col||any|key}}
-;Level.flags&#091;[[Modding:Constants#Level Flags|Level Flag]] flag] = '''boolean''' value
+Removes a property from the level object.
-:Sets the given level flag to the given value.
+:''key'': The key of the property to remove.
 ----
-{{moddef|desc|roll_weight|dot|value|list|list|integer|sum}}
+;{{moddef|desc|set_property|col||any|key|any|value}}
-:Randomly chooses an item from the list according to the weight property of the list items. Sum must be the sum of the weights of all the list items.
+Assigns a new value to an existing property.
+:''key'': The key of the property to change.
+:''value'': The new value to assign to the property.
 ----
-{{moddef|desc|weight_list_sum|dot|integer|list|list}}
+=== Cell Level Functions ===
-:Returns the sum of the weight properties of all the items in the list.
+;{{moddef|desc|get_cell|col|CellID|Coord|where}}
+Gets the cell at a specific map coordinate.
+:''where'': The location to get.
+:'''Returns''': The ID of the cell at the location.
 ----
-{{moddef|desc|place_tile|dot||table|translation|string|tile|integer|x|integer|y}}
+;{{moddef|desc|raw_get_cell|col|integer|integer|x|integer|y}}
-:Places the map tile given by ''translation'' and ''tile'' on the map at the position given by ''x'' and ''y''. ''translation'' should be a table that maps single character strings to either cell ids, or to tables. These tables have their first array element be a cell id, but they may also contain a being and''or'' item key that is mapped to a being or item id respectively. Level.drop_being_ext and Level.drop_item_ext syntax is allowed. ''tile'' should be a string of characters that are defined in ''translation''. Line breaks correspond to line breaks on the map.
+Gets the cell ID at a specific map coordinate.
+:''x'': The X position of the coordinate to get.
+:''y'': The Y position of the coordinate to get.
+:'''Returns''': The numeric ID of the cell at the coordinates.
 ----
-{{moddef|desc|player|dot||integer|x|integer|y}}
+;{{moddef|desc|set_cell|col||Coord|where|CellID|what}}
-:Sets the initial position of the player for a special or scripted level. This should be called in the Create hook; after that it has no meaningful effect.
+Assigns a new cell to a map coordinate.
+:''where'': The location to change.
+:''what'': The cell to assign to the location.
 ----
-{{moddef|desc|result|dot|integer|integer|value}}
+;{{moddef|desc|raw_set_cell|col||integer|x|integer|y|integer|what}}
-:If ''value'' is given, updates the level's status and returns nil. If ''value'' is omitted, returns the current status.
+Assigns a new cell to a map coordinate.
+:''x'': The X position of the location to change.
+:''y'': The Y position of the location to change.
+:''what'': The numeric ID of the cell to assign.
 ----
-{{moddef|desc|eye_contact|dot|boolean|Coord|c1|Coord|c2}}
+;{{moddef|desc|get_hp|col|integer|Coord|where}}
-:Determines whether or not there is a line-of-sight path between '''c1''' and '''c2'''. This calculation ignores light flags (such that two beings can have eye contact even if they aren't visible to each other).
+Gets the HP of the cell at the specified location.
+:''where'': The coordinate to get the HP amount from.
+:'''Returns''': The amount of HP the cell has.
 ----
-{{moddef|desc|is_visible|dot|boolean|Coord|position}}
+;{{moddef|desc|set_hp|col||Coord|where|integer|new_hp}}
-:Determines if the given position is visible to the player.
+Sets the HP of the cell at the specified location.
+:''where'': The coordinate to set.
+:''new_hp'': The new HP value to set for the coordinate.
 ----
-{{moddef|desc|nuke|dot}}
+;{{moddef|desc|get_light_flag|col|boolean|Flag|what|Coord|where}}
-:Triggers an immediate nuclear explosion as from a [[thermonuclear bomb]].
+Checks a cell for a certain light flag.
+:''what'': The LightFlag (named constant that starts with LF) to check for.  Refer to [[Modding:Constants#Light Flag|this]] for more info.
+:''where'': The location to check.
+:'''Returns''': ''True'' if the flag is set.  ''False'' if it is not.
 ----
-{{moddef|desc|explosion|dot||Coord|position|integer|radius|integer|delay|integer|damage_dice|integer|damage_sides|Color|color|Sound ID|sound|DamageType|damagetype|ExplosionFlag List|flags|Cell ID|content}}
+;{{moddef|desc|set_light_flag|col||Flag|what|boolean|[value]|Coord|[where]}}
-:Creates an [[explosions|explosion]] centered at the given position with the given parameters. ''radius'' is the size of the explosion. ''delay'' is the delay in milliseconds between animation frames (typically this is around 40). ''damage_dice'' and ''damage_sides'' determine the damage roll for the explosion. For a no-damage explosion, both should be 0. The default damage type is fire. ''content'' determines the cell that is randomly created wherever the explosion does enough damage. By default, there are no flags and there is no content. Only some colors are supported, and these are automatically translated into 3 color combinations used by the explosion animation. The supported colors are LIGHTBLUE, BLUE, MAGENTA, GREEN, LIGHTRED, YELLOW, and the default RED.
+;{{moddef|desc|set_light_flag|col||Flag|what|boolean|[value]|Area|[where]}}
+Sets or unsets a LightFlag at a specified location or specified locations.
+:''what'': The LightFlag (named constant that starts with LF) to check for.  Refer to [[Modding:Constants#Light Flag|this]] for more info.
+:''value'': ''Optional.'' ''True'' to set the flag, ''False'' to unset it.  If omitted, the default is to set the flag.
+:''where'': ''Optional.'' The coordinate or area to change.  If an area is supplied, all cells in the area will have the flag set or unset.  If omitted, the entire map will have the flag set or unset.
 ----
-{{moddef|desc|light_flag_get|dot|boolean|Coord|position|LightFlag|flag}}
+;{{moddef|desc|is_visible|col|boolean|Coord|a}}
-;Level.light&#091;[[Modding:Coord|Coord]] position]&#091;[[Modding:Constants#LightFlag|LightFlag]] flag] &rarr; '''boolean'''
+Determines if the player can see this space.
-:Gets the value of the given light flag at the given position.
+:''a'': The space to check.
+:'''Returns''': ''True'' if the player can see it, ''False'' if the player cannot.
 ----
-{{moddef|desc|light_flag_set|dot||Coord|position|LightFlag|flag|boolean|value}}
+;{{moddef|desc|eye_contact|col|boolean|Coord|a|Coord|b}}
-;Level.light&#091;[[Modding:Coord|Coord]] position]&#091;[[Modding:Constants#LightFlag|LightFlag]] flag] = '''boolean''' value
+Checks to see if two spaces can see each other.  This check uses the monster vision algorithm, which is stricter than the player's vision algorithm.
-;Level.light&#091;[[Modding:Constants#LightFlag|LightFlag]] flag] = '''boolean''' value
+:''a'': The first space to check.
-:Sets the value of the given light flag at the given position. For the syntax without a position, the light flag will be set at every position on the map.
+:''b'': The second space to check.
+:'''Returns''': ''True'' if the spaces are visible to each other, ''False'' if not.
 ----
-{{moddef|desc|hp_get|dot|integer|Coord|position}}
+;{{moddef|desc|is_empty|col|boolean|Coord|where|Flags|reqs}}
-;Level.hp&#091;[[Modding:Coord|Coord]] position] &rarr; '''integer'''
+Checks to see if the indicated cell is "empty", defining "empty" based on a list of criteria.
-:Gets the current hp of the cell at the given position.
+:''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|hp_set|dot||Coord|position|integer|value}}
+;{{moddef|desc|is_empty_area|col|boolean|Area|where|Flags|reqs}}
-;Level.hp&#091;[[Modding:Coord|Coord]] position] = '''integer''' value
+Checks to see if the indicated area is "empty", defining "empty" based on a list of criteria.
-:Sets the current hp of the cell at the given position. Setting hp to 0 won't destroy a cell.
+:''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|is_corpse|dot|boolean|Coord|position}}
+=== Being Level Functions ===
-:Determines whether the given position has a corpse in it. This counts the cell with id "corpse" as a corpse even though it otherwise isn't a corpse as far as the engine is concerned.
+;{{moddef|desc|beings|col|table}}
+Gets a table containing all of the beings on the level.
+:'''Returns''': A table containing all beings on the level.
 ----
-{{moddef|desc|scan|dot|boolean|Area|scan_area|Cell ID|good}}
+;{{moddef|desc|beings_in_range|col|table|Coord|where|integer|range}}
-:Determines if every cell in ''scan_area'' is ''good''.
+Gets a table containing all of the beings within a certain distance of a location.
+:''where'': The location to search around.
+:''range'': The distance away from the location to get beings from.
+:'''Returns''': A table containing the beings close enough to the location specified.
 ----
-{{moddef|desc|fill|dot||Cell ID|cell|Area|fill_area}}
+;{{moddef|desc|get_being|col|Being|Coord|where}}
-:Sets every cell in the given area to the area. ''fill_area'' is optional; it defaults to the full map.
+Gets the being at the specified coordinate.
+:''where'': The location to get the being from.
+:'''Returns''': The being at the location.
 ----
-{{moddef|desc|flood|dot||Cell ID|tile|Area|flood_area}}
+;{{moddef|desc|drop_being|col|Being|BeingID|what|Coord|where}}
-:Changes CELLSET_FLOORS and CF_LIQUID tiles in the area to ''tile''. If ''tile'' has CF_HAZARD, then it will destroy items.
+Places a being on the map.
+:''what'': The id of the being to place.
+:''where'': The location to attempt to drop the being.  If there is already a being at that location, the being will be dropped nearby.
+:'''Returns''': A reference to the being dropped.
 ----
-{{moddef|desc|scatter|dot||Area|scatter_area|Cell ID|good|Cell ID|fill|integer|count}}
+;{{moddef|desc|drop_being_ext|col||BeingID|being|Coord|where}}
-:Chooses ''count'' random tiles in ''scatter_area'' (possibly with duplicates) and sets any chosen cells that are ''good'' to ''fill''.
+Places a being on the map with modifications.
+:''being'': A BeingID, or a table whose first field is a BeingID, followed by the changes to the beings properties in the form ''field = new_value''.
+:''where'': The location to attempt to drop the being.  If there is already a being at that location, the being will be dropped nearby.
 ----
-{{moddef|desc|scatter_put|dot||Area|scatter_area|table|translation|string|tile|Cell ID|good|integer|count}}
+;{{moddef|desc|clear_being|col||Coord|where|boolean|silent}}
-:Chooses ''count'' random subareas with upper-left corner in ''scatter_area'' of the size appropriate of ''tile'' (using the first line length and number of lines to define a rectangular area). There may be duplicates or overlaps. For each subarea, if the area is already filled with ''good'', then it is replaced with ''tile'' (according to ''translation''). See Level.place_tile for the semantics of ''translation'' and ''tile''.
+Removes a being from the map.
+:''where'': The location to remove the being from.
+:''silent'': If ''true'', the being will be removed without making any sounds or causing any messages. If ''false'', the being will act as though they were killed (complete with message and sound).
 ----
-{{moddef|desc|push_cell|dot|boolean|Coord|c|Coord|target|boolean|quiet}}
+;{{moddef|desc|get_being_table|col|table|integer|[dlevel]|table|[weights]|table|[reqs]|integer|[dmod]}}
-:Swaps the content of the cells located in '''c''' and '''target''': this will only occur successfully if '''target''' is a part of CELLSET_FLOORS. If '''target''' has the CF_HAZARD flag, the cell on '''c''' activates its OnDestroy hook. '''quiet''', when set to true, includes messages (mostly specific to barrels, the only object pushed in the base game).
+Gets a weight table for beings and being groups, using the indicated criteria.
+:''dlevel'': ''Optional.'' The depth to pull the list of beings for. Only beings and groups that have an equal or smaller min_level and an equal or larger max_level will be selected. The ''dmod'' parameter also modifies which beings will be picked. If omitted, the current danger level (which is usually the current depth) is used.
+:''weights'': ''Optional.'' A table containing modifiers to weights. The keys of the table are ids, flags, or blueprint fields to look for. For example, "former" will match the being with the id "former" (that is, Former Humans). Suppling a being flag (such as BF_BOSS or BF_ENVIROSAFE) will look for that flag in the being prototype's flag list. Suppling a blueprint field will match all beings that have that field in their blueprint table, provided that the value of the field isn't ''nil'', ''false'', or 0. Each matched being will have its weight multiplied by the value supplied for that key. For example, <tt>"former" = 2</tt> will double the weight value of Former Humans, while <tt>"former" = 0.5</tt> will halve it. If a being matches multiple entries, all are applied. (for example, the table {BF_ENVIROSAFE = 2, "pain" = 2} will match Pain Elementals twice -- since both apply a double modifier to weight, Pain Elementals will now have 4 times the weight.) If omitted, no modifications are made to weights.
+:''reqs'': ''Optional.'' A table containing requirements to check for.  Only beings that meet all of the requirements will be included in the resulting weight table.  The keys of the table are blueprint fields that must be matched.  The value for each key in the table is either a single value, which only beings whose blueprint field key has the value supplied will match, or a table of values, which will match beings that have one or more of the supplied values if the value of the blueprint field isn't a table itself, or all of the values if it is.  For example, if the reqs table is <tt>{ id = "former" }</tt> , it will match Former Human (since its id is "former").  If the reqs table has <tt>{ id = {"former", "sergeant", "captain" } }</tt>, Former Human, Former Sergeant, and Former Captain will be matched. If the reqs table has <tt>{ flags = { BF_BOSS, BF_ENVIROSAFE } }</tt>, this will return all the beings with both the enviro-safe flag and the boss flag (since the flags blueprint field is a table itself).  If omitted, no beings or groups are excluded (aside from those already excluded by the dlevel and dmod parameters).
+:''dmod'': The current dlevel is adjusted by the value here for the min_level check.  This allows beings with a higher min_level to be selected on an earlier depth (if positive), or exclude beings with a higher min_level for extra levels (if negative).  In other words, this enables monsters to spawn "out of depth".  If omitted, the default is 3 if difficulty is medium (HMP), 6 if difficulty is hard or very hard (UV and N!), and 0 otherwise.
+:'''Returns''': A weight table object.
 ----
-{{moddef|desc|get_being|dot|Being|integer|index}}
+;{{moddef|desc|flood_monster|col||*ParamTable*|args}}
-:Returns the being at the given index in the sparse being array. A being's index won't change as long as it is in the array.
+Places one or more of a single type of monster on the level.
+:''args'': A table that looks for the following keys:
+::''id'': The ID of the being to place.
+::''danger'': The total amount of danger points worth of this monster to place.  This field is optional if ''count'' is set.  If both ''danger'' and ''count'' are set, the function will stop placing monsters when either ''danger'' or ''count'' is reached.
+::''count'': The number of monsters to place.  This field is optional if ''danger'' is set.  If both ''danger'' and ''count'' are set, the function will stop placing monsters when either ''danger'' or ''count'' is reached.
+::''flags'': ''Optional.'' A list of [[Modding:Constants#Empty_flags|EmptyFlags]] that determines where monsters are allowed to be placed.  If omitted, the default list is { EF_NOBEINGS, EF_NOBLOCK, EF_NOHARM, EF_NOSPAWN }.
 ----
-{{moddef|desc|get_being_by_uid|dot|Being|integer|uid}}
+;{{moddef|desc|flood_monsters|col||*ParamTable*|args}}
-:Returns the being with the given uid, or nil if that being doesn't exist or has been removed from the map.
+Places monsters on the level.
+:''args'': A table that looks for the following keys:
+::''danger'': The total amount of danger points worth of monsters to place.  This field is optional if ''amount'' is set.  If both ''danger'' and ''amount'' are set, the function will stop placing monsters when either ''danger'' or ''amount'' is reached.
+::''amount'': The number of monsters to place.  This field is optional if ''danger'' is set.  If both ''danger'' and ''amount'' are set, the function will stop placing monsters when either ''danger'' or ''amount'' is reached.
+::''flags'': ''Optional.'' A list of [[Modding:Constants#Empty_flags|EmptyFlags]] that determines where monsters are allowed to be placed.  If omitted, the default list is { EF_NOBEINGS, EF_NOBLOCK, EF_NOHARM, EF_NOSPAWN }.
+::''reqs'': ''Optional.'' See get_being_table for more info about this parameter.
 ----
-{{moddef|desc|drop_being|dot|Being|Being ID|bid|Coord|position}}
+;{{moddef|desc|roll_being|col|BeingID|*ParamTable*|args}}
-:Drops a newly created being in the given position. ''bid'' can also be an actual being object, although this should not be used for beings that are already on the map. If the position is occupied, the being will be dropped nearby. The dropped being is returned. If the function fails, nil is returned.
+Picks an ID for a being out of a list.
+:''args'': A table that looks for the following keys:
+::''list'': A table with BeingIDs as keys and the weight for the being as the value.  If this key is supplied, all other keys are ignored.
+:: These next 4 keys create a being list using ''get_being_table'' if the ''list'' parameter is omitted.  The ID will be selected from the resulting weight table.  It will not pick a group.
+::''level'': See the ''danger'' parameter for ''get_being_table''.
+::''weights'': See the ''weights'' parameter for ''get_being_table''.
+::''diffmod'': See the ''dmod'' parameter for ''get_being_table''.
+::''reqs'': See the ''reqs'' parameter for ''get_being_table''.
 ----
-{{moddef|desc|drop_being_ext|dot||table|being|Coord|position}}
+;{{moddef|desc|summon|col||BeingID|id|integer|[count]}}
-:As Level.drop_being, except additional values are accetable for ''being'' as Level.drop_item_ext.
+Places a given number of a single being onto the map.
+:''id'': The ID of the being to place.
+:''count'': ''Optional.'' The number of that being to place.  If omitted, only one being will be placed.
 ----
-{{moddef|desc|summon|dot|Being|Being ID|bid|integer|count}}
+;{{moddef|desc|summon|col||*ParamTable*|args}}
-:Creates new beings of the type given by ''bid'' and amount given by ''count'' and scatters them around the map. The last dropped being (if any) is returned. ''count'' is optional and defaults to 1.
+Places a given number of a single being onto the map.
+:''args'': A table that looks for the following keys:
+::''id'': The ID of the being to place.
+::''count'': ''Optional.'' The number of that being to place.  If omitted, only one being will be placed.
+::''cell'': ''Optional.'' A cell or set of cells that are valid locations for placement of the being(s).  If omitted, the beings can be placed on any cell.
+::''area'': ''Optional.'' The area the beings can spawn in.  If omitted, the area used is the entire map.
+::''empty'': ''Optional.'' A list of [[Modding:Constants#Empty_flags|EmptyFlags]] that determines where monsters are allowed to be placed.  If omitted, the default list is { EF_NOBEINGS, EF_NOBLOCK, EF_NOHARM, EF_NOSPAWN } if ''cell'' is omitted, and { EF_NOBEINGS, EF_NOBLOCK } if ''cell'' is supplied.
 ----
-{{moddef|desc|area_summon|dot|Being|Area|where|Being ID|bid|integer|count}}
+=== Item Level Functions ===
-:As Level.summon, but all the summoned beings are randomly placed in ''where'' rather than scattered across the whole map.
+;{{moddef|desc|items|col|table}}
+Gets a table containing all of the items on the level.
+:'''Returns''': A table containing all items on the level.
 ----
-{{moddef|desc|clear_being|dot||Coord|position}}
+;{{moddef|desc|items_in_range|col|table|Coord|where|integer|range}}
-{{moddef|desc|clear_being|dot||integer|index}}
+Gets a table containing all of the items within a certain distance of a location.
-:Removes an item from the map at the given position, or from the given index in the item array.
+:''where'': The location to search around.
+:''range'': The distance away from the location to search around.
+:'''Returns''': A table containing all of the items within range of the location.
 ----
-{{moddef|desc|get_being_list|dot|list,integer}}
+;{{moddef|desc|get_item|col|Item|Coord|where}}
-:Returns the list and sum (ready to be used with [[#level_roll_weight|Level.roll_weight]]) for beings and beings groups according to Level.danger_level and DIFFICULTY. The result is cached.
+Gets the item at a location.
+:''where'': The location to retrieve the item from.
+:'''Returns''': A reference to the Item at the location.
 ----
-{{moddef|desc|random_being|dot|Being ID}}
+;{{moddef|desc|drop_item|col|Item|string|what|Coord|where|boolean|[onfloor]}}
-:Returns a random being chosen according to weights from the current level's list. This will never choose a group. The returned id is always a string id.
+;{{moddef|desc|drop_item|col|Item|Item|what|Coord|where|boolean|[onfloor]}}
+Places an item on the map.
+:''what'': The item to place.  Either a string containing the ID of the item or a table representing an existing item.
+:''where'': The location to place the item.  If occupied, the nearest available location will be chosen.
+:''onfloor'': ''Optional.''  If true, will apply the difficulty modifier to an ammo item that is placed.  If false, the ammo item is placed with the given amount of ammo.  If omitted, the default is false.  This argument has no effect on non-ammo items.
+:'''Returns''': A reference to the dropped item.
 ----
-{{moddef|desc|flood_monster|dot||Being ID|bid|integer|amount}}
+;{{moddef|desc|drop_item_ext|col||table|item|Coord|where}}
-:Add the given monster type to the level in an amount specified by the total danger value ''amount'' (so it scales appropriately with Level.flood_monsters).
+;{{moddef|desc|drop_item_ext|col||string|item|Coord|where}}
+Places an item with modifications on the map.
+:''what'': The item to place.  Either a string containing the ID of the item or a table with the ItemID string as it's first value, followed by a table containing entries in the form of <tt>"item_property" = new_value</tt> as the second value.
+:''where'': The location to place the item at.  If occupied, the nearest available location will be chosen.
 ----
-{{moddef|desc|flood_monsters|dot||integer|amount}}
+;{{moddef|desc|try_destroy_item|col||Coord|where}}
-:Adds monsters to the level using the normal algorithm for random levels. The ''amount'' is a total danger value such as a value returned by Generator.being_weight.
+Attempts to destroy the item in a specified location.  This function will not destroy the item if the item has the flag IF_NODESTROY or IF_UNIQUE.  To guarantee destruction of an item, call the item's :destroy() method.
+:''where'': The location of the item to try to destroy.
 ----
-{{moddef|desc|beings|dot|Being iterator}}
+;{{moddef|desc|get_item_table|col|table|integer|[dlevel]|table|[weights]|table|[reqs]}}
-:Gives an iterator over all beings in the level.
+Gets a weight table for items, using the indicated criteria.
+:''dlevel'': ''Optional.'' The depth to pull the list of items for.  If omitted, the value in ''level.danger_level'' is used.
+:''weights'': ''Optional.'' A table containing modifiers to weights. The keys of the table are ids, flags, or blueprint fields to look for.  For example, "smed" will match Small Med-Packs.  Suppling an item flag (such as IF_UNIQUE or IF_SHOTGUN, or an ITEMTYPE value) will look for that flag in the item prototype's flag list.  Suppling a blueprint field will match all items that have that field in their blueprint table, provided that the value isn't ''nil'', ''false'', or 0.  Each matched item will have its weight multiplied by the value supplied for that key.  For example, <tt>"smed" = 2</tt> will double the weight of Small Med-Packs, while <tt>"smed" = 0.5</tt> will halve it.  If an item matches multiple entries, all are applied.  (For example, the table {IF_UNIQUE = 2, "uberarmor" = 2} will match Berserker Armor twice -- since both apply a double modifier to weight, Berserker Armor would have 4 times the weight.)  If omitted, no modifications are made to weights.
+:''reqs'': ''Optional.'' A table containing requirements to check for.  Only items that meet all of the requirements will be included in the resulting weight table.  The keys of the table are blueprint fields that must be matched.  The value for each key in the table is either a single value, which only items whose blueprint field key has the value supplied will match, or a table of values, which will match items that have one or more of the supplied values if the value of the blueprint field isn't a table itself, or all of the values if it is.  For example, if the reqs table is <tt>{ id = "smed" }</tt>, it will match Small Med-Packs (since its id is "smed").  If the reqs table has <tt>{ id = {"smed", "lmed", "phase", "hphase" }</tt>, it will match Small Med-Packs, Large Med-Packs, Phase Devices, and Homing Phase Devices.  If the reqs table has <tt>{ flags = {IF_UNIQUE, IF_SHOTGUN} }</tt>, this will match all unique shotguns (since the flags blueprint field is a table itself).  If omitted, no items are excluded (aside from those already excluded by other factors, such as the ''dlevel'' parameter).
+::NOTE: This function has a hidden limitation when trying to generate exotics and uniques.  The function will not pick exotics if the ''danger_level'' of the level is less then the current difficulty (where ITYTD = 1 and N! = 5).  The function will not pick uniques if the ''danger_level'' of the level is less than 3 more than the current difficulty (where ITYTD = 1 and N! = 5).  If you need to generate exotics or uniques before the indicated ''danger_level'', you can add the needed items to the resulting table yourself using the <tt>:add(<object>)</tt> method on the returned weight table object.  Other functions that use this function (such as ''flood_items'' and ''roll_item'') will also have this behavior.
+:'''Returns''': A weight table object.
 ----
-{{moddef|desc|beings_in_range|dot|Being iterator|Coord|position|integer|range}}
+;{{moddef|desc|flood_items|col||integer|amount}}
-:Gives an iterator over all beings within '''range''' units of [[distance]] from '''position''' in the level.
+Places several different items on the level, using the default criteria.
+:''amount'': The number of items to place on the level.
 ----
-{{moddef|desc|get_item|dot|Item|integer|index}}
+;{{moddef|desc|flood_items|col||*ParamTable*|args}}
-:Returns the item at the given index in the sparse item array. An item's index won't change as long as it is in the array.
+Places several different items on the level, using specific criteria.
+:''args'': A table that looks for the following keys:
+::''amount'': The number of items to place on the level.
+::''level'', ''weights'', ''reqs'': ''All optional.'' See the ''get_item_table'' function for more info.
 ----
-{{moddef|desc|get_item_by_uid|dot|Item|integer|uid}}
+;{{moddef|desc|roll_item|col||*ParamTable*|args}}
-:Returns the item with the given uid, or nil if that item doesn't exist or has been removed from the map.
+Picks an item at random using specified criteria.
+:''args'': A table that looks for the following keys:
+::''level'': ''Optional.'' Sent to ''get_item_table'' as the ''dlevel'' parameter.  Refer to ''get_item_table'' for more info.
+::''type'': ''Optional.'' A table containing one or more ITEMTYPE values.  If supplied, only items that have one of the indicated types will be selected.  If omitted, any item type can be picked.
+::''weights'': ''Optional.'' Sent to ''get_item_table'' as the ''weights'' parameter.  Refer to ''get_item_table'' for more info.
+::''reqs'': ''Optional.''  Sent to ''get_item_table'' as the ''reqs'' parameter.  Refer to ''get_item_table'' for more info.
+::''unique_mod'': ''Optional.''  A multiplier to the weights of all unique items.  If omitted, 1 is used.
+::''exotic_mod'': ''Optional.''  A multiplier to the weights of all exotic items.  If omitted, 1 is used.
+::''special_mod'': ''Optional.''  A multiplier to the weights of all exotic and unique items.  Combines with ''unique_mod'' and ''exotic_mod''.  If omitted, 1 is used.
+:'''Returns''': The ID of the rolled item.
 ----
-{{moddef|desc|drop_item|dot|Item|Item ID|iid|Coord|position}}
+;{{moddef|desc|drop|col|Item|ItemID|id|integer|[count]}}
-:Drops a newly created item in the given position. ''iid'' can also be an actual item object, although this should not be used for items that are already on the map. If the position is occupied, the item will be dropped nearby. The dropped item is returned. If the function fails, nil is returned.
+Places one or more of a specific item on the map.
+:''id'': The ID of the item to place.
+:''count'': ''Optional.'' The number of the item to place.  If omitted, only 1 item will be placed.
+:'''Returns''': A reference to the last item placed.
 ----
-{{moddef|desc|drop_item_ext|dot||table|item|Coord|position}}
+;{{moddef|desc|area_drop|col|Item|Area|where|ItemID|id|integer|[count]|boolean|[onfloor]}}
-:As Level.drop_item, except additional values are acceptable for ''item''. If ''item'' is a table, the first list element is passed used to determine which item to drop. For other key-value pairs in the table, the property of the dropped item that corresponds to the key will be set to the value.
+Places one or more of a specific item on the map in an area.
+:''where'': The area to confine the item drops to.
+:''id'': The Id of the item to place.
+:''count'': ''Optional.'' The number of the item to place.  If omitted, only 1 item will be placed.
+:''onfloor'': ''Optional.'' If true, will apply the difficulty modifier to an ammo item that is placed.  If false, the ammo item is placed with the given amount of ammo.  If omitted, the default is false.  This argument has no effect on non-ammo items.
+:'''Returns''': A reference to the last item placed.
+=== Miscellanous Functions ===
+;{{moddef|desc|explosion|col||Coord|where|integer|size|integer|delay|integer|dice|integer|sides|Color|color|SoundID|[sound_id]|DamageType|[type]|ExplosionFlags|[flags]|CellID|[content]}}
+Creates an explosion on the map.
+:''where'': The location for the center of the explosion.
+:''size'': The size of the explosion.  If greater than 8, the explosion will be visible in all cells, including cells that are not currently in the player's vision.
+:''delay'': The amount of time (in milliseconds) that each step of the explosion will take.
+:''dice'': The number of dice to use for the damage.  Enter 0 to prevent the explosion from dealing damage (for decoration explosions).
+:''sides'': The number of sides for each die to use for the damage.  Enter 0 to prevent the explosion from dealing damage (for decoration explosions).
+:''color'': ''Optional.'' The color of the explosion.  Not all colors will show.  If omitted, a RED explosion will be used.
+:''sound_id'': ''Optional.'' The ID of the sound to use for this explosion.  If omitted, no sound is used.
+:''type'': ''Optional.'' The type of damage this explosion deals.  If omitted, the default is DAMAGE_FIRE.
+:''flags'': ''Optional.'' A list of ExplosionFlags that will modify what the explosion applies to or how it applies.  If omitted, no modifications are made to the explosion.
+:''content'': ''Optional.'' The cell to fill cells in the explosion area with if the explosion hits a cell for more than 20 damage.  If omitted, cells will not changed.
 ----
-{{moddef|desc|drop|dot|Item|Item ID|iid|integer|count}}
+;{{moddef|desc|flood|col||CellID|tile|Area|flood_area}}
-:Creates new items of the type given by ''iid'' and amount given by ''count'' and scatters them around the map. The last dropped item (if any) is returned. ''count'' is optional and defaults to 1.
+Replaces non-wall tiles in an area with a different tile.
+:''tile'': The cell to fill with.  This does not have to be a fluid cell.
+:''flood_area'': The area to fill.
 ----
-{{moddef|desc|area_drop|dot|Item|Area|where|Item ID|iid|integer|count}}
+;{{moddef|desc|is_corpse|col|boolean|Coord|c}}
-:As Level.drop, but all dropped items are randomly placed in ''where'' rather than scattered across the whole map.
+Indicates if a coordinate has a corpse cell or not.
+:''c'': The location to check.
+:'''Returns''': ''True'' if the coordinate is a corpse, ''False'' if it is not.
 ----
-{{moddef|desc|try_destroy_item|dot||Coord|c}}
+;{{moddef|desc|nuke|col}}
-:Destroys an item at '''position''', if there is one to be found.
+Instantly nukes a level.
 ----
-{{moddef|desc|get_item_list|dot|list,integer|integer|max_level|integer|unique_mult}}
+;{{moddef|desc|play_sound|col||SoundID|sound_id|Coord|where}}
-:Returns the list and sum (ready to be used with [[#level_roll_weight|Level.roll_weight]]) for items according to ''max_level'', and ''unique_mult''. ''max_level'' defaults to Level.danger_level, and is used to determine which items fall in the proper level range. Unique items' weights are multiplied by ''unique_mult'' (which defaults to 1). The result is cached.
+Plays a sound on the map.
+:''sound_id'': The id of the sound to play.
+:''where'': The location to play the sound at.
 ----
-{{moddef|desc|roll_item_type|dot|Item ID|ItemType list|itypes|integer|max_level|integer|unique_mod}}
+;{{moddef|desc|player|col||integer|x|integer|y}}
-:Returns a random item chosen from among the given item types according to weights from the list specified by ''max_level'' and ''unique_mod''. The returned id is always a string id.
+Set the position of the player on the map.
+:''x'': The x coordinate of the position to move the player to.
+:''y'': The y coordinate of the position to move the player to.
 ----
-{{moddef|desc|roll_item|dot|Item ID|integer|max_level|integer|unique_mod}}
+;{{moddef|desc|push_cell|col||Coord|c|Coord|target|boolean|[quiet]}}
-:As Level.roll_item_type, but the item type of the result isn't restricted.
+Attempts to move a cell to a new location. (Swaps two cells.)
+:''c'': The source coordinate.
+:''target'': The destination coordinate.
+:''quiet'': ''Optional.'' If ''True'', messages about success or failure as well as sounds that would play on success or failure are all suppressed.  If ''False'', sounds and messages will happen as it would normally.  If omitted, the default is ''False''.
 ----
-{{moddef|desc|flood_items|dot||integer|amount|}}
+;{{moddef|desc|recalc_fluids|col}}
-:Adds items to the level according to the normal algorithm for random levels (not counting special features). The number of items is given by ''amount''.
+Recalculates fluid edges.
 ----
-{{moddef|desc|items|dot|Item iterator}}
+;{{moddef|desc|register_hook|col|string|hookname|<any>|func}}
-:Gives an iterator over all items in the level.
+Registers a hook with this object.
+:''hookname'': The name of the hook to register.
+:''func'': The function to assign to the hook.
 ----
-{{moddef|desc|items_in_range|dot|Item iterator|Coord|position|integer|range}}
-:Gives an iterator over all items within '''range''' units of [[distance]] from '''position''' in the level.