# 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.

<!-- glossary:generated - everything below this line is generated by `python -m talemate.game.engine.nodes.tools glossary --write` - do not edit -->


_15 nodes._

| Node | Registry path |
| --- | --- |
| [Assign Voice](#assign-voice) | `agents/director/AssignVoice` |
| [On Persist Character Generate Visual](#on-persist-character-generate-visual) | `agents/director/events/onPersistCharacterGenerateVisual` |
| [Direct Actor](#direct-actor) | `agents/director/fn/directActor` |
| [Direct Narrator](#direct-narrator) | `agents/director/fn/directNarrator` |
| [Yield To Actor](#yield-to-actor) | `agents/director/fn/yieldToActor` |
| [Yield To User](#yield-to-user) | `agents/director/fn/yieldToUser` |
| [Roll Dice](#roll-dice) | `agents/director/gameplay/rollDice` |
| [Insert Chat Message](#insert-chat-message) | `agents/director/InsertChatMessage` |
| [Instruct Avatar Generation](#instruct-avatar-generation) | `agents/director/instructAvatarGeneration` |
| [Log Director Action](#log-director-action) | `agents/director/LogAction` |
| [Persist Character](#persist-character) | `agents/director/PersistCharacter` |
| [Scene Direction](#scene-direction) | `agents/director/SceneDirection` |
| [Director Settings](#director-settings) | `agents/director/Settings` |
| [Wsh Activate Character](#wsh-activate-character) | `agents/director/wshActivateCharacter` |
| [Wsh Dectivate Character](#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](../../../agents/index.md) 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. |