# TECHNICAL & GAME DESIGN SPECIFICATION: QUEST & MILESTONE SYSTEM
# PROJECT FREEEXILE: DARK MARTIAL ASTRAL 2.5D ARPG

> **Responsible Departments**: Lead Systems Designer (`poe2_game_designer`), Lead Documentation Architect (`lead_documentation_architect`), Lead Localization Architect (`localization_lead`).  
> **Document Version**: 1.0.0-RELEASE  
> **Governs**: [Game Server Quest Engine](file:///c:/Projects/FreeExile/server/world/quest_engine.py), [Protobuf Protocol](file:///c:/Projects/FreeExile/proto/quest.proto), [Wiki Service](file:///c:/Projects/FreeExile/server/common/wiki_service.py).

---

## 1. ARCHITECTURAL OVERVIEW & PHILOSOPHY

In the **Dark Astral Martial** universe of `FreeExile`, exiled wanderers step into the **The Savage Deadlands** without the generic quest tropes of traditional MMORPGs (no mindless fetch quests, zero inflationary gold rewards). The Quest System is anchored on three foundational pillars:

1. **Barter Spiritual Stone Economy Integration**:
   - All quest rewards and milestone achievements grant actual [Crafting Spiritual Stones & Sigils](file:///c:/Projects/FreeExile/wiki/en/CURRENCIES_AND_SPIRIT_STONES_SPECS.md): [Primal Bloodstones](file:///c:/Projects/FreeExile/wiki/en/CURRENCIES_AND_SPIRIT_STONES_SPECS.md#21-primal-chaos-stone), [Ancient Bone Brands](file:///c:/Projects/FreeExile/wiki/en/CURRENCIES_AND_SPIRIT_STONES_SPECS.md#22-destiny-rune), [Wraithbone Spikes](file:///c:/Projects/FreeExile/wiki/en/CURRENCIES_AND_SPIRIT_STONES_SPECS.md#23-sovereign-sigil), and the ultimate [Savage Blood Mirror](file:///c:/Projects/FreeExile/wiki/en/CURRENCIES_AND_SPIRIT_STONES_SPECS.md#24-void-mirror-relic).
   - Unlocks permanent **Astral Meridian Points** directly on the 1,500+ acupoint Savage Bone Matrix.

2. **Three-Tier Quest Architecture**:
   - **Normal Quests (Main & Regional)**: World onboarding, teaching foundational survival mechanics, and unlocking core features.
   - **Cryptic Hidden Quests (Secret Encounters)**: Completely invisible in the quest log until specific environmental, combat, or astral prerequisites are met.
   - **High-Tier Astral Quests (Epic Trials)**: Endgame boss encounters, deep demonic sealing matrices, keystone acupoint breakthroughs, and artifact mirroring.

3. **Milestone Tier Progression**:
   - Accumulative milestones (Tier I to Tier V) rewarding comprehensive mastery, providing massive currency caches, prestige titles, and expanded consignment vault capacity.

```mermaid
flowchart TD
    subgraph Three_Tier_Quests["THREE-TIER QUEST ARCHITECTURE"]
        NORM["Normal Quests<br/>(Main Story & Regional)"]
        HIDDEN["Cryptic Secret Quests<br/>(Environmental & Combat Triggers)"]
        EPIC["High-Tier Astral Quests<br/>(Golden Bosses & Keystone Break)"]
    end

    subgraph Server_Authority["SERVER-AUTHORITATIVE ENGINE"]
        QE["QuestEngine<br/>(server/world/quest_engine.py)"]
        VERIFY["Zero-Trust Progress Validation<br/>(Combat, Movement, Crafting Authority)"]
    end

    subgraph Milestone_Tiers["MILESTONE PROGRESSION"]
        M1["Tier I: Exile Realm Novice"]
        M2["Tier II: Meridian Grandmaster"]
        M3["Tier III: True Martial Renown"]
        M4["Tier IV: Savage Exile Pioneer"]
        M5["Tier V: Sovereign of Realms"]
    end

    NORM --> QE
    HIDDEN --> QE
    EPIC --> QE
    QE --> VERIFY
    VERIFY --> Milestone_Tiers
```

---

## 2. NORMAL QUESTS (MAIN STORYLINE & REGIONAL PROGRESSION)

Normal quests guide the player from an outcast awakening at Buried Sword Cliff to a seasoned martial artist versed in primal stone alchemy.

### Detailed Normal Quest Registry

| Quest ID | Title & Region | Req. Level | Prerequisite | Authoritative Objective | Rewards & Meridian Points |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `quest_norm_01_thuc_tinh_tang_kiem` | **Awakening at Buried Sword Cliff** *(Buried Sword Cliff)* | Lv 1 | None | Defeat $5$ [Corrupted Bone Hounds](file:///c:/Projects/FreeExile/wiki/en/MONSTERS_AND_BOSSES_SPECS.md#21-corrupted-bone-hound) (`mob_trash_bone_hound`) | • 500 EXP<br/>• Crude Flint x5<br/>• +1 Meridian Point<br/>• Title: *The Awakened Exile* |
| `quest_norm_02_khai_thong_dan_dien` | **Origin Dantian Awakening** *(Savage Bone Matrix)* | Lv 2 | `quest_norm_01` | Unlock the Origin Dantian acupoint (`meridian_origin_dantian`) | • 1,200 EXP<br/>• Feral Amber x3<br/>• +2 Meridian Points |
| `quest_norm_03_luyen_khi_hoa_thach` | **Primal Chaos Smelting** *(Crafting UI)* | Lv 5 | `quest_norm_02` | Craft $1$ [Primal Bloodstone](file:///c:/Projects/FreeExile/wiki/en/CURRENCIES_AND_SPIRIT_STONES_SPECS.md#21-primal-chaos-stone) | • 2,500 EXP<br/>• Primal Bloodstone x3<br/>• Blood Whetstone x5<br/>• +2 Meridian Points |
| `quest_norm_04_diet_u_hon_kiem_no` | **Liberate Ghost Sword Thralls** *(Ancient Sword Mound)* | Lv 8 | `quest_norm_03` | Slay $10$ [Ghost Sword Thralls](file:///c:/Projects/FreeExile/wiki/en/MONSTERS_AND_BOSSES_SPECS.md#22-ghost-sword-thrall) (`mob_trash_ghost_sword_thrall`) | • 4,000 EXP<br/>• Primal Bloodstone x5<br/>• Feral Amber x5<br/>• +3 Meridian Points |
| `quest_norm_05_khai_mo_van_gioi_cac` | **Outcast Vault Consignment** *(Trading Feature)* | Lv 10 | `quest_norm_04` | Execute $1$ Instant Buyout transaction (`action_vault_instant_buyout`) | • 6,000 EXP<br/>• Primal Bloodstone x10<br/>• Ancient Bone Brand x1<br/>• +3 Meridian Points<br/>• Title: *Vault Merchant* |

---

## 3. CRYPTIC HIDDEN QUESTS (SECRET ANCIENT ENCOUNTERS)

Hidden quests embody the organic serendipity of classical martial arts tales. No NPC indicators or map markers exist for these quests.

```mermaid
sequenceDiagram
    autonumber
    actor Player as Savage Exile (Client)
    participant MoveAuth as Movement Authority
    participant Combat as Combat Engine
    participant QE as Quest Engine (Server)
    participant Haptics as Apple Core Haptics (iOS)

    Note over Player,Combat: Scenario: HP at 8% in Blood Scale Ruins
    Player->>MoveAuth: Execute Phantom Evasion (Huyễn Ảnh Bộ)
    MoveAuth->>Combat: Validate i-frame avoidance
    Combat->>QE: Trigger Event: EVASION_NEAR_DEATH (HP: 8%, Zone: Blood Scale)
    QE->>QE: Evaluate criteria: trigger_hidden_quest()
    Note over QE: Condition met! Activate: quest_hidden_01_huyen_anh_to_su
    QE-->>Player: Packet QuestProgressSyncNotice (Status: IN_PROGRESS)
    Player->>Haptics: Play Secret Pulse Haptic (Sharpness: 0.95)
```

### The 4 Great Cryptic Hidden Quests

#### 3.1. Phantom Secret Vault (`quest_hidden_01_huyen_anh_to_su`)
- **Secret Trigger (`HiddenTrigger`)**:
  - In `zone_blood_scale_ruins`.
  - Player health drops to critical threshold: $HP < 10\%$.
  - Execute **Phantom Evasion** with perfect timing against an incoming lethal strike.
- **Narrative**: The dimensional distortion ruptures space, transporting the player to the ancient Phantom Sect Vault.
- **Objective**: Discover the founder's stele in the secret shrine (`loc_secret_phantom_shrine`).
- **Reward**:
  - $15,000$ EXP.
  - $15$ **Primal Bloodstones**, $3$ **Ancient Bone Brands**.
  - $+5$ Astral Meridian Points.
  - Title: **Peerless Phantom**.

---

#### 3.2. Stele of the Celestial Sovereign (`quest_hidden_02_tan_bi_than_tuong`)
- **Secret Trigger**:
  - During a sandstorm in `zone_boundless_sandstorm`.
  - Meditate before the Nameless Monolith and offer $1$ [Feral Amber](file:///c:/Projects/FreeExile/wiki/en/CURRENCIES_AND_SPIRIT_STONES_SPECS.md#26-tạo-hóa-thạch).
- **Objective**: Decipher the glyphs carved upon the monolith (`action_decipher_ancient_stele`).
- **Reward**:
  - $20,000$ EXP.
  - $3$ **Wraithbone Spikes**, $20$ **Primal Bloodstones**.
  - $+6$ Meridian Points.
  - Title: **Sovereign's Disciple**.

---

#### 3.3. Five Elements Generative Order (`quest_hidden_03_ngu_hanh_tuong_sinh`)
- **Secret Trigger**:
  - Slay $5$ Elite monsters in exact **Generative Order** within 60 seconds:
    $$\text{Metal} \longrightarrow \text{Water} \longrightarrow \text{Wood} \longrightarrow \text{Fire} \longrightarrow \text{Earth}$$
- **Objective**: Harmonize the elemental matrix at the Five Dragons Altar (`loc_five_elements_altar`).
- **Reward**:
  - $30,000$ EXP.
  - $5$ **Ancient Bone Brands**, $5$ **Wraithbone Spikes**.
  - $+8$ Meridian Points.
  - Title: **Elemental Harmonizer**.

---

#### 3.4. Rebirth of the Buried Blade (`quest_hidden_04_u_hon_oan_kiem`)
- **Secret Trigger**:
  - Recover a rusted sword relic from Ghost Sword Thralls in Ancient Sword Mound.
  - Deliver it to the summit altar of Buried Sword Cliff (`zone_tang_kiem_nhai_altar`) during night hours.
- **Objective**: Cleanse the sword using $1$ [Crude Flint](file:///c:/Projects/FreeExile/wiki/en/CURRENCIES_AND_SPIRIT_STONES_SPECS.md#25-khai-linh-châu) (`action_cleanse_rusted_blade`).
- **Reward**:
  - $35,000$ EXP.
  - $25$ **Primal Bloodstones**, $4$ **Wraithbone Spikes**.
  - $+8$ Meridian Points.
  - Title: **Resurrected Soul of the Blade**.

---

## 4. HIGH-TIER ASTRAL QUESTS (EPIC ENDGAME TRIALS)

Tailored for high-level martial artists with fully developed equipment affixes and activated meridians.

### Detailed High-Tier Quest Registry

| Quest ID | Trial Title & Description | Req. Level | Prerequisite | Authoritative Objectives | Rewards & Relics |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `quest_epic_01_phong_ma_co_tran` | **Abyssal Demon Matrix Battle**<br/>Conquer floor 50 of the Demonic Seal Matrix and slay the Golden Fiend. | Lv 30 | `quest_norm_05` | 1. Slay [Abyssal Dragon King](file:///c:/Projects/FreeExile/wiki/en/MONSTERS_AND_BOSSES_SPECS.md#41-hắc-giao-long-vương)<br/>2. Craft a Rare tier gear piece | • 80,000 EXP<br/>• 40 Primal Bloodstones<br/>• 8 Ancient Bone Brands<br/>• 5 Wraithbone Spikes<br/>• +12 Meridian Points<br/>• Title: *Demon Seal Sovereign* |
| `quest_epic_02_nghich_menh_dai_huyet` | **Keystone Acupoint Breakthrough**<br/>Awaken the ultimate physical keystone altering meridian thermodynamics. | Lv 40 | `quest_epic_01` | Activate the [Unbreakable Body](file:///c:/Projects/FreeExile/wiki/en/CORE_LORE_AND_SYSTEMS.md#4-kỳ-kinh-bát-mạch-đồ) keystone (`meridian_keystone_unbreakable`) | • 150,000 EXP<br/>• 15 Ancient Bone Brands<br/>• 8 Wraithbone Spikes<br/>• +15 Meridian Points<br/>• Title: *Savage Exile Pioneer* |
| `quest_epic_03_luyen_che_thai_hu_kinh` | **Void Mirror Replication Trial**<br/>Harness supreme spiritual energy to mirror a 6-affix perfect relic. | Lv 50 | `quest_epic_02` | Mirror a rare artifact with [Savage Blood Mirror](file:///c:/Projects/FreeExile/wiki/en/CURRENCIES_AND_SPIRIT_STONES_SPECS.md#24-thái-hư-càn-khôn-kính) (`action_mirror_artifact_clone`) | • 300,000 EXP<br/>• 1 Savage Blood Mirror<br/>• 100 Primal Bloodstones<br/>• +20 Meridian Points<br/>• Title: *Lord of the Void* |
| `quest_epic_04_van_gioi_than_ma_tranh_ba` | **Sovereigns of the Cosmos Trial**<br/>Conquer floor 100 of the Void Rift and defeat the Primordial Flame Lord. | Lv 60 | `quest_epic_03` | Slay Primordial Boss: [Flame Demon Lord](file:///c:/Projects/FreeExile/wiki/en/MONSTERS_AND_BOSSES_SPECS.md#44-xích-diễm-hỏa-tỳ-hưu) (`boss_flame_demon_lord`) | • 500,000 EXP<br/>• 2 Savage Blood Mirrors<br/>• 30 Ancient Bone Brands<br/>• 20 Wraithbone Spikes<br/>• +30 Meridian Points<br/>• Title: *Boundless Archfiend* |

---

## 5. MILESTONE PROGRESSION & TIER REWARDS

```
[FREEEXILE MILESTONE REWARD LADDER]
┌────────────────────────────────────────────────────────────────────────┐
│ TIER I: EXILE REALM NOVICE      (5 Quests Completed)                   │
│ └──> Crude Flint x10, Feral Amber x5, +2 Meridian Points        │
├────────────────────────────────────────────────────────────────────────┤
│ TIER II: MERIDIAN GRANDMASTER   (7 Quests + 1 Cryptic Secret)          │
│ └──> Primal Bloodstone x15, Ancient Bone Brand x2, +5 Meridian Points       │
├────────────────────────────────────────────────────────────────────────┤
│ TIER III: TRUE MARTIAL RENOWN   (9 Quests + 2 Secrets + 1 High-Tier)   │
│ └──> Primal Bloodstone x30, Ancient Bone Brand x6, Wraithbone Spike x5       │
├────────────────────────────────────────────────────────────────────────┤
│ TIER IV: FATE DEFIER PIONEER    (11 Quests + 3 Secrets + 2 High-Tier)  │
│ └──> Primal Bloodstone x60, Ancient Bone Brand x15, Wraithbone Spike x10     │
│      +15 Meridian Points, Title: Savage Exile Pioneer                   │
├────────────────────────────────────────────────────────────────────────┤
│ TIER V: SOVEREIGN OF REALMS     (13 Quests + 4 Secrets + 4 High-Tier)  │
│ └──> ⭐ 2 VOID MIRROR RELICS, 150 Chaos Stones, 50 Ancient Bone Brands       │
│      +30 Meridian Points, Title: SOVEREIGN OF REALMS                   │
│      Unlocks Exclusive Royal Gold Loot Beam Shader                     │
└────────────────────────────────────────────────────────────────────────┘
```

### Detailed Milestone Tier Specifications

| Milestone Tier | Unlock Requirements | Barter Currency Rewards | Meridian Boost | Prestige Unlocks |
| :--- | :--- | :--- | :--- | :--- |
| **Tier I: Exile Realm Novice**<br/>`ms_tier_1_so_nhap_hoang_gioi` | Complete $\ge 5$ quests | • Crude Flint x10<br/>• Feral Amber x5 | $+2$ Meridian Points | • Title: *Exile Realm Novice*<br/>• +10% Movement Speed in Outposts |
| **Tier II: Meridian Grandmaster**<br/>`ms_tier_2_thong_suot_kinh_mach` | $\ge 7$ total quests<br/>$\ge 1$ Cryptic Secret | • Primal Bloodstone x15<br/>• Ancient Bone Brand x2 | $+5$ Meridian Points | • Title: *Meridian Grandmaster*<br/>• $+20$ Consignment Vault slots |
| **Tier III: True Martial Renown**<br/>`ms_tier_3_chan_vo_xuat_the` | $\ge 9$ total quests<br/>$\ge 2$ Cryptic Secrets<br/>$\ge 1$ High-Tier Quest | • Primal Bloodstone x30<br/>• Ancient Bone Brand x6<br/>• Wraithbone Spike x5 | $+8$ Meridian Points | • Title: *True Martial Renown*<br/>• $-50\%$ Trading Consignment fee |
| **Tier IV: Savage Exile Pioneer**<br/>`ms_tier_4_nghich_menh_chuyen_luan` | $\ge 11$ total quests<br/>$\ge 3$ Cryptic Secrets<br/>$\ge 2$ High-Tier Quests | • Primal Bloodstone x60<br/>• Ancient Bone Brand x15<br/>• Wraithbone Spike x10 | $+15$ Meridian Points | • Title: *Savage Exile Pioneer*<br/>• Unlocks 2nd Relic Trinket Slot |
| **Tier V: Sovereign of Realms**<br/>`ms_tier_5_van_gioi_chi_ton` | All $\ge 13$ quests<br/>$\ge 4$ Cryptic Secrets<br/>$\ge 4$ High-Tier Quests | • **2 Savage Blood Mirrors**<br/>• 150 Primal Bloodstones<br/>• 50 Ancient Bone Brands<br/>• 30 Wraithbone Spikes | $+30$ Meridian Points | • Title: **Sovereign of Realms**<br/>• Exclusive Royal Gold & Violet Loot Beam<br/>• Golden Statue in Boundless Plaza |

---

## 6. SERVER-AUTHORITATIVE ZERO-TRUST SECURITY

1. **Client Never Dictates Quest State**:
   - Clients only receive push notifications (`QuestProgressSyncNotice`). All objectives are incremented exclusively through the internal server engine loop (30Hz) verifying hits, kills, coordinates, and crafting events.
2. **Two-Phase Commit Claim Protection**:
   - Both `claim_quest_reward` and `claim_milestone_reward` are idempotent and atomic. Double claims are immediately rejected, logged as security anomalies, and prevented by transactional locks.