# Raidborne — Game Design Document

## Overview

**Raidborne** is a 4-player online raiding game that strips away the filler content of traditional MMOs and focuses entirely on the core loop: form a party, learn an encounter's mechanics, execute under pressure, earn rewards, and push into harder content. Think FFXIV's Savage raid design distilled into tight, bite-sized sessions (10–20 minutes per run) with no daily quests, no world bosses for casuals, no crafting minigames — just the fight.

This game is **for people who enjoy the challenge of a Savage raid.** There is no "easy mode." Every encounter is designed at a high difficulty ceiling. The challenge comes from mechanical execution, coordination, and mastery — not from outleveling content.

**Engine:** Godot 4.x
**Platform:** PC first (Windows/Linux), gamepad + mouse/keyboard
**Art style:** Stylized anime/cartoon 3D — clean silhouettes, readable at a glance, expressive but not photorealistic
**Session length:** Individual boss encounters target **7–10 minutes** (matching FFXIV Savage clear times). A full tier run (all 4 encounters) targets ~30–40 minutes of pure fight time.

---

## Core Loop

```
Hub (offline/single-player)
  ├── Pick class, customize character, browse shop
  ├── Equip Artifacts + Role Skills for your target encounter
  ├── Form or join a 4-player party
  └── Enter a Raid Encounter (online multiplayer, single boss fight)
         │
         ▼
    FIGHT: One boss, multiple phases, mechanical execution
         │
         ├── Wipe → encounter resets, retry immediately (no penalty)
         └── Clear → rewards screen
              │
              ▼
    Rewards: XP (if under tier cap), Gold, chance at Artifact drop
              │
              ▼
    Hub: manage Artifacts, prep Role Skills for next encounter,
         level up → unlock harder encounters in the tier
              │
              ▼
    Clear all 4 encounters in a tier → next tier unlocks
```

---

## Raid Structure

### Tiers and Encounters

Content is organized into **Tiers**. Each Tier contains exactly **4 Raids**, and each Raid is a **single boss encounter** (one fight, no multi-boss sequences). This mirrors FFXIV's structure where each "raid" is one designed encounter.

| Tier | Name (placeholder) | Encounters | Level Range | Tier Cap |
|------|-------------------|------------|-------------|----------|
| 1 | The Shallows | 4 bosses | 1 – 5 | 5 |
| 2 | Emberhollow | 4 bosses | 6 – 10 | 10 |
| 3 | The Glass Spire | 4 bosses | 11 – 15 | 15 |
| 4+ | (content updates) | 4 bosses each | +5 per tier | scales |

**At launch:** 3 Tiers (12 unique boss encounters), level cap of 15.
**Ongoing:** Each content update adds a new Tier (+4 encounters, +5 level cap). The game's ceiling grows over time.

### Level-Based Progression (No Gear Score)

**Your level IS your power.** There is no gear score, no item level gate. Your character's base stats (HP, Damage, Healing Power, Defense) scale directly with level. Artifacts do NOT make you "stronger" in a raw sense — they reshape *how* you express that power (see Artifacts section).

**How tier progression works:**
- Each Tier spans 5 levels (the "Level Range" column is a guide, not a gate). You're *expected* to be in that range, but it's not enforced.
- **Tier unlock is completion-based:** Clear all 4 encounters in a Tier → next Tier unlocks. No level requirement. A skilled player at level 6 can unlock Tier 3 by beating all of Tier 2 early.
- A Tier is **clearable underleveled** but noticeably harder. At the tier's cap level, it should feel comfortable (not trivial — the mechanics are the same challenge, but your HP/damage margins are wider).
- If you're struggling with Encounter 3 of a Tier, you can grind Encounters 1–2 for XP until you hit a higher level within that tier's range, making all encounters easier.
- **Once you reach a Tier's cap, you earn no more XP from that Tier.** You must move to the next Tier to continue leveling. This prevents infinite grinding of old content for power.
- **Revisiting old Tiers:** Your effective level is capped at that Tier's maximum. A level 15 player revisiting Tier 1 plays as a level 5 character. The challenge remains (mechanics don't scale down) but your stats are reduced to match, keeping it fair for mixed-level groups.

**Why this works:**
- No "am I gear-scored high enough?" anxiety. You know exactly where you stand: your level.
- The "grind earlier encounters in the tier" loop is natural and self-contained — you're not stuck, just underleveled for the later fights.
- Horizontal Artifact progression means revisiting old tiers isn't "power-farming" — you're already at the stat cap for that content.

### Within an Encounter

Each raid is **one boss fight.** No trash mobs, no multi-phase dungeon crawling. You enter the arena, pull the boss, and fight through its phases until it dies or the enrage timer kills everyone.

- **Enrage timer:** Each boss has an enrage mechanism that ends the fight if the party is too slow. Two types exist:
  - **Soft enrage:** The boss's behavior *is* the tell. At a set time, the boss delivers a dialog line ("Enough games. Let's finish this.") and begins spamming a raid-wide attack that ramps up in power every few seconds until it's impossible to heal through (~2–5 min ramp). No separate UI timer — the boss getting angrier and hitting harder IS the warning. Players feel the pressure escalate mechanically.
  - **Hard enrage:** At a specific time (e.g., exactly 10:00), the boss instantly kills all players. The enrage timestamp is shown in the UI as a countdown (top-right, next to boss HP) because there is no mechanical warning — it's a pure DPS race against the clock.
  
  The specific type and timing vary per encounter. Early encounters in a tier tend toward soft enrage (more forgiving, readable); later encounters use hard enrage with tighter DPS checks. The required DPS to beat the timer gets progressively tighter from Encounter 1 → Encounter 4 within a tier.
- **Phases:** Bosses have 2–4 phases triggered by HP thresholds or timed events. Each phase introduces new mechanics or shifts existing ones.
- **No dead time:** The transition from "entering the arena" to "boss is aggro'd" should be under 5 seconds. No walking through corridors, no cutscenes mid-fight (except a brief 3s intro at the very start).

### Death, Revives, and Wipes

**Death:** When a player's HP reaches zero, they are **dead.** Their character falls at their position. They cannot move, attack, or be healed. The fight continues in real-time for remaining players — no pause, no downed timer.

**Reviving (FFXIV-style):** Any party member can revive a dead ally by using a **Revive Potion** consumable on their corpse. There is no class-specific revive ability; the potion is universal.

- Reviving takes **2 seconds of channeling** (the reviver must stand near the corpse and not take damage).
- The revived player spawns at 30% HP with a **Weakness debuff**: -25% Damage and Healing for **90 seconds.** A subtle grey tint on their character model indicates the debuff is active.
- If the reviver takes damage during the channel, it breaks and they must retry.

**Design intent around Revives:** Experienced players should **never need a revive to clear an encounter.** A well-executed party keeps everyone alive through proper positioning, healing, and tank mitigation. Bringing a Revive Potion is a **risk vs. reward insurance choice:**
- *Bring it:* You have a safety net if someone makes a mistake. Costs you a consumable slot that could hold an offensive buff.
- *Don't bring it:* You free up a slot for Power Tonic or Cooldown Draught, but one bad mechanic hit and a player is gone for good (until the wipe reset).

This mirrors FFXIV's potion strategy: top parties run minimal potions because their execution is clean; learning parties pack revives and health pots as a safety net.

**Wipe:** If **all 4 players are dead simultaneously**, the encounter wipes. All players respawn at the arena entrance, boss resets to full HP and Phase 1. No XP or Gold is lost. Players can retry as many times as they want — no wipe counter, no penalty, no "give up" prompt. The only cost is time and patience.

**Key principle:** Death is a *setback within the fight*, not an automatic end. A party with 2+ Revive Potions distributed can keep fighting through multiple individual deaths. This creates dramatic "we're down to one but the healer is popping a revive" moments.

---

## Classes and Combat

### Combat System: GCD + Combos + Weaving

The combat system follows FFXIV's core structure: a **Global Cooldown (GCD)** gates your primary actions, with off-GCD abilities woven in between.

#### Global Cooldown (GCD)

- The GCD is the rhythm of combat. Pressing a GCD-bound action (combo hit or on-GCD ability) starts a cooldown timer that prevents you from using another GCD-bound action until it completes.
- **Default GCD: 2.5 seconds** for all classes at launch. May be tuned per class later (e.g., Blade 2.3s for faster rotation, Warden 2.7s for heavier hits).
- The GCD is displayed as a radial sweep on the ability bar / combo button.

#### Combo Attacks (On-GCD)

The primary damage button is a **rotating multi-hit combo.** Each press consumes one GCD tick and advances to the next hit in the sequence. When the final hit lands, the combo resets to the first.

- Combo hits are **on-GCD** — they use the global cooldown just like FFXIV's mainhand attacks.
- **Melee combos require positionals.** If a combo step specifies "Front" and you're not in Front when you press the button (and the GCD is ready), the combo **breaks** — it resets to Hit 1 with no damage dealt, but the GCD still triggers. The UI shows which positional is needed for the current step.
- Ranged combos do NOT require positionals (they have range/line-of-sight requirements) but may have other constraints.
- Getting hit by an enemy attack does NOT break your combo (that would be too punishing), but it may reset class-specific gimmick gauges (Momentum, Flux — see below).

