feat(items): add the lucky coin exchange of delgado

docs-website/docs/server-features/lucky-coins.md

@@ -0,0 +1,38 @@
+---
+title: Lucky coins
+sidebar_label: Lucky coins
+sidebar_position: 6
+description: Registering lucky coins at Delgado and exchanging them for items.
+---
+
+Delgado, an NPC in Devias, collects lucky coins. When a player talks to him,
+the game client offers two dialogs:
+
+* **Lucky coin registration**: each click registers one lucky coin of the
+  inventory. The coin is used up, and the count of the registered coins of the
+  character goes up. The dialog shows this count. In the original game, the
+  registered coins took part in a lottery, which isn't part of the server; the
+  count is kept in the character attribute *Registered Lucky Coins*, so that a
+  game master can see it.
+* **Lucky coin exchange**: the player exchanges 10, 20 or 30 coins for an item.
+  The coins can be spread over several stacks. When the inventory has no space
+  for the item, the coins are kept.
+
+Lucky coins are stacked, up to 255 coins per stack. They don't drop from
+monsters by default; add them to a drop item group to make them obtainable
+(see [Item drops](../admin-panel/item-drops.md)).
+
+## Settings
+
+The plugin **Lucky coin event** is configured on the
+[Plugins](../admin-panel/plugins.md) page. When it's deactivated, the coins
+can't be registered or exchanged.
+
+* **Rewards** (default: none): the possible items of the exchange. Each reward
+  has the count of coins (10, 20 or 30), the group and number of the item and
+  its level. One of the rewards for the exchanged count of coins is chosen
+  randomly.
+
+The rewards of the original game are not known, so there are none by default.
+Without a reward for a count of coins, the exchange of that count is refused,
+and the client says that there are not enough coins.

docs-website/sidebars.js

@@ -68,6 +68,7 @@ const sidebars = {
         "server-features/cash-shop",
         "server-features/discord",
         "server-features/player-shop-currencies",
+        "server-features/lucky-coins",
         "server-features/waiting-items",
       ],
     },

docs/Packets/C1-BF-0B-LuckyCoinCountResponse_by-server.md

@@ -0,0 +1,19 @@
+# C1 BF 0B - LuckyCoinCountResponse (by server)
+
+## Is sent when
+
+After the player opened the lucky coin registration dialog of the NPC Delgado, which requests the count of the registered coins.
+
+## Causes the following actions on the client side
+
+The client shows the count of the registered lucky coins in the dialog.
+
+## Structure
+
+| Index | Length | Data Type | Value | Description |
+|-------|--------|-----------|-------|-------------|
+| 0 | 1 |   Byte   | 0xC1  | [Packet type](PacketTypes.md) |
+| 1 | 1 |    Byte   |   8   | Packet header - length of the packet |
+| 2 | 1 |    Byte   | 0xBF  | Packet header - packet type identifier |
+| 3 | 1 |    Byte   | 0x0B  | Packet header - sub packet type identifier |
+| 4 | 4 | IntegerLittleEndian |  | Count |

docs/Packets/C1-BF-0C-LuckyCoinRegistrationResponse_by-server.md

@@ -0,0 +1,30 @@
+# C1 BF 0C - LuckyCoinRegistrationResponse (by server)
+
+## Is sent when
+
+After the player requested to register a lucky coin at the NPC Delgado.
+
+## Causes the following actions on the client side
+
+The client unlocks the register button. When the coin was registered, it shows the new count of the registered coins; otherwise, it shows a message.
+
+## Structure
+
+| Index | Length | Data Type | Value | Description |
+|-------|--------|-----------|-------|-------------|
+| 0 | 1 |   Byte   | 0xC1  | [Packet type](PacketTypes.md) |
+| 1 | 1 |    Byte   |   12   | Packet header - length of the packet |
+| 2 | 1 |    Byte   | 0xBF  | Packet header - packet type identifier |
+| 3 | 1 |    Byte   | 0x0C  | Packet header - sub packet type identifier |
+| 4 | 1 | LuckyCoinRegistrationResult |  | Result |
+| 8 | 4 | IntegerLittleEndian |  | Count |
+
+### LuckyCoinRegistrationResult Enum
+
+Defines the result of the lucky coin registration request.
+
+| Value | Name | Description |
+|-------|------|-------------|
+| 0 | NotEnoughItems | The player has no lucky coin in the inventory. |
+| 1 | Registered | The lucky coin was registered. |
+| 100 | AlreadyApplied | The account already applied, and it can only apply once. |

docs/Packets/C1-BF-0D-LuckyCoinExchangeResponse_by-server.md

