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

From DoomRL Wiki

Jump to: navigation, search
(Created page with "WIP pulled from 096 still investigating ------- == API == The Thing API can also be used with beings. {|class="wikitable" style="border: 2px solid ...")
 
m (being:alt_fire)
 
(One intermediate revision by one user not shown)
Line 1: Line 1:
WIP pulled from 096 still investigating
+
''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.
  
 
 
 
== API ==
 
 
The [[Modding:Thing#API|Thing API]] can also be used with beings.
 
The [[Modding:Thing#API|Thing API]] can also be used with beings.
 +
 +
=== Being API Function List ===
  
 
{|class="wikitable" style="border: 2px solid darkred; border-spacing: 0; font-size: 90%; margin: 0.25em 0.5em;"
 
{|class="wikitable" style="border: 2px solid darkred; border-spacing: 0; font-size: 90%; margin: 0.25em 0.5em;"
Line 17: Line 17:
 
   |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px;
 
   |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px;
 
   |c2=padding:0px 2px;
 
   |c2=padding:0px 2px;
   |[[Modding:Being|Being]]|being.[[#being_new|new]]([[Modding:Being|Being ID]] id)
+
   |{{modarg|Being}}|{{moddef|list|new|dot||BeingID|id}}
   |'''void'''|[[Modding:Being|Being]]:[[#being_destroy|destroy]]('''boolean''' silent)
+
   |{{modarg|void}}|{{moddef|list|kill|cln||boolean|[overkill]}}
  |'''void'''|[[Modding:Being|Being]]:[[#being_kill|kill]]('''boolean''' overkill)
+
   |{{modarg|void}}|{{moddef|list|ressurect|cln||integer|range}}
   |'''void'''|[[Modding:Being|Being]]:[[#being_ressurect|ressurect]]('''integer''' rrange)
+
   |{{modarg|void}}|{{moddef|list|apply_damage|cln||integer|amount|BodyTarget|target|DamageType|[type]}}
   |'''void'''|[[Modding:Being|Being]]:[[#being_apply_damage|apply_damage]]('''integer''' damage, [[Modding:Constants#BodyTarget|BodyTarget]] target, [[Modding:Constants#DamageType|DamageType]] damageType)
+
   |{{modarg|void}}|{{moddef|list|get_name|cln||boolean|[known]|boolean|[capitalize]}}
   |'''string'''|[[Modding:Being|Being]]:[[#being_get_name|get_name]]('''boolean''' known, '''boolean''' capitalized)
+
   |{{modarg|table}}|{{moddef|list|inv_items|cln}}
  |[[Modding:Item|Item]]|[[Modding:Being|Being]]:[[#being_get_inv_item|get_inv_item]]('''integer''' slot)
+
   |{{modarg|Item}}|{{moddef|list|get_eq_item|cln||EquipSlot|slot}}
   |'''void'''|[[Modding:Being|Being]]:[[#being_set_inv_item|set_inv_item]]('''integer''' slot, [[Modding:Item|Item]] item)
+
   |{{modarg|void}}|{{moddef|list|set_eq_item|cln||EquipSlot|slot|Item|item}}
   |[[Modding:Item|Item]]|[[Modding:Being|Being]]:[[#being_get_eq_item|get_eq_item]]([[Modding:Constants#Equip Slots|Equip Slot]] slot)
+
  |{{modarg|boolean}}|{{moddef|list|add_inv_item|cln||Item|item}}
   |'''void'''|[[Modding:Being|Being]]:[[#being_set_eq_item|set_eq_item]]([[Modding:Constants#Equip Slots|Equip Slot]] slot, [[Modding:Item|Item]] item)
+
   |{{modarg|void}}|{{moddef|list|play_sound|cln||SoundID|sound}}
   |'''void'''|[[Modding:Being|Being]]:[[#being_play_sound|play_sound]]('''Sound ID''' sound)
+
   |{{modarg|integer}}|{{moddef|list|get_total_resistance|cln||ResistType|resist|BodyTarget|[target]}}
   |'''integer'''|[[Modding:Being|Being]]:[[#being_get_total_resistance|get_total_resistance]]([[Modding:Constants#Resistance|Resistance]] resistance, [[Modding:Constants#BodyTarget|BodyTarget]] target)
+
   |{{modarg|boolean}}|{{moddef|list|quick_swap|cln}}
   |'''boolean'''|[[Modding:Being|Being]]:[[#being_use|use]]('''integer''' slot)
+
  |{{modarg|boolean}}|{{moddef|list|pickup|cln}}
   |'''boolean'''|[[Modding:Being|Being]]:[[#being_wear|wear]]('''integer''' slot)
+
  |{{modarg|boolean}}|{{moddef|list|unload|cln||Item|item}}
   |'''boolean'''|[[Modding:Being|Being]]:[[#being_pickup|pickup]]([[Modding:Coord|Coord]] pos)
+
  |{{modarg|boolean}}|{{moddef|list|drop|cln||Item|item}}
   |'''void'''|[[Modding:Being|Being]]:[[#being_attack|attack]]([[Modding:Coord|Coord]] or [[Modding:Being|Being]] target)
+
  |{{modarg|boolean}}|{{moddef|list|use|cln||Item|item}}
   |'''void'''|[[Modding:Being|Being]]:[[#being_fire|fire]]([[Modding:Coord|Coord]] target, [[Modding:Item|Item]] weapon)
+
   |{{modarg|boolean}}|{{moddef|list|wear|cln||Item|item}}
   |'''boolean'''|[[Modding:Being|Being]]:[[#being_reload|reload]]()
+
   |{{modarg|boolean}}|{{moddef|list|attack|cln||Being|target}}
   |'''integer'''|[[Modding:Being|Being]]:[[#being_direct_seek|direct_seek]]([[Modding:Coord|Coord]] target)
+
   |{{modarg|boolean}}|{{moddef|list|attack|cln||Coord|target}}
   |'''boolean'''|[[Modding:Being|Being]]:[[#being_path_find|path_find]]([[Modding:Coord|Coord]] target, '''integer''' cutoff, '''integer''' maximum)
+
   |{{modarg|boolean}}|{{moddef|list|fire|cln||Coord|target|Item|weapon}}
   |'''integer'''|[[Modding:Being|Being]]:[[#being_path_next|path_next]]()
+
  |{{modarg|boolean}}|{{moddef|list|alt_fire|cln||Coord|target|Item|weapon}}
   |[[Modding:Coord|Coord]]|[[Modding:Being|Being]]:[[#being_flock_target|flock_target]]('''integer''' range, '''integer''' mind, '''integer''' maxd)
+
   |{{modarg|boolean}}|{{moddef|list|reload|cln}}
   |'''void'''|[[Modding:Being|Being]]:[[#being_msg|msg]]('''string''' msg_player, '''string''' msg_being)
+
   |{{modarg|boolean}}|{{moddef|list|alt_reload|cln}}
   |[[Modding:Item|Item]]|[[Modding:Being|Being]]:[[#being_select_slot_by_letter|select_slot_by_letter]]('''string''' letter)
+
  |{{modarg|integer}}, {{modarg|Coord}}|{{moddef|list|direct_seek|cln||Coord|dest}}
   |'''void'''|[[Modding:Being|Being]]:[[#being_phase|phase]]([[Modding:Cell|Cell ID]] cell)
+
  |{{modarg|void}}|{{moddef|list|relocate|cln||Coord|dest}}
   |'''void'''|[[Modding:Being|Being]]:[[#being_spawn|spawn]]([[Modding:Being|Being ID]] being)
+
   |{{modarg|boolean}}|{{moddef|list|path_find|cln||Coord|dest|integer|cutoff|integer|maximum}}
   |'''boolean'''|[[Modding:Being|Being]]:[[#being_is_visible|is_visible]]()
+
   |{{modarg|integer}}, {{modarg|Coord}} or {{modarg|boolean}}|{{moddef|list|path_next|cln}}
   |'''boolean'''|[[Modding:Being|Being]]:[[#being_is_player|is_player]]()
+
   |{{modarg|Coord}}|{{moddef|list|flock_target|cln||integer|range|integer|mind|integer|maxd}}
   |'''integer'''|[[Modding:Being|Being]]:[[#being_set_items|set_items]]([[Modding:ItemSet|ItemSet]] set)
+
   |{{modarg|void}}|{{moddef|list|msg|cln||string|msg_player|string|msg_being}}
   |'''void'''|[[Modding:Being|Being]]:[[#being_nuke|nuke]]('''integer''' time)
+
   |{{modarg|Item}}|{{moddef|list|select_slot_by_letter|cln||string|letter}}
   |[[Modding:Item|Item]], '''boolean'''|[[Modding:Being|Being]]:[[#being_pick_mod_item|pick_mod_item]]('''string''' modletter, '''integer''' techbonus)
+
   |{{modarg|void}}|{{moddef|list|phase|cln||CellID|[cell]}}
 +
   |{{modarg|void}}|{{moddef|list|spawn|cln||BeingID|monster}}
 +
   |{{modarg|boolean}}|{{moddef|list|act|cln||Coord|coord}}
 +
   |{{modarg|boolean}}|{{moddef|list|eye_contact|cln||Coord|other}}
 +
  |{{modarg|boolean}}|{{moddef|list|eye_contact|cln||Thing|other}}
 +
  |{{modarg|boolean}}|{{moddef|list|in_sight|cln||Coord|other}}
 +
  |{{modarg|boolean}}|{{moddef|list|in_sight|cln||Thing|other}}
 +
  |{{modarg|boolean}}|{{moddef|list|is_player|cln}}
 +
   |{{modarg|integer}}|{{moddef|list|set_items|cln||SetID|set}}
 +
   |{{modarg|void}}|{{moddef|list|nuke|cln||integer|[time]}}
 +
   |{{modarg|Item}}, {{modarg|boolean}}|{{moddef|list|pick_mod_item|cln||string|modletter|integer|techbonus}}
 
   |}}
 
   |}}
 
|}
 
|}
  
{{Anchor|being_new}}
+
=== Being API Function Descriptions ===
;being.new([[Modding:Being|Being ID]] id) → [[Modding:Being|Being]]
+
;{{moddef|desc|new|dot|Being|BeingID|id}}
:This creates a newly allocated being of the appropriate type. The being won't exist on the map until it is placed by e.g. Level.drop_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.
 +
----
 +
;{{moddef|desc|kill|cln||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.
 +
----
 +
;{{moddef|desc|ressurect|cln||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.
 +
----
 +
;{{moddef|desc|apply_damage|cln||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.
 +
----
 +
;{{moddef|desc|get_name|cln||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.
 +
----
 +
;{{moddef|desc|inv_items|cln|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.
 +
----
 +
;{{moddef|desc|get_eq_item|cln|Item|EquipSlot|slot}}
 +
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.
 +
----
 +
;{{moddef|desc|set_eq_item|cln||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.
 +
----
 +
;{{moddef|desc|add_inv_item|cln||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.
 
----
 
----
{{Anchor|being_destroy}}
+
;{{moddef|desc|play_sound|cln||SoundID|sound}}
;[[Modding:Being|Being]]:destroy('''boolean''' silent)
+
Plays a sound at the being's location.
:Deallocates the memory associated with the being and removes it from the level (if applicable). The normal results of killing a being (e.g. leaving a corpse) are ignored. The ''silent'' parameter is optional. If true, applicable OnKill and OnKillAll hooks and events will also be ignored.
+
:''sound'': The sound to play.
 
----
 
----
{{Anchor|being_kill}}
+
;{{moddef|desc|get_total_resistance|cln|integer|ResistType|resist|BodyTarget|[target]}}
;[[Modding:Being|Being]]:kill('''boolean''' overkill)
+
Gets the total resistance for being, given the resistance type and target.
:Kills the being. If the optional ''overkill'' parameter is true, then the being will be gibbed.
+
:''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.
 
----
 
----
{{Anchor|being_ressurect}}
+
;{{moddef|desc|quick_swap|cln|boolean}}
;[[Modding:Being|Being]]:ressurect('''integer''' rrange)
+
Switches the weapon in the "weapon" slot with the one in the "prepared" slot.  Expends energy on success.
:Resurrects a single corpse that is found within a square of side-length 2 × ''rrange'' + 1, centered around the being. Nearer corpses are preferred. The corpse must not have another being standing on it and must be within sight of the being (as determined by the enemy line-of-sight algorithm). The resurrected being (if any) will have BF_NOEXP set. Messages are included.
+
:'''Returns''': ''True'' if the swap worked. ''False'' if it failed.
 
----
 
----
{{Anchor|being_apply_damage}}
+
;{{moddef|desc|pickup|cln|boolean}}
;[[Modding:Being|Being]]:apply_damage('''integer''' damage, [[Modding:Constants#BodyTarget|BodyTarget]] target, [[Modding:Constants#DamageType|DamageType]] damageType)
+
Attempts to pickup the item at the being's current location.  Expends energy on success.
:Deals damage to the being using the given body target and damage type. (The default damage type is bullet damage.)
+
:'''Returns''': ''True'' if the pickup succeeded, ''False'' if it failed.
 
----
 
----
{{Anchor|being_get_name}}
+
;{{moddef|desc|unload|cln|boolean|Item|item}}
;[[Modding:Being|Being]]:get_name('''boolean''' known, '''boolean''' capitalized) → '''string'''
+
Attempts to unload the indicated item.  Expends energy on success.
:Returns the name of the being. If ''known'' is true, "the" is added, otherwise "a" or "an" is added. If BF_UNIQUENAME is set for the being, then no article is used in either case. If ''capitalized'' is true, then the first letter will be capitalized.
+
:''item'': The item to try to unload.
 +
:'''Returns''': ''True'' if the unloading succeeded, ''False'' if it failed.
 
----
 
----
{{Anchor|being_get_inv_item}}
+
;{{moddef|desc|drop|cln|boolean|Item|item}}
;[[Modding:Being|Being]]:get_inv_item('''integer''' slot) → [[Modding:Item|Item]]
+
Attempts to drop an item.  Expends energy on success.
;[[Modding:Being|Being]].inv['''integer''' slot] → [[Modding:Item|Item]]
+
:''item'': The item to try to drop.
:Returns the item in the given slot in the being's inventory. If the slot is empty, nil is returned instead.
+
:'''Returns''': ''True'' if the drop succeeded, ''False'' if it failed.
 
----
 
----
{{Anchor|being_set_inv_item}}
+
;{{moddef|desc|use|cln|boolean|Item|item}}
;[[Modding:Being|Being]]:set_inv_item('''integer''' slot, [[Modding:Item|Item]] item)
+
Attempts to use an item.  Expends energy on success.
;[[Modding:Being|Being]].inv['''integer''' slot] = [[Modding:Item|Item]] item
+
:''item'': The item to try to use.
:Sets the given slot in the being's inventory to the given item. If the slot wasn't empty before, the previous constents are lost.
+
:'''Returns''': ''True'' if the use succeeded. ''False'' if it failed.
 
----
 
----
{{Anchor|being_get_eq_item}}
+
;{{moddef|desc|wear|cln|boolean|Item|item}}
;[[Modding:Being|Being]]:get_eq_item([[Modding:Constants#Equip Slots|Equip Slot]] slot) → [[Modding:Item|Item]]
+
Attempts to equip an item. Expends energy on success.
;[[Modding:Being|Being]].eq[[[Modding:Constants#Equip Slots|Equip Slot]] slot] → [[Modding:Item|Item]]
+
:''item'': The item to try to wear.
:Returns the item in the given equipment slot of the being. If the slot is empty, nil is returned instead. There are additional shorthands for each equipment slot: the ''eq'' table has .weapon, .prepared, .armor, and .boots fields.
+
:'''Returns''': ''True'' if the item was worn. ''False'' if the command failed.
 
----
 
----
{{Anchor|being_set_eq_item}}
+
;{{moddef|desc|attack|cln|boolean|Being|target}}
;[[Modding:Being|Being]]:set_eq_item([[Modding:Constants#Equip Slots|Equip Slot]] slot, [[Modding:Item|Item]] item)
+
;{{moddef|desc|attack|cln|boolean|Coord|target}}
;[[Modding:Being|Being]].eq[[[Modding:Constants#Equip Slots|Equip Slot]] slot] = [[Modding:Item|Item]] item
+
Attempts to attack something.  Expends energy on success.
:Sets the being's equipment slot to the given item. Any item that was previously in that slot is lost. There are additional shorthands for each equipment slot: the ''eq'' table has .weapon, .prepared, .armor, and .boots fields.
+
:''target'': A being or a location to attack.
 +
:'''Returns''': ''True'' if the attack was attempted. ''False'' if the being couldn't attack.
 
----
 
----
{{Anchor|being_play_sound}}
+
;{{moddef|desc|fire|cln|boolean|Coord|target|Item|weapon}}
;[[Modding:Being|Being]]:play_sound('''Sound ID''' sound)
+
Attempts to fire a weapon at something.  Expends energy on success.
:Plays the given sound as if it came from the being's position.
+
:''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.
 
----
 
----
{{Anchor|being_get_total_resistance}}
+
;{{moddef|desc|alt_fire|cln|boolean|Coord|target|Item|weapon}}
;[[Modding:Being|Being]]:get_total_resistance([[Modding:Constants#Resistance|Resistance]] resistance, [[Modding:Constants#BodyTarget|BodyTarget]] target) → '''integer'''
+
Attempts to fire a weapon using its alternate fire mode.
:Calculates the being's effective resistance against attacks of the given target (default is body). This accounts for inherent resists as well as equipment bonuses.
+
:''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.
 
----
 
----
{{Anchor|being_use}}
+
;{{moddef|desc|reload|cln|boolean}}
;[[Modding:Being|Being]]:use('''integer''' slot) → '''boolean'''
+
Attempts to reload the equipped weapon.
;[[Modding:Being|Being]]:use([[Modding:Item|Item]] item) → '''boolean'''
+
:'''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.
:This makes the being use the given consumable item from its inventory. The function always returns false. (Bug: it is supposed to return true on success.)
+
 
----
 
----
{{Anchor|being_wear}}
+
;{{moddef|desc|alt_reload|cln|boolean}}
;[[Modding:Being|Being]]:wear('''integer''' slot) → '''boolean'''
+
Attemptes to reload the equipped weapon using its alternate reload.
;[[Modding:Being|Being]]:wear([[Modding:Item|Item]] item) → '''boolean'''
+
:'''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.
:This makes the being wear the given eqipment from its inventory. Returns true on success and false on failure.
+
 
----
 
----
{{Anchor|being_pickup}}
+
;{{moddef|desc|direct_seek|cln|integer, Coord|Coord|dest}}
;[[Modding:Being|Being]]:pickup([[Modding:Coord|Coord]] pos) → '''boolean'''
+
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.
:This makes the being pick up the item at the given position. ''pos'' is optional; it defaults to the being's position. Returns true on success and false on failure.
+
:''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.
 
----
 
----
{{Anchor|being_attack}}
+
;{{moddef|desc|relocate|cln||Coord|dest}}
;[[Modding:Being|Being]]:attack([[Modding:Coord|Coord]] or [[Modding:Being|Being]] target)
+
Moves the being to the indicated location, with animations.
:This makes the being do a standard melee attack against the targeted being or coord.
+
:''dest'': The location to move the being to.
 
----
 
----
{{Anchor|being_fire}}
+
;{{moddef|desc|path_find|cln|boolean|Coord|dest|integer|cutoff|integer|maximum}}
;[[Modding:Being|Being]]:fire([[Modding:Coord|Coord]] target, [[Modding:Item|Item]] weapon)
+
Search for a path to the indicated location.  Pathfinding is a time intensive procedure, use conservatively.
:This makes the being fire at ''target'' with ''weapon''.
+
:''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.
 
----
 
----
{{Anchor|being_reload}}
+
;{{moddef|desc|path_next|cln|integer, Coord}} or '''boolean'''
;[[Modding:Being|Being]]:reload() → '''boolean'''
+
Moves the being to the next space on the found path.
:This makes the being reload its currently equipped weapon. The return value is true if there being had at least some of the appropriate ammo to attempt reloading with.
+
:'''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.
 
----
 
----
{{Anchor|being_direct_seek}}
+
;{{moddef|desc|flock_target|cln|Coord|integer|range|integer|mind|integer|maxd}}
;[[Modding:Being|Being]]:direct_seek([[Modding:Coord|Coord]] target) → '''integer'''
+
Assigns a coord based on other beings of the same type.
:This makes the being take a step towards the target. The being will always try to travel in a direct path. The return value is either 0, 1, 2, or 3. 0 indicates success, 1 indicates that a wall blocked the move, 2 indicates that a door blocked the move, and 3 indicates that a being blocked the move.
+
:''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''.
 
----
 
----
{{Anchor|being_path_find}}
+
;{{moddef|desc|msg|cln||string|msg_player|string|msg_being}}
;[[Modding:Being|Being]]:path_find([[Modding:Coord|Coord]] target, '''integer''' cutoff, '''integer''' maximum) → '''boolean'''
+
Prints a message depending on the status of the subject of the message.
:This attempts to calculate a path between the being and ''target''. The ''cutoff'' and ''maximum'' parameters are somewhat technical, but basically they indicate how much time should be spend searching for a path. DoomRL uses 40, 200 for bosses and 10, 40 for normal enemies. The path will be remembered by the being, and can be followed using path_next. Modders should keep in mind that path-finding is a somewhat expensive operation, especially for large ''cutoff'' and ''maximum''. The return value indicates whether a path was found. Even if no path was found, a path will be loaded that will try to take the being closer to the target (although this path may be empty). This uses the AStar searching algorithm using Euclidean distance as a heuristic. The search is aborted if ''maximum'' nodes are expanded without finding the target or it ''cutoff'' nodes are expanded without getting closer to the target. When aborted, a path is created to the closest expanded node to the target in terms of the heuristic.
+
:''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.
 
----
 
----
{{Anchor|being_path_next}}
+
;{{moddef|desc|select_slot_by_letter|cln|Item|string|letter}}
;[[Modding:Being|Being]]:path_next() → '''integer'''
+
Gets the slot based on the character entered.
:This causes the being to take a step along the path last calculated by path_find. The return value follows the pattern of direct_seek.
+
:''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.
 
----
 
----
{{Anchor|being_flock_target}}
+
;{{moddef|desc|phase|cln||CellID|[cell]}}
;[[Modding:Being|Being]]:flock_target('''integer''' range, '''integer''' mind, '''integer''' maxd) → [[Modding:Coord|Coord]]
+
Teleports the being to a new cell.
:This looks for the closest being of the same type to the being (within a square ''range''). If the being is farther than ''maxd'' away, then its position is returned. If it is closer than ''mind'', then a position opposite from the closest with respect to the being is returned. Otherwise (or if there is no nearby being of the same type), a random coord from the scanning area is returned.
+
:''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.
 
----
 
----
{{Anchor|being_msg}}
+
;{{moddef|desc|spawn|cln||BeingID|monster}}
;[[Modding:Being|Being]]:msg('''string''' msg_player, '''string''' msg_being)  
+
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).
:If the being is the player, then ''msg_player'' is displayed. If the being is not the player, but visible to the player, the ''msg_being'' is displayed. If either message is nil it is ignored.
+
:''monster'': The ID of the being to spawn.
 
----
 
----
{{Anchor|being_select_slot_by_letter}}
+
;{{moddef|desc|act|cln|boolean|Coord|coord}}
;[[Modding:Being|Being]]:select_slot_by_letter('''string''' letter) → [[Modding:Item|Item]]
+
Makes the being interact with the indicated location.
:Returns the one of the being's equipment where "a" is for armor, "b" is for boots, "w" is for weapon, and "p" is for the prepared slot. If the slot is empty, nil is returned.
+
:''coord'': The location to interact with.
 +
:'''Returns''': ''True'' if the action was successful, ''False'' if not.
 
----
 
----
{{Anchor|being_phase}}
+
;{{moddef|desc|eye_contact|cln|boolean|Coord|other}}
;[[Modding:Being|Being]]:phase([[Modding:Cell|Cell ID]] cell)
+
;{{moddef|desc|eye_contact|cln|boolean|Thing|other}}
:If ''cell'' is omitted, then the being is displaced randomly as if it used a [[phase device]] (without the flashy interface stuff). If the cell is included, the being is displaced to a random cell of the given cell id. If the chosen cell is occupied, a nearby cell is used. If no such cell exists, a random cell is chosen.
+
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.
 
----
 
----
{{Anchor|being_spawn}}
+
;{{moddef|desc|in_sight|cln|boolean|Coord|other}}
;[[Modding:Being|Being]]:spawn([[Modding:Being|Being ID]] being)
+
;{{moddef|desc|in_sight|cln|boolean|Thing|other}}
;[[Modding:Being|Being]]:spawn([[Modding:Being|Being]] being)
+
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.
:Drops a new being of the appropriate type (or the given being) nearby. The dropped being is set with the BF_NOEXP flag.
+
:''other'': A Coord, Being, or Item whose position will be checked.
 +
:'''Returns''': ''True'' if the object is visible, ''False'' if not.
 
----
 
----
{{Anchor|being_is_visible}}
+
;{{moddef|desc|is_player|cln|boolean}}
;[[Modding:Being|Being]]:is_visible() → '''boolean'''
+
Returns whether this being is the player or not.
:Determines if the player can see the being.
+
:'''Returns''': ''True'' if this being is the player.  ''False'' if it is not.
 
----
 
----
{{Anchor|being_is_player}}
+
;{{moddef|desc|set_items|cln|integer|SetID|set}}
;[[Modding:Being|Being]]:is_player() → '''boolean'''
+
Gets the number of items worn by the being that are part of a set.
:Determines if the being is the player.
+
:''set'': The set to check.
 +
:'''Returns''': The number of items of that set worn by this being.
 
----
 
----
{{Anchor|being_set_items}}
+
;{{moddef|desc|nuke|cln||integer|[time]}}
;[[Modding:Being|Being]]:set_items([[Modding:ItemSet|ItemSet]] set) → '''integer'''
+
Creates a nuke under the being and sets the nuke timer.
:Counts the number of the being's equipped items that belong to the given set.
+
:''time'': ''Optional.'' The number of game turns the the nuke will go off in.  If omitted, the default is 1.
 
----
 
----
{{Anchor|being_nuke}}
+
;{{moddef|desc|pick_mod_item|cln|Item, boolean|string|modletter|integer|techbonus}}
;[[Modding:Being|Being]]:nuke('''integer''' time)
+
Performs the choice, check, and attachment of a mod to an item.  Only the player can call this function.
:Sets the nuke timer to ''time'' and changes the cell under the being to the nuke cell. By default, ''time'' is 1. (Setting the nuke time to 0 will disable the countdown.)
+
:''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.
 
----
 
----
{{Anchor|being_pick_mod_item}}
 
;[[Modding:Being|Being]]:pick_mod_item('''string''' modletter, '''integer''' techbonus) → [[Modding:Item|Item]], '''boolean'''
 
:This only works for the player. This gives the player the item select menu used by mods, and calculates whether the mod is legal (using the given ''techbonus''). This includes assembly checking. The first return value is the item on success. The second return value is true on
 

Latest revision as of 00:59, 13 July 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.

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.

Personal tools