Files
metin2-server/docs/FEATURE-QUERY-PROTOCOL.md
T
shenleiandClaude Opus 5.5 a28393b16b Port the AVA2 switchbot (自动洗练) 1:1
AVA2 new_switchbot ported as port_switchbot.{h,cpp}: SWITCHBOT item window (7),
CG/GC 171 and GG 31 with AVA2 subheaders and field order, pack(1) structs pinned
by static_assert, 0.1 s roll, P2P hand-over on warp, boot ALTER of
player.item.window. Switchers come from the inventory; current checks and
ItemLog are kept. Clients sending "mt20261016" or newer as the version
timestamp get the switchbot; older clients are left alone.

The v1 /mt_switchbot chat command, its lock verb and query capability bit 64
are removed (cap mask 1023 -> 959).

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

7.0 KiB

PORT read-only query protocol v1

Date: 2026-10-15. Implementation: src/server/game/src/port_features.h, port_wiki_queries.inc. Client: metin2-client FeatureServiceScript.inc. This is a narrow transport adaptation of AVA2 encyclopedia/drop/chest/details features, not a copy of AVA2 packet numbers or item layout.

Request through existing CG chat command:

/mt_features 1 REQUEST cap
/mt_features 1 REQUEST mob MOB_VNUM OFFSET
/mt_features 1 REQUEST chest ITEM_VNUM OFFSET
/mt_features 1 REQUEST sources ITEM_VNUM OFFSET
/mt_features 1 REQUEST stats
/mt_features 1 REQUEST dungeons
/mt_features 1 REQUEST calendar 1 OFFSET
/mt_features 1 REQUEST bosses

REQUEST: 1..2147483647, independent for each game session's pending command. Subject: unsigned 32-bit nonzero ID. OFFSET: 0..4096. Other versions, excess arguments, oversized tokens, signed/overflow identifiers are rejected. Queries require an own PC descriptor. Per-character throttle: 250 ms. No gameplay mutation, consumption, random draws or database write.

Replies use existing CHAT_TYPE_COMMAND; no binary struct is serialized:

MTF1 cap REQUEST 1 MASK SERVER_TIME
MTF1 begin REQUEST KIND SUBJECT OFFSET TOTAL MODE SERVER_TIME
MTF1 row REQUEST INDEX ITEM COUNT RULE MIN MAX WEIGHT GROUP_TOTAL RARE
MTF1 stat REQUEST INDEX KEY SIGNED_VALUE
MTF1 event REQUEST INDEX EVENT_ID KIND START END CHANNEL EMPIRE ACTIVE
MTF1 boss REQUEST INDEX VNUM MAP X Y CHANNEL ALIVE MAX NEXT PERIOD
MTF1 end REQUEST ROW_COUNT
MTF1 error REQUEST ERROR

MASK: 1 mob drops, 2 chest preview, 4 own stats, 8 item sources, 16 dungeon snapshots, 32 scheduled calendar, 64 was the v1 switchbot (/mt_switchbot / MTSB1) and is no longer advertised, because the AVA2 switchbot uses its own packets (FEATURE-SWITCHBOT.md), 256 world bosses (see FEATURE-BOSS-TRACK.md). The current mask is 959. Unknown capability bits are ignored; unknown versions are rejected. Capability advertises the query implementation; missing quest/config can still return unsupported/schedule_unavailable. The client negotiates before business queries; old servers time out to unsupported, not an empty result.

Each drop/chest/source page contains at most 8 rows, with consecutive absolute indices. TOTAL is capped at 4096; stats are one complete bounded snapshot (currently the named keys in kPortStats, less than 128). Client commits only a complete, matching begin/rows/end sequence. Unknown/stale request IDs cannot overwrite the current selection. Each line is bounded below 512 bytes; rows contain IDs and values, not server-provided script/names/markup.

Rules:

