Files
metin2-server/docs/FEATURE-SWITCHBOT.md
T

6.2 KiB

PORT switchbot (自动洗练), AVA2 port

AVA2 ENABLE_SWITCHBOT ported 1:1 (reference: AVA2 game/src/new_switchbot.{h,cpp}, client PythonSwitchbot.cpp and root/uiswitchbot.py). Classes, API, packets, the window and the 0.1 s roll speed are AVA2's. It replaces the v1 /mt_switchbot chat protocol (MTSB1, query capability bit 64). That command and its lock verb are gone.

Source:

  • src/server/game/src/port_switchbot.{h,cpp}: SwitchbotHelper, CSwitchbot, CSwitchbotManager, PortSwitchbotBoot.
  • common/length.h: SWITCHBOT = 7 in EWindows (GROUND is now 8), SWITCHBOT_SLOT_COUNT 6 / _REAL 5 / ALTERNATIVE_COUNT 2 / NORM_ATTR_NUM 5, TItemPos::IsSwitchbotPosition.
  • common/tables.h: the switchbot tables.

Window and items

  • Items placed in the SWITCHBOT window (cells 0..4) are kept in m_pointsInstant.pSwitchbotItems and saved with window = 'SWITCHBOT'. The db loads, saves and deletes that window with SAFEBOX and DRAGON_SOUL_INVENTORY (three queries in ClientManagerPlayer.cpp).
  • At boot (game cores only), PortSwitchbotBoot adds 'SWITCHBOT' to the player.item.window enum if it is missing. The deploy SQL carries the same ALTER.
  • MoveItem only accepts SwitchbotHelper::IsValidItem items into the window. That is AVA2's list: weapons, rings, and armour (body, head, shield, wrist, shoes, necklace, earrings, talisman). Cell 5 is rejected. The move hooks send:
    • switchbot_error active when the item is moved out of a running slot;
    • switchbot_error invalid when the item is not valid for the switchbot.
  • Drop, give, exchange and safebox refuse switchbot cells: the item has to go back to the inventory first. Shops sell only from the inventory.

Rolling

  • CSwitchbot::SwitchItems runs every 0.1 s (c_fSpeed). Each active slot takes one switcher per pass.
  • A slot finishes when one configured alternative fully matches within the first 5 attributes (AVA2 CheckItem). An alternative that isn't configured counts as a match.
  • Deviations from AVA2 (also listed at the top of port_switchbot.cpp):
    • Cell 5 (AVA2's hidden switcher cell) is never used. Switchers come from the inventory, skipping stacks that are being exchanged, locked or sold in the player's shop.

    • Which switcher is used follows the manual path:

      • a talisman takes only 71302;
      • a weapon or body armour with no level limit above 40 takes 71151 / 76023 first;
      • everything else takes 71084, then 39028.
    • A slot whose item has no attributes stops instead of rolling.

    • Every roll is written to ItemLog as SWITCHBOT, with the item id as the hint.

    • End and stop messages are server commands, which the client turns into localized text:

      • switchbot_end <slot>
      • switchbot_stop noattr <slot>
      • switchbot_stop nochanger <slot>

      The slot is 0-based. AVA2 sent the locale ids 864 / 865 with slot+1.

    • Leaving the core deletes the table once it has been sent on. A logout that unregisters the last active slot also stops the event.

    • The attribute list has two pseudo sets after ATTRIBUTE_SET_MAX_NUM: 8 = rings (port_rings.cpp) and 9 = talismans (port_pendant.cpp).

  • Warp: CHARACTER::WarpSet sends the table over P2P (HEADER_GG_SWITCHBOT 31, TPacketGGSwitchbot) before GC_WARP. The target core keeps it, and EnterGame re-registers the slots whose item is still there and restarts the event.

Protocol

Header numbers, subheaders and field order are AVA2's. The structs are pack(1), and their sizes are pinned with static_assert in port_switchbot.cpp and in the client (Packet.h, PythonSwitchbot.h).

Packet Header Layout
CG 171, dynamic BYTE header, int size, BYTE subheader, BYTE slot (7) + START: TSwitchbotAttributeAlternativeTable[2] (15 each) / STOP
GC 171, dynamic same 7-byte head + UPDATE: TSwitchbotTable (220) / UPDATE_ITEM: TSwitchbotUpdateItem (40: slot, vnum, count, 3 sockets, 7 attributes) / SEND_ATTRIBUTE_INFORMATION: TSwitchbottAttributeTable[n] (9)
GG 31 TPacketGGSwitchbot (223)

CG is registered in packet_info.cpp with Set(..., true) and GG with Set(..., false). The 40250 base packets are unchanged.

Version gate. The client is built with LOCALE_SERVICE_EUROPE, so every locale sends CG_CLIENT_VERSION2. The new client's timestamp is 1215955205 mt20261016. 203 is a europe locale and checks the version with atoi, which still reads 1215955205. Before EnterGame sends anything, it checks SwitchbotHelper::IsClientSupported, which looks for mt<date> in the timestamp with date >= PORT_SWITCHBOT_CLIENT_VERSION. An older client sends 1215955205 only and gets no GC_SWITCHBOT packet. It can't fill the window either. (The non-EU branch sends mt20261016.)

Verification

  • tests/features/test_switchbot.py checks:
    • the window enum, headers, subheaders, struct fields and sizes, on both the server and the client;
    • the window hooks, the P2P hand-over, the boot ALTER and the switcher choice;
    • the version gate;
    • that /mt_switchbot is gone.
  • Client: metin2-client/tests/wiki/test_switchbot.py checks that the window script is AVA2 uiswitchbot.py verbatim, plus its glue.
  • Live-tested on 203 on 2026-10-16 with the Mac client and a script driver. Weapons ran on channel5 against the live db. Rings and talismans ran on the isolated sbtest cluster (metin2-client/tools/server/sbtest), which has the unlocked protos. Results:
    • Move in, drag back, start/stop, auto-finish on target, refusal to move out while active, refusal of an invalid item; about 12 rolls/s, ItemLog matches the switchers consumed.
    • Rings roll from the ring pool with 71084; talismans roll from the talisman pool with 71302 only.
    • Relog keeps the items (from the db cache, and from MySQL after a restart). The bot stops and the targets are cleared, as in AVA2 (UnregisterItem on logout).
    • Same-core map change (1 → 21 → 1) keeps rolling with the targets kept; it only pauses during the warp.
    • The cross-core P2P hand-over is not tested yet (the test cluster has one core).
  • Not deployed. The live 203 still runs v1. Rings and talismans need the whole feature/ava2-unlock (with its protos), and the server and client must be deployed together.