Modding:level API (0.9.9.7)

From DoomRL Wiki

Revision as of 15:01, 24 May 2013 by Shark20061 (Talk | contribs)

Jump to: navigation, search

This page is currently under construction.

Contents

API

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

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

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

The argument 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.
Retrieved from "https://drl.chaosforge.org/w/index.php?title=Modding:level_API_(0.9.9.7)&oldid=2561"
Personal tools