# Conquest War (討伐征戦 / Seibatsu)

Tracks what is known about the Conquest War event system and what remains to be
reverse-engineered before it can be fully implemented in Erupe.

The `feature/conquest` branch (origin) attempted a partial implementation but drifted too far
from `develop` without completing the core gameplay loop and is not mergeable in its current
state. Its findings are incorporated below.

---

## Game Context

**Conquest War** (討伐征戦, also called *Seibatsu*) is a weekly rotating time-limited event
introduced in the G2 update (July 2013). Players hunt legendary monsters and race to level them
up on a per-player leaderboard.

The event follows a **three-week, three-phase cycle** tracked server-side as the "Earth" system:

| Week | Phase | Japanese | Description |
|------|-------|----------|-------------|
| 1 | **Conquest (Seibatsu)** | 討伐征戦 | Hunting phase — players level their monsters |
| 2 | **Pallone Festival** | パローネ祭典 | Side festival event concurrent with conquest rewards |
| 3 | **Tower (Dure)** | 塔 | Tower climbing event for additional rewards |

### Conquest Mechanics

- Each player has their own independent monster (not shared with others).
- Players hunt their own monster or join quests at the same or higher level.
- A monster starts at level 1 and caps at **9999**.
- Level gain per hunt: **+5** (no faints), **+3** (one faint), **+1** (multiple faints).
- As the monster levels, its stats scale up, making each subsequent hunt harder.
- At week end, rewards are distributed based on the player's rank on the per-monster
  leaderboard.

### Target Monsters (configurable)

The live service used **Shantien**, **Disufiroa**, **G-Rank Black Fatalis**, and
**G-Rank Crimson Fatalis**. The branch defaults to monster IDs `[116, 107, 2, 36]`
(Deviljho, Rajang, Rathalos, Gore Magala — suitable for G8 and below, where the original
four are not available).

For clients at `RealClientMode <= G8`, only the first 3 monsters are exposed; G9+ exposes 4.

### Reward Distribution Types

The `DistributionType` field in reward packets uses these sentinel values:

| Value | Meaning |
|-------|---------|
| `7201` | Item reward (ItemID + quantity) |
| `7202` | N-Points (currency) |
| `7203` | Guild contribution points |

---

## Packet Overview

Thirteen packets implement the Conquest/Earth system. All live in `network/mhfpacket/`.
None have `Build()` implemented (all return `NOT IMPLEMENTED`) — responses are built
directly in handler code using `byteframe`.

### `MsgMhfGetEarthStatus` — Client → Server → Client

Fetches the current Earth event windows and which monsters are active.

**Request** (`msg_mhf_get_earth_status.go`):
```
AckHandle uint32
Unk0      uint32   — unknown; never used by handler
Unk1      uint32   — unknown; never used by handler
```

**Response** (built in `handlers_earth.go → handleMsgMhfGetEarthStatus`):
```
for each active earth event (up to 3: Conquest, Pallone, Tower):
  [uint32] StartTime       — Unix timestamp
  [uint32] EndTime         — Unix timestamp
  [int32]  StatusID        — 1 or 2 (Conquest); 11 (Pallone active) or 12 (Pallone reward); 21 (Tower)
  [int32]  EarthID         — unique event ID from DB row
  [int32]  MonsterID × N   — active conquest monsters (3 for G8, 4 for G9+)
```

**Status ID semantics**: the difference between `1` and `2` for the Conquest phase is not
known. The branch selects `1` when the hunt week is active and `2` otherwise, but this is
a guess.

**Current state**: Implemented. Event windows are generated from a single `events` table row
(`event_type = 'earth'`). A 21-day rolling cycle is computed from that row's `start_time`.
Debug mode (`EarthDebug = true`) collapses the windows to week boundaries for faster testing.

---

### `MsgMhfGetEarthValue` — Client → Server → Client

Fetches numeric values associated with the current Earth event (kill counts, floor tallies,
special flags).

**Request** (`msg_mhf_get_earth_value.go`):
```
AckHandle uint32
Unk0      uint32   — unknown
Unk1      uint32   — unknown
ReqType   uint32   — 1, 2, or 3 (see below)
Unk3–Unk6 uint32   — unknown; never used by handler
```

