56aa6d79df
Introduce detailed specifications for combat skill usage, including interaction flow, state machine updates, and the skill targeting system. Implement the SkillTargetingSystem to handle targeting validation and area of effect calculations. Enhance the CombatHUD specification to define the UI overlay for combat phases. Integrate these systems into the GameLoop for improved combat mechanics and user experience.
96 lines
3.6 KiB
Markdown
96 lines
3.6 KiB
Markdown
# **Combat State & Movement Specification**
|
|
|
|
This document defines the logic for managing the Turn-Based Combat Loop and the execution of Movement Actions.
|
|
|
|
## **1. TypeScript Interfaces (Data Models)**
|
|
|
|
```typescript
|
|
export type CombatPhase =
|
|
| "INIT"
|
|
| "TURN_START"
|
|
| "WAITING_FOR_INPUT"
|
|
| "EXECUTING_ACTION"
|
|
| "TURN_END"
|
|
| "COMBAT_END";
|
|
|
|
export interface CombatState {
|
|
/** Whether combat is currently active */
|
|
isActive: boolean;
|
|
/** Current Round number */
|
|
round: number;
|
|
/** Ordered list of Unit IDs for the current round */
|
|
turnQueue: string[];
|
|
/** The ID of the unit currently taking their turn */
|
|
activeUnitId: string | null;
|
|
/** Current phase of the turn loop */
|
|
phase: CombatPhase;
|
|
}
|
|
|
|
// src/types/Actions.ts
|
|
|
|
export interface ActionRequest {
|
|
type: "MOVE" | "SKILL" | "ITEM" | "WAIT";
|
|
sourceId: string;
|
|
targetId?: string; // For targeted skills
|
|
targetPosition?: { x: number; y: number; z: number }; // For movement/AoE
|
|
skillId?: string;
|
|
itemId?: string;
|
|
}
|
|
|
|
export interface MovementResult {
|
|
success: boolean;
|
|
path: { x: number; y: number; z: number }[];
|
|
costAP: number;
|
|
finalPosition: { x: number; y: number; z: number };
|
|
}
|
|
```
|
|
|
|
## **2. Conditions of Acceptance (CoA)**
|
|
|
|
These checks ensure the combat loop feels fair and responsive.
|
|
|
|
### **System: TurnSystem (src/systems/TurnSystem.js)**
|
|
|
|
- **CoA 1: Initiative Roll:** Upon starting combat, all active units must be sorted into the turnQueue based on their Speed stat (Highest First).
|
|
- **CoA 2: Turn Start Hygiene:** When a unit's turn begins:
|
|
- Their currentAP must reset to baseAP.
|
|
- Status effects (DoTs) must tick.
|
|
- Cooldowns must decrement.
|
|
- **CoA 3: Cycling:** Calling endTurn() must move the activeUnitId to the next in the queue. If the queue is empty, increment round and re-roll/reset the queue.
|
|
|
|
### **System: MovementSystem (src/systems/MovementSystem.js)**
|
|
|
|
- **CoA 1: Validation:** Moving to a tile must fail if:
|
|
- The tile is blocked/occupied.
|
|
- No path exists.
|
|
- The unit has insufficient AP for the _entire_ path.
|
|
- **CoA 2: Execution:** A successful move must:
|
|
- Update the Unit's position in the UnitManager.
|
|
- Update the VoxelGrid occupancy map.
|
|
- Deduct the correct AP cost (including terrain modifiers).
|
|
- **CoA 3: Path Snapping:** If the user clicks a tile, but the unit only has AP to reach halfway, the system should allow moving to the _furthest reachable tile_ on that path (optional QoL).
|
|
|
|
## **3. Implementation Prompts**
|
|
|
|
Use these prompts to generate the specific logic files.
|
|
|
|
### **Prompt 1: The Turn System**
|
|
|
|
"Create src/systems/TurnSystem.js. It should manage the CombatState.
|
|
|
|
1. Implement startCombat(units): Sorts units by speed into turnQueue and sets phase to TURN_START.
|
|
2. Implement startTurn(): Refills the active unit's AP, processes cooldowns/statuses, and sets phase to WAITING_FOR_INPUT.
|
|
3. Implement endTurn(): Rotates the queue. If queue is empty, start new Round.
|
|
4. It should accept the UnitManager in the constructor to access unit stats.
|
|
5. Dispatch events: combat-start, turn-start, turn-end."
|
|
|
|
### **Prompt 2: The Movement System**
|
|
|
|
"Create src/systems/MovementSystem.js. It coordinates Pathfinding, VoxelGrid, and UnitManager.
|
|
|
|
1. Implement validateMove(unit, targetPos): Returns { valid: boolean, cost: number, path: [] }. It checks `A*` pathfinding and compares cost vs unit.currentAP.
|
|
2. Implement executeMove(unit, targetPos):
|
|
- Validates the move first.
|
|
- Updates grid.moveUnit(unit, targetPos).
|
|
- Deducts AP.
|
|
- Returns a Promise that resolves when the visual movement (optional animation hook) would handle it, or immediately for logic."
|