AI Recorder

Overview

The AI Recorder is the recording utility for the AI Debug Recorder system and is responsible for logging all inputs, decisions and other useful data in real-time while the game is being played out.

At the end of the game session, the recorder serializes all the gathered data for future processing. This utility lives within the AI Systems.

How to Start and Stop the Recorder

There are several ways to start and/or stop a recording:

  • Automatic - Via the cvar "ai_Recorder_Auto", the Recorder can be set up to automatically begin a new recording whenever a new game session starts. Additionally, the recording will be stopped and saved when the game session comes to a close (this could be because the user disconnected from the game, the server was restarted, the player manually closed the game via 'quit', or the Editor exited gamemode; however, this is not true if the game is closed due to the application crashing). This method is great for internal development, but should be turned off when resources are critical (for example, running on consoles or during an important demonstration).
  • Manual In Code - Using the IAIRecorder interface, it is possible to Start and/or Stop a recording whenever it is wanted.
  • Manual Via Console - Using the console commands 'ai_Recorder_Start' and 'ai_Recorder_Stop', it is possible to start and/or stop a recording from the in-game console whenever it is wanted.

Output File

Regardless of which method is used to perform a recording, all recordings are saved within the Recordings folder located in the root game directory. The file name of the recording is formatted as such:

MapName_Build(A) Date(B) Time(C).rcd

  • MapName - This is the name of the map in which the recording took place. The exception is if the recording took place in the Editor through the game mode, in which case the map name is suffixed with EDITORAUTO.
  • Build(A) - This is the version of the build with which the recording was made. It is always recommended to use the same build version to view the recording.
  • Date(B) - This is the date the recording was made.
  • Time(C) - This is the time the recording was saved.

If you create a manual recording, you can pass in an optional file name to be used for the outputted recording file. If none is specified, the above format is used.

How to Add New Data to the Recording

The recording is comprised of many streams which are responsible for chronologically logging a specific type of input.

There are already several streams for certain data which is being recorded:

  • E_RESET - When the agent is reset.
  • E_SIGNALRECIEVED - When the agent receives a signal.
  • E_SIGNALRECIEVEDAUX - When the agent receives an auxiliary signal.
  • E_SIGNALEXECUTING - When the agent is executing a received signal (processing it).
  • E_GOALPIPESELECTED - When the agent selects a new goal pipe.
  • E_GOALPIPEINSERTED - When the agent inserts a new goal pipe.
  • E_GOALPIPERESETED - When the goal pipe on the agent is reset.
  • E_BEHAVIORSELECTED - When the agent selects a new behavior.
  • E_BEHAVIORDESTRUCTOR - When the agent's current behavior has its destructor called.
  • E_BEHAVIORCONSTRUCTOR - When the agent's current behavior has its constructor called.
  • E_ATTENTIONTARGET - When the agent's attention target changes.
  • E_ATTENTIONTARGETPOS - When the position of the agent's attention target changes.
  • E_REGISTERSTIMULUS - When the agent receives a perception stimulus.
  • E_HANDLERNEVENT - When the agent's mind handles an event.
  • E_REFPOINTPOS - When the agent's reference point position changes.
  • E_AGENTPOS - When the agent's position changes.
  • E_AGENTDIR - When the agent's look direction changes.
  • E_LUACOMMENT - When a Lua comment is made on the agent.
  • E_HEALTH - When the agent's health changes.
  • E_HIT_DAMAGE - When the agent receives hit damage.
  • E_DEATH - When the agent is killed.
  • E_SIGNALEXECUTEDWARNING - When the agent is taking too long to process a signal.
  • E_BOOKMARK - When a bookmark is placed on the agent.

To record info for any of these events, use the IAIRecordable interface (which all AI Objects inherit from, and is used to link to the Recorder itself). It is also possible to add a new stream to the recording if needed.

All of the streams listed above are already handled by the AI System in various places, with the exception of the Bookmark stream. This is a special stream which is intended to be used by the Game to mark areas of interest for easy debugging later.

For example, a game project may connect a keyboard input to log event data on the Bookmark stream whenever the button is pressed, and inform the QA team to push the button whenever they see odd behavior from the AI.