AI Communication

Overview

AI Communication is about playing sound/voice and/or animations at the right times in the course of the game.

Note that Communication animations are not played if the AI is currently playing a smart object action.

Example

To actually trigger a Communication (event), use goalop "communicate".

For example:

   <GoalPipe name="Cover2_Communicate">
      <Communicate name="comm_welcome" channel="Search" expirity="0.5"/>
   </GoalPipe>

• name is the name of the actual Communication (sound/voice and/or animation). Possible Communications are defined by the XML file that the property CommConfig of this AI refers to.
• channel is the name of the Communication Channel this AI is using. The Channel should be defined in some XML file which resides in Game/Scripts/AI/Communication.
• expirity (expiry) is the maximum allowable delay in triggering this Communication (when the Communication Channel is temporarily occupied). If the Communication couldn't be triggered within this time period, it is discarded.

Communication Channels

Communication Channel determines whether an AI can play a Communication at the moment, depending on whether the Communication Channel is occupied or not.

A hierarchy of Communication Channels determine, which other Communication Channels (namely, parent Communication Channels) are occupied as well, when a child Communication Channel is occupied.

Let me emphasize that Communication Channel is a totally self-contained concept, independent of any other AI Communication concepts. Its sole purpose is to be in one of the two states: occupied or free.

Example

<Communications>
	<ChannelConfig>
		<Channel name="Global" minSilence="1.5" flushSilence="0.5" type="global">
			<Channel name="Group" minSilence="1.5" flushSilence="0.5" type="group">
				<Channel name="Search" minSilence="6.5" type="group"/>
				<Channel name="Reaction" priority="2" minSilence="2" flushSilence="0.5" type="group"/>
				<Channel name="Threat" priority="4" minSilence="0.5" flushSilence="0.5" type="group"/>
			</Channel>
			<Channel name="Personal" priority="1" minSilence="2" actorMinSilence="3" type="personal"/>
		</Channel>
	</ChannelConfig>
</Communications>

• name
• priority
• minSilence: Minimum time (in seconds) for which the Channel remains occupied after the Communication has completed.
• flushSilence: Time (in seconds) for which a Channel remains occupied after flushing the Channel. It is used to override the imposed silence time for the Channel which is no longer playing a Communication. If this attribute is not specified, the value of minSilence is used.
• actorMinSilence: Minimum imposed time (in seconds) to restrict AI actors from playing voice libraries after starting a Communication.
• ignoreActorSilence: Ignore (AI) actor Communication restrictions from the script.
• type: personal, group, or global.

Communication Configurations

Communication Configuration determines which Communications (and how) an AI can play. A concrete Communication Configuration is assigned to an AI using the its property CommConfig.

Example

<Communications>

  <!--Animation + Sound Event example (needs state using the action/signal in the animation graph)-->
  <Config name="Surprise">
	<Communication name="comm_anim" finishMethod="animation" blocking="all" forceAnimation="1">
		<Variation animationName="Surprise" soundName="sounds/interface:player:heartbeat" />
	</Communication>
  </Config>

  <!--Sound Event example-->
  <Config name="Welcome">
	<Communication name="comm_welcome" finishMethod="sound" blocking="none">
      <Variation soundName="sounds/dialog:dialog:welcome" />
    </Communication>
  </Config>

</Communications>

Config attributes

• name: Communication Configuration name, which can be assigned to an AI using its property CommConfig.

Every Communication Configuration should contain at least one Communication, using either tag <Communication>.

Communication attributes

• name
• choiceMethod: Method used to choose a variation: Random, Sequence, RandomSequence, or Match (just the first variation).
• responseName
• responseChoiceMethod: Similar to choiceMethod
• forceAnimation

Every Communication should contain at least one Variation.

Variation attributes

• animationName: Animation graph input value.
• soundName
• voiceName
• lookAtTarget: 1/0, true/false, or yes/no. Makes the AI look at the target.
• finishMethod: Any or all of: animation, sound, voice, timeout, all. It defines the way to determine when the communication is finished - after the animation is finished, or time interval has elapsed etc.
• blocking: Any or all of: movement, fire, all, none. It allows to disable the movement and/or firing of the AI.
• animationType: signal or action
• timeout

Voice Libraries

To support localized dialogs, sub-titles, and lip sync, Voice Libraries are necessary. The right Voice Libraries can be assigned to the right AIs (or Entity Archetypes) using property esVoice.

Voice Library is an XML Excel file which resides in GameSDK/Libs/Communication/Voice. Its format is as in the example (GameSDK/Libs/Communication/Voice/npc_01_example.xml).

American English defines the localization this Voice Library belongs to.

Localization/<language>/dialog/ai_npc_01/ is the path where the files (2nd column) actually are.

For each Communication (1st column) - "see", "pain", "death", and "alerted" - a few variations are provided.

The 3rd column is just for comments.

Flow Graph Node

To trigger Communications using Flow Graph logic the Flow Graph node "AI:Communication" can be used.

Startup

At startup, folder Game/Scripts/AI/Communication and all subfolders are scanned for XML files which contain Channel Configurations and Communication Configurations.

The SDK includes two basic Configuration XML files:

• BasicCommunications.xml
• ChannelConfig.xml

Turning off animation and/or voice

Communication animation and/or voice can be turned off using the AI's Lua script or the entity properties in Sandbox:

Readability =
{
   bIgnoreAnimations = 0,
   bIgnoreVoice = 0,
},

Debugging

To get debug information about AI Communication, the following CVars are available (provided ai_DebugDraw is 1):

• ai_DebugDrawCommunication
• ai_DebugDrawCommunicationHistoryDepth
• ai_RecordCommunicationStats

Debug output to console:

Playing communication: comm_welcome[3007966447] as playID[84]
CommunicationPlayer::PlayState: All finished! commID[-1287000849]
CommunicationManager::OnCommunicationFinished: comm_welcome[3007966447] as playID[84]
CommunicationPlayer removed finished: comm_welcome[3007966447] as playID[84] with listener[20788600]

Implementation

The code of the Communication Manager resides in CryAISystem and CryAction:

CryAISystem (Code/CryEngine/CryAISystem/Communication/):

• Communication.h: Definitions for Channel, Communication, and Variation
• CommunicationChannel.h/.cpp
• CommunicationChannelManager.h/.cpp
• CommunicationManager.h/.cpp: Loading Configurations, rendering debug information
• CommunicationPlayer.h/.cpp: Triggering Communications
• CommunicationTestManager.h/.cpp: A simple test system for the Communication Manager

CryAction (Code/CryEngine/CryAction/AI/):

• CommunicationHandler.h/.cpp: Playing sound events, setting Animation Graph inputs
• CommunicationVoiceLibrary.h/.cpp
• CommunicationVoiceTestManager.h/.cpp: A simple test system for Voice Libraries

Troubleshooting

<Communicate name="TargetSpottedWhileSearching" channel="Reaction" expirity="1.0" waitUntilFinished="0" />

<Communication name="TargetSpottedWhileSearching" finishMethod="voice" blocking="none">
    <Variation voiceName="TargetSpottedWhileSearching"/>
</Communication>