Director Agent Nodes

Director operations: scene direction, character persistence, voice assignment, chat message insertion, dice rolls, actor/narrator direction functions and the director's websocket handler modules.

15 nodes.

Node	Registry path
Assign Voice	agents/director/AssignVoice
On Persist Character Generate Visual	agents/director/events/onPersistCharacterGenerateVisual
Direct Actor	agents/director/fn/directActor
Direct Narrator	agents/director/fn/directNarrator
Yield To Actor	agents/director/fn/yieldToActor
Yield To User	agents/director/fn/yieldToUser
Roll Dice	agents/director/gameplay/rollDice
Insert Chat Message	agents/director/InsertChatMessage
Instruct Avatar Generation	agents/director/instructAvatarGeneration
Log Director Action	agents/director/LogAction
Persist Character	agents/director/PersistCharacter
Scene Direction	agents/director/SceneDirection
Director Settings	agents/director/Settings
Wsh Activate Character	agents/director/wshActivateCharacter
Wsh Dectivate Character	agents/director/wshDectivateCharacter

Assign Voice

agents/director/AssignVoice

Has the director automatically pick and assign a fitting TTS voice to a character, choosing from the voices available through the ready TTS APIs (global and scene voice libraries). Does nothing when automatic voice assignment is disabled in the director settings or when no voices are available.

Inputs

Input	Type	Description
state	any	The graph state
character	character	The character to assign a voice to

Outputs

Output	Type	Description
state	any	The state input, passed through
character	character	The character, passed through
voice	tts/voice	The character's voice after assignment (may be unset if assignment was skipped)

On Persist Character Generate Visual

agents/director/events/onPersistCharacterGenerateVisual

Node module (base type core/Event) defined in src/talemate/agents/director/modules/on-persist-character-generate-visual.json.

Properties

Property	Type	Default	Description
event_name	str	"agent.director.character_management.after_persist_character"	Event to listen for
auto_register	bool	False	Self-register from the node registry instead of requiring placement in the scene loop graph

Direct Actor

agents/director/fn/directActor

Node module (base type core/functions/Function) defined in src/talemate/agents/director/modules/direct-actor.json.

Outputs

Output	Type	Description
fn	function
name	str
allow_multiple_calls	bool
ai_callback	focal/callback

Properties

Property	Type	Default	Description
name	str	"direct_actor"	The name of the function
allow_multiple_calls	bool	False	Function can be called multiple times during AI Function Calling

Direct Narrator

agents/director/fn/directNarrator

Node module (base type core/functions/Function) defined in src/talemate/agents/director/modules/direct-narrator.json.

Outputs

Output	Type	Description
fn	function
name	str
allow_multiple_calls	bool
ai_callback	focal/callback

Properties

Property	Type	Default	Description
name	str	"direct_narrator"	The name of the function
allow_multiple_calls	bool	False	Function can be called multiple times during AI Function Calling

Yield To Actor

agents/director/fn/yieldToActor

Node module (base type core/functions/Function) defined in src/talemate/agents/director/modules/yield-to-actor.json.

Outputs

Output	Type	Description
fn	function
name	str
allow_multiple_calls	bool
ai_callback	focal/callback

Properties

Property	Type	Default	Description
name	str	"yield_to_user"	The name of the function
allow_multiple_calls	bool	False	Function can be called multiple times during AI Function Calling

Yield To User

agents/director/fn/yieldToUser

Node module (base type core/functions/Function) defined in src/talemate/agents/director/modules/yield-to-user.json.

Outputs

Output	Type	Description
fn	function
name	str
allow_multiple_calls	bool
ai_callback	focal/callback

Properties

Property	Type	Default	Description
name	str	"yield_to_user"	The name of the function
allow_multiple_calls	bool	False	Function can be called multiple times during AI Function Calling

Roll Dice

agents/director/gameplay/rollDice

Node module (base type core/Graph) defined in src/talemate/agents/director/modules/roll-dice.json.

Inputs

Input	Type	Description
state	any
min	int
max	int
reason	str
emit_system_message	bool	(optional)
modifier	int	(optional)

Outputs

Output	Type	Description
state	any
min	int
max	int
reason	str
emit_system_message	bool
result	int
formatted_result	str

Insert Chat Message

agents/director/InsertChatMessage

Inserts a message into the director chat. Can optionally display an asset from scene_assets by providing an asset_id.

Inputs

Input	Type	Description
state	any
message	str
source	str	(optional)
asset_id	str	(optional)

Outputs

Output	Type	Description
state	any
chat_message	director/chat_message
message	str
source	str
asset_id	str

