ChatRPG

Instructions

Implementation Reference

• src/modules/spatial.ts:1716-1923 (handler)

  The core handler function for 'calculate_movement' tool. It supports three modes: 'path' (A* pathfinding to target), 'reach' (flood-fill reachable squares within movement budget), and 'adjacent' (checks 8 surrounding squares). Integrates with encounter terrain and participant positions for realistic D&D 5e movement costs.
  export function calculateMovement(input: CalculateMovementInput): string { const content: string[] = []; const mode = input.mode || 'path'; // Get encounter state if provided let encounter: ReturnType<typeof getEncounterState> | undefined; let terrain: Map<string, string> = new Map(); let creatures: Map<string, string> = new Map(); if (input.encounterId) { encounter = getEncounterState(input.encounterId); if (!encounter) { throw new Error(`Encounter not found: ${input.encounterId}`); } // Build terrain map if (encounter.terrain) { for (const pos of encounter.terrain.obstacles || []) { terrain.set(pos, 'obstacle'); } for (const pos of encounter.terrain.difficultTerrain || []) { terrain.set(pos, 'difficultTerrain'); } for (const pos of encounter.terrain.water || []) { terrain.set(pos, 'water'); } } // Build creature positions map for (const p of encounter.participants || []) { if (p.position) { creatures.set(`${p.position.x},${p.position.y}`, p.name); } } } const gridWidth = encounter?.terrain?.width || input.gridWidth || 20; const gridHeight = encounter?.terrain?.height || input.gridHeight || 20; const fromPos = { x: input.from.x, y: input.from.y }; switch (mode) { case 'path': { const toPos = { x: input.to!.x, y: input.to!.y }; content.push(centerText('PATH CALCULATION', MOVEMENT_DISPLAY_WIDTH)); content.push(''); content.push(`From: (${fromPos.x}, ${fromPos.y})`); content.push(`To: (${toPos.x}, ${toPos.y})`); content.push(''); content.push(BOX.LIGHT.H.repeat(MOVEMENT_DISPLAY_WIDTH)); content.push(''); // Same position check if (fromPos.x === toPos.x && fromPos.y === toPos.y) { content.push('Distance: 0 feet'); content.push(''); content.push('Already at destination!'); return createBox('PATH', content); } // Simple A* pathfinding const path = findPath(fromPos, toPos, gridWidth, gridHeight, terrain, creatures, input.creaturesBlock); if (path.length === 0) { content.push('STATUS: BLOCKED'); content.push(''); content.push('No path available - destination is unreachable.'); return createBox('PATH', content); } // Calculate total cost let totalCost = 0; let hasDifficultTerrain = false; for (let i = 1; i < path.length; i++) { const pos = path[i]; const key = `${pos.x},${pos.y}`; const terrainType = terrain.get(key) || 'normal'; const cost = TERRAIN_COSTS[terrainType] || 1; if (cost === 2) hasDifficultTerrain = true; totalCost += cost * 5; } content.push(`Distance: ${totalCost} feet`); if (hasDifficultTerrain) { content.push('(includes difficult terrain)'); } content.push(''); // Show path content.push(centerText('PATH WAYPOINTS', MOVEMENT_DISPLAY_WIDTH)); content.push(''); for (let i = 0; i < path.length; i++) { const pos = path[i]; const key = `${pos.x},${pos.y}`; const terrainType = terrain.get(key); let marker = ''; if (i === 0) marker = ' (start)'; else if (i === path.length - 1) marker = ' (end)'; else if (terrainType === 'difficultTerrain') marker = ' [difficult]'; else if (terrainType === 'water') marker = ' [water]'; content.push(` ${i + 1}. (${pos.x}, ${pos.y})${marker}`); } return createBox('PATH', content); } case 'reach': { const movementBudget = input.movement || 30; content.push(centerText('REACHABLE SQUARES', MOVEMENT_DISPLAY_WIDTH)); content.push(''); content.push(`From: (${fromPos.x}, ${fromPos.y})`); content.push(`Movement: ${movementBudget} feet`); content.push(''); content.push(BOX.LIGHT.H.repeat(MOVEMENT_DISPLAY_WIDTH)); content.push(''); // Flood fill to find reachable squares const reachable = findReachable(fromPos, movementBudget, gridWidth, gridHeight, terrain, creatures, input.creaturesBlock); let hasDifficultTerrain = false; for (const pos of reachable) { const key = `${pos.x},${pos.y}`; if (terrain.get(key) === 'difficultTerrain' || terrain.get(key) === 'water') { hasDifficultTerrain = true; break; } } content.push(`Reachable: ${reachable.length} squares`); if (hasDifficultTerrain) { content.push('(movement reduced by difficult terrain)'); } content.push(''); // List reachable positions (limited to prevent huge output) const maxShow = 20; content.push(centerText('POSITIONS', MOVEMENT_DISPLAY_WIDTH)); content.push(''); for (let i = 0; i < Math.min(reachable.length, maxShow); i++) { const pos = reachable[i]; content.push(` (${pos.x}, ${pos.y})`); } if (reachable.length > maxShow) { content.push(` ... and ${reachable.length - maxShow} more`); } return createBox('REACHABLE', content); } case 'adjacent': { content.push(centerText('ADJACENT SQUARES', MOVEMENT_DISPLAY_WIDTH)); content.push(''); content.push(`Position: (${fromPos.x}, ${fromPos.y})`); content.push(''); content.push(BOX.LIGHT.H.repeat(MOVEMENT_DISPLAY_WIDTH)); content.push(''); // Find 8 adjacent squares const adjacent: Array<{ x: number; y: number; status: string }> = []; const directions = [ { dx: -1, dy: -1 }, { dx: 0, dy: -1 }, { dx: 1, dy: -1 }, { dx: -1, dy: 0 }, { dx: 1, dy: 0 }, { dx: -1, dy: 1 }, { dx: 0, dy: 1 }, { dx: 1, dy: 1 }, ]; for (const dir of directions) { const nx = fromPos.x + dir.dx; const ny = fromPos.y + dir.dy; // Check bounds if (nx < 0 || nx >= gridWidth || ny < 0 || ny >= gridHeight) { continue; } const key = `${nx},${ny}`; let status = 'open'; if (terrain.get(key) === 'obstacle') { status = 'blocked (obstacle)'; } else if (creatures.has(key)) { status = `occupied (${creatures.get(key)})`; } else if (terrain.get(key) === 'difficultTerrain') { status = 'difficult terrain'; } else if (terrain.get(key) === 'water') { status = 'water'; } adjacent.push({ x: nx, y: ny, status }); } content.push(`Adjacent: ${adjacent.length} squares`); content.push(''); content.push(centerText('POSITIONS', MOVEMENT_DISPLAY_WIDTH)); content.push(''); for (const pos of adjacent) { content.push(` (${pos.x}, ${pos.y}) - ${pos.status}`); } return createBox('ADJACENT', content); } default: throw new Error(`Unknown mode: ${mode}`); } }
• src/modules/spatial.ts:1675-1693 (schema)

  Zod input validation schema for the calculate_movement tool, defining parameters like mode (path/reach/adjacent), positions, movement budget, grid size, and options for terrain/creature blocking.
  export const calculateMovementSchema = z.object({ mode: MovementModeSchema.default('path'), encounterId: z.string().optional(), from: MovementPositionSchema, to: MovementPositionSchema.optional(), movement: z.number().min(0).default(30), gridWidth: z.number().min(5).max(100).default(20), gridHeight: z.number().min(5).max(100).default(20), creaturesBlock: z.boolean().default(false), }).refine((data) => { // Path mode requires 'to' position if (data.mode === 'path' && !data.to) { return false; } return true; }, { message: 'Path mode requires "to" position', });
• src/registry.ts:715-732 (registration)

  Registration of the 'calculate_movement' tool in the central tool registry. Converts Zod schema to JSON Schema and wraps the handler with validation and error handling.
  calculate_movement: { name: 'calculate_movement', description: 'Calculate movement paths, reachable squares, or adjacent squares with terrain support', inputSchema: toJsonSchema(calculateMovementSchema), handler: async (args) => { try { const validated = calculateMovementSchema.parse(args); const result = calculateMovement(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); } },