advance_turn
Progress combat encounters by moving to the next combatant's turn, managing round transitions, updating conditions, and tracking initiative order.
Instructions
Advance to the next combatant's turn in an encounter. Handles round transitions when all combatants have acted, ticks condition durations (removing expired conditions), clears action economy for the previous combatant, and provides death save reminders for combatants at 0 HP. Returns ASCII-formatted turn info with initiative order preview.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| encounterId | Yes | Active encounter ID | |
| processEffects | No | Process start/end turn effects | |
| processAuras | No | Process aura effects |
Implementation Reference
- src/registry.ts:820-838 (registration)Registration of the 'advance_turn' MCP tool, including metadata, input schema reference (advanceTurnSchema), and handler wrapper that validates arguments and delegates to the core advanceTurn function.
advance_turn: { name: 'advance_turn', description: 'Advance to the next combatant\'s turn in an encounter. Handles round transitions when all combatants have acted, ticks condition durations (removing expired conditions), clears action economy for the previous combatant, and provides death save reminders for combatants at 0 HP. Returns ASCII-formatted turn info with initiative order preview.', inputSchema: toJsonSchema(advanceTurnSchema), handler: async (args) => { try { const validated = advanceTurnSchema.parse(args); const result = advanceTurn(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:824-837 (handler)The MCP tool handler for 'advance_turn'. Performs Zod validation on input args using advanceTurnSchema, executes the core advanceTurn(validated) logic, and handles success/error responses.
handler: async (args) => { try { const validated = advanceTurnSchema.parse(args); const result = advanceTurn(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:823-823 (schema)Reference to the Zod input schema (advanceTurnSchema) converted to JSON Schema for MCP tool input validation. Schema imported from './modules/combat.js'.
inputSchema: toJsonSchema(advanceTurnSchema), - src/registry.ts:225-225 (registration)Import statement bringing in the advanceTurn function (core handler logic) and advanceTurnSchema 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';