Modding:Tutorial/Custom Beings

In the following tutorial you will learn the basics of being objects. Beings are anything in the game that can act independently on the map, without the need to specifically interact with with it. The player object is also a being, and so all of the topics mentioned here will also apply to the player (with some exceptions). We will learn how to create new beings, as well as how to apply various modifications in order to produce special and unique varieties.

Prototype

The following is a complete list of the being prototype table:

Beings{
    name            = "evil marine",                --required field
    name_plural     = "evil marines",               --defaults to name with an appended 's'
    id              = "badclone",                   --defaults to lowercased first word of 'name'
    ascii           = "@",                          --required field
    color           = DARKGRAY,                     --required field
    sound_id        = "soldier",                    --checked if 'id' has no sound bindings
    desc            = "It's you, but evil."         --required field
    kill_desc       = "fragged by your evil clone", --defaults to ""
    kill_desc_melee = "mauled by your evil clone",  --defaults to ""
    weight          = 1,                            --required field
    danger          = 12,                           --required field
    minLev          = 20,                           --required field
    maxLev          = 100,                          --defaults to 200
    corpse          = true,                         --defaults to true
    HP              = 100,                          --defaults to 10
    armor           = 2,                            --defaults to 0
    res_bullet      = 0,                            --defaults to 0
    res_melee       = 0,                            --defaults to 0
    res_shrapnel    = 0,                            --defaults to 0
    res_acid        = 0,                            --defaults to 0
    res_fire        = 0,                            --defaults to 0
    res_plasma      = 0,                            --defaults to 0
    weapon          = "bazooka",                    --defaults to "" (no weapon)
    toDam           = 5,                            --defaults to 0
    toHit           = 5,                            --defaults to 0
    toHitMelee      = 0,                            --defaults to 0
    attackchance    = 60,                           --defaults to 75
    vision          = 11,                           --defaults to 9
    speed           = 100,                          --defaults to 100
    XP              = 2000,                         --defaults to 3*'danger'^2+20
    ai_type         = "cyberdemon_ai",              --defaults to ""
    group           = 0,                            --defaults to 0
    flags           = {},                           --defaults to {}
    bulk            = 100,                          --defaults to 100
    sprite          = 0,                            --required field, set to 0
    overlay         = {0,0,0,0},                    --defaults to {0,0,0,0}
}

