Modding:being (0.9.9.7)

From DoomRL Wiki

Revision as of 21:04, 31 January 2012 by Game Hunter (Talk | contribs)

Jump to: navigation, search

If it bleeds, it leads. Beings inherit from the Thing base class which handles some basic properties in common with items. In addition the Player inherits this class, so anything you can do to creatures can be done to the player as well.

Contents

Prototype

New beings are created from being prototypes. Think of a being prototype as a recipe for creating new beings. There can be multiple former humans, but they all came from the same prototype. Prototypes are declared by passing a table with the desired properties to the Beings function. Engine hooks may also be included in the prototype. Mostly, the prototype's properties just describe beings' initial properties (occasionally with different names). Beings' properties can also mostly be changed after they are instantiated. Required fields are underlined. Sometimes required fields can safely be omitted, but this will generate a message in the log file. All being prototypes are stored in a global table called beings. This table can be indexed by id or nid.

Being Prototype
string name This is the being's name.
string name_plural This is the being's name_plural. By default, this is the name with an "s" appended.
string ascii This is the being's picture. It should be a single character string.
string id This is the being's sid. It must be distinct from other string ids. (The numeric id is automatically assigned to a field called nid.) Only the first 20 characters will be used. The default is the first word of the name in all lowercase.
integer list overlay This field is only used in the graphical version. It describes a color transformation to be applied to the being's sprite. This will create overlay_red, overlay_green, overlay_blue, and overlay_alpha fields in the being prototype.
integer XP This is the being's expvalue. By default, it is 3xD2+20, where D is the being's danger (see below).
Cell ID corpse The determines the corpse left by the being. If the value is true, a new corpse cell will automatically be created. Otherwise this field is interpretted as a cell id. After a being is declared, this field will have been translated to a number. The default is true.
Item Prototype weapon If this field is included, a new item will be declared and automatically equipped for beings generated from this prototype. The item prototype will automatically be a natural ranged weapon, have an id assigned, have zero weight, have no sprite, and have the IF_NODROP and IF_NOAMMO flags.
integer sprite This is the being's sprite. (Use 0 for no sprite.)
Color color This is the being's color.
integer toDam This is the being's toDam. (This bonus only applies to melee attacks.) The default is 0.
integer toHit This is the being's toHit. The default is 0.
integer speed This is the being's speed. (Remember, the maximum allowed speed is 255.) The default is 100.
integer armor This is the being's armor. The default is 0.
integer danger This is a monster generation parameter.
integer weight This is a monster generation parameter.
integer minLev This is a monster generation parameter.
integer maxLev This is a monster generation parameter. The default is 200.
integer HP This is the being's hpmax and starting hp. The default is 10.
integer bulk This parameter is unused. The default is 100.
integer group Monsters from different groups will fight each other if they use the default AI. Oddly, the default is "weapon-other" which, as a string, translates to 0. The player is in group 1.
integer attackchance This is the being's attackchance The default is 75.
integer toHitMelee This is the being's toHitMelee. The default is 0.
Being Flag list flags The flags in this list will be included in the being's flag set. Upon instantiation, a flagSet property is added to the prototype will include these flags (and possibly some automatic flags) in set format. The default is an empty list.
string sound_id If included and the being doesn't have sound bindings configured, then it will look for sound bindings under its sound_id.
AI ID ai_type This determines the being's AI. By default, the old pascal AI is used. (The pascal AI doesn't have an id.)
integer vision This is the being's vision. The default is 9. (The player also has vision 9 by default.)
integer res_bullet This is the being's res_bullet. The default is 0.
integer res_melee This is the being's res_melee. The default is 0.
integer res_shrapnel This is the being's res_shrapnel. The default is 0.
integer res_acid This is the being's res_acid. The default is 0.
integer res_fire This is the being's res_fire. The default is 0.
integer res_plasma This is the being's res_plasma. The default is 0.
string desc This is the description of the being displayed in the more information view.
string kill_desc If included, this being will have a special kill description in the mortem.
string kill_desc_melee As kill_desc, but for melee kills.

