Files
metin2-server/docs/FEATURE-CHEST.md
T
shenleiandClaude Opus 5.5 4b4f32ed58 Add batch gift box opening (mt_chest)
AVA2 ENABLE_MULTI_CHEST port: /mt_chest 1 open CELL COUNT opens up to 200
gift boxes of one vnum across bag cells through the original UseItem path,
stops at 3 free cells, skips monster/debuff groups and reports the gains
as MTCH1 lines.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-15 23:24:11 +09:00

3.7 KiB

PORT batch chest opening, v1

Date: 2026-10-15. AVA2-style batch opening of gift boxes (reference: AVA2 ENABLE_MULTI_CHEST, /chest_drop, CHARACTER::OpenChest). Source: src/server/game/src/port_chest.h (header-only, included from cmd_general.cpp), command mt_chest (cmd.cpp). It reuses the quiet-INFO hook (m_portQuietInfo / m_portLastInfo) added for the switchbot. No packet header, no DB schema, no char.h/item.h change.

AVA2 rewrote the drop loop (GiveItemFromSpecialItemGroupNew, AutoGiveItemChest, cap 1000). That rewrite is not ported. Here every box goes through the original CHARACTER::UseItem → UseItemEx ITEM_GIFTBOX path, one box at a time, so the original checks, the special_item_group roll, gold/exp, ItemLog and consumption stay exactly as they are.

Rules

  • Only ITEM_GIFTBOX items whose special item group exists, is not empty and contains none of the give types MOB, SLOW, DRAIN_HP, POISON, MOB_GROUP. Boxes that spawn monsters or apply debuffs stay single-use (error kind). Other item types (e.g. ITEM_USE chests with quest scripts) are not batchable.
  • The chosen cell is opened first while it still holds the box vnum; after that, any other bag cell with the same vnum. Most gift boxes on 203 have no stack flag, so a batch normally spans many cells. Items being exchanged are skipped.
  • At most 200 boxes per command.
  • Before each box the character must still have 3 free bag cells (GetEmptyInventory(3)). This keeps room for any reward, so AutoGiveItem never has to drop one on the ground. The loop stops with reason full.
  • Busy: dead, stunned, warping, observer, !CanHandleItem, exchange, own shop, shop open, safebox, cube. Checked before the command and before each box.
  • A box counts as opened only when the bag count of its vnum went down by exactly one. Anything else (the original path refused it, e.g. the dragon soul qualification) stops the loop with reason rejected. The last INFO line of that refusal is forwarded once.
  • Per-box INFO lines are held back while the batch runs.
  • Throttle: one command per 500 ms per player id.

Protocol (CHAT_TYPE_COMMAND, version 1)

/mt_chest 1 open CELL COUNT          CELL = bag cell, COUNT = 1..200, digits only (at most 5)
MTCH1 got VNUM COUNT                 one line per gained vnum (box vnum excluded), at most 40 lines
MTCH1 done VNUM ASKED OPENED REASON GOLD
MTCH1 error rate|invalid|busy|item|kind|full
  • REASON: done (all asked boxes opened), empty (no box of this vnum left), full (fewer than 3 free cells), busy, rejected.
  • GOLD: gold balance change over the batch.
  • Gains are the difference between bag + dragon soul bag counts before and after the batch.
  • A request with a version other than 1, a token longer than 10 characters or more than 5 tokens is ignored silently.

There is no MTF1 capability bit (the mask stays 511). The client marks the server unsupported when no MTCH1 reply arrives within 3 s and falls back to normal single use.

Verification

  • tests/features/test_chest.py compiles the production header against stubs of the UseItem gift-box contract (consume one box, gold, stacking reward, dragon soul reward, INFO lines). It covers:
    • cross-cell order and the gains/gold summary with INFO held back;
    • a stack, fewer asked than held, more asked than held (empty);
    • the 3-free-cell stop (full, error full);
    • refusal by the original path (rejected, INFO forwarded once);
    • non-gift box, monster box, missing and empty group (kind);
    • missing/exchanging item, busy, invalid input, silently ignored version, throttle.
    • It also checks the cmd.cpp / cmd_general.cpp wiring.
  • All tests/features/test_*.py pass.