Action System Reference

Components for parsing and handling action tags from AI responses.

EstuaryActionManager

Parses action tags from bot responses and dispatches events.

import { EstuaryActionManager, ParsedAction } from 'estuary-lens-studio-sdk';

Constructor

const manager = new EstuaryActionManager(character);

Methods

Method	Parameters	Description
`setTargetCharacter()`	`character`	Set character to monitor
`registerAction()`	`charId, name, desc?`	Register an action
`registerActions()`	`charId, names[]`	Register multiple actions
`unregisterAction()`	`charId, name`	Unregister action
`isActionRegistered()`	`charId, name`	Check registration
`getRegisteredActions()`	`charId`	Get registered actions
`setActionEnabled()`	`charId, name, enabled`	Enable/disable action
`onAction()`	`name, handler`	Subscribe to action
`onActions()`	`names[], handler`	Subscribe to multiple
`onAnyAction()`	`handler`	Subscribe to all
`startListening()`	-	Start monitoring responses
`stopListening()`	-	Stop monitoring
`clearHistory()`	-	Clear action history
`wasActionTriggered()`	`name, withinMs?`	Check if triggered
`getActionsByName()`	`name`	Get actions by name
`dispose()`	-	Clean up resources

Properties

Property	Type	Description
`currentAction`	`ParsedAction \| null`	Most recent action
`actionHistory`	`ParsedAction[]`	All triggered actions
`isListening`	`boolean`	Monitoring status
`debugLogging`	`boolean`	Debug mode
`onlyFinalResponses`	`boolean`	Parse only final responses
`maxHistorySize`	`number`	Max history entries
`strictMode`	`boolean`	Only trigger registered

EstuaryActions

Global action event system for easy access from any script.

import { EstuaryActions, ParsedAction } from 'estuary-lens-studio-sdk';

Static Methods

Method	Parameters	Returns	Description
`on()`	`actionName, handler`	`() => void`	Subscribe to action (returns unsubscribe)
`onAny()`	`handler`	`() => void`	Subscribe to all actions (returns unsubscribe)
`wasTriggered()`	`actionName`	`boolean`	Check if action was triggered
`getManager()`	-	`EstuaryActionManager`	Get underlying manager instance
`setManager()`	`manager: EstuaryActionManager`	`void`	Set the manager instance (called internally)

Static Properties

Property	Type	Description
`currentAction`	`ParsedAction \| null`	Most recent action
`actionHistory`	`ParsedAction[]`	Action history

Usage Example

// Subscribe to specific action
const unsub = EstuaryActions.on("wave", (action) => {
    print(`Wave at ${action.timestamp}`);
});

// Unsubscribe
unsub();

// Subscribe to all actions
EstuaryActions.onAny((action) => {
    print(`Action: ${action.name}`);
});

ParsedAction

Represents a parsed action from bot response. Used by both EstuaryActionManager and EstuaryActions.

interface ParsedAction {
    name: string;       // Action name (e.g., "wave", "sit")
    tag: string;        // Full tag text (e.g., '<action name="wave" />')
    messageId: string;  // Source message ID
    timestamp: number;  // Detection time (Date.now())
}

RegisteredAction

Represents a registered action definition.

interface RegisteredAction {
    name: string;           // Action name
    description?: string;   // Optional description
    enabled: boolean;       // Whether action is enabled
}

Action Tag Format

The action system parses <action> tags embedded in AI responses:

<action name="wave" />
<action name="sit" />
<action name='dance' />

Regex pattern: /<action\s+name\s*=\s*["']([^"']+)["']\s*\/?>/gi

EstuaryActionManager​

Constructor​

Methods​

Properties​

EstuaryActions​

Static Methods​

Static Properties​

Usage Example​

ParsedAction​

RegisteredAction​

Action Tag Format​