ChatRPG

Instructions

Implementation Reference

• src/modules/magic.ts:1288-1479 (handler)

  Main handler function for the synthesize_spell tool. Performs Arcana check with DC calculation based on spell level and modifiers, resolves roll with advantage/disadvantage support, determines success/mishap/critical outcomes, and returns formatted ASCII output describing the improvised spell creation result.
  export function synthesizeSpell(input: SynthesizeSpellInput): string { const content: string[] = []; const { encounterId, casterId, intent, proposedSpell, arcanaBonus = 0, rollMode = 'normal', manualRoll, manualRolls, nearLeyLine, desperationBonus, materialComponentValue, } = input; // Calculate DC using helper function const { dc, modifiers: dcModifiers } = calculateSynthesisDC( proposedSpell.level, nearLeyLine, materialComponentValue ); // Build header content.push(centerText('ARCANE SYNTHESIS', DISPLAY_WIDTH)); content.push(''); content.push(`Caster: ${casterId}`); if (encounterId) { content.push(`Encounter: ${encounterId}`); } content.push(''); content.push(`Intent: "${intent}"`); content.push(''); content.push(BOX.LIGHT.H.repeat(DISPLAY_WIDTH)); content.push(''); // Show proposed spell content.push(centerText('PROPOSED SPELL', DISPLAY_WIDTH)); content.push(''); content.push(`Name: ${proposedSpell.name}`); content.push(`Level: ${proposedSpell.level}`); content.push(`School: ${proposedSpell.school}`); content.push(`Range: ${proposedSpell.range} ft`); // Effect details content.push(''); content.push(`Effect Type: ${proposedSpell.effect.type}`); if (proposedSpell.effect.damage) { content.push(`Damage: ${proposedSpell.effect.damage} ${proposedSpell.effect.damageType || ''}`); } if (proposedSpell.effect.healing) { content.push(`Healing: ${proposedSpell.effect.healing}`); } if (proposedSpell.effect.condition) { content.push(`Condition: ${proposedSpell.effect.condition}`); } // Area of effect if (proposedSpell.area) { content.push(`Area: ${proposedSpell.area.size} ft ${proposedSpell.area.shape}`); } // Saving throw if (proposedSpell.savingThrow) { content.push(`Save: DC ${proposedSpell.savingThrow.dc} ${proposedSpell.savingThrow.ability.toUpperCase()}`); } // Concentration and duration if (proposedSpell.concentration) { content.push(`Concentration: Yes`); } if (proposedSpell.duration) { content.push(`Duration: ${proposedSpell.duration}`); } content.push(''); content.push(BOX.LIGHT.H.repeat(DISPLAY_WIDTH)); content.push(''); // Show DC calculation content.push(centerText('ARCANA CHECK', DISPLAY_WIDTH)); content.push(''); content.push(`Base DC: 10 + (${proposedSpell.level} × 2) = ${10 + proposedSpell.level * 2}`); if (dcModifiers.length > 0) { content.push(`Modifiers: ${dcModifiers.join(', ')}`); } content.push(`Final DC: DC ${dc}`); content.push(''); // Show circumstance bonuses if (nearLeyLine) { content.push('Near ley line: DC reduced'); } if (desperationBonus) { content.push(`Desperation: +${DESPERATION_ROLL_BONUS} to roll (mishap on failure)`); } if (materialComponentValue !== undefined) { content.push(`Material components: ${materialComponentValue}gp`); } // Roll the check const { finalRoll, rollDisplay } = resolveArcanaRoll(rollMode, manualRoll, manualRolls); // Apply desperation bonus to roll let rollBonus = arcanaBonus; if (desperationBonus) { rollBonus += DESPERATION_ROLL_BONUS; } const total = finalRoll + rollBonus; const isNat1 = finalRoll === 1; const isNat20 = finalRoll === 20; content.push(''); content.push(`Roll: ${rollDisplay}`); if (rollBonus !== 0) { content.push(`Modifier: ${formatModifier(rollBonus)}`); content.push(`Total: ${finalRoll} ${formatModifier(rollBonus)} = ${total}`); } else { content.push(`Total: ${total}`); } content.push(''); content.push(BOX.LIGHT.H.repeat(DISPLAY_WIDTH)); content.push(''); // Determine outcome const success = total >= dc && !isNat1; const marginOfSuccess = total - dc; const enhancedSuccess = success && marginOfSuccess >= ENHANCED_MASTERY_THRESHOLD; const criticalSuccess = success && isNat20; const mishap = isNat1 || (desperationBonus && !success); // Display result if (criticalSuccess) { content.push(centerText('CRITICAL SUCCESS!', DISPLAY_WIDTH)); content.push(''); content.push('The magic flows flawlessly!'); content.push('The spell manifests with perfect clarity.'); content.push(''); content.push(`${proposedSpell.name} created successfully!`); if (proposedSpell.effect.damage) { content.push(`Deals maximum damage: ${proposedSpell.effect.damage}`); } } else if (enhancedSuccess) { content.push(centerText('ENHANCED SUCCESS!', DISPLAY_WIDTH)); content.push(''); content.push('Exceptional mastery of the arcane!'); content.push(`Beat DC by ${marginOfSuccess} - enhanced effect`); content.push(''); content.push(`${proposedSpell.name} created with bonus!`); } else if (success) { content.push(centerText('SUCCESS', DISPLAY_WIDTH)); content.push(''); content.push('The improvised magic takes form!'); content.push(''); content.push(`${proposedSpell.name} created successfully!`); if (proposedSpell.effect.damage) { content.push(`Damage: ${proposedSpell.effect.damage} ${proposedSpell.effect.damageType || ''}`); } if (proposedSpell.effect.healing) { content.push(`Healing: ${proposedSpell.effect.healing}`); } } else if (mishap) { if (isNat1) { content.push(centerText('MISHAP!', DISPLAY_WIDTH)); content.push(''); content.push('The magic surges wildly!'); content.push('A critical failure causes a magical backfire!'); } else { content.push(centerText('SEVERE MISHAP!', DISPLAY_WIDTH)); content.push(''); content.push('Desperation magic gone wrong!'); content.push('The risky casting has backfired terribly!'); } content.push(''); content.push('The DM should determine the mishap effect:'); content.push('- Wild magic surge'); content.push('- Damage to caster'); content.push('- Unintended effect'); } else { content.push(centerText('FAILED', DISPLAY_WIDTH)); content.push(''); content.push('The magic fails to coalesce.'); content.push('The spell fizzles without taking form.'); content.push(''); content.push(`Missed DC by ${dc - total}`); } const title = mishap ? 'SPELL MISHAP' : success ? 'SPELL SYNTHESIZED' : 'SYNTHESIS FAILED'; return createBox(title, content); }
• src/modules/magic.ts:1217-1233 (schema)

  Zod schema defining input validation for synthesize_spell, including proposed spell details, caster info, intent, and various modifiers for the Arcana check.
  export const synthesizeSpellSchema = z.object({ encounterId: z.string().optional(), casterId: z.string(), intent: z.string(), proposedSpell: ProposedSpellSchema, // Arcana check modifiers arcanaBonus: z.number().optional(), rollMode: RollModeSchema.optional(), manualRoll: z.number().min(1).max(20).optional(), manualRolls: z.array(z.number().min(1).max(20)).length(2).optional(), // Circumstance modifiers nearLeyLine: z.boolean().optional(), desperationBonus: z.boolean().optional(), materialComponentValue: z.number().optional(), });
• src/registry.ts:1020-1038 (registration)

  Tool registration in the central registry, including name, description, input schema conversion, and wrapper handler that validates input and delegates to the synthesizeSpell function.
  synthesize_spell: { name: 'synthesize_spell', description: 'Arcane Synthesis for improvised magic. Caster proposes a custom spell effect; Arcana check DC = 10 + (level × 2) + modifiers. Success creates temporary spell effect, failure may cause mishaps. Supports circumstance modifiers (ley lines, desperation, material components).', inputSchema: toJsonSchema(synthesizeSpellSchema), handler: async (args) => { try { const validated = synthesizeSpellSchema.parse(args); const result = synthesizeSpell(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); } }, },
• src/modules/magic.ts:1262-1282 (helper)

  Helper function to calculate the Arcana check DC for spell synthesis based on spell level, ley line proximity, and material component value.
  function calculateSynthesisDC( level: number, nearLeyLine?: boolean, materialComponentValue?: number ): { dc: number; modifiers: string[] } { let dc = 10 + (level * 2); const modifiers: string[] = []; if (nearLeyLine) { dc -= 2; modifiers.push('Near ley line: -2'); } if (materialComponentValue && materialComponentValue >= 100) { const reduction = Math.floor(materialComponentValue / 100); dc -= reduction; modifiers.push(`Components (${materialComponentValue}gp): -${reduction}`); } return { dc, modifiers }; }