**Response**: a variable-length array of 6-uint32 entries, wrapped in `doAckEarthSucceed`.
Each entry: `[ID, Value, Unk, Unk, Unk, Unk]`. The last four fields are always zero in
known captures.

| ReqType | Known entries | Notes |
|---------|--------------|-------|
| 1 | `{1, 100}`, `{2, 100}` | Block + DureSlays count — exact meaning unclear |
| 2 | `{1, 5771}`, `{2, 1847}` | Block + Floors? — "Floors?" is a guess |
| 3 | `{1001, 36}` getTouhaHistory; `{9001, 3}` getKohouhinDropStopFlag; `{9002, 10, 300}` getKohouhinForceValue | `ttcSetDisableFlag` relationship unknown |

**Current state**: Implemented with hardcoded values. No database persistence.

---

### `MsgMhfReadBeatLevel` — Client → Server → Client

Reads the player's current conquest beat levels (monster progress values) from the server.

**Request** (`msg_mhf_read_beat_level.go`):
```
AckHandle    uint32
Unk0         uint32   — always 1 in the JP client (hardcoded literal)
ValidIDCount uint32   — always 4 in the JP client
IDs          [16]uint32 — always [0x74, 0x6B, 0x02, 0x24, 0, 0, ...] (hardcoded)
```

**Response**: `ValidIDCount` entries of `[ID uint32, Value uint32, 0 uint32, 0 uint32]`.
Default value if no DB data: `{0,1, 0,1, 0,1, 0,1}` (level 1 for each slot).

**Current state**: Fully implemented. Beat levels are read from `characters.conquest_data`
(16-byte BYTEA). Defaults to level 1 if the column is NULL.

---

### `MsgMhfUpdateBeatLevel` — Client → Server → Client

Saves the player's updated conquest beat levels after a quest.

**Request** (`msg_mhf_update_beat_level.go`):
```
AckHandle uint32
Unk1      uint32     — unknown
Unk2      uint32     — unknown
Data1     [16]int32  — unknown purpose; entirely discarded by the handler
Data2     [16]int32  — beat level data; only first 4 values are stored
```

**Response**: `{0x00, 0x00, 0x00, 0x00}`.

**Current state**: Implemented, but incomplete. Only `Data2[0..3]` is written to the DB.
`Data1` and `Data2[4..15]` are silently ignored. `Unk1`/`Unk2` purposes are unknown.

---

### `MsgMhfReadBeatLevelAllRanking` — Client → Server → Client

Fetches the global leaderboard for a given monster.

**Request** (`msg_mhf_read_beat_level_all_ranking.go`):
```
AckHandle uint32
Unk0      uint32
MonsterID int32   — which monster's ranking to fetch
Unk2      int32   — unknown
```

**Response structure** (from known captures):
```
[uint32] Unk
[int32]  Unk
[int32]  Unk
for each of 100 entries:
  [uint32] Rank
  [uint32] Level
  [32 bytes] HunterName (null-padded)
```

**Current state**: Stubbed. Returns 100 zero-filled entries. No database ranking data exists.

---

### `MsgMhfReadBeatLevelMyRanking` — Client → Server → Client

Fetches the player's own rank on the conquest leaderboard.

**Request** (`msg_mhf_read_beat_level_my_ranking.go`):
```
AckHandle uint32
Unk0      uint32
Unk1      uint32
Unk2      [16]int32  — unknown; possibly the same ID array as ReadBeatLevel
```

**Current state**: Stubbed. Returns an empty buffer. Response format unknown.

---

### `MsgMhfReadLastWeekBeatRanking` — Client → Server → Client

Purpose is partially understood: the handler comment says "controls the monster headings for
the other menus". Likely provides context for which monster's data to display.

**Request** (`msg_mhf_read_last_week_beat_ranking.go`):
```
AckHandle    uint32
Unk0         uint32
EarthMonster int32
```

**Response** (current stub): `[EarthMonster uint32, 0, 0, 0]`. Actual format unknown.

**Current state**: Minimal stub. Response structure not reverse-engineered.

---

### `MsgMhfGetBreakSeibatuLevelReward` — Client → Server → Client

Returns per-monster level-break milestone rewards (items granted at specific level thresholds).

