# Scene Nodes

Scene lifecycle and metadata. The **Scene Loop** module is the heart of a playable scene — it processes turns, input and events (see the [Command Module](../../core-concepts/command_module.md) and [Events](../../core-concepts/events.md) concepts). The Get/Set pairs manage the scene's title, description, introduction and content classification, and the storyline modules drive dynamic storylines.

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


_18 nodes._

| Node | Registry path |
| --- | --- |
| [Creative Loop](#creative-loop) | `scene/CreativeLoop` |
| [Dynamic Storyline](#dynamic-storyline) | `scene/dynamicStoryline` |
| [Game Loop Actor Iteration](#game-loop-actor-iteration) | `scene/event/trigger/GameLoopActorIter` |
| [Generate Storyline](#generate-storyline) | `scene/generateStoryline` |
| [Get Content Classification](#get-content-classification) | `scene/GetContentClassification` |
| [Get Story Description](#get-story-description) | `scene/GetDescription` |
| [Get Story Introduction](#get-story-introduction) | `scene/GetIntroduction` |
| [Get Scene Loop State](#get-scene-loop-state) | `scene/GetSceneLoopState` |
| [Get Scene State](#get-scene-state) | `scene/GetSceneState` |
| [Get Story Title](#get-story-title) | `scene/GetTitle` |
| [Restore Scene](#restore-scene) | `scene/Restore` |
| [Scene Loop](#scene-loop) | `scene/SceneLoop` |
| [Select Actor For Turn](#select-actor-for-turn) | `scene/SelectActorForTurn` |
| [Set Content Classification](#set-content-classification) | `scene/SetContentClassification` |
| [Set Story Description](#set-story-description) | `scene/SetDescription` |
| [Set Introduction](#set-introduction) | `scene/SetIntroduction` |
| [Set Story Title](#set-story-title) | `scene/SetTitle` |
| [Unpack Interaction State](#unpack-interaction-state) | `scene/UnpackInteractionState` |

## Creative Loop

`scene/CreativeLoop`

Node module (base type `scene/SceneLoop`) defined in `src/talemate/game/engine/nodes/modules/scene/creative-loop.json`.

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `trigger_game_loop` | `bool` | `False` | Trigger the game loop event |

## Dynamic Storyline

`scene/dynamicStoryline`

Node module (base type `core/Event`) defined in `src/talemate/game/engine/nodes/modules/scene/dynamic-storyline.json`.

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `event_name` | `str` | `"scene_loop_init"` | Event to listen for |
| `auto_register` | `bool` | `False` | Self-register from the node registry instead of requiring placement in the scene loop graph |

## Game Loop Actor Iteration

`scene/event/trigger/GameLoopActorIter`

Trigger the game loop actor iteration event.

In a most basic setup you will trigger this everytime an actor has had a turn.

After the event is sent, a follow-up character iteration event is also
fired: game_loop_player_character_iter for player characters, or
game_loop_ai_character_iter for AI characters.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `trigger` | `any` | Trigger input to activate the node |
| `actor` | `actor` | The actor that has had a turn |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `event` | `event` | The event object that was sent |

## Generate Storyline

`scene/generateStoryline`

Node module (base type `core/Graph`) defined in `src/talemate/game/engine/nodes/modules/scene/generate-storyline.json`.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `topic` | `str` |  |
| `analysis_instructions` | `str` | (optional) |
| `analysis_enabled` | `bool` | (optional) |
| `state` | `any` |  |
| `intro_length` | `int` | (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` |  |
| `text` | `str` |  |
| `theme` | `str` |  |

## Get Content Classification

`scene/GetContentClassification`

Get the content classification text for the scene

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `content_classification` | `str` |  |

## Get Story Description

`scene/GetDescription`

Get the description text for the scene

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `description` | `str` |  |

## Get Story Introduction

`scene/GetIntroduction`

Get the introduction text for the scene

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `introduction` | `str` |  |

## Get Scene Loop State

`scene/GetSceneLoopState`

Returns the current scene loop states

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `dict` | The current node state, this is the state of the graph currently being processed |
| `parent` | `dict` | The parent node state, this is the state of the graph that contains the current graph |
| `shared` | `dict` | The shared state, this is the state shared between all graphs |

## Get Scene State

`scene/GetSceneState`

Gets some basic information about the scene

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `characters` | `list` | A list of characters in the scene |
| `active` | `bool` | Whether the scene is active |
| `auto_save` | `bool` | Whether auto save is enabled |
| `auto_progress` | `bool` | Whether auto progress is enabled |
| `scene` | `scene` | The scene instance |

## Get Story Title

`scene/GetTitle`

Get the title text for the scene

Falls back to the scene name if no title is set.

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `title` | `str` | The scene title (or scene name, or empty string) |

## Restore Scene

`scene/Restore`

Restore the scene to its restore point

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |

## Scene Loop

`scene/SceneLoop`

The main scene loop node

It will loop through the scene graph until the loop is broken.

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `trigger_game_loop` | `bool` | `True` | Trigger the game loop event |

## Select Actor For Turn

`scene/SelectActorForTurn`

Node module (base type `core/Graph`) defined in `src/talemate/game/engine/nodes/modules/scene/select-actor-for-turn.json`.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` |  |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` |  |
| `character` | `character` |  |
| `player` | `bool` |  |
| `ai` | `bool` |  |

## Set Content Classification

`scene/SetContentClassification`

Set the content classification text for the scene

Raises an error if the text is longer than max_length characters.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |
| `content_classification` | `str` | The content classification text |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |
| `content_classification` | `str` | The content classification text |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `content_classification` | `str` | `""` | The content classification text |
| `max_length` | `int` | `75` | The maximum length of the content classification text (characters, NOT tokens) |

## Set Story Description

`scene/SetDescription`

Set the description text for the scene

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` |  |
| `description` | `str` |  |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` |  |
| `description` | `str` |  |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `description` | `text` | `""` | The description text |

## Set Introduction

`scene/SetIntroduction`

Set the introduction text for the scene

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |
| `introduction` | `str` | The introduction text |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `introduction` | `text` | `unset` | The introduction text |
| `emit_history` | `bool` | `True` | Whether to re-emit the entire history of the scene |

## Set Story Title

`scene/SetTitle`

Set the title text for the scene

Raises an error if the new title is empty.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |
| `new_title` | `str` | The new title text |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |
| `new_title` | `str` | The new title text |
| `old_title` | `str` | The previous title (or scene name if no title was set) |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `new_title` | `str` | `""` | new_title |
| `stroy_title` | `str` | `""` | The title text |

## Unpack Interaction State

`scene/UnpackInteractionState`

Will take an interaction state and unpack it into the individual fields

Inputs
- interaction_state `interaction_state`

Outputs
- act_as `str`
- from_choice `str`
- input `str`
- reset_requested `bool`

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `interaction_state` | `interaction_state` |  |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `act_as` | `str` |  |
| `from_choice` | `str` |  |
| `input` | `str` |  |
| `reset_requested` | `bool` |  |