# Session Mode — Boss & Marker 參考手冊

本文件是 `session_markers.json` + `engine/session_mode.py` 的自然語言描述。
標記清單以 `session_markers.json` 為準，本文件負責解釋「這些標記在代碼中怎麼被使用」。

## 架構概覽

Session 生命週期由 3 個原語驅動（`SessionMode._do_entry` / `_do_save` / `_do_reset`），
5 個 handler class 各自定義 4 個回呼（`on_first_spawn` / `on_same_spawn` / `on_exit` / `finalize_stage`）：

| Handler | 模式 | 對應遊戲內容 |
|---|---|---|
| `_AdvVisionHandler` | `advvision` | 危險委託 |
| `_AbyssHandler` | `abyss` | 軌外之境 |
| `_WeeklyHandler` | `weekly` | 異象巡禮 |
| `_AnomalyHuntHandler` | `anomaly_hunt` | 異象追獵 |
| `_FreeHandler` | `free` | 預設閒置（所有回呼為 pass） |

### 共用機制

- 離場訊號：S2C `CurCloneSaveData` value = `"None"`（block size = 0x18，pattern: None / 0xFFFFFFFF / None）
- Retry 產品決策（S63）：程式保留 best-effort 的自動 retry 偵測，但不保證所有模式都能準確偵測。使用說明已加入提醒：重新挑戰任何關卡時，建議手動按 F6（重置）。

---

## 危險委託 / AdvVision

> 共 6 階級，階級從 `advvision_mob.json` 依 HP 比對判斷
> 12 boss，分為 mon（4 個）和 boss（8 個）兩類

### 生命週期

- 啟動 session — 首次偵測到 `AdvVision_*` spawn marker（嚴格比對 `session_markers.json` 白名單，不做 prefix regex）
- save + 新 session（clone_entry） — 活躍 session 期間偵測到 CurCloneSaveData 副本進場訊號
- save + 新 session（retry） — 同 marker 再次出現，且 `_is_retry_signal` 為 true，`spawn_count ≥ 2`（best-effort，見下方說明）
- save + 結束 session — 偵測到 `advvision_exit` 訊號（CurCloneSaveData = "None"）

### Retry 偵測機制（`_is_retry_signal`）

- boss 分類（hp_boss_keys 前綴 `Boss_` / `boss_`，8 個）：retry 封包的 `stage_byte` 有值，比對 `entry_val` 或 `entry_val + 1`
- mon 分類（hp_boss_keys 前綴 `mon_`，4 個）：retry 封包的 `stage_byte` 永遠 = 0，只比對 `stage_byte == 0`
- 因存在 off-by-one（首次 entry 經 `on_first_spawn` 設 `spawn_count=0`，第一次 retry 只推到 1，不達 ≥2 門檻），實際觸發需第二次 retry

### Boss 清單

來源：`session_markers.json` `advvision` 區段

| Boss | 委託名 (zh) | 委託名 (en) | Marker | 分類 | hp_boss_keys |
|---|---|---|---|---|---|
| 洄天魚幡 | 天棄之子 | Heaven's Forsaken | `AdvVision_RainLiyuuQi` | mon | `mon_025_double_*` |
| 血染妖刀 | 何處是歸鄉 | Where Is Home | `AdvVision_YaoDao` | mon | `mon_13_1` |
| 波普 | 超音速塗鴉 | Lightspeed Tagger | `AdvVision_TuyaGuai` | mon | `mon_012_2` |
| 瓦楞城堡 | 盛情難卻 | Kindness Hard to Refuse | `AdvVision_PaperCastle` | mon | `mon_48` |
| 音霸魔王 | 律動大師 | Rhythm Master | `AdvVision_BoomBox` | boss | `Boss_15` |
| 底片-MANISH | 品牌紀念日 | Brand Anniversary | `AdvVision_WorldFilm` | boss | `Boss_06` |
| 瑪門 | 毛線球還是方斯 | Yarn Ball or Fons? | `AdvVision_Mammon` | boss | `boss_17` |
| 賽潤尼緹 | 靜默庭園 | Silent Garden | `AdvVision_flowerBoss` | boss | `boss_07` |
| 黑之書 | 後青春期的書 | The Book of Post-Adolescence | `AdvVision_BlackBook` | boss | `boss_09` |
| 無首鐵馭 | 鐵馭強襲 | Ride Assault | `AdvVision_MotoBoss` | boss | `boss_13` |
| 斑蝶 | 去看電影吧 | Let's Go See a Movie | `AdvVision_Boss08` | boss | `Boss_08` |
| 囿巢鳥 | 喚孤歸 | Call of the Lost | `AdvVision_Boss33` | boss | `boss_33` |

