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.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.