Events
List of currently supported events.
Events not listed here
There are some other events defined in the talemate codebase that are purposefully not listed here yet.
The reason for this is that there is an ongoing cleanup process and some of them may not stick around in their current form.
You can of course still hook into them, but be aware that they may change or be removed in the future.
Event Index
Game Loop
game_loop
Triggered at the start of each game loop iteration, before the actor turns are processed. This is the master signal for the per-iteration game loop and runs once per scene loop cycle when the game loop is triggered.
Payload
| Name | Type | Description |
|---|---|---|
scene |
Scene |
The scene object |
had_passive_narration |
bool |
Whether passive narration has already fired this iteration |
game_loop_actor_iter
Triggered after either a player or AI character has had a turn.
Payload
| Name | Type | Description |
|---|---|---|
scene |
Scene |
The scene object |
actor |
Actor |
The actor object |
game_loop |
GameLoopEvent |
The parent game loop event for this iteration |
game_loop_ai_character_iter
Triggered after the AI character has had a turn.
Payload
| Name | Type | Description |
|---|---|---|
scene |
Scene |
The scene object |
character |
Character |
The character object |
game_loop |
GameLoopEvent |
The parent game loop event for this iteration |
game_loop_player_character_iter
Triggered after the player character has had a turn.
Payload
| Name | Type | Description |
|---|---|---|
scene |
Scene |
The scene object |
character |
Character |
The character object |
game_loop |
GameLoopEvent |
The parent game loop event for this iteration |
game_loop_new_message
Triggered when a new message is added to the scene history.
Payload
| Name | Type | Description |
|---|---|---|
scene |
Scene |
The scene object |
message |
SceneMessage |
The message object |
player_turn_start
Triggered when the user turn starts. User input has not yet happened at this point.
Payload
| Name | Type | Description |
|---|---|---|
scene |
Scene |
The scene object |
Scene Loop
scene_init
Triggered once during scene startup, before the scene loop begins running. Use this to perform one-time setup that needs to happen as soon as a scene is loaded.
Payload
| Name | Type | Description |
|---|---|---|
scene |
Scene |
The scene object |
scene_loop_init
Triggered when the scene loop is initialised. Fires once at the start of the very first scene loop cycle, after agent nodes and commands have been registered.
Payload
| Name | Type | Description |
|---|---|---|
scene |
Scene |
The scene object |
scene_loop_init_after
Fires immediately after scene_loop_init. Use this when you need to react to scene loop initialisation but want to run after handlers attached to scene_loop_init have completed.
Payload
| Name | Type | Description |
|---|---|---|
scene |
Scene |
The scene object |
scene_loop_start_cycle
Triggered when the scene loop starts a new cycle.
Payload
| Name | Type | Description |
|---|---|---|
scene |
Scene |
The scene object |
scene_loop_end_cycle
Triggered when the scene loop ends a cycle.
Payload
| Name | Type | Description |
|---|---|---|
scene |
Scene |
The scene object |
scene_loop_error
Triggered when an unhandled exception escapes the scene loop. Internal control-flow exceptions (like ActedAsCharacter and GenerationCancelled) are handled before this fires, so this signal indicates a real error condition that listeners may want to log or recover from.
Payload
| Name | Type | Description |
|---|---|---|
scene |
Scene |
The scene object |
Regenerate Events
regenerate.msg.character
Triggered after regeneration replaces a CharacterMessage.
Payload
| Name | Type | Description |
|---|---|---|
scene |
Scene |
The scene in which regeneration happened |
message |
CharacterMessage |
The regenerated character message |
character |
Character |
The character associated with the message |
regenerate.msg.narrator
Triggered after regeneration replaces a NarratorMessage.
Payload
| Name | Type | Description |
|---|---|---|
scene |
Scene |
The scene object |
message |
NarratorMessage |
The regenerated narrator message |
character |
None |
Not applicable (always None) |
regenerate.msg.reinforcement
Triggered when a ReinforcementMessage is regenerated.
Payload
| Name | Type | Description |
|---|---|---|
scene |
Scene |
The scene object |
message |
ReinforcementMessage |
The regenerated reinforcement message |
character |
None |
Not applicable |
regenerate.msg.context_investigation
Triggered when a ContextInvestigationMessage is regenerated.
Payload
| Name | Type | Description |
|---|---|---|
scene |
Scene |
The scene object |
message |
ContextInvestigationMessage |
The regenerated context investigation message |
character |
None |
Not applicable |
Conversation Agent Events
agent.conversation.before_generate
Emitted just before the Conversation agent sends the prompt to the model.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
ConversationAgent |
The agent instance |
actor |
Actor |
The speaking actor |
character |
Character |
Shortcut to actor.character |
agent.conversation.inject_instructions
Emitted while constructing the prompt, before the prompt is sent to the model.
Handlers can mutate dynamic_instructions to inject extra task instructions.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
ConversationAgent |
The agent instance |
character |
Character |
Target character |
dynamic_instructions |
list[DynamicInstruction] |
Mutable. Append strings here to include them near the top of the prompt |
agent.conversation.generated
Emitted after the Conversation agent receives the model output but before the message is pushed to history.
Handlers can edit generation in-place to clean up or transform the text (the Editor agent does this).
Payload
| Field | Type | Notes |
|---|---|---|
agent |
ConversationAgent |
The agent instance |
actor |
Actor |
Actor that spoke |
character |
Character |
The speaking character |
response |
str |
Mutable. Final text lines that will be turned into messages |
Creator Agent Events
agent.creator.contextual_generate.before
Contextual generation are things like character attributes, details, scene introductions, etc.
Emitted before the Creator agent sends the prompt to the model.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
CreatorAgent |
The agent instance |
character |
Character |
The character that the contextual generation is for |
template_vars |
dict |
Variables that will be fed into the prompt – mutable |
dynamic_instructions |
list[DynamicInstruction] |
Mutable. Push additional DynamicInstruction objects to influence generation |
agent.creator.contextual_generate.after
Emitted after the Creator agent receives the model output but before the message is pushed to history.
Handlers can edit response in-place to clean up or transform the text (the Editor agent does this).
Payload
| Field | Type | Notes |
|---|---|---|
agent |
CreatorAgent |
The agent instance |
response |
str |
Mutable. Final text lines that will be turned into messages |
template_vars |
dict |
Variables that were fed into the prompt – mutable |
dynamic_instructions |
list[DynamicInstruction] |
Mutable. Push additional DynamicInstruction objects to influence generation |
agent.creator.autocomplete.before
Autocomplete generation for character action or narrative text.
Emitted before the Creator agent sends the prompt to the model.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
CreatorAgent |
The agent instance |
input |
str |
The input text that the autocomplete is for |
type |
str |
The type of autocomplete (e.g. dialogue, narrative) |
character |
Character |
The character that the autocomplete is for |
template_vars |
dict |
Variables that will be fed into the prompt – mutable |
dynamic_instructions |
list[DynamicInstruction] |
Mutable. Push additional DynamicInstruction objects to influence generation |
agent.creator.autocomplete.after
Emitted after the Creator agent receives the model output but before the message is pushed to history.
Handlers can edit response in-place to clean up or transform the text (the Editor agent does this).
Payload
| Field | Type | Notes |
|---|---|---|
agent |
CreatorAgent |
The agent instance |
response |
str |
Mutable. Final text lines that will be turned into messages |
input |
str |
The input text that the autocomplete is for |
type |
str |
The type of autocomplete (e.g. dialogue, narrative) |
character |
Character |
The character that the autocomplete is for |
template_vars |
dict |
Variables that were fed into the prompt – mutable |
dynamic_instructions |
list[DynamicInstruction] |
Mutable. Push additional DynamicInstruction objects to influence generation |
Editor Agent Events
agent.editor.revision-revise.before
Emitted before the Editor agent requests the revision-revise prompt.
Handlers can add extra revise instructions via dynamic_instructions or adjust template_vars.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
EditorAgent |
The agent instance |
template_vars |
dict |
Variables that will be fed into the prompt – mutable |
dynamic_instructions |
list[DynamicInstruction] |
Mutable. Push additional DynamicInstruction objects to influence generation |
agent.editor.revision-revise.after
Emitted after the Editor agent receives the model output but before the message is pushed to history.
Handlers can edit response in-place to clean up or transform the text (the Editor agent does this).
Payload
| Field | Type | Notes |
|---|---|---|
agent |
EditorAgent |
The agent instance |
response |
str |
Mutable. Final text lines that will be turned into messages |
template_vars |
dict |
Variables that were fed into the prompt – mutable |
dynamic_instructions |
list[DynamicInstruction] |
Mutable. Push additional DynamicInstruction objects to influence generation |
agent.editor.revision-analysis.before
Emitted before the Editor agent requests the revision-rewrite prompt.
Handlers can add extra analysis instructions via dynamic_instructions or adjust template_vars.
Note
The signal is named revision-analysis.* for historical reasons — it was
introduced when analysis and rewrite were two separate prompts. They are
now combined into a single prompt (editor.revision-rewrite), but the
signal name is kept for backward compatibility.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
EditorAgent |
The agent instance |
template_vars |
dict |
Variables that will be fed into the prompt – mutable |
dynamic_instructions |
list[DynamicInstruction] |
Mutable. Push additional DynamicInstruction objects to influence analysis |
agent.editor.revision-analysis.after
Emitted after the revision-rewrite prompt returns. Intended as a notification hook for observers of the rewrite flow.
Warning
Historically this signal fired between a separate analysis prompt and a
rewrite prompt, with response carrying the raw analysis text that
handlers could mutate before the rewrite ran. Analysis and rewrite are
now combined into a single prompt, so there is no separable "analysis
text" — response is not set on the emission and any mutation is
discarded. Use agent.editor.revision-revise.after
if you need to inspect or replace the final rewritten text.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
EditorAgent |
The agent instance |
template_vars |
dict |
Same vars used for the prompt |
Narrator Agent Events
agent.narrator.before_generate
Emitted before the Narrator agent sends the prompt to the model.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
NarratorAgent |
The agent instance |
agent.narrator.inject_instructions
Emitted while constructing the prompt, before the prompt is sent to the model.
Handlers can mutate dynamic_instructions to inject extra task instructions.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
NarratorAgent |
The agent instance |
dynamic_instructions |
list[DynamicInstruction] |
Mutable. Append strings here to include them near the top of the prompt |
agent.narrator.generated
Emitted after the Narrator agent receives the model output but before the message is pushed to history.
Handlers can edit generation in-place to clean up or transform the text (the Editor agent does this).
Payload
| Field | Type | Notes |
|---|---|---|
agent |
NarratorAgent |
The agent instance |
response |
str |
Mutable. Final text lines that will be turned into messages |
Director Agent Events
agent.director.guide.before_generate
Emitted before the Director guidance module runs to craft guidance text.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
DirectorAgent |
The agent instance |
agent.director.guide.inject_instructions
Runs just after the previous event. Same payload – gives one more chance to adjust dynamic_instructions.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
DirectorAgent |
The agent instance |
dynamic_instructions |
list[DynamicInstruction] |
Mutable. Add strings to influence the prompt |
agent.director.guide.generated
Fires after guidance text is generated, but before it is cached or written to context.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
DirectorAgent |
The agent instance |
response |
str |
Mutable. The guidance text |
agent.director.generate_choices.before_generate
Emitted before the Director generates player choice actions.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
DirectorAgent |
The agent instance |
character |
Character |
The character that the choices are for |
agent.director.generate_choices.inject_instructions
Run before the Director generates player choice actions, gives one more chance to adjust dynamic_instructions.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
DirectorAgent |
The agent instance |
character |
Character |
The character that the choices are for |
dynamic_instructions |
list[DynamicInstruction] |
Mutable. Add strings to influence the prompt |
agent.director.generate_choices.generated
After choices text is ready.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
DirectorAgent |
The agent instance |
response |
str |
Mutable. Text that describes available choices |
choices |
list[str] |
Mutable. List of of generated choices |
character |
Character |
The character that the choices are for |
agent.director.character_management.before_persist_character
Emitted before a new character is persisted into the scene by the director's character management module. The blank Character instance has been created and is attached to the emission, but it has not yet been added to the scene as an actor and no attribute / detail / dialogue templates have been applied.
Useful for adjusting the character object (e.g. seeding default attributes, voice assignment hints, color overrides) before the rest of the persist pipeline runs.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
DirectorAgent |
The agent instance |
character |
Character |
Mutable. The character about to be persisted |
agent.director.character_management.after_persist_character
Emitted after the character has been fully persisted: actor added, generation templates applied, voice assigned (if enabled), character activated and committed to memory. The default on-persist-character-generate-visual module hooks into this signal to optionally generate a portrait.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
DirectorAgent |
The agent instance |
character |
Character |
The character that was just persisted |
World State Agent Events
agent.world_state.time
Emitted when the world state agent advances the time in the scene.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
WorldStateAgent |
The agent instance |
duration |
str |
The duration of the time passage (ISO 8601 duration) |
human_duration |
str |
The human-readable duration of the time passage |
narrative |
str |
The narrative direction of the time passage |
Summarization Agent Events
agent.summarization.scene_analysis.before
Emitted just before the summarizer performs a scene analysis prompt. Handlers can tweak template_vars or inject dynamic_instructions to influence the analysis.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
SummarizeAgent |
The agent instance |
template_vars |
dict |
Mutable. Variables used in the prompt |
analysis_type |
str |
conversation or narration |
dynamic_instructions |
list[DynamicInstruction] |
Mutable |
agent.summarization.scene_analysis.cached
Fired when a cached analysis is reused instead of generating a new one. Same payload as above plus response containing cached analysis text.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
SummarizeAgent |
The agent instance |
template_vars |
dict |
Mutable. Variables used in the prompt |
analysis_type |
str |
conversation or narration |
dynamic_instructions |
list[DynamicInstruction] |
Mutable |
response |
str |
The cached analysis text |
agent.summarization.scene_analysis.before_deep_analysis
Occurs before running deep analysis passes (context investigations). Payload is SceneAnalysisDeepAnalysisEmission.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
SummarizeAgent |
The agent instance |
analysis |
str |
Current analysis text |
analysis_type |
str |
Same as above |
analysis_sub_type |
str |
e.g. progress, query, etc. |
max_content_investigations |
int |
Upper bound for investigations |
character |
Character |
Character in focus (may be None) |
agent.summarization.scene_analysis.after_deep_analysis
Fired immediately after deep analysis completes. Payload identical to previous event; handlers may alter analysis.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
SummarizeAgent |
The agent instance |
analysis |
str |
Current analysis text |
analysis_type |
str |
Same as above |
analysis_sub_type |
str |
e.g. progress, query, etc. |
max_content_investigations |
int |
Upper bound for investigations |
character |
Character |
Character in focus (may be None) |
agent.summarization.scene_analysis.after
Emitted after scene analysis is done and stored in scene state. Payload: SceneAnalysisEmission with response populated.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
SummarizeAgent |
The agent instance |
template_vars |
dict |
Mutable. Variables used in the prompt |
analysis_type |
str |
conversation or narration |
dynamic_instructions |
list[DynamicInstruction] |
Mutable |
response |
str |
The analysis text |
agent.summarization.summarize.before
Emitted before the summarizer performs a summarize prompt. Handlers can tweak template_vars or inject dynamic_instructions to influence the summarize.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
SummarizeAgent |
The agent instance |
text |
str |
The text to summarize |
template_vars |
dict |
Mutable. Variables used in the prompt |
dynamic_instructions |
list[DynamicInstruction] |
Mutable |
extra_instructions |
str |
Mutable. any additional instructions |
generation_options |
GenerationOptions |
Mutable. Generation options |
summarization_history |
list[str] |
Mutable. any previous historical summaries |
agent.summarization.summarize.after
Emitted after the summarizer performs a summarize prompt. Handlers can inspect or replace response.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
SummarizeAgent |
The agent instance |
text |
str |
The text to summarize |
template_vars |
dict |
Mutable. Variables used in the prompt |
dynamic_instructions |
list[DynamicInstruction] |
Mutable |
extra_instructions |
str |
Mutable. any additional instructions |
generation_options |
GenerationOptions |
Mutable. Generation options |
summarization_history |
list[str] |
Mutable. any previous historical summaries |
response |
str |
Mutable. The summary text |
agent.summarization.before_build_archive
Fires at the very top of build_archive, before the summarizer decides whether new archive entries need to be produced. Handlers can short-circuit or instrument the archive-building pass.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
SummarizeAgent |
The agent instance |
generation_options |
GenerationOptions \| None |
Generation options that will be used for any summarization prompts performed during the build |
agent.summarization.after_build_archive
Fires after build_archive has finished processing all eligible history entries (whether or not anything was actually summarized this pass).
Payload
| Field | Type | Notes |
|---|---|---|
agent |
SummarizeAgent |
The agent instance |
generation_options |
GenerationOptions \| None |
The generation options that were used during the build |
agent.summarization.layered_history.finalize
Emitted while finalizing a layered history archive entry. Handlers can inspect or replace the entry before it is added to the layered history. The emission exposes a response property that is a shortcut for entry.text, so handlers that only want to rewrite the summary text can mutate response directly.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
SummarizeAgent |
The agent instance |
entry |
LayeredArchiveEntry \| None |
Mutable. The layered archive entry being finalized |
summarization_history |
list[str] |
Mutable. Previous summaries used as context |
response |
str \| None |
Mutable. Shortcut for entry.text |
agent.summarization.rag_build_sub_instruction
Fires when the summarizer assembles the additional sub-instruction used when fetching RAG context. Mixins (and external handlers) listen on this signal to append guidance about how the retrieved context should be interpreted.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
SummarizeAgent |
The agent instance |
sub_instruction |
str \| None |
Mutable. Concatenated sub-instruction to attach to the RAG query |
TTS Agent Events
agent.tts.prepare.before
Emitted before an optional prepare_fn runs against an audio chunk (e.g. text normalization, audio-tag rewriting, voice selection). Only fires for chunks that declare a prepare_fn.
Payload
| Field | Type | Notes |
|---|---|---|
chunk |
Chunk |
The TTS chunk about to be prepared |
context |
GenerationContext |
The full generation context (all chunks for the current request) |
wav_bytes |
bytes \| None |
Always None at this point |
agent.tts.prepare.after
Fires after a chunk's prepare_fn has run but before audio generation starts. Handlers can inspect (or mutate) the now-prepared chunk.
Payload
| Field | Type | Notes |
|---|---|---|
chunk |
Chunk |
The prepared TTS chunk |
context |
GenerationContext |
The full generation context |
wav_bytes |
bytes \| None |
Always None at this point |
agent.tts.generate.before
Emitted immediately before the chunk is sent to the active TTS backend for synthesis.
Payload
| Field | Type | Notes |
|---|---|---|
chunk |
Chunk |
The TTS chunk about to be synthesised |
context |
GenerationContext |
The full generation context |
wav_bytes |
bytes \| None |
Always None at this point |
agent.tts.generate.after
Fires after the TTS backend returns audio for a chunk and before the audio is played back. Handlers can inspect (or replace) the produced audio via wav_bytes.
Payload
| Field | Type | Notes |
|---|---|---|
chunk |
Chunk |
The TTS chunk that was synthesised |
context |
GenerationContext |
The full generation context |
wav_bytes |
bytes \| None |
Mutable. The synthesised audio bytes (None if generation failed) |
Visual Agent Events
agent.visual.generation.before_generate
Emitted before the visual agent dispatches a generation request to the active backend (text-to-image or image-edit).
Payload
| Field | Type | Notes |
|---|---|---|
agent |
VisualAgent |
The agent instance |
request |
GenerationRequest |
The request that is about to be sent to the backend |
response |
GenerationResponse |
A response shell with id populated; not yet filled in |
agent.visual.generation.after_generate
Fires after a generation request has completed and the resulting image has been delivered to the frontend (and optionally auto-saved as a scene asset). The same emission instance from before_generate is reused, so response now carries the generated image data.
Payload
| Field | Type | Notes |
|---|---|---|
agent |
VisualAgent |
The agent instance |
request |
GenerationRequest |
The original request |
response |
GenerationResponse |
The completed response, including base64 image data |