Modding:being API (0.9.9.7)

WIP pulled from 096 still investigating

---

API

The Thing API can also be used with beings.

Being Interface
Being	being.new(Being ID id)
void	Being:destroy(boolean silent)
void	Being:kill(boolean overkill)
void	Being:ressurect(integer rrange)
void	Being:apply_damage(integer damage, BodyTarget target, DamageType damageType)
string	Being:get_name(boolean known, boolean capitalized)
Item	Being:get_inv_item(integer slot)
void	Being:set_inv_item(integer slot, Item item)
Item	Being:get_eq_item(Equip Slot slot)
void	Being:set_eq_item(Equip Slot slot, Item item)
void	Being:play_sound(Sound ID sound)
integer	Being:get_total_resistance(Resistance resistance, BodyTarget target)
boolean	Being:use(integer slot)
boolean	Being:wear(integer slot)
boolean	Being:pickup(Coord pos)
void	Being:attack(Coord or Being target)
void	Being:fire(Coord target, Item weapon)
boolean	Being:reload()
integer	Being:direct_seek(Coord target)
boolean	Being:path_find(Coord target, integer cutoff, integer maximum)
integer	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(Cell ID cell)
void	Being:spawn(Being ID being)
boolean	Being:is_visible()
boolean	Being:is_player()
integer	Being:set_items(ItemSet set)
void	Being:nuke(integer time)
Item, boolean	Being:pick_mod_item(string modletter, integer techbonus)

being.new(Being ID id) → Being

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.

---

Being:destroy(boolean silent)

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.

---

Being:kill(boolean overkill)

Kills the being. If the optional overkill parameter is true, then the being will be gibbed.

---

Being:ressurect(integer rrange)

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.

---

Being:apply_damage(integer damage, BodyTarget target, DamageType damageType)

Deals damage to the being using the given body target and damage type. (The default damage type is bullet damage.)

---

Being:get_name(boolean known, boolean capitalized) → string

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.

---

Being:get_inv_item(integer slot) → Item

Being.inv[integer slot] → Item

Returns the item in the given slot in the being's inventory. If the slot is empty, nil is returned instead.

---

Being:set_inv_item(integer slot, Item item)

Being.inv[integer slot] = Item item

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.

---

Being:get_eq_item(Equip Slot slot) → Item

Being.eq[Equip Slot slot] → Item

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.

---

Being:set_eq_item(Equip Slot slot, Item item)

Being.eq[Equip Slot slot] = Item item

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.

---

Being:play_sound(Sound ID sound)

Plays the given sound as if it came from the being's position.

---

Being:get_total_resistance(Resistance resistance, BodyTarget target) → integer

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.

---

Being:use(integer slot) → boolean

Being:use(Item item) → boolean

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.)

---

Being:wear(integer slot) → boolean

Being:wear(Item item) → boolean

This makes the being wear the given eqipment from its inventory. Returns true on success and false on failure.

---

Being:pickup(Coord pos) → boolean

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.

---

Being:attack(Coord or Being target)

This makes the being do a standard melee attack against the targeted being or coord.

---

Being:fire(Coord target, Item weapon)

This makes the being fire at target with weapon.

---

Being:reload() → boolean

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.

---

Being:direct_seek(Coord target) → integer

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.

---

Being:path_find(Coord target, integer cutoff, integer maximum) → boolean

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.

---

Being:path_next() → integer

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.

---

Being:flock_target(integer range, integer mind, integer maxd) → Coord

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.

---

Being:msg(string msg_player, string msg_being)

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.

---

Being:select_slot_by_letter(string letter) → Item

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.

---

Being:phase(Cell ID cell)

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.

---

Being:spawn(Being ID being)

Being:spawn(Being being)

Drops a new being of the appropriate type (or the given being) nearby. The dropped being is set with the BF_NOEXP flag.

---

Being:is_visible() → boolean

Determines if the player can see the being.

---

Being:is_player() → boolean

Determines if the being is the player.

---

Being:set_items(ItemSet set) → integer

Counts the number of the being's equipped items that belong to the given set.

---

Being:nuke(integer time)

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.)

---

Being:pick_mod_item(string modletter, integer techbonus) → 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