Mirrors/talemate
1
0
Fork 0
mirror of https://github.com/vegu-ai/talemate.git synced 2026-09-02 20:20:40 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
talemate/docs/user-guide/node-editor/reference/nodes/scene.md

378 lines
9.6 KiB
Markdown
Raw Permalink Normal View History

0.39.0 (#274) - **Help Agent** — A new agent that answers questions about Talemate itself — settings, agents, clients, the world editor — grounded in the bundled documentation, and able to change agent and application settings on request. - **Timeline Rollback** — Scrub a slider across a scene's automatic version history, preview the message history at any revision, then roll the scene back in place or fork the revision into a new save. - **Pi Bridge Client** — A new client type that drives generations through the pi coding agent's headless RPC mode, making any model pi can reach usable in Talemate. - **Application Settings** — Settings move out of their modal into an always-available Settings tab, with a single topic-grouped sidebar, a settings search, all API keys on one page, and unsaved-change tracking. - **Scene Library** — The home screen is rebuilt as a full-page landing view with a file-tree scene library, cover thumbnails and per-save metadata, scene and save deletion, and a drag-and-drop import dropzone. - **Fast Character Creation** — Generate a character in a single request instead of one prompt per aspect, with a Consolidate multi-select, a token budget, and a Fill in misses pass. Off by default. - **Scene Backdrop** — Set any scene illustration as a backdrop filling the scene view behind the messages, saved with the scene, with configurable text legibility and an Immersive quick-toggle. - **Scene Visual Manager** — World Editor → Scene gains a Visuals tab to browse, upload, generate and delete the scene's backgrounds and illustrations, and set the cover image and backdrop. - **Visual Prompt Finalization** — Post-processing actions — match and replace, or a free-form AI instruction — rewrite image prompts right before they reach the image backend, with per-scene and per-character overrides and reusable template sets. - fixes #271 - fixes #275 Plus 25 improvements and 39 bug fixes — see [CHANGELOG.md](https://github.com/vegu-ai/talemate/blob/prep-0.39.0/CHANGELOG.md#0390) for the full list.
2026-08-29 13:21:22 +03:00
# 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` | |
Reference in New Issue Copy Permalink