Contenido generado con IA — puede contener errores.

ExyliaStaff/Referenciadev

API

Preguntar en qué estado está un miembro del staff, leer las listas, ejecutar una acción de módulo y escuchar todo lo que hace el staff.

Página 31 de 3811 min de lectura

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.

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

El artefacto, el repositorio y la línea del plugin.yml son los mismos para todos los plugins de Exylia y viven en la página de la API pública.

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#

MétodoQué hace
boolean isStaff(Player)Si tiene el permiso de staff. La pregunta sobre la que se apoyan los demás módulos; recibe el jugador porque lee un permiso.
boolean isInStaffMode(UUID)Si tiene una sesión de staff abierta.
boolean isVanished(UUID)Si está oculto para los jugadores por debajo de su nivel de vanish.
boolean isFrozen(UUID)Si está congelado y no puede actuar.
boolean isSpectator(UUID)Si su sesión de staff está atravesando bloques.
boolean isXrayVisionActive(UUID)Si está viendo minerales a través de la piedra.

Vanish#

MétodoQué hace
int vanishLevel(Player)Su nivel de vanish, 0 si no tiene ningún nodo de nivel. Lee permisos, así que recibe el jugador.
int hiddenLevel(Player)El nivel al que está oculto ahora mismo: su vanishLevel, o menor mientras lo eligió con /vanish level.
boolean canSee(Player viewer, Player target)Si el observador puede ver al objetivo ahora mismo: que no esté en vanish, que tenga permiso para ver a los que sí, y la comparación de niveles, en ese orden.

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#

MétodoQué hace
boolean isStaffChatToggled(UUID)Si su chat normal va al chat de staff.
GlobalChatMode globalChatMode(UUID)Hasta dónde llega su chat. OFF si el módulo está apagado o si nunca lo subió.
boolean receivesMiningAlerts(UUID)Si recibe avisos de minería sospechosa.

Listas#

MétodoQué hace
List<UUID> onlineStaff()Todo el que en este servidor cuenta como staff, sin orden particular.
List<UUID> onlineInStaffMode()Todo el que en este servidor tiene una sesión de staff abierta.
List<UUID> onlineVanished()Todo el que en este servidor está en vanish. Lo que una lista de tab o un contador de jugadores resta.

Las tres 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. Las listas son inmutables. Filtrá onlineVanished() con canSee cuando la lista es para un solo espectador.

Reportes#

MétodoQué hace
int openReportCount()Reportes esperando al staff, en toda la red: cada servidor tiene la cola abierta.
int openReportsAgainst(UUID target)Reportes abiertos que nombran a un jugador. Los reportes cerrados no cuentan.
ReportResult report(Player reporter, Player target, String reason)Envía un reporte igual que /report <player> <reason>.

report corre las mismas comprobaciones que el comando (no a uno mismo, la protección del staff, el cooldown, el límite de reportes abiertos) y le explica un rechazo a quien reporta con las palabras del propio plugin. Una razón que coincide con un id de razón configurado se guarda como esa razón, con su peso; cualquier otra cosa es texto libre. Una razón en blanco lanza IllegalArgumentException. Llamalo en el hilo de quien reporta.

ReportResultSignificado
SUBMITTEDAceptado. La alerta al staff y la confirmación a quien reporta llegan una vez escrita la fila.
SELFQuien reporta se nombró a sí mismo.
STAFF_PROTECTEDEl objetivo es staff y el dueño no permite reportar al staff.
ON_COOLDOWNQuien reporta envió otro reporte hace muy poco.
TOO_MANY_OPENQuien reporta ya tiene tantos reportes abiertos como se permite.
CANCELLEDUn listener canceló el PlayerReportEvent.
MODULE_DISABLEDEl módulo de reportes está apagado.

Todo rechazo salvo CANCELLED y MODULE_DISABLED ya se le explicó a quien reporta, así que quien llama solo tiene que decir algo en esos dos casos.

Módulos#

MétodoQué hace
boolean isModuleEnabled(String moduleId)Si esa función está corriendo ahora mismo. Un id desconocido simplemente no está habilitado.
Set<String> enabledModules()Todos los módulos que están corriendo, en un set inmutable.

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.

