aether-shards/specs/Combat_Skill_Usage.spec.md

Combat Skill Usage Specification

This document defines the workflow for selecting, targeting, and executing Active Skills during the Combat Phase.

1. The Interaction Flow

The process follows a strict 3-step sequence:

1. Selection (UI): Player clicks a skill button in the HUD.
2. Targeting (Grid): Game enters TARGETING_MODE. Player moves cursor to select a target. Valid targets are highlighted.
3. Execution (Engine): Player confirms selection. Costs are paid, and effects are applied.

2. State Machine Updates

We need to expand the CombatState in GameLoop to handle targeting.

State	Description	Input Behavior
IDLE / SELECTING_MOVE	Standard state. Cursor highlights movement range.	Click Unit = Select. Click Empty = Move.
TARGETING_SKILL	Player has selected a skill. Cursor highlights Skill Range.	Hover: Update AoE Reticle. Click: Execute Skill. Cancel (B/Esc): Return to IDLE.
EXECUTING_SKILL	Animation playing. Input locked.	None.

3. The Skill Targeting System

We need a helper system (src/systems/SkillTargetingSystem.js) to handle the complex math of "Can I hit this?" without cluttering the GameLoop.

Core Logic: isValidTarget(source, targetTile, skillDef)

1. Range Check: Manhattan distance between Source and Target <= skill.range.
2. Line of Sight (LOS): Raycast from Source head height to Target center. Must not hit isSolid voxels (unless skill has ignore_cover).
3. Content Check:
   • If target_type is ENEMY: Tile must contain a unit AND unit.team != source.team.
   • If target_type is ALLY: Tile must contain a unit AND unit.team == source.team.
   • If target_type is EMPTY: Tile must be empty.

Visual Logic: getAffectedTiles(targetTile, skillDef)

Calculates the Area of Effect (AoE) to highlight in Red.

• SINGLE: Just the target tile.
• CIRCLE (Radius R): All tiles within distance R of target.
• LINE (Length L): Raycast L tiles in the cardinal direction from Source to Target.
• CONE: A triangle pattern originating from Source.

4. Integration Steps (How to Code It)

Step 1: Create SkillTargetingSystem

This class encapsulates the math.

class SkillTargetingSystem {
    constructor(grid, unitManager) { ... }

    /** Returns { valid: boolean, reason: string } */
    validateTarget(sourceUnit, targetPos, skillId) { ... }

    /** Returns array of {x,y,z} for highlighting */
    getAoETiles(sourcePos, cursorPos, skillId) { ... }
}

Step 2: Update GameLoop State

Add activeSkillId to track which skill is pending.

// In GameLoop.js

// 1. Handle UI Event
onSkillClicked(skillId) {
    // Validate unit has AP
    if (this.unit.currentAP < getSkillCost(skillId)) return;

    this.combatState = 'TARGETING_SKILL';
    this.activeSkillId = skillId;

    // VISUALS: Clear Movement Blue Grid -> Show Attack Red Grid (Range)
    const skill = this.unit.skills.get(skillId);
    this.voxelManager.highlightRange(this.unit.pos, skill.range, 'RED_OUTLINE');
}

// 2. Handle Cursor Hover (InputManager event)
onCursorHover(pos) {
    if (this.combatState === 'TARGETING_SKILL') {
        const aoeTiles = this.targetingSystem.getAoETiles(this.unit.pos, pos, this.activeSkillId);
        this.voxelManager.showReticle(aoeTiles); // Solid Red Highlight
    }
}

Step 3: Execution Logic

When the player confirms the click.

// In GameLoop.js -> triggerSelection()

if (this.combatState === 'TARGETING_SKILL') {
    const valid = this.targetingSystem.validateTarget(this.unit, cursor, this.activeSkillId);

    if (valid) {
        this.executeSkill(this.activeSkillId, cursor);
    } else {
        // Audio: Error Buzz
        console.log("Invalid Target");
    }
}

executeSkill(skillId, targetPos) {
    this.combatState = 'EXECUTING_SKILL';

    // 1. Deduct Costs (AP, Cooldown) via SkillManager
    this.unit.skillManager.payCosts(skillId);

    // 2. Get Targets (Units in AoE)
    const targets = this.targetingSystem.getUnitsInAoE(targetPos, skillId);

    // 3. Process Effects (Damage, Status) via EffectProcessor
    const skillDef = this.registry.get(skillId);
    skillDef.effects.forEach(eff => {
        targets.forEach(t => this.effectProcessor.process(eff, this.unit, t));
    });

    // 4. Cleanup
    this.combatState = 'IDLE';
    this.activeSkillId = null;
    this.voxelManager.clearHighlights();
}