AI Relations (Editing)

Originally written by Ishtvan on http://forums.thedarkmod.com/topic/1636, additions by greebo & fidcal 2009-03-13

AI Types (Teams)

Different AI types are defined by their team property. Put simply, AI on one team will generally be friendly to each other and antagonistic to AI on some other teams and tolerate yet others. Some AI teams are passive and will flee; others will attack. These are the default values for the team property and their team type:

• 0 = player
• 1 = builders
• 2 = city watch, houseguards
• 3 = nobility, commoners
• 4 = inventors/engineers
• 5 = street people, beggars
• 6 = criminals
• 7 = pagans
• 8 = mages
• 9 = revenants, zombies, skeletons
• 10 = ghosts
• 11 = werebeasts
• 12 = spiders & spider queen
• 13 = belchers
• 14 = rats & other passive animals
• 15 = elementals
• 16 = steambots

Mappers can change the team of individual AI entities by setting the team property to a new value but this is generally for special situations where for example, an individual(s) from one team is meant to have 'joined' another group. But to change the relationship between teams, eg, two normally friendly teams become enemies or vice versa, see the following sections.

Definition of Relationship Types

The three types of relationships are Friends, enemies, and neutrals. When assigning relations they take the values 1, -1, and 0.

• 1: Friends will
  • come to the aid of another friend who is alerted.
  • commence searching or attacking in that friend's vicinity or flee depending on AI type.
  • Be alerted if finding a body of a friend.
• -1: Enemies will
  • Attack other enemies they become aware of.
  • Ignore other enemy and neutral bodies
• 0: Neutrals will
  • ignore calls of distress from those they are neutral to.
  • Ignore all bodies they are neutral to.

Default Relationships

Even if you're starting your map from scratch, at map start the game will always load a set of default relationships from the entityDef atdm:team_relations_default. Any relationships not defined in there are automatically made enemies between teams and friends within teams (members of Team 2 are friendly to other members of Team 2).

Most relations defined within atdm:team_relations_default work both ways. So if Team A is set to regard Team B as friendly then Team B also regards Team A as friendly, unless there is a specific asymmetric relationship defined. Note that this is only true for these definitions that are read in from the default file and not for any custom definitions.

You can view this set by opening the tdm_team_relations.def file, but do not alter these values. See the next section about how to specify custom team relations.

Here is a summary of default Dark Mod team relationships:

• All are friendly to others within their own team.
• Builders are friends to 'normal' humans but neutral to beggars, criminals, pagans, mages.
• Guards are friends to 'normal' humans, pagans, and mages but neutral to beggars, criminals.
• Other 'normal' humans are friends back to builders and guards
• Beggars are neutral to all including the player but not monsters.
• Criminals, pagans, and mages are neutral to all except the player and monsters.
• All monster teams are neutral to each other.
• Rats and any other passive animals are neutral to all.
• Elementals are enemies of all.

Here is a chart of the default relationships.

Changing Team Relationship Info in the Editor

The default Dark Mod team relationships cover normal situations so the mapper usually need do nothing about them. In special situations you might need to change relationships between teams. This can be done both at map start and dynamically (see #Changing Relationships during the Game) changed during play.

To specify changes to the default relationships at the start of your own mission, create an entity internal > atdm:team_relations in your map. (A small rectangular entity will show up.) Override certain default relationships by adding spawnargs to this entity in the following way:

"rel 0,2" "1"

The left-hand key holds a pair of numbers defining the team numbers the relationship refers to, the right-hand value holds the type of relationship. Read this spawnarg like this:

Team 0 considers Team 2 as friendly. 

As you might suspect, the right-hand value has the following convention:

• Negative (value < 0): hostile
• 0 is neutral
• Positive (value > 0): values

Important

The above spawnarg does not imply that team 2 regards team 0 as friendly too. This has to be specified explicitly, defining the asymmetric matrix element.

To define the relationship for the reverse (team 2 => team 0), add a spawnarg like this:

"rel 2,0" "1"

Note that it is indeed possible to define a different relationship for 0 => 2 than for 2 => 0. Also, it's possible to define the relationship between members within a team itself, like

"rel 2,2" "-1"

This lets members of team 2 consider all members of the same team as hostile (see #Why change relations within a team?

One small note about the atdm:team_relations entity: this entity will pass its spawnargs to the relationship manager at spawn time and remove itself immediately afterwards, so that you don't have an unnecessary entity floating around your map.

Why change relations within a team?

It might seem weird to define a team's relationship with itself by setting "rel 1,1" to something, but later on we might want to have a "rogue team," like beasts that attack everyone, even other members of the "beast" team (eg, a cannibalistic predator or something). Also, the team's relationship with itself can be thought of as "morale," and we can maybe check this number to see how likely they are to come to each other's aid in combat and stuff like that.

Just to emphasize, you don't normally change the default friendliness of team members for each other but only in very special situations. If you want team X "every man for himself" and attack its own members, set "rel X,X" explicitly to a negative value.

Changing Relationships during the Game

To let relationships change during runtime, you can use triggers or scripts. There is a trigger entity called atdm:target_setrelations which can hold the same type of relationship spawnargs as described above. To activate these settings, just trigger this entity. Note that you can even trigger this entity multiple times, so you can re-use it, if you ever wanted to.

If you're switching teams to friendly, remember to define both directions of the relationship on these types of entities ("0,2" as well as "2,0").

To see how to make AI ignore the player until he does something wrong, see AI Ignore Player.

What happens if a Team is not mentioned at all?

If an AI is present in the map (or maybe is spawned by script later during the game), whose team is not mentioned in the matrix (like, say, team 60), the relationship code will handle this gracefully and consider this team as hostile to all the other teams. Still, members of team 60 are friendly to all other members of team 60 by default.

Debugging Relationships

Use the following console command to dump the current values of the relationship matrix to the console:

tdm_ai_rel_print

This will produce a rather long list, so you might want to use the condump command to write the console output to a file for later studying.

Also, watch out for console warnings during map start, which might indicate syntax errors of your spawnargs. Finally, it's also possible to use the log file. Activate the AI log class to see any messages coming from the relationship code.

See also

• AI Relations (Scripting)