Files
metin2-server/docs/FEATURE-SWITCHBOT.md
T
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

94 lines
8.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.