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>
112 lines
5.9 KiB
Markdown
112 lines
5.9 KiB
Markdown
# 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.
|