Files
metin2-server/docs/FEATURE-BATTLEPASS.md
T
shenleiandClaude Opus 5.5 cd395c73b7 Battle pass: add 2027 seasons (202701-202712)
Same 8 missions and final reward as 202612, monthly Berlin starts through 2028-01-01.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 09:39:52 +09:00

112 lines
5.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# PORT battle pass
A monthly mission pass, ported from AVA2's `ENABLE_BATTLE_PASS` (the window behind `uibattlepassex.py`). A season is a time window with up to ten missions. Each mission has its own reward, and a final reward unlocks once every mission is done. The pass is free for every player; AVA2 sold a ticket item (25150–25161), and this port has none.
Source:
- `src/server/game/src/port_battlepass.h`: config, per-player state and bag fit; standard C++ only.
- `port_battlepass_runtime.h`: game side, included only by cmd_general.cpp.
- `port_battlepass_hooks.h`: hook declarations for the other files.
Tables: `tools/battlepass/schema.sql`. Season file: `tools/battlepass/port_battlepass.tsv`. Test: `tests/features/test_battlepass.py`.
## Season file
The file is `<locale base>/port_battlepass.tsv`, for example `share/locale/newcibn/port_battlepass.tsv`. Every core checks it at most once every 5 s and reloads it when its mtime, size or inode changes, the same rule the event calendar uses. Replace it atomically with a temporary file and `mv`.
```
MTBATTLEPASS 1
season ID START END unix seconds, [START, END)
mission SLOT TYPE SUB TARGET [VNUM COUNT]x0..3
final VNUM COUNT [VNUM COUNT]x0..5
```
- Any error disables the whole file; the game logs `PORT_BP: port_battlepass.tsv disabled: line N: why`. Errors include:
- a bad number or a duplicate slot;
- overlapping seasons;
- a season without missions;
- a sub on a type that takes none.
- Slot numbers are 1..10. A season ID must never be reused: progress and claims are stored per season ID.
- A reward must be a bag item:
- not a dragon soul stone;
- size 1..3;
- at most 24 stacks per claim.
A bad reward is caught when someone claims it: the answer is `config`, `sys_err` logs it, and the slot stays claimable after the file is fixed.
| Type | Counts | SUB |
|---|---|---|
| 1 | monster kills (not boss, not stone) | mob vnum or 0 |
| 2 | boss kills (rank ≥ boss) | mob vnum or 0 |
| 3 | metin stone kills | stone vnum or 0 |
| 4 | seconds online | 0 |
| 5 | fish caught | item vnum or 0 |
| 6 | successful refines | resulting item vnum or 0 |
| 7 | levels gained | 0 |
| 8 | gold paid to NPC shops | 0 |
| 9 | items sold to NPC shops | item vnum (required) |
A kill counts for the player that `CHARACTER::Reward` gives the quest kill event to, which is the `DistributeExp` attacker. As in AVA2, it counts only when the monster is within 20 levels of the player. A party member who is not that attacker gets nothing. Type 9 needs a vnum because selling any item could be farmed with cheap shop items.
The shipped file has seasons 202610–202712 (through 2028-01-01), starting at local midnight on the first of each month (Europe/Berlin, the server's zone). Each has:
- eight missions, rewards taken from 40250 items;
- a final reward of the three pearls and 70024.
The targets follow the scale of AVA2's month 10 (`player.battle_pass`).
## Storage
```
player.mt_battlepass_progress (pid, season, slot, value, target) PRIMARY KEY (pid, season, slot)
player.mt_battlepass_claim (pid, season, slot, claimed_at) PRIMARY KEY (pid, season, slot); slot 0 = final
```
**Counting.** Events are counted in memory, as the delta per slot. `CHARACTER::SaveReal`, which covers the periodic save, logout and warp, adds play time, then queues one upsert on the game's ordered SQL connection:
`value = LEAST(value + delta, target)`
Because the write adds, a core does not need to have read the row first. Two cores that both see the player during a warp add their own deltas, with no overwrite.
**Loading.** At the first event or `/mt_bp`, a `FuncQuery` reads the stored values and claims. Flushes queued after that read are added on top. A generation number drops the answers of a session that has already ended.
**Season change.** The counts of the old season are written while that season is still in the file. The new season then loads its own rows.
**Claims.** A claim checks four things before writing anything:
1. the state is loaded;
2. the mission is complete;
3. the slot is not claimed yet;
4. all the stacks fit in the bag. The fit is first-fit in `GetEmptyInventory` order, and a size-2 or size-3 item stays inside one 45-cell page.
Only then does it run `INSERT IGNORE` into the claim table synchronously. Only the request whose insert affected a row creates the items, into the cells checked before. A double click, a retry or another core finds the row already there and gets `claimed`. Each item gets an `MT_BP_CLAIM` item log with the hint `SEASON SLOT`, and the character is saved right away.
Known limits:
- If the core crashes between the claim row and the item save, that reward is lost. The claim row and the item log are there for a GM to compensate.
- While a warp is in flight, the window can show slightly less progress than is stored. Nothing is lost or counted twice.
## Protocol
```
/mt_bp 1 info | 1 claim SLOT | 1 close
MTBP1 season ID START END NOW COUNT
MTBP1 mission SLOT TYPE SUB TARGET VALUE CLAIMED [VNUM COUNT]...
MTBP1 final CLAIMED ALLDONE [VNUM COUNT]...
MTBP1 end
MTBP1 none no season running (or no valid file)
MTBP1 progress SLOT VALUE pushed while the window is open
MTBP1 done SLOT a mission was finished (always sent)
MTBP1 claimed SLOT the reward is in the bag; a full info follows
MTBP1 error loading|slot|claimed|incomplete|space|config|db|rate|invalid
```
- `info` before the load is answered as soon as the load arrives.
- A `done` for a mission that an event finished before the load is sent when the load arrives.
- `info` and `claim` share a 300 ms gap per player (`rate`).
- A wrong version, more than three tokens, or a token longer than 10 characters gets no answer.
## Setup
1. Apply `tools/battlepass/schema.sql` once.
2. Copy `port_battlepass.tsv` to the locale base directory.
3. Restart the cores with the new binary.
Without the file, every `/mt_bp` answers `none` and nothing is counted or written.