Resources

interface Resources(source)

Resources of players from all RPG plugins supported by Mimic: mana, stamina and similar. Get it via Mimic.resources. To make your own plugin's resources available here, implement ResourceProvider instead.

A resource is something a player spends and gets back, with a current amount and a maximum. A player may have resources from several plugins at once.

Quick start

// Pay a cost. Nothing is taken if the player doesn't have enough
Key mana = Key.key("mmocore:mana");
if (!resources.take(player, mana, 20.0)) {
player.sendMessage("Not enough mana!");
return;
}

// Use the player's mana whatever plugin it comes from, server owners choose the plugin in Mimic config
Resource resource = resources.getPrimaryResource(player);
if (resource == null) return; // There is no mana on this server
ResourceState state = resources.getState(player, resource.key());

IDs

Resources are identified by Key, which consists of a namespace and a path:

  • The namespace is the ID of the plugin providing the resource: mmocore, heroes.

  • The path is the resource within that plugin: mana, stamina.

The namespace is required, since the same path in different plugins means a different resource. Note that Key.key("mana") turns into minecraft:mana, so validate resource IDs read from configs against getAllResources.

Rules

  • Works only with online players.

  • null or false means "not possible right now": the resource doesn't exist, the player doesn't have it, the plugin doesn't support this action, or the player's data isn't loaded yet.

  • Don't cache results. Amounts change all the time because of regeneration, and a class change may replace them.

  • Plugins storing whole numbers round amounts down. So take may take a bit more, and give a bit less. An amount smaller than the plugin can store, like a millionth of health, isn't taken at all.

  • Mimic never sends messages to the player.

  • Read from any thread. Change resources only on the main thread (on Folia - on the player's thread).

Since

0.10.0

Functions

Link copied to clipboard
abstract fun getAllResources(): List<Resource>

Returns all resources of all providers, regardless of players. Use it for discovery and config validation. Resources are sorted by provider priority, then in the order the provider returns them.

Link copied to clipboard
abstract fun getPrimaryResource(player: Player): Resource?

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, resourceId: Key): 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
abstract fun give(player: Player, resourceId: Key, amount: Double): Boolean

Gives amount of the resourceId, but not above ResourceState.max.

Link copied to clipboard
abstract fun has(player: Player, resourceId: Key, amount: Double): Boolean

Returns true if the player has at least amount of the resourceId.

Link copied to clipboard
abstract fun set(player: Player, resourceId: Key, amount: Double): Boolean

Sets the current amount of the resourceId. The amount is kept between 0 and ResourceState.max.

Link copied to clipboard
abstract fun take(player: Player, resourceId: Key, amount: Double): Boolean

Takes amount of the resourceId, or nothing if the player has less. The plugin may take a different amount by its own rules, for example with a discount.