Kit de interfaz de juego UIDoc

Da estilo a las pantallas UIDoc terminadas con el kit de UI de juego dibujado a mano del motor: el mecanismo @import, la referencia de clases, las reglas de ensamblaje y ejemplos prácticos.

---

El kit de UI del juego es el conjunto de UI dibujado a mano del equipo de arte ($AO/ui/kit/Game UI/**): modales, botones, pestañas, barras de progreso, banners, portillas, ranuras de objetos, casillas de verificación y conmutadores. El motor incluye una hoja de estilo compatible, de modo que cualquier asset UIDoc pueda adoptar el aspecto del kit sin copiar CSS.

Aplica el kit como un último paso de estilización. Construye primero la pantalla — diseño, enlaces, eventos, comportamiento de la ventana gráfica — verifica que funcione y luego aplícale el aspecto. El estilo del kit es pintura y relleno; nunca debe ser la herramienta para arreglar el diseño.

Cómo habilitar el kit

Añade una línea al index.css:

@import "game-ui-kit";

En tiempo de compilación, el motor sustituye res/ui/kit/kit.css en lugar de la importación, así que pon primero la importación y debajo tus propias reglas — tus reglas ganan los empates de cascada. La importación se compone con las utilidades de Tailwind. Editar la hoja de estilo del motor vuelve a compilar los assets que la importan en la siguiente compilación; UIDoc sigue sin recargarse en caliente en una partida en ejecución.

El único patrón que debes conocer

UIDoc no tiene fondos CSS de mapa de bits, así que el arte del kit entra a través de elementos ordinarios img Cada contenedor del kit es un elemento posicionado cuyo primer hijo es una .kit-bg imagen; el div posee la forma y el diseño, la imagen solo pinta, con nine-slicing mediante ajustes de asset que vienen con el kit:

<div class="kit-modal">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_simple_grey1.png">
  <!-- content -->
</div>

.kit-bg es object-fit: fill para arte con nine-slicing (modales, botones, pestañas, barras, banners). El arte de aspecto fijo (casillas de verificación, conmutadores, portillas, iconos de ranura) usa .kit-bg--contain y el propio ancho/alto del contenedor.

Usa .kit-bg--shadow en el fondo real img cuando el arte deba proyectar una sombra. Usa una drop-shadow(...), sensible al alfa, así que las esquinas transparentes y el resultado pintado del nine-slicing definen la silueta. Un box-shadow sigue en cambio el cuadro delimitador rectangular del contenedor, mientras que poner drop-shadow(...) en el contenedor también incluiría su texto y otros descendientes.

Coloca el texto visible del botón/pestaña en un elemento de etiqueta en primer plano después del arte. El texto sin procesar que pertenece al contenedor puede pintarse debajo de su imagen hija:

<button class="kit-btn kit-btn--green">
  <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_green1.png">
  <span class="kit-btn-label">JUGAR</span>
</button>

El kit baja visualmente las etiquetas directas de botones 5 px para que coincidan con el arte. Para un frente compuesto, como un icono más un precio, envuelve todo el frente en .kit-btn-content para que el icono y el texto se muevan juntos:

<button class="kit-btn kit-btn--green">
  <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/shiny_buttons/button_large_green1.png">
  <span class="kit-btn-content price">
    <img src="coin.png">
    <span class="kit-btn-label">300</span>
  </span>
</button>

Referencia de clases

Clase	Usa
.kit-bg, .kit-bg--contain, .kit-bg--shadow	Imagen de fondo artística, ajuste de aspecto fijo y sombra de imagen sensible al alfa
.kit-fg	Capa genérica de primer plano por encima de .kit-bg
.kit-modal	Panel posicionado en columna flex con relleno del kit
.kit-modal-header	Área segura del título centrado con 72 px reservados a ambos lados
.kit-modal-title	Fila de título centrada; combínala con .kit-text-header
.kit-title-banner	pointy_banner_* fondo detrás de un título de modal, completamente dentro del modal
.kit-header-band	modal_header_* franja a lo largo del borde superior pintado del modal
.kit-dim	Oscurecimiento de pantalla completa detrás de un modal
.kit-btn, .kit-btn-label, .kit-btn-content, .kit-btn--<colour>	Arte del botón más una etiqueta o grupo de primer plano rebajado visualmente con un contorno que coincide con el color
.kit-tab-row, .kit-tab, .kit-tab-label, .kit-tab--active	Fila de navegación de pestañas tipo pastilla con etiquetas de primer plano
.kit-progress, .kit-progress-fill, .kit-progress--N, .kit-progress--compact	Pista más relleno vinculado; el modificador de familia alinea el relleno y compacta selecciona la escala de 30 px
.kit-card, .kit-list-row	Contenedores estructurales para tarjetas y filas respaldadas por arte
.kit-close	Control de cierre de primer plano anclado de forma absoluta en la esquina superior derecha del modal
.kit-slot, .kit-slot-icon, .kit-slot-qty	Cuadro de inventario/tienda con icono y cantidad
.kit-porthole	Marco circular; apila *_back.png debajo de *_ring.png
.kit-checkbox, .kit-toggle	Controles de estado de aspecto fijo
.kit-text-header/body/body-dark/info	Los cuatro estilos de texto aprobados del documento de arte

Los tamaños de texto siguen el documento de arte (65/55/45/40) en la ventana gráfica lógica estándar; sobrescríbelos en el asset cuando una pantalla necesite una escala diferente.

Reglas de ensamblaje

Esto proviene de la documentación Game UI del equipo de arte y de la práctica establecida; las clases codifican la mayor parte, los patrones de marcado cubren el resto.

• Títulos: blanco, Heavy, contorno negro, sombra proyectada (.kit-text-header), colocados directamente sobre el modal, sobre una .kit-title-banner (fondo de banner oscuro, completamente dentro del modal — evita el banner puntiagudo marrón "amarillo"), o sobre una .kit-header-band cuando la combinación de colores funciona: una banda saturada sobre un modal claro (rojo sobre blanco) se lee bien; apagado sobre apagado (dorado sobre gris) no. Cuando tengas dudas, el texto de título simple siempre es seguro.
• Encabezados de modal cerrables: mantén .kit-close como hijo directo de .kit-modal, donde permanece anclado de forma absoluta en la parte superior derecha. Coloca el título o el banner de título dentro de .kit-modal-header; sus reservas laterales simétricas de 72 px mantienen el título visualmente centrado y libre del control de cierre. Calcula el ancho del modal como el ancho deseado del título/banner más ambas reservas de 72 px más el relleno izquierdo y derecho del panel. Esto hace deliberadamente que los modales cerrables sean un poco más anchos que el contenido del cuerpo ajustado al mínimo.
• Sombras del arte: box-shadow sigue un cuadro delimitador rectangular. Para arte irregular o de kit con nine-slicing, pon .kit-bg--shadow en el fondo real img para que la sombra siga su alfa pintado. No pongas el filtro en .kit-modal, porque eso incluiría el texto del modal y el arte hijo en la silueta de la sombra.
• Botones: el texto es blanco con un contorno de color que complementa el arte del botón — nunca negro. Coloca una etiqueta simple directamente en .kit-btn-label para que se pinte por encima del arte y reciba el desplazamiento de línea base óptico de 5 px del kit. Para contenido con icono y texto, coloca ambos dentro de un .kit-btn-content hijo directo para que el par reciba ese desplazamiento juntos. Usa shiny_buttons para compras e interacciones especiales, basic_buttons para todo lo demás, y dale al texto un relleno generoso. El botón gris es el aspecto deshabilitado.
• Texto del cuerpo: contorno sutil con 20 % de opacidad (.kit-text-body) en modales de color; texto oscuro sin adornos (.kit-text-body-dark) en modales blancos/grises.
• Pestañas: una fila tipo pastilla dentro de el cuerpo del modal, no pegada al borde superior. Coloca el texto en .kit-tab-label. Active tab uses a colour art variant (e.g. tabs_blue) con un contorno de texto a juego; las pestañas inactivas usan tabs_black. Usa tab_med.png o tab_large.png para etiquetas dinámicas. Los archivos fuente de tab_small.png son inconsistentes y algunos contienen etiquetas horneadas, por lo que intencionalmente no están segmentados en nueve.
• Barras de progreso: cada carpeta progress_bar_N empareja un backing.png con un fill_*.pnghecho a medida, pero los desplazamientos internos difieren por familia y a menudo son asimétricos por el borde inferior/la sombra proyectada. El arte de la pista va en .kit-bg; el relleno compatible de la familia va en .kit-progress-fill, que usa object-fit: fill; añade el .kit-progress--N modificador de familia correspondiente al contenedor y vincula data-style-image-fill-amount. No sustituyas una imagen icono teñida ni una imagen transparente decorativa: el tinte conserva el alfa de origen, y cover puede recortar arte cuadrado en huecos o cuñas diagonales en una pista delgada. Previsualiza la barra en 0, 0.25, 0.5, y 1; los diagnósticos actuales no detectan alfa de textura inadecuado. El componente predeterminado tiene 40 px de grosor; añade .kit-progress--compact para la forma de 30 px escalada proporcionalmente. Para un grosor personalizado, establece valores iguales de font-size y height en el contenedor para que sus sangrías familiares basadas en em se escalen con él. Las pistas del kit usan flex-shrink: 0; elige el grosor explícitamente en lugar de confiar en que un padre flex comprima la pista, lo que puede hacer que la pista y su relleno se resuelvan a tamaños distintos.
• Ranuras de objeto: cuadrados de color (inv_square_<colour>1.png) para ranuras llenas; inv_square_empty2.png es el estado VACÍO diseñado.
• El arte de la familia de modales comparte una sola escala (esquinas de 37 px, contorno de 6 px en píxeles de origen — los insets de corte suministrados ya tienen esto en cuenta). Las piezas pensadas para componerse, como una banda de encabezado sobre un modal, se alinean porque están dibujadas a la misma escala; no edites manualmente los valores de corte individuales.

Ejemplo: modal de ajustes

Los modales con franja (modal_stripe_*) llevan una banda inferior más oscura — coloca la fila de acciones sobre ella manteniéndola como el último hijo del flujo.

<div class="kit-modal settings">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_stripe_blue1.png">
  <div class="kit-modal-header">
    <div class="kit-modal-title kit-text-header">AJUSTES</div>
  </div>
  <button class="kit-close" data-on-click="event:settings:close">
    <img src="$AO/ui/kit/Icons/misc_icons_2/exit_button_small.png">
  </button>
  <div class="rows">
    <div class="row">
      <span class="kit-text-body">Música</span>
      <button class="kit-toggle" data-on-click="event:toggle:music">
        <img class="kit-bg kit-bg--contain" data-if="music.on" src="$AO/ui/kit/Game UI/Additional Elements/Sliders + Toggles/switch_long_on.png">
        <img class="kit-bg kit-bg--contain" data-if="music.off" src="$AO/ui/kit/Game UI/Additional Elements/Sliders + Toggles/switch_long_off.png">
      </button>
    </div>
    <div class="row">
      <span class="kit-text-body">Pase de temporada</span>
      <div class="kit-progress kit-progress--1 pass-progress">
        <img class="kit-bg" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/backing.png">
        <img class="kit-progress-fill" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/fill_yellow.png"
             data-style-image-fill-amount="pass.progress">
      </div>
    </div>
  </div>
  <div class="actions">
    <button class="kit-btn kit-btn--yellow" data-on-click="event:settings:save">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_yellow1.png">
      <span class="kit-btn-label">GUARDAR</span>
    </button>
    <button class="kit-btn kit-btn--red" data-on-click="event:settings:reset">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_red1.png">
      <span class="kit-btn-label">RESTABLECER</span>
    </button>
  </div>
</div>

@import "game-ui-kit";

.settings { width: 620px; }
.settings .rows { display: flex; flex-direction: column; gap: 18px; margin-bottom: 26px; }
.settings .row { display: flex; align-items: center; justify-content: space-between; gap: 20px; }
.settings .pass-progress { width: 260px; }
.settings .actions { display: flex; gap: 16px; justify-content: center; }

UI.uidoc_bind_bool("music.on", player.music_enabled);
UI.uidoc_bind_bool("music.off", !player.music_enabled);
UI.uidoc_bind_float("pass.progress", clamp(player.pass_progress, 0.0, 1.0));

Ejemplo: cuadro de confirmación (solicitud de batalla)

Una banda de encabezado saturada sobre un modal claro, texto oscuro en el cuerpo y un par aceptar/rechazar amarillo/rojo.

<div class="kit-modal battle">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_simple_white1.png">
  <div class="kit-header-band">
    <img class="kit-bg" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_header_red1.png">
    <div class="kit-modal-header">
      <span class="kit-text-header band-title">SOLICITUD DE BATALLA</span>
    </div>
  </div>
  <button class="kit-close" data-on-click="event:battle:close">
    <img src="$AO/ui/kit/Icons/misc_icons_2/exit_button_small.png">
  </button>
  <div class="kit-porthole challenger">
    <img class="kit-bg kit-bg--contain" src="$AO/ui/kit/Game UI/Additional Elements/Circle Portholes/blue_back.png">
    <img class="kit-bg kit-bg--contain" src="$AO/ui/kit/Game UI/Additional Elements/Circle Portholes/gold_ring.png">
  </div>
  <span class="kit-text-body-dark message">¡{{challenger.name}} te reta a una batalla!</span>
  <div class="actions">
    <button class="kit-btn kit-btn--yellow" data-on-click="event:battle:accept">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_yellow1.png">
      <span class="kit-btn-label">ACEPTAR</span>
    </button>
    <button class="kit-btn kit-btn--red" data-on-click="event:battle:decline">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_red1.png">
      <span class="kit-btn-label">RECHAZAR</span>
    </button>
  </div>
</div>

@import "game-ui-kit";

.battle { width: 680px; align-items: center; }
.battle .band-title { font-size: 55px; }
.battle .challenger { margin-bottom: 10px; }
.battle .message { text-align: center; margin-bottom: 24px; }
.battle .actions { display: flex; gap: 16px; }

Ejemplo: recompensa diaria

Un título respaldado por un banner en un modal gris, ranuras de recompensa, una barra de racha y un brillante botón de reclamar.

<div class="kit-modal reward">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_simple_grey1.png">
  <div class="kit-modal-header">
    <div class="kit-title-banner">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Additional Elements/Horizontal Banners/pointy_banner_blue.png">
      <span class="kit-text-header banner-title">RECOMPENSA DIARIA</span>
    </div>
  </div>
  <button class="kit-close" data-on-click="event:reward:close">
    <img src="$AO/ui/kit/Icons/misc_icons_2/exit_button_small.png">
  </button>
  <span class="kit-text-body-dark streak">Día {{streak.day}} — ¡sigue así!</span>
  <div class="slots">
    <div class="kit-slot" data-for="reward in rewards" data-for-key="reward.id">
      <img class="kit-bg kit-bg--contain" src="{{reward.back}}">
      <img class="kit-slot-icon" src="{{reward.icon}}">
      <span class="kit-slot-qty">{{reward.count}}</span>
    </div>
  </div>
  <div class="kit-progress kit-progress--1 streak-bar">
    <img class="kit-bg" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/backing.png">
    <img class="kit-progress-fill" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/fill_yellow.png"
         data-style-image-fill-amount="streak.progress">
  </div>
  <button class="kit-btn kit-btn--yellow claim" data-on-click="event:reward:claim">
    <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/shiny_buttons/button_large_yellow1.png">
    <span class="kit-btn-label">RECLAMAR</span>
  </button>
</div>

@import "game-ui-kit";

.reward { width: 600px; align-items: center; }
.reward .banner-title { font-size: 50px; }
.reward .streak { margin-bottom: 16px; }
.reward .slots { display: flex; gap: 12px; margin-bottom: 18px; }
.reward .streak-bar { width: 320px; margin-bottom: 22px; }

Las ranuras rellenas vinculan reward.back a $AO/ui/kit/Game UI/Item Backs/inventory_squares_1/inv_square_blue1.png (u otro color); las ranuras vacías usan inv_square_empty2.png sin icono.

Cobertura del arte

Los insets de nine-slice se incluyen en res/ui/kit/Game UI/.asset_settings para: Modales básicos (simples, con franja, con encabezados), botones básicos y brillantes, pastillas y trapezoides de pestañas de modal medianas/grandes, fondos/rellenos de barras de progreso horizontales (excluyendo sprites de segmento y barra fija de aspecto 12), banners puntiagudos horizontales y paneles interiores horizontales. Las piezas de aspecto fijo —incluidos los cuadrados de inventario, casillas de verificación, deslizadores y conmutadores, portillas, máscaras de ayuda y resaltados— no necesitan cortes. Otras familias (tarjetas, bocadillos de diálogo, banners elegantes, fondos de clasificación) existen en el kit pero todavía no tienen insets ajustados; mídelos antes de cortarlos y mantén las piezas compuestas a una sola escala compartida.