zablooGlosario
Las palabras en las que está escrito el resto de estas docs —envelope, IR, binding, named action, degradación— cada una en una frase llana y un ejemplo sacado de la misma pantalla de tienda.
Estas son las palabras en las que está escrita el resto de la documentación. Cada una tiene una frase llana y un ejemplo, y los ejemplos son todos de la misma pantalla: la tienda del gremio que construye la guía de primeros pasos, con un contador de oro y una lista de cosas que comprar. Lee la página una vez de arriba abajo y la referencia del formato deja de necesitar notas al pie; a partir de ahí, vuelve aquí por enlace cada vez que una página use una palabra que no conozcas.
Los términos se quedan con su nombre inglés, que es el que verás en el código, en la IR y en el resto del producto.
Lo que se publica
Envelope
Un envelope es el único fichero JSON que el juego descarga y dibuja: un número de versión, un diccionario de tokens, una o más views, y las imágenes que usan.
La pantalla de tienda, su tema y sus iconos viajan juntos en un mismo envelope, y el juego lo carga igual venga de tu editor o de un hot-update. Página completa: Envelope.
{ "v": 1, "tokens": { … }, "views": { "shop": { … } }, "assets": { … } }
IR
La IR —representación intermedia— es el formato que va dentro del envelope: un árbol de nodos que lleva layout, estilo y las dos conexiones con el juego.
Son datos y solo datos. No puede bifurcar, ni calcular, ni llamar a nada, que es lo que hace seguro mandarla a un juego publicado hace meses: un envelope nuevo cambia lo que ve un jugador sin cambiar lo que la build puede hacer. Sección completa: El formato.
{ "type": "Text", "text": { "bind": "player.gold" }, "style": { "fontSize": 20 } }
View
Una view es una pantalla dentro del envelope, guardada bajo un id por el que el juego la pide.
Un envelope lleva varias —hud, shop, settings— y el juego decide cuál
está en pantalla. En un proyecto recién creado, cada .tsx de src/views/ es
una view, y el nombre del fichero es el id.
"views": { "shop": { "type": "Container", "children": [ … ] } }
Token
Un token es un valor con nombre —un color, un espaciado, un radio— al que los estilos apuntan en vez de escribir el número ellos mismos.
El oro del contador de la tienda es {color.gold} en todos los nodos que lo
usan, así que retematizar la UI entera es un diccionario nuevo y no un árbol
nuevo. Por eso un tema se puede hot-updatear por su cuenta. Página completa:
Style y tokens.
"tokens": { "color.gold": "#facc15" },
"style": { "color": "{color.gold}" }
Lo que lo dibuja
SDK
El SDK es la librería de código abierto que instalas en tu motor: carga el envelope, lo maqueta, lo dibuja y le da al juego la API para manejarlo.
Unity es el SDK de referencia para la v1. @zabloo/renderer-web es el mismo
contrato en una página web — es lo que corre los previews en vivo de este
sitio, y lo que usa el preview de pnpm dev mientras escribes.
Renderer
El renderer es la mitad del SDK que dibuja: su propia pasada de layout, su propio teselador, su propio atlas de glifos.
Se dibuja a sí mismo, así que detrás de una UI de zabloo no hay DOM ni widget del motor — la pantalla de tienda se pinta en la GPU a partir del mismo envelope en todas partes. Por eso la página de producto puede dejarte pulsar Ejecutar sobre la cosa de verdad en vez de enseñarte una foto de ella.
Node, primitive, composite
Un node es un elemento del árbol de una view: un type, su layout, su
estilo, sus hijos.
Un primitive es uno de los trece tipos de nodo que define la IR — el
conjunto cerrado que documenta el catálogo, una página
cada uno. Un composite es un componente que @zabloo/react exporta por
comodidad —List, Row, Modal— que se aplana en primitivos al exportar y
nunca llega a la IR.
La lista de artículos de la tienda se escribe como <List>, un composite; lo
que el juego recibe es un nodo
Repeat, un primitivo.
Lo que se intercambian el juego y la UI
Dos palabras de este grupo sostienen todo el producto. Los datos son del juego; la UI solo dice dónde leerlos — eso es un binding. La UI dispara nombres, no funciones — eso es una named action. No hay un tercer mecanismo, y no hay nada más dinámico en el formato.
Binding
Un binding es una dirección dentro de los datos del juego, escrita donde iría un valor.
Al contador de oro no se le da un número: se le da player.gold, y lee lo que
el juego tenga ahí, remaquetándose cuando ese número se mueve. El juego empuja;
la UI sigue. Página completa:
Bindings y actions.
{ "type": "Text", "text": { "bind": "player.gold" } }
Data path
Un data path es esa dirección: segmentos separados por puntos, donde un segmento numérico indexa un array y ningún otro hace nada raro.
Leer un path es total — uno que no lleva a ninguna parte no da ningún valor, así que un binding cuyos datos aún no han llegado no dibuja nada en vez de romper el frame.
player.gold
shop.items.3.name
Named action
Una named action es una cadena que la UI dispara y a la que el juego se suscribe.
El botón de compra de la tienda declara "buy"; qué hace comprar vive en el
juego y nunca en el JSON. Eso es justo lo que permite sustituir la pantalla sin
tocar la build — la UI dispara nombres, no funciones, porque una función no se
puede serializar.
{ "type": "Button", "onClick": "buy" }
Action context
Un action context es lo que lleva consigo una action disparada desde dentro de una fila repetida, para que el juego pueda saber qué fila la ha disparado.
Sin él, todos los botones de compra de la tienda mandarían el mismo "buy"
pelado. Con él, el juego recibe el path del artículo, su clave estable y su
posición.
{ "path": "shop.items.3", "key": "sword-01", "index": 3 }
Host channel
El host channel es la API de runtime con la que el juego maneja la UI: siete operaciones de ida, tres callbacks de vuelta.
SetData("player.gold", 1250) mueve el número al que está bindeado el
contador; onAction es donde llega "buy". A propósito no forma parte del
envelope — son operaciones de runtime, y un documento no tiene dónde meterlas.
Página completa: El canal del host.
Cómo aguanta con el tiempo
Hot-update
Un hot-update es publicar un envelope nuevo para una build que los jugadores ya tienen instalada.
Como las pantallas viajan como datos, mover el botón de compra o añadir una fila a la tienda es un payload nuevo y no una build nueva: no se recompila nada y no se reinstala nada. También es la razón de que aquí un SDK que se encuentra contenido más nuevo que él sea el caso normal y no el caso de error.
Degradation
La degradation —la degradación— es lo que hace un SDK con las partes de un envelope que no reconoce, en vez de fallar.
Un tipo de nodo desconocido se dibuja como un
Container
conservando su layout, su estilo y sus hijos; una propiedad desconocida se
ignora; un valor desconocido dentro de un conjunto cerrado cae al valor por
defecto de esa propiedad. El resultado es una pantalla incompleta en vez de una
pantalla equivocada — y un envelope corrupto nunca se lleva el juego por
delante. Páginas completas: Loading y
Versionado.
Focus scope
Un focus scope es la región dentro de la cual se le permite moverse a la navegación con teclado y con mando.
Normalmente es la view entera. Mientras hay un
Overlay modal
levantado —el diálogo de “confirmar compra” de la tienda— el scope es el
subárbol de ese overlay: el mando no puede volver a la lista de detrás, y
cerrar el diálogo devuelve el foco a donde estaba. Página completa:
Input y focus.