AI Use Tags

What is an AI Use Tag?

AI use tags are spawn variables found in the .def file for an entity type, which the AI looks for to see if an entity can be used in a particular way. For example, an entity type that acts like a torch can have certain tags declared in its .def file so that the AI knows it can light the torch. Another example would be a tag that declares an item to be a weapon. When an AI encounters an entity whose type has a tag declaring it is a weapon, the AI can branch in its script to react in a certain way. (Currently, weapons, such as arrows, belonging to non-friends are treated as alarming.)

What AI Use Tags are there?

The primary AI use tag is a variable declared in a .def file called "AIUse". Once the "AIUse" tag is specified, the specific use value given will lead the AI to look for other tags that describe sub-type or functional variation. Hence, the AI Use tag system behaves like a logical tree, with "AIUse" forming the root of the logical tree.

An example of an AIUse declaration from a def file would be the following line found in Darkmod/def/tdm_lights.def "AIUse" "AIUSE_LIGHTSOURCE"

What AIUse values does the current AI base script understand?

The following values are defined in /Darkmod/script/darkmod_ai_constants_usevalues.script and are interpreted by the Dark Mod AI base script. Each value given is described by its general meaning, the spawn argument variable ranging from 0.0 to 1.0 defining the chance the AI will notice the visual stimulus of the item, and the effect on the AI.

AIUSE_WEAPON

• meaning: The object is a type of weapon.
• chance to notice: "chanceNoticeWeapon"
• visual response SDK function: State::OnVisualStimWeapon
• effects: If it doesn't belong to a friend, it will raise the level of alarm in the AI. A noticed non-friendly weapon is also treated as 2 points of evidence of some sort of intruder.

AIUSE_PERSON

• meaning : The object is a person or person like creature.
• chance to notice: "chanceNoticePerson"
• visual response SDK function: State::OnVisualStimPerson
• effects:
  1. If the person is friendly or neutral and unocnscious or dead, the AI will react with alarm
  2. If the person is friendly, the AI may greet the person
  3. If the person is an enemy, they will be reacted to as a threat

AIUSE_LIGHTSOURCE

• meaning : The object is a light source
• chance to notice: "chanceNoticeLight"
• visual response SDK function: State::OnVisualStimLightSource
• effects:
  1. If the lightsource is off, and supposed to be on, that will produce a small amount of alarm
  2. If the lightsource is off, and the AI is alarmed or suspicious enough to want more light, they may try to turn it on

AIUSE_DOOR

• meaning: The object is an open door, hatch or other similar item
• chance to notice: "chanceNoticeDoor"
• visual response SDK function: State::OnVisualStimDoor
• effects: If the door is marked as supposed to be closed, it will cause some alarm and be treated as evidence of intruders

AIUSE_BLOOD_EVIDENCE

• meaning: The object is some sort of blood spatter or evidence of conflict
• chance to notice: "chanceNoticeBlood"
• visual response SDK function: State::OnVisualStimBlood
• effects: This will alarm the AI and count as evidence of intruders

AIUSE_BROKEN_ITEM

• meaning: The object is broken (evidence of conflict)
• chance to notice: "chanceNoticeBrokenItem"
• visual response SDK function: State::OnVisualStimBrokenItem
• effects: This will alarm the AI and count as evidence of intruders

AIUSE_MISSING_ITEM_MARKER

• meaning: The object is a non-physical marker noting that an object that was there is no longer there
• chance to notice: "chanceNoticeMissingItem"
• visual response SDK function: State::OnVisualStimMissingItem
• effects: If the item belongs to a friend, it creates alarm, counts as evidence of intruders, and sets a flag tell the AI that items have been stolen.
• special notes: Absence marker entities are created for entities descended from "item" when they are moved or placed in the player's inventory and destroyed if the item is placed back close enough to its original position.

However, the absence marker is only created if the item has the spawn argument "absence_noticeability" set to a non-zero value.

AIUSE_SUSPICIOUS

• meaning: The object is a non-physical marker noting that an object is suspicious (arrows stuck in wood) OR a fire arrow or fireball passing by
• chance to notice: "chanceNoticeSuspiciousItem"
• visual response SDK function: State::OnVisualStimSuspicious
• effects: This will alarm the AI and count as evidence of intruders

What AIUse values does the current AI base script not yet understand?

The following AIUse values are defined but not currently used by the scripts. Perhaps some enterprising person will do some scripting to support them. Obviously, more AIUse values can be defined to support more sophistication in AI scripts.

AIUSE_SEAT AIUSE_COOK AIUSE_EAT AIUSE_DRINK AIUSE_PET AIUSE_MONSTER AIUSE_UNDEAD AIUSE_CATTLE AIUSE_PEST

AIUSE_PERSON specific spawn arguments

"personGender is used to to note the gender of the "AIUSE_PERSON" entity. It is used when an AI speaks to another AI. The following values are valid:

• PERSONGENDER_FEMALE
• PERSONGENDER_MALE
• PERSONGENDER_UNKNOWN

"personType is used to define the "class" or "role" of a person. This is used when an AI speaks to another AI and could have other behavioral uses. The following values are valid:

• PERSONTYPE_GENERIC This value indicates a person with no specific role
• PERSONTYPE_NOBLE This indicates a person who is of noble title
• PERSONTYPE_CITYWATCH This indicates an officer of the city watch
• PERSONTYPE_PROGUARD This indicates a mercenary or highly professional guard
• PERSONTYPE_BUILDER The person is a representative of the Builder Church
• PERSONTYPE_PAGAN The person is a pagan
• PERSONTYPE_THIEF The person is a thief or outlaw
• PERSONTYPE_PRIEST The person is a Builder priest.
• PERSONTYPE_BEGGAR The person is a beggar.

AIUSE_LIGHTSOURCE specific spawn arguments

"lightType" is looked to for light sources to see what type of light source it is. The following values are valid:

• AIUSE_LIGHTTYPE_TORCH
• AIUSE_LIGHTTYPE_GASLAMP
• AIUSE_LIGHTTYPE_ELECTRIC
• AIUSE_LIGHTTYPE_MAGIC
• AIUSE_LIGHTTYPE_AMBIENT

"switchName" is used to see if a switch controls the light source. If this value exists, it is the name of an entity instance in the map that can be activated to switch this lightsource on and off. The AI will path to it and use it if it wants to turn the light on or off. If a switch doesn't exist, and it is a torch or gas type light, the light can be relit by an AI by approaching the light and calling an action on the light object.

"shouldBeOn" is used to see if the light is supposed to be on. AI will be alerted by "AIUSE_LIGHTSOURCE" entities that are off and have this spawn argument set to a non-zero value.

AIUSE_DOOR specific spawn arguments

"shouldBeClosed" is used to see if the door is supposed to be closed. AI will be alerted by "AIUSE_DOOR" entities that are open and have this spawn argument set to a non-zero value.