Files
metin2-server/docs/FEATURE-SWITCHBOT.md
shenleiandClaude Opus 5.5 dc7159338e Add attribute lock (AVA2 ENABLE_LOCK_ATTR port)
Up to two normal attribute slots (addon pair = one group) keep their
type and value through CItem::ChangeAttribute, so scroll rerolls, the
switchbot and GM rerolls all respect it. The mask lives in the new
player.mt_item_attr_lock table (created at boot), cached per CItem and
written synchronously; CopyAttributeTo carries it to refined items.
No item struct, db cache or client packet change. Toggled with
/mt_switchbot 1 lock CELL SLOT; MTSB1 lock line follows attrs_end.

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

8.3 KiB
Raw Permalink Blame History

PORT switchbot (automatic attribute change), v1

AVA2-style automatic rerolling (reference: AVA2 new_switchbot.cpp / uiswitchbot.py), rebuilt so that the server stays authoritative and the existing reroll path is unchanged. Source: src/server/game/src/port_switchbot.h, command mt_switchbot (cmd.cpp), quiet-INFO hook in CHARACTER::ChatPacket (char.cpp), fields in char.h. No attribute lock, no DB schema, no packet header, no P2P transfer.

Rules

  • Each roll calls the original CHARACTER::UseItem(scroll cell, target cell). All checks, probabilities, the addon handling, ItemLog CHANGE_ATTRIBUTE and scroll consumption are the manual path's. That includes the 71151/76023 restriction (weapon/body, level limit <= 40) and the GM quest flag. A roll counts only when exactly one scroll of the chosen vnum was consumed. Otherwise the bot stops with rejected and resends the original INFO line once.
  • The per-roll INFO lines (属性已变更) are held back while the bot calls UseItem (m_portQuietInfo); all other chat types pass through.
  • Only ITEM_USE / USE_CHANGE_ATTRIBUTE scrolls are accepted. USE_CHANGE_ATTRIBUTE2 has no handler in this server's UseItemEx.
  • Target item: inventory cell, not costume, attribute set != -1, at least one attribute, not equipped or in an exchange. It is bound by item ID.
  • One bot per character. One roll every 250 ms (PASSES_PER_SEC(1)/4). Limit 1..1000 rolls.
  • Targets: up to 2 alternatives, each 1..5 distinct (apply, minimum). An alternative matches when every target is found among the 5 normal attribute slots with value >= minimum. Any matching alternative stops the bot (AVA2 CheckItem semantics). The bot also checks before it starts, so an item that already matches consumes nothing.
  • Allowed targets are the applies the attribute table can roll for this item's set, excluding the item's base proto applies. The maximum is lValues[min(maxLevelBySet,5)-1]. Items with an addon type also allow skill damage 30 / normal hit 65, the item_addon bounds.
  • Every tick re-checks the state and stops with a reason. This replaces AVA2's hooks into every move/trade path.
    • Character gone, VID changed (logout or warp) or descriptor lost: the bot is erased silently.
    • busy: dead, warping, !CanHandleItem(), exchange, own shop, shop, safebox or cube open.
    • item_gone: the item is missing, has another owner, has left the inventory window or is equipped.
    • no_scroll, limit, matched, rejected, stopped.
  • No offline rolling. Rolls stop when the player leaves, and every completed roll has already been saved and logged by the original path.

Protocol (CHAT_TYPE_COMMAND, version 1)

Requests (250 ms per-character throttle; tokens <= 10 chars, <= 30 tokens):

/mt_switchbot 1 attrs CELL
/mt_switchbot 1 start CELL SCROLL_VNUM LIMIT N1 (APPLY MIN)*N1 [N2 (APPLY MIN)*N2]
/mt_switchbot 1 stop
/mt_switchbot 1 status
/mt_switchbot 1 lock CELL SLOT        (attribute lock, see FEATURE-ATTR-LOCK.md)

Replies:

MTSB1 attrs CELL VNUM COUNT
MTSB1 attr INDEX APPLY MAX            (COUNT rows, INDEX 0..COUNT-1)
MTSB1 attrs_end CELL COUNT
MTSB1 state ACTIVE CELL VNUM ROLLS LIMIT SCROLL SCROLLS REASON
MTSB1 lock CELL VNUM MASK             (after every attrs_end, and as the reply to lock)
MTSB1 error VERB CODE

REASON is one of running matched limit no_scroll item_gone rejected busy stopped idle. Error codes:

Code Meaning
rate throttled
invalid malformed
item no item in that cell
equipped equipped or in an exchange
no_attr the item cannot be rerolled
scroll the scroll is missing or the wrong type
target the apply is not allowed, above the maximum or a duplicate
running this character already has a bot
busy see the busy states above