Properties

Property	Type	Default	Description
message	text	""	The message to insert
source	str	"user"	The source of the message. Choices: user, director.
asset_id	str	""	Optional asset ID from scene_assets library to display

Instruct Avatar Generation

agents/director/instructAvatarGeneration

Node module (base type core/Graph) defined in src/talemate/agents/director/modules/instruct-avatar-generation.json.

Inputs

Input	Type	Description
state	any
character	character
set_current_avatar	bool	(optional)
set_default_avatar	bool	(optional)
asset_ctx	asset_attachment_context	(optional)

Outputs

Output	Type	Description
state	any
character	character
set_current_avatar	bool
set_default_avatar	bool
asset_ctx	asset_attachment_context

Log Director Action

agents/director/LogAction

Logs a director action by pushing a DirectorMessage to the scene history and emitting it to the UI. When console_only is true the message is flagged as hidden so it is not shown in the scene, but still appears in the debug console.

Inputs

Input	Type	Description
state	any	The graph state
action	str	The name of the action to log
action_description	str	The description of the action
console_only	bool	Whether to hide the message from the scene (optional)

Outputs

Output	Type	Description
state	any	The state input, passed through

Properties

Property	Type	Default	Description
action	str	""	The action to log
action_description	str	""	The description of the action
console_only	bool	False	Whether to log the action to the console only

Persist Character

agents/director/PersistCharacter

Persists a character that currently only exists as part of the given context as a real character that can actively participate in the scene.

Pre-generated description, dialogue_instructions and example_dialogue inputs (e.g. from an agents/creator/GenerateCharacter node) are used as-is instead of being generated again. When wiring a generated name into character_name, disable the determine_name property so the name is not determined twice.

Inputs

Input	Type	Description
state	any
character_name	str	(optional)
context	str	(optional)
description	str	(optional)
attributes	dict,str	(optional)
dialogue_instructions	str	(optional)
example_dialogue	list	(optional)
is_player	bool	(optional)

Outputs

Output	Type	Description
state	any
character	character

Properties

Property	Type	Default	Description
determine_name	bool	True	Whether to determine the name of the character
is_player	bool	False	Whether the character is a player

Scene Direction

agents/director/SceneDirection

Executes an autonomous scene direction turn (game master mode).

The director analyzes the scene and takes multiple sequential actions until satisfied or hitting the max actions limit, without user interaction.

Skips execution (leaving all outputs unresolved) when scene direction is disabled and always_on is not set, or on the first turn of the scene unless run_immediately is set.

Inputs

Input	Type	Description
state	any	Required state to trigger execution
max_actions	number	(optional) Optional override for max actions per turn (0 = agent default)
is_first_turn	bool	(optional) Optional flag marking this as the scene's first turn
always_on	bool	(optional) Optional override to always execute (ignores agent enabled config)
run_immediately	bool	(optional) Optional flag to run even on the first turn

Outputs

Output	Type	Description
state	any	The input state passed through
actions_taken	list	List of actions executed during the turn
yield_to_user	bool	Whether the director wants to yield to the player
action_count	number	Number of actions taken

Properties

Property	Type	Default	Description
max_actions	int	0	Maximum actions per turn (0 = use agent default). Range: 0 – 20.
always_on	bool	False	Override agent config and always execute scene direction (ignores enabled setting)
run_immediately	bool	False	Run immediately (do not yield first turn)
is_first_turn	bool	False	Is this the first turn of the scene?

Director Settings

agents/director/Settings

Base node to render director agent settings.

Every setting of the director agent is exposed as an output socket named after the setting - see the agent's documentation under Agents for what each setting does.

Wsh Activate Character

agents/director/wshActivateCharacter

Node module (base type agents/AgentWebsocketHandler) defined in src/talemate/agents/director/modules/wsh-activate-character.json.

Outputs

Output	Type	Description
fn	function
name	str
allow_multiple_calls	bool
ai_callback	focal/callback

Properties

Property	Type	Default	Description
name	str	"activate_character"	The name of the handler
agent	str	"director"	The agent to register the handler on. Choices are generated at runtime.

Wsh Dectivate Character

agents/director/wshDectivateCharacter

Node module (base type agents/AgentWebsocketHandler) defined in src/talemate/agents/director/modules/wsh-dectivate-character.json.

Outputs

Output	Type	Description
fn	function
name	str
allow_multiple_calls	bool
ai_callback	focal/callback

Properties

Property	Type	Default	Description
name	str	"deactivate_character"	The name of the handler
agent	str	"director"	The agent to register the handler on. Choices are generated at runtime.