---

## 異象巡禮 / Weekly

> 共 7 階（marker 含階級後綴 `_Lv1` ~ `_Lv7`）
> 2 boss

### 生命週期

- 啟動 session — 首次偵測到 `WeeklyClone_Boss*_Lv*` spawn marker
- save + 新 session（retry） — 同 marker 再次出現，直接 save_and_new（`on_same_spawn` 無條件觸發）
- save + 結束 session — 偵測到 `clone_exit` 訊號（CurCloneSaveData = "None"）

### Boss 清單

來源：`session_markers.json` `weekly` 區段

| Boss | 名稱 (en) | Marker 前綴 | 階級 |
|---|---|---|---|
| 墨菲克斯 | Morphix | `WeeklyClone_Boss05` | `_Lv1` ~ `_Lv7` |
| 永不謝幕的阿拉克涅 | The Never-ending Arachne | `WeeklyClone_Boss10` | `_Lv1` ~ `_Lv7` |

---

## 異象追獵 / Anomaly Hunt

> 無階級、無重新挑戰
> 大地圖戰鬥，有 loading 的才有進退場標記

### 生命週期

- 啟動 session — 偵測到 `WorldBoss_*_Entrance` 或 `Boss0*_IntoBattle` 進場標記
- retry — 無（`on_same_spawn` 為 pass）
- save + 結束 session — 偵測到 `world_boss_exit` 訊號（`WorldBoss_*_Exit`）

### Boss 清單

來源：`session_markers.json` `anomaly_hunt` 區段

| Boss | 名稱 (en) | 進場標記 | 退場標記 | 備註 |
|---|---|---|---|---|
| 無首鐵馭 | Headless Rider | `WorldBoss_Boss13` | `WorldBoss_13_Exit` | |
| 黑之書 | Black Tome | `WorldBoss_09_Entrance` | `WorldBoss_09_Exit` | |
| 海囚 | Sea Prisoner | `Boss019_IntoBattle` | `WorldBoss_19_Exit` | 進場標記格式不同 |
| 囿巢鳥 | Nestbound Bird | `WorldBoss_33_Entrance` | `WorldBoss_33_Exit` | |
| 斑蝶 | Swallowtail | `WorldBoss_08_Entrance` | `WorldBoss_08_Exit` | |
| 音霸魔王 | Beat King | — | — | 大地圖直接戰鬥，無 loading，暫不支援 |
| 賽潤尼緹 | Serenetti | — | — | 大地圖直接戰鬥，無 loading，暫不支援 |

---

## 軌外之境 / Abyss

> 2 路線 × 10 站，每站有上半場（half=0）或上+下半場（half=0,1）
> marker 格式：`Abyss_{route}_{station}_{half}`
> spawn 封包的第 2 byte 為波次編號（LE uint32，02=第一波，03=第二波）

### 生命週期

- 啟動 session — 首次偵測到任何 `Abyss_*` spawn marker
- save + 新 session（wave reset） — 同 marker 再次出現且 `wave_index == 2`（第一波重新開始）
- save + 新 session（站別變更） — 偵測到不同的 `Abyss_{route}_{station}_{half}` marker
- save + 結束 session — 偵測到 `abyss_leave` 訊號（`Abyss_Station_LeaveClone`）

### Handler 額外狀態

`route` / `station` / `half` 寫入戰報 meta

### 路線清單

來源：`session_markers.json` `abyss` 區段，共 40 條

#### 節理環線 / Fracture Circle（route = Common）
- 站 1~5：僅上半場（half=0）
- 站 6~10：上半場 + 下半場（half=0, 1）
- Marker 格式：`Abyss_Common_{station}_{half}`

#### 本初環線 / Prime Circle（route = 1）
- 站 1~10：上半場 + 下半場（half=0, 1）
- Marker 格式：`Abyss_1_{station}_{half}`

---

## 通行正義

- 待探索（第 5 種 session 模式，尚無封包資料）
