Saltar al contenido

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

NametagService

Visibilidad del nametag por motivo. Hilo del servidor.

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)

    Oculta el nametag por un motivo.

  • void show(UUID player, String reason)

    Quita ese motivo.

  • boolean hidden(UUID player)

    Si está oculto.

  • void refresh(UUID player)

    Recalcula en el siguiente tick.

net.sofycore.api.menu

MenuService

Abre menús integrados o personalizados. Hilo del servidor.

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)

    Abre un menú; false si el módulo está apagado, el menú no existe o los argumentos son incorrectos.

  • Set<String> menus()

    IDs de menús disponibles.

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.