@@ -0,0 +1,29 @@
+# C1 BF 0D - LuckyCoinExchangeResponse (by server)
+
+## Is sent when
+
+After the player requested to exchange lucky coins for an item at the NPC Delgado.
+
+## Causes the following actions on the client side
+
+The client unlocks the exchange buttons and shows a message about the result.
+
+## Structure
+
+| Index | Length | Data Type | Value | Description |
+|-------|--------|-----------|-------|-------------|
+| 0 | 1 |   Byte   | 0xC1  | [Packet type](PacketTypes.md) |
+| 1 | 1 |    Byte   |   5   | Packet header - length of the packet |
+| 2 | 1 |    Byte   | 0xBF  | Packet header - packet type identifier |
+| 3 | 1 |    Byte   | 0x0D  | Packet header - sub packet type identifier |
+| 4 | 1 | LuckyCoinExchangeResult |  | Result |
+
+### LuckyCoinExchangeResult Enum
+
+Defines the result of the lucky coin exchange request.
+
+| Value | Name | Description |
+|-------|------|-------------|
+| 0 | NotEnoughItems | The player doesn't have enough lucky coins in the inventory. |
+| 1 | Exchanged | The lucky coins were exchanged for an item. |
+| 2 | InventoryFull | The inventory has not enough space for the item. The client asks for a free space of 2 x 4. |

docs/Packets/ServerToClient.md

@@ -241,8 +241,11 @@
   * [C1 BF 08 - IllusionTempleHolyItemRelics (by server)](C1-BF-08-IllusionTempleHolyItemRelics_by-server.md)
   * [C1 BF 09 - IllusionTempleEventState (by server)](C1-BF-09-IllusionTempleEventState_by-server.md)
   * [C1 BF 0A - ChainLightningHitInfo (by server)](C1-BF-0A-ChainLightningHitInfo_by-server.md)
+  * [C1 BF 0B - LuckyCoinCountResponse (by server)](C1-BF-0B-LuckyCoinCountResponse_by-server.md)
   * [C1 BF 0B - LuckyCoinCount (by server)](C1-BF-0B-LuckyCoinCount_by-server.md)
+  * [C1 BF 0C - LuckyCoinRegistrationResponse (by server)](C1-BF-0C-LuckyCoinRegistrationResponse_by-server.md)
   * [C1 BF 0C - LuckyCoinRegistrationResult (by server)](C1-BF-0C-LuckyCoinRegistrationResult_by-server.md)
+  * [C1 BF 0D - LuckyCoinExchangeResponse (by server)](C1-BF-0D-LuckyCoinExchangeResponse_by-server.md)
   * [C1 BF 0D - LuckyCoinExchangeResult (by server)](C1-BF-0D-LuckyCoinExchangeResult_by-server.md)
   * [C1 BF 0E - DoppelgangerEnterResult (by server)](C1-BF-0E-DoppelgangerEnterResult_by-server.md)
   * [C1 BF 0F - DoppelgangerMonsterPosition (by server)](C1-BF-0F-DoppelgangerMonsterPosition_by-server.md)

docs/Progress.md

@@ -87,6 +87,7 @@ complexity and effort). Complexity 0 means we wont implement it.
 | *RequestGuildMarkCastleOwner* | 0xB902            | 100%     | 1          | Entering the hunting zone (0xB905) is implemented |
 | *JewelMix*                    | 0xBC              | 100%     | 4          |                                               |
 | *CrywolfGroup*              | 0xBD              | 100%     | 10         |                                               |
+| *LuckyCoin* | 0xBF0B-0xBF0D | 100% | 3 | Registration and exchange at Delgado |
 | *IllusionTempleGroup*       | 0xBF              | 100%     | 10         | Team-based PvP mini game: relic pickup/delivery, scoring, skill points, special skills, rewards |
 | FriendListRequest           | 0xC0              | 0%       | 0          | Not needed, friend list is sent automatically |
 | *FriendAdd*                   | 0xC1              | 100%     | 2          |                                               |

src/GameLogic/Attributes/Stats.cs

@@ -163,6 +163,11 @@ public class Stats
     /// </summary>
     public static AttributeDefinition TotalRegisteredRenas { get; } = new(new Guid("56C2D3B4-4F5A-6B7C-8D9E-0F1A2B3C4D5E"), "Total Registered Renas", "Total registered items (all-time counter)");
 
+    /// <summary>
+    /// Gets the attribute definition of the count of the lucky coins which a character registered at the NPC Delgado.
+    /// </summary>
+    public static AttributeDefinition RegisteredLuckyCoins { get; } = new(new Guid("7D4A0CDF-124F-4CFF-89FF-357A2001B041"), "Registered Lucky Coins", "The count of the lucky coins which were registered at the NPC Delgado.");
+
     /// <summary>
     /// Gets the zen amount rate attribute definition.
     /// </summary>

src/GameLogic/ItemConstants.cs

