Revision as of 14:41, 7 December 2017

Introduction

Old proverb: "Assume you are wrong before assuming the generics system is."

The generic behaviours system in DOS2 allows NPCs to react to certain player actions. Where the generic behaviors in DOS1 were written completely in Osiris without any framework, in DOS2 the behaviors are data-driven: The framework is in code, the definitions are in text files (data), the behaviours are in Script and the exceptions are in Story. The goal for this new system was to make it mod friendly and flexible enough so that people could easily change or add behaviours, as well as making sure that players have enough feedback in the game to know how NPCs will react to them.

In short: Players commit Crimes. NPCs see crimes or crime scenes and respond with warnings or actions.

Definitions

Crime  

An action that is performed by the player that will invoke a NPC reaction

Tension  

A numeric value that is applied to an area to modify reactions and triggers alarm. It represents how likely the NPCs are to let you get away with a crime.

Crime Scene  

Evidence left behind from a crime. When a NPC sees it, they go into investigation mode, looking for players to interrogate. Crime scenes are registered from Osiris.

Investigate  

A behavior script part of CRIME_HumanReactions that will cause the NPC to look around and interrogate visible players. This behaviour gets triggered by code if no NPC saw the crime happen.

Interrogate  

An interactive dialog that will start between a NPC and the suspected player that will determine their innocence for the investigated crime. This behaviour gets triggered by script when an NPC that is in investigation mode sees a player.

Victim  

The person directly affected by the crime. This field is set when a crime gets registered by Osiris.

Lead Investigator  

The primary NPC that should react to the witnessed crime / action. This NPC is selected by code based on their tags and the data definitions.

Primary Sensible Action  

The lead investigator's reaction. This is define in data.

Secondary Sensible Action  

The reaction of witnesses other than the lead. This is defined in data.

Sensible Action  

A reference to primary or secondary sensible action.

Warning  

This is the dialog that will be called by the lead investigator when they sees a crime. This is defined in data.

Crime Region  

A trigger that encompasses an entire region (for example Ghetto of Fort Joy). The trigger is registered via Osiris.

Crime Area  

A smaller area that can have different tension from the region. e.g. A backroom, a forbidden area, prison, ... The trigger is registered via Osiris.

Alarm Mode  

A state when all the NPCs inside a crime area go into investigation mode. This is triggered via code based on the number and severity of registered crimes.

Tension

Tension is a numeric value that is applied to an area to modify reactions and trigger alarm mode. There are 3 levels of tension each with its own reactions.

Overall tension is calculated by adding up three parameters:

Crime Region Tension 

Raised by crimes registered in that region. (The total crimewave of the region)

Crime Area Tension 

Some crime areas have higher tension then other this is set in the properties of the trigger in the editor

Player Tension 

Raised by number and severity of crimes convicted

This makes Tension both player & location specific. Two players in the same area might have very different tensions and tension may rise dramatically by entering a forbidden area.

Crime Regions and Areas

Crime Region

This is a trigger that encompasses an entire region like the Ghetto of Fort Joy. a crime region stores crime and the region tension. Each prison is connected to a crime region as well. Each crime region has a Crime Regions "Owner ID" in its properties. This allows to connect 2 crime regions such as second floors, caves etc etc. If an NPC witnessed a crime outside of a Crime Region then the NPC will preform a Sensible Action right away without giving warnings. If their Sensible Action includes arrest, then they will go into combat.

Crime Area

Crime areas are triggers inside the Crime regions and are used to apply higher or lower tension to specific areas. Each crime area has a minimum tension field that is added to the region tension calculation. It is set in the editor on the trigger. Crime areas are also important for alarms: when an alarm mode is triggered all the NPCs inside a crime area will enter investigation mode.

(The Picture is only showing some of the area triggers.)

Reaction Pipeline

1. Register Crime (Osiris)
2. Check all NPCs in the detection range (code based on data)
3. Assign a Lead Investigator (Refer to flowchart for full assigning lead process) (code)
4. Check if the lead saw the crime (code)
   1. If Yes: execute the sensible action appropriate to the tension level (code based on data -> behaviour script and Osiris)
5. Check if someone heard the crime or saw a crime scene after the fact
   1. If Yes, tension is low or the crime cannot raise alarm: Start Investigation
   2. If Yes, tension is high and the crime can raise alarm: Start Alarm Mode

