06.01. Crear fuentes STORE

Un archivo .store es un manifiesto de payloads etiquetados. Cada label debe ser único dentro de la fuente y cada entrada puede seleccionarse después por ese nombre.

Cabecera

Toda fuente comienza con el magic exacto y una versión soportada:

MAGIC "store"
VERSION 1

Usa VERSION 1 para payloads locales/raw. Usa VERSION 2 cuando haya declaraciones tipadas, @REQST o conversión de fuentes TTF:

MAGIC "store"
VERSION 2

Solo las versiones 1 y 2 están soportadas actualmente. La versión 3 queda reservada para futuras funciones del lenguaje, como funciones o macros.

Items de media y binarios opacos

La forma por bloque tiene exactamente cuatro campos, en este orden:

@ITEM BINARY
: "config.bin"       ; ruta relativa a la carpeta del .store
: "bin"               ; formato de origen
: "RAW"               ; formato de salida/datos
: config_blob         ; label
@end

Los tipos de item soportados son IMAGE, AUDIO y BINARY.

Para IMAGE y AUDIO, el tercer campo es el formato de salida del plugin, como el formato soportado por el conversor seleccionado. La extensión del archivo debe coincidir con el formato declarado. En BINARY, raw significa bytes opacos, no un parser ni un ensamblador.

Fuentes TTF

VERSION 2 puede consumir una fuente local .ttf mediante @FONT. La entrada siempre es TTF; el perfil de salida decide si se guardan los bytes originales o un atlas bitmap:

@FONT raw_font:
    source "assets/font.ttf"
    output BYTES
@end

@FONT gba_font:
    source "assets/font.ttf"
    output BITMAP
    pixel_format MONO1
    size 8
    cell_width 8
    cell_height 8
    glyphs ASCII_PRINTABLE
    layout GRID
    columns 16
@end

BYTES copia el TTF exactamente y no requiere Pillow. BITMAP usa el plugin de fuentes para crear un atlas GRID en orden por filas. Los formatos de píxel soportados son MONO1 (un bit MSB-first por píxel), GRAY8 (un byte de alpha por píxel) y RGBA8888 (glifos blancos con el alpha rasterizado). ASCII_PRINTABLE selecciona los códigos 0x20 a 0x7E; ASCII selecciona 0x00 a 0x7F; cualquier otro valor entre comillas en glyphs se interpreta como una secuencia explícita de caracteres. columns controla el ancho del atlas. Cada bloque @FONT crea una entrada raw usando su nombre como label.

La conversión bitmap requiere Pillow y solo acepta rutas locales. La fuente debe terminar en .ttf y los límites de recursos se aplican tanto a la entrada como al atlas generado.

Bloques binarios inline

VERSION 2 puede contener un payload binario raw directamente en la fuente. Usa @BINARY, un label identificador, una o más líneas de bytes hexadecimales de dos dígitos y @END:

MAGIC "store"
VERSION 2

@BINARY MODE_3
01 03 A0 E3,
03 10 A0 E3 01 1B 81 E3
B0 10 C0 E1
@END

Los espacios separan bytes y las comas son opcionales. También se acepta el prefijo 0x. El bloque se guarda como un único payload opaco y no ejecuta plugins. @BINARY está limitado a la versión 2; para la versión 1 usa @FILE o @ITEM BINARY.

Valores tipados de bytes exactos

Los valores tipados requieren VERSION 2:

MAGIC "store"
VERSION 2

str greeting = "Hello, world"
uint8 age = 30
int32 count = -2
float32 decimal = 13.0000

Los valores son únicamente literales. No hay expresiones, asignaciones, actualizaciones en runtime ni conversiones de tipos. Los rangos enteros se comprueban según el ancho y los floats deben ser finitos.

El tipo declarado se conserva en el índice de un storage versión 2 para que el consumidor pueda aplicar después un layout de bytes. El payload ya está codificado en la forma canónica little-endian.

Añadir un archivo local

@FILE copia un archivo local arbitrario como bytes raw:

@FILE "myfile.bin"
@FILE "headers/boot.dat" AS boot_header

Sin AS, el label es el nombre base del archivo (myfile en el primer ejemplo). La ruta es relativa al .store y debe permanecer dentro de su carpeta: se rechazan rutas absolutas y recorridos con ...

Solicitar un binario acotado de GitHub

@REQST requiere VERSION 2 y un archivo .bin alojado en GitHub:

@REQST algorithm "github.com/owner/repository/path/algorithm.bin/main"

También se acepta https://github.com/.... La ruta debe terminar en una rama, contener una ruta de archivo .bin y no puede incluir credenciales, query strings, fragmentos ni recorridos. Solo se siguen hosts HTTPS de GitHub. La petición tiene timeout de 15 segundos y está limitada a 16 MiB, o al límite global configurado si es menor.

@REQST adquiere bytes raw, no ejecuta código. El archivo descargado se guarda con el label declarado sin usar plugins de imagen o audio.

Importar entradas de otro contenedor

Usa @CONTAINER para copiar entradas etiquetadas de un storage validado:

@CONTAINER "variables/vars.storage.bin":
    get etiqueta1
    get etiqueta2
@end

La ruta es local a la carpeta del .store actual y tiene las mismas restricciones de seguridad que @FILE. Las entradas conservan sus labels y bytes originales. Se recomienda escribir @end; solo puede omitirse cuando el bloque es el último de la fuente.

Si una entrada seleccionada tiene metadatos tipados de la versión 2, la fuente que importa también debe ser VERSION 2; la versión 1 solo puede contener entradas raw.

Restricciones

• Los labels deben ser identificadores como config_blob o MODE_3 y ser únicos.
• Las rutas se resuelven desde la carpeta del .store, no desde el directorio de trabajo del proceso.
• Un item BINARY no es un entero tipado; usa una declaración tipada cuando importe el ancho y la representación numérica.
• Una declaración tipada no es una variable de runtime: es un payload fijo.
• La conversión de IMAGE y AUDIO es explícita. Usa BINARY o @FILE si el origen debe conservarse byte por byte.