docs(tournament): add hunting tournament setup and operations guide

houmgaor
2026-03-22 14:40:49 +01:00
parent 90bc36ad75
commit be800d12c2

@@ -57,6 +57,56 @@ Decrypted quest data is cached in memory. The cache expires after `QuestCacheExp
If `ClientMode` is set to Z1 or earlier, quest data is automatically backported for compatibility with older clients.
## Hunting Tournament
The hunting tournament system (`公式狩猟大会`) hosts periodic competitive events where players submit timed hunts and fishing runs. The tournament lobby, cup listings, leaderboards, registration, and run submission are all server-driven.
### Lifecycle phases
Each tournament row has four Unix timestamps that drive the phase shown to the client:
| Phase | State byte | Description |
|-------|:---:|-------------|
| Before start | 0 | No active tournament shown |
| Registration open | 1 | Players can register (`EntryTournament`) |
| Hunting active | 2 | Players can enter and submit runs |
| Ranking / reward | 3 | Results visible; rewards claimable |
### Database tables
| Table | Purpose |
|-------|---------|
| `tournaments` | One row per tournament instance (schedule) |
| `tournament_cups` | Competition categories (speed hunt, fishing, etc.) linked to a tournament |
| `tournament_sub_events` | Specific hunt/fish targets grouped by `cup_group` |
| `tournament_entries` | Player registrations |
| `tournament_results` | Submitted run records (submission order = rank proxy) |
### Seed data
`TournamentDefaults.sql` seeds cup and sub-event data from live tournament #150 (Brachydios time-attack + fishing cups). A demo tournament starting immediately is also inserted so the lobby is populated on a fresh install.
### Scheduling a tournament
Update the demo row or insert a new one:
```sql
-- Update the existing demo tournament
UPDATE tournaments SET
name = '第151回公式狩猟大会',
start_time = EXTRACT(epoch FROM '2026-04-01 14:00:00+09'::timestamptz)::bigint,
entry_end = EXTRACT(epoch FROM '2026-04-04 14:00:00+09'::timestamptz)::bigint,
ranking_end = EXTRACT(epoch FROM '2026-04-13 14:00:00+09'::timestamptz)::bigint,
reward_end = EXTRACT(epoch FROM '2026-04-20 14:00:00+09'::timestamptz)::bigint
WHERE id = 1;
```
To add new cup types or hunt targets, insert rows into `tournament_cups` (with the correct `tournament_id`) and `tournament_sub_events` (linked by `cup_group`).
### Known limitation
The `Unk2` field in `MsgMhfEnterTournamentQuest` is stored as `event_id` in `tournament_results`. Its exact semantics are unconfirmed — if leaderboards appear empty in-game, this is the likely cause. See [#184](https://github.com/Mezeporta/Erupe/issues/184).
## Save Data
### Character Saves