#### Off-GCD Abilities (Weaving)

Some abilities are **off-GCD** — they have their own independent cooldown and can be used at any time, even while the GCD is still sweeping. This is the "weave" mechanic from FFXIV: you slot these in between your GCD combo ticks.

- Each class has a mix of on-GCD and off-GCD abilities among their 4 class skills.
- **All Role Skills are off-GCD** (heals, taunts, mitigations — reactive utilities you need at any moment).
- The visual indicator: off-GCD abilities show their own radial cooldown; on-GCD abilities are greyed out while the GCD is active (they'll activate the instant the GCD completes if pressed during it, queuing for the next tick).

#### Positional System

| Position | Relative to target's facing direction |
|----------|---------------------------------------|
| Front | Directly in front (0°) |
| Back | Directly behind (180°) |
| Left | To the target's left side (90°) |
| Right | To the target's right side (270°) |

- A **positional indicator** appears near the target showing which direction is required for the current combo step. Small directional arrow, not a huge UI element.
- Front/Back are used from Tier 1. Left/Right appear in Tier 3+ encounters and higher-tier combos.

#### Damage Mitigation Stacking

When a player has multiple damage mitigation effects active simultaneously (e.g., Weaken on the boss + personal Mitigate + Sanctuary + Iron Guard absorb), they are applied **sequentially, highest percentage first.** Each mitigation reduces the *remaining* damage after the previous one has been applied.

**Formula:** Process all active % mitigations sorted from highest to lowest. For each: `remaining_damage = remaining_damage × (1 - mitigation%)`. Absorb shields (flat value) are subtracted after all % mitigations are applied.

**Example:** Boss hits for 100 damage. Active mitigations: Mitigate (60%), Weaken on boss (20%), Sanctuary (40%).
1. Sort: 60%, 40%, 20%
2. 100 × (1 - 0.60) = 40
3. 40 × (1 - 0.40) = 24
4. 24 × (1 - 0.20) = 19.2
5. Final damage: **19** (rounded down)

**Key property:** Because each mitigation is applied to the *reduced* remainder, stacking multiple mitigations always yields a result greater than zero (unless a single mitigation is 100%). You can never reduce a hit to exactly 0 through % mitigation stacking alone. This prevents "I'm unhittable" situations while still making full mitigation feel dramatically powerful (100 → 19 is a huge difference).

#### Targeting

- Single primary target + one "focus" secondary target (useful for healers triaging, tanks marking adds).
- Tab or wheel to cycle targets. Q to set/clear focus.

---

### Role Skills (Core + Specialist)

In addition to their 4 class abilities, every player has **Role Skills** specific to their role (Tank / Healer / DPS). These are all off-GCD abilities with their own cooldowns. The system is split into two tiers:

- **Core Role Skills (2 per role, always equipped):** Non-negotiable essentials that define what it means to fill your role. You cannot swap these out. Every healer can heal; every tank can taunt and mitigate. These are always available in every fight.
- **Specialist Role Skill (1 slot, chosen from a pool before the raid):** The strategic pre-pull decision. Looking at the encounter's mechanics, you pick which specialist tool you need. This is where risk/reward choices live (e.g., "Do I bring Revive for safety, or Vulnerability Mark for DPS?").

**Total Role Skill loadout: 2 Core + 1 Specialist = 3 off-GCD role abilities.**

This design frees class ability slots from "table stakes" utilities. A healer doesn't need a class slot for basic healing or cleanses — those are Core Role Skills. Their 4 class slots focus on unique identity (raid buffs, gimmick enablers, special mechanics).

#### Tank Role Skills

**Core (always equipped):**
| Role Skill | Cooldown | Effect |
|-----------|----------|--------|
| **Taunt** | 8s | Forces the target to attack you. Resets threat generation. The bread-and-butter aggro tool. |
| **Mitigate** | 15s | Reduces all incoming damage by 60% for 6 seconds. Your primary "I'm about to get hit by something big" button. |

**Specialist pool (choose 1):**
| Role Skill | Cooldown | Effect |
|-----------|----------|--------|
| **Provoke** | 25s | AoE taunt: forces all enemies within 15m to attack you. For multi-add phases. |
| **Iron Guard** | 30s | Damage shield: absorbs the next X damage over 8 seconds. Stacks with Mitigate for extreme survival windows. |
| **Rallying Shout** | 40s | Grants all party members a 20% damage reduction for 6 seconds. Your "raid-wide mitigate" for unavoidable AoE hits. |

#### Healer Role Skills

**Core (always equipped):**
| Role Skill | Cooldown | Effect |
|-----------|----------|--------|
| **Heal** | 6s | Single-target heal. Reliable, straightforward. The "keep someone alive" button. Generates Lumen Charges for Luminary. |
| **Status Cure** | 12s | Removes all **curable** harmful status effects from one target. Your Esuna. Essential for fights with debuff-heavy mechanics. Curable statuses are indicated in the HUD by a white underline beneath their icon (FFXIV-style). See "Status Effect Taxonomy" below. |

**Specialist pool (choose 1):**
| Role Skill | Cooldown | Effect |
|-----------|----------|--------|
| **Revive** | 30s | Channel for 2s on a dead ally's corpse to bring them back at 30% HP with Weakness debuff. Requires a Revive Potion consumable to activate. *The risk/reward choice: spending your specialist slot here means giving up offensive/utility tools for a safety net.* |
| **Cure Aura** | 25s | AoE heal: restores HP to all party members within 10m over 4 seconds. For when everyone takes a chunk. Generates Lumen Charges for each ally healed. |
| **Sanctuary** | 30s | Damage reduction aura (40%) on one ally for 8 seconds. Pre-apply before a known heavy hit. |

*The Revive decision:* Bringing Revive as your specialist + a Revive Potion in your consumable slot is the "full safety net" choice. It costs you an offensive/utility specialist AND a consumable slot. An experienced party that trusts its execution might run Cure Aura (for AoE pressure phases) and skip the revive entirely — if everyone plays clean, no one dies, and you kept your offensive tools.

#### DPS Role Skills

**Core (always equipped):**
| Role Skill | Cooldown | Effect |
|-----------|----------|--------|
| **Second Wind** | 20s | Self-heal: restores 15% of your max HP over 4 seconds. Your "the healer is busy, I need to patch myself" button. Keeps you alive through minor mechanic hits without healing resources. |
| **Weaken** | 30s | Applies a debuff to the target boss: reduces ALL of its outgoing damage by 20% for 8 seconds. This is a raid-wide support tool — it reduces the damage from *every* hit the boss lands, including unavoidable raid-wides. Your contribution to party survivability. "I can't mitigate like the tank, but I can make everything the boss does hurt less." At lower levels (entering a tier underleveled), proper use of Weaken + Mitigate + Sanctuary layered together may be the difference between surviving a raid-wide or wiping. At tier cap level, the party has more HP margin and mitigation matters less. |

**Specialist pool (choose 1):**
| Role Skill | Cooldown | Effect |
|-----------|----------|--------|
| **Signature Strike** | 20s | A powerful single-target attack that does NOT follow combo positional requirements. Your "dump everything" nuke for when the target is vulnerable or about to phase. |
| **Cleave** | 18s | AoE damage to all enemies within 6m of target. For adding pulls or cleaning up adds. |
| **Vulnerability Mark** | 25s | Marks the target: they take +15% damage from ALL party members for 10 seconds. Sets up party burst windows. |
| **Focus Fire** | 35s | Next 3 GCD actions deal +30% damage. A short personal DPS window to line up with vulnerability marks or phase transitions. |

#### Role Skill Design Principles
- All Role Skills are **off-GCD** — they're reactive utilities, not rotation pieces.
- Core skills have shorter cooldowns (6–15s) since they're used frequently and are essential.
- Specialist skills have longer cooldowns (18–40s) since they're powerful situational tools.
- The specialist choice is the **pre-pull strategy moment:** reading the encounter's mechanics and deciding which tool you need. A fight with heavy AoE phases? Healer brings Cure Aura, tank brings Rallying Shout. A fight with a single massive tank buster? Tank brings Iron Guard. A fight where you need to prove DPS? Both DPS bring Vulnerability Mark or Focus Fire.
- Role Skills scale with level (same as class abilities).

#### Status Effect Taxonomy and Curability

Every status effect in the game has a **`curable` flag** set at design time. If `curable = true`, the healer's Status Cure Role Skill can remove it. If `curable = false`, it cannot be removed by any means other than its natural duration expiring.

**HUD indicator:** Curable status effects display a **white underline** beneath their icon in the party frames and self-buff/debuff area (matching FFXIV's convention). Non-curable effects have no underline. Players learn to read this at a glance: "white line = healer can fix that."

**General curability rules:**
| Status Type | Curable? | Examples |
|-------------|----------|----------|
| Boss-applied mechanic debuffs | **Yes** (usually) | Poison, Stun, Bleed, Slow, Vulnerability (from boss attacks) |
| Player-applied offensive debuffs | **No** (usually) | Blade's Bleed, Arcanist's Vulnerability Mark, DPS Weaken |
| Self-inflicted trade-off debuffs | **No** | Weakness (post-revive), combo break penalty |
| Special "curable by design" offensive debuffs | **Yes** (exception) | See below |

**The exception — curable offensive debuffs as team dynamics:**
In some encounters or with specific Artifacts, a powerful offensive ability may apply a debuff that is *intentionally* marked `curable = true`. Example: An Arcanist Artifact modifies their Chain Lightning to also apply "Arcane Fatigue" (-30% attack speed on target, 10s, curable). This creates an interesting team dynamic: the healer *could* cure it to restore the boss's speed (bad for the party), but in some encounter contexts a temporarily slower boss might be desirable (e.g., buying time during a complex mechanic phase). More commonly, this just means "the healer has one more thing to manage" — keeping an eye out for curable debuffs on allies that are actually *helpful* and not accidentally curing them.

This is a design tool, not a default. Most player-applied debuffs are non-curable. The curable-offensive-debuff is a spice mechanic for specific encounters or high-tier Artifacts.

---

### Starting Classes (4)

Each class fills one role. The game does not *enforce* composition — you can run 4 DPS if you want — but encounters are designed assuming the standard Tank/Healer/DPS/DPS split.

Each class has a **gimmick** — a unique mechanical identity that makes their rotation feel distinct and keeps players engaged with their own kit.

---

#### Warden (Tank)

**Gimmick: Aegis Gauge.** The Warden builds **Aegis charges** (max 3) by taking damage while taunting or using defensive abilities (Role Skill mitigations count). At full Aegis (3/3), their next on-GCD ability is **free** (doesn't consume a GCD tick) and reflects 40% of incoming damage back to the attacker for 5 seconds. This creates a "soak → reward" loop: you're expected to take hits, and doing so well makes your next big move cost nothing.

**Combo (3 hits, melee, on-GCD):**
| Hit | Name | Positional | Effect |
|-----|------|-----------|--------|
| 1 | Shield Bash | Front required | Moderate damage + applies a weak taunt (adds threat) |
| 2 | Guard Break | Back required | Moderate damage + interrupts target's current cast/channel |
| 3 | Avalanche Strike | Any position | Heavy damage + small AoE behind the target (catches adds behind) |

Wrong positional on Hit 1 or 2 → combo breaks, resets to Hit 1, no damage, GCD still consumed.

**Class Abilities:**
| # | Name | Type | Cooldown | Effect |
|---|------|------|----------|--------|
| 1 | Reckless Swing | On-GCD | — (uses GCD) | High single-target damage. +40% bonus from Front positional. Your "big combo extension" hit. |
| 2 | War Cry | Off-GCD | 45s | AoE taunt all enemies in range + grant party members a 10% damage buff for 6s (utility/offense) |
| 3 | Bulwark | Off-GCD | 25s | Damage shield: absorbs the next X damage over 8s. Generates 1 Aegis charge on full absorption. (Defensive) |
| 4 | Iron Will | Off-GCD | 60s | For 10 seconds: taking damage generates Aegis charges 2x faster AND your Mitigate Role Skill cooldown is reduced by 50%. Your "I'm about to survive something impossible" window. |

---

#### Luminary (Healer)

**Gimmick: Lumen Charge Combo.** The Luminary's combo is their *only* source of damage, and its final hit scales with how actively they've been healing. Each time a heal lands on an ally (Role Skill heals AND class ability heals count), the Luminary gains 1 **Lumen Charge** (max 3). Charges persist until spent on the combo's final hit. This creates a natural rhythm: heal through mechanic phases → burst damage during safe windows.

**Design goal: Healing is DPS-neutral.** When the Luminary spends GCD ticks healing (via Role Skills, which are off-GCD so they don't directly cost combo time) they're not losing combo progress, BUT the act of focusing on healing means they're not positioning for their own combo or weaving in damage. The Lumen Charge system compensates: the more you heal, the harder your next Nova Burst hits. A Luminary who ignores healing has a weak combo; one who keeps the party alive has devastating burst potential.

**Combo (3 hits, ranged, on-GCD):**
| Hit | Name | Range Req | Effect |
|-----|------|-----------|--------|
| 1 | Glow Shot | Min range (>8m from target) | Weak single-target damage |
| 2 | Radiant Bolt | Min range required | Medium damage + small splash to enemies within 3m of target (40% damage) |
| 3 | Nova Burst | Any range | **Uncharged (0 Lumens):** Medium AoE at target location. **1 Lumen:** +50% damage. **2 Lumens:** +100% damage. **Fully Charged (3 Lumens):** Strong AoE, large radius, consumes all charges. |

The charge state is shown on the combo button with glowing pips (0/1/2/3). Players can see at a glance whether their next Nova Burst will be weak or devastating.

**Class Abilities:**
| # | Name | Type | Cooldown | Effect |
|---|------|------|----------|--------|
| 1 | Radiant Empowerment | Off-GCD | 40s | Raid buff: all party members gain +15% Damage for 12 seconds. Your "go time" call — line it up with phase transitions or vulnerability marks. |
| 2 | Lumen Wellspring | On-GCD | — (uses GCD) | Heals the lowest-HP ally in range for a moderate amount AND generates 1 Lumen Charge immediately (regardless of heal size). Your "emergency top-off + combo fuel" tool. |
| 3 | Sanctuary Barrier | Off-GCD | 35s | Place an absorb shield on one ally: absorbs the next X damage over 10s. If the shield fully breaks, it heals the target for 20% of the absorbed amount. (Defensive) |
| 4 | Prism Refraction | Off-GCD | 55s | For 8 seconds: your heals also apply a small damage reduction (15%) to the healed ally. Your "sustain through a heavy phase" tool — makes your Role Skill heals more efficient during sustained pressure. |

Note: The Luminary's basic healing comes from **Role Skills** (Heal, Cure Aura). Their class abilities focus on *unique support identity*: raid buffs, combo fuel generation, defensive barriers, and heal efficiency. They are a **support engine**, not just a "button masher healer."

---

#### Blade (DPS — Melee)

**Gimmick: Momentum.** Each combo hit that lands in the correct positional grants +1 **Momentum** (max 5). Getting hit by an enemy attack resets Momentum to 0. At 5/5 Momentum, the next on-GCD ability used has its effect enhanced (+30% damage) AND generates a small self-heal (5% max HP). After spending it, Momentum resets to 0 and must be rebuilt through correct positional combo hits. This rewards sustained positional play and punishes getting caught in AoEs — your "reward moment" is earned through consistent correctness.

**Combo (3 hits, melee, on-GCD):**
| Hit | Name | Positional | Effect |
|-----|------|-----------|--------|
| 1 | Quick Slash | Front required | Fast, low damage. Short animation — good for repositioning quickly between GCD ticks. |
| 2 | Crescent Cut | Back required | Medium damage + applies a **Bleed** to target (3 ticks over 6s) |
| 3 | Executioner | Left OR Right required | High damage. If target has an active Bleed, consumes it for additional bonus damage (+50% of remaining bleed ticks). |

Wrong positional → combo breaks, resets to Hit 1, no damage, GCD consumed, Momentum lost.

**Class Abilities:**
| # | Name | Type | Cooldown | Effect |
|---|------|------|----------|--------|
| 1 | Blade Storm | On-GCD | — (uses GCD) | High single-target damage burst. +40% bonus from Back positional. Your "finisher" nuke — line it up when Momentum is about to spend or target is vulnerable. |
| 2 | Whirlwind | Off-GCD | 20s | AoE around self: damages all enemies within 5m. No positional required. For add cleanup. |
| 3 | Adrenaline Rush | Off-GCD | 50s | For 10 seconds: your GCD is reduced by 20% (faster combo rotation). Does NOT reset Momentum. Your "DPS window" — activate during safe phases. |
| 4 | Fatal Flank | Off-GCD | 30s | Medium damage + applies **Vulnerability** to target (+15% damage taken for 8s). Best from Left or Right (+50% effect duration). Sets up party burst windows. Overlaps with the DPS Role Skill "Vulnerability Mark" but is stronger — use when you can get the positional. |

---

#### Arcanist (DPS — Ranged/Magic)

**Gimmick: Flux Buildup.** The Arcanist generates **Flux** (max 3) when their combo hits connect without being interrupted by damage taken. Getting hit resets Flux to 0. At 3/3 Flux, the next Firebolt (combo Hit 1) becomes a **Piercing Bolt** — it passes through the primary target and strikes one additional enemy behind them for 70% damage. The visual is a bright beam that clearly shows the pierce line. This rewards staying alive and maintaining range: your "free extra hit" is earned by not getting caught.

**Combo (2 hits, ranged, on-GCD):**
| Hit | Name | Range Req | Effect |
|-----|------|-----------|--------|
| 1 | Firebolt | Min range (>6m), must have line of sight | Medium single-target projectile damage. **With 3 Flux:** becomes Piercing Bolt (hits +1 enemy behind for 70%). Consumes all Flux. |
| 2 | Arcane Lance | Min range (>6m) | High damage, short wind-up (0.3s). Pierces through target hitting one enemy in a straight line behind them for 50% damage. |

No positionals required — the Arcanist's positioning challenge is *range management* and avoiding ground AoEs while maintaining minimum distance.

**Class Abilities:**
| # | Name | Type | Cooldown | Effect |
|---|------|------|----------|--------|
| 1 | Chain Lightning | On-GCD | — (uses GCD) | Hits target + chains to up to 2 additional enemies within 8m for 60% damage each. Great for multi-target phases. Replaces a combo hit in the rotation (doesn't advance combo). |
| 2 | Meteor Call | Off-GCD | 40s | Target a ground location (within 30m). After a 2-second cast (must stand still), a meteor strikes that spot dealing heavy AoE damage. Pre-position for add packs or finish off low-HP targets. |
| 3 | Haste Sigil | Off-GCD | 45s | Increases GCD speed by 20% for 12 seconds (faster combo rotation). Your "DPS window" — time it with vulnerability buffs or phase transitions. |
| 4 | Arcane Barrier | Off-GCD | 30s | Self-protect: reduces all incoming damage by 60% for 5s + grants brief immunity to knockback/stun (defensive). Lets you push through a mechanic window safely without losing Flux. |

---

### Class Design Rules

- Every class has **at least one defensive/utility ability** among their 4 class skills.
- The Luminary is the only class without a "pure damage" class ability — their combo IS their damage, scaled by healing performance. Their class slots are support identity.
- Tank's combo damage is lower than DPS classes but their survivability and taunt (Role Skill) make them the anchor of the fight.
- Each class gimmick should be **readable at a glance** in the UI (a gauge, pips, a color shift) so players don't need to think about numbers mid-fight.
- Abilities scale with character level. Artifacts modify *how* they work, not their base power.
- Future expansion: additional classes per role (e.g., a second Tank with a different gimmick, a DPS hybrid). Target 1–2 new classes per major content update.

---

## Progression

### Levels

- **Level IS power.** Base stats (HP, Damage, Healing Power, Defense) scale with level. No item level, no gear score. Your number goes up, you hit harder and survive longer.
- Max level at launch: **15** (3 tiers × 5 levels). Increases by +5 with each new Tier content update. Long-term target: 50+.
- XP is earned from raid clears within a Tier. Once you hit the Tier's cap, that Tier gives no more XP.
- **XP scales per encounter within a tier:** Encounter 1 gives the least XP; Encounter 4 gives the most. It is *viable* to reach the tier's level cap by grinding only Encounter 1, but it takes significantly longer. Players skilled enough to clear later encounters level faster and progress to the next tier sooner. This rewards skill without gating it.
- **Tier unlock is completion-based, not level-based.** Clearing all 4 encounters in a Tier unlocks the next Tier — regardless of your current level. There is no hard level gate. However, entering a new Tier significantly underleveled makes it *much* harder (your HP/damage margins are thinner, enrage timers feel tighter). The practical advice is: stay in your level-matched tier until you hit its cap, then move on. But if you're a skilled player who's already crushing Encounter 4 of Tier 2 at level 7? Go ahead and try Tier 3. It'll be tough, but the door isn't locked.
- Revisiting an old Tier: your effective level is capped at that Tier's max, and you earn no XP (you're already past it).

### Artifacts (Horizontal Progression)

Artifacts are **build customization tools**, not power scaling. They do NOT increase your base stats in a way that makes you "stronger" than another player of the same level. Instead, they offer **trade-offs and skill modifications** that let players tailor their character to their preferred playstyle or a specific encounter's demands.

**Philosophy:** Two players at the same level should be roughly equally powerful in raw terms. The difference is *how* they express that power. One Blade might run artifacts that make their Bleed last longer but reduce their combo damage slightly. Another might run artifacts that boost their Executioner hit but remove the Bleed entirely. Both are valid; they just play differently and suit different encounter patterns.

**Slots (4):**
| Slot | Flavor | Typical Modification Focus |
|------|--------|---------------------------|
| Charm | Offensive trinket | Modifies combo behavior, damage type trade-offs |
| Ring | Utility trinket | Modifies ability effects, adds conditional triggers |
| Talisman | Defensive trinket | Modifies survivability mechanics, trade-offs for defense |
| Sigil | Identity trinket | Unique passive that alters a core class mechanic |

**What Artifacts do (examples):**

*Trade-off style (swap one thing for another):*
- "Your Heal Role Skill heals 30% less instantly, but the remaining 50% is healed over 6 seconds." (Less burst healing, more sustain — good for fights with steady damage, bad for sudden big hits)
- "Your Mitigate Role Skill lasts 4 seconds longer, but its cooldown increases by 10 seconds." (Longer safety window, less frequent)
- "Your combo's final hit deals +35% damage, but you cannot move for 1.5 seconds after it lands." (Bigger nuke, vulnerability window)

*Skill alteration style (change how a skill works):*
- "Luminary's Nova Burst (fully charged) also applies a 20% vulnerability debuff to all hit enemies for 4 seconds." (Healer's burst now sets up party damage)
- "Blade's Bleed duration is doubled, but each tick deals 40% less damage." (Longer pressure vs. immediate chunk)
- "Arcanist's Piercing Bolt hits 2 additional enemies instead of 1, but each for 50% instead of 70%." (Wider pierce, less per-target)

*Conditional trigger style:*
- "When your Momentum/Flux/Aegis gauge is at maximum, your next heal also restores 5% HP to the lowest-HP party member." (Rewards maintaining your gimmick)
- "If you take no damage for 10 seconds, your next ability has a 20% reduced cooldown." (Rewards clean play)

**Rarity Tiers:**
- **Common** — Single small trade-off or stat shift (e.g., "Heal -10%, Healing over time +15%")
- **Uncommon** — Two related modifications (e.g., "Combo Hit 3 +20% damage, GCD +0.2s for that hit only")
- **Rare** — One significant skill alteration that meaningfully changes how a class plays
- **Epic** — Unique identity-shifting passive, dropped only from specific bosses (one per encounter). Defines a "build" around it.

**Acquisition:**
- Artifacts drop from boss kills with a **chance**, not guaranteed. Each boss has a pool of possible Artifact drops (4–6 items). On kill, there is a **25% chance** an artifact drops; if it does, one is selected randomly from that boss's pool.
- This means: ~1 in 4 clears yields an artifact. Getting a specific desired artifact from a 5-item pool at 25% drop rate ≈ 1 in 20 clears on average. This is the "grind for your build" loop.
- Players can **decompose** unwanted Artifacts into **Essence**. At the hub vendor, Essence can be spent to roll a random artifact from a chosen Tier's pool (guarantees at least Uncommon rarity). This provides a slow alternative to pure RNG grinding.
- **No Artifact carries over between Tiers in terms of relevance.** Lower-tier artifacts are strictly inferior modifications. You're always working toward current-Tier artifacts for your build.

### Consumables

Players bring **2 consumable slots** into a raid. These are purchased with Gold or dropped from bosses (small chance, separate from Artifact drops).

| Consumable | Effect | Cost / Availability |
|-----------|--------|-------------------|
| Minor Health Potion | Restore 30% HP over 5s (self) | Common, cheap at shop |
| Major Health Potion | Restore 60% HP instantly (self) | Uncommon, shop + rare drops |
| **Revive Potion** | Required to use the Revive Role Skill. Channel 2s on a dead ally → 30% HP + Weakness debuff. | Rare, shop + drop. One per raid per player. |
| Power Tonic | +25% Damage for 30s (self) | Uncommon, shop + drops |
| Iron Skin Elixir | +50% Defense for 20s (self) | Uncommon, shop + drops |
| Cooldown Draught | Reduces all ability cooldowns by 15% for the fight (self) | Rare, drop only. One per raid. |

**Consumable strategy mirrors FFXIV potion planning:**
- A learning party: Major Health + Revive Potion on every member. Safety first.
- An experienced party: Power Tonic + Cooldown Draught on DPS, Iron Skin + Minor Health on tank, Cure Aura prep + no revive on healer (trust the execution).
- The Revive Potion is the biggest "do I trust my party?" decision. Bringing it costs you an offensive slot. Not bringing it means one bad wipe-adjacent moment and a player is gone for 90+ seconds (or the whole pull if others also die).

Consumables are **not shared** — each player manages their own two slots independently.

### Gold

Earned from all boss kills (scaling with Tier; first clear of an encounter gives 2x gold vs. repeats). Spent on:
- Consumables
- Artifact decompose/Essence craft service fees
- Outfits (cosmetic)
- Hub decorations / quality-of-life items

---

## The Hub

A single-player, offline area. No other players are present (except in the raid itself). This is where all meta-game activity happens.

**Hub contents:**
- **Character Screen:** Change class (no cost, instant — no "respec" fee), view/modify appearance, equip Outfits.
- **Artifact Inventory:** Sort, compare, decompose, craft via Essence. Preview trade-off descriptions clearly ("This will make your X do Y but cost Z").
- **Role Skill Loadout:** Select which 2 Role Skills to equip for your next raid. See the full pool of 4 with descriptions.
- **Consumable Prep:** Select the 2 consumables to bring into your next raid. Visible to party members in the pre-pull lobby.
- **Shop:** Buy consumables, Outfits, hub decorations with Gold.
- **Raid Board:** Browse available Tiers and their 4 encounters each (locked/unlocked), view boss info/mechanic hints, form a party or post looking for group members. Shows your current level relative to the tier's range.
- **Training Range:** A private single-player encounter with a training dummy (and optionally dummy adds). Players can test their combo rotation, GCD timing, Role Skill weaving, positional mechanics, and consumable usage in a safe space. No enrage timer, no wipe risk. The dummy can be configured to require positionals. Gives trivial XP (only useful before your first online raid). Also serves as the primary development testing environment for combat mechanics. *Launch scope: minimum (dummy + positional indicators + basic hit feedback). Simulated encounter mechanics (fake AoEs, timed events) are a post-launch addition.*
- **Lore / Bestiary:** Unlocked entries about bosses, lore fragments from encounter clears.

**Hub art direction:** A cozy, stylized tavern/camp aesthetic — think a cross between FFXIV's Gildia and a fantasy campsite. Warm lighting, simple geometry, readable at a glance. It should feel like "home" before the tension of the raid.

---

## Party Formation and Matchmaking

- **Manual:** In the Hub, a player can create a party slot (up to 4) and share an invite code (short alphanumeric string). Friends enter the code to join.
- **LFG Board:** Players post "Looking for [Role] — Tier X, Encounter Y." Other players browse and request to join. The host approves.
- **Quick Match (future):** Auto-fill empty slots with other players. Bots are a stretch goal; player quick-match is more likely first.
- **Solo with Bots:** A single-player option where the 3 missing party members are AI-controlled using the same class ability/combo/Role Skill systems. This is explicitly a later addition but should be considered in architecture from day one.

### Party Rules During a Raid

**Disconnects (FFXIV-style):**
- If a player disconnects, they are **removed from the fight.** The raid continues with remaining players. In most cases this results in a wipe due to being undermanned, but it's not automatic — if 3 players can still handle the boss, they keep going.
- There is **no time limit** on reconnecting. When the player returns, they rejoin at the current state of the fight (if still active) or at the start of the next phase. Their character respawns at the party's current location with 50% HP and a brief 5s vulnerability window to prevent instant re-engagement.

**Leaving a session:**
- If a player **voluntarily leaves** (clicks "Leave Raid"), it is **permanent for that session.** They cannot rejoin. The remaining players continue (or wipe if undermanned). The leaver returns to the Hub and must create or join a new raid instance.
- This prevents "leaving and immediately rejoining" exploit loops. A more robust drop-in/drop-out system may be added in a future update for convenience, but at launch it's binary: you're in or you're out.

**Ready check:** Before the boss pull, a ready check appears. All current party members must confirm within 10 seconds. If someone doesn't confirm, the pull is delayed (it doesn't auto-start). This gives players time to verify Role Skills, consumables, and focus targets.

**Pre-pull lobby:** After all players are in the instance but before the pull, there's a brief lobby phase where each player's equipped Role Skills and consumables are visible to the party. This is the "are we ready? Does everyone have the right tools?" moment.

---

## Encounters and Mechanics Design

### Design Philosophy

Every raid encounter should teach **one core mechanic** clearly in its early phases, then layer additional elements on top as the fight progresses. Players should be able to describe what they need to do after one wipe ("oh, I need to spread when the ground glows red").

Since there is no "easy mode," every encounter is designed at a high difficulty ceiling from the start. The first encounter in a Tier introduces new mechanical vocabulary; encounters 2–4 combine and increase density on those mechanics.

**No tutorials. No hand-holding.** There are no tutorial encounters, no forced tooltips, no "press X to learn Y" sequences. Players learn through:
- **Skill descriptions in the UI:** Reading your own ability/combo/Role Skill text should give a general understanding of your rotation and what positionals are needed. The text is the manual.
- **Telegraphs and tells:** Ground indicators, cast bars, audio cues, boss dialog. The world tells you what's about to happen.
- **Trial and error:** You die. You learn. You retry. The enrage timer is the punishment for not learning fast enough.
- **The Training Range:** A private space to experiment with your kit before going online. Not a tutorial — a sandbox.

This mirrors the FFXIV raiding culture: you read the guide (or in our case, the skill descriptions), you try it, you wipe, you figure it out with your party. The fun IS the discovery.

### Core Mechanical Vocabulary (Tier 1 introduces these)

| Mechanic | Description | Player Action |
|----------|-------------|---------------|
| **Spread** | AoE circles appear under players; standing in them deals heavy damage | Move outside all circles |
| **Stack** | A debuff stacks on party members; being near others converts it to a small shared tick instead of a large individual one | Group up tightly |
| **Tank Swap** (Tier 2+) | Boss gains an enrage stack on the current tank after X seconds; another player must taunt | Off-tank uses Taunt Role Skill to pick up aggro |
| **Positional** | A boss attack only hits players in a specific direction relative to the boss | Rotate to correct position relative to target |
| **Phase Transition** | At HP thresholds the boss changes behavior; adds may spawn, mechanics shift | Adjust strategy mid-fight |
| **Enrage** | Timer-based end condition: either a ramping damage over time ("soft") or an instant kill at a set timestamp ("hard"). Gets tighter per encounter within a tier. | DPS pressure; healer keeps party alive under stress. Soft enrage gives a warning window; hard enrage is a pure DPS race. |

### Encounter Structure (example: Tier 1, Encounter 3)

```
"Deepcurrent Leviathan" — Teaches: Spread + Phase Transition + enrage pressure

Phase 1 (100% → 60% HP): ~3 minutes
  - Boss uses basic attacks (tank taunts with Role Skill)
  - Every 25s: "Tidal Surge" — 4 AoE circles appear under random party members
    (SPREAD mechanic). Circles are visible for 3s before activating.
  - DPS maintain combo rotation, healer keeps tank topped with Heal Role Skill
  - Teaches: reading ground indicators, spread positioning, GCD rhythm

Phase 2 (60% → 30% HP): ~3 minutes
  - Boss gains "Crushing Wave" — a frontal cone attack every 20s.
    Players must be OUT of the front arc (positional awareness).
  - Tidal Surge continues but circles now appear in PAIRS (two simultaneous)
    and shrink over 4s instead of being instant. Tighter movement.
  - At 45% HP: 2 "Current Add" fish spawn — they apply a STACK debuff to
    random party members every 10s. Party must group to share the tick
    while DPS priority-shift to kill adds quickly.
  - Teaches: positional dodges + stack management + target switching

Phase 3 (30% → 0% HP): ~3 minutes (enrage timer active)
  - Boss enters "Leviathan's Wrath": attack speed +30%, Tidal Surge circles
    are 50% larger, Crushing Wave cone is wider.
  - Enrage timer: 3 minutes (total fight should be ~9 min; this is the DPS race)
  - All mechanics from Phases 1+2 continue simultaneously at increased frequency.
  - Teaches: sustained execution under pressure, consumable timing
    (this is when Power Tonics and Cooldown Draughts go in)

Total expected fight time: 8–10 minutes for a competent party.
Enrage timer: 13 minutes (generous for learning, tight for sloppy play).
```

### Difficulty Scaling Within a Tier

The 4 encounters in a Tier share mechanical vocabulary but increase **execution density:**
- **Encounter 1:** Introduces the Tier's new mechanic(s) clearly. Generous timing windows. "Learn it."
- **Encounter 2:** Combines the new mechanic with one from a previous Tier. Slightly tighter windows. "Apply it."
- **Encounter 3:** Multiple mechanics overlap simultaneously. Adds target-switching pressure. "Do it while also doing that."
- **Encounter 4:** The Tier's capstone. All mechanics at maximum density, tightest timing, shortest enrage margin. "Prove you've got it."

### Boss Tells and Readability (FFXIV-style)

Players are given the same types of warnings FFXIV uses:
- **Cast bars** on the boss for telegraphed attacks (shows ability name + remaining cast time)
- **Ground indicators** (colored circles, cones, lines) appear BEFORE the damage hits. Color coding: red = damage to player, blue = heal/buff zone, yellow = "stand here" stack point.
- **Audio cues** — distinct sounds for different mechanic types (a deep rumble before a ground AoE, a sharp chime for a positional requirement)
- **UI callouts** — brief text popups for major phase transitions ("PHASE 2 — Leviathan's Wrath")

Timing windows are generous enough that a player who *sees* the tell can react, but tight enough that you can't just camp in one spot. Normal reaction window: 1.5–3 seconds from tell to impact.

---

## Artifacts and Outfits (Separation of Concerns)

### Artifacts (Combat / Build)
- No visual representation on the character model.
- Shown as icon + trade-off description in inventory/UI.
- Modify **how** your abilities work, not raw power numbers.
- Dropped from raids (chance-based, not guaranteed). This is the "build" progression.
- Horizontal: two players at the same level are equally powerful; they just play differently.

### Outfits (Cosmetic)
- Change the character's visual model (clothing, armor style, accessories).
- Have **zero combat effect.** A player in a flashy outfit hits exactly as hard as one in defaults.
- Acquired via: Gold purchases at the shop, rare raid cosmetic drops (a unique look per Tier), or achievement unlocks.
- This separation means players can be competitive without being "fashion-gated," and cosmetics remain purely expressive.

---

## Character Creator

Simple, anime/cartoon-styled character customization. No body sliders — a curated set of options to keep the pipeline manageable and the style consistent.

| Feature | Options (launch) |
|---------|-----------------|
| Gender | Male / Female / Non-binary (affects base model proportions + voice lines if any) |
| Face shape | 5 presets |
| Eyes | Shape (4) × Color (12) |
| Hair | Style (12) × Color (16, including fantasy colors) |
| Skin tone | 8 swatches |
| Distinguishing marks | Scars, freckles, markings (3 slots, optional) |
| Name | Text input, 3–16 chars |

No height slider. No body type slider. The anime style keeps proportions stylized; the creator is about *identity*, not realism.

---

## Controls

### Mouse + Keyboard
| Input | Action |
|-------|--------|
| WASD / Arrow Keys | Move |
| Space or LMB (click) | Combo Attack (advances to next hit, consumes GCD) |
| 1–4 | Class Abilities 1–4 |
| Z | Role Skill 1 |
| X | Role Skill 2 |
| Right-click | Target enemy |
| Tab | Cycle targets |
| Q | Focus target (secondary) |
| C | Use consumable 1 |
| V | Use consumable 2 |
| F | Interact / Revive channel start (when near corpse with Revive Potion + Role Skill) |
| B | Character / Inventory screen |
| N | Party frames toggle position |
| M | Map (if applicable to raid layout) |

### Gamepad
| Input | Action |
|-------|--------|
| Left Stick | Move |
| R2 / RT | Combo Attack (advances to next hit, consumes GCD) |
| X/A, Y/B, B/X, A/... (face buttons) | Class Abilities 1–4 |
| L1 / LB | Role Skill 1 |
| L2 / LT | Role Skill 2 |
| R1 / RB | Use consumable 1 |
| R3 / RS click | Use consumable 2 |
| D-Pad left/right | Cycle targets |
| L3 / LS | Target closest enemy |
| Start / Menu | Inventory / Pause |

All mappings are rebindable in settings.

---

## UI / HUD Design

**In-combat HUD (minimal, readable at a glance):**
- **Bottom center:** Ability bar — 4 class ability icons + 2 Role Skill icons + Combo Attack button. The GCD radial sweep overlays the entire bar (shows when you can act). Off-GCD abilities show their own independent cooldown radials. Consumable slots (2) flank the right side.
- **Combo button detail:** Shows current hit number (1, 2, or 3), a directional arrow if the current step requires a positional, and class gimmick pips (Lumen Charges for Luminary, Flux for Arcanist). A brief "COMBO BROKEN" flash on wrong positional.
- **Top left:** Party frames — 4 horizontal bars showing HP. Dead players show a greyed-out frame with "DEAD" text. Weakness debuff shown as a small clock icon. Role Skill active effects shown as small icons on the frame.
- **Top right:** Boss health bar + enrage timer countdown (turns red in final 60s). Phase indicator (e.g., "Phase 2"). Phase progress within current phase shown as a thin sub-bar.
- **Center screen:** Target frame — small portrait, HP bar, debuff icons on the target. Positional requirement arrow for current combo step appears here when applicable. Boss cast bar appears here during telegraphed attacks.
- **Bottom left:** Active buff/debuff icons on self + class gimmick gauge:
  - Warden: 3 Aegis pips that glow when charged
  - Luminary: Lumen charge pips (also shown on combo button)
  - Blade: Momentum bar (0–5 segments)
  - Arcanist: 3 Flux pips (also shown on combo button)
- **Kill feed / mechanic callouts:** Brief text popups for important events ("PHASE 2", "Boss is casting Crushing Wave!"), positioned top-center.

**GCD visual:** The global cooldown is shown as a subtle radial sweep across the bottom ability bar. When the GCD is active, on-GCD abilities (combo button + any on-GCD class skills) are slightly dimmed. Off-GCD abilities remain at full brightness with their own cooldown timers. This lets players see at a glance "what can I do RIGHT NOW" vs. "what's coming in 2 seconds."

**Design rule:** The HUD should occupy less than 20% of screen real estate. The player's eyes should be on the *world* (enemy tells, ground effects, party positioning) not on UI elements. Gimmick indicators and GCD state should be readable in a single peripheral glance without looking down.

---

## Audio Direction

- **Combat music:** Intense, driving tracks — think FFXIV Savage raid themes. One track per boss encounter, with intensity shifts at phase transitions (new instrumentation, tempo increase). The music should make you *feel* the pressure of the enrage timer in final phases.
- **Hub music:** Warm, acoustic, inviting. Should feel like a contrast to the raid tension. A place to breathe between fights.
- **SFX:** Punchy, cartoon-style hit sounds. No gritty realism — matches the art style. Combo hits have distinct audio per step (Hit 1 = light "shink," Hit 2 = heavier "clash," Hit 3 = big "CRACK") so players can feel rotation rhythm by ear. GCD completion has a subtle "click" so you can time weaves auditorily.
- **Voice:** No full voice acting at launch. Short exclamation lines on class abilities (grunts, "Hah!", spell chants) add flavor without budget. A distinct vocal cue when a player dies and when they're revived ("...alright, I'm back").

---

## Technical Notes (Godot-specific)

### Architecture Considerations
- **Authoritative server model.** The game server owns all combat state: positions, HP, GCD timers, combo states, gimmick gauges, debuffs/buffs. Clients send input; server validates and broadcasts. This is non-negotiable for a competitive raid game — client-side prediction for movement only, not damage or combo progression.
- **Network:** Use Godot's multiplayer (ENet or WebRTC). Target: 4 clients + 1 authoritative server (architecture supports up to 8 for future content). Bandwidth should be trivial at this player count; the main concern is latency (<80ms RTT target) and consistency on GCD timing and mechanic triggers.
- **Raid instances are ephemeral.** A raid session exists only while players are in it. No persistent world simulation outside raids. The hub is a local scene with no server component (until LFG/matchmaking needs a presence server).
- **Save data:** Local + cloud sync (Godot doesn't have this built-in; use a lightweight backend like Supabase or a custom REST API for account, progress, inventory, and Artifact persistence).

### Hard Architecture Rule: Logic/Presentation Separation

This is a **non-negotiable structural constraint** on the codebase. All game logic must be separable from Godot's scene tree so that mechanics can be unit-tested headless (no renderer, no window, no GPU) via `godot --headless`.

**The rule:** Everything in `logic/` is a **refcounted GDScript class** (`class_name X`). No `extends Node`. No signals. No `_process()`, `_ready()`, or any lifecycle callbacks. No references to scenes, views, input, or rendering. These are pure data + behavior objects.

Everything in `game/` extends Node and handles presentation: rendering, input polling, animation, camera, UI updates. It **calls into** `logic/` classes but never contains game rules itself.

| Layer | Directory | Extends | Contains | Tests via |
|-------|-----------|---------|----------|-----------|
| Logic | `logic/` | `RefCounted` (implicit) | Combat formulas, GCD timing, combo state machines, damage calc, artifact modifiers, progression math, raid state, boss AI decisions | GUT headless (`godot --headless`) |
| Game | `game/` | `Node2D`, `Node3D`, `Control`, etc. | Player controllers, boss entities, HUD, camera, input handling, animation playback, network sync glue | Manual / integration |
| Data | `data/` | JSON / Resource files | Balance numbers, encounter timelines, class definitions, artifact definitions | Validated by logic tests |

**What this looks like in practice:**

```gdscript
# logic/combat/gcd_timer.gd
class_name GCDTimer
extends RefCounted  # implicit — no "extends Node"

var _remaining: float = 0.0
var _total: float = 2.5

func _init(gcd_duration: float = 2.5):
    _total = gcd_duration
    _remaining = 0.0

func is_ready() -> bool:
    return _remaining <= 0.0

func tick(delta_time: float) -> void:
    if _remaining > 0.0:
        _remaining = max(_remaining - delta_time, 0.0)

func consume() -> bool:
    if not is_ready():
        return false
    _remaining = _total
    return true

func get_progress() -> float:
    if _total <= 0.0: return 1.0
    return 1.0 - (_remaining / _total)
```

```gdscript
# tests/test_gcd.gd
extends GutTest

func test_gcd_blocks_immediate_reuse():
    var gcd = GCDTimer.new(2.5)
    assert_true(gcd.consume())       # First use: succeeds
    assert_false(gcd.is_ready())     # Not ready yet
    assert_false(gcd.consume())      # Second use: blocked

func test_gcd_recovers_after_duration():
    var gcd = GCDTimer.new(2.5)
    gcd.consume()
    gcd.tick(1.0)                    # 1s elapsed
    assert_false(gcd.is_ready())     # Still not ready
    gcd.tick(1.5)                    # 2.5s total elapsed
    assert_true(gcd.is_ready())      # Now ready
    assert_true(gcd.consume())       # Can use again
```

Run with: `godot --headless -s res://tests/run_all.gd` — completes in milliseconds, no window, no GPU.

**Why this matters for AI-driven development:**
- An AI can write and verify combat logic, progression math, and encounter timelines entirely through headless tests without ever touching the rendering pipeline.
- Iteration speed: change a damage formula → run test → see pass/fail in <1s. No scene loading, no asset imports, no editor.
- The `game/` layer becomes a thin "adapter" that reads from logic state and updates visuals. It's the easiest layer to write (and rewrite) because it contains no rules — just "if HP < max, set bar width to HP/max."

**Enforcement:** Code review rule — any `extends Node` in `logic/` is a blocker. Any game rule (damage formula, cooldown check, state transition) in `game/` is a refactor target. The CI/test pipeline should fail if a logic class accidentally references a Node type.

### GCD and Combo System Implementation
- The GCD timer is **server-authoritative.** Client sends "attack pressed" or "ability X pressed" input. Server checks: Is the GCD ready? Is the ability off-cooldown? Is the positional correct (for combo hits)? If all valid → advance state, apply effects, broadcast to all clients.
- **Input queuing:** If a player presses an on-GCD action while the GCD is still active (last 0.3s of the sweep), it queues and fires the instant the GCD completes. This prevents the frustrating "I pressed it but the GCD wasn't quite done" feel.
- Combo state machine lives on the server per player: current hit index, positional requirement for current hit, gimmick gauge values.
- Off-GCD abilities are checked independently — they don't wait for or affect the GCD timer.
- Gimmick gauges (Momentum, Flux, Aegis, Lumen Charges) are server-state, synced to all clients each tick.

### Disconnect Handling
- The server maintains raid state independently of any single client. If a player disconnects, their character is marked "absent" — they don't contribute damage, can't be targeted, and their party frame shows "DISCONNECTED." No corpse remains (they weren't "killed," just gone).
- Reconnection: when the player's client re-establishes connection with valid session token, they rejoin at current raid state. Their character spawns at party location with 50% HP + 5s vulnerability. If the current phase is mid-mechanic, they get a brief 2s "catch up" window where they're invulnerable while the scene renders for them.
- No timeout — the server keeps the instance alive as long as ≥1 player remains connected.

### Project Structure (high-level)
```
project/
├── logic/           # PURE GDScript. No "extends Node." Fully testable headless.
│   ├── combat/
│   │   ├── gcd_timer.gd          # GCD timing, input queuing
│   │   ├── combo_state.gd        # Combo state machine (hit index, positional checks)
│   │   ├── damage_calculator.gd  # Damage formulas, crits, modifiers
│   │   ├── ability_resolver.gd   # Ability activation, cooldown checks, effect application
│   │   └── gimmick_gauges.gd     # Momentum, Flux, Aegis, Lumen Charge logic
│   ├── progression/
│   │   ├── xp_system.gd          # XP curves, level caps, tier gating
│   │   ├── artifact_mods.gd      # Artifact trade-off application to ability params
│   │   └── drop_table.gd         # Loot roll logic (25% chance, pool selection)
│   ├── network/
│   │   ├── raid_state.gd         # Authoritative server state for a raid instance
│   │   ├── input_validator.gd    # Validates client inputs against server state
│   │   └── sync_protocol.gd      # What to broadcast, when, to whom
│   └── ai/
│       ├── boss_director.gd      # Reads encounter timeline, fires phase/mechanic events
│       └── boss_ability.gd       # Individual boss ability logic (casts, triggers)
├── game/            # Node-based. Presentation + input + rendering. Calls into logic/.
│   ├── hub/
│   │   ├── hub_scene.tscn
│   │   ├── character_screen.tscn
│   │   ├── shop.tscn
│   │   └── raid_board.tscn
│   ├── raid/
│   │   ├── t1e1_arena.tscn
│   │   ├── t1e2_arena.tscn
│   │   ├── ...
│   │   ├── player_controller.gd  # Input → logic calls. Animation playback.
│   │   └── boss_entity.gd        # Renders boss state from raid_state. Plays VFX.
│   ├── ui/
│   │   ├── hud.tscn
│   │   ├── party_frames.tscn
│   │   ├── combo_indicator.tscn
│   │   ├── gcd_bar.tscn
│   │   └── inventory.tscn
│   └── character_creator.tscn
├── data/            # JSON / Resource files for balance. No logic.
│   ├── classes.json        # Combo definitions, abilities, gimmick params, GCD values
│   ├── role_skills.json    # Role skill pools per role
│   ├── artifacts.json      # All artifacts with trade-off descriptions + effect params
│   ├── bosses/             # One file per encounter: timeline, phases, mechanics
│   │   ├── t1e1.json
│   │   ├── t1e2.json
│   │   └── ...
│   └── consumables.json
├── tests/           # GUT test files. Instantiate logic/ classes directly. Headless.
│   ├── combat/
│   │   ├── test_gcd.gd
│   │   ├── test_combo_positional.gd
│   │   ├── test_damage_calc.gd
│   │   └── test_gimmick_gauges.gd
│   ├── progression/
│   │   ├── test_xp_curves.gd
│   │   ├── test_artifact_mods.gd
│   │   └── test_drop_table.gd
│   └── network/
│       └── test_raid_state.gd
└── assets/
    ├── models/
    ├── animations/
    ├── audio/
    └── ui/
```

### Boss AI
- Behavior tree or state-machine based (Godot has no built-in BT; use a lightweight library or hand-roll a simple one).
- Each boss is a data-driven definition: HP, abilities with cooldowns/triggers, phase thresholds (HP % or timed), mechanic timelines. A "boss director" script reads the timeline and fires events; individual ability logic lives in attached scripts.
- Boss encounters are authored as **timed event scripts** with conditional branches based on party state (e.g., "if tank HP < 30%, delay next mechanic by 2s to avoid trivial wipe").
- **Boss dialog:** Each boss has at minimum 2 short voice/text lines: an **introduction** (played when the encounter starts, sets tone/lore) and an **enrage line** (played when soft enrage triggers or hard enrage is approaching — "Enough games. Let's finish this!"). Some bosses may have additional lines at phase transitions depending on their personality and lore. Lines are short (1 sentence), punchy, and delivered as on-screen text with a subtle voice grunt/exclamation (no full voice acting). The specific number of lines per boss is a design choice based on the character — a theatrical villain gets more lines than a silent ancient beast.

### Performance Targets
- 60 FPS on mid-range hardware (GTX 1060 / RX 580 class) at 1080p.
- Stylized art keeps draw calls low; no post-processing beyond a simple outline pass and tone mapping.
- Raid arenas are enclosed, small spaces — no large open worlds to render.

### Future: 8-Player Raids
The architecture should support scaling from 4 to 8 players without fundamental changes:
- Party frame UI scales (2 rows of 4 instead of 1 row of 4)
- Boss HP and enrage timers scale with player count (data-driven multiplier)
- Mechanics that reference "the party" work the same at 8 as at 4 (spread = spread more, stack = stack in groups of 4)
- New encounter types can be designed specifically for 8-player dynamics (e.g., two-tank swaps, split-party mechanics where 4 players handle one side while 4 handle another)
- Role Skill system scales naturally: 2 tanks, 2 healers, 4 DPS

---

## Scope: Launch vs. Post-Launch

### Launch (MVP)
- 4 classes (one per role), each with combo attack + 4 class abilities + class gimmick
- Role Skill system (2 Core always-equipped + 1 Specialist chosen from pool per role)
- GCD-based combat with positional combos and off-GCD weaving
- Tier 1–3 (12 unique boss encounters) fully playable online
- Hub with character creation, class selection, shop, artifact inventory, consumable prep, Role Skill loadout
- Manual party formation (invite codes) + LFG board
- Core combat loop: GCD rhythm, combo rotation with positionals, class gimmicks, Role Skill weaving, spread/stack/enrage
- Death / Revive Potion / Weakness debuff system
- Artifact drops (chance-based), decompose/Essence system
- Gold economy
- Basic UI/HUD as described including GCD bar, combo indicators, gimmick gauges
- Mouse+Keyboard and Gamepad support
- Disconnect handling (FFXIV-style, no timeout)

### Post-Launch Roadmap (rough order)
1. **Tier 4 content** (4 new encounters, level cap → 20), LFG board improvements
2. **Quick Match with bots** (solo mode using same class/GCD/Role Skill systems)
3. **Additional classes** (5th and 6th — a second Tank or a hybrid DPS with unique gimmick)
4. **Outfit shop expansion**, raid cosmetic drops per Tier
5. **Leaderboard / clear times** per encounter (speedrun element; wipe count as tiebreaker)
6. **Co-op modifiers** ("Ironman" — no consumables allowed; "Blind" — no UI mechanic callouts, relies on audio/visual tells only) for replayability
7. **8-player raid content** (new Tier designed for larger groups, or a separate "Grand Raid" mode)
8. **Cross-platform** (console, if engine licensing permits)

---

## Resolved Design Decisions

| Question | Decision |
|----------|----------|
| PvP? | No. PvE only. The game is about cooperating with your party against designed encounters. |
| Difficulty modes? | No Normal/Savage split. One difficulty per encounter, tuned to FFXIV Savage-level challenge. The game IS the hard mode. |
| Multiple bosses per raid? | No. Each raid = one boss encounter. Each tier = 4 encounters. Matches FFXIV structure. |
| Power source? | Level. No gear score. Artifacts are horizontal (build expression, not raw power). |
| Party size beyond 4? | Launch is locked to 4. Architecture supports up to 8 for future content. |
| Disconnect behavior? | FFXIV-style: raid continues without them (likely wipe), no reconnect timeout, rejoin at current state. |
| Leaving a session? | Permanent for that instance. Must create/join a new raid to play again. |
| Class depth / skill tree? | No skill tree. Depth comes from: GCD combo system with positionals, class gimmicks, Role Skill loadout choice, and Artifact trade-offs that modify ability behavior. |
| Weakness debuff duration? | 90 seconds, -25% Damage/Healing. Static across all tiers. Will tune via playtesting. |
| Lumen Charge generation? | Counter-based: +1 charge per heal cast (not per HP amount). Design goal: healing is DPS-neutral. |
| Revive necessity? | Experienced players should never need one. It's a risk/reward insurance choice, not a requirement. |
| GCD duration? | 2.5s default for all classes at launch. May vary slightly per class post-playtest. |
| Boss tells? | FFXIV-style: cast bars, ground indicators (color-coded), audio cues, UI phase callouts. |

---

## Resolved Design Decisions (Round 2)

| Question | Decision |
|----------|----------|
| Artifact drop rate / rarity gating? | Flat 25% drop chance for ALL artifacts regardless of rarity. No super-rare gated items. Every artifact is an "essential build piece" — no artifact should be so rare that lacking it makes a player unplayable in a party. Adjust rate post-launch if needed. |
| Role Skill structure? | **Option A: 2 Core (always equipped) + 1 Specialist (chosen from pool).** Healer Core: Heal + Status Cure. Tank Core: Taunt + Mitigate. DPS Core: Self-Heal + Boss Weaken. Specialist pools offer situational tools (Revive, AoE heal, Iron Guard, Vulnerability Mark, etc.). Revive is a *specialist* choice — a deliberate risk/reward decision, not a given. |
| GCD value and modification? | 2.5s default for all classes at launch. GCD is **modifiable by Artifacts** (e.g., "-0.1s GCD" on a Charm, or "+0.1s GCD but +10% Damage" as a trade-off). One class may get a small innate GCD reduction as part of its identity (TBD). This makes GCD a build consideration without breaking the core rhythm. |
| Encounter length target? | **7–10 minutes** per boss encounter (matching actual FFXIV Savage clear times). Tight, dense, no filler. Phases should be short and punchy rather than long and drawn out. |
| Launch content & release cadence? | Tiers 1–2: "onboarding" difficulty, beatable in a couple of hours total (first 10 levels). Tier 3+: full FFXIV Savage-equivalent difficulty. Expected clear time for a new tier: ~1 week of practice for a coordinated 4-man group (vs. 2–3 weeks in FFXIV, partly because we're 4-player not 8). **Launch:** 3 tiers. **Tier 4:** ready within a few weeks post-launch. **Ongoing:** new tier every 1–2 months, plus other content (new classes, modifiers, cosmetics) to keep engagement between tiers. |
| Trading / item transfer? | **No trading system.** No way to give, sell, or transfer items to other players. Artifacts are bound to the player who loots them. Gold is personal. Keeps the economy simple and prevents power-gating through item hoarding. |
| Pre-encounter information? | **Organic discovery.** No pre-clear mechanic guides, no boss strategy previews. Players learn through telegraphs, trial, and error. A skilled player should be able to read tells and solve mechanics on the fly; most players will learn through wipes. The Bestiary fills in *after* first clear (lore + mechanic summary for reference), but nothing is revealed before you've seen the fight. |

---

## Resolved Design Decisions (Round 3)

| Question | Decision |
|----------|----------|
| Role Skill structure? | **2 Core (always equipped) + 1 Specialist (chosen pre-pull).** Healer: Heal + Status Cure / pool includes Revive, Cure Aura, Sanctuary. Tank: Taunt + Mitigate / pool includes Provoke, Iron Guard, Rallying Shout. DPS: Self-Heal + Boss Weaken / pool includes Signature Strike, Cleave, Vulnerability Mark, Focus Fire. |
| Enrage timer design? | **Two types:** "Soft" (boss dialog + ramping raid-wide attack, boss behavior IS the tell) and "Hard" (instant kill at timestamp, shown as UI countdown). Early encounters lean soft; later ones go hard. No separate enrage UI for soft — the boss getting angrier is the warning. |
| XP distribution within a tier? | **Later encounters give more XP.** Enc 1 < 2 < 3 < 4. Viable to cap by grinding Enc 1, but slower. Rewards skill. |
| Tier unlock gating? | **Completion-based.** Clear all 4 → next tier unlocks. No hard level gate. Underleveled = harder, not locked. |
| Tier 1–2 difficulty? | Same systems, less dense encounters. Fewer phases, generous windows. Teaches vocabulary gently. Tier 3+ is full Savage density. |
| DPS Weaken design intent? | Raid-wide support debuff on the boss (reduces ALL outgoing damage). Complements tank Mitigate (personal) and healer Sanctuary (single-target). Proper layered mitigation is a raid mechanic. Critical at low levels, more lenient at tier cap. |
| Status Cure scope? | Per-status `curable` flag. White underline in HUD for curable effects (FFXIV-style). Boss mechanics: usually curable. Player offensive debuffs: usually NOT curable. Exception: specific high-tier Artifacts may create curable offensive debuffs as team dynamic spice. |
| Specialist pool size? | 3–4 options per role at launch. Expand with content updates. |
| Onboarding / tutorials? | **None.** No tutorial encounters, no forced tooltips. Players learn from skill descriptions, telegraphs, trial/error, and the Training Range (private sandbox). The enrage timer punishes not learning. The fun IS self-discovery. |
| Mitigation stacking? | **Sequential, highest-first.** Each % mitigation is applied to the remaining damage after the previous one. Sorted highest → lowest before processing. Absorb shields subtracted after all % mits. Can never reach 0 through % stacking alone (no 100% mit abilities exist). Example: 100 dmg with 60%/40%/20% mits → 19 final. |
| Training Range launch scope? | **Minimum.** Dummy + positional indicators + basic hit feedback. No simulated encounter mechanics at launch. Post-launch expansion can add fake AoEs, timed events, etc. |
| Boss dialog? | **Minimum 2 lines per boss:** introduction + enrage. Additional phase-transition lines at the designer's discretion based on boss personality/lore. Short (1 sentence), on-screen text + subtle voice grunt. No full voice acting. |

---

## Open Questions (next iteration)

1. **Specific mitigation values per tier:** We have the stacking formula, but what are the actual % values for each mitigation source at each tier? As boss damage scales up with tiers, do mitigation percentages stay flat (and just matter more because the base number is bigger) or do they need to scale? Probably flat — the formula handles it naturally since higher base damage × same % = still meaningful reduction.

2. **Absorb shield values:** Iron Guard and Luminous Ward use "absorbs the next X damage." What is X relative to player HP at each tier? Probably a fixed % of max HP (e.g., 30%) so it scales naturally with level. Needs balancing against boss hit patterns.

3. **Combo break feedback:** When a melee player uses the wrong positional and their combo breaks, what's the feedback? A visual flash on the combo button? A sound? A brief "BROKEN" text? How punishing should it *feel* without being rage-inducing? Probably: distinct audio cue (a dull "thud" vs. the normal hit sound) + combo button flashes red briefly + GCD still consumed (you lost that tick). No additional penalty beyond losing progress.

---

*Document version: 0.6 — Mitigation stacking formula, Training Range launch scope confirmed, boss dialog guidelines, all prior open questions resolved.*