Developer API | Astral Realms Documentation

Availability Check

Always verify the API is initialised before calling it (e.g. in onEnable after adding AstralCore as a dependency):

if (!AstralPaperAPI.isInitialized()) {
    getLogger().warning("AstralCore not available!");
    return;
}

Services

Register and retrieve arbitrary AstralService implementations:

// Registration (during your plugin's onEnable)
AstralPaperAPI.registerService(MyEconomyService.class, new MyEconomyServiceImpl());

// Retrieval (anywhere)
Optional<MyEconomyService> economy = AstralPaperAPI.getService(MyEconomyService.class);
economy.ifPresent(e -> e.pay(player, 100));

// Direct access to the repository
ServiceRepository services = AstralPaperAPI.services();

Your service class must extend AstralService (a marker interface in commons).

Item Stack Suppliers

Register a named provider so items with your namespace prefix are resolved automatically in menus and dialogs:

AstralPaperAPI.registerItemStackSupplier("mymod", key -> {
    // return an ItemStack or null when key is not found
    return MyItemRegistry.get(key);
});

Usage in YAML:

material: "mymod-special_sword"

Placeholder Processors

Register a text-level processor applied to all strings before they are sent to players:

AstralPaperAPI.registerPlaceholderProcessor((player, text) ->
    text.replace("{name}", player.getName())
);

Component Processors

Register an Adventure Component processor (applied after MiniMessage parsing):

AstralPaperAPI.registerComponentProcessor((player, component) -> {
    // e.g. append a suffix
    return component;
});

PlaceholderContainer

Create an isolated placeholder context for a player:

PlaceholderContainer ctx = AstralPaperAPI.createPlaceholderContainer(player);
ctx.registerDirect("kills", playerKills);

Or adapt an existing container for a player (registers player.* and PAPI fallback):

AstralPaperAPI.adaptPlaceholdersFor(player, existingContainer);

Placeholder Substitution

Apply %key% substitution on a string using a function:

String result = AstralPaperAPI.processPlaceholders(
    "Hello %player.name%, you have %kills% kills.",
    key -> switch (key) {
        case "kills" -> playerKills;
        default -> null;
    }
);

Accessing Core Services

// Server information from config.yml
ServerInformation info = AstralPaperAPI.serverInformation();

// Network player service
PlayerService players = AstralPaperAPI.players();
Optional<MinecraftPlayer> target = players.findByName("Steve");

// Server discovery service
ServerService servers = AstralPaperAPI.servers();

Custom Actions and Requirements

See Custom Actions and Custom Requirements for registering new action/requirement types that can be used in any menu or dialog YAML.

Type Adapters

Register a constructor argument adapter for use with AstralAdapter-based action/requirement constructors:

AstralPaperAPI.registerAdapter(MyType.class, (node, context) -> {
    return new MyType(node.getString());
});