Overlays

Un overlay dibuja objetos en el inventario del propio jugador solo en el cliente. El inventario real nunca se escribe, así que no se puede perder, duplicar ni dejar nada atrás.

PluginOverlays overlays = Overlays.of(this);
overlays.load("staff", getConfig().getConfigurationSection("staff-hotbar"));
 
overlays.show(player, "staff");   // entrando en modo staff
overlays.hide(player);            // saliendo

Por qué no cambiar el inventario y ya

Guardar el inventario, escribir las herramientas y devolver el viejo es lo obvio, y cada paso es una forma de perderle los objetos a alguien:

• Un crash, una desconexión o un autoguardado entre la escritura y la restauración guardan las herramientas en el mundo como objetos reales — herramientas de staff funcionales, con acciones atadas, en el cofre de alguien.
• Meter un objeto en un inventario real dispara el trigger de logro inventory_changed, así que un diamante decorativo reparte un logro.
• Un objeto recogido mientras las herramientas estorban o reemplaza una o se pierde.

Nada de eso puede pasar aquí: un crash pierde el cuento y conserva el inventario.

Escribir uno

El mismo formato que usan los objetos de un menú: mismo material, name, lore, actions, condition. Solo cambia el hueco, porque los huecos de un overlay son sitios del inventario del jugador.

lock: FULL          # FULL (por defecto) | OWNED
pickup: false       # por defecto true
hide_rest: true     # por defecto false
 
refresh:
  mode: SMART
  interval: 20
 
items:
  teleport:
    slot: 0
    material: COMPASS
    name: '{primary}&lTELETRANSPORTE'
    actions:
      - 'right: staff:random_teleport'
 
  leave:
    slot: 8
    material: BARRIER
    name: '{error}&lSALIR DE STAFF'
    actions:
      - 'any: staff:leave'

O en código, para un overlay que ningún archivo describe:

OverlayDefinition staff = OverlayDefinition.of("staff")
        .slot(0, UiItem.of(compass).bindings(bindings).build())
        .lock(OverlayLock.FULL)
        .pickup(false)
        .hideRest()
        .build();
overlays.show(player, staff);

Huecos

Numerados como los numera player.getInventory().setItem, que no es como los numera el cliente ni como los numera una ventana de contenedor. OverlaySlots convierte entre las tres; un archivo solo escribe la primera.

Los cinco huecos que se llevan puestos se pueden escribir por nombre — boots, leggings, chestplate, helmet, offhand — porque slot: 39 para un casco es un número que nadie recuerda. Los rangos y las listas funcionan como en todas partes: slots: "0-8", slots: ["0-2", "helmet"].

Los tres ajustes

Los rechazos son a nivel de paquete: el mensaje del cliente nunca llega al servidor, así que el servidor nunca lo responde con los objetos que de verdad tiene. Con los dos locks se rechaza cualquier clic cuyo destino elija el servidor y no el jugador — shift-clic, tecla numérica, cambio a la mano secundaria, doble clic, arrastre — venga del hueco que venga, además de tirar objetos, el intercambio de mano, el clic central y la escritura de hueco en creativo.

Qué ejecuta una pulsación

El mismo vocabulario de clics que responde un botón de menú, así que un objeto de overlay y uno de menú se escriben igual — salvo que el de overlay se pulsa en el mundo además de en la pantalla de inventario.

A las acciones se les pasa overlay.id, overlay.slot, overlay.click y — cuando la pulsación fue sobre algo — overlay.target y overlay.block. OverlayKeys les pone nombre.

Qué hace una mano vacía

empty_hand:
  actions:
    - 'right: staff:inspect'
  commands:
    - 'shift_right: player: co i'

Las mismas líneas que acepta un objeto, sin el objeto, para todos los huecos que el overlay posee y deja vacíos — las herramientas que responden a un sitio y no a un botón, como el clic derecho sobre un cofre para mirarlo por dentro.

Redibujado y ciclo de vida

refresh es el bloque de los menús y significa lo mismo: SMART redibuja solo lo que puede cambiar, FULL lo redibuja todo y ON_CLICK redibuja lo que se pulsó. Un overlay estático no arranca ningún temporizador, y un hueco que se dibuja idéntico a lo que hay en pantalla no manda paquete.

overlays.refresh(player);              // ahora, sin esperar al temporizador
overlays.isShowing(player);
overlays.showing(player);              // Optional<OverlayDefinition>
overlays.hide(player);
overlays.hideAll();
Overlays.hide(player);                 // lo pusiera quien lo pusiera
Overlays.worn();                       // cuántos jugadores llevan uno

Un jugador lleva un overlay a la vez, lo haya puesto quien lo haya puesto: mostrar un segundo quita el primero. Todo lo que puso un plugin se quita al desactivarlo, así que un reload nunca deja a nadie con botones cuyas acciones vienen de un classloader que ya no existe.

Todos los métodos son seguros desde cualquier hilo; lo que toca a un jugador salta antes a su hilo, así que se comporta igual en Folia.