MétodoQué hace
boolean mayEnterStaffMode(Player)Si tiene permitido abrir una sesión. Preguntalo para esconder un botón en vez de que el jugador lo apriete y reciba un no.
boolean enterStaffMode(Player)Abre una sesión de staff.
void exitStaffMode(Player)Cierra la sesión y le devuelve su propio inventario. Se registra como salida administrativa, porque la terminó algo que no fue su propio comando.
void setVanished(Player, boolean vanished, boolean silent)Oculta o muestra a un jugador. silent se saltea la confirmación y el efecto, para un vanish puesto por algo que no fue su propia mano.
void freeze(Player target, Player staff)Congela a un jugador. El miembro del staff queda nombrado en el registro y en el aviso.
void unfreeze(Player target, Player staff)Libera a un jugador congelado.
void sendStaffChat(Player, String message)Manda un mensaje al chat de staff. El emisor tiene que tener permitido usarlo.
void setGlobalChatMode(Player, GlobalChatMode)Define hasta dónde llega el chat de un miembro del staff.

GlobalChatMode#

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

ConstanteAlcance
OFFSolo el chat a su alrededor, aislamiento incluido.
GLOBALTodos los chats de este servidor, sea lo que sea que los aísle.
NETWORKEso, más cada línea de chat de todos los demás servidores de la red.

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#

Cinco eventos, en net.exylia.lib.api.staff.event. Dos informan de lo que ya pasó; dos dejan que otro plugin rechace un freeze o un reporte antes de que ocurra; uno avisa de que un jugador congelado se fue.

Lo agregado para reportes y freeze (onlineVanished, los métodos de reportes, ReportResult y los últimos tres eventos) necesita exylia-api de ExyliaLib v1.133.0 o posterior.

Lo que ya pasó#

StaffStateChangeEvent y StaffActionEvent 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.

EventoSe dispara cuandoTrae
StaffStateChangeEventUna pieza del estado de staff de un jugador cambió.getPlayer(), getKind(), isEnabled()
StaffActionEventUn miembro del staff hizo algo que merece contarse.getStaff(), getAction(), getTarget()

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#

TipoSignificado
STAFF_MODESe abrió o se cerró una sesión de staff.
VANISHEl jugador fue ocultado o mostrado.
FROZENEl jugador fue congelado o liberado.
STAFF_CHATSu chat normal ahora va al chat de staff, o dejó de ir.
GLOBAL_CHATCambió el alcance de su chat; isEnabled() es false solo para apagado.
MINING_ALERTSEmpezó o dejó de recibir avisos de minería sospechosa.
XRAY_VISIONEmpezó o dejó de ver minerales a través de la piedra.
REVEALEmpezó o dejó de ver a los jugadores que oculta una poción de invisibilidad.
SPECTATORSu sesión de staff entró o salió de espectador.

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.

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

Freezes y reportes#

EventoSe dispara cuandoCancelableTrae
PlayerFreezeEventUn jugador está por ser congelado, con /freeze o freeze(...), una vez que el plugin lo aceptó y antes de que le pase nada.SígetTarget(), getStaff()
PlayerReportEventUn jugador está reportando a otro, una vez superadas todas las comprobaciones y antes de guardar nada o alertar a nadie. Se dispara para /report, el menú de razones y report(...).SígetReporter(), getTarget(), getTargetName(), getReason()
FrozenPlayerQuitEventUn jugador congelado salió del servidor.NogetPlayer(), getStaffId(), getStaffName()

Cancelar PlayerFreezeEvent deja libre al objetivo; cancelar PlayerReportEvent no guarda nada, no alerta a nadie y no inicia ningún cooldown. En los dos casos no se le dice a nadie por qué, porque el listener que lo rechazó es el único que lo sabe: un plugin de partidas que protege a un jugador en plena pelea debería decirlo él mismo. Una liberación nunca se rechaza. PlayerReportEvent se dispara una sola vez, en el servidor de quien reporta, lo que lo convierte en el que escucha un webhook de Discord o una verificación cruzada con el anticheat. getReason() es texto plano escrito por un jugador: tratalo como entrada.

FrozenPlayerQuitEvent es el gancho para lo que un servidor hace con alguien que se desconecta de un screenshare. Se dispara después de que la sesión terminó en este servidor, así que isFrozen ya responde false (con persist-on-quit activado, el freeze se vuelve a aplicar cuando entra de nuevo), y después de que corrieron los quit-commands del propio plugin. getStaffId() es null cuando lo congeló la consola. No se dispara mientras el servidor se está apagando.

java
@EventHandler
public void onFrozenQuit(FrozenPlayerQuitEvent event) {
    webhook.send(event.getPlayer().getName() + " logged out while frozen by " + event.getStaffName());
}

Lo que no expone#

Nada de abridores de menú, flujos de editor, filas de sanciones o de reportes, ni escrituras de configuración. 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.

¿Falta algo en esta página? Dínoslo en Discord