Files
metin2-server/docs/FEATURE-ATTR-LOCK.md
T
2026-10-15 23:11:29 +09:00

7.1 KiB
Raw Blame History

PORT attribute lock

AVA2 ENABLE_LOCK_ATTR, rebuilt for this server's item layout. Up to two of the five normal attribute slots keep their type and value when the item is rerolled. Source: src/server/game/src/port_attr_lock.{h,cpp}, CItem::ChangeAttribute / CopyAttributeTo (item_attribute.cpp), the cache fields in item.h/item.cpp, the boot hook in main.cpp, and the lock verb of mt_switchbot (port_switchbot.h).

Storage

AVA2 keeps up to two 1-based slot indices as attribute values at indices 7 and 8 of its 15-slot attribute array. This server has ITEM_ATTRIBUTE_MAX_NUM = 7 (5 normal + 2 rare) and ITEM_SOCKET_MAX_NUM = 3, which metin stones use. The item table does have socket3..socket5, but TPlayerItem and the client packets only carry 3 sockets, so using them would change both the db↔game and client wire formats. The item row is also rewritten with REPLACE INTO, so a column written behind the db cache would be lost.

The lock therefore lives in its own table, which no packet or db-cache structure carries:

CREATE TABLE IF NOT EXISTS mt_item_attr_lock (item_id INT UNSIGNED NOT NULL PRIMARY KEY, mask TINYINT UNSIGNED NOT NULL) ENGINE=MyISAM
  • Each game core creates it at boot (PortAttrLockBoot, auth cores skip it). No manual migration is needed.
  • Bit i of mask is normal slot i (0..4). A mask of 0 deletes the row.
  • PortAttrLockGet reads the mask once per CItem with a synchronous DBManager::DirectQuery by primary key and caches it on the item (m_portAttrLock, m_portAttrLockLoaded). Exchanges on the same core keep the object and its cache. A warp or relog creates a new object, which reads the row again.
  • PortAttrLockSet writes synchronously, so the next core always sees the new value, and writes an ATTR_LOCK item log (hint = new mask).
  • A failed lookup logs a syserr, returns 0 and is retried next time. A failed write leaves the cache unchanged and returns the db error.
  • CopyAttributeTo (refine, upgrade, over9 refine, quest item swaps) copies the lock to the new item ID together with the attributes.
  • Rows of destroyed items stay behind. They are harmless because item IDs are not reused.

Rules

  • Only the five normal slots can be locked; the rare slots 5/6 are not affected. The item must sit in the inventory, not be equipped or in an exchange, not be a costume, and have an attribute set. The slot must hold an attribute.

  • At most 2 lock groups, and at least one filled slot must stay unlocked. On items with an addon type (sAddonType, weapons whose slots 0/1 are the skill / normal hit bonus pair), slots 0 and 1 lock and unlock together and count as one group.

  • The bot's own item cannot be locked or unlocked while the bot is rolling it (running).

  • Locking is free. AVA2 consumes 50348/50349 per lock or unlock; those vnums do not exist in 203 item_proto.

  • CItem::ChangeAttribute (scroll rerolls, the switchbot, the GM command):

    1. take the effective mask: stored mask ∩ filled slots, with the addon pair kept whole;
    2. clear the normal slots;
    3. apply the addon only if the addon pair is not locked;
    4. put back the locked slots at their indices;
    5. reroll the remaining count with the original PutAttribute. It writes to the first empty slot and skips types already present, so the gaps fill in order without duplicating a locked type.

    With no lock, the effective mask is 0 and the sequence equals the original. The attribute count is kept, and the rare slots are untouched.

  • Adding an attribute (71085) and rare-attribute scrolls do not look at the lock.

Protocol (part of mt_switchbot v1)

/mt_switchbot 1 lock CELL SLOT       toggle the lock on normal slot SLOT (0..4)
MTSB1 lock CELL VNUM MASK            effective mask; also sent after every attrs_end
MTSB1 error lock CODE                item equipped no_attr busy running slot max db rate invalid

slot means out of range or empty. max means a third group, or every filled slot locked. db means the write failed. Older servers never send a lock line, so the client shows no lock buttons there.

Verification

  • tests/features/test_attr_lock.py cuts the production CItem::ChangeAttribute body out of item_attribute.cpp and compiles it against a stub item. It checks that:
    • with no lock every slot changes;
    • locked slots 1+3 are kept in place and the gaps are refilled;
    • a locked type is not rolled again;
    • a lock on an empty slot is ignored;
    • a locked addon pair skips ApplyAddon, while an unlocked one is rerolled;
    • the rare slot is untouched and the count is kept;
    • there is no DB lookup when there are no attributes;
    • every toggle, effective-mask and group-count rule holds.
  • It also checks the boot hook, the Makefile, the cache initialisation and that CopyAttributeTo copies the lock.
  • tests/features/test_switchbot.py covers the lock verb (toggle, slot, max, db, running, no_attr, item, invalid, the addon pair) and the lock line after attrs_end.
  • FreeBSD: full rebuild of game in /root/metin2-features-dev (log attrlock-build.log; item.h changed, so every .cpp was touched).
  • Live on 2026-10-15, channel-5 test core (13040) with the isolated binary, macOS client, [SA]Admin, armour 11209 (item 20000178, 5 attributes), scroll 71084:
    • the first boot created the table;
    • locking slot 1 → mask 2, then slot 3 → mask 10, then slot 0 → error lock max;
    • 10 switchbot rolls (limit, scrolls 143 → 133): (23,10) in slot 1 and (39,10) in slot 3 stayed the same on every roll, slots 0/2/4 changed every roll, and there were no duplicate types;
    • the row read 20000178 10;
    • a new client session showed lock 19 11209 10 (reloaded from the table);
    • unlocking → 8 → 0, and the row was deleted;
    • log has four ATTR_LOCK rows (hints 2, 10, 8, 0).
  • Not done: Android device test.

Production deployment

  • 2026-10-15 16:08, approved by the user. All 203 live cores now run main dc71593 (game sha256 a8556bdc…, the exact binary the channel-5 core was tested with, built in /root/metin2-features-dev). The db binary is unchanged. 0 players were online.
  • Package /root/deploy-features/20261015-attrlock (deploy.sh check|go|rollback, SHA256SUMS). The previous game/db (boss deploy, 400e44f) are in /root/backup-bin/20261015-160813. The 8 changed files were synced into /usr/metin2/src, and the replaced ones are in src-before/. Because item.h changed, a later rebuild.sh build must touch every game .cpp. sh deploy.sh rollback restores both; the mt_item_attr_lock table can stay, since old binaries ignore it.
  • CH2–CH4 and the channel-5 core were started by hand after start.sh 1, giving 14 game cores plus db and auth.
  • Live acceptance on CH1 (13000), same armour 11209 (item 20000178), scroll 71084:
    • lock slot 1 → 2, slot 3 → 10, slot 0 → error lock max;
    • 10 switchbot rolls (scrolls 133 → 123): (23,10) and (39,10) unchanged on every roll, the other slots changed;
    • the row read 20000178 10; a new session showed lock 19 11209 10;
    • unlocking → 8 → 0 deleted the row, and four new ATTR_LOCK log rows were written;
    • no PortAttrLock syserr entries.