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)