Skip to content

API Reference

Services reference

Every public sofyCore service interface with its methods, how to obtain it and its threading notes.

Obtain each service with api.service(Type.class). Signatures match the current sofycore-api.

Ranks

net.sofycore.api.rank

RankService

Ranks, grants and permissions. Writes are authorized again on commit; models are immutable.

Access: api.service(RankService.class)

package net.sofycore.api.rank;

public interface RankService {
    CompletableFuture<String> changeAsync(Actor actor, Change change);
    CompletableFuture<State> inspectAsync(Actor actor, UUID target);
    Optional<State> online(UUID playerId);
    Map<String, RankDefinition> catalog();
    List<String> grantable(UUID actorId);
    String placeholder(UUID playerId, String key);
    CompletableFuture<Authorization> authorizeAsync(Actor actor, Collection<UUID> targets, boolean consoleIssuer, String permission, boolean ownerOnly, String operationDigest);
    boolean ready();
}
  • CompletableFuture<String> changeAsync(Actor actor, Change change)

    Applies an administrative change (create, grant, revoke, extend, permission, rule...).

  • CompletableFuture<State> inspectAsync(Actor actor, UUID target)

    Authorized view of a user, also offline.

  • Optional<State> online(UUID playerId)

    Current in-memory view of an online player.

  • Map<String, RankDefinition> catalog()

    Rank catalog.

  • List<String> grantable(UUID actorId)

    Visual hint of ranks an actor may grant; commit authorizes again.

  • String placeholder(UUID playerId, String key)

    Resolves a rank placeholder, including parameterized ones.

  • CompletableFuture<Authorization> authorizeAsync(Actor actor, Collection<UUID> targets, boolean consoleIssuer, String permission, boolean ownerOnly, String operationDigest)

    Exact-operation hierarchy authorization (used by moderation).

  • boolean ready()

    Whether the rank system is ready.

net.sofycore.api.rank

RankAppearanceService

Visible rank (prefix, suffix, name color) used by chat, nametags and menus.

package net.sofycore.api.rank;

public interface RankAppearanceService {
    Optional<RankAppearance> visibleRank(UUID playerId);
    AutoCloseable registerProvider(Provider provider);
}
  • Optional<RankAppearance> visibleRank(UUID playerId)

    Rank shown for a player.

  • AutoCloseable registerProvider(Provider provider)

    Registers an appearance provider.

net.sofycore.api.rank

RankContextService

Registers additional permission contexts. Callbacks run on the platform thread and must read memory only.

package net.sofycore.api.rank;

public interface RankContextService {
    AutoCloseable register(Set<String> keys, Function<UUID, Map<String, Collection<String>>> provider);
    void refresh(UUID playerId);
}
  • AutoCloseable register(Set<String> keys, Function<UUID, Map<String, Collection<String>>> provider)

    Registers a context provider.

  • void refresh(UUID playerId)

    Requests a new context capture.

Moderation

net.sofycore.api.moderation

ModerationService

Sanctions, history and moderation settings. Never join() futures on the server thread.

package net.sofycore.api.moderation;

public interface ModerationService {
    CompletableFuture<Sanction> issueAsync(RankService.Actor actor, Sanction.Type type, String target, long seconds, String reason, boolean silent);
    CompletableFuture<Void> removeAsync(RankService.Actor actor, Sanction.Type type, String target, String warnId, String reason, boolean silent);
    CompletableFuture<ModerationView> inspectAsync(RankService.Actor actor, String target);
    CompletableFuture<ModerationPage<Map<String,String>>> historyAsync(RankService.Actor actor, String target, boolean staff, String cursor);
    Optional<ModerationView> online(UUID playerId);
    boolean maySpeak(UUID playerId);
    boolean ready();
}
  • CompletableFuture<Sanction> issueAsync(RankService.Actor actor, Sanction.Type type, String target, long seconds, String reason, boolean silent)

    Issues a sanction (BAN, IPBAN, BLACKLIST, MUTE, WARN, KICK).

  • CompletableFuture<Void> removeAsync(RankService.Actor actor, Sanction.Type type, String target, String warnId, String reason, boolean silent)

    Removes an active sanction.

  • CompletableFuture<ModerationView> inspectAsync(RankService.Actor actor, String target)

    Authorized current view of a subject.

  • CompletableFuture<ModerationPage<Map<String,String>>> historyAsync(RankService.Actor actor, String target, boolean staff, String cursor)

    Paginated player or staff history.

  • Optional<ModerationView> online(UUID playerId)

    Immutable in-memory view of an online player.

  • boolean maySpeak(UUID playerId)

    Whether the player may speak (no I/O).

  • boolean ready()

    Module readiness.