Schematic representation of reaction pipeline

Defining Generic Behaviours

A generic behaviour tells the game which NPCs should react to what and how. There is no way in the editor yet to edit crime behaviours. You have to directly edit a text file at Public/YourMod/Stats/Generated/Data/Crimes.txt

Generic Behaviour Definition

Here is an example definition of the Murder crime in the Shared mod:

new entry "Murder"
type "Crime"
data "CrimeType" "Murder"
data "TensionWeight" "100"
data "Lifetime" "90"
data "DetectionRange" "20"
data "AudibleRange" "15"
data "Audible" "Yes"
data "Continuous" "No"
data "ContinuousDelayTimer" ""
data "CreatesCrimescene" "Yes"
data "CanRaiseAlarm" "Yes"
data "CanMerge" ""
data "MaxInvestigators" "6"
data "InterrogateDialog" "GEB_Interrogation_Murder"
data "SoundEvent" "UI_CrimeSystem_Murder"
object crimereaction "NOT_MESSING_AROUND","any","1","","1","","","GEB_Attack_Murder","CRIME_Arrest","CRIME_AttackWithOptionalAD","GEB_AD_Noticed_Murder"
object crimereaction "GUARD","any","2","","1","","","GEB_Attack_Murder","CRIME_AttackCallHelp","CRIME_AttackWithOptionalAD",""
object crimereaction "PALADIN","any","3","","1","","","GEB_Attack_Murder","CRIME_AttackCallHelp","CRIME_AttackWithOptionalAD",""
object crimereaction "SEEKER","any","3","","1","","","GEB_Attack_Murder","CRIME_AttackCallHelp","CRIME_AttackWithOptionalAD",""
object crimereaction "MAGISTER","any","4","","1","","","GEB_Attack_Murder","CRIME_AttackCallHelp","CRIME_AttackWithOptionalAD",""
object crimereaction "LONEWOLF","any","5","","1","","","GEB_Attack_Murder","CRIME_AttackCallHelp","CRIME_AttackWithOptionalAD",""
object crimereaction "TOVAH","any","6","","1","","","GEB_Attack_Murder","CRIME_AttackCallHelp","CRIME_AttackWithOptionalAD",""
object crimereaction "CIVILIAN","any","7","","","","","GEB_Attack_Murder","CRIME_AttackCallHelp","CRIME_Flee",""
object crimereaction "ANIMAL","any","8","1","","","","GEB_Attack_Murder","CRIME_Flee","CRIME_Flee",""
object crimereaction "RC_GY_MASKEDSERVANT","any","1","","1","","","RC_GY_AD_RykersBodyguard_Crime","CRIME_AttackWithOptionalAD","CRIME_AttackWithOptionalAD","RC_GY_AD_RykersBodyguard_Investigation"

The "data" entries give common information about the crime itself:

CrimeType 

This is the ID of the generic behaviour. This is a unique ID that will be used to register the crime from Osiris with code.

TensionWeight 

This determines how this crime impacts the tension in a certain area. Higher values mean tension will rise faster and will result in stronger reactions from NPCs.

Lifetime 

How long does the crime scene stick around when not discovered? (in seconds)

DetectionRange 

How close do NPCs have to be to notice the player's action when they can see it? (sight range)

AudibleRange 

How close do NPCs have to be to notice the player's action when they cannot see it? (hearing range)

Audible 

Can NPCs hear the player's action at all? If this is set to No, NPCs won't react if they can't see players perform the crime and the AudibleRange gets ignored.

Continuous 

If this is set to "Yes", NPCs will react to the behavior when noticing the player even if they didn't notice the player during the initial action (Trespassing for example: NPCs should not only react when they see you first enter a forbidden area, but whenever they encounter you inside a forbidden area). If this is set to "No", then NPCs will be able to react to the action only if they saw it when it initially happened (Assault for example).

ContinuousDelayTimer 

After a reaction to a continuous crime, an NPCs will be put on an ignore list for that time. That NPC won't react again until the end of the timer. This is mainly for crimes that only trigger ADs, such as "Smelly": you don't want NPCs to complain non-stop about how bad the player smells.

CreatesCrimescene 

Does this action leave a crime scene? If this is set to Yes, NPCs can detect the action by seeing the crime scene that is left after the player performed the action (e.g. Murder leaves a body, but Assault leaves nothing). The CrimeScene is the location where the crime was first registered.

