Service System

AstralCore uses a ServiceRepository to allow loose coupling between plugins. Any AstralService implementation can be registered and retrieved without creating a hard compile-time dependency.

AstralService Interface

AstralService is a marker interface in commons. Implement it to mark your service class:

import com.astralrealms.core.service.AstralService;

public interface MyEconomyService extends AstralService {
    double getBalance(Player player);
    void pay(Player player, double amount);
}

Registering a Service

@Override
public void onEnable() {
    AstralPaperAPI.registerService(MyEconomyService.class, new MyEconomyServiceImpl());
}

Retrieving a Service

Optional<MyEconomyService> economy = AstralPaperAPI.getService(MyEconomyService.class);
economy.ifPresent(e -> {
    double balance = e.getBalance(player);
    player.sendMessage("Balance: " + balance);
});

Or directly via the repository:

ServiceRepository repo = AstralPaperAPI.services();
repo.get(MyEconomyService.class).ifPresent(...);

Built-in Services

AstralCore ships several built-in services accessible through the main plugin instance:

Service	Access	Description
`PlayerService`	`AstralPaperAPI.players()`	Network-wide player tracking and lookup
`ServerService`	`AstralPaperAPI.servers()`	Server discovery and heartbeat management
`MenuService`	`AstralCore.get().menus()`	Menu blueprint management and opening
`DialogService`	`AstralCore.get().dialogs()`	Dialog blueprint management and opening
`BlockService`	`AstralCore.get().blocks()`	Player-placed block tracking
`PaperTeleporationService`	`AstralCore.get().teleportation()`	Cross-server teleportation

PlayerService

PlayerService players = AstralPaperAPI.players();

// Online check
boolean online = players.isOnline(uuid);

// Lookup by name (async, hybrid cache/DB)
players.findByName("Steve").thenAccept(opt -> {
    opt.ifPresent(p -> System.out.println(p.server()));
});

// All online player names
Collection<String> names = players.onlinePlayerNames();

ServerService

ServerService servers = AstralPaperAPI.servers();

// Find the least-populated server in a group
servers.findEmptiestByGroup("survival").thenAccept(opt -> {
    opt.ifPresent(server -> {
        // Transfer player to that server
    });
});

Service Lifecycle

Services are registered once and persist until the plugin is disabled. There is no built-in unregister — if your plugin is reloaded it should re-register its services on the next onEnable.

23 April 2026