ResourceProvider

Implement it to make your plugin's resources available via Resources. Register it in onLoad via Mimic.registerResourceProvider. To read or change resources of players, use Resources instead.

A resource is something a player spends and gets back, with a current amount and a maximum: mana, stamina, energy, rage. Your plugin may have one resource or many.

What to implement

Mimic takes and gives resources through getState and setAmount, so there is nothing else to implement.

Resource IDs

Mimic adds your provider id as the namespace, so return IDs without it: mana becomes myplugin:mana. Don't change id later, it breaks consumers' configs.

If your plugin has its own namespaced IDs, convert them to paths:

  • Drop your plugin's own namespace: myplugin:mana ->mana.

  • Keep other namespaces as the first path part: myaddon:rage ->myaddon/rage.

Other rules:

  • Allowed characters: a-z, 0-9, ., _, - and /. Resources with other characters are ignored.

  • To convert other IDs, lowercase them and replace other characters with _. Keep a map back to the original IDs.

  • If two IDs become the same (Mana and mana), log a warning and keep one of them.

Rules

  • Only online players are passed to the provider.

  • Never throw. If the player's data isn't loaded yet, return null from reads and false from writes.

  • Don't change data until the player's data is loaded, even if your plugin's API allows it.

  • Never send messages to the player, like "not enough mana".

  • Reads may be called from any thread. If your plugin can't read data there, return null instead of throwing.

  • Writes are expected on the main thread (on Folia - on the player's thread), but Mimic doesn't enforce it.

Mimic does the rest: selects the provider by the resource ID namespace, checks amounts, never gives above ResourceState.max or sets below 0, and catches errors thrown by the provider.

Since

0.10.0

Types

Link copied to clipboard

Resource of a ResourceProvider. Definitions are immutable, so they can be cached and reused.

Properties

Link copied to clipboard

All resources this provider knows, regardless of players. The list may change at runtime, so it is read on every request.

Inherited properties

Link copied to clipboard
open val id: String
Link copied to clipboard
open val isEnabled: Boolean

Functions

Link copied to clipboard

Returns the resource the player spends on abilities by default, like mana, or null if there is no such resource.

Link copied to clipboard
abstract fun getState(player: Player, @KeyPattern.Value resourceId: String): ResourceState?

Returns how much of the resourceId the player has, or null if the player doesn't have the resource or their data isn't loaded.

Link copied to clipboard
open fun setAmount(player: Player, @KeyPattern.Value resourceId: String, amount: Double): Boolean

Sets the current amount of the resourceId right away, so the next getState returns the new value. Skip this method if your plugin applies changes later.