Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions docs-website/docs/server-features/inventory-charms.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
---
title: Figurines and charms
sidebar_label: Figurines and charms
description: Figurines and charms give a bonus while used in the inventory.
---

The figurines and charms are items of the in-game shop. They are not worn in
an equipment slot. Instead, the player right clicks them inside the inventory
to use them, and the bonus applies as long as they stay in use there. Another
right click stops the use.

| Item | Number | Bonus |
| ------------------------ | ------ | ------------------------------ |
| Hawk Figurine | 13/128 | +10% critical damage chance |
| Goat Figurine | 13/129 | +10% excellent damage chance |
| Oak Charm | 13/130 | +50 maximum health |
| Maple Charm | 13/131 | +50 maximum mana |
| Golden Oak Charm | 13/132 | +100 health, +500 shield |
| Golden Maple Charm | 13/133 | +150 mana, +50 ability (AG) |

The values are the ones which the game client shows in the item tooltip. For
the Golden Oak Charm, the Season 6 Episode 3 client shows +100 health and +500
shield, which matches its `ItemAddOption.bmd`; older clients showed +150 and
+50. The values are stored as power-ups of the item definitions, so they can
be changed in the admin panel.

## Rules

* Only one item of the same kind can be in use at the same time. Using a
second one is refused with a message. The Hawk and Goat Figurines, the Oak
and Golden Oak Charms, and the Maple and Golden Maple Charms count as the
same kind: they form an exclusive group in the configuration.
* The item keeps its state when it is moved inside the inventory.
* When the item leaves the inventory, for example when it is dropped or moved
into the vault, it is no longer in use, and the bonus is removed. This also
happens when the item was removed from the configuration in the meantime.
* Using an item which is already in use keeps its bonus, so the current
health, mana and so on stay as they are.
* Like in the original game, the state is stored in the durability of the
item: 254 means in use, 255 means not in use. A new item starts with 255
when it is added to the inventory. The item definitions have a durability
of 1, so the items are not stackable.

## Configuration

The *Items used inside the inventory* feature plugin defines which items can
be used inside the inventory. By default, these are the items 13/128 to
13/134. Each item can have an exclusive group: only one item of a group can
be in use at the same time. By default, the figurines are group 1, the oak
charms group 2 and the maple charms group 3. It also defines the
durability values of an item which is in use (254) and not in use (255).
They have to match the game client. When the plugin is deactivated, no item
can be used this way.

## Update of existing databases

The update *Add the figurines and charms* adds the items, and links the
products of the cash shop to them. Their packages were not for sale before,
because their products had no item. The update leaves them that way, so the
administrator can put them on sale in the admin panel.

## Protocol

The client sends the request `C1 BF 20` with the inventory slot and the
requested state. The server answers with the same packet and the new state of
the item.

:::note
The Worn Horseshoe (13/134) is not added yet, because there is no attribute
for the item drop rate yet.
:::
1 change: 1 addition & 0 deletions docs-website/sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ const sidebars = {
"server-features/anti-cheat",
"server-features/test-actors",
"server-features/gens",
"server-features/inventory-charms",
"server-features/cash-shop",
"server-features/discord",
"server-features/player-shop-currencies",
Expand Down
1 change: 1 addition & 0 deletions docs/Progress.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ complexity and effort). Complexity 0 means we wont implement it.
| *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 |
| *InventoryItemEquip* | 0xBF20 | 100% | 2 | Using figurines and charms inside the inventory |
| FriendListRequest | 0xC0 | 0% | 0 | Not needed, friend list is sent automatically |
| *FriendAdd* | 0xC1 | 100% | 2 | |
| *WaitFriendAdd* | 0xC2 | 100% | 2 | |
Expand Down
6 changes: 5 additions & 1 deletion src/GameLogic/IItemPowerUpFactory.cs
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,12 @@ public interface IItemPowerUpFactory
/// </summary>
/// <param name="item">The item.</param>
/// <param name="attributeSystem">The attribute system of the player who equipped the item.</param>
/// <param name="isInUseInsideInventory">
/// If set to <c>true</c>, the item isn't equipped, but in use inside the inventory, see <see cref="InventoryItemUseConfiguration"/>.
/// Otherwise, an item which isn't equipped has no power ups.
/// </param>
/// <returns>The created power ups.</returns>
IEnumerable<PowerUpWrapper> GetPowerUps(Item item, AttributeSystem attributeSystem);
IEnumerable<PowerUpWrapper> GetPowerUps(Item item, AttributeSystem attributeSystem, bool isInUseInsideInventory = false);

