Modding:being API (0.9.9.7)

From DoomRL Wiki

(Redirected from Modding:being API)
Jump to: navigation, search

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.

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

The Thing API can also be used with beings.

Being API Function List

Being Interface
Being being.new(BeingID id)
void being:kill(boolean [overkill])
void being:ressurect(integer range)
void being:apply_damage(integer amount, BodyTarget target, DamageType [type])
void being:get_name(boolean [known], boolean [capitalize])
table being:inv_items()
Item being:get_eq_item(EquipSlot slot)
void being:set_eq_item(EquipSlot slot, Item item)
boolean being:add_inv_item(Item item)
void being:play_sound(SoundID sound)
integer being:get_total_resistance(ResistType resist, BodyTarget [target])
boolean being:quick_swap()
boolean being:pickup()
boolean being:unload(Item item)
boolean being:drop(Item item)
boolean being:use(Item item)
boolean being:wear(Item item)
boolean being:attack(Being target)
boolean being:attack(Coord target)
boolean being:fire(Coord target, Item weapon)
boolean being:alt_fire(Coord target, Item weapon)
boolean being:reload()
boolean being:alt_reload()
integer, Coord being:direct_seek(Coord dest)
void being:relocate(Coord dest)
boolean being:path_find(Coord dest, integer cutoff, integer maximum)
integer, Coord or boolean being:path_next()
Coord being:flock_target(integer range, integer mind, integer maxd)
void being:msg(string msg_player, string msg_being)
Item being:select_slot_by_letter(string letter)
void being:phase(CellID [cell])
void being:spawn(BeingID monster)
boolean being:act(Coord coord)
boolean being:eye_contact(Coord other)
boolean being:eye_contact(Thing other)
boolean being:in_sight(Coord other)
boolean being:in_sight(Thing other)
boolean being:is_player()
integer being:set_items(SetID set)
void being:nuke(integer [time])
Item, boolean being:pick_mod_item(string modletter, integer techbonus)

Being API Function Descriptions

being.new(BeingID id) → Being

Creates a new being object from the specified blueprint.

id: The ID of the being to create.
Returns: A reference to the new being object.
being:kill(boolean [overkill])

Kills the being.

overkill: Optional. If True, the being will be gibbed (extra blood, inventory will not drop, and a corpse will not be placed). If False the being will be killed normally. If omitted, the being will be killed normally.
being:ressurect(integer range)

Resurrects the nearest eligble corpse in sight of the calling being. Handles all message output.

range: The maximum distance (in terms of movement) that a corpse can be in order to be eligble for resurrection.

NOTE: The function name is a misspelling.

being:apply_damage(integer amount, BodyTarget target, DamageType [type])

Deals damage to the being.

amount: The amount of damage the attack does. This is not necessarily the amount of HP the being will lose; the being's resistance and armor may apply against this value.
target: One of TARGET_INTERNAL, TARGET_TORSO, or TARGET_FEET. TARGET_INTERNAL only uses the target's internal armor and resistances (equipment, for the most part, will be ignored). TARGET_TORSO uses the item in the armor slot to help reduce the damage, and TARGET_FEET uses the item in the boots slot to help reduce the damage.
DamageType: Optional. One of the named constants starting with "DAMAGE_". Indicates the type of damage being dealt, which influences the properties and effects the damage has on the target. If omitted, DAMAGE_BULLET will be used.
being:get_name(boolean [known], boolean [capitalize])

Returns the name of the being, with the appropriate preposition.

known: Optional. If true, the being will not use an article (a, an, or the) when getting the name string. If false, an article (a, an, or the) will be appended to the front of the name. If omitted, the default is to use an article. BF_UNIQUENAME determines when "the" is used instead of "a" or "an".
capitalize: Optional. If true, the name of the being will be capitalized. If false, it will not be adjusted. If omitted, the default is to not adjust.
being:inv_items() → table

Gets an iterator over the items in the being's inventory.

Returns: A table containing references to each item in the being's inventory.
being:get_eq_item(EquipSlot slot) → Item

Retrieves the item in the indicated equipment slot. Equivalent to "being.eq.slotname", where slotname is "weapon", "armor", "boots", or "prepared".

slot: One of SLOT_WEAPON, SLOT_ARMOR, SLOT_BOOTS, or SLOT_PREPARED.
Returns: A reference to the item equipped in the indicated slot.
being:set_eq_item(EquipSlot slot, Item item)

