Contenido generado con IA — puede contener errores.

ExyliaLib/Interfaces

Items

Un item descrito en YAML — icono de menú, entrada de kit, item especial o escudo — leído una vez y dibujado por jugador.

Página 20 de 549 min de lectura

Un icono de menú, un item especial, una entrada de kit, un slot de hotbar de lobby y un escudo son el mismo bloque de YAML. Este es el único parser para todos ellos.

java
PluginItems items = Items.of(this);
 
Item icon = items.parse(section);              // una vez, al cargar el archivo
ItemStack stack = items.render(icon, player);  // cada vez que alguien lo mira

Item es una definición, no un ItemStack. Guarda sus placeholders sin resolver, la comparten todos los jugadores que la ven, y se puede comparar, cachear y testear sin un servidor en marcha. Convertirla en item es trabajo por jugador.

El objeto#

material decide qué es el item, y lleva más que un nombre de material:

Escrito comoSignifica
DIAMOND_SWORDUn material
%kit_icon%Un material que decide el lector
basehead-<base64>Una cabeza, por textura
urlhead-<url>Una cabeza, por URL de skin
playerhead-NotchUna cabeza, por nombre de jugador
playerhead-%player_name%Una cabeza cuyo dueño depende de la fila
bytes:<base64>Un item serializado

Tanto - como : separan el prefijo de su carga, sin distinguir mayúsculas. Las cabezas nunca bloquean: una textura o una URL no tocan la red, y una cabeza de jugador que aún no se ha descargado vuelve en plano.

Un placeholder se lee dos veces

material: "%arena_icon%" es un material cuando se lee el archivo, porque es todo lo que puede ser antes de que alguien lo rellene. El texto ya resuelto vuelve a pasar por la tabla de arriba — así que %arena_icon% con headbase-eyJ0… dibuja la cabeza. Solo se leen dos veces los valores que llevaban placeholder.

Texto#

ClaveSignificado
nameEl nombre pintado en el item.
display-nameEl nombre en forma plana, para mensajes y logs.
loreLíneas del tooltip. <nl>, saltos reales y \n literales parten una entrada en varias.
amountTamaño de pila, como número o placeholder.

name y display-name son separados, no una pareja con alternativa: uno se pinta en el item — negrita, con degradado, con un contador dentro — y el otro es lo que un plugin le cita a un jugador.

Aspecto#

ClaveSignificado
glow, glowingEl brillo de encantamiento, sin línea en el tooltip.
hide-tooltipOculta el tooltip entero.
hide-attributesOculta todo lo que escribe vanilla por su cuenta.
unbreakableLo marca irrompible.
custom-model-dataEl número de modelo.
max_stack_sizeEl límite de pila.
flags, item-flagsNombres de ItemFlag a ocultar.
item_modelUna clave de modelo, namespace:key.
tooltip_styleUna clave de estilo de tooltip.
enchantmentsUna sección de NOMBRE: nivel, o una lista de NOMBRE:nivel.

Las grafías con guion bajo y con guion funcionan las dos.

Traits#

Solo algunos materiales los tienen, así que viven en un record aparte — los otros miles de items llevan una referencia compartida en vez de seis campos nulos cada uno.

yaml
potion:
  base_type: HEALING
  upgraded: true            # STRONG_HEALING
  color: "#ff4d4d"
  custom_effects:
    - type: SPEED
      amplifier: "%level%"  # resuelto por jugador
      duration: 600
 
armor_trim:
  pattern: "%helmet_trim_pattern%"
  material: "%helmet_trim_material%"
 
banner_patterns:
  base_color: WHITE
  patterns:
    - pattern: STRIPE_BOTTOM
      color: LIGHT_GRAY
 
banner_design: "%shield_preview%"   # un diseño calculado por jugador
 
force-consumable: true
consumable-time: 1.0
consumable-nutrition: 6
consumable-saturation: 14.4
consumable-sound: ITEM_HONEY_BOTTLE_DRINK
 
attributes:
  - "attack_damage|8"
  - "movement_speed|0.05"
 
nbt:
  kind: special
  uses: 3

Un trait que no encaja con su material no hace nada. Una poción puesta en una espada es una clave sobrante en un archivo de config, no un motivo para fallar mientras se dibuja un menú.

Por qué `nbt` necesita un plugin

Los valores escritos con nbt se guardan bajo el namespace del plugin dueño, así que dos plugins pueden escribir id en un item sin chocar. Items.parse sin plugin está bien para definiciones que no guardan valores, que son casi todas.

Objetos que no son lo que aparentan#

Los objetos propios de un plugin se dibujan con el material que les venga bien, y el material es sobre lo que actúa el servidor: una ficha dibujada como perla del end es una perla que se lanza, una dibujada como comida se come, una dibujada como bloque se coloca. Todas esas gastan algo que el jugador tenía que conservar.

java
PluginItems items = Items.of(this);
items.inert("item");     // la clave de datos que llevan los objetos de este plugin

Todo lo que lleve esa clave pasa a ser inerte: usarlo no hace nada. Se puede seguir cogiendo, tirando, comerciando, metiendo en un cofre y clicando en un menú — simplemente se niega a gastarse como el objeto que aparenta. Pedirlo dos veces reemplaza las claves en vez de registrar un segundo guardián, así que un plugin que se recarga en caliente no acaba con uno por recarga.

Guardar lo que alguien lleva en la mano#

La otra dirección, para un selector de iconos:

java
String icon = Source.of(player.getInventory().getItemInMainHand()).raw();

