Referencia de la API
Referencia de servicios
Todas las interfaces de servicio públicas de sofyCore con sus métodos, cómo obtenerlas y sus notas de hilos.
Obtén cada servicio con api.service(Tipo.class). Las firmas corresponden a la versión actual de sofycore-api.
Rangos
net.sofycore.api.rank
RankService
Rangos, grants y permisos. Las escrituras se vuelven a autorizar al confirmar; los modelos son inmutables.
Acceso: 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)Aplica un cambio administrativo (crear, grant, revoke, extend, permiso, regla...).
CompletableFuture<State> inspectAsync(Actor actor, UUID target)Vista autorizada de un usuario, también offline.
Optional<State> online(UUID playerId)Vista actual en memoria de un jugador conectado.
Map<String, RankDefinition> catalog()Catálogo de rangos.
List<String> grantable(UUID actorId)Ayuda visual de los rangos que un actor puede dar; la confirmación vuelve a autorizar.
String placeholder(UUID playerId, String key)Resuelve un placeholder de rangos, incluidos los parametrizados.
CompletableFuture<Authorization> authorizeAsync(Actor actor, Collection<UUID> targets, boolean consoleIssuer, String permission, boolean ownerOnly, String operationDigest)Autorización jerárquica de una operación exacta (la usa moderación).
boolean ready()Si el sistema de rangos está listo.
net.sofycore.api.rank
RankAppearanceService
Rango visible (prefijo, sufijo, color) usado por chat, nametags y menús.
package net.sofycore.api.rank;
public interface RankAppearanceService {
Optional<RankAppearance> visibleRank(UUID playerId);
AutoCloseable registerProvider(Provider provider);
}Optional<RankAppearance> visibleRank(UUID playerId)Rango que se muestra para un jugador.
AutoCloseable registerProvider(Provider provider)Registra un proveedor de apariencia.
net.sofycore.api.rank
RankContextService
Registra contextos de permisos adicionales. Los callbacks se ejecutan en el hilo de plataforma y solo deben leer memoria.
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)Registra un proveedor de contexto.
void refresh(UUID playerId)Solicita una nueva captura de contexto.
Moderación
net.sofycore.api.moderation
ModerationService
Sanciones, historial y ajustes de moderación. Nunca hagas join() de los futuros en el hilo del servidor.
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)Emite una sanción (BAN, IPBAN, BLACKLIST, MUTE, WARN, KICK).
CompletableFuture<Void> removeAsync(RankService.Actor actor, Sanction.Type type, String target, String warnId, String reason, boolean silent)Retira una sanción activa.
CompletableFuture<ModerationView> inspectAsync(RankService.Actor actor, String target)Vista actual autorizada de un sujeto.
CompletableFuture<ModerationPage<Map<String,String>>> historyAsync(RankService.Actor actor, String target, boolean staff, String cursor)Historial paginado de un jugador o del staff.
Optional<ModerationView> online(UUID playerId)Vista inmutable en memoria de un jugador conectado.
boolean maySpeak(UUID playerId)Si el jugador puede hablar (sin I/O).
boolean ready()Disponibilidad del módulo.
net.sofycore.api.moderation
ReportService
Reportes de jugadores y su revisión.
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)Crea un reporte.
CompletableFuture<ModerationPage<Report>> reportsAsync(RankService.Actor actor, String cursor)Cola abierta, paginada.
CompletableFuture<Report> transitionAsync(RankService.Actor actor, UUID id, String action, String resolution)Toma, libera, resuelve o descarta un reporte.
Map<String,String> reportTypes()Categorías de reporte configuradas.
Staff
net.sofycore.api.staff
StaffService
Acceso a freeze, vanish y modo staff.
package net.sofycore.api.staff;
public interface StaffService {
FreezeService freeze();
VanishService vanish();
StaffModeService mode();
}FreezeService freeze()Servicio de freeze.
VanishService vanish()Servicio de vanish.
StaffModeService mode()Servicio de modo staff.
net.sofycore.api.staff
FreezeService
Freeze de red con los mismos permisos y jerarquía que /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)Congela a un jugador. Result: FROZEN, ALREADY_FROZEN, UNFROZEN, NOT_FROZEN.
CompletableFuture<Result> unfreezeAsync(RankService.Actor actor, String target)Descongela a un jugador.
CompletableFuture<Result> toggleAsync(RankService.Actor actor, String target)Alterna el freeze (lo usan los ítems de staff).
CompletableFuture<Optional<FreezeState>> stateAsync(UUID player)Estado de freeze desde Redis.
boolean frozen(UUID player)Hilo del servidor, solo jugadores de este servidor.
net.sofycore.api.staff
VanishService
Vanish basado en jerarquía.
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)Alterna el vanish.
CompletableFuture<Boolean> setAsync(UUID player, boolean vanished)Fija el vanish.
CompletableFuture<Boolean> stateAsync(UUID player)Estado desde Redis.
boolean vanished(UUID player)Estado en memoria (hilo del servidor).
boolean canSee(UUID viewer, UUID target)Si viewer puede ver a target.
net.sofycore.api.staff
StaffModeService
Estado del modo staff.
package net.sofycore.api.staff;
public interface StaffModeService {
boolean active(UUID player);
boolean enter(UUID player);
boolean exit(UUID player);
}boolean active(UUID player)Cualquier hilo.
boolean enter(UUID player)Hilo del servidor; mismas comprobaciones que el comando.
boolean exit(UUID player)Hilo del servidor.
Puntos VIP y mantenimiento
net.sofycore.api.vippoints
VippointsService
Puntos VIP globales y tienda de rangos. Los rechazos son IllegalArgumentException con un código de REASONS; cualquier otro error significa resultado incierto.
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)Saldo de un jugador conectado, desde memoria.
CompletableFuture<Long> balanceAsync(UUID player)Saldo, también offline.
CompletableFuture<Long> addAsync(UUID player, long amount, String actor)Suma puntos (hasta el máximo global).
CompletableFuture<Long> takeAsync(UUID player, long amount, String actor)Quita puntos, nunca por debajo de cero.
CompletableFuture<Long> setAsync(UUID player, long amount, String actor)Fija un saldo.
List<VipTemplate> templates()Plantillas de la tienda.
CompletableFuture<VipPurchase> previewAsync(UUID player, String templateId)Qué haría una compra.
CompletableFuture<VipPurchase> purchaseAsync(UUID player, String templateId, long expectedPrice)Compra una plantilla; un menú debe confirmar antes.
net.sofycore.api.maintenance
MaintenanceService
Mantenimiento de la red. Las lecturas son de memoria; los cambios terminan en un hilo de trabajo.
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()Si el mantenimiento está activo.
MaintenanceState state()Estado actual.
CompletableFuture<MaintenanceState> enableAsync(String actor, String reason, boolean freezeRanks, long bonusMillis)Activa el mantenimiento.
CompletableFuture<MaintenanceState> disableAsync(String actor, long bonusMillis)Desactiva el mantenimiento.
Interfaz
net.sofycore.api.bossbar
BossBarService
Catálogo de bossbars de la red. Registrado mientras el módulo bossbar está activo.
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()Catálogo actual.
CompletableFuture<BossBarCatalog> createAsync(BossBarEntry entry)Crea una barra.
CompletableFuture<BossBarCatalog> editAsync(String id, UnaryOperator<BossBarEntry> change)Edita una barra.
CompletableFuture<BossBarCatalog> deleteAsync(String id)Borra una barra.
CompletableFuture<BossBarCatalog> setEnabledAsync(boolean enabled)Interruptor de toda la red.
CompletableFuture<BossBarCatalog> setGroupAsync(String group, List<String> servers)Crea o reemplaza un grupo de servidores.
net.sofycore.api.scoreboard
ScoreboardService
Control del sidebar para otros plugins. Solo hilo del servidor.
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)Oculta el sidebar mientras quede algún motivo.
void show(UUID playerId, String reason)Quita un motivo de ocultación.
boolean hidden(UUID playerId)Si está oculto.
void refresh(UUID playerId)Vuelve a dibujar ya.
net.sofycore.api.essentials
EssentialsService
Acciones de essentials. Hilo del servidor; quien llama valida permisos y jerarquía.
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)Cambia el modo de juego.
boolean heal(UUID player)Cura.
boolean feed(UUID player)Alimenta.
boolean flight(UUID player, boolean allowed)Permite o quita el vuelo.
boolean god(UUID player, boolean enabled)Fija el modo dios.
boolean teleportTo(UUID staff, UUID target)Teletransporta al staff hasta el objetivo.
boolean openInventory(UUID staff, UUID target, boolean enderChest)Abre una vista de inventario en vivo.
Usuarios y red
net.sofycore.api.user
UserService
Perfiles y preferencias de usuario, guardados con 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)Resuelve un nombre conocido.
CompletableFuture<Optional<UserProfile>> findAsync(UUID id)Lee un perfil sin crearlo.
CompletableFuture<UserProfile> setAnnouncementsAsync(UUID id, boolean enabled)Preferencia de anuncios.
CompletableFuture<UserProfile> setBossBarAsync(UUID id, boolean visible)Preferencia de bossbar.
CompletableFuture<UserProfile> setPrivateMessagesAsync(UUID id, boolean enabled)Preferencia de privados.
CompletableFuture<UserProfile> setTagAsync(UUID id, String tagKey)Tag elegido.
net.sofycore.api.user
OnlineUsers
Snapshots en memoria de los usuarios conectados.
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 de un usuario conectado.
Optional<UUID> sessionId(UUID id)ID de sesión actual, para descartar resultados tardíos.
List<UserSessionReadyEvent> readySessions()Sesiones ya cargadas (para módulos activados tarde).
OptionalLong playtimeMillis(UUID id)Tiempo de juego en vivo.
net.sofycore.api.network
PlayerDirectory
Presencia de jugadores y servidores en la red.
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 de este servidor.
CompletableFuture<Optional<PlayerLocation>> findAsync(String exactName)Busca a un jugador en la red.
CompletableFuture<Optional<ServerPresence>> serverAsync(String serverId)Presencia de un servidor.
CompletableFuture<List<NetworkPlayer>> rosterAsync()Jugadores de la red.
Almacenamiento y sonidos
net.sofycore.api.storage
PersistenceService
Registros versionados (namespace, clave, revisión, payload binario) en MongoDB/MySQL/MariaDB/SQLite con caché Redis.
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)Lee un registro, primero Redis.
CompletableFuture<List<StoredRecord>> scanAsync(String namespace, String afterKey, int limit)Páginas de 1–1000 registros ordenadas por clave.
CompletableFuture<Boolean> putAsync(String namespace, String key, long expectedRevision, byte[] payload)Escritura compare-and-set; -1 inserta; false indica conflicto.
CompletableFuture<Boolean> deleteAsync(String namespace, String key, long expectedRevision)Borrado compare-and-set.
net.sofycore.api.storage
RedisService
Redis compartido con el prefijo de la red. Set e incremento exigen TTL.
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)Lee una clave.
CompletableFuture<Void> setAsync(String key, String value, long ttlSeconds)Escribe con TTL (1–31536000 s).
CompletableFuture<Long> incrementAsync(String key, long amount, long ttlSeconds)Incremento atómico con caducidad.
CompletableFuture<Long> publishAsync(String channel, String message)Publica en pub/sub (hasta 64 Ki caracteres).
CompletableFuture<RedisSubscription> subscribeAsync(String channel, Consumer<String> listener)Suscribe; se cierra con RedisSubscription.closeAsync().
net.sofycore.api.sound
SoundService
Sonidos independientes de la versión: nombres modernos adaptados a cada versión.
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)Prepara un sonido una vez.
void play(UUID playerId, PreparedSound sound)Lo reproduce a un jugador.
Set<String> validNames()Nombres de sonido aceptados.