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

From Nexus Mods Wiki
Revision as of 14:17, 7 February 2020 by WarhorseStudios (talk | contribs)
Jump to: navigation, search

NPCs – souls, role, metaroles, characters, 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
    </ul>

    </ul>

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

      </ul> </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.