Skip to content

feat(items): items which expire, to sell the time-limited cash shop products - #1548

Open
pllanosclaria wants to merge 22 commits into
MUnique:masterfrom
pllanosclaria:feat/item-expiration
Open

pllanosclaria wants to merge 22 commits into
MUnique:masterfrom
pllanosclaria:feat/item-expiration

Conversation

@pllanosclaria

@pllanosclaria pllanosclaria commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Closes #1525

The cash shop refused every product with a duration, so the client showed "This item is not currently available" for the rented pets, transformation rings, rings and necklaces and small wings: 21 of the 205 packages of a fresh database could be sold. With this PR an item can expire, and the time-limited wearable products are sold: 104 of 205 packages. The design was agreed in #1525; this follows the current description there.

Time-limited consumables (seals, scrolls, auras, charms) stay not for sale. In OpenMU a seal gives a 30-minute effect and is consumed, while the shop sells it for 1 to 30 days; that needs a timed effect which survives a logout, which is a separate feature.

Changes

  • Data: Item.ExpiresAt (DateTime?, UTC, null = permanent) and ItemDefinition.IsSellableWhenExpired, the client's sellableWhenRentalExpired (25 items). Migration AddItemExpiration, with the compiled models and the generated loader and converter code. The loader generator got the timestamp with time zone type. Items with different expirations don't stack.

  • Configuration: ItemRules sets IsSellableWhenExpired like the client data. New price definitions with the client's fixed values for the rented items (ItemValue: 1000 zen selling price for the Panda, Demon, Spirit of Guardian and the rings and necklaces of feat(items): add the rings and necklaces of the cash shop #1400, 2000 for the Skeleton, 80 for the small wings and capes), so the server pays what the client shows. The mandatory update AddRentalItemRulesUpdatePlugIn ("Sell the rented items of the cash shop") does both for existing configurations and puts the time-limited packages which can now be delivered on sale.

  • Delivery: InventoryProductDelivery sets ExpiresAt = now + Duration when the player uses the product from the cash shop storage, so a gift waiting in the storage doesn't lose time. CanBeDelivered accepts a duration for a wearable item without consume effect which the player can get rid of once it expired (droppable, sellable, or sellable when expired). The server never creates a time-limited item the player couldn't get rid of; the catalog check of the admin panel reports such a product.

  • Expiry: ItemExpirationPlugIn, one IPeriodicTaskPlugIn with its own CheckInterval (1 minute), instead of a timer per player. An expired item stays in the inventory, also when it's equipped. The player gets the message " has expired", the client gets the item again with the expired state, and the stats of an equipped item are recalculated. Its next check is kept per game context, because one plugin instance serves all game servers of a process.

  • No effect: Item.HasEffect(utcNow) (durability left and not expired) is used for the power-ups, set power-ups, item skills, the offline-leveling pet and combat handlers and the Crywolf altar. Other players don't see an expired item in the appearance.

  • Rules: a valid time-limited item never leaves its owner's inventory, and no time-limited item is a crafting ingredient (some success rates depend on the item's price). It isn't repaired and has no durability decay with time.

    Action Valid Expired
    Move within the inventory, unequip allowed allowed
    Equip allowed refused
    Vault, trade, personal store, crafting refused refused
    Drop refused if IsDroppable
    Sell to NPC refused if IsSellableWhenExpired or IsSellableToNpc

    The trade and the personal store also check it when the trade is completed or the item bought.

  • Protocol: original client: bits 0x02 (period) and 0x04 (expired) of byte 5 of the item. Open source client: the extended item format has no free bit, so the two highest bits of the level byte are used (0x40, 0x80; the level is masked with 0x3F). After the inventory list D2 11 and one D2 12 per time-limited item, and a D2 12 after every resend of such an item, so the tooltip shows the time left (IItemExpirationViewPlugIn).

  • Admin panel: the item editor shows and edits whether an item is time-limited and when it expires (UTC), and refuses an expiration for an item the player couldn't get rid of.

  • Docs: docs/CashShop.md and the cash shop and accounts pages of the docs website.

  • Plugin names, messages and editor captions in English and German (and the other languages where the files have them).

