Files
metin2-server/docs/FEATURE-VIP.md
T
shenleiandClaude Opus 5.5 69e335ba9c Add VIP cards extending the seven premium services
Using 38001 (7 days) or 38002 (30 days) moves every account.account
*_expire column to max(now, end) + days, capped at 400 days left, with a
1 s gap per player. The db core only hands out the login-time premium
times (CLoginData), so the game reads the row back after a card and on
every enter-game and updates m_aiPremiumTimes and the 500..506 icons.
/mt_vip 1 status reports the remaining seconds. docs/FEATURE-VIP.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 02:13:17 +09:00

85 lines
5.2 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 VIP card
A card extends all seven original premium services of the account. 40250 has the services but no in-game way to grant them. Source: `src/server/game/src/port_premium.h`, the hook in `CHARACTER::UseItem` (char_item.cpp), the enter-game refresh in input_login.cpp, `CHARACTER::PortSetPremiumTime` (char.h) and `/mt_vip` (cmd_general.cpp, cmd.cpp). Item data (size, flags, names, shop): metin2-client `tools/server/vip-card`.
## Services
`account.account` holds one end time per service. The game keeps them in `m_aiPremiumTimes` and shows affect `AFFECT_PREMIUM_START + i` (500..506) as the icon.
| i | Premium | Column | Effect on newcibn |
|---|---|---|---|
| 0 | `PREMIUM_EXP` | `silver_expire` | monster exp ×1.2 × `mob_exp_buyer`/100 (char_battle.cpp) |
| 1 | `PREMIUM_ITEM` | `gold_expire` | item drop rate |
| 2 | `PREMIUM_SAFEBOX` | `safebox_expire` | safebox size 3 (input_db.cpp) |
| 3 | `PREMIUM_AUTOLOOT` | `autoloot_expire` | gold goes straight to the bag (char_battle.cpp) |
| 4 | `PREMIUM_FISH_MIND` | `fish_mind_expire` | fishing |
| 5 | `PREMIUM_MARRIAGE_FAST` | `marriage_fast_expire` | marriage love points |
| 6 | `PREMIUM_GOLD` | `money_drop_rate_expire` | gold drop rate |
## Cards
| Vnum | Days |
|---|---|
| 38001 | 7 |
| 38002 | 30 |
Both are unused `ITEM_NONE` rows in 40250. `PortVipUseCard` runs in `UseItem` after the sex check, before any type handling, so the item type does not matter.
When a card is used:
1. The card is refused, and not consumed, in two cases:
- the player used a card or `/mt_vip` less than 1 s ago (`rate`);
- for any service, the remaining time plus the card would exceed 400 days (`full`). The `int` end times stay far below 2038.
2. Otherwise one card is consumed, with an `MT_VIP_CARD` item log whose hint is the number of days.
3. One `UPDATE` moves every column to `GREATEST(UNIX_TIMESTAMP(col), UNIX_TIMESTAMP()) + days × 86400`. A service that has expired restarts from now; a running one is extended.
## Freshness
Auth reads the columns only at login and passes them to the db core's `CLoginData`. Every later player load, such as a warp or a core change, fills `TPlayerTable.aiPremiumTimes` from that login-time copy. So after a card, and on every enter-game, the game reads the row itself.
`PortVipRefresh` handles this:
- It queues `SELECT UNIX_TIMESTAMP(col)... FROM account.account WHERE id=` through `DBManager::FuncQuery`. That is the same ordered queue and connection as the card's `UPDATE`, so the read sees the update.
- The answer finds the player again by PID and checks the account ID; if the player has left, nothing happens.
- For each service whose end changed, it sets `m_aiPremiumTimes[i]`, then either adds the affect with the remaining duration or removes it if the service has expired.
- It logs `PORT_VIP: <name> type <i> end <unix>`.
The db core is not changed.
## Protocol
```
/mt_vip 1 status ask for the remaining time
MTVIP1 times R0 R1 R2 R3 R4 R5 R6 remaining seconds per service (0 = none), PREMIUM_EXP .. PREMIUM_GOLD
MTVIP1 added VNUM DAYS a card was consumed; a times line follows once the row is read back
MTVIP1 error CODE rate full invalid
```
- `status` and card use share the 1 s throttle per player.
- A wrong version, or more than three tokens, gets no answer; an old client never sends one.
- The client (metin2-client `src/platform/ScriptLib/VipScript.inc`, module `mt_vip`) treats a `status` with no answer within 3 s as a server without the feature.
## Exp bonus
On newcibn the premium exp branch multiplies by 1.2 and then by `GetMobExpRate`, which returns event flag `mob_exp_buyer` (default 100). `/e mob_exp_buyer 167` gives 1.2 × 1.67 ≈ 2.0, that is +100 %. Event flags live in `player.quest` (pid 0) and every core shares them, so the flag is set once, by a GM, at deploy.
## Verification
- `tests/features/test_vip.py` checks the wiring:
- the command entry is at the end of `cmd_info`;
- the include is outside the `__AUCTION__` block;
- the hook sits between the sex check and the summon-item block;
- the refresh runs after the login affect loop.
- It also compiles the production header against a stub account table, the ordered SQL queue and the affects. It covers:
- a 7-day card, the read-back and the icons;
- the gap refusal, then a 30-day card stacked onto the current end;
- the 400-day cap: no card consumed, no query;
- other items left untouched;
- the enter-game refresh over stale values;
- a service expired by hand, and the `status` command;
- a player who leaves before the answer, and a missing account row.
- Live test, channel5 (2026-10-15), Admin account with all expire values reset to 0:
- 38002 (30 days) set all seven columns to now + 30 days, added affects 500..506 and returned `times 2592000…`.
- Two 38001 used through the inventory right-click, 2 s apart, extended to 44 days.
- A same-map `/warp` reloaded the player with the login-time 30 days. The refresh logged the seven `PORT_VIP` corrections to 44 days, and the panel showed "剩余 43 天 23 小时" for every service.
- Earlier, with premium, autoloot gold went straight to the bag; without it, the gold stayed on the ground.