RULE Meaning of MIN/MAX and weights
0 rank common drop (common_drop_item.txt) or level-range common drop (common_drop_new.txt, MIN/MAX clipped to monster level ±20); MIN/MAX = eligible player levels
1 independent monster drop group; weight is original configured threshold, not final probability
2 weighted kill group; MIN = original kill-per-drop parameter; weight/group total describe the conditional selection
3 level group; MIN = player minimum level; original denominator 1,000,000
4 glove/premium eligibility required; threshold still subject to runtime drop modifiers
5 monster-template extra item
10 NORMAL chest, select one weighted entry
11 PCT chest, independent comparison per entry against a 1..100 random integer
20/21 reverse source is a NORMAL/PCT chest, ITEM is the chest ID

For sources with rules below 20, ITEM is a monster ID. For chest rewards, IDs 1..7 are the existing CSpecialItemGroup reward enum: GOLD, EXP, MOB, SLOW, DRAIN_HP, POISON, MOB_GROUP. COUNT is the original amount/effect/target parameter, not always an item count. QUEST/SPECIAL groups are not treated as chest rewards. A matching item template and GIFTBOX/TREASURE_BOX type are required.

Errors: rate, invalid, missing, offset, unsupported, unsupported_chest, too_many. Empty mob/source pages refer only to covered regular drop paths. Quest/event/hard-coded/map-specific/extra-stone-drop paths are not advertised as exhaustively queried. Chest preview does not validate current inventory keys/eligibility or grant rewards; original use path owns those checks.

Stats use stable text keys mapped to this build's POINT constants. LEVEL/HP/SP and maxima use the actual character getters; other keys use own character GetPoint. No access to another player's stats and no AVA2 numeric point aliases. This is a point snapshot, not a final damage simulator or all-source multiplier breakdown.

Tests / build

python3 tests/features/test_queries.py

The test compiles production query and command bodies against original group classes. It checks all supported group paths, live fixture changes, common-only polymorph filtering, NORMAL/PCT weights, special reward IDs, unsupported groups, own stats/HP getter, source pages, throttle/invalid requests and zero RNG calls.

FreeBSD target build was completed in /root/metin2-features-dev/src/server/game/src, with both BINDIR and GAMEDIR pointed to the isolated directory. The Makefile moves its output: never omit GAMEDIR during validation. Includes added to the legacy build require dependency regeneration or explicit -W item_manager.cpp -W cmd_general.cpp; after char.h changes rebuild all affected units.

No live 203 binary was replaced, no service was restarted and no DB schema was changed by this batch. The staged build is not a production deployment. Live acceptance and mobile device validation remain pending; switchbot/attribute locks and battlepass are not claimed implemented. The subsequent dungeon/calendar batch is documented in FEATURE-DUNGEON-CALENDAR.md.

Dungeon/calendar snapshots

dungeons uses subject/offset 0 and a complete stat-style snapshot, capped at 128 fields. Mandatory lair keys: end, join_end, phase (0 new run possible, 1 join window, 2 room busy), ticket, tickets, boss, owned, alive, npc, map, each prefixed lair_. The original strict negative cooldown test is preserved: a new run is available only after end, not at end. lair_phase is not authorization to enter. Optional weekly group must be complete: weekly_end, weekly_hunt_end, weekly_active, weekly_npc, weekly_map. These are personal collection-task times, independent of shared room admission. A running/unloaded own quest returns busy; missing/invalid settings return unsupported.

calendar uses subject 1, offset 0..4096, page size 8, total at most 256. Event rows contain only bounded IDs/numeric data. Kind 1 moonlight-box, 2 Christmas-sock; time/scope semantics in FEATURE-DUNGEON-CALENDAR.md. ACTIVE reflects the interval and requesting character's current channel/empire. UI renders UTC dates, resynchronizes after sleep, and only fires opt-in reminders from freshly confirmed snapshots. No client-authored schedule or progress update command exists.

Update 2026-10-15: this code went live on 203 together with switchbot and pickup (main 3b7e158); see the production deployment section of FEATURE-SWITCHBOT.md. No port_events.tsv is installed, so the calendar gates are still inert.