ChatRPG

Instructions

Implementation Reference

• src/modules/data.ts:1070-1109 (handler)

  Core handler function for move_party tool. Parses input with Zod schema, routes to operation-specific handlers (handleMove for movement logic, handlePartyStatus for current location/exits, handlePartyHistory for travel log), handles errors, and returns formatted MCP CallToolResult with ASCII art output.

  export async function moveParty(input: unknown): Promise<{ content: { type: 'text'; text: string }[] }> {
    try {
      const parsed = movePartySchema.parse(input);
  
      let result: string;
  
      // Determine operation type
      const op = (parsed as any).operation || 'move';
  
      switch (op) {
        case 'move':
          result = handleMove(parsed as z.infer<typeof moveOperationSchema>);
          break;
        case 'status':
          result = handlePartyStatus(parsed as z.infer<typeof statusOperationSchema>);
          break;
        case 'history':
          result = handlePartyHistory();
          break;
        default:
          result = createBox('ERROR', ['Unknown operation'], DISPLAY_WIDTH);
      }
  
      return { content: [{ type: 'text' as const, text: result }] };
    } catch (error) {
      const lines: string[] = [];
  
      if (error instanceof z.ZodError) {
        for (const issue of error.issues) {
          lines.push(`${issue.path.join('.')}: ${issue.message}`);
        }
      } else if (error instanceof Error) {
        lines.push(error.message);
      } else {
        lines.push('An unknown error occurred');
      }
  
      return { content: [{ type: 'text' as const, text: createBox('ERROR', lines, DISPLAY_WIDTH) }] };
    }
  }

• src/modules/data.ts:759-788 (schema)

  Zod input schema for move_party tool. Discriminated by operation: 'move' (toLocationId/name, force/unlock/discover flags), 'status' (show hidden exits), 'history' (travel log). Supports fuzzy enums.

  const MovePartyOperationSchema = fuzzyEnum(['move', 'status', 'history'] as const);
  
  /** Move operation schema */
  const moveOperationSchema = z.object({
    operation: z.literal('move').optional().default('move'),
    toLocationId: z.string().optional(),
    toLocationName: z.string().optional(),
    force: z.boolean().optional().default(false),
    unlocked: z.boolean().optional().default(false),
    discovered: z.boolean().optional().default(false),
  });
  
  /** Status operation schema */
  const statusOperationSchema = z.object({
    operation: z.literal('status'),
    showHidden: z.boolean().optional().default(false),
  });
  
  /** History operation schema */
  const historyOperationSchema = z.object({
    operation: z.literal('history'),
  });
  
  /** Combined schema for move_party */
  export const movePartySchema = z.union([
    moveOperationSchema,
    statusOperationSchema,
    historyOperationSchema,
  ]);

