dnd-oracle

Instructions

Implementation Reference

• src/tools/analyze-loadout.ts:109-230 (handler)

  The async handler function that implements the logic for 'analyze_loadout', including item lookup, cost/weight/AC calculation, and encumbrance tracking.

  async ({ items, strength_score }) => {
    const found: LoadoutItem[] = [];
    const notFound: string[] = [];
  
    for (const name of items) {
      const eq = getEquipmentByName(db, name);
      if (eq) {
        found.push({ equipment: eq, name: eq.name });
      } else {
        notFound.push(name);
      }
    }
  
    const lines: string[] = [];
    lines.push('# Equipment Loadout Analysis');
    lines.push('');
  
    if (notFound.length > 0) {
      lines.push('## Unrecognized Items');
      lines.push('');
      lines.push('The following items were not found in the SRD equipment list. Use `search_equipment` to find the correct name.');
      for (const name of notFound) {
        lines.push(`- ~~${name}~~ *(not found)*`);
      }
      lines.push('');
    }
  
    if (found.length === 0) {
      lines.push('*No recognized equipment items to analyze.*');
      return {
        content: [{ type: 'text' as const, text: lines.join('\n') }],
      };
    }
  
    // Inventory table
    lines.push('## Inventory');
    lines.push('');
    lines.push('| Item | Category | Cost | Weight |');
    lines.push('|------|----------|------|--------|');
  
    let totalWeight = 0;
    let totalCostGp = 0;
  
    for (const item of found) {
      const eq = item.equipment;
      const weight = eq.weight ?? 0;
      const cost = eq.cost_gp ?? 0;
      totalWeight += weight;
      totalCostGp += cost;
  
      const weightStr = eq.weight !== null ? `${eq.weight} lb.` : '—';
      lines.push(`| ${eq.name} | ${eq.category ?? '—'} | ${formatCost(eq.cost_gp, eq.cost_unit)} | ${weightStr} |`);
    }
  
    lines.push('');
    lines.push(`**Total Weight:** ${totalWeight} lb.`);
    lines.push(`**Total Cost:** ${totalCostGp} gp`);
    lines.push('');
  
    // AC breakdown
    lines.push('## Armor Class');
    lines.push('');
    lines.push(calculateAc(found));
    lines.push('');
  
    // Weapons summary
    const weapons = found.filter(
      (item) => item.equipment.damage_dice !== null,
    );
    if (weapons.length > 0) {
      lines.push('## Weapons');
      lines.push('');
      for (const w of weapons) {
        const eq = w.equipment;
        const props = eq.weapon_properties ?? '';
        const rangeStr =
          eq.range_normal !== null
            ? ` (${eq.range_normal}/${eq.range_long ?? '—'} ft.)`
            : '';
        lines.push(
          `- **${eq.name}**: ${eq.damage_dice} ${eq.damage_type ?? ''}${rangeStr}${props ? ` — ${props}` : ''}`,
        );
      }
      lines.push('');
    }
  
    // Encumbrance
    if (strength_score !== undefined) {
      lines.push('## Encumbrance');
      lines.push('');
      const carryCapacity = strength_score * 15;
      const encumberedThreshold = strength_score * 5;
      const heavilyEncumberedThreshold = strength_score * 10;
  
      lines.push(`**Strength:** ${strength_score}`);
      lines.push(`**Carry Capacity:** ${carryCapacity} lb.`);
      lines.push(`**Current Load:** ${totalWeight} lb. (${Math.round((totalWeight / carryCapacity) * 100)}%)`);
      lines.push('');
  
      if (totalWeight > carryCapacity) {
        lines.push(`**Status: OVER CAPACITY** — Cannot move. Exceeds carry capacity by ${totalWeight - carryCapacity} lb.`);
      } else if (totalWeight > heavilyEncumberedThreshold) {
        lines.push(`**Status: HEAVILY ENCUMBERED** — Speed reduced by 20 ft. (threshold: ${heavilyEncumberedThreshold} lb.)`);
      } else if (totalWeight > encumberedThreshold) {
        lines.push(`**Status: ENCUMBERED** — Speed reduced by 10 ft. (threshold: ${encumberedThreshold} lb.)`);
      } else {
        lines.push(`**Status: Unencumbered** — No speed penalty.`);
      }
  
      lines.push('');
      lines.push('| Threshold | Weight | Status |');
      lines.push('|-----------|--------|--------|');
      lines.push(`| 0–${encumberedThreshold} lb. | Unencumbered | No penalty |`);
      lines.push(`| ${encumberedThreshold + 1}–${heavilyEncumberedThreshold} lb. | Encumbered | Speed −10 ft. |`);
      lines.push(`| ${heavilyEncumberedThreshold + 1}–${carryCapacity} lb. | Heavily Encumbered | Speed −20 ft. |`);
      lines.push(`| ${carryCapacity + 1}+ lb. | Over Capacity | Cannot move |`);
    }
  
    return {
      content: [{ type: 'text' as const, text: lines.join('\n') }],
    };
  },

• src/tools/analyze-loadout.ts:96-107 (schema)

  The Zod schema defining the input arguments for the 'analyze_loadout' tool.

  inputSchema: {
    items: z
      .array(z.string())
      .min(1)
      .describe('List of equipment item names to analyze'),
    strength_score: z
      .number()
      .min(1)
      .max(30)
      .optional()
      .describe('Character Strength score for encumbrance calculation'),
  },

• src/tools/analyze-loadout.ts:92-92 (registration)

  The registration name of the tool within the server.

  'analyze_loadout',