**Request** (`msg_mhf_get_break_seibatu_level_reward.go`):
```
AckHandle    uint32
Unk0         uint32   — unknown; debug-printed but never used
EarthMonster int32
```

**Response**: variable-length array of reward entries via `doAckEarthSucceed`:
```
[int32] ItemID
[int32] Quantity
[int32] Level    — the level threshold at which this reward unlocks
[int32] Unk      — always 0 in known data
```

**Current state**: Implemented with hardcoded per-monster reward tables. Item IDs were
derived from packet captures. No database backend.

---

### `MsgMhfGetWeeklySeibatuRankingReward` — Client → Server → Client

Returns reward tables for conquest ranking, Pallone Festival routes, and Tower floors.
The most complex handler in the branch.

**Request** (`msg_mhf_get_weekly_seibatu_ranking_reward.go`):
```
AckHandle    uint32
Unk0         uint32   — unknown; debug-printed but never used
Operation    uint32   — 1 = conquest ranking, 3 = Pallone festival, 5 = event rewards
ID           uint32   — event/route ID (for Op=1: aligns with EarthStatus 1 and 2)
EarthMonster uint32
```

**Response format for Operation = 1** (conquest ranking rewards):
```
per entry:
  [int32]  Unk0
  [int32]  ItemID
  [uint32] Amount
  [int32]  PlaceFrom
  [int32]  PlaceTo
```

**Response format for Operations 3 and 5** (Pallone/Tower):
```
per entry:
  [int32]  Index0   — floor number (Op=5) or place rank (Op=3)
  [int32]  Index1
  [uint32] Index2   — distribution slot (Op=5 tower dure: 1 or 2)
  [int32]  DistributionType   — 7201/7202/7203
  [int32]  ItemID
  [int32]  Amount
```

**Current state**: Implemented with hardcoded tables derived from packet captures.
- Operation 1: All four monsters return the same bracket table (ranks 1–100, 101–1000,
  1000–1001). The tables are identical for all monsters — this may be correct, or captures
  were only recorded for one monster.
- Operation 3 (Pallone): 91 entries across 11 routes, all zero-filled — format is known
  but content is not.
- Operation 5 (Tower): Tower dure kill rewards (260001) and 155-entry floor reward table
  (260003, floors 1–1500) are hardcoded from captures.

Note in source: "Can only have 10 in each dist" — the maximum entries per distribution slot
before the client discards them is 10.

---

### `MsgMhfGetFixedSeibatuRankingTable` — Client → Server → Client

Returns a static "fixed" leaderboard (likely a seeded/display ranking, not live player data).
The handler notes this packet is *not* triggered when `EarthStatus == 1`, suggesting it
belongs to the reward-week display rather than the hunt-week display.

**Request** (`msg_mhf_get_fixed_seibatu_ranking_table.go`):
```
AckHandle    uint32
Unk0         uint32   — unknown
Unk1         int32    — unknown
EarthMonster int32
Unk3         int32    — unknown
Unk4         int32    — unknown
```

**Response**: up to 9 entries:
```
[int32]   Rank
[int32]   Level
[32 bytes] HunterName (null-padded)
```

**Current state**: Implemented with 9 hardcoded "Hunter N" placeholder entries per monster.
`Unk1`, `Unk3`, `Unk4` purposes unknown.

---

### `MsgMhfGetSeibattle` — Client → Server → Client

Fetches Seibattle (guild-vs-guild battle) data. The `GuildID` field suggests this is
guild-specific, but the handler ignores it entirely.

**Request** (`msg_mhf_get_seibattle.go`):
```
AckHandle uint32
Unk0      uint8
Type      uint8    — 1=timetable, 3=key score, 4=career, 5=opponent, 6=convention result,
                     7=char score, 8=cur result
GuildID   uint32
Unk3      uint8    — unknown
Unk4      uint16   — unknown
```

**Response**: varies by `Type`. Timetable (Type=1) returns 3 eight-hour battle windows
computed from midnight. All other types return zero-filled structs.

**Current state**: Stubbed. No database queries, no guild-specific data. The seibattle
guild-vs-guild combat system is entirely unimplemented.

---

### `MsgMhfPostSeibattle` — Client → Server → Client

