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>
85 lines
5.2 KiB
Markdown
85 lines
5.2 KiB
Markdown
# 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.
|