/// <summary>
/// Gets the set power ups, which are created for existing <see cref="ItemSetGroup"/>s in the equipped items.
Expand Down
113 changes: 113 additions & 0 deletions src/GameLogic/InventoryItemUseConfiguration.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
// <copyright file="InventoryItemUseConfiguration.cs" company="MUnique">
// Licensed under the MIT License. See LICENSE file in the project root for full license information.
// </copyright>

namespace MUnique.OpenMU.GameLogic;

using MUnique.OpenMU.DataModel.Composition;
using MUnique.OpenMU.DataModel.Configuration.Items;

/// <summary>
/// The configuration of the items which are used inside the inventory, like the figurines and charms.
/// </summary>
public class InventoryItemUseConfiguration
{
/// <summary>
/// The default of <see cref="InUseDurability"/>, which is the value the game client expects.
/// </summary>
private const byte DefaultInUseDurability = 254;

/// <summary>
/// The default of <see cref="NotInUseDurability"/>, which is the value the game client expects.
/// </summary>
private const byte DefaultNotInUseDurability = 255;

/// <summary>
/// Gets or sets the items which are used inside the inventory instead of being equipped.
/// </summary>
/// <remarks>
/// By default, these are the figurines (group 13, number 128 and 129), the charms (130 to 133)
/// and the worn horseshoe (134), which the game client requests to use with a right click in the inventory.
/// The figurines, the oak charms and the maple charms each form an exclusive group,
/// see <see cref="InventoryUsedItemIdentifier.ExclusiveGroup"/>.
/// </remarks>
[MemberOfAggregate]
[ScaffoldColumn(true)]
[Display(ResourceType = typeof(PlugInResources), Name = nameof(PlugInResources.InventoryItemUseConfiguration_Items_Name), Description = nameof(PlugInResources.InventoryItemUseConfiguration_Items_Description))]
public ICollection<InventoryUsedItemIdentifier> Items { get; set; } = CreateDefaultItems();

/// <summary>
/// Gets or sets the durability of an item which is in use.
/// </summary>
/// <remarks>
/// Like in the game client, the durability of such an item tells whether it's in use,
/// so this value has to match the client.
/// </remarks>
[Display(ResourceType = typeof(PlugInResources), Name = nameof(PlugInResources.InventoryItemUseConfiguration_InUseDurability_Name), Description = nameof(PlugInResources.InventoryItemUseConfiguration_InUseDurability_Description))]
public byte InUseDurability { get; set; } = DefaultInUseDurability;
Comment thread
icheat2win marked this conversation as resolved.
Resolved

/// <summary>
/// Gets or sets the durability of an item which isn't in use.
/// </summary>
/// <remarks>
/// Like in the game client, the durability of such an item tells whether it's in use,
/// so this value has to match the client. A new item starts with it.
/// </remarks>
[Display(ResourceType = typeof(PlugInResources), Name = nameof(PlugInResources.InventoryItemUseConfiguration_NotInUseDurability_Name), Description = nameof(PlugInResources.InventoryItemUseConfiguration_NotInUseDurability_Description))]
public byte NotInUseDurability { get; set; } = DefaultNotInUseDurability;

/// <summary>
/// Determines whether the item definition belongs to an item which is used inside the inventory.
/// </summary>
/// <param name="definition">The item definition.</param>
/// <returns><c>true</c>, if items of this definition are used inside the inventory; otherwise, <c>false</c>.</returns>
public bool Contains(ItemDefinition definition)
{
return this.Items.Any(id => id.Group == definition.Group && id.Number == definition.Number);
}

/// <summary>
/// Determines whether items of the two definitions exclude each other, so that only one of them can be in use
/// at the same time. That's the case for the same definition, and for definitions of the same exclusive group.
/// </summary>
/// <param name="definition">The item definition.</param>
/// <param name="otherDefinition">The other item definition.</param>
/// <returns><c>true</c>, if only one of the items can be in use at the same time; otherwise, <c>false</c>.</returns>
public bool AreExclusive(ItemDefinition definition, ItemDefinition otherDefinition)
{
if (definition == otherDefinition)
{
return true;
}

var group = this.GetExclusiveGroup(definition);
return group != 0 && group == this.GetExclusiveGroup(otherDefinition);
}

private static ICollection<InventoryUsedItemIdentifier> CreateDefaultItems()
{
const byte figurines = 1;
const byte oakCharms = 2;
const byte mapleCharms = 3;
return
[
CreateItem(128, figurines), // Hawk Figurine
CreateItem(129, figurines), // Goat Figurine
CreateItem(130, oakCharms), // Oak Charm
CreateItem(131, mapleCharms), // Maple Charm
CreateItem(132, oakCharms), // Golden Oak Charm
CreateItem(133, mapleCharms), // Golden Maple Charm
CreateItem(134, 0), // Worn Horseshoe
];

static InventoryUsedItemIdentifier CreateItem(short number, byte exclusiveGroup)
{
return new InventoryUsedItemIdentifier { Group = 13, Number = number, ExclusiveGroup = exclusiveGroup };
}
}

private byte GetExclusiveGroup(ItemDefinition definition)
{
return this.Items.FirstOrDefault(id => id.Group == definition.Group && id.Number == definition.Number)?.ExclusiveGroup ?? 0;
}
}
40 changes: 40 additions & 0 deletions src/GameLogic/InventoryItemUseFeaturePlugIn.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
// <copyright file="InventoryItemUseFeaturePlugIn.cs" company="MUnique">
// Licensed under the MIT License. See LICENSE file in the project root for full license information.
// </copyright>

