Items

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.

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:

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.

Texto

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

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.

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

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.

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:

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

Source.of(config.icon()).label();      // "Nether Star"

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

Dibujarlo de vuelta

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.