# 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 `/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.