• src/registry.ts:1059-1076 (registration)

  Tool registration entry in central registry. Converts Zod schema to JSON Schema for MCP, provides thin wrapper handler that calls the actual moveParty implementation, includes tool description.

  move_party: {
    name: 'move_party',
    description: 'Move the party between connected locations. Operations: move (travel to connected location), status (show current location and exits), history (show travel history). Validates connections, handles locked/hidden passages, one-way paths, and tracks travel history.',
    inputSchema: toJsonSchema(movePartySchema),
    handler: async (args) => {
      try {
        const result = await moveParty(args);
        return 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/modules/data.ts:822-939 (helper)

  Primary helper implementing 'move' operation logic: finds target, validates edge traversal (one-way, locked DC, hidden discovery), updates party location state and history, renders arrival scene with exits.

  function handleMove(input: z.infer<typeof moveOperationSchema>): string {
    // Validate input
    if (!input.toLocationId && !input.toLocationName) {
      return createBox('ERROR', ['Either toLocationId or toLocationName is required'], DISPLAY_WIDTH);
    }
  
    // Find target location
    const target = findLocation(input.toLocationId || input.toLocationName || '');
    if (!target) {
      return createBox('ERROR', [`Location not found: ${input.toLocationId || input.toLocationName}`], DISPLAY_WIDTH);
    }
  
    // Check if already at target
    if (partyState.currentLocationId === target.id) {
      return createBox('ALREADY HERE', [`The party is already at ${target.name}.`], DISPLAY_WIDTH);
    }
  
    // Get current location
    const current = partyState.currentLocationId ? locationStore.get(partyState.currentLocationId) : null;
  
    // If no current location or force, just place the party
    if (!current || input.force) {
      partyState.currentLocationId = target.id;
      partyState.history.push({ locationId: target.id, timestamp: Date.now() });
  
      const lines: string[] = [];
      lines.push(`Location: ${target.name}`);
      if (target.locationType) {
        lines.push(`Type: ${target.locationType}`);
      }
      if (target.lighting) {
        lines.push(`Lighting: ${target.lighting}`);
      }
      if (target.description) {
        lines.push('');
        lines.push(target.description);
      }
  
      // Show exits
      const exits = getExitsForLocation(target.id, false);
      if (exits.length > 0) {
        lines.push('');
        lines.push('Exits:');
        for (const exit of exits) {
          lines.push(`  ${ARROW} ${exit.locationName} (${exit.connectionType})`);
        }
      }
  
      return createBox('PARTY ARRIVED', lines, DISPLAY_WIDTH);
    }
  
    // Check if connected
    const edge = getEdgeBetween(current.id, target.id);
    if (!edge) {
      return createBox('CANNOT TRAVEL', [`${target.name} is not connected to ${current.name}.`], DISPLAY_WIDTH);
    }
  
    // Check one-way
    if (!isEdgeTraversable(edge, current.id)) {
      return createBox('ONE-WAY PATH', [`Cannot travel back through this one-way passage.`], DISPLAY_WIDTH);
    }
  
    // Check locked
    if (edge.locked && !input.unlocked) {
      const lines: string[] = [];
      lines.push(`The ${edge.connectionType} to ${target.name} is locked.`);
      if (edge.lockDC) {
        lines.push(`Lock DC: ${edge.lockDC}`);
      }
      lines.push('');
      lines.push('Use unlocked: true to bypass the lock.');
      return createBox('LOCKED', lines, DISPLAY_WIDTH);
    }
  
    // Check hidden
    if (edge.hidden && !input.discovered && !partyState.discoveredHiddenEdges.has(edge.id)) {
      return createBox('CANNOT TRAVEL', [`No visible path to ${target.name} from here.`], DISPLAY_WIDTH);
    }
  
    // Mark hidden edge as discovered if using discovered flag
    if (edge.hidden && input.discovered) {
      partyState.discoveredHiddenEdges.add(edge.id);
    }
  
    // Perform the move
    const previousLocation = current.name;
    partyState.currentLocationId = target.id;
    partyState.history.push({ locationId: target.id, timestamp: Date.now() });
  
    // Build output
    const lines: string[] = [];
    lines.push(`From: ${previousLocation}`);
    lines.push(`To: ${target.name}`);
    lines.push(`Via: ${edge.connectionType}`);
  
    if (target.locationType) {
      lines.push(`Type: ${target.locationType}`);
    }
    if (target.lighting) {
      lines.push(`Lighting: ${target.lighting}`);
    }
    if (target.description) {
      lines.push('');
      lines.push(target.description);
    }
  
    // Show exits
    const exits = getExitsForLocation(target.id, false);
    if (exits.length > 0) {
      lines.push('');
      lines.push('Exits:');
      for (const exit of exits) {
        lines.push(`  ${ARROW} ${exit.locationName} (${exit.connectionType})`);
      }
    }
  
    return createBox('PARTY MOVED', lines, DISPLAY_WIDTH);
  }

• src/modules/data.ts:748-752 (helper)

  Global in-memory state tracking party's current location ID, travel history stack, and discovered hidden connections. Essential for movement validation and status reporting.

  let partyState: PartyLocationState = {
    currentLocationId: null,
    history: [],
    discoveredHiddenEdges: new Set(),
  };