ChatRPG

Instructions

Implementation Reference

• src/modules/spatial.ts:1435-1641 (handler)

  The core handler function for the place_prop tool. Handles all operations: place (create new prop), list (show all props), remove (delete by ID), update (modify properties), move (relocate prop). Integrates with encounter terrain bounds, validates positions, generates unique IDs, and stores props in per-encounter memory. Returns formatted ASCII output.
  export function placeProp(input: PlacePropInput): string { const content: string[] = []; const operation = input.operation || 'place'; // Validate encounter exists const encounter = getEncounterState(input.encounterId); if (!encounter) { throw new Error(`Encounter not found: ${input.encounterId}`); } // Get grid bounds from terrain const gridWidth = encounter.terrain?.width || 20; const gridHeight = encounter.terrain?.height || 20; // Initialize props array for this encounter if needed if (!encounterProps.has(input.encounterId)) { encounterProps.set(input.encounterId, []); } const props = encounterProps.get(input.encounterId)!; switch (operation) { case 'place': { // Validate position bounds const pos = input.position!; if (pos.x < 0 || pos.x >= gridWidth || pos.y < 0 || pos.y >= gridHeight) { throw new Error(`Position (${pos.x}, ${pos.y}) is out of bounds (grid is ${gridWidth}x${gridHeight})`); } // Create new prop const prop: Prop = { id: generatePropId(), name: input.name!, type: input.type!, position: { x: pos.x, y: pos.y, z: pos.z ?? 0 }, }; // Add optional properties if (input.state !== undefined) prop.state = input.state; if (input.locked !== undefined) prop.locked = input.locked; if (input.lockDC !== undefined) prop.lockDC = input.lockDC; if (input.coverType !== undefined) prop.coverType = input.coverType; if (input.blocksMovement !== undefined) prop.blocksMovement = input.blocksMovement; if (input.destructible !== undefined) { prop.destructible = input.destructible; if (input.hp !== undefined) { prop.hp = input.hp; prop.maxHp = input.hp; } if (input.ac !== undefined) prop.ac = input.ac; } if (input.size !== undefined) prop.size = input.size; if (input.description !== undefined) prop.description = input.description; if (input.hidden !== undefined) prop.hidden = input.hidden; if (input.trapDC !== undefined) prop.trapDC = input.trapDC; if (input.trapDamage !== undefined) prop.trapDamage = input.trapDamage; if (input.trigger !== undefined) prop.trigger = input.trigger; props.push(prop); // Build output content.push(centerText('PROP PLACED', PROP_DISPLAY_WIDTH)); content.push(''); content.push(`Name: ${prop.name}`); content.push(`Type: ${prop.type}`); content.push(`Position: (${prop.position.x}, ${prop.position.y}, ${prop.position.z ?? 0})`); content.push(`ID: ${prop.id}`); content.push(''); content.push(BOX.LIGHT.H.repeat(PROP_DISPLAY_WIDTH)); content.push(''); // Show properties content.push(centerText('PROPERTIES', PROP_DISPLAY_WIDTH)); content.push(''); if (prop.state) content.push(`State: ${prop.state}`); if (prop.size) content.push(`Size: ${prop.size}`); if (prop.coverType) content.push(`Cover: ${prop.coverType}`); if (prop.blocksMovement) content.push('Blocks Movement: Yes'); if (prop.destructible) { content.push('Destructible: Yes'); if (prop.hp) content.push(`HP: ${prop.hp}`); if (prop.ac) content.push(`AC: ${prop.ac}`); } if (prop.locked) { content.push('Locked: Yes'); if (prop.lockDC) content.push(`Lock DC: ${prop.lockDC}`); } if (prop.hidden) content.push('Hidden: Yes'); if (prop.trapDC) content.push(`Trap DC: ${prop.trapDC}`); if (prop.trapDamage) content.push(`Trap Damage: ${prop.trapDamage}`); if (prop.trigger) content.push(`Trigger: ${prop.trigger}`); if (prop.description) { content.push(''); content.push(`Description: ${prop.description}`); } return createBox('PROP PLACED', content); } case 'list': { content.push(centerText('ENCOUNTER PROPS', PROP_DISPLAY_WIDTH)); content.push(''); content.push(`Encounter: ${input.encounterId}`); content.push(`Total Props: ${props.length}`); content.push(''); content.push(BOX.LIGHT.H.repeat(PROP_DISPLAY_WIDTH)); content.push(''); if (props.length === 0) { content.push('No props placed.'); } else { for (const prop of props) { content.push(`${prop.name} (${prop.type})`); content.push(` ID: ${prop.id}`); content.push(` Position: (${prop.position.x}, ${prop.position.y}, ${prop.position.z ?? 0})`); if (prop.state) content.push(` State: ${prop.state}`); content.push(''); } } return createBox('PROP LIST', content); } case 'remove': { const propIndex = props.findIndex(p => p.id === input.propId); if (propIndex === -1) { throw new Error(`Prop not found: ${input.propId}`); } const removedProp = props.splice(propIndex, 1)[0]; content.push(centerText('PROP REMOVED', PROP_DISPLAY_WIDTH)); content.push(''); content.push(`Name: ${removedProp.name}`); content.push(`Type: ${removedProp.type}`); content.push(`ID: ${removedProp.id}`); content.push(''); content.push('Prop has been removed from the encounter.'); return createBox('PROP REMOVED', content); } case 'update': { const prop = props.find(p => p.id === input.propId); if (!prop) { throw new Error(`Prop not found: ${input.propId}`); } // Update properties if (input.state !== undefined) prop.state = input.state; if (input.locked !== undefined) prop.locked = input.locked; if (input.lockDC !== undefined) prop.lockDC = input.lockDC; if (input.coverType !== undefined) prop.coverType = input.coverType; if (input.blocksMovement !== undefined) prop.blocksMovement = input.blocksMovement; if (input.hp !== undefined) prop.hp = input.hp; if (input.hidden !== undefined) prop.hidden = input.hidden; content.push(centerText('PROP UPDATED', PROP_DISPLAY_WIDTH)); content.push(''); content.push(`Name: ${prop.name}`); content.push(`ID: ${prop.id}`); content.push(''); content.push(BOX.LIGHT.H.repeat(PROP_DISPLAY_WIDTH)); content.push(''); content.push(centerText('CURRENT STATE', PROP_DISPLAY_WIDTH)); content.push(''); if (prop.state) content.push(`State: ${prop.state}`); if (prop.locked) content.push('Locked: Yes'); if (prop.hidden) content.push('Hidden: Yes'); content.push(`Position: (${prop.position.x}, ${prop.position.y}, ${prop.position.z ?? 0})`); return createBox('PROP UPDATED', content); } case 'move': { const prop = props.find(p => p.id === input.propId); if (!prop) { throw new Error(`Prop not found: ${input.propId}`); } if (!input.position) { throw new Error('New position required for move operation'); } const newPos = input.position; if (newPos.x < 0 || newPos.x >= gridWidth || newPos.y < 0 || newPos.y >= gridHeight) { throw new Error(`Position (${newPos.x}, ${newPos.y}) is out of bounds`); } const oldPos = { ...prop.position }; prop.position = { x: newPos.x, y: newPos.y, z: newPos.z ?? 0 }; content.push(centerText('PROP MOVED', PROP_DISPLAY_WIDTH)); content.push(''); content.push(`Name: ${prop.name}`); content.push(`ID: ${prop.id}`); content.push(''); content.push(`From: (${oldPos.x}, ${oldPos.y}, ${oldPos.z ?? 0})`); content.push(`To: (${prop.position.x}, ${prop.position.y}, ${prop.position.z ?? 0})`); return createBox('PROP MOVED', content); } default: throw new Error(`Unknown operation: ${operation}`); } }
• src/modules/spatial.ts:1328-1370 (schema)

  Zod input schema for place_prop tool. Defines parameters for all operations (place, remove, update, move, list). Validates required fields per operation (e.g., name/type/position for place, propId for remove/update/move). Supports rich prop attributes: state, locked/lockDC, coverType, blocksMovement, destructible/hp/ac, size, description, hidden, trapDC/damage/trigger.
  export const placePropSchema = z.object({ encounterId: z.string(), operation: PropOperationSchema.default('place'), // For place operation name: z.string().optional(), type: PropTypeSchema.optional(), position: PropPositionSchema.optional(), // For remove/update/move operations propId: z.string().optional(), // Prop properties state: z.string().optional(), // 'open', 'closed', 'on', 'off', etc. locked: z.boolean().optional(), lockDC: z.number().min(1).max(30).optional(), coverType: PropCoverTypeSchema.optional(), blocksMovement: z.boolean().optional(), destructible: z.boolean().optional(), hp: z.number().min(1).optional(), ac: z.number().min(1).max(30).optional(), size: PropSizeSchema.optional(), description: z.string().optional(), // Trap properties hidden: z.boolean().optional(), trapDC: z.number().min(1).max(30).optional(), trapDamage: z.string().optional(), trigger: z.string().optional(), }).refine((data) => { // For place operation, name, type, and position are required if (data.operation === 'place') { return data.name !== undefined && data.type !== undefined && data.position !== undefined; } // For remove/update/move, propId is required if (['remove', 'update', 'move'].includes(data.operation)) { return data.propId !== undefined; } return true; }, { message: 'Place operation requires name, type, and position. Remove/update/move require propId.', });
• src/registry.ts:695-713 (registration)

  MCP tool registration entry. Converts Zod schema to JSON Schema for MCP compatibility. Handler validates inputs with placePropSchema, calls placeProp(validated), and formats success/error responses.
  place_prop: { name: 'place_prop', description: 'Place or manage interactive props on the battlefield (barrels, doors, chests, etc.)', inputSchema: toJsonSchema(placePropSchema), handler: async (args) => { try { const validated = placePropSchema.parse(args); const result = placeProp(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); } }, },