T4 Modules Howto Guide/Player Descriptors

Who do you want to be today?

Important variables

Variable	Effect
name	Display name of this option in the selection menu. REQUIRED.
short_name	Identifier of this option. name is used if unset.
type	Defines which birth stage this descriptor belongs to. REQUIRED.
descriptor_choices	Selects which later descriptors are allowed or disallowed.
talents_types	Talent types learned at start of game
talents	List of starting learned talents.
desc	String that describes the descriptor. Appears in the selection menu. REQUIRED.
body	Initializes available slots. Requires ActorInventory defineInventory() calls in load.lua beforehand(?) which is NOT done in the example module.
copy	These variables and values will be copied to the resulting player object. See NPCs for values.
experience	Experience rate. 1 being normal experience gain.
stats	Initial stats for character. Is added to default stat values.

Important to note is that these variables do not overwrite, they add every time. If your race adds 2 strength, and your class adds 2 strength again you will end up with 4 strength. The exception to this is the copy variable. All elements in this will overwrite previous copy elements.

Editing the Example Module for your own use

At the time of writing, ToME has descriptors for world, race, subrace, sex, class and subclass. However, the example module only has a descriptor for role.

If you want to expand this and introduce your own descriptors for races and classes like ToME, or different descriptors entirely, you need to edit the following line in your /class/Game.lua file:

local birth = Birther.new(self.player, {"base", "role" }, function()

For comparison, ToME has this line:

local birth = Birther.new(self.player, {"base", "world", "race", "subrace", "sex", "class", "subclass" }, function()

Now you just need to create your own descriptors in the /data/birth/descriptors.lua file. If you want to organize your descriptors in multiple files for organization such as ToME does, remember to make a load call with your file path, such as the following ToME uses for its elf descriptor file.

load("/data/birth/races/elf.lua")

Leveling up

Once you gain enough xp to level, the levelup() method on the player gets called.
Use this method to include specific special code that runs on a new level up, such as gaining hp and stats.

Note that if you make use of NPC level scaling, its important to define a levelup() on the Actor class as well. Since Player inherits from Actor, you can have the Player class call Actor's levelup() method through:

mod.class.Actor.levelup(self)

Guide

This guide is roughly based on the te3 player descriptor guide.

In the default ToME module, you get to choose from a race, a sub-race, gender, a background, a class, and then a subclass. To the T-Engine, these are all the same thing, called 'player descriptors' (Character descriptors would be more accurate, but that's nitpicking), or PDs for short. PDs are what let you alter the player character in all sorts of different ways. Player descriptors typically stack, so any modifications done to one will usually add with any other modifications, rather than replacing them.

There's no definition or distinction between different types of PDs by the engine. They can all have the same functionality, the only place any consistency is found is by the module author. So, if you only want stats to come from races, and skills from classes, you will have to make sure that only races gain stat bonuses and only classes have skill bonuses. The engine will not discriminate against this for you.

All the examples below will be from the ToME module, so you should be able to see pretty easily where everything came from and can easily modify it and see what happens.

Possibly the most important PD is the one that the player will never see, the base descriptor, found in /data/birth/descriptors.lua. This is the one that is loaded for every character, and provides the universal traits that each character will share. This one has been edited slightly for clarity.

newBirthDescriptor{
    type = "base",
    name = "base",
    desc = {
    },
    talents = {},
    experience = 1.0,
    body = { INVEN = 1000, MAINHAND=1, OFFHAND=1, BODY=1, QUIVER=1 },

    copy = {
        -- Mages are unheard of at first, nobody but them regenerates mana
        mana_rating = 6,
        mana_regen = 0,

        max_level = 50,
        money = 10,
        resolvers.equip{ id=true,
            {type="lite", subtype="lite", name="brass lantern"},
        },
        resolvers.inventory{ id=true,
            {type="potion", subtype="potion", name="potion of lesser healing", ego_chance=-1000},
            {type="potion", subtype="potion", name="potion of lesser healing", ego_chance=-1000},
            {type="potion", subtype="potion", name="potion of lesser healing", ego_chance=-1000},
            {type="potion", subtype="potion", name="potion of cure poison", ego_chance=-1000},
            {type="potion", subtype="potion", name="potion of cure poison", ego_chance=-1000},
        },
        resolvers.generic(function(e)
            e.hotkey[9] = {"inventory", "potion of lesser healing"}
        end),
    },
}

This defines out the body and inventory slots for each character, the base experience rate and starting gold and the minimum equipment each character will need to have.

The second PD applied by the ToME module is your race, followed by subrace, found appropriate in /data/birth/races/. Races are where ToME typically grants the character their most unique abilities and major stat adjustments. Below is the PD for elves, and then a subrace of elf.

newBirthDescriptor{
    type = "race",
    name = "Elf",
    desc = {
        "Quendi are Elves, the first children of Eru.",
        "The first Elves awoke by Cuiviénen, the Water of Awakening in the far east of Middle-earth, long Ages before the Rising of the Sun or Moon.",
        "Unlike Men, the Elves are not subject to death by old age.",
    },
    descriptor_choices =
    {
        subrace =
        {
            Nandor = "allow",
            Avari = "allow",
            __ALL__ = "never",
        },
    },
    talents = {
--        [ActorTalents.T_IMPROVED_MANA_I]=1,
    },
    copy = {
        type = "humanoid", subtype="elf",
        default_wilderness = {39, 17},
        starting_zone = "tower-amon-sul",
        starting_quest = "start-dunadan",
        starting_intro = "elf",
    },
    experience = 1.05,
}

newBirthDescriptor
{
    type = "subrace",
    name = "Nandor",
    desc = {
        "Elves who turned aside from the Great Journey in the early days and settled in th east of the Misty Mountains.",
        "Both the Wood-Elves of Mirkwood and the Elves of Lórien are Nandor.",
        "They posses the Grace of the Eldar talent which allows them a boost of speed every once in a while.",
    },
    stats = { str=-2, mag=2, wil=3, cun=1, dex=1, con=0 },
    experience = 1.3,
    talents = { [ActorTalents.T_NANDOR_SPEED]=1 },
    copy = {
        life_rating = 9,
    },
}

Go back to T4 Modules Howto Guide