A state line is pushed after every roll and when the bot stops. When the reason is item_gone, CELL and VNUM are 0.

Capability: the MTF1 cap mask advertises bit 64 (63 -> 127). Clients that don't know it ignore it, and the client also times out to "unsupported" against old servers.

Verification

  • tests/features/test_switchbot.py compiles the production header against stubs of the UseItem/ChatPacket contract. It covers the allowed list (proto exclusion, set filter, level cap, addon), validation, two alternatives, the already-matched start, quiet INFO, limit, no_scroll, rejected (INFO resent once), item_gone, busy, stop/status/idle and silent erase on a VID change.
  • tests/features/test_queries.py was updated for cap mask 127.
  • FreeBSD build of the whole game target on 203 in /root/metin2-features-dev (BINDIR=GAMEDIR=/root/metin2-features-dev/bin), log /root/metin2-features-dev/switchbot-build.log, with no warnings from the new code. The live /usr/metin2 binary was not replaced and no service was restarted.
  • Live test on 2026-10-15. 203 ran an extra core (/usr/metin2/server/channel5/first: CHANNEL 5, PORT 13040, P2P 14040, MAP_ALLOW 1 21 41) with its game symlinked to the isolated binary. The macOS native client (--live-server 192.168.21.203:11000:13040) drove [SA]Admin, sword 279, scroll 71084:
    • attrs returned 14 rows for the sword (18 for armor 12019), received complete.
    • limit 10 → limit after 10 rolls. State lines arrived about every 0.24 s (about 4 rolls/s); the scroll count fell 200 → 190.
    • Two alternatives with minimum 1 → matched after 18 rolls.
    • Start on an item that already matches → matched with 0 rolls and no scroll used.
    • Moving the item 33 → 90 mid-run → the run continued, the state line reported cell 90, and stop → stopped.
    • Client exit mid-run (8 rolls) → log.log stopped at the exit second. The CHANGE_ATTRIBUTE row count (72 = 10+18+12+12+12+8) stayed the same 20 s later.
    • Opening a private shop mid-run → busy about 1 s after the shop opened (6 rolls). The character needs a shop bundle (50200 or 71049); without one OpenMyShop returns before setting m_pkMyShop, so no shop opens and the bot correctly keeps rolling.
    • 76014 with 6 scrolls and limit 10 → no_scroll after 6 rolls.
    • 71151 on the level-90 sword (the original path allows limit level <= 40) → rejected with 0 rolls and the scroll kept.
    • Every roll wrote one CHANGE_ATTRIBUTE row. The core's syserr shows no new errors; the new_quest_lv52 LUA_ERROR also appears on the live cores.
  • Live acceptance on CH1 (13000) after the deploy, sword 279 and scroll 71084:
    • two alternatives with minimum 1 → matched after 2 rolls;
    • three attributes at the maximum with limit 10 → limit after 10 rolls, scrolls 157 → 147;
    • stop after 1 s → stopped after 4 rolls.
  • Not done yet: Android device validation.

Production deployment

  • 2026-10-15 14:51, approved by the user. The 203 live cores now run main 3b7e158 (game sha256 0d798ec0…, the binary the channel-5 core was tested with). The db binary is unchanged. Live /usr/metin2/src was at 4577d86, so the deploy also shipped 1a36719 (query protocol and calendar drop gates; the gates stay inert without port_events.tsv).
  • Package /root/deploy-features/20261015-features (deploy.sh check|go|rollback, SHA256SUMS). The previous game/db are in /root/backup-bin/20261015-145122 (recorded in LAST_BACKUP), and the replaced /usr/metin2/src files are in src-before/. sh deploy.sh rollback restores both.
  • The first go stopped at rebuild.sh stop_server ("server still running" after about 38 s, cores still exiting) before any backup or copy; the second go succeeded. start.sh was answered with 1, which starts only CH1 and game99, so CH2–CH4 were started afterwards with each run.sh in the start.sh order. The channel-5 test core was restarted too, giving the pre-deploy layout of 14 cores plus db and auth. The new syserr entries contain only the existing new_quest_lv52 LUA_ERROR (present since 2026-09-21).

Open items

  • Attribute lock: done separately in FEATURE-ATTR-LOCK.md (table mt_item_attr_lock, applied inside CItem::ChangeAttribute, so every bot roll keeps the locked slots). The bot's own item cannot be locked or unlocked while it rolls.
  • In 203 player.item_proto, 71084, 71151, 76014, 76023 and 39028 are USE/USE_CHANGE_ATTRIBUTE (subtype 18); 71302 (the AVA2 talisman scroll) does not exist. The bot accepts any USE_CHANGE_ATTRIBUTE scroll and leaves item rules to the original path.