The commits chore(resources): regenerate the designer… only regenerate Designer.cs files which had drifted from their unchanged .resx files on master, so the commits after them change only the resources they add.

The client side is sven-n/MuMain#1150. An older open source client shows rented items with a wrong level, because it doesn't mask the level byte. The bit layout is a proposal; if another one fits better, both sides change.

Testing

  • New tests: ItemExpirationExtensionsTest, ItemExpirationPlugInTest (including one game context not taking the check of another), TimeLimitedItemRulesTests (every row of the table above, the trade and the personal store), ItemExpirationRemoteViewTests and ItemSerializerTests (the bits and D2 11/12), PowerUpFactoryTest, CashShopActionsTest, RentalItemRulesDataTest (flags and prices on a new and on an existing configuration, idempotence, no buyable time-limited product without a way out), ItemViewModelExpirationTests and CashShopCatalogPageTests (admin panel).
  • ItemPriceCalculatorGoldenMasterTest and the legacy calculator of the initialization tests: the rented items are left out of the comparison on purpose, because their prices change. ItemFormulasEqualTodayTest covers the new prices.
  • dotnet build src/MUnique.OpenMU.sln, then dotnet test src/MUnique.OpenMU.sln --no-build, after merging master: MUnique.OpenMU.Tests 3240 passed, 2 skipped; Persistence.Initialization.Tests 912 passed, 12 skipped; Web.Tests 725 passed, 1 failed: MapComponentTests.ControllerCreatedAfterDisposalIsDisposedAsync, which passed three times out of three when run alone (it's about the live map, not this change); the other projects passed. No analyzer warnings in the changed files.
  • In game, on a local server (docker image of this branch, existing Season 6 database: the migration and the update were applied at the start) with the MuMain branch:
    • bought a 1-day and a 7-day Pet Panda and a Pet Skeleton; the tooltip shows the expiration day; the pet works while it's valid;
    • a valid item: drop, trade, vault and Chaos Machine refused, by the client's own rules or by the server's;
    • the expiry of an equipped pet and wings: the message, the experience bonus is gone, the pet disappears and stops collecting zen, the wings disappear and the character walks instead of flying, without a relog; another player sees the same; the expiry comes within the check interval;
    • an expired item: equip refused (drag and right click), sold to the NPC for exactly the client's price (1000 zen), consistent after a relog;
    • an item which expired while the character was offline is reported after the login.
  • Not tested with the original 1.04d client, and the personal store wasn't tried in game (it's covered by the tests).

Notes

  • Open question from Items which expire, to sell the time-limited cash shop products #1525, not changed here: a pet loses durability on every hit the player takes, also when it's expired and still equipped, and a pet which can't be trained is destroyed at durability 0 without a message. That's the existing behaviour, so a rented pet can also end by its durability instead of its time. If that isn't wanted, time-limited items (or only the expired ones) could be exempted from the durability loss; I'd do that in a follow-up.
  • GoblinPointsForPlayTimePlugIn keeps its next check in one field too, so with several game servers in one process the first one takes the check of the others. Not changed here; I can send a separate PR.
  • The date field of the item editor shows the stored UTC date, which is easy to confuse with the local time.
  • Building the packets project regenerates three docs which are already out of date on master (C1-11-ObjectHit*_by-server.md, C1-48-ShowEffect_by-server.md); I left them out of this PR.

An item gets an expiration timestamp, Item.ExpiresAt (UTC), which is null for
a permanent item. Until then, a time-limited item works like a normal one; once
expired, it stays in the inventory without effect.

ItemDefinition.IsSellableToNpcWhenExpired tells whether an expired item of the
kind can be sold to an NPC merchant although it isn't sellable otherwise, like
the items which are rented in the cash shop. CanBeDisposedOfWhenExpired
combines it with IsDroppable and IsSellableToNpc: an item which allows none of
them would stay in the inventory forever, so it must not become time-limited.

The migration adds both columns. The compiled models and the generated code of
the persistence model and the game configuration loader include them; the
loader generator now reads timestamp columns, because items are also loaded
with the configuration (merchant stores, quest rewards).
…urces