Submits a seibattle result. All fields are unknown.

**Request** (`msg_mhf_post_seibattle.go`):
```
AckHandle uint32
Unk0      uint8
Unk1      uint8
Unk2      uint32
Unk3      uint8
Unk4      uint16
Unk5      uint16
Unk6      uint8
```

**Current state**: Stubbed. Returns `{0,0,0,0}`. No data is read or persisted.

---

### `MsgMhfGetAdditionalBeatReward` — Client → Server → Client

Purpose unclear. The handler comment states: *"Actual responses in packet captures are all
just giant batches of null bytes. I'm assuming this is because it used to be tied to an
actual event that no longer triggers in the client."*

**Request** (`msg_mhf_get_additional_beat_reward.go`):
```
AckHandle uint32
Unk0–Unk3 uint32   — all unknown
```

**Current state**: Returns 260 (`0x104`) zero bytes. Whether real responses were ever
non-zero is unknown.

---

## Database Schema

The branch adds two migrations:

```sql
-- schemas/patch-schema/23-earth.sql
ALTER TYPE event_type ADD VALUE 'earth';

-- schemas/patch-schema/24-conquest.sql
ALTER TABLE public.characters ADD COLUMN IF NOT EXISTS conquest_data BYTEA;
```

And seeds four conquest quests (`schemas/bundled-schema/ConquestQuests.sql`):
quest IDs `54257`, `54258`, `54277`, `54370` — all `quest_type = 33`, `max_players = 0`.

**Missing tables** required for a full implementation:

| Table | Purpose |
|-------|---------|
| `conquest_rankings` | Per-player, per-monster beat level leaderboard |
| `conquest_reward_claims` | Track which level-break and ranking rewards have been claimed |
| `seibattle_scores` | Guild seibattle results and career records |
| `seibattle_schedules` | Persistent timetable (currently computed in memory) |

---

## Configuration

Two keys were added to `config.go` / `config.json` by the branch:

| Key | Type | Default | Purpose |
|-----|------|---------|---------|
| `EarthDebug` | bool | `false` | Collapses event windows to week boundaries for testing |
| `EarthMonsters` | []int32 | `[116, 107, 2, 36]` | Active conquest target monster IDs |

---

## What Is Already Understood

- The three-phase Earth event cycle (Conquest → Pallone → Tower) and its 21-day rolling
  window, keyed to a single `events` row.
- `GetEarthStatus` response wire format: per-phase `[Start, End, StatusID, EarthID, MonsterIDs…]`.
- `ReadBeatLevel` request is fully hardcoded by the JP client (IDs `0x74, 0x6B, 0x02, 0x24`);
  no dynamic ID resolution is needed.
- Per-character beat level storage: 4 × int32, 16 bytes, in `characters.conquest_data`.
- Level-break reward item IDs and quantities for monsters 116, 107, 2, 36 (from captures).
- Weekly ranking reward brackets for conquest (ranks 1–100, 101–1000, 1000–1001).
- Tower floor reward table (floors 1–1500, item IDs and quantities from captures).
- Tower dure kill reward distributions (dist 1 and 2, from captures).
- `GetWeeklySeibatuRankingReward` response wire format for all three operations.
- `GetFixedSeibatuRankingTable` response wire format (rank + level + 32-byte name).
- `GetBreakSeibatuLevelReward` response wire format (ItemID + Quantity + Level + Unk).
- Distribution type sentinels: `7201` = item, `7202` = N-Points, `7203` = guild contribution.
- The 10-entry-per-distribution-slot limit in weekly seibatu ranking rewards.
- `GetSeibattle` timetable format: 3 × 8-hour windows from midnight.
- Conquest quest IDs: `54257`, `54258`, `54277`, `54370` (type 33).

---

## What Needs RE Before Full Implementation

### High Priority — blocks any functional gameplay

