place_prop

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);
      }
    },
  },