The Designer.cs files of PlugInResources and ItemPriceDefinitionNames had entries
appended by hand, out of the generator's order and with a different format, and
some keys of the .resx were missing. They are regenerated from the unchanged
.resx files with the StronglyTypedResourceBuilder, like Visual Studio's
PublicResXFileCodeGenerator does, so the next change of the resources only adds
its own entries.
…nt's price

The client lets the items which are rented in the cash shop (pets, transformation
rings, the rings and necklaces of the shop, the small wings and capes) be sold to
an NPC only once they expired (sellableWhenRentalExpired). ItemRules sets
IsSellableToNpcWhenExpired on them.

For these items the client shows a small fixed selling price: 1000 zen, 2000 for
the Skeleton pet and ring, 80 for the small wings and capes. Before, the server
priced them like accessories and paid 33 zen. Three price definitions give the
same prices: a third of a fixed buying price, rounded to tens, without a
reduction by the durability. They are appended to the price definitions, so the
numbers of the existing ones don't change.

The mandatory update sets the flag on existing configurations and assigns the
prices to the items which still have the price of the accessories; a price which
a server owner chose is kept.

The frozen copy of the item formulas test gets the same prices, as its remarks
ask for an intentional change. The golden master of the price rules, whose
legacy calculator must not change, leaves out the items of the new price
definitions.
Like the designers of the initialization resources, the Designer.cs of the admin
panel resources drifted from its .resx (entries out of the generator's order).
It's regenerated from the unchanged .resx, so the next change of the resources
only adds its own entries.
A time-limited product of the cash shop is delivered as items which expire after
the product's duration, counted from the moment the player uses it from the
cash shop storage, so a purchase or gift waiting in the storage doesn't lose
time. Every purchase delivers new items; items with different expirations don't
stack.

Only items which are worn can expire (CanBeTimeLimited): their effect lasts while
they are equipped. A consumable item with a duration, like a seal, would need an
effect which lasts as long as the product, which isn't supported, so these
products stay refused. So does an item which a player couldn't drop or sell once
it expired, because it would stay in the inventory forever.

A new configuration has the packages of the pets, transformation rings, rings,
necklaces and small wings for sale (104 instead of 62 packages); bundles which
also contain time-limited seals or scrolls stay not for sale. The mandatory
update of the rented items puts the same packages on sale in an existing
configuration which uses the client's script.

The catalog check of the admin panel reports a time-limited product only when
its item can't expire, and says why.
The Designer.cs files of PlayerMessage and PlugInResources drifted from their
.resx files (entries out of the generator's order). They are regenerated from
the unchanged .resx files, so the next change of the resources only adds its
own entries.
An expired time-limited item has no power-ups and doesn't count for a set bonus,
like an item without durability. So it has no effect from the start when it
expired while the player was offline.

The new periodic ItemExpirationPlugIn handles the items which expire while the
player is online: an equipped item stays in its slot, but its power-ups are
created again, which removes its effect (and with it e.g. the transformation of
a ring or the flight of wings); the client gets the item again, and the player
is told that it expired. An item which expired while the player was offline is
reported at the first check after the login. Nothing is deleted: the player
sells or drops the expired item.

One check for all players runs every CheckInterval (one minute by default),
instead of a timer per player, which would have to be updated with every change
of the inventory. The plugin is active by default, because without it the
equipped items wouldn't stop working until the next login.
Besides the power-ups, some effects of an equipped item are taken from the item
directly: the skill of an item with a skill, the pet of the offline leveling, the
Fenrir which the offline combat checks, and the mount which the Crywolf altar
checks. Item.HasEffect (durability left and not expired) is used for all of them,
so an expired time-limited item has none of these effects either. When the
item expires while it's equipped, the skill list removes the skill like for an
item without durability.
A time-limited item, valid or expired, can't be moved into another storage than
the inventory: not into the vault, a trade, a personal store or a crafting
window. Its remaining time mustn't pass to another player, and it's no crafting
ingredient, because some crafting rates depend on the item price. The trade
and the purchase from a personal store check it again, in case such an item got
there anyway.

A valid time-limited item can't be dropped or sold to an NPC. Once it expired,
the player gets rid of it by dropping it, if its item definition allows it, or
by selling it to an NPC, if IsSellableToNpcWhenExpired or IsSellableToNpc
allows it. An expired item can't be equipped, like in the client.

A time-limited item can't be repaired, and it doesn't wear out with time; its
period ends it instead.
Like the other designers, the Designer.cs of the shared web resources drifted
from its .resx (entries out of the generator's order, some keys missing). It's
regenerated from the unchanged .resx, so the next change of the resources only
adds its own entries.
The item editor shows whether a worn item is time-limited and when it expires
(UTC). Switching the time limit on lets the item expire in one day.

An item which couldn't be disposed of once it expired, because it can't be
dropped or sold to an NPC, can't be made time-limited: the editor refuses to
save it, like the server doesn't deliver such an item from the cash shop. A test
of the initialization checks that every time-limited item which a new
configuration sells has a way out, and that the items which the client doesn't
let drop while they are rented can be sold once they expired.
Like the other designers, the Designer.cs of the game server's PlugInResources
drifted from its .resx. It's regenerated from the unchanged .resx, so the next
change of the resources only adds its own entries.
The season 6 client reads the period state of an item from byte 5: 0x02 marks a
time-limited item and 0x04 an expired one. The item serializer sets them; the
deserialization ignores them, so the client never decides an expiration.

The client stores the expiration date per inventory slot (D2 12, after the count
D2 11) and shows the time left in the tooltip. The new IItemExpirationViewPlugIn
sends the dates after the inventory list, and the date of a single item whenever
the client creates the item again: when it appears, is moved within the
inventory, is updated (e.g. when it expires), or a move fails. The date follows
the item, because the client takes it for the item which is in the slot when
the packet arrives.

The view plugin exists for clients from season 6 on, so the older clients don't
get these packets.
The extended item format of the open source client had no free bit for the
period state: the 8 option flags are in use. The level byte only needs 6 bits
(item levels go up to 15, trainable pets are sent with level 0), so its two
highest bits carry it: 0x40 for a time-limited item and 0x80 for an expired
one, like the bits 0x02 and 0x04 of byte 5 in the format of the original client.
The level is read from the lower 6 bits, and the deserialization ignores the
flags.

The expiration date itself comes with D2 12, like for the original client.
The design document describes the time-limited items: which items can be
time-limited, how their effect, expiry, rules, prices and protocol work, and the
update for existing databases. The roadmap marks the item expiration as done for
worn items, and the numbers of buyable packages are the current ones.

The cash shop page of the documentation website tells players and operators how
time-limited items behave, and the accounts page describes the expiration
fields of the item editor.
An expired time-limited pet stays in the pet slot of its owner, but it has no
effect, so it doesn't accompany its owner anymore: it's left out of the
appearance which other players get, and when it expires, they get the change as
if the pet was taken off (both for the original and the open source client).
Not only an expired pet: no expired time-limited item, in any slot, is part of
the appearance which other players see, so e.g. expired wings aren't shown
either. The owner looks as if the slot was empty, because the item has no effect.
As suggested in the review of MUnique#1525, the flag is called IsSellableWhenExpired:
an expired time-limited item can be sold, which only an NPC merchant buys anyway,
because a time-limited item can't be offered in a personal store. The migration
of the item expiration is changed in place, because it isn't released yet.
One plugin instance serves all game servers of a process, because the
plug-in manager is a singleton. With a single time for the next check,
the game server which ran the task first took the check of the others,
so items on the other game servers expired minutes late. The next check
is now kept per game context.
@codacy-production

codacy-production Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 101 complexity

Metric Results
Complexity 101

View in Codacy

NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.

Found by Codacy: the Apply overloads of ItemRules weren't adjacent, and some
new lines of the cash shop docs were longer than 80 characters.
Conflicts: the appearance plugins (master renamed item to changedItem; the
expired check is kept), the plugin resources (both sides added entries; the
designers are regenerated from the merged .resx files).
The analyzers of master (SA1500, SA1201, SA1504) found them in the Fenrir check
of the offline combat handler, the order of the item price definitions and the
accessors of the item editor.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Items which expire, to sell the time-limited cash shop products

1 participant