@@ -269,6 +269,11 @@ public class ItemConstants
     /// </summary>
     public static ItemIdentifier MoonstonePendant => new(38, 13);
 
+    /// <summary>
+    /// Gets the identifier for the lucky coin (group 14, number 100), which is registered and exchanged at the NPC Delgado.
+    /// </summary>
+    public static ItemIdentifier LuckyCoin => new(100, 14);
+
     /// <summary>
     /// Gets all scrolls.
     /// </summary>

src/GameLogic/LuckyCoins/LuckyCoinConfiguration.cs

@@ -0,0 +1,21 @@
+// <copyright file="LuckyCoinConfiguration.cs" company="MUnique">
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+// </copyright>
+
+namespace MUnique.OpenMU.GameLogic.LuckyCoins;
+
+/// <summary>
+/// The configuration of the lucky coin exchange at the NPC Delgado.
+/// </summary>
+public class LuckyCoinConfiguration
+{
+    /// <summary>
+    /// Gets or sets the possible rewards of the exchange. When a player exchanges coins,
+    /// one of the rewards for that count of coins is chosen randomly.
+    /// </summary>
+    /// <remarks>
+    /// The rewards of the original game are server data which isn't known, so there are none by default.
+    /// Without a reward for a count of coins, the exchange of that count isn't possible.
+    /// </remarks>
+    public IList<LuckyCoinReward> Rewards { get; set; } = new List<LuckyCoinReward>();
+}

src/GameLogic/LuckyCoins/LuckyCoinFeaturePlugIn.cs

@@ -0,0 +1,39 @@
+// <copyright file="LuckyCoinFeaturePlugIn.cs" company="MUnique">
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+// </copyright>
+
+namespace MUnique.OpenMU.GameLogic.LuckyCoins;
+
+using System.Runtime.InteropServices;
+using MUnique.OpenMU.PlugIns;
+
+/// <summary>
+/// The lucky coin event of the NPC Delgado: players register lucky coins, or exchange them for items.
+/// When it's deactivated, the players can't register or exchange lucky coins.
+/// </summary>
+[PlugIn]
+[Display(Name = nameof(PlugInResources.LuckyCoinFeaturePlugIn_Name), Description = nameof(PlugInResources.LuckyCoinFeaturePlugIn_Description), ResourceType = typeof(PlugInResources))]
+[Guid("3D6F9337-6A79-4F89-B995-4B7E722E63D1")]
+public class LuckyCoinFeaturePlugIn : IFeaturePlugIn, ISupportCustomConfiguration<LuckyCoinConfiguration>, ISupportDefaultCustomConfiguration
+{
+    /// <inheritdoc />
+    public LuckyCoinConfiguration? Configuration { get; set; }
+
+    /// <summary>
+    /// Gets the configuration of the lucky coin event of the game context.
+    /// </summary>
+    /// <param name="gameContext">The game context.</param>
+    /// <returns>The configuration; <c>null</c>, if the lucky coin event is deactivated.</returns>
+    public static LuckyCoinConfiguration? GetActiveConfiguration(IGameContext gameContext)
+    {
+        return gameContext.FeaturePlugIns.GetPlugIn<LuckyCoinFeaturePlugIn>() is { } plugIn
+            ? plugIn.Configuration ?? new LuckyCoinConfiguration()
+            : null;
+    }
+
+    /// <inheritdoc />
+    public object CreateDefaultConfig()
+    {
+        return new LuckyCoinConfiguration();
+    }
+}

src/GameLogic/LuckyCoins/LuckyCoinReward.cs

@@ -0,0 +1,38 @@
+// <copyright file="LuckyCoinReward.cs" company="MUnique">
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+// </copyright>
+
+namespace MUnique.OpenMU.GameLogic.LuckyCoins;
+
+/// <summary>
+/// A possible reward of the lucky coin exchange at the NPC Delgado.
+/// </summary>
+public class LuckyCoinReward
+{
+    /// <summary>
+    /// Gets or sets the count of the lucky coins which are exchanged for this reward.
+    /// The game client offers to exchange 10, 20 or 30 coins.
+    /// </summary>
+    public int CoinCount { get; set; }
+
+    /// <summary>
+    /// Gets or sets the group of the reward item.
+    /// </summary>
+    public byte ItemGroup { get; set; }
+
+    /// <summary>
+    /// Gets or sets the number of the reward item.
+    /// </summary>
+    public short ItemNumber { get; set; }
+
+    /// <summary>
+    /// Gets or sets the level of the reward item.
+    /// </summary>
+    public byte ItemLevel { get; set; }
+
+    /// <inheritdoc />
+    public override string ToString()
+    {
+        return $"{this.CoinCount} coins: {this.ItemGroup}/{this.ItemNumber} +{this.ItemLevel}";
+    }
+}