CanRaiseAlarm 

Can this crime trigger alarm mode?

CanMerge 

Can multiple instances of this crime be merged into a single crime? E.g. multiple trespassing crimes into a single area can be merged (it's the same crime), but not multiple murders (every murder is a separate crime).

MaxInvestigators 

This determines the number of NPCs that can investigate the crime simultaneously (when not in alarm mode; in alarm mode, all NPCs enter investigation mode)

InterrogateDialog

When an NPC is investigation mode, this is the dialog they will use when they see a player and start interrogating them

SoundEvent

the sound played when such a crime is detected.

Each "object" entry specifies a tag and how NPCs with this tag react when they detect this kind of crime. In order, the following fields are defined:

ReactionCategory_Tag 

This specifies a tag that characters must have to react to the crime / action.

Tension 

Can take one of three values: low, high, any. Determines for which tension level(s) this reaction will be executed.

ReactionCategory_Priority  

This is used to select a the lead investigator that will react to the crime. Lower number means the tag has a greater priority (for clarity, we usually specify the characters with the greatest priority first).

DisableInvestigate 

This specifies that while characters with this tag should react to perpetrators of crimes they saw being committed, they should never start investigating a crime when they merely stumble upon a crime scene, or heard a crime being committed (except when in alarm mode).

StopsAndInterruptsCrimes 

If this is filled with "1", then the primary sensible action of this crime will stop other crime dialogues. (a sensible action for this crime will however never start if the tension of the other crime is higher)

VictimReaction 

An override for PrimarySensibleAction if the victim of the crime is selected as the lead investigator. If not specified, it will fall back to PrimarySensibleAction.

VictimDialog

An override for Dialog used by VictimReaction. If not specified, it will fall back to Dialog (can be an interactive or automated dialog, depending on how the reaction starts/uses it).

Dialog 

The dialog used by the PrimarySensibleAction reaction (can be an interactive or automated dialog, depending on how the reaction starts/uses it).

PrimarySensibleAction 

The main reaction (= warning), performed if this NPC is lead investigator for the crime (unless they're the victim and VictimReaction has been specified).

SecondarySensibleAction 

A reaction that the NPC performs when they have been selected as investigator for this crime, but were not chosen as lead.

NoticedAD 

The dialog associated with the secondary sensible action (always an AD).

Setting up your characters for generic behaviours

For a character to react to generic behaviors it should have two key elements

1. Have a tag that can react to that crime / action (ReactionCategory_Tag)
   • for example if there is a Magister with no MAGISTER Tag then he will not react like a Magister
2. A Script with a sensible reaction that will be called from (ReactionCategory_PrimaryReaction)
   • The general script with reactions is CRIME_HumanReactions for non-animals and CRIME_AnimalReactions for animals, but this can also be a custom script with a custom behaviour.

Setting up your level for generic behaviors

For a level to react to generic behaviors it should have two key elements:

1. A Crime Region to register crimes to and store tension.
   • If there is no crime region, then the tension can not be stored and the NPCs will use the out-of-region reaction. This reaction is usually "attack".
2. A Crime Area is mainly for alarm and adding minimum tension level.
   • For example when a third body has been discovered in a house, not the entire region should go to alarm; only the NPCs inside the crime area. This can be a house, a courtyard, a temple, a cave, and so on.
   • If you want to create a higher tension areas you should also use crime area and assign a minimum tension value in the editor.

Disabling and enabling behaviours

At the moment it's only possible to enable and disable reactions to crimes per-character from Osiris script. However, do NOT use the game engine calls directly. A couple of procedures have been made for this purpose:

• ProcCharacterDisableAllCrimes: disables all generic behaviors (= crime reactions) for a character.
• ProcCharacterEnableAllCrimes: enables all generic behaviors for a character.
• ProcCharacterEnableCrime: enable a certain generic behavior (= crime) for a character. This uses the CrimeType from the Generic Behaviour Definition .
• ProcCharacterDisableCrime: disable a certain generic behavior for a character. This uses the CrimeType from the Generic Behaviour Definition .

By default, all characters will react to all crimes for which their tags are registered. If you wish for a character to only react to a particular crime, first disable all crimes for it and then re-enable the particular crimes it should react to.