net.sofycore.api.moderation

ReportService

Player reports and their review workflow.

package net.sofycore.api.moderation;

public interface ReportService {
    CompletableFuture<Report> fileAsync(RankService.Actor actor, String target, String type, String details);
    CompletableFuture<ModerationPage<Report>> reportsAsync(RankService.Actor actor, String cursor);
    CompletableFuture<Report> transitionAsync(RankService.Actor actor, UUID id, String action, String resolution);
    Map<String,String> reportTypes();
}
  • CompletableFuture<Report> fileAsync(RankService.Actor actor, String target, String type, String details)

    Files a report.

  • CompletableFuture<ModerationPage<Report>> reportsAsync(RankService.Actor actor, String cursor)

    Open queue, paginated.

  • CompletableFuture<Report> transitionAsync(RankService.Actor actor, UUID id, String action, String resolution)

    Takes, releases, resolves or dismisses a report.

  • Map<String,String> reportTypes()

    Configured report categories.

Staff

net.sofycore.api.staff

StaffService

Access to freeze, vanish and staff mode.

package net.sofycore.api.staff;

public interface StaffService {
    FreezeService freeze();
    VanishService vanish();
    StaffModeService mode();
}
  • FreezeService freeze()

    Freeze service.

  • VanishService vanish()

    Vanish service.

  • StaffModeService mode()

    Staff mode service.

net.sofycore.api.staff

FreezeService

Network freeze with the same permissions and hierarchy as /freeze.

package net.sofycore.api.staff;

public interface FreezeService {
    CompletableFuture<Result> freezeAsync(RankService.Actor actor, String target);
    CompletableFuture<Result> unfreezeAsync(RankService.Actor actor, String target);
    CompletableFuture<Result> toggleAsync(RankService.Actor actor, String target);
    CompletableFuture<Optional<FreezeState>> stateAsync(UUID player);
    boolean frozen(UUID player);
}
  • CompletableFuture<Result> freezeAsync(RankService.Actor actor, String target)

    Freezes a player. Result: FROZEN, ALREADY_FROZEN, UNFROZEN, NOT_FROZEN.

  • CompletableFuture<Result> unfreezeAsync(RankService.Actor actor, String target)

    Unfreezes a player.

  • CompletableFuture<Result> toggleAsync(RankService.Actor actor, String target)

    Toggles the freeze (used by staff items).

  • CompletableFuture<Optional<FreezeState>> stateAsync(UUID player)

    Freeze state from Redis.

  • boolean frozen(UUID player)

    Server thread, players of this server only.

net.sofycore.api.staff

VanishService

Hierarchy-based vanish.

package net.sofycore.api.staff;

public interface VanishService {
    CompletableFuture<Boolean> toggleAsync(UUID player);
    CompletableFuture<Boolean> setAsync(UUID player, boolean vanished);
    CompletableFuture<Boolean> stateAsync(UUID player);
    boolean vanished(UUID player);
    boolean canSee(UUID viewer, UUID target);
}
  • CompletableFuture<Boolean> toggleAsync(UUID player)

    Toggles vanish.

  • CompletableFuture<Boolean> setAsync(UUID player, boolean vanished)

    Sets vanish.

  • CompletableFuture<Boolean> stateAsync(UUID player)

    State from Redis.

  • boolean vanished(UUID player)

    In-memory state (server thread).

  • boolean canSee(UUID viewer, UUID target)

    Whether viewer can see target.

net.sofycore.api.staff

StaffModeService

Staff mode state.

package net.sofycore.api.staff;

