Scene Message Nodes

Create and manipulate messages in the scene log: character, narrator and director messages, message versions, context visibility and message metadata.

6 nodes.

Node	Registry path
Add Message Version	scene/message/AddMessageVersion
Character Message	scene/message/CharacterMessage
Director Message	scene/message/DirectorMessage
Narrator Message	scene/message/NarratorMessage
Toggle Message Context Visibility	scene/message/ToggleMessageContextVisibility
Unpack Message Meta	scene/message/UnpackMeta

Add Message Version

scene/message/AddMessageVersion

Append a new version to a message's revision stack and make it the active canonical.

Typical use: hook game_loop_new_message (or push_history), rewrite the message body, and have the prior canonical preserved on the stack so the user can navigate back to it via the revision arrows in chat. The prior version stays at its existing index with its own source/reason intact — this node only appends and shifts the active pointer.

Only valid for message types the revision UI can walk: CharacterMessage, NarratorMessage, ContextInvestigationMessage (i.e. anything with _supports_versions = True). Anything else raises InputValueError — filter the message type before reaching this node.

For CharacterMessage, new_text is auto-prefixed with "Name: " if missing, matching the convention in scene/message/CharacterMessage.

Inputs

Input	Type	Description
state	any	The graph state
message	message_object	The SceneMessage to append a version to (required)
new_text	str	The new canonical text (required)
source	str	(optional) Version source label (optional, overrides property)
reason	str	Free-form annotation rendered alongside the source badge (optional)

Outputs

Output	Type	Description
state	any	The state input, passed through
message	message_object	The same SceneMessage instance (post-append)
new_text	str	Passthrough of new_text
source	str	Passthrough of source actually used
reason	str	Passthrough of reason actually used
version	any	The MessageVersion instance that was appended

Properties

Property	Type	Default	Description
source	str	"custom"	The source label attached to the new version entry. Choices: original, revision, regenerate, continue, custom.
reason	str	""	Free-form annotation rendered alongside the source badge in the revision navigator

Character Message

scene/message/CharacterMessage

Creates a character message from a character and a message

The message text is automatically prefixed with the character's name ("Name: ...") if it isn't already. The character's current avatar (if set) is captured on the message at creation time.

Inputs

Input	Type	Description
character	character	The character object
message	str	The message to send
source	str	(optional) The source of the message - player or ai, so whether the message is result of user input or AI generated
from_choice	str	(optional) For player messages this indicates that the message was generated from a choice selection, for ai sourced messages this indicates the instruction that was followed

Outputs

Output	Type	Description
message	message_object	The message object (this is a scene_message.CharacterMessage instance)

Properties

Property	Type	Default	Description
source	str	"player"	The source of the message. Choices: player, ai.

Director Message

scene/message/DirectorMessage

Creates a director message

Inputs

Input	Type	Description
message	str	The message to send
source	str	(optional) The source of the message - player or ai, so whether the message is result of user input or AI generated
meta	dict	(optional) A dictionary of meta information to attach to the message. Can hold the character name that the message is related to.
character	character	(optional) The character object that the message is related to
action	str	(optional) Describes the director action
subtype	str	(optional) The subtype of the director message, used for further categorization

Outputs

Output	Type	Description
message	message_object	The message object (this is a scene_message.DirectorMessage instance)
source	str	The source input, passed through
meta	dict	The meta input, passed through
character	character	The character input, passed through
action	str	The action input, passed through
subtype	str	The subtype input, passed through

Properties

Property	Type	Default	Description
source	str	"ai"	The source of the message. Choices: player, ai.
action	str	"actor_instruction"	Describes the director action. Choices: actor_instruction, user_direction.
subtype	str	unset	The subtype of the director message, used for further categorization of the message. Choices: function_call, user_direction.

Narrator Message

scene/message/NarratorMessage

Creates a narrator message

Inputs

Input	Type	Description
message	str	The message to send
source	str	(optional) The source of the message - player or ai, so whether the message is result of user input or AI generated
meta	dict	(optional) A dictionary of meta information to attach to the message. This will generally be arguments and function name that was called on the narrator agent to generate the message and will be used when regenerating the message.

Outputs

Output	Type	Description
message	message_object	The message object (this is a scene_message.NarratorMessage instance)

Properties

Property	Type	Default	Description
source	str	"ai"	The source of the message. Choices: player, ai.

Toggle Message Context Visibility

scene/message/ToggleMessageContextVisibility

Hide or show a message. Hidden messages are not displayed to the AI.

Inputs

Input	Type	Description
message	message_object	The message object

Outputs

Output	Type	Description
message	message_object	The message object

Properties

Property	Type	Default	Description
hidden	bool	False	Whether the message is hidden

Unpack Message Meta

scene/message/UnpackMeta

Unpacks a message meta dictionary into arguments

Inputs

Input	Type	Description
meta	dict	The meta dictionary

Outputs

Output	Type	Description
agent_name	str	The agent name
function_name	str	The function name
arguments	dict	The arguments dictionary