Equips an item to the being. Equivalent to "being.eq.slotname = item", where slotname is "weapon", "armor", "boots", or "prepared".

slot: One of SLOT_WEAPON, SLOT_ARMOR, SLOT_BOOTS, or SLOT_PREPARED.
item: The item to equip to the slot. If there is a different item in the slot already, it will be destroyed. If nil, the equipped item is destroyed.
being:add_inv_item(Item item)

Adds an item to the being's inventory.

item: The item to add.
Returns: True if the item was added. False if the being's inventory is full.
being:play_sound(SoundID sound)

Plays a sound at the being's location.

sound: The sound to play.
being:get_total_resistance(ResistType resist, BodyTarget [target]) → integer

Gets the total resistance for being, given the resistance type and target.

resist: The resistance to get the value for.
target: Optional. One of TARGET_INTERNAL, TARGET_TORSO, or TARGET_FEET. TARGET_INTERNAL only uses the target's internal resistance (equipment, for the most part, will be ignored). TARGET_TORSO uses the item in the armor slot to calculate resistance, and TARGET_FEET uses the item in the boots slot to calculate resistance. If omitted, TARGET_TORSO is used.
being:quick_swap() → boolean

Switches the weapon in the "weapon" slot with the one in the "prepared" slot. Expends energy on success.

Returns: True if the swap worked. False if it failed.
being:pickup() → boolean

Attempts to pickup the item at the being's current location. Expends energy on success.

Returns: True if the pickup succeeded, False if it failed.
being:unload(Item item) → boolean

Attempts to unload the indicated item. Expends energy on success.

item: The item to try to unload.
Returns: True if the unloading succeeded, False if it failed.
being:drop(Item item) → boolean

Attempts to drop an item. Expends energy on success.

item: The item to try to drop.
Returns: True if the drop succeeded, False if it failed.
being:use(Item item) → boolean

Attempts to use an item. Expends energy on success.

item: The item to try to use.
Returns: True if the use succeeded. False if it failed.
being:wear(Item item) → boolean

Attempts to equip an item. Expends energy on success.

item: The item to try to wear.
Returns: True if the item was worn. False if the command failed.
being:attack(Being target) → boolean
being:attack(Coord target) → boolean

Attempts to attack something. Expends energy on success.

target: A being or a location to attack.
Returns: True if the attack was attempted. False if the being couldn't attack.
being:fire(Coord target, Item weapon) → boolean

Attempts to fire a weapon at something. Expends energy on success.

target: The location to fire at.
weapon: The item to fire at the location with.
Returns: True if the weapon was fired. False if it failed.
being:alt_fire(Coord target, Item weapon) → boolean

Attempts to fire a weapon using its alternate fire mode.

target: The location to fire at.
weapon: The item to fire at the location with.
Returns: True if the weapon was fired. False if it failed.
being:reload() → boolean

Attempts to reload the equipped weapon.

Returns: True if the weapon was loaded with at least 1 ammo. False if the weapon didn't get any ammo put in it at all.
being:alt_reload() → boolean

Attemptes to reload the equipped weapon using its alternate reload.

Returns: True if the weapon was loaded with at least 1 ammo. False if the weapon didn't get any ammo put in it at all.
being:direct_seek(Coord dest) → integer, Coord

Attempts to move directly toward a location. Expends energy only on a successful move. The being will try moving around objects in its way. It will only move at most 1 space for each time this is called.

dest: The location to attempt to move toward.
Returns: An integer, representing the result of the move, and a Coord, holding the previous location of the being. The integer can be 0 (MOVEOK), 1 (MOVEBLOCK), 2 (MOVEDOOR), or 3 (MOVEBEING). 0 means the move was successful, and energy was expended. 1 means there was a wall in the way. 2 means there was door or other CF_OPENABLE cell in the way. 3 means a being was in the way.
being:relocate(Coord dest)

Moves the being to the indicated location, with animations.

dest: The location to move the being to.
being:path_find(Coord dest, integer cutoff, integer maximum) → boolean

Search for a path to the indicated location. Pathfinding is a time intensive procedure, use conservatively.

dest: The location to find a path to.
cutoff: A path finding parameter. The search is aborted if this number of positions are checked without getting closer to the target destination. DoomRL uses 10 for normal enemies and 40 for bosses. Larger values may cause the algorithm to take longer.
maximum: A path finding parameter. The search is aborted if this number of positions are checked without reaching the target. DoomRL uses 40 for normal enemies and 200 for bosses. Larger values may cause the algorithm to take longer.
Returns: True if a path was found, False if not.
being:path_next() → integer, Coord or boolean

