manage_encounter
Create and manage RPG encounters by linking simulation states with persistent character records, supporting operations like adding participants, tracking combat, and syncing outcomes.
Instructions
Composite tool for encounter management with state synchronization. Operations: create (with characterId linking), get (with verbosity), end (with participantUpdates), commit (sync to persistent characters), list (active encounters). Supports bridging encounter simulation state with persistent character records.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| operation | No | ||
| seed | No | ||
| participants | No | ||
| terrain | No | ||
| lighting | No | bright | |
| surprise | No | ||
| encounterId | No | ||
| verbosity | No | standard | |
| outcome | No | ||
| generateSummary | No | ||
| preserveLog | No | ||
| notes | No | ||
| characterIds | No | Specific characters to commit (defaults to all) | |
| dryRun | No | Preview changes without applying | |
| includeEnded | No | ||
| participant | No | ||
| manualInitiative | No | Manual initiative roll (otherwise rolls automatically) |
Implementation Reference
- src/registry.ts:941-959 (registration)Registration of the 'manage_encounter' tool. Defines name, description, input schema from manageEncounterSchema, and a handler that parses arguments with the schema and executes manageEncounter function.
manage_encounter: { name: 'manage_encounter', description: 'Composite tool for encounter management with state synchronization. Operations: create (with characterId linking), get (with verbosity), end (with participantUpdates), commit (sync to persistent characters), list (active encounters). Supports bridging encounter simulation state with persistent character records.', inputSchema: toJsonSchema(manageEncounterSchema), handler: async (args) => { try { const validated = manageEncounterSchema.parse(args); const result = manageEncounter(validated); return success(result); } catch (err) { if (err instanceof z.ZodError) { const messages = err.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', '); return error(`Validation failed: ${messages}`); } const message = err instanceof Error ? err.message : String(err); return error(message); } }, }, - src/registry.ts:945-957 (handler)The handler function that implements the tool logic: input validation using manageEncounterSchema, execution of core manageEncounter logic, and response formatting with success or error.
handler: async (args) => { try { const validated = manageEncounterSchema.parse(args); const result = manageEncounter(validated); return success(result); } catch (err) { if (err instanceof z.ZodError) { const messages = err.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', '); return error(`Validation failed: ${messages}`); } const message = err instanceof Error ? err.message : String(err); return error(message); } - src/registry.ts:947-947 (schema)Usage of manageEncounterSchema for input validation (schema definition imported from './modules/combat.js').
const validated = manageEncounterSchema.parse(args); - src/registry.ts:225-225 (registration)Import statement for manageEncounter function and manageEncounterSchema from the combat module.
import { manageCondition, manageConditionSchema, createEncounter, createEncounterSchema, executeAction, executeActionSchema, advanceTurn, advanceTurnSchema, rollDeathSave, rollDeathSaveSchema, modifyTerrain, modifyTerrainSchema, renderBattlefield, renderBattlefieldSchema, getEncounter, getEncounterSchema, endEncounter, endEncounterSchema, manageEncounter, manageEncounterSchema } from './modules/combat.js';