API | Mod Documentation

Important: This section is now outdated and unsupported. Click here for the latest release.

Structure and Overview

Offline Player Cache offers a small API package, located at com.github.clevernucleus.opc.api and contains the following:

📂api
 ┣📄CacheableValue.java abstract class
 ┗📄PlayerCacheAPI.java class

The contents of CacheableValue.java are available here. The contents of PlayerCacheAPI.java are shown below:

Modifiers and Type	Method/Field and Description
`public` `static` `final` `String`	MODID The mod id.
`public` `static` `CacheableValue<T>`	registerCacheableValue(CacheableValue<T> key) Gains access to the offline player cache object. This should only be used on the logical server.
`public` `static` `T`	get(MinecraftServer server, UUID uuid, CacheableValue<T> key) If the player is offline and exists in the cache, retrieves the last cached value. If the player is online, retrieves the player’s current value.
`public` `static` `T`	get(MinecraftServer server, String name, CacheableValue<T> key) If the player is offline and exists in the cache, retrieves the last cached value. If the player is online, retrieves the player’s current value.
`public` `static` `void`	uncacheValue(String name, CacheableValue<T> key) Removes the input value cached to the input player, if it exists.
`public` `static` `void`	uncachePlayer(UUID uuid) Removes the player who’s uuid this belongs to from the cache, if they exist.
`public` `static` `void`	uncachePlayer(String name) Removes the player who’s name this belongs to from the cache, if they exist.
`Collection<String>`	getPlayerNames(MinecraftServer server) Returns all offline/cached AND online players’ names.
`Collection<UUID>`	getPlayerIds(MinecraftServer server) Returns all offline/cached AND online players’ UUIDs.

Using Offline Player Cache

This section will use the cacheable value implementation shown here to further provide an example of how OPC could be used in a project:

1. Registering a Cacheable Value

import com.github.clevernucleus.opc.api.PlayerCacheAPI;

import net.fabricmc.api.ModInitializer;

public class ExampleMod implements ModInitializer {

    // Register our CurrentHealthValue from before.
    public static final CacheableValue<Float> CURRENT_HEALTH_VALUE = PlayerCacheAPI
    .registerCacheableValue(new CurrentHealthValue());

    @Override
    public void onInitialize() {}
}

That is all that is needed. Players will disconnect and their current health will be cached on the server, ready to be accessed at any time. An potential usage is with commands - in the next example, we create a new command: /example health <name>.

2. Creating a command with OPC

public static void register(CommandDispatcher<ServerCommandSource> dispatcher) {
    LiteralCommandNode<ServerCommandSource> exampleNode = CommandManager
    .literal("example").build();
    dispatcher.getRoot().addChild(exampleNode);
    
    LiteralCommandNode<ServerCommandSource> currentHealthNode = CommandManager
    .literal("health").build();
    exampleNode.addChild(currentHealthNode);

    ArgumentCommandNode<ServerCommandSource, String> nameNode = CommandManager
    .argument("name", StringArgumentType.string()).executes(ctx -> {
        MinecraftServer server = ctx.getSource().getServer();
        String player = StringArgumentType.getString(ctx, "name");
        float health = PlayerCacheAPI.get(server, player, ExampleMod.CURRENT_HEALTH_VALUE);
        LiteralText msg = new LiteralText(player + "'s current health is: " + health);

        ctx.getSource.sendFeedback(msg, false);

        return 1;
    }).build();
    currentHealthNode.addChild(nameNode);
}

Using examples 1. and 2., we have added the command /example health <name>. The output of which is <name>'s health is: <health>. You can now effectively get the current health of all online and offline players on your server. This is obviously a very simplistic example: usually you would also add a command node to take a UUID argument in addition to the player’s name; and you would have a suggestion provider to give you all player names/uuids.

Tags: