Files
metin2-server/docs/FEATURE-AVA2-UNLOCK.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

141 lines
13 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.
# AVA2 items: unlocking the locked systems
The 478 AVA2 drop items come from metin2-client `tools/server/ava2-items` (see FEATURE-AVA2-DROPS.md). Items of systems 40250 lacks were imported as ITEM_NONE. This branch turns them back into usable items one system at a time. Each phase keeps the AVA2 row (type, subtype, values, applies) once the server and client understand it.
| Phase | Items | State |
|---|---|---|
| P1 boxes and keys | 77918–77920 boxes, 77921–77923 keys (`ITEM_TREASURE_BOX` / `ITEM_TREASURE_KEY`, value0 3–5) | done |
| P2 stones | 28444 破碑之石+4 (`APPLY_ATTBONUS_STONE`), 28445 Boss stone (`APPLY_ATTBONUS_BOSS`) | done |
| P3 dragon armor | 21210–21219 暗龙 (warrior), 21230– 风龙 (assassin), 21250– 魔龙 (sura), 21270– 神龙 (shaman), +0..+9 | done (client) |
| P4 sash | 85004 领主 / 85008 大师 / 85014 王朝 / 85018 皇家 披风 (`COSTUME_SASH`, grade 4) | done, not deployed |
| P5 mounts | 71502 / 71505 / 71508 / 71511 坐骑时装 (`COSTUME_MOUNT`), 71234 / 71254 坐骑外观 (`COSTUME_MOUNT_SKIN`) + mobs 32012 / 32028 | done, not deployed |
| P6 costume enchants | 54001–54078 时装 / 发型强化石, 54124–54174 坐骑外观强化石 (`USE_CHANGE_ATTRIBUTE`); weapon / sash-skin / effect ranges and 53996 stay locked | done, not deployed |
| P7 talismans | 护符 chains 9600–10950 (`ARMOR_PENDANT`, +0..+200 per element), 71301 / 71302 / 53996 / 53997 talisman attribute items | done, not deployed |
| P8 new rings | 戒指 chains 19500 红宝石 / 19520 石榴石 / 19540 祖母绿 / 19560 蓝宝石 (`ITEM_NEW_RINGS`, +0..+9) | done, not deployed |
## P1: boxes and keys
40250 already has both types. A key opens a box when their value0 match (char_item.cpp, `ITEM_TREASURE_KEY`); the box then hands out its special_item_group group (live since the drops deploy). 203's own boxes use value0 0–2, so AVA2's 3–5 don't clash.
## P2: stone and Boss bonus
The points exist from the biolog port (POINT_ATTBONUS_STONE 240, POINT_ATTBONUS_BOSS 241, damage in battle.cpp); the apply types did not.
- `APPLY_ATTBONUS_STONE = 139`, `APPLY_ATTBONUS_BOSS = 140` (common/length.h), the same numbers as AVA2 and the client (`ItemData.h`). 92–138 are reserved for AVA2 applies not ported yet: `aApplyInfo` maps them to POINT_NONE and ProtoReader's `arApplyType` names them `APPLY_RESERVED_<n>`, so array index = apply number.
- `CHARACTER::ApplyPoint` handles both like the other additive applies.
- ProtoReader is in the db, so **the db binary must be redeployed with the game**; an old db rejects the items' `APPLY_ATTBONUS_*` columns.
- The two stones share AVA2's stone family 31 (value5), so a weapon holds only one of them. The 7 guardian weapons keep their AVA2 `APPLY_ATTBONUS_BOSS 5`.
Test: `tests/features/test_applies.py` (numbering in length.h, constants.cpp, ProtoReader and the client header).
## P3: dragon armor
Ordinary `ARMOR_BODY` items; the server needed nothing. All ten refine steps are imported so the refine chain (refine sets 81–89, 203's own costs) works; +9 ends the chain.
The look is armor shape 32 (value3). The 40250 race msm stop at shape 30, and they cannot be patched from a pack (a bare file name always comes from the root pack). The client therefore registers the shape after each race msm load: script `mt_shapes` (metin2-client `src/platform/ScriptLib/ArmorShapesScript.inc`). The models `<race>_7_1.gr2` (+ LODs, skin) ship in the ava2items pack.
**Open:** AVA2 requires level 115–120. 203 caps at MAX_LEVEL 105, so nobody can wear the armor, nor the guardian weapons (level 120) already live.
## P4: sash
AVA2's sash (acce) system, ported from `Srcs/Server` (`#ifdef __SASH_SYSTEM__`) into `game/src/port_sash.cpp`.
- Item: `ITEM_COSTUME` / `COSTUME_SASH = 3` (ProtoReader `arSub28`, so **the db binary changes too**). value0 = grade (the four imported sashes are grade 4); socket0 = absorption %, socket1 = vnum of the absorbed weapon/armor. An unrolled grade-4 sash gets 11–25 % on first equip/creation (`SASH_GRADE_4_ABS_*`), combining caps at 19 %.
- Slot `WEAR_COSTUME_SASH = 24`; `PART_SASH` follows `PART_HAIR`. The part is not stored in the player table: `SetPlayerProto` clears it and the equipped sash sets it to vnum − 85000, +1000 once absorption reaches 19 % (the client shows the glow above 86000).
- **Protocol:** `CHR_EQUIPPART_SASH` is a fifth `awPart` WORD in GC_CHARACTER_ADD / ADD2 / UPDATE, `HEADER_CG_SASH = 211`, `HEADER_GC_SASH = 215`. Old clients break; the server and the client deploy together.
- Absorbed bonuses: the sash adds the absorbed item's applies, attributes and (weapons) attack values scaled by absorption, `int(v*abs/100 + .5)` (+1 when positive), in `CItem::ModifyPoints` and battle.cpp. `MTSASH <code>` chat commands report window errors and results to the client (`mt_sash`).
- Combine: two sashes of the same grade, price 100k/200k/300k/500k by grade, success 80/70/50/30 %. Absorb: sash + weapon/armor, the material is destroyed.
- Window: quest `sash` on 王铁匠 20016 (203 has no NPC 60003), `pc.open_sash(true)` combine / `(false)` absorb: metin2-client `tools/server/sash` (installs `pc.open_sash` into quest_functions).
- Client: `src/platform/ScriptLib/SashScript.inc` (`mt_sash`: windows, costume slot, tooltips), models + `item_scale.txt` + effects in the ava2items pack.
Test: `tests/features/test_sash.py` (numbering, packet layout shared with the client header, quest hook).
## P5: mount costume and mount skin
AVA2's `ENABLE_MOUNT_COSTUME_SYSTEM` + `ENABLE_MOUNT_SKIN`, ported 1:1 into `game/src/port_mount.cpp`. They ride on the 40250 horse: the worn costume only changes the horse race.
- Items: `ITEM_COSTUME` / `COSTUME_MOUNT = 2` and `COSTUME_MOUNT_SKIN = 4` (AVA2 numbers the skin 7; ProtoReader `arSub28` gains `COSTUME_MOUNT_SKIN`, so **the db binary changes again**). value0 = horse race.
- 71502 狮子 20113 (怪物强悍 +30 %), 71505 野猪 20110 (破碑 +30 %), 71508 狼 20111 (Boss +30 %), 71511 20112 (双倍经验 30 %).
- The applies count while the costume is worn.
- Skins 71234 蓝色巴里 → 32012, 71254 白色冬日羊驼 → 32028.
- Both subtypes return no attribute set (`GetAttributeSetIndex` −1, the sash too), so they cannot be rerolled.
- Slots `WEAR_COSTUME_MOUNT = 25` and `WEAR_COSTUME_MOUNT_SKIN = 26`.
- `GetMyHorseVnum`: the worn skin's value0, else the worn mount's value0, else the horse-level race.
- Summoning and riding still need horse level ≥ 1, as on AVA2; equipping without a horse says `MTMOUNT need_horse`.
- Riding uses horse stamina.
- Hooks follow AVA2:
- Equipping re-summons.
- Taking the mount off sends the horse away; taking the skin off re-summons.
- A skin needs a worn mount (`need_mount`). Neither piece changes while riding (`riding`). The mount stays while a skin is worn (`has_skin`).
- A worn mount is summoned on login.
- `/user_horse_back` also takes the mount off.
- Mobs 32012 / 32028 come from the AVA2 mob_proto rows (`mobs-server.tsv`, installed by `install_items.py … <mobs-server.tsv>`).
- Client:
- RaceManager `__IsNewMountRace` (32000–32100 → `npc_mount`).
- `mt_mount` (`MountScript.inc`) registers the npclist rows, adds the costume window slots and renders the `MTMOUNT` messages.
- The models ship in the ava2items pack (`MOUNT_MOBS`).
Test: `tests/features/test_mount.py`.
## P6: costume enchants
AVA2's `ENABLE_SPECIAL_COSTUME_ATTR`, in `game/src/port_costume_attr.cpp`. The items are `ITEM_USE` / `USE_CHANGE_ATTRIBUTE`. value0 is the apply type and value1 the value; AVA2 apply numbers equal 203's (P2 aligned 139/140). value2 is the target mask `1 << bonus flag`.
- Unlocked ranges (make_items `ENCHANT_KEEP`):
- 54001–54027 时装 (mask 2, body);
- 54028–54078 发型 (4, hair);
- 54124–54174 坐骑外观 (16, mount skin).
- Still locked, since the target systems don't exist here: 54079– weapon costume (8), 54175– sash skin (32), 54220– effect (64). 53996 became a talisman item in P7.
- `CItem::IsCostumeEnchant` (vnum 54001–54267 with a nonzero value2) is checked first in the change/add-attribute case of `UseItemEx`, before the 40250 costume refusal. So an enchant never reaches the reroll code, and dragged onto gear it is refused (`MTCATTR target`).
- `CostumeEnchantUse` follows AVA2's checks:
- target kind and mask (`target`);
- apply none (`none`);
- not while worn (`equipped`, the 40250 switcher rule);
- at most 3 attributes (`full`);
- no duplicate apply (`has`).
- Then `AddAttribute`, consume one, `ItemLog COSTUME_ENCHANT`, `done`.
- The switchbot never uses enchants: it only looks up the switcher vnums in FEATURE-SWITCHBOT.md.
- Client `mt_costume_attr` (`CostumeAttrScript.inc`):
- marks matching costumes as usable drop targets (the 40250 inventory already sends every `USE_CHANGE_ATTRIBUTE` drop);
- adds the attribute and targets to the enchant tooltip;
- renders `MTCATTR`.
Test: `tests/features/test_costume_attr.py`.
## P7: talismans
AVA2's `ITEM_TALISMAN_EQUIPMENT` + `ELEMENT_NEW_BONUSES`, in `game/src/port_pendant.cpp`.
- Item: `ITEM_ARMOR` / `ARMOR_PENDANT = 7` (ProtoReader `arSub2`, so **the db binary changes again**), worn in `WEAR_PENDANT = 27`. The AVA2 wear flag `WEAR_PENDANT` does not exist here: `FindEquipCell` sends every talisman to the slot before the wear-flag check.
- Six chains of 201 items (+0..+200), fire 9600, ice 9830, earth 10060, dark 10290, wind 10520, elect 10750. Each carries `APPLY_ENCHANT_<element>` = its step; the level limit rises from 20 to 60 along the chain.
- Refine sets 440–499 (fragment 96001–96006 + 30031 + 33031 ×10, 50000 yang, 100 %) are SQL rows: metin2-client `tools/server/pendant` (`install.sh`, then restart the db).
- Applies `APPLY_ENCHANT_ELEC..DARK = 123..128` (AVA2 numbers; the db names are AVA2's, `APPLY_ENCHANT_ELECT` first) → `POINT_ENCHANT_* = 242..247`.
- Damage (battle.cpp `CalcAttBonus`): against a monster with `RACE_FLAG_ATT_<element>`, attack +point %, so a +200 talisman triples the attack on those monsters (×(1+200/100)), which is AVA2's own balance. Each flag is its own `if`, as on AVA2. AVA2 leaves out ICE; we include it, since 203 has 83 ice monsters and an ice talisman chain.
- Attributes:
- The pool is AVA2's item_attr pendant column (20 rows, levels 1–5), kept in a table in `port_pendant.cpp` instead of a new item_attr column (that would change the db boot packet).
- `GetAttributeSetIndex` stays −1. So talismans drop without attributes, and the 40250 switchers and the attribute lock refuse them. The switchbot rolls them with 71302 only (pseudo attribute set 9).
- 71302 rerolls all attributes (needs at least one; levels 0/10/40/35/15 %). 71301 adds one up to 5, always succeeding (levels 40/50/10 %). No duplicates.
- **Deviation:** AVA2's 53996 / 53997 are generic switcher / adder items, a free 40250 gear reroll. Here they work like 71302 / 71301, as their zh names (护符附魔道具 / 护符加持道具) say.
- Not while worn (`equipped`), like the 40250 switcher. Any other attribute item dropped on a talisman, or a talisman item dropped on anything else, gets `target`.
- Messages: `MTPENDANT target|equipped|empty|changed|full|added` (client `mt_pendant`). `ItemLog PENDANT_CHANGE` / `PENDANT_ADD`.
- Not ported: AVA2's element target packet (`ELEMENT_TARGET`, the element icon over the target HP bar).
- Client: `ItemData.h` / `PythonItemModule` constants, `c_Equipment_Pendant`, apply texts, and `mt_pendant` (`PendantScript.inc`: the equipment slot under the earring, item drop targets, messages).
Test: `tests/features/test_pendant.py`; `test_applies.py` covers the 123–128 numbering.
## P8: new rings
AVA2's `ENABLE_NEW_RINGS`, in `game/src/port_rings.cpp`.
- Item: `ITEM_NEW_RINGS = 36` (`ITEM_SHINING = 35` is reserved for the AVA2 numbering and not ported). It is a new ProtoReader type, so **the db binary changes again**. Worn in `WEAR_RINGS_1 = 28` / `WEAR_RINGS_2 = 29`: `FindEquipCell` takes ring slot 1 when free, else slot 2. Rings have no wear flag.
- Four chains of 10 (+0..+9). Each step carries a stat (INT / DEX / STR / CON) and a resist against one class. Level limit 90 (203's MAX_LEVEL is 105). They reuse 203's refine sets 46–54, which already have AVA2's materials, so no refine SQL is needed.
- Sockets: rings are socket accessories (`IsAccessoryForSocket`). Drills add sockets (up to 3). As with every socket or attribute item in 40250, the ring must not be worn. Each family takes its AVA2 jewel (`CanPutInto`): 19500 → 50635, 19520 → 50636, 19540 → 50637, 19560 → 50638 (19220 → 50634 is in the table, but that family is not imported).
- Attributes:
- The pool is AVA2's `item_attr_rings` (20 rows, levels 1–5), kept as a table in `port_rings.cpp`. `GetAttributeSetIndex` stays −1, and `PutAttributeWithLevel` branches to the ring pool.
- The 40250 switchers and adders (`USE_CHANGE_ATTRIBUTE`, `USE_ADD_ATTRIBUTE`, `USE_ADD_ATTRIBUTE2`) accept rings, with the usual not-while-worn rule. 71151 / 71152 (weapon / armor only) refuse them, by design.
- The switchbot rolls rings from this pool (pseudo attribute set 8). The rare (6th / 7th) attributes skip rings. AVA2's `item_attr_rare_rings` is not ported.
- Rings drop without attributes: `AlterToMagicItem` only handles weapons and armor.
- Client: `ITEM_TYPE_RINGS`, `c_Equipment_Rings1/2` (253 / 254), and `mt_rings` (`RingsScript.inc`). That module adds the two slots beside the shoes, the accessory tooltip (applies, attributes, jewel sockets) and the drop targets for drills, jewels, switchers and adders.
Test: `tests/features/test_rings.py`.