Skip to content

Supporter System

Jump to bottom
Lumii edited this page Nov 1, 2026 · 1 revision

Overview

Citrine provides a remotely updated supporter system that allows mods to maintain lists of supporter UUIDs. Lists are fetched from HTTPS endpoints, cached locally, and periodically refreshed.

The system uses UUIDs rather than usernames, so supporter status is not tied to a player's Minecraft name.

Packages

  • org.carpentry.citrine.api.supporter
  • org.carpentry.citrine.api.util

Creating a Supporter List

Use SupporterUtils.createRemoteList() to create and register a remotely updated supporter list.

public static final SupporterList SUPPORTERS =
        SupporterUtils.createRemoteList(
                "examplemod",
                URI.create("https://example.com/supporters.json"),
                Duration.ofMinutes(30)
        );

Parameters:

Parameter Description
id Unique identifier for the list.
uri HTTPS URL pointing to the supporter JSON file.
refreshInterval How frequently the list should be refreshed.

The list ID may only contain letters, numbers, underscores, and hyphens. Refresh intervals must be at least one minute.

Each registered list is automatically refreshed, beginning immediately after registration.

SupporterList

SupporterList represents a remotely maintained collection of supporter UUIDs.

Checking supporter status

boolean supporter = SUPPORTERS.isSupporter(player.getUuid());

Returns whether the supplied UUID belongs to the list.

Getting all supporters

Set<UUID> supporters = SUPPORTERS.getSupporters();

Returns an immutable snapshot of the current supporter UUIDs.

Manually refreshing

SUPPORTERS.refresh();

Requests an immediate refresh and returns a CompletableFuture<Boolean> indicating whether the refresh succeeded.

A failed refresh preserves the last successfully loaded supporter list.

JSON Format

Supporter lists must use the following JSON structure:

{
  "version": 1,
  "supporters": [
    "00000000-0000-0000-0000-000000000000",
    "11111111-1111-1111-1111-111111111111"
  ]
}
  • version specifies the format version. Currently, only version 1 is supported.
  • supporters contains the UUID strings of registered supporters.

Invalid entries or unsupported formats cause the refresh to fail.

Local Caching

Supporter lists are cached in the following directory:

.minecraft/config/citrine/supporters/

Each list gets its own JSON file, named after its registered ID.

Cached supporter data is loaded when the list is constructed, allowing previously fetched supporter information to remain available while offline or when a refresh fails.

Styled Player Names

SupporterUtils.getStyledName() provides a convenient way to append Citrine's supporter indicator to a player's name.

Text name = SupporterUtils.getStyledName(
        player.getUuid(),
        player.getName()
);

If the player belongs to Citrine.CITRINE_SUPPORTERS, an orange supporter glyph is appended to the supplied text. Otherwise, the original text is returned unchanged.

The supporter glyph uses the private-use character U+E782 and requires a font resource that defines it.

Shutting Down

Call SupporterUtils.shutdown() during mod/server shutdown:

SupporterUtils.shutdown();

This cancels scheduled refresh tasks, clears registered lists, and shuts down the refresh executor.

Important: The refresh manager cannot be reused after shutdown. Call this only when the application is actually shutting down.

Clone this wiki locally