namespace MUnique.OpenMU.GameLogic;

using System.Runtime.InteropServices;
using MUnique.OpenMU.PlugIns;

/// <summary>
/// The use of items inside the inventory, like the figurines and charms.
/// While such an item is in use, its power-ups apply, although it isn't equipped.
/// When it's deactivated, no item can be used inside the inventory.
/// </summary>
[PlugIn]
[Display(Name = nameof(PlugInResources.InventoryItemUseFeaturePlugIn_Name), Description = nameof(PlugInResources.InventoryItemUseFeaturePlugIn_Description), ResourceType = typeof(PlugInResources))]
[Guid("0C9C3D52-7B0E-4E55-9D1B-2E6A35C4F1A8")]
public class InventoryItemUseFeaturePlugIn : IFeaturePlugIn, ISupportCustomConfiguration<InventoryItemUseConfiguration>, ISupportDefaultCustomConfiguration
{
/// <inheritdoc />
public InventoryItemUseConfiguration? Configuration { get; set; }

/// <summary>
/// Gets the configuration of the items which are used inside the inventory.
/// </summary>
/// <param name="gameContext">The game context.</param>
/// <returns>The configuration; <c>null</c>, if the feature is deactivated.</returns>
public static InventoryItemUseConfiguration? GetActiveConfiguration(IGameContext gameContext)
{
return gameContext.FeaturePlugIns.GetPlugIn<InventoryItemUseFeaturePlugIn>() is { } plugIn
? plugIn.Configuration ?? new InventoryItemUseConfiguration()
: null;
}

/// <inheritdoc />
public object CreateDefaultConfig()
{
return new InventoryItemUseConfiguration();
}
}
Loading
Loading