Un item normal se guarda como su nombre de material — STONE, no cuatrocientos caracteres de base64. Cualquier cosa con meta se guarda entera como bytes:. Una mano vacía es AIR.

El nombre y el lore se descartan. Se conserva todo lo que el item aparenta — modelo, color, patrones, brillo — pero quien dibuja el icono escribe su propio nombre y lore. Son además casi todo el tamaño de un item: el nombre con degradado de una espada de kit se serializa como JSON de componentes y se pasa de los 512 caracteres que admite una columna de icono.

Nombrarlo para una persona#

java
Source.of(config.icon()).label();      // "Nether Star"
Guardado comoSe lee como
NETHER_STARNether Star
playerhead-NotchNotch's Head
basehead-…, urlhead-…Custom Head
playerhead-%player_name%Player Head
bytes:…El material que hay dentro, o Custom Item

label() es para una persona; raw() es lo que vuelve a una config o a una columna.

Dibujarlo de vuelta#

java
ItemStack icon = Items.icon(home.icon());

Una llamada, toda la gramática, sin plugin y sin jugador — para quien tiene una cadena suelta salida de una columna. Un icono de menú no lo necesita: escribe material: "%home_icon%" y la fila lo resuelve con el jugador.

Lo ilegible vuelve como papel

Una cadena que no nombra nada, o un bytes: que no se puede decodificar, se dibuja como papel y no como nada. Una fila ilegible sigue siendo una fila que alguien tiene que ver y borrar, y el papel se lee como "esto no se pudo leer" donde un bloque de piedra se lee como la configuración de alguien.

Guardar un item que es el premio#

Source.whole(stack).raw() es la misma lectura sin tirar nada: nombre, lore, encantamientos y atributos. Úsalo cuando el item guardado se le devuelve a un jugador — una recompensa, un slot de kit, el stock de una tienda — y Source.of cuando solo se dibuja. Cuesta longitud: un nombre con degradado se serializa como JSON de componentes, así que la columna necesita sitio.

Items dentro de items#

Containers lee shulkers y bundles igual, desde el propio item, así que es seguro en cualquier hilo.

java
if (Containers.isContainer(stack)) rows = Containers.contentsOf(stack);
ItemStack inner = Containers.resolve(kitItems, "6.13");
if (Containers.isBlocked(stack, settings.blockedMaterials())) refuse();
ItemStack repacked = Containers.withContents(box, remaining);
LlamadaResponde
isContainer(item)Un bundle o una shulker.
contentsOf(item)Lo que hay dentro, con sus posiciones, null para un slot vacío.
isFilled(item), count(contents)Si hay algo dentro, y cuántos stacks no vacíos tiene una lista de contenido.
resolve(items, "6.13")La posición 6 de la lista, y luego la 13 de lo que había dentro. parentOf, child y depth recorren la ruta.
isBlocked(stack, names)Si el stack, o algo que lleve a cualquier profundidad, está en una lista de materiales. Una caja no sirve para saltarse una lista de bloqueo.
withContents(item, contents)Una copia con otro contenido: una shulker toma los primeros 27 slot a slot, un bundle los no vacíos en orden. Cualquier otra cosa vuelve sin cambios.

Items como palabras#

ItemTexts convierte un item en texto para mensajes y logs:

LlamadaResponde
describe(stack)El nombre visible como texto plano, o el material en palabras: Diamond sword.
enchantments(stack)Sus encantamientos, incluidos los guardados de un libro. enchantmentName(e) nombra uno.
summary(stack)Una línea de auditoría: 1x "Loot" Shulker Box{3x Diamond}. También para una plantilla y cantidad, o una lista.

Un nombre visible son palabras de un jugador: insértalo en un mensaje con Values.putText, nunca como texto interpretado.

En qué estante va un item#

java
ItemGroup group = ItemGroup.of(Material.DIAMOND_PICKAXE);   // TOOLS

ItemGroup.of(material) responde BLOCKS, TOOLS, ARMOUR, FOOD, REDSTONE, ENCHANTED_BOOKS, POTIONS o MISC, así las pestañas de categoría de un mercado y el filtro de una lista de precios coinciden. id() es como se escribe en config (enchanted-books) e ItemGroup.byId lo vuelve a leer, armor incluido. Un plugin que quiera otra respuesta para un material pone sus propias excepciones delante.

Loadouts#

Un kit, un loadout de arena o el equipo de una clase es una lista plana de 41 posiciones, en el orden en que un jugador lee un inventario:

PosicionesParte
0–3Casco, peto, pantalones, botas.
4Mano secundaria.
5–31Los 27 slots de almacenamiento.
32–40Los 9 slots de la barra rápida.
java
List<ItemStack> kit = Loadout.capture(player);           // lo que lleva puesto y encima, recortado
 
Editors.of(this).loadout(kit)                            // un editor con forma de inventario
        .title("{primary}&lEDIT KIT")
        .onSave(items -> kits.save(id, items))
        .open(player);
 
List<String> diff = Loadout.differences(layout, kit.toArray(ItemStack[]::new));
boolean fair = Loadout.isRearrangement(layout, kitItems);

Loadout.partOf(index) nombra una posición, y Loadout.at(items, index) lee una (pasado el final es null, no un error). Un loadout termina en su último item.

differences compara la distribución que hizo un jugador con el kit del que salió: las posiciones y cómo se reparten los stacks no cuentan, solo cuántos hay de cada item. Cada línea es +n item si sobra o -n item si falta; vacío significa que es una redistribución legítima. Los items se comparan tal como los guarda un inventario, y se ignora el aspecto — nombres, lore, tinte, trims, patrones de estandarte, modelos — porque nada de eso da ventaja.

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