Repository navigation
feat(items): items which expire, to sell the time-limited cash shop products - #1548
Open
pllanosclaria wants to merge 22 commits into
Open
pllanosclaria wants to merge 22 commits into
pllanosclaria wants to merge 22 commits into
Conversation
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.
This was referenced Nov 18, 2026
Up to standards ✅🟢 Issues
|
| Metric | Results |
|---|---|
| Complexity | 101 |
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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) andItemDefinition.IsSellableWhenExpired, the client'ssellableWhenRentalExpired(25 items). MigrationAddItemExpiration, with the compiled models and the generated loader and converter code. The loader generator got thetimestamp with time zonetype. Items with different expirations don't stack.Configuration:
ItemRulessetsIsSellableWhenExpiredlike 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 updateAddRentalItemRulesUpdatePlugIn("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:
InventoryProductDeliverysetsExpiresAt = now + Durationwhen the player uses the product from the cash shop storage, so a gift waiting in the storage doesn't lose time.CanBeDeliveredaccepts 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, oneIPeriodicTaskPlugInwith its ownCheckInterval(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.
IsDroppableIsSellableWhenExpiredorIsSellableToNpcThe trade and the personal store also check it when the trade is completed or the item bought.
Protocol: original client: bits
0x02(period) and0x04(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 with0x3F). After the inventory listD2 11and oneD2 12per time-limited item, and aD2 12after 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.mdand 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 regenerateDesigner.csfiles which had drifted from their unchanged.resxfiles 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
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),ItemExpirationRemoteViewTestsandItemSerializerTests(the bits andD2 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),ItemViewModelExpirationTestsandCashShopCatalogPageTests(admin panel).ItemPriceCalculatorGoldenMasterTestand the legacy calculator of the initialization tests: the rented items are left out of the comparison on purpose, because their prices change.ItemFormulasEqualTodayTestcovers the new prices.dotnet build src/MUnique.OpenMU.sln, thendotnet 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.Notes
GoblinPointsForPlayTimePlugInkeeps 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.C1-11-ObjectHit*_by-server.md,C1-48-ShowEffect_by-server.md); I left them out of this PR.