Flags

Being Flags

Being Flags
BF_INV Stops the being from taking any damage. (Directly setting the being's HP can circumvent this. Does not work well with the being's HP set to zero.)
BF_BERSERK Gives the damage reduction and melee damage bonus of berserk. (The speed bonus is not included.)
BF_ENVIROSAFE Beings with this flag are immune to damage from acid and lava tiles. (New hazardous tiles will have to check for this flag to respect it.)
BF_BACKPACK Gives the ammo-stacking benefits of the Backpack powerup.
BF_POWERBONUS Extends the duration of powerups as the Marine class bonus. New powerups will have to check for this flag (or use the provided helper function) to respect it.
BF_STAIRSENSE For the player, reveals the stairs tile(s) as the Scout class bonus.
BF_INSTAUSE Allows consumable items to be used in 0.1s instead of the usual 1.0s, as the Technician class bonus.
BF_MAPEXPERT Makes computer maps work like tracking maps, as the Technician class bonus.
BF_MODEXPERT Allows the being to mod unique items.
BF_QUICKSWAP Gives the benefits of the Juggler trait.
BF_BERSERKER Gives the benefits of the Berserker trait.
BF_DUALGUN Gives the benefits of the dualgunner trait.
BF_MASTERDODGE Gives the benefits of the Dodgemaster trait.
BF_SHOTTYMAN Gives the benefits of the Shottyman trait.
BF_POWERSENSE For the player, shows the locations of all powerups (as the first level of the Intuition trait).
BF_BEINGSENSE For the player, shows the locations of enemies (as the second level of the Intuition trait).
BF_LEVERSENSE1 For the player, gives partial information about levers (as the first level of the Intuition trait).
BF_LEVERSENSE2 For the player, shows the exact effect of levers (as the second level of the Intuition trait).
BF_VAMPYRE Gives the benefits of the Vampyre trait.
BF_BULLETDANCE Gives the benefits of the Bullet Dance trait.
BF_ARMYDEAD Gives the benefits of the Army of the Dead trait.
BF_AMMOCHAIN Gives the benefits of the Ammochain trait.
BF_MEDPLUS Allows med-packs to heal beyond 100% health (part of the Survivalist trait).
BF_HARDY Allows protection to reduce damage all the way to zero (part of the Survivalist trait).
BF_CLEAVE Gives the benefits of the Blademaster trait.
BF_GUNKATA Gives the benefits of the Gun Kata trait.
BF_SHOTTYHEAD Gives the benefits of the Shottyhead trait.
BF_NORUNPENALTY Gives the benefits of the Running Man trait.
BF_DUALBLADE If both weapons in the being's equipment slots have IF_BLADE, this flag allows both weapons to attack in the same turn, each at half the attack time (part of the Malicious Blades trait).
BF_BLADEDEFEND If the weapon in the being's prepared slot has IF_BLADE, this flag grants the being with resistances as Malicious Blades.
BF_PISTOLMAX Gives the benefits of the Sharpshooter trait.
BF_FIREANGEL Gives the benefits of the Fireangel trait.
BF_ENTRENCHMENT Gives the benefits of the Entrenchment trait.
BF_SCAVENGER Gives the benefits of the Scavenger trait (useless on anything other than the player).
BF_IMPATIENT This flag causes packs to be automatically used when picked up as Angel of Impatience.
BF_DARKNESS For the player, stops exploration from being recorded as in Angel of Darkness.
BF_MAXDAMAGE Beings with this flag always roll maximum damage as in Angel of Max Carnage.
BF_NOHEAL This is a marker flag that stops healing effects from working as in Angel of Masochism. New sources of healing will have to check for this flag in order to respect it.
BF_SESSILE Beings with this flag cannot move.
BF_NOMELEE This flag stops the being from doing any type of melee attack.
BF_REGENERATE Beings with this flag regenerate one health per second if they have less than 20 health remaining.
BF_SELFIMMUNE Makes the being immune to its own attacks.
BF_KNOCKIMMUNE Makes the being immune to knockback.
BF_UNIQUENAME This flag makes the game treat the being's name as a proper noun.
BF_ENTERBOSS1 This is a flag for the player that helps determine which victory message to use in the mortem.
BF_KILLBOSS1 This is a flag for the player that helps determine which victory message to use in the mortem.
BF_ENTERBOSS2 This is a flag for the player that helps determine which victory message to use in the mortem.
BF_KILLBOSS2 This is a flag for the player that helps determine which victory message to use in the mortem.
BF_CHARGE This is a flag for the AI. Beings with this flag are willing to walk through hazardous cells to reach the player. (This applies to the default AI, and the direct_seek method.)
BF_HUNTING This is a flag for the default AI. Beings with this flag will search out the player even if he is not in their line of sight.
BF_OPENDOORS This is a flag for the default AI. Beings with this flag will open doors.
BF_NODROP Beings with this flag will not drop their inventory or equipment when they die.
BF_NOEXP Beings with this flag will not award experience to the player.
BF_BOSS Killing this monster will cause the same message as killing the final boss as well as its death explosion and ending the game.
BF_JC
When used with BF_BOSS, changes the explosion to blue and changes the message to indicate that JC was killed instead of the cyberdemon.

