NPCs, Souls, Roles, Metaroles, Characters, Brains Documentation

From Nexus Mods Wiki
Revision as of 13:11, 25 September 2019 by WarhorseStudios (talk | contribs)
Jump to: navigation, search

NPCs – souls, role, metaroles, brains

This article describes everything you need to know about NPCs and various principles – NPC entity, souls, roles, metaroles, characters, NPC brains.
The following image explains the relationships between all the concepts

NPCs SRMCB Image1.png

NPC entity

Any human or animal object that can be controlled by AI MBT trees is an NPC entity. There are several NPC entity classes – each for every animal and human type with different animation skeletons.

NPC entities:

  • Humans
    • NPC (=males)
    • NPC_Female
  • Animals
    • Boar
    • Cow
    • DeerDoe
    • Dog
    • Hare
    • Hen
    • Horse
    • Pig
    • RedDeer
    • RoeBuck
    • Sheep
  • </ul>

    The entities are available for placing in the level in CE Sandbox Editor in RollupBar under “Entities > AI”. (Note: there are also non-functional legacy entities from basic CryEngine).

    An NPC entity, by default, has the default head, default body, default clothes and plays idle animations ad infinitum. The NPC entity, like any other, is saved in its constituent layer/LYR file (.lyr).

    NPC entity properties that be changed:

     

    Soul

    Most NPC properties, which make it a unique individual, are saved in its soul.

    If you save the aforementioned setup (default NPC entity placed in level) right away a local soul data is stored in the LYR. This is a basic CryEngine functionality. KCD, however, uses something called “shared souls” – an equivalent saved in DB and with expanded capabilities.

    The main table is “soul” where every record is a separate soul. Soul DB table contains a wide number of settings – from head model, to faction membership, to daycycle schedule settings.

    Parameter(s)

    Description

    Note

    soul_id

    Soul GUID

    Created in WH NPC Editor

    soul_name

    Name of the soul

    Uniqueness not required, but strongly suggested

    soul_class_id

    Not required. Used for custom grouping of NPCs

    Trackable in Quest Flow Graph

    initial_clothing_preset_id

    Reference to the initial clothes of the NPC

    Set in WH Inventory Editor

    character_head_id

    Reference to the head model of the NPC

    Set in WH NPC Editor

    character_hair_id

    Reference to the hair model of the NPC

    Set in WH NPC Editor

    initial_clothing_dirt

    Initial dirtiness of the NPC

     

    inventory_id

    Reference to initial inventory template

    Set in WH Inventory Editor

    *str, agi, spc, vit, gearing, barter, courage, charisma, vision, shadiness

    various skills, stats and PRG parameters

    Set in Storm

    reputation

    initial personal reputation towards player

    Set in Storm

    brain_id

    Reference to a brain class

    Set in WH NPC Editor

    faction

    NPC's faction membership

    Set in Swift

    social_class_id

    NPC's social class setting

    Set in Swift. Plays role in Crime Systém

    *activity_0-8

    name of daycycle schedule activity

    Set in Storm

    *time_0-8

    starting time of the daycycle schedule activity

    Set in Storm

    soul_vip_class_id

    VIP systems protection settings

    Set manually in DB

    initial_weapon_preset_id

    Reference to the initial weapons of the NPC

    Set in WH Inventory Editor

    _soul_ui_name_id

    NPC's UI name if not defined by Character (in Skald)

    Created manually. Set in Storm

    skald_character_id

    Reference to NPC's Character

    Character created in Skald, linked in Swift

    combat_level

    Combat level of the NPC

    Determines combat abilities. Interpreted by Storm


    One of the important setting is a reference to the soul’s brain. Brain is a construct that holds all MBT trees and thus allows you to script the NPC’s behavior. Typically a human NPC has the brain “npc_daycycle” (see documentation).

    There are also other related tables with additional setting or definitions referenced from the soul table:

    soul_archetype
    soul_class
    soul_combat_level
    soul_crime_role
    soul_ui_name
    soul_vip_class
    soul2hobby
    soul2inventory
    soul2metarole
    soul2perk
    soul2role
    soul2skill
    brain
    clothing_preset
    faction
    inventory
    shop
    shopkeeper
    skill
    stat
    weapon_preset

     

    Pairing entity to soul

    The link between entity and soul is save in the LYR file.

    New soul

    A new soul is created in WH NPC Editor/Properties.

    It is strongly advised for the soul name and entity name to be the same.

     Soul/Entity naming conventions

    We strongly recommend incorporating the name of your mod or its part (quest) in the name. This will prevent naming clashes with other mods. We recommend following this format

    <locationPrefix>_<modOrQuestName>_<additionalInfo>_<nameOrRole>_<additional_info><numberIfNotAlone>

    Where:

     

    locationPrefix- roughly tells you where the NPC stands in the level. Vanilla KCD uses the following prefixes. You may invent your own.

    update MAP

    morOrQuestName – unique name for your mod or quest the NPC is related to

    additionInfo – any additional info if needed

    nameOrRole – name of the NPC (e.g. peter) or their role in the world (e.g. guard). The most generic NPCs are usually named man or woman

    numberIfNotAlone - If there are more people eligible for the same name, add a number

    Examples:

     sas_guard3
    cros_q_massacre_bandit5
    tal_borek
    tal_ dlc1_borek_trialogTwin

      

     

    Select an NPC entity in the level and name it properly. Click “Create new shared soul”. This will create a temporary local (!) soul of the same name as the entity name. Not yet committed soul is indicated with this line

    NPCs SRMCB Image2.png
    Saving any layer will commit the soul data into DB and the highlighted line will change to the proper DB soul name.

    Existing soul

    Sometimes (e.g. when you create a twin for certain situations, or when you want to have the same NPC in different level) you may want to link to an existing soul. In that case click the button “Connect to existing soul” in WH NPC Editor/Properties.

    Character

    A character is an independently created “design counterpart” for a soul. It can hold information that facilitates development in purely design/writing phase so that it can be oblivious to the state of the game level or souls.

    However, the only character data critical for the game are:

    • Voice – The basic VO unit. Typically, one voice = one voice actor. However if a voice actor is capable of delivering more distinct voices they can have more voices assigned to them.
    • Character UI name – The name that appears in the game right above the “Talk” prompt.

    NPCs SRMCB Image3.png

    Characters are created in Skald.
    Characters are linked to souls in Swift.

    Role

    NPCs SRMCB Image4.png

    A role defines a participant in dialog and holds all of their lines across the entire game. Roles are created in Skald when you write a dialog (see more in Skald Tutorial).

    A single role can appear in multiple separate dialogs (like EXAMPLE MAN in the image above). In other words - a new dialog can re-use any existing roles.

    One role can be assigned to multiple souls. This in effect means that all these souls can take part in all dialog where the role is present, and that all these lines of that role must be recorded by the voice specified in the soul-character relationships.

    Roles are assigned to souls in Storm and the data is stored in DB table “soul2role”

    Metarole

    Metarole is a concept that allows roles to be temporarily available or unavailable to the NPC.

    Each role is assigned to a metarole. The default metarole, to which all new roles are assigned, is called NPC and is switched on by default on all NPCs. A role can be assigned to a different metarole in Swift.

    The NPC must have assigned ALL the roles it can use at any time. Roles which are “under” non-default metarole can then be switched on and off (respectively) by the following LUA functions:

    soul:AddMetaRoleByName(“metaroleName”) OR soul:AddMetaRole(metaroleID)

    soul:RemoveMetaRoleByName(“metaroleName”) OR soul:RemoveMetaRole(metaroleID)

    But why?

    What are metarole good for in practice? Examples:

    Situation 1 – roles can be too general and their assignment to souls too ambiguous.

    Premise: Any NPC can go to any shop and have a dialog with the shopkeeper.

    NPCs SRMCB Image5.png

    Problem: Any shopkeeper can also become a shopper. This means that if shopkeeper1 goes shopping and attempts to talk with another shopkeeper2, both shopkeeper1 and shopkeeper2 have both roles. The Dialog System, despite both NPCs performing different behaviors, doesn’t know at this point who should be the customer and who the shopkeeper. In the best scenario the NPCs will play their role in this situation randomly each time, in the worst case they will refuse to talk altogether.

    Solution: You still give the role SHOPPER to all NPCs in the world, and the role SHOPKEEPER to all shopkeepers. But you will set the SHOPPER role to metarole META_SHOPPER and SHOPKEEPER to META_SHOPKEEPER and both will be removed by default (no setup is needed for that). Then, the NPC who plays the customer, will have LUA script soul:AddMetaRoleByName(“META_SHOPPER”) at the start of its behavior, while any shopkeeper ready to accept customer will have soul:RemoveMetaRoleByName(“META_SHOPPER”) at the start of its shopkeeper behavior. Both behaviors will perform soul:RemoveMetaRoleByName(“metaroleName”) by the time their dialogs are no longer needed. These LUA call pairs are often used in MBT tree node LUAWrapper.

    Situation 2 – overriding systemic metarole-driven monologs

    Premise: There are several systems (similar to the shopkeeper-customer problem described above) primarily driven by metaroles, such as dudeprox (“Henry has come to see us!”) or trespass comments (“Get out of here before I call the guards”). You don’t want to reinvent the wheel. You want the use the functionality behind these systems. You want to use a custom monolog, not the generic ones.

    Solution: You create a monolog with new role (e.g. EXAMPLE MAN – DUDEPROX) and give it higher priority (more in Skald tutorial/documentation). Then you assign that role to system metarole KOMENTAR_NA_JINDRU (see more on how to make sense of the by-default Czech role and metarole names here). That’s all. What happens is that the dudeprox system temporarily switches on the core dudeprox role (KOMENTAR_NA_JINDRU) and attempts to play the dudeprox dialogs. It will look at all the valid monologs. All of them are always valid, but your custom monolog is valid in the specific situation and has a higher priority, so its played. When the custom monolog becomes invalid again your NPC will revert back to using generic monologs in these situations.

     

    Situation 3 – minimizing possible interference of in-game or any other special dialog with regular dialogs.

    Premise: There is NPC1 and player. By pressing “E to Talk” you engage in numerous conversations with NPC1 (with role EXAMPLE MAN).

    NPCs SRMCB Image6.png

    But under certain circumstances there is also another special dialog which you don’t want to appear among the listed topics. For example, a quest gets suddenly activated which leads to a situation where a short exchange is automatically played when you get close to NPC1. If this was handled as a NPC’s bark (= ingame monologue), there would be no interference, but the designer wants an ingame dialog here which is a dialog like any other but without cameras and dialog selection interface and you also have full control over you character.

    Problem: When you press “E to Talk”, the system selects all dialogs where player and NPC1 and player are the sole participant. Then it filters out any dialogs with FALSE condition. Now if you do a poor job with conditions your ingame dialog may be listed among the normal topics. Worse even, if the ingame dialog has non-default priority, you may end in situation where the ingame dialog always takes over and you can’t talk to the person normally (BTW that is how the refusal bark on waking NPC up in the night works by design).

    Solution: There are several possible solutions to curb these clashes. One of them consists of adding the ingame dialog NPC’s role to a new metarole and switching it on only temporarily. It allows you to avoid having to write complex sets of entry conditions (for both the ingame dialog and the other dialogs) and having to restrict normal dialogs altogether (greyed-out “E to talk”) while the ingame is being played.

    Brain

    NPC entity belongs among SmartEntities (along with SmartObjects, SmartAreas etc.) which means they can hold a brain. Brain is what allows you to control that entity via AI MBT trees.
    Brains are assigned to souls. Default brain of any newly created soul is “npc_test_base” which, as you can see upon inspection, does nothing.

    Normal NPCs have the brain “npc_daycycle” which takes care of every aspect of their basic functionality – from reactions to various systems (hearing, perception, crime, trespass, dialog requests, player presence etc.), to being able to process their daycycle schedule settings as the world time goes on.

    There are also other specialized brains for humans with limited capabilities due to specialized focus – npc_battle, npc_deadbody. These brains are simplified for the sake of optimization. After all, the dead don’t need to react to sound.

    Animal brains also have dedicated brains – npc_horse, npc_horse etc.

    Player is an NPC entity like any other. He must have the soul “dude” which has the brain “player”. Without it the NPCs and many other systems cannot function properly as many systems react to player and need to communicate with the player brain.

    Brains npc_daycycle and player are further described in their respective documentations.