API

StaffService es la forma en que otro plugin pregunta si un jugador está en vanish, congelado o de servicio, y con la que ejecuta una de las acciones del propio staff sin pasar por un comando.

ExyliaAPI.get(StaffService.class).ifPresent(staff -> {
    if (staff.isVanished(target.getUniqueId()) && !staff.canSee(viewer, target)) {
        event.setCancelled(true);
    }
});

Cada función es un módulo, y un módulo puede estar apagado

El modo staff, el vanish, el freeze, el chat de staff y el resto son módulos separados que el dueño prende y apaga en config.yml o en caliente. Una pregunta sobre un módulo apagado responde como si nadie estuviera en ese estado — false, 0, GlobalChatMode.OFF — y una acción sobre un módulo apagado no hace nada. Nada de esto lanza excepciones porque falte una función: que falte es una decisión del dueño, no un error. Preguntá isModuleEnabled(String) cuando la diferencia importe.

Todo lo que devuelve un valor es una lectura en memoria de las cachés de los módulos, segura desde un placeholder, una línea de scoreboard o un listener de combate. Todo lo que actúa ejecuta el mismo flujo que el comando del propio staff — los chequeos de permisos, los mensajes que ve, el redibujado de la hotbar, el registro de la sesión — así que llamalo desde el hilo principal y no más seguido de lo que un jugador podría dispararlo.

Estado

Vanish

canSee es el chequeo que quiere cualquier cosa que liste, apunte o dibuje jugadores — es lo que mantiene a un admin oculto para un helper que por lo demás sí puede ver staff en vanish.

Chat

Listas

Las dos son de este servidor únicamente: el staff que trabaja en otro servidor de la red no está conectado acá y no tiene un Player del que leer un permiso. Ambas listas son inmutables.

Módulos

Los ids son los que el dueño escribe en config.yml: staffmode, vanish, freeze, staffchat, globalchat, mining, xrayvision y el resto. El conjunto cambia en caliente — un dueño puede apagar un módulo sin reiniciar — así que leelo cuando lo necesites en vez de guardarlo en caché.

Acciones

Cada una ejecuta el mismo flujo que el comando del propio staff, chequeos de permisos y mensajes al jugador incluidos. Cuando una devuelve un boolean es si el flujo se ejecutó, no si salió bien en algún sentido más profundo: una negativa ya se le dijo al jugador.

GlobalChatMode

Cada escalón incluye al anterior, así que un ciclo solo suma alcance.

bypasses() es true para cualquier cosa que no sea OFF, y es por lo que a un plugin de chat le importa: un miembro del staff por encima de OFF lee los chats que aísla una partida, una arena o un evento, así que un plugin que esconde líneas de otros jugadores tiene que dejar pasar las suyas.

Eventos

Dos eventos, en net.exylia.lib.api.staff.event. Los dos se disparan después de que el cambio o la acción ya ocurrió, en el hilo del jugador del que tratan, y ninguno es cancelable: informan, no controlan. Justamente porque se disparan después, recibir uno es una garantía: cuando corre tu listener el service ya responde de la forma nueva. Para rechazar un cambio, controlá el permiso que lo permite.

Los propios módulos de ExyliaStaff usan estos eventos en vez de llamarse entre sí — la hotbar redibuja su ítem de vanish, el registro cuenta un freeze, el scoreboard actualiza una línea — y por eso viven en la API pública y no dentro del plugin. Cualquier cosa que quiera una auditoría, un webhook o un scoreboard por miembro del staff escucha esos mismos dos.

StaffStateChangeEvent.Kind

Cada módulo con un interruptor por jugador lo informa acá en vez de definir un evento propio, así que la lista crece a medida que se agregan módulos. Un listener al que le importa un solo tipo filtra; uno que hace un switch sobre todos debería tener una rama por defecto.

@EventHandler
public void onState(StaffStateChangeEvent event) {
    if (event.getKind() == StaffStateChangeEvent.Kind.STAFF_MODE && !event.isEnabled()) {
        // el turno terminó
    }
}

StaffActionEvent

getAction() es un id corto como freeze, report_resolve o punish. Aparecen ids nuevos a medida que se agregan módulos, así que tratá uno desconocido como una acción que tiene esta versión del plugin y la tuya no conoce, no como un error. getTarget() es null para una acción que no trata sobre nadie en particular.

Lo que no expone

Nada de abridores de menú, flujos de editor, filas de sanciones o de reportes, ni escrituras de configuración. Los reportes, el helpop, la inspección y el historial de sanciones se leen y se manejan desde dentro del plugin, y el registro de staff se llena con StaffActionEvent y no con un método que llames tú.

Si una integración realmente necesita algo que no está acá, pídelo en Discord — agregar un método a un service es un release menor.