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

5.9 KiB
Raw Blame History

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.