Skip to content
Closed
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
23 changes: 23 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,28 @@
## [Unreleased]

### Items API

New Items API replaces `ItemsRegistry` ([#95](https://github.com/EndlessCodeGroup/Mimic/issues/95)).
See [Items](https://github.com/EndlessCodeGroup/Mimic/blob/develop/mimic-bukkit-api/README.md#items) for details and examples.

- `Mimic.getItems()` creates and identifies items, `Mimic.registerItemProvider()` makes a plugin's items available.
Requires Mimic API level `MimicApiLevel.VERSION_0_11`. The API is stable.
- Item IDs are `Key`s with a required namespace: `minecraft:diamond`, `craftengine:default/palm_log`.
There is no search over all providers in the new API.
- An item belongs to the provider with the highest priority recognizing it,
so a custom item no longer matches the ID of its vanilla base ([#86](https://github.com/EndlessCodeGroup/Mimic/issues/86)).
- Items can be created for a player, MMOItems and CraftEngine use it.
- The payload is a `String` in the format of the item's provider. An item is not created if its payload is invalid.
- `ItemsRegistry` API is deprecated but keeps working, every items registry is available via Items API.
`Mimic.getItemsRegistry()` shows items of all item providers and still accepts IDs without a namespace.
- Items registries' own `isSameItem` is used again ([#85](https://github.com/EndlessCodeGroup/Mimic/issues/85)).
- **Changed:** MMOItems IDs include the item type: `mmoitems:sword/excalibur` instead of `mmoitems:excalibur` ([#87](https://github.com/EndlessCodeGroup/Mimic/issues/87)).
`ItemsRegistry` API still accepts IDs without the type if only one type has the item, but logs a warning.
- **Changed:** `ItemsRegistry.getItem` returns `null` if an item provider can't use the payload. Previously, the payload was ignored.
- **Changed:** Empty stacks have no ID, and `minecraft:air` is not an item.
- Config option `disabled-items-registries` is renamed to `disabled-item-providers`, the old value is moved automatically.
- `/mimic items` requires item IDs with a namespace and gives items created for the target player.

### Blocks API

New Blocks API replaces the experimental `BlockRegistry` ([#96](https://github.com/EndlessCodeGroup/Mimic/issues/96)).
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@ With Mimic, you don't need to download all RPG plugins and write specific code f
- [ClassSystem] *(deprecated, use [Classes])* - API to work with player's classes.
- [Resources] - API to work with player's resources: mana, stamina and similar. Read them, take costs, give them back.
- [PlayerInventory] *(experimental)* - API to access player's inventories content.
- [ItemsRegistry] - API adding the possibility to create and validate custom items created with plugins.
- [Items] - API to create and identify vanilla items and custom items created with plugins.
- [ItemsRegistry] *(deprecated, use [Items])* - API to create and validate custom items created with plugins.
- [Blocks] - API to identify, set and break vanilla blocks and custom blocks created with plugins.

### Implementations
Expand Down Expand Up @@ -97,5 +98,6 @@ Please make sure to update tests as appropriate.
[ClassSystem]: mimic-api/src/main/kotlin/classes/ClassSystem.kt
[Resources]: mimic-bukkit-api/src/main/kotlin/resources/Resources.kt
[PlayerInventory]: mimic-api/src/main/kotlin/inventory/PlayerInventory.kt
[Items]: mimic-bukkit-api/src/main/kotlin/items/Items.kt
[ItemsRegistry]: mimic-api/src/main/kotlin/items/ItemsRegistry.kt
[Blocks]: mimic-bukkit-api/src/main/kotlin/blocks/Blocks.kt
1 change: 1 addition & 0 deletions mimic-api/src/main/kotlin/MimicApiLevel.kt
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ public object MimicApiLevel {
/**
* # Version 0.11
* - Blocks API, experimental BlockRegistry API is removed
* - Items API, ItemsRegistry API is deprecated
*/
public const val VERSION_0_11: Int = 7

Expand Down
1 change: 1 addition & 0 deletions mimic-api/src/main/kotlin/items/ItemsRegistry.kt
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ import ru.endlesscode.mimic.MimicService
* Mapping them to the plugin's own IDs is up to the implementation: `itemsadder:ruby_sword` -> `itemsadder/ruby_sword`.
* Invalid IDs are ignored.
*/
@Deprecated("Use Items API from mimic-bukkit-api instead, it identifies items by their owner and creates them for a player.")
public interface ItemsRegistry<ItemStackT : Any> : MimicService {

/** Returns all known item IDs. */
Expand Down
160 changes: 141 additions & 19 deletions mimic-bukkit-api/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ Available services:
- [ClassProvider]
- [BukkitClassSystem.Provider] *(deprecated, use [ClassProvider])*
- [BukkitPlayerInventory.Provider] *(experimental)*
- [BukkitItemsRegistry]
- [ItemProvider]
- [BukkitItemsRegistry] *(deprecated, use [ItemProvider])*
- [BlockProvider]

> Experimental APIs may change in future versions.
Expand Down Expand Up @@ -59,7 +60,7 @@ Levels levels = mimic.getLevels();
Classes classes = mimic.getClasses();
Resources resources = mimic.getResources();
BukkitPlayerInventory inventory = mimic.getPlayerInventory(player);
BukkitItemsRegistry itemsRegistry = mimic.getItemsRegistry();
Items items = mimic.getItems();
Blocks blocks = mimic.getBlocks();
```

Expand All @@ -77,10 +78,9 @@ CharacterClass playerClass = classes.getPrimaryClass(player);
// See the "Resources" section below for details
boolean isPaid = resources.take(player, Key.key("mmocore:mana"), 20.0);

// ItemsRegistry is not related to player so it can be used without provider
ItemStack stick = itemsRegistry.getItem("minecraft:stick");
boolean isPalmLogInHand = itemsRegistry.isSameItem(player.getInventory().getItemInMainHand(), "craftengine:default/palm_log");
boolean isPalmLogExists = itemsRegistry.isItemExists("craftengine:default/palm_log");
// See the "Items" section below for details
ItemStack sword = items.createItem(Key.key("mmoitems:sword/excalibur"), 1, player, null);
boolean isSwordInHand = items.isItem(player.getInventory().getItemInMainHand(), Key.key("mmoitems:sword/excalibur"));

// See the "Blocks" section below for details
boolean isPalmLog = blocks.isBlock(block, Key.key("craftengine:default/palm_log"));
Expand All @@ -93,14 +93,15 @@ Mimic identifies items, blocks, level tracks, classes and resources by [resource
where the namespace is the ID of the plugin's implementation: `minecraft:acacia_boat`, `craftengine:default/palm_log`, `auraskills:mining`.
The path may contain lowercase letters, digits, `.`, `_`, `-` and `/`.

- **Items:** ID without namespace, or with the `mimic` namespace, is searched over all registries in order of priority.
- **Items:** the namespace is required, see [Item IDs](#item-ids).
- **Blocks:** the namespace is required, see [Block IDs](#block-ids).
- **Level tracks:** the namespace is required, see [Track IDs](#track-ids).
- **Classes and class slots:** the namespace is required, see [Class IDs](#class-ids).
- **Resources:** the namespace is required, see [Resource IDs](#resource-ids).

> Item IDs with uppercase letters (`minecraft:DIAMOND_SWORD`) or with more than one `:` (`ia:itemsadder:ruby_sword`) are deprecated.
> They still work but log a warning.
> The deprecated `ItemsRegistry` API still searches an item ID without namespace, or with the `mimic` namespace, over all plugins.
> It also accepts item IDs with uppercase letters (`minecraft:DIAMOND_SWORD`), with more than one `:` (`ia:itemsadder:ruby_sword`)
> and MMOItems IDs without item type (`mmoitems:excalibur`), but logs a warning.

<details>
<summary>Full example</summary>
Expand All @@ -112,7 +113,7 @@ The path may contain lowercase letters, digits, `.`, `_`, `-` and `/`.
import ru.endlesscode.mimic.Mimic;
import ru.endlesscode.mimic.MimicApiLevel;
import ru.endlesscode.mimic.classes.Classes;
import ru.endlesscode.mimic.items.BukkitItemsRegistry;
import ru.endlesscode.mimic.items.Items;
import ru.endlesscode.mimic.level.Levels;
import net.kyori.adventure.key.Key;

Expand All @@ -128,8 +129,8 @@ The path may contain lowercase letters, digits, `.`, `_`, `-` and `/`.
return mimic.getClasses();
}

public static BukkitItemsRegistry getItemsRegistry() {
return mimic.getItemsRegistry();
public static Items getItems() {
return mimic.getItems();
}

@Override
Expand Down Expand Up @@ -166,11 +167,9 @@ The path may contain lowercase letters, digits, `.`, `_`, `-` and `/`.

boolean isWarrior = getClasses().hasClass(player, Key.key("fabled:warrior"));

// ItemsRegistry is not related to player so it can be used without provider
BukkitItemsRegistry itemsRegistry = getItemsRegistry();
ItemStack stick = itemsRegistry.getItem("minecraft:stick");
boolean isPalmLogInHand = itemsRegistry.isSameItem(player.getInventory().getItemInMainHand(), "craftengine:default/palm_log");
boolean isPalmLogExists = itemsRegistry.isItemExists("craftengine:default/palm_log");
Key excalibur = Key.key("mmoitems:sword/excalibur");
ItemStack sword = getItems().createItem(excalibur, 1, player, null);
boolean isSwordInHand = getItems().isItem(player.getInventory().getItemInMainHand(), excalibur);
}
}
```
Expand Down Expand Up @@ -420,6 +419,81 @@ To make resources of your plugin available, implement [ResourceProvider]: only r

`minecraft:health` is changed directly, as a cost and not as damage: no damage or regain events are fired,
armor and absorption hearts are ignored, and taking all health kills the player.
### Items

[Items] gives access to vanilla items and custom items of all supported plugins:
create an item by its ID, get the ID of a stack, check that a stack is a specific item.

#### Item IDs

An item ID is a `Key` like `mmoitems:sword/excalibur`: the namespace is the ID of the plugin providing the item,
the path is the item within that plugin.
The namespace is required, there is no search over all plugins.
`Key.key("excalibur")` turns into `minecraft:excalibur`, so validate IDs read from configs:

```java
Key itemId = Key.key(config.getString("item"));
if (!items.hasItem(itemId)) {
getLogger().warning("Unknown item " + itemId.asString());
}
```

`items.getAllItems()` lists all IDs, for example, for tab completion.
See ID formats of the supported plugins in [Supported Implementations](../mimic-bukkit/README.md#supported-implementations).

#### Identifying items

An item belongs to the plugin with the highest priority that recognizes it, and vanilla items belong to `minecraft`.
So a ruby built on a diamond is never `minecraft:diamond`.
Items are compared by ID only: amount, stats, durability and lore of the stack are ignored.

```java
Key itemId = items.getItemId(stack); // null if no plugin recognizes the item
boolean isExcalibur = items.isItem(stack, Key.key("mmoitems:sword/excalibur"));
// Any diamond, vanilla or a custom item built on it
boolean isDiamond = stack.getType() == Material.DIAMOND;
```

#### Creating items

```java
// A new stack with a single item, or null if the item doesn't exist
ItemStack stick = items.createItem(Key.key("minecraft:stick"));
ItemStack palmLogs = items.createItem(Key.key("craftengine:default/palm_log"), 16);

// Create the item for the player: some plugins scale items to the player's level.
// The payload is in the format of the plugin providing the item, with an invalid payload the item is not created
ItemStack sword = items.createItem(Key.key("minecraft:diamond_sword"), 1, player, "[damage=10]");
```

The amount is kept within `1` and the maximum stack size of the item.
Each call returns a new stack, so it is safe to change it.

#### Rules

- Call `createItem` on the main thread. Other methods may be called from any thread.
- Item IDs may be unknown until their plugins finish loading, and may change when a plugin reloads.
Don't keep created stacks across reloads.
- A payload is passed only to the plugin named by the item ID. Plugins taking no payload ignore it.

#### Migration from ItemsRegistry

`ItemsRegistry` API is deprecated but keeps working: every registered items registry is available via [Items],
and `Mimic.getItemsRegistry()` shows items of all item providers.

| ItemsRegistry | Items |
|--------------------------------------|-----------------------------------------------------|
| `getItem(id, payload, amount)` | `createItem(id, amount, player, payload)` |
| `getItemId(item)` | `getItemId(item)` |
| `isSameItem(item, id)` | `isItem(item, id)` |
| `isItemExists(id)` | `hasItem(id)` |
| `getKnownIds()` | `getAllItems()` |

- IDs are `Key`s with a required namespace. To keep accepting IDs without a namespace in your configs,
look them up in `getAllItems()` yourself.
- MMOItems IDs include the item type: `mmoitems:sword/excalibur` instead of `mmoitems:excalibur`.
- The payload is a `String`.

### Blocks

[Blocks] gives access to vanilla blocks and custom blocks of all supported plugins:
Expand Down Expand Up @@ -537,10 +611,55 @@ public class MyClassProvider implements ClassProvider {
}
```

Items registries and block providers receive and return IDs without the namespace, Mimic adds it.
Item providers and block providers receive and return IDs without the namespace, Mimic adds it.
Mapping the plugin's own IDs to valid Mimic IDs is up to the implementation, for example `default:palm_log` → `default/palm_log`.
Invalid IDs returned by an implementation are ignored with a warning.
See [BlockProvider] for the rules about block IDs, ownership of blocks and threading.
See [ItemProvider] and [BlockProvider] for the rules about IDs, ownership of items and blocks, and threading.

<details>
<summary>Item provider example</summary>

```java
import org.bukkit.entity.Player;
import org.bukkit.inventory.ItemStack;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import ru.endlesscode.mimic.items.ItemProvider;

import java.util.Collection;

public class MyItemProvider implements ItemProvider {

@NotNull
@Override
public String getId() {
return "myplugin";
}

// Read on every request, so it can change on the plugin reload
@NotNull
@Override
public Collection<String> getAllItems() {
return MyItems.getIds();
}

// Return null for items of other plugins and for vanilla items
@Nullable
@Override
public String getItemId(@NotNull ItemStack item) {
return MyItems.getId(item);
}

// Return a new stack on every call, or null if the item is unknown.
// This provider takes no payload, so it is ignored
@Nullable
@Override
public ItemStack createItem(@NotNull String itemId, int amount, @Nullable Player player, @Nullable String payload) {
return MyItems.create(itemId, amount, player);
}
}
```
</details>

<details>
<summary>Block provider example</summary>
Expand Down Expand Up @@ -696,6 +815,7 @@ public void onLoad() {

// Register your implementations and specify minimal required Mimic version for it.
mimic.registerClassProvider(new MyClassProvider(), MimicApiLevel.CURRENT, this);
mimic.registerItemProvider(new MyItemProvider(), MimicApiLevel.CURRENT, this);
mimic.registerBlockProvider(new MyBlockProvider(), MimicApiLevel.CURRENT, this);
mimic.registerLevelProvider(new MyLevelProvider(), MimicApiLevel.CURRENT, this);
}
Expand Down Expand Up @@ -723,6 +843,8 @@ IDs of the default implementations (`mimic`, `minecraft`, `permissions`) are res
[BukkitClassSystem]: src/main/kotlin/classes/BukkitClassSystem.kt
[BukkitPlayerInventory.Provider]: src/main/kotlin/inventory/BukkitPlayerInventory.kt
[BukkitItemsRegistry]: src/main/kotlin/items/BukkitItemsRegistry.kt
[Items]: https://endlesscodegroup.github.io/Mimic/mimic-bukkit-api/ru.endlesscode.mimic.items/-items/index.html
[ItemProvider]: https://endlesscodegroup.github.io/Mimic/mimic-bukkit-api/ru.endlesscode.mimic.items/-item-provider/index.html
[Blocks]: https://endlesscodegroup.github.io/Mimic/mimic-bukkit-api/ru.endlesscode.mimic.blocks/-blocks/index.html
[BlockProvider]: https://endlesscodegroup.github.io/Mimic/mimic-bukkit-api/ru.endlesscode.mimic.blocks/-block-provider/index.html

Expand Down
19 changes: 19 additions & 0 deletions mimic-bukkit-api/api/mimic-bukkit-api.api
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ public abstract interface class ru/endlesscode/mimic/Mimic {
public abstract fun getClassSystemProvider ()Lru/endlesscode/mimic/classes/BukkitClassSystem$Provider;
public abstract fun getClasses ()Lru/endlesscode/mimic/classes/Classes;
public static fun getInstance ()Lru/endlesscode/mimic/Mimic;
public abstract fun getItems ()Lru/endlesscode/mimic/items/Items;
public abstract fun getItemsRegistry ()Lru/endlesscode/mimic/items/BukkitItemsRegistry;
public fun getLevelSystem (Lorg/bukkit/entity/Player;)Lru/endlesscode/mimic/level/BukkitLevelSystem;
public abstract fun getLevelSystemProvider ()Lru/endlesscode/mimic/level/BukkitLevelSystem$Provider;
Expand All @@ -22,6 +23,8 @@ public abstract interface class ru/endlesscode/mimic/Mimic {
public abstract fun registerClassProvider (Lru/endlesscode/mimic/classes/ClassProvider;ILorg/bukkit/plugin/Plugin;Lorg/bukkit/plugin/ServicePriority;)Lru/endlesscode/mimic/classes/ClassProvider;
public fun registerClassSystem (Lru/endlesscode/mimic/classes/BukkitClassSystem$Provider;ILorg/bukkit/plugin/Plugin;)Lru/endlesscode/mimic/classes/BukkitClassSystem$Provider;
public abstract fun registerClassSystem (Lru/endlesscode/mimic/classes/BukkitClassSystem$Provider;ILorg/bukkit/plugin/Plugin;Lorg/bukkit/plugin/ServicePriority;)Lru/endlesscode/mimic/classes/BukkitClassSystem$Provider;
public fun registerItemProvider (Lru/endlesscode/mimic/items/ItemProvider;ILorg/bukkit/plugin/Plugin;)Lru/endlesscode/mimic/items/ItemProvider;
public abstract fun registerItemProvider (Lru/endlesscode/mimic/items/ItemProvider;ILorg/bukkit/plugin/Plugin;Lorg/bukkit/plugin/ServicePriority;)Lru/endlesscode/mimic/items/ItemProvider;
public fun registerItemsRegistry (Lru/endlesscode/mimic/items/BukkitItemsRegistry;ILorg/bukkit/plugin/Plugin;)Lru/endlesscode/mimic/items/BukkitItemsRegistry;
public abstract fun registerItemsRegistry (Lru/endlesscode/mimic/items/BukkitItemsRegistry;ILorg/bukkit/plugin/Plugin;Lorg/bukkit/plugin/ServicePriority;)Lru/endlesscode/mimic/items/BukkitItemsRegistry;
public fun registerLevelProvider (Lru/endlesscode/mimic/level/LevelProvider;ILorg/bukkit/plugin/Plugin;)Lru/endlesscode/mimic/level/LevelProvider;
Expand Down Expand Up @@ -151,6 +154,22 @@ public abstract interface class ru/endlesscode/mimic/inventory/BukkitPlayerInven
public abstract interface class ru/endlesscode/mimic/items/BukkitItemsRegistry : ru/endlesscode/mimic/items/ItemsRegistry {
}

public abstract interface class ru/endlesscode/mimic/items/ItemProvider : ru/endlesscode/mimic/MimicService {
public abstract fun createItem (Ljava/lang/String;ILorg/bukkit/entity/Player;Ljava/lang/String;)Lorg/bukkit/inventory/ItemStack;
public abstract fun getAllItems ()Ljava/util/Collection;
public abstract fun getItemId (Lorg/bukkit/inventory/ItemStack;)Ljava/lang/String;
}

public abstract interface class ru/endlesscode/mimic/items/Items {
public fun createItem (Lnet/kyori/adventure/key/Key;)Lorg/bukkit/inventory/ItemStack;
public fun createItem (Lnet/kyori/adventure/key/Key;I)Lorg/bukkit/inventory/ItemStack;
public abstract fun createItem (Lnet/kyori/adventure/key/Key;ILorg/bukkit/entity/Player;Ljava/lang/String;)Lorg/bukkit/inventory/ItemStack;
public abstract fun getAllItems ()Ljava/util/List;
public abstract fun getItemId (Lorg/bukkit/inventory/ItemStack;)Lnet/kyori/adventure/key/Key;
public abstract fun hasItem (Lnet/kyori/adventure/key/Key;)Z
public abstract fun isItem (Lorg/bukkit/inventory/ItemStack;Lnet/kyori/adventure/key/Key;)Z
}

public abstract class ru/endlesscode/mimic/level/BukkitLevelSystem : ru/endlesscode/mimic/level/LevelSystem {
public fun <init> (Lorg/bukkit/entity/Player;)V
public final fun getPlayer ()Lorg/bukkit/entity/Player;
Expand Down
Loading
Loading