create_encounter
Generate D&D 5e combat encounters with participants, terrain, and initiative tracking for RPG sessions.
Instructions
Create a D&D 5e combat encounter with participants, terrain, and initiative tracking
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | ||
| participants | Yes | ||
| terrain | No | ||
| lighting | No | bright | |
| surprise | No |
Implementation Reference
- src/modules/combat.ts:953-1007 (handler)The main handler function for the create_encounter tool. Validates input, generates encounter ID, rolls initiatives, sorts order, stores state, and returns formatted output.export function createEncounter(input: CreateEncounterInput): string { // Validate unique participant IDs const ids = new Set<string>(); for (const p of input.participants) { if (ids.has(p.id)) { throw new Error(`Duplicate participant ID: ${p.id}`); } ids.add(p.id); } // Generate unique encounter ID const encounterId = randomUUID(); // Apply defaults const terrain = input.terrain || { width: 20, height: 20 }; const lighting = input.lighting || 'bright'; const surpriseSet = new Set(input.surprise || []); // Roll initiative for all participants and mark surprised const participantsWithInitiative = input.participants.map(p => { const initiativeRoll = rollD20(); const initiative = initiativeRoll + (p.initiativeBonus || 0); const surprised = surpriseSet.has(p.id); return { ...p, initiative, surprised, }; }); // Sort by initiative (highest first) participantsWithInitiative.sort((a, b) => { if (b.initiative !== a.initiative) { return b.initiative - a.initiative; } // Tie-breaker: higher initiative bonus goes first return (b.initiativeBonus || 0) - (a.initiativeBonus || 0); }); // Store encounter state const encounterState: EncounterState = { id: encounterId, round: 1, participants: participantsWithInitiative, terrain, lighting, currentTurnIndex: 0, }; encounterStore.set(encounterId, encounterState); // Format output return formatEncounterCreated(encounterState); }
- src/modules/combat.ts:923-930 (schema)Zod schema defining the input structure for create_encounter, including participants, terrain, lighting, and surprise.export const createEncounterSchema = z.object({ seed: z.string().optional(), participants: z.array(ParticipantSchema).min(1), terrain: TerrainSchema.optional(), lighting: LightSchema.default('bright'), surprise: z.array(z.string()).optional(), });
- src/registry.ts:422-439 (registration)Tool registration in the central registry, defining name, description, input schema (converted to JSON schema), and wrapper handler that validates input and calls the main createEncounter function.create_encounter: { name: 'create_encounter', description: 'Create a D&D 5e combat encounter with participants, terrain, and initiative tracking', inputSchema: toJsonSchema(createEncounterSchema), handler: async (args) => { try { const validated = createEncounterSchema.parse(args); const result = createEncounter(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); } },