public interface StaffModeService {
    boolean active(UUID player);
    boolean enter(UUID player);
    boolean exit(UUID player);
}
  • boolean active(UUID player)

    Any thread.

  • boolean enter(UUID player)

    Server thread; same checks as the command.

  • boolean exit(UUID player)

    Server thread.

VIP points and maintenance

net.sofycore.api.vippoints

VippointsService

Global VIP points and the rank shop. Rejections are IllegalArgumentException with a code from REASONS; any other error means an uncertain result.

package net.sofycore.api.vippoints;

public interface VippointsService {
    OptionalLong cachedBalance(UUID player);
    CompletableFuture<Long> balanceAsync(UUID player);
    CompletableFuture<Long> addAsync(UUID player, long amount, String actor);
    CompletableFuture<Long> takeAsync(UUID player, long amount, String actor);
    CompletableFuture<Long> setAsync(UUID player, long amount, String actor);
    List<VipTemplate> templates();
    CompletableFuture<VipPurchase> previewAsync(UUID player, String templateId);
    CompletableFuture<VipPurchase> purchaseAsync(UUID player, String templateId, long expectedPrice);
}
  • OptionalLong cachedBalance(UUID player)

    Balance of a connected player, from memory.

  • CompletableFuture<Long> balanceAsync(UUID player)

    Balance, also offline.

  • CompletableFuture<Long> addAsync(UUID player, long amount, String actor)

    Adds points (up to the global maximum).

  • CompletableFuture<Long> takeAsync(UUID player, long amount, String actor)

    Takes points, never below zero.

  • CompletableFuture<Long> setAsync(UUID player, long amount, String actor)

    Sets a balance.

  • List<VipTemplate> templates()

    Shop templates.

  • CompletableFuture<VipPurchase> previewAsync(UUID player, String templateId)

    What a purchase would do.

  • CompletableFuture<VipPurchase> purchaseAsync(UUID player, String templateId, long expectedPrice)

    Buys a template; a menu must confirm first.

net.sofycore.api.maintenance

MaintenanceService

Network maintenance. Reads are in memory; changes complete on a worker thread.

package net.sofycore.api.maintenance;

public interface MaintenanceService {
    boolean enabled();
    MaintenanceState state();
    CompletableFuture<MaintenanceState> enableAsync(String actor, String reason, boolean freezeRanks, long bonusMillis);
    CompletableFuture<MaintenanceState> disableAsync(String actor, long bonusMillis);
}
  • boolean enabled()

    Whether maintenance is on.

  • MaintenanceState state()

    Current state.

  • CompletableFuture<MaintenanceState> enableAsync(String actor, String reason, boolean freezeRanks, long bonusMillis)

    Turns maintenance on.

  • CompletableFuture<MaintenanceState> disableAsync(String actor, long bonusMillis)

    Turns maintenance off.

Interface

net.sofycore.api.bossbar

BossBarService

Network boss bar catalog. Registered while the bossbar module is active.

package net.sofycore.api.bossbar;

public interface BossBarService {
    BossBarCatalog catalog();
    CompletableFuture<BossBarCatalog> createAsync(BossBarEntry entry);
    CompletableFuture<BossBarCatalog> editAsync(String id, UnaryOperator<BossBarEntry> change);
    CompletableFuture<BossBarCatalog> deleteAsync(String id);
    CompletableFuture<BossBarCatalog> setEnabledAsync(boolean enabled);
    CompletableFuture<BossBarCatalog> setGroupAsync(String group, List<String> servers);
}
  • BossBarCatalog catalog()

    Current catalog.

  • CompletableFuture<BossBarCatalog> createAsync(BossBarEntry entry)

    Creates a bar.

  • CompletableFuture<BossBarCatalog> editAsync(String id, UnaryOperator<BossBarEntry> change)

    Edits a bar.

  • CompletableFuture<BossBarCatalog> deleteAsync(String id)

    Deletes a bar.

  • CompletableFuture<BossBarCatalog> setEnabledAsync(boolean enabled)

    Network-wide switch.

  • CompletableFuture<BossBarCatalog> setGroupAsync(String group, List<String> servers)

    Creates or replaces a server group.

net.sofycore.api.scoreboard

ScoreboardService

Sidebar control for other plugins. Server thread only.

package net.sofycore.api.scoreboard;

