aether-shards/specs/EffectProcessor.spec.md

Effect Processor Specification: The Game Logic Engine

This document defines the architecture for the Effect Processor, the central system responsible for executing all changes to the game state (Damage, Healing, Movement, Spawning).

1. System Overview

The EffectProcessor is a stateless logic engine. It takes a Definition (What to do) and a Context (Who is doing it to whom), and applies the necessary mutations to the UnitManager or VoxelGrid.

Architectural Role

• Input: EffectDefinition (JSON), Source (Unit), Target (Unit/Tile).
• Output: State Mutation (HP changed, Unit moved) + EffectResult (Log data).
• Pattern: Strategy Pattern. Each effect_type maps to a specific Handler Function.

2. Integration Points

A. Calling the Processor

The Processor is never called directly by the UI. It is invoked by:

1. SkillManager: When an Active Skill is executed.
2. EventSystem: When a Passive Item triggers (e.g., "On Hit -> Apply Burn").
3. Environmental Hazard: When a unit starts their turn on Fire/Acid.

B. Dependencies

The Processor requires injection of:

• VoxelGrid: To check collision, modify terrain, or move units.
• UnitManager: To find neighbors (Chain Lightning) or spawn tokens (Turrets).
• RNG: A seeded random number generator for damage variance and status chances.

3. Data Structure (JSON Schema)

Every effect in the game must adhere to this structure.

interface EffectDefinition {
  type: EffectType;

  // -- Magnitude --
  power?: number; // Base amount (Damage/Heal)
  attribute?: string; // Stat to scale off (e.g., "strength", "magic")
  scaling?: number; // Multiplier for attribute (Default: 1.0)

  // -- Flavour --
  element?: "PHYSICAL" | "FIRE" | "ICE" | "SHOCK" | "VOID" | "TECH";

  // -- Status/Buffs --
  status_id?: string; // For APPLY_STATUS
  duration?: number; // Turns
  chance?: number; // 0.0 to 1.0

  // -- Movement/Physics --
  force?: number; // Distance for Push/Pull
  destination?: "TARGET" | "BEHIND_TARGET"; // For Teleport

  // -- Conditionals --
  condition?: {
    target_tag?: string; // e.g. "MECHANICAL"
    target_status?: string; // e.g. "WET"
    hp_threshold?: number; // e.g. 0.3 (30%)
  };
}

type EffectType =
  | "DAMAGE"
  | "HEAL"
  | "APPLY_STATUS"
  | "REMOVE_STATUS"
  | "TELEPORT"
  | "PUSH"
  | "PULL"
  | "SPAWN_UNIT"
  | "MODIFY_TERRAIN" // Destroy walls, create hazards
  | "CHAIN_DAMAGE"; // Bouncing projectiles

4. Handler Specifications

Handler: DAMAGE

• Logic: FinalDamage = (BasePower + (Source[Attribute] * Scaling)) - Target.Defense.
• Element Check: If Target has Resistance/Weakness to element, modify FinalDamage.
• Result: Target.currentHP -= FinalDamage.

Handler: CHAIN_DAMAGE

• Logic: Apply DAMAGE to primary target. Then, scan for N nearest enemies within Range R. Apply DAMAGE * Decay to them.
• Synergy: If condition.target_status is present on a target, the chain may branch or deal double damage.

Handler: TELEPORT

• Logic: Validate destination tile (must be Air and Unoccupied). Update Unit.position and VoxelGrid.unitMap.
• Visuals: Trigger "Vanish" VFX at old pos, "Appear" VFX at new pos.

Handler: MODIFY_TERRAIN

• Logic: Update VoxelGrid ID at Target coordinates.
• Use Case: Sapper's "Breach Charge" turns ID_WALL into ID_AIR.
• Safety: Check VoxelGrid.isDestructible(). Do not destroy bedrock.

---

5. Conditions of Acceptance (CoA)

CoA 1: Attribute Scaling

• Given a Damage Effect with power: 10 and attribute: "magic", if Source has magic: 5, the output damage must be 15.

CoA 2: Conditional Logic

• Given an Effect with condition: { target_status: "WET" }, if the target does not have the "WET" status, the effect must not execute (return early).

CoA 3: State Mutation

• When APPLY_STATUS is executed, the Target unit's statusEffects array must contain the new ID with the correct duration.

CoA 4: Physics Safety

• When PUSH is executed, the system must check VoxelGrid.isSolid() behind the target. If a wall exists, the unit must not move into the wall (optionally take "Smash" damage instead).

---

6. Prompt for Coding Agent

"Create src/systems/EffectProcessor.js.

1. Constructor: Accept VoxelGrid and UnitManager. Initialize a map of handlers.
2. Process Method: process(effectDef, source, target). Look up handler by effectDef.type. Verify checkConditions(). Execute handler. Return ResultObject.
3. Handlers: Implement handleDamage, handleHeal, handleStatus, handleMove.
4. Helper: Implement calculatePower(def, source) to handle attribute scaling logic centrally."