Engine Hooks

Specifying one or more of these hooks in the prototype will allow for greater customization.

Being Hooks
void OnCreate(Being self)
void OnAction(Being self)
void OnDie(Being self, boolean overkill)

OnCreate(Being self)
This is called when the being is created.

OnAction(Being self)
This is called at the beginning of each of the being's turns. (Note that turns are only differentiated if time elapses in between.)

OnDie(Being self, boolean overkill)
This is called when the being dies. overkill is true if the being was gibbed.

Properties

Beings also have all the Thing properties in addition to those listed below. For beings, the resistance fields are inherent resistances that apply to all attacks.

Being
Byte attackchance This is how likely (in percent) a monster is to use a ranged attack on its turn. The exact interpretation may depend on the AI. This property is read-only.
Integer hp This is the being's current health.
Word hpmax This is the being's maximum health.
Byte vision This is the being's vision radius. (It is up to the AI to respect this radius.)
LongInt scount This is the being's speed count or energy. It counts up by the being's speed every 0.1s, and when it reaches 5000, the being gets to act. For details, see here.
ShortInt tohit This accuracy modifier is applied to all of the being's attacks.
ShortInt todam This damage modifier is applied to all the being's melee attacks.
ShortInt todamall This damage modifier is applied to all the being's attacks.
ShortInt tohitmelee This accuracy modifier is applied to the being's melee attacks.
Byte speed This is the rate at which the being's scount increases. It affects the speed of all actions.
Byte armor This is the being's natural armor. It appears as protection against all attacks.
Word expvalue This is the amount of experience that is awarded to the player when the being dies.
ShortInt techbonus This usually corresponds to Whizkid levels; it affects the number of mods that can be applied and the level of assemblies that can be constructed.
ShortInt pistolbonus This usually corresponds to Son of a Gun levels; it affects pistol firing time and damage.
ShortInt rapidbonus This usually corresponds to Triggerhappy levels; it affects the number of shots fired by rapid-fire weapons.
ShortInt bodybonus This is the property used to implement Badass. Each point reduces knockback by one, and anything above zero stops health decay.
Byte reloadtime This is the percentage of normal reload time that the being takes to reload. (It is used to implement Reloader.)
Byte firetime This is the percentage of normal fire time that the being takes to fire. (It is used to implement Finesse.)
Byte movetime This is the percentage of normal movement time that the being takes to move. For the player, anything less than 100 applies a corresponding dodge bonus. (This is used to implement Hellrunner.)
Word soundact This is the being's .act sound.
Word soundhit This is the being's .hit sound.
Word sounddie This is the being's .die sound.
Word soundattack This is the being's .attack sound.
Word soundmelee This is the being's .melee sound.
Word soundhoof This is the being's .hoof sound.
Being Prototype proto This is the being's prototype.

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 success and false on failure. (modletter should be the length one string corresponding to the mod type.)
Personal tools