Moves the being to the next space on the found path.

Returns: If there is a valid path, an integer, representing the result of the move, and a Coord, holding the previous location of the being, are returned. The integer can be 0 (MOVEOK), 1 (MOVEBLOCK), 2 (MOVEDOOR), or 3 (MOVEBEING). 0 means the move was successful, and energy was expended. 1 means there was a wall in the way. 2 means there was door or other CF_OPENABLE cell in the way. 3 means a being was in the way. If there was no valid path to move along, the boolean value False is returned instead.
being:flock_target(integer range, integer mind, integer maxd) → Coord

Assigns a coord based on other beings of the same type.

range: The distance to check.
mind: Matching beings will try to keep this much distance between them.
maxd: Matching beings will try to be at least this close to each other.
Returns: A coordinate. If the beings are mind away or closer, the coordinate will be away from the closest matching being. If the beings are maxd away or farther, the coordinate will be the location of the closest being. Otherwise, the coordinate is a random position within range.
being:msg(string msg_player, string msg_being)

Prints a message depending on the status of the subject of the message.

msg_player: Optional. If the calling being is the player, this message will be printed. If omitted, no message is printed if called by the player.
msg_being: Optional. If the calling being is not the player, but is in the player's vision, this message will be printed. If omitted, no message is printed if called by a visible non-player being.
being:select_slot_by_letter(string letter) → Item

Gets the slot based on the character entered.

letter: A single character string.
Returns: If letter is "a", the item in the armor slot is returned. If letter is "b", the item in the boots slot is returned. If letter is "w", the item in the weapon slot is returned. If letter is "p", the item in the prepared slot is returned. Otherwise, nil is returned.
being:phase(CellID [cell])

Teleports the being to a new cell.

cell: Optional. A cell id to search for. If multiple cells of that id are on the level, one is picked at random. If omitted, any cell empty of beings, items, stairs, walls, hazardous terrain, or LFNOSPAWN can be selected.
being:spawn(BeingID monster)

Summons monsters around this being. Monsters summoned this way grant no experience to the player (that is, BF_NOEXP is set on the spawned beings).

monster: The ID of the being to spawn.
being:act(Coord coord) → boolean

Makes the being interact with the indicated location.

coord: The location to interact with.
Returns: True if the action was successful, False if not.
being:eye_contact(Coord other) → boolean
being:eye_contact(Thing other) → boolean

Checks if something is visible from this being's location.

other: A Coord, Being, or Item whose position will be checked.
Returns: True if the being can see the checked object or location, False if not.
being:in_sight(Coord other) → boolean
being:in_sight(Thing other) → boolean

Checks to see if something can be from the being's location. If the being is the player, the player's vision algorithm is used. Otherwise, the being's eye_contact algorithm is used.

other: A Coord, Being, or Item whose position will be checked.
Returns: True if the object is visible, False if not.
being:is_player() → boolean

Returns whether this being is the player or not.

Returns: True if this being is the player. False if it is not.
being:set_items(SetID set) → integer

Gets the number of items worn by the being that are part of a set.

set: The set to check.
Returns: The number of items of that set worn by this being.
being:nuke(integer [time])

Creates a nuke under the being and sets the nuke timer.

time: Optional. The number of game turns the the nuke will go off in. If omitted, the default is 1.
being:pick_mod_item(string modletter, integer techbonus) → Item, boolean

Performs the choice, check, and attachment of a mod to an item. Only the player can call this function.

modletter: The letter representing the mod being attached. Standard DoomRL mod letters are: 
 Agility: A     Tech:      T      Bulk: B     Power: P
 Sniper:  S     Firestorm: F      Nano: N     Onyx:  O

Custom modpacks should use different letters.

techbonus: The number of points of tech bonus the being has. DoomRL uses the Whizkid level for this number.
Returns: An Item and a boolean. The Item returned is the resulting item after being modded with the mod pack, unless an assembly (mod array) was matched and accepted. The boolean value is True if the modding was successful or False if it was not. If the boolean value is False or the Item was turned into an assembly, Nil is returned instead of the item.
Retrieved from "https://drl.chaosforge.org/w/index.php?title=Modding:being_API_(0.9.9.7)&oldid=2638"
Personal tools