| Unknown | Where to look | Notes |
|---------|---------------|-------|
| Semantics of `EarthStatus` IDs 1 vs 2 | Packet captures during hunt week vs reward week | Currently guessed; wrong selection may break phase detection |
| `MsgMhfUpdateBeatLevel.Data1[16]` | Captures with known quest outcome | Second int32 array entirely discarded; may carry the level gain delta |
| `MsgMhfUpdateBeatLevel.Unk1 / Unk2` | Same captures | May carry monster ID or quest ID needed for routing |
| `ReadBeatLevelAllRanking` response structure | Captures from an active leaderboard | Header fields (3 × uint32 before the 100 entries) unknown |
| `ReadBeatLevelMyRanking` response structure | Same | Format entirely unknown; returns empty today |
| `ReadLastWeekBeatRanking` full response | Captures after week rollover | Only monster ID echoed back today |

### Medium Priority — required for accurate reward flow

| Unknown | Where to look | Notes |
|---------|---------------|-------|
| `MsgMhfPostSeibattle` all fields (`Unk0–Unk6`) | Captures after a seibattle result | Handler does nothing today; this is the score submission path |
| `GetSeibattle` types 3–8 response formats | Captures for each `Type` value | Currently all return zero structs |
| `GetSeibattle.Unk0 / Unk3 / Unk4` | Same captures | Likely context selectors for guild/season |
| `GetEarthValue.Unk0 / Unk1 / Unk3–Unk6` | Captures across different event phases | 6 of the 8 request fields are unknown |
| `GetEarthStatus.Unk0 / Unk1` | Captures across phases | Never used by the handler; may be version or session flags |
| `GetWeeklySeibatuRankingReward` Op=3 content | Captures during Pallone Festival | 91 entries are zero-filled placeholders |
| Claim tracking semantics | Compare reward endpoint with gacha claim flow | No "claimed" flag exists anywhere in the schema |

### Low Priority — cosmetic / completeness

| Unknown | Where to look | Notes |
|---------|---------------|-------|
| `GetFixedSeibatuRankingTable.Unk1 / Unk3 / Unk4` | Captures | Likely unused alignment or version fields |
| `GetBreakSeibatuLevelReward.Unk0` | Captures with different monsters | Debug-printed; may be season or event ID |
| `ReadBeatLevelAllRanking.Unk0 / Unk2` | Captures | Likely pagination or season selectors |
| `GetAdditionalBeatReward` full structure | Captures if the packet is ever non-null | May be permanently dead in the last client version |
| Pallone Festival route semantics | JP wiki / community guides | 11 routes × 13 entries, all content unknown |
| Original live-service event scheduling cadence | JP wiki archives | Cycle length and reset time not publicly documented |

---

## Relation to Other Systems

**Gacha service** (`svc_gacha.go`): The reward distribution model (distribution type,
item ID, amount, rank brackets) is structurally similar to the gacha reward pipeline.
Conquest reward claiming can likely reuse or adapt `GachaService.ClaimRewards` and its
point transaction infrastructure.

**Raviente siege** (`sys_channel_server.go`, `handlers_register.go`): Conquest quests may
use the same `MsgMhfRegisterEvent` / semaphore pattern for quest slot management, though
this has not been confirmed with captures.

**Tower event** (`feature/tower` branch): The Tower phase is part of the same Earth event
cycle. The `GetWeeklySeibatuRankingReward` handler already covers Tower rewards (Op=5).
The two branches should be coordinated or merged.

---

## Known Code Quality Issues in the Branch

The following must be fixed before any part of this branch is merged:

- `fmt.Printf` debug prints left in packet `Parse()` methods:
  `msg_mhf_get_break_seibatu_level_reward.go`, `msg_mhf_get_weekly_seibatu_ranking_reward.go`,
  `msg_mhf_get_fixed_seibatu_ranking_table.go`, `msg_mhf_read_last_week_beat_ranking.go`
- The `cleanupEarthStatus` function wipes `conquest_data` for all characters on event
  expiry — this erases history. Completed conquest data should be archived, not deleted.
- The branch introduced a large `handlers.go` consolidation file that deleted existing test
  files (`handlers_achievement_test.go`, `channel_isolation_test.go`, etc.). These must be
  restored.
- DB access in `handlers_earth.go` uses raw `s.server.db` calls instead of the repo pattern.
  Any merge must route these through `CharacterRepo` and `EventRepo` interfaces.
- `EarthMonsters` config currently accepts any IDs; a G9+ client will crash if fewer than 4
  monsters are configured when `RealClientMode > G8`.