public interface ScoreboardService {
    void hide(UUID playerId, String reason);
    void show(UUID playerId, String reason);
    boolean hidden(UUID playerId);
    void refresh(UUID playerId);
}
  • void hide(UUID playerId, String reason)

    Hides the sidebar while any reason remains.

  • void show(UUID playerId, String reason)

    Removes a hiding reason.

  • boolean hidden(UUID playerId)

    Whether it is hidden.

  • void refresh(UUID playerId)

    Redraws now.

net.sofycore.api.nametag

NametagService

Nametag visibility by reason. Server thread.

package net.sofycore.api.nametag;

public interface NametagService {
    void hide(UUID player, String reason);
    void show(UUID player, String reason);
    boolean hidden(UUID player);
    void refresh(UUID player);
}
  • void hide(UUID player, String reason)

    Hides the nametag for a reason.

  • void show(UUID player, String reason)

    Removes that reason.

  • boolean hidden(UUID player)

    Whether it is hidden.

  • void refresh(UUID player)

    Recalculates on the next tick.

net.sofycore.api.menu

MenuService

Opens built-in or custom menus. Server thread.

package net.sofycore.api.menu;

public interface MenuService {
    boolean open(UUID player, String menu, String... arguments);
    Set<String> menus();
}
  • boolean open(UUID player, String menu, String... arguments)

    Opens a menu; false if the module is off, the menu is unknown or arguments are wrong.

  • Set<String> menus()

    Available menu ids.

net.sofycore.api.essentials

EssentialsService

Essentials actions. Server thread; the caller validates permissions and hierarchy.

package net.sofycore.api.essentials;

public interface EssentialsService {
    boolean gameMode(UUID player, String mode);
    boolean heal(UUID player);
    boolean feed(UUID player);
    boolean flight(UUID player, boolean allowed);
    boolean god(UUID player, boolean enabled);
    boolean teleportTo(UUID staff, UUID target);
    boolean openInventory(UUID staff, UUID target, boolean enderChest);
}
  • boolean gameMode(UUID player, String mode)

    Changes the game mode.

  • boolean heal(UUID player)

    Heals.

  • boolean feed(UUID player)

    Feeds.

  • boolean flight(UUID player, boolean allowed)

    Allows or disallows flight.

  • boolean god(UUID player, boolean enabled)

    Sets god mode.

  • boolean teleportTo(UUID staff, UUID target)

    Teleports staff to target.

  • boolean openInventory(UUID staff, UUID target, boolean enderChest)

    Opens a live inventory view.

Users and network

net.sofycore.api.user

UserService

User profiles and preferences, saved with compare-and-set.

package net.sofycore.api.user;

public interface UserService {
    CompletableFuture<Optional<UUID>> findIdAsync(String currentName);
    CompletableFuture<Optional<UserProfile>> findAsync(UUID id);
    CompletableFuture<UserProfile> setAnnouncementsAsync(UUID id, boolean enabled);
    CompletableFuture<UserProfile> setBossBarAsync(UUID id, boolean visible);
    CompletableFuture<UserProfile> setPrivateMessagesAsync(UUID id, boolean enabled);
    CompletableFuture<UserProfile> setTagAsync(UUID id, String tagKey);
}
  • CompletableFuture<Optional<UUID>> findIdAsync(String currentName)

    Resolves a known name.

  • CompletableFuture<Optional<UserProfile>> findAsync(UUID id)

    Reads a profile without creating it.

  • CompletableFuture<UserProfile> setAnnouncementsAsync(UUID id, boolean enabled)

    Announcement preference.

  • CompletableFuture<UserProfile> setBossBarAsync(UUID id, boolean visible)

    Boss bar preference.

  • CompletableFuture<UserProfile> setPrivateMessagesAsync(UUID id, boolean enabled)

    Private messages preference.

  • CompletableFuture<UserProfile> setTagAsync(UUID id, String tagKey)

    Selected tag.

net.sofycore.api.user

OnlineUsers

In-memory snapshots of connected users.

package net.sofycore.api.user;

