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).
• 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 this 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 (e.g., setting this to "acid" or "lava" to make an enemy that leaves a hazardous tile when it dies).
• HP determines how much damage the being can take before it dies.
• armor determines how much damage the being absorbs before HP is subtracted. 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.
• 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 callable 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., setting the melee to-hit to 0 while keeping the 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.