Combat System Creator - SHINOBI WAY

Create combat system components following the dual-system architecture: pure calculations separated from state workflow.

Architecture Principle

Player Action → CombatCalculationSystem (pure math) → CombatWorkflowSystem (apply to state)

CombatCalculationSystem: Pure functions, no mutations, returns complete results CombatWorkflowSystem: State management, applies calculated results, controls flow

When to Use

Add new damage calculations or formulas
Create new status effects or mitigation mechanics
Add new combat phases or turn logic
Refactor existing combat code
Balance or modify combat math

Quick Reference

Damage Pipeline (5 Steps)

1. Hit Check    → MELEE: Speed vs Speed | RANGED: Accuracy vs Speed | AUTO: Always hits
2. Base Damage  → ScalingStat × damageMult
3. Element      → Super: 1.5× (+10% crit) | Resist: 0.5× | Neutral: 1.0×
4. Critical     → 8% + (DEX × 0.5) + bonuses, max 75%, multiplier 1.75×
5. Defense      → Flat (max 60% reduction) then % (soft cap 75%)

Mitigation Pipeline (Priority Order)

1. INVULNERABILITY → Blocks ALL damage (return 0)
2. REFLECTION      → Calculate reflected damage (before curse)
3. CURSE           → Amplify: damage × (1 + curseValue)
4. SHIELD          → Absorb damage before HP
5. GUTS            → Survive at 1 HP if roll succeeds

Defense Formulas

Type	Flat	Percent (Soft Cap)
Physical	`STR × 0.3`	`STR / (STR + 200)`
Elemental	`SPI × 0.3`	`SPI / (SPI + 200)`
Mental	`CAL × 0.25`	`CAL / (CAL + 150)`

Damage Properties

Property	Flat Def	% Def
NORMAL	✅ (max 60%)	✅
PIERCING	❌	✅
ARMOR_BREAK	✅	❌
TRUE	❌	❌

Workflow: Adding New Mechanics

Step 1: Identify System

Ask: Is this pure math or state management?

CombatCalculationSystem	CombatWorkflowSystem
Damage formulas	Applying damage to HP
Hit/miss/evasion rolls	Turn order management
Crit calculations	Buff duration tracking
Defense reduction	Phase transitions
Effect chance rolls	Combat log generation

Step 2: Design the Calculation Interface

For new calculations, define the result interface:

interface NewMechanicResult {
  // All values needed to apply this mechanic
  value: number;
  triggered: boolean;
  // Metadata for logging
  logs: CombatLogEntry[];
}

Step 3: Implement Pure Function

// In CombatCalculationSystem
function calculateNewMechanic(
  attackerStats: DerivedStats,
  defenderStats: DerivedStats,
  context: CombatContext
): NewMechanicResult {
  // Pure calculation - NO state mutation
  return { value, triggered, logs };
}

Step 4: Implement Workflow Application

// In CombatWorkflowSystem
function applyNewMechanic(
  state: CombatWorkflowState,
  result: NewMechanicResult
): CombatWorkflowState {
  // Apply result to state - returns NEW state
  return { ...state, /* updated values */ };
}

Creating New Status Effects

Effect Types Available

// Damage Over Time
DOT, BLEED, BURN, POISON

// Crowd Control
STUN, CONFUSION, SILENCE

// Defensive
SHIELD, INVULNERABILITY, REFLECTION

// Stat Modifiers
BUFF, DEBUFF, CURSE

// Recovery
HEAL, REGEN, CHAKRA_DRAIN

Effect Interface

interface SkillEffect {
  type: EffectType;
  value: number;           // Damage/heal amount or multiplier
  duration: number;        // Turns (-1 = permanent)
  chance: number;          // 0.0-1.0 application chance
  targetStat?: PrimaryStat; // For BUFF/DEBUFF
  damageType?: DamageType;  // For DoTs
  damageProperty?: DamageProperty;
}

DoT Damage Formula

// DoTs get 50% defense mitigation
dotDamage = max(1, baseDamage - (flatDef × 0.5) - (damage × percentDef × 0.5))

Creating New Combat Phases

Existing Turn Phases

Player Turn:

TURN_START → Reset flags
UPKEEP → Toggle costs, passive regen
MAIN_ACTION → Skill execution
DEATH_CHECK → Victory/defeat
TURN_END → Mark turn complete

Enemy Turn:

DOT_ENEMY → Process enemy DoTs
DOT_PLAYER → Process player DoTs (through shield)
DEATH_CHECK_DOT → Check DoT kills
ENEMY_ACTION → AI skill selection + execution
DEATH_CHECK_ATTACK → Check combat kills
RESOURCE_RECOVERY → Cooldowns, chakra regen
TERRAIN_HAZARDS → Environmental damage
FINAL_DEATH_CHECK → Hazard kills

Adding New Phase

// 1. Add to CombatPhase enum
enum CombatPhase {
  // ... existing
  NEW_PHASE,
}

// 2. Create calculation function
function calculateNewPhaseEffects(state: CombatWorkflowState): NewPhaseResult;

// 3. Create workflow handler
function processNewPhase(state: CombatWorkflowState): CombatWorkflowState;

// 4. Insert into turn flow in processEnemyTurn or executePlayerAction

Output Templates

New Calculation Function

/**
 * [Description of what this calculates]
 * @param attackerStats - Attacker's derived stats
 * @param defenderStats - Defender's derived stats
 * @param skill - The skill being used
 * @returns [ResultType] with all calculation details
 */
export function calculateX(
  attackerStats: DerivedStats,
  defenderStats: DerivedStats,
  skill: Skill
): XResult {
  const result: XResult = {
    // Initialize result object
  };

  // Pure calculations here
  // NO state mutation
  // Use Math.random() for rolls

  return result;
}

New Workflow Function

/**
 * [Description of what state changes this applies]
 * @param state - Current combat state
 * @param result - Calculation result to apply
 * @returns New combat state with changes applied
 */
export function applyX(
  state: CombatWorkflowState,
  result: XResult
): CombatWorkflowState {
  // Create new state object (immutable)
  const newState = { ...state };

  // Apply result values to state
  // Add combat logs
  // Check for combat end conditions

  return newState;
}

New Effect Implementation

// In constants/index.ts - Add to SKILLS
NEW_SKILL: {
  id: 'new_skill',
  name: 'New Skill Name',
  // ... other properties
  effects: [{
    type: EffectType.NEW_EFFECT,
    value: 10,
    duration: 3,
    chance: 0.8,
    damageType: DamageType.PHYSICAL,
    damageProperty: DamageProperty.NORMAL
  }]
}

// In CombatSystem.ts - Handle in applyMitigation or processDoT
if (buff.effect.type === EffectType.NEW_EFFECT) {
  // Calculate effect
  // Apply to appropriate target
}

Reference Files

combat-mechanics.md - Full combat formulas and constants
architecture.md - Dual-system architecture details

Balance Constants

Resource Pools

HP: 50 + (WIL × 12)
Chakra: 30 + (CHA × 8)
HP Regen: maxHP × 0.02 × (WIL / 20)
Chakra Regen: INT × 2

Combat Constants

Base Hit: 92%
Hit Range: 30-98%
Base Crit: 8%
Crit Cap: 75%
Crit Mult: 1.75×
Flat Def Cap: 60% of damage
% Def Cap: 75%

Survival

Guts: WIL / (WIL + 200)
Status Resist: CAL / (CAL + 80)
Evasion: SPD / (SPD + 250)

combat-system-creator