name is what the being appears to be in-game (e.g., using the 'look' command).
name_plural is what the game uses when a pluralized form of the name is required (e.g., in the kills section of the mortem).
id is the being identifier, to be used in lua whenever you want to call the item prototype.
ascii is the ASCII character used to represent the being in the console.
color is one of 16 (4-bit) colors that you can use to distinguish the being on the map.
sound_id is what you want the being's sound bindings to map to. If the being's id is not registered for sound bindings, it will use this key instead (useful when mapping several beings to a single set of sounds). (Note that in the current version, registering sound bindings for custom beings requires direct manipulation of the prototype. This will be explained later on.)
desc is the description of the enemy, as seen when using the 'more' command while looking.
kill_desc is what shows at the top of a mortem if the player was killed by this being's ranged attack.
kill_desc_melee is what shows at the top of a mortem if the player was killed by this being's melee attack.
weight affects the frequency that the being will appear, for random monster generation purposes.
danger is the capacity by which the being can be added to the map, for random monster generation purposes.
minLev is the earliest floor on which the being can appear, for random monster generation purposes.
maxLev is the latest floor on which the being can appear, for random monster generation purposes. weight, danger, minLev, and maxLev are only important on levels that randomly generate beings using Level.flood_monsters().
corpse determines if the being will generate a corpse upon death. Alternatively, you can choose a cell (by referencing its id here) that the being will leave upon death.
HP determines how much damage the being can take before it dies.
armor determines how much damage the being absorbs before HP is subtracted, modified by the damage type of the source. Note that, without BF_HARDY, armor can only reduce damage to 1.
res_[damage_type] sets the internal resistance of the being for damage_type. Internal resistance affects both torso and foot sources. Note that amount of damage absorbed by resistance is calculated before any damage absorption due to armor, and that 100% resistance can reduce damage to 0 (though anything less will not).
weapon sets the being's default weapon (in its weapon equipment slot). This can either be an id for a separate item prototype, or it can be inlined into the being prototype. If inlined, the following is true by default for the item prototype:
- type is set to ITEMTYPE_NRANGED
- id is automatically assigned (although no lua-based id (sid) will exist)
- weight and sprite are set to 0
- IF_NODROP and IF_NOAMMO are added to the flags table
toDam is the damage modifier to the being's natural melee attack. It deals 1d3 damage unmodified.
toHit is the accuracy modifier to all of the being's attacks.
toHitMelee is the accuracy modifier to the being's melee attack. toHit and toHitMelee can have negative values (e.g., in order to set melee to-hit to 0 while keeping ranged to-hit at some positive value).
attackchance is the chance that the being will attack on a given turn. This can be overridden with custom AI.
vision is the distance in which the being can see, assuming no cells that block vision are present.
speed is the speed of any of the being's internal actions (e.g., movement and attacking). Values greater than 100 result in a faster being, while values less than 100 result in a slower being. The maximum value this can be set to is 255.
XP determines how much experience the player receives upon killing the enemy. Only the player can benefit from experience.
ai_type sets the AI of the being. There are a number of pre-defined AI for the base monsters, but it is possible to define your own.
group assigns the being to a particular group of other beings that it will not attack. Beings of different groups, by default, will attack each other. In the base game, all monsters are in group 0, while the player is in group 1.
flags defines what being flags you give the being.
bulk is an unused parameter, so you can ignore it entirely.
sprite is what will eventually be the graphical tile of the being. Set to 0 and ignore it for now.
overlay, like sprite, is based on there being graphical tiles in DoomRL. You can ignore this key entirely for the time being.

Properties

Several of the being object properties are identical to their prototype counterparts, others differ only by name. The comparisons are given here:

The following properties are the same as the prototype keys:
- attackchance
- vision
- speed
- armor
The following properties have a different name than a prototype key, but function exactly the same as the key:
- The key sound_id is broken up into the following properties:
  - soundact is heard occasionally whenever the being acts
  - soundhit is heard whenever the being takes damage
  - sounddie is heard whenever the being dies
  - soundattack is heard whenever the being uses a ranged attack
  - soundmelee is heard whenever the being uses a melee attack
  - soundhoof is heard whenever the being moves (often disabled on most beings)
