mirror of https://github.com/vegu-ai/talemate.git synced 2026-09-02 12:09:31 +02:00

Files

veguAI 89e01ac138 Node editor node reference glossary (#107 ) (#111 )

* docs: complete node editor node reference glossary (#107) - generated by new nodes.tools glossary subcommand, 47 categorized pages covering all 403 nodes, docstring gap fixes, help-agent docs-index entries

* docs: fix Jinja2 Format discoverability - document dynamic-input template variables, move node to string page, link key inference from dynamic-input notes, strip links from index summaries

* help agent: keep node reference out of the chat prompt - collapse glossary entries to one pointer line (~19k chars saved), agent retrieves node info via search_docs/read_doc tool calls

* help agent: replace in-prompt docs index with find_docs lookup tool - prompt carries a 13-line section overview (~1.5k chars vs ~66k), pages located via keyword-scored find_docs at runtime

* changelog: help agent prompt slimming + find_docs lookup

* docs: sort node reference index and nav alphabetically by page title

* review: move module constants into top-of-file constant blocks (glossary MAX_DEFAULT_LENGTH; docs SECTION_DESCRIPTIONS, _FIND_STOPWORDS, FIND_DOCS_LIMIT)

* review: word-boundary find_docs scoring with plural/-ing folds, find_docs+section_overview unit tests, jinja2 template field description override

* docs: help agent overview no longer claims an in-prompt index of all documentation pages

* docs: full node docstring audit pass - 335 classes audited by 5 agents, ~89 accuracy fixes (nonexistent/misnamed sockets, wrong behavior claims), ~94 expansions, 5 factually-wrong PropertyField descriptions corrected, glossary regenerated

2026-07-20 01:49:33 +03:00

9.6 KiB

Raw Blame History

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 and Events concepts). The Get/Set pairs manage the scene's title, description, introduction and content classification, and the storyline modules drive dynamic storylines.

18 nodes.

Node	Registry path
Creative Loop	`scene/CreativeLoop`
Dynamic Storyline	`scene/dynamicStoryline`
Game Loop Actor Iteration	`scene/event/trigger/GameLoopActorIter`
Generate Storyline	`scene/generateStoryline`
Get Content Classification	`scene/GetContentClassification`
Get Story Description	`scene/GetDescription`
Get Story Introduction	`scene/GetIntroduction`
Get Scene Loop State	`scene/GetSceneLoopState`
Get Scene State	`scene/GetSceneState`
Get Story Title	`scene/GetTitle`
Restore Scene	`scene/Restore`
Scene Loop	`scene/SceneLoop`
Select Actor For Turn	`scene/SelectActorForTurn`
Set Content Classification	`scene/SetContentClassification`
Set Story Description	`scene/SetDescription`
Set Introduction	`scene/SetIntroduction`
Set Story Title	`scene/SetTitle`
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`

9.6 KiB Raw Blame History

Scene Nodes

Creative Loop

Dynamic Storyline

Game Loop Actor Iteration

Generate Storyline

Get Content Classification

Get Story Description

Get Story Introduction

Get Scene Loop State

Get Scene State

Get Story Title

Restore Scene

Scene Loop

Select Actor For Turn

Set Content Classification

Set Story Description

Set Introduction

Set Story Title

Unpack Interaction State

9.6 KiB

Raw Blame History