public interface OnlineUsers {
    Optional<UserProfile> user(UUID id);
    Optional<UUID> sessionId(UUID id);
    List<UserSessionReadyEvent> readySessions();
    OptionalLong playtimeMillis(UUID id);
}
  • Optional<UserProfile> user(UUID id)

    Snapshot of an online user.

  • Optional<UUID> sessionId(UUID id)

    Current session id, to fence late results.

  • List<UserSessionReadyEvent> readySessions()

    Sessions already loaded (for late-enabled modules).

  • OptionalLong playtimeMillis(UUID id)

    Live playtime.

net.sofycore.api.network

PlayerDirectory

Network presence of players and servers.

package net.sofycore.api.network;

public interface PlayerDirectory {
    String serverId();
    CompletableFuture<Optional<PlayerLocation>> findAsync(String exactName);
    CompletableFuture<Optional<ServerPresence>> serverAsync(String serverId);
    CompletableFuture<List<NetworkPlayer>> rosterAsync();
}
  • String serverId()

    server.id of this server.

  • CompletableFuture<Optional<PlayerLocation>> findAsync(String exactName)

    Finds a player in the network.

  • CompletableFuture<Optional<ServerPresence>> serverAsync(String serverId)

    Presence of a server.

  • CompletableFuture<List<NetworkPlayer>> rosterAsync()

    Players of the network.

Storage and sounds

net.sofycore.api.storage

PersistenceService

Versioned records (namespace, key, revision, binary payload) on MongoDB/MySQL/MariaDB/SQLite with a Redis read-through cache.

package net.sofycore.api.storage;

public interface PersistenceService {
    CompletableFuture<Optional<StoredRecord>> getAsync(String namespace, String key);
    CompletableFuture<List<StoredRecord>> scanAsync(String namespace, String afterKey, int limit);
    CompletableFuture<Boolean> putAsync(String namespace, String key, long expectedRevision, byte[] payload);
    CompletableFuture<Boolean> deleteAsync(String namespace, String key, long expectedRevision);
}
  • CompletableFuture<Optional<StoredRecord>> getAsync(String namespace, String key)

    Reads a record, Redis first.

  • CompletableFuture<List<StoredRecord>> scanAsync(String namespace, String afterKey, int limit)

    Pages of 1–1000 records ordered by key.

  • CompletableFuture<Boolean> putAsync(String namespace, String key, long expectedRevision, byte[] payload)

    Compare-and-set write; -1 inserts; false means a conflict.

  • CompletableFuture<Boolean> deleteAsync(String namespace, String key, long expectedRevision)

    Compare-and-set delete.

net.sofycore.api.storage

RedisService

Shared Redis with the network key prefix. TTL is required for set and increment.

package net.sofycore.api.storage;

public interface RedisService {
    CompletableFuture<Optional<String>> getAsync(String key);
    CompletableFuture<Void> setAsync(String key, String value, long ttlSeconds);
    CompletableFuture<Long> incrementAsync(String key, long amount, long ttlSeconds);
    CompletableFuture<Long> publishAsync(String channel, String message);
    CompletableFuture<RedisSubscription> subscribeAsync(String channel, Consumer<String> listener);
}
  • CompletableFuture<Optional<String>> getAsync(String key)

    Reads a key.

  • CompletableFuture<Void> setAsync(String key, String value, long ttlSeconds)

    Writes with TTL (1–31536000 s).

  • CompletableFuture<Long> incrementAsync(String key, long amount, long ttlSeconds)

    Atomic increment with expiry.

  • CompletableFuture<Long> publishAsync(String channel, String message)

    Pub/sub publish (up to 64 Ki characters).

  • CompletableFuture<RedisSubscription> subscribeAsync(String channel, Consumer<String> listener)

    Subscribes; close with RedisSubscription.closeAsync().

net.sofycore.api.sound

SoundService

Version-independent sounds: modern names mapped to each server version.

package net.sofycore.api.sound;

public interface SoundService {
    PreparedSound prepare(SoundSpec settings);
    void play(UUID playerId, PreparedSound sound);
    Set<String> validNames();
}
  • PreparedSound prepare(SoundSpec settings)

    Prepares a sound once.

  • void play(UUID playerId, PreparedSound sound)

    Plays it for a player.

  • Set<String> validNames()

    Accepted sound names.