- hpmax is the property of HP
- tohit is the property of toHit
- todam is the property of toDam
- tohitmelee is the property of toHitMelee
- expvalue is the property of XP
There are also a number of properties that are instantiated by default without automatic customization. They are as follows:
- proto is the being's prototype. Don't change this unless you're planning on doing something really hacky.
- hp is the being's current health. It defaults to the HP prototype key, but changes whenever the being takes damage.
- scount is the being's speed count, or energy. For each turn that passes, all beings' scount is increased 100 (modified by each's speed); whenever a particular being takes an action, its scount is decreased by the amount of game seconds it takes for the action, multiplied by 1000. (For custom actions, scount must be modified manually in order for the action to take any time.)
- todamall is a damage modifer applied to all of the being's attack (melee and ranged). (When the player invests in Son of a Bitch, this property is modified.)
- Three properties affect the time in which particular actions are taken, given as a percentage relative to speed:
  - movetime affects how much time it takes for the being to move: for the player, this also corresponds to an increased dodge chance. (When the player invests in Hellrunner, this property is modified.)
  - reloadtime affects how much time it takes for the being to reload its weapon. (When the player invests in Reloader, this property is modified.
  - firetime affect how much time it takes for the being to attack. (When the player invests in Finesse, this property is modified.)
- bodybonus reduces knockback by the number given, and any value greater than 0 will prevent health decay above 100%. (When the player invests in Badass, this property is modified.)
- pistolbonus lowers firetime and increases damage whenever the being is using a weapon with the item flag IF_PISTOL. (When the player invests in Son of a Gun, this property is modified.)
- rapidbonus modifies the number of shots fired from a weapon whose "shots" property is greater than one. (When the player invests in Triggerhappy, this property is modified.)
- techbonus increases the number of mods that can be added to the being's equipment, as well as what tier of assemblies the being can create. (When the player invests in Whizkid, this property is modified.)
Finally, there are the properties that beings inherit from things. (Some of the thing properties are readonly, meaning they can't be changed once the instantiated object is initialized. These will be bolded for clarification.)
- The following properties are the same as the prototype keys:
  - color
  - id
  - name
  - sprite
  - res_bullet
  - res_shrapnel
  - res_melee
  - res_acid
  - res_fire
  - res_plasma
- The following properties have a different name than a prototype key, but function exactly the same as the key:
  - picture is the property of ascii
  - nameplural is the property of name_plural
- The following properties are automatically given by default:
  - sid is a string identifier, similar to id. This is what is used dominantly by modders, and is set based on the being's id key.
  - uid is a unique identifier across all instantiated objects. This is often used to save the state of a game.
  - x is the x-coordinate of the being on the map.
  - y is the y-coordinate of the being on the map. x and y make up a being's coordinate indirectly.
  - __ptr is a pointer to the object in the engine: you'll never have to worry about this property.

Engine Hooks

Beings come with three hooks:

OnCreate(being) is called when being is allocated to memory (i.e., created but not necessarily placed on the map). Use this function to add or modify properties, or potentially cause special cases to occur depending on the circumstances of the creation.
OnAction(being) is called whenever being takes an action. This is where a great deal of code used to be added when a modder wanted to manipulate the being's special abilities and/or AI, but is now mostly used as a means to have abilities that should be activated on every action. For more complicated setups, the modder should create a special AI for the being (explained later).
OnDie(being,overkill) is called whenever being dies. The overkill parameter is a boolean that only triggers OnDie() if being was gibbed on death. (In this way you can set up two separate OnDie() hooks to the same being prototype.)

Example Beings

There are quite a few things you can do with beings. The following examples will go through the more common uses for beings: you should feel free to work with any of these as a base for your own designs.

Dummy

Dummies are beings that cannot be killed but cannot kill, either. They are mainly used as targets, potentially as a trigger or simply something to shoot at. In spite of this simple purpose, there is a lot you can do with dummies. First, let's add the prototype fields:

Beings{
    name   = "dummy",
    id     = "dummy",
    ascii  = "I",
    color  = WHITE,
    desc   = "Nothing but a punching bag."
    sprite = 0,
    weight = 0,
    danger = 0,
    minLev = 0,
    speed  = 0,
    flags  = {BF_INV},
}

Since the dummy isn't going to be attacking at all, we can ignore a great deal of keys, and unless we want the dummy to be able to randomly spawn with other enemies, we set the generation parameters to 0. The important factors to this prototype involve the being's speed and flags:

speed is set to 0, so the dummy will never have any turn whatsoever.
- If you want the dummy to attack but not move, you can set the BF_SESSILE flag (which does exactly that).
- If, instead, you want the dummy to move but not attack, you will have to resort to building a custom AI, although such an AI would be relatively simple compared to an AI that requires both attacking and moving.
"BF_INV" is the flag set when a player is invulnerable, which prevents any damage from being taken regardless of its source (even going so far as to include a nuclear explosion!).
- If you want to prevent only certain types of damage, you can alternatively set any of the six resistance keys to 100, allowing for complete immunity against that type of damage. Note that there is no resistsance for piercing attacks, nor would this dummy ever withstand a nuclear explosion.
- If you want the dummy to be able to take damage but not die (as will be used later), you can set the HP to a ridiculous amount, such as 1000, and use a hook to set its hp to hpmax. This should prevent death in all but the most extreme cases. (I don't know the limit on HP, but 1000 will actually work.) Note that, if the dummy's speed is set to zero, the OnAction() hook won't trigger.

Now we can place the dummy on the map and go to town. However, this dummy can still be pushed around if it takes enough damage, and there's a good chance we don't want to chase this thing all across the map. There are two ways to add some knockback prevention:

Items{
    name = "dummysuit"
    weight = 0,
    sprite = 0,
    type = ITEMTYPE_ARMOR,
    desc = "for dummy",
    knockmod = -100,
    flags = {IF_NODROP},
}
 
Beings{
    name   = "dummy",
    ....
    OnCreate = function(self)
        self.eq.armor = item.new("dummysuit")
    end
}

The first method is to create a custom item, either armor or boots, that provides 100% knockback reduction, and then place the armor/boots in the dummy's armor/boots equipment slot on creation. The "IF_NODROP" flag is there so that, no matter what kind of dummy you create, it will never let the armor drop (allowing the player to wear it).

Beings{
    name   = "dummy",
    ....
    OnCreate = function(self)
        self.bodybonus = 100
    end
}

The second method is to alter the dummy's bodybonus property on creation, setting it to a very high amount so that only extreme amounts of damage will ever cause movement. bodybonus works like the Badass trait, so each point will prevent X damage from causing knockback, where X depends on the damage type (usually 12, 7 for fire). (Note that bodybonus accepts only ShortInt values, which range from -128 to 127.) This isn't as guaranteed as the first method, but requires fewer lines of code to execute and doesn't add a new item definition.

Now that we have an indestructible, immovable being, we can try making it useful. One fairly simple possibility is to have it spawn with an item and have it act as a decoy for other enemies to attack while you run from them. Here is one way to set it up:

Items{
    name = "hologram projector",
    id = "holo",
    level = 10,
    weight = 30,
    sprite = 0,
    desc = "Creates a virtual replica of yourself. These hellish buffoons won't know the difference!"
    type = ITEMTYPE_PACK,
 
    OnUse = function()
        local p = player:get_position()
        local a = area.around(p,2)
        Level.area_summon(a,"decoy",1)
        return(true)
    end,
}
 
Beings{
    name   = "decoy",
    id     = "decoy",
    ascii  = "@",
    color  = LIGHTGRAY,
    desc   = "It looks just like you!",
    soundID = "soldier",
    sprite = 0,
    weight = 0,
    danger = 0,
    minLev = 0,
    group =  1,
    speed  = 40,
    flags  = {BF_INV},
 
    OnCreate = function(self)
        self.bodybonus = 100
        self.scount = 4000
    end,
 
    OnAction = function(self)
        self:kill()
    end,
}

The item, called holo, uses Level.area_summon() to spawn a single dummy being adjacent to the player. The area is found by first getting the coordinate of the player using player:get_position(), and then using that coordinate to create a square centered around that coordinate with area.around().

The being, called decoy, is very similar to our original dummy, although a few things have changed in order to make it work properly:

First, we set speed to a non-zero but small number. This will serve as the decoy's starting position on its timer.
Next, we change the decoy's scount on creation to 4000. Since each turn increases scount by speed, and beings take actions when their scount is 5000, we can calculate that (5000-4000)/40 = 25, which is the amount of game seconds that the being will exist before taking an action.
Finally, we modify the decoy's OnAction() hook to remove itself from the map using the being:kill() method. This is used instead of the Level.clear_being() method so that it doesn't interfere with 100% completions (since any being added to the map will add one to the total enemies on the map).
In addition to the changes above, we also set group to 1, same as the player's, so that all enemies will attack the decoy just as they would the player. (To be fair, I don't know how well this works with the enemy AI, but this is the only way for this to work short of very specific AI modifications.)

The end result is that we have an item that causes a decoy to spawn next to the player, which lasts for 25 turns and will be attacked by enemies before disappearing. It should work in theory, although the extent to which enemies will attack a pacifist decoy aren't well-known. It is likely that you'll need not to attack enemies yourself to get the best use out of it.

Modding:Tutorial/Custom Beings

From DoomRL Wiki

Contents

Prototype

Properties

Engine Hooks

Example Beings

Dummy

Views

Personal tools

Navigation

Search

Toolbox