Schemas — descripciones de acciones, comandos y campos de datos

Schemas es una biblioteca: permite a cada mod describir, como datos, qué aceptan sus acciones de escenario, cómo son sus comandos DSL y qué campos tienen sus tipos de datos. A partir de esa descripción, las herramientas construyen formularios, selectores y comprobaciones, de modo que el autor rellena un formulario en lugar de memorizar nombres de parámetros, y un error se detecta antes de ejecutar el juego.

Este mod no tiene ventana propia. Lo que de él se ve lo muestran otras herramientas:

Schema Tools — la paleta de comandos y la ventana Editor de datos;
Validator — parámetros desconocidos o ausentes y referencias rotas en su informe;
los editores de objetos y personajes — los campos que otros mods añaden a objetos y personajes.

De la descripción al formulario y a la comprobación

items_base/schemas/items_base.json        la descripción, junto al código de la acción
        │
        ▼
catálogo de esquemas (todos los mods, en orden de carga)
        │
        ├──► formulario en la paleta         un campo por parámetro
        ├──► línea de escenario              action item.remove id=… count=…
        └──► comprobación                    el mismo veredicto en la paleta y en el validador

Items Engine describe su acción item.remove así:

{
  "Id": "item.remove",
  "Name": "items/schema/remove",
  "Description": "items/schema/remove_desc",
  "Category": "items",
  "Params": [
    { "Key": "id", "Type": "ref", "Kind": "item", "Required": true, "Name": "items/schema/field/item" },
    { "Key": "count", "Type": "int", "Default": "1", "Name": "items/schema/field/count" }
  ]
}

La paleta de comandos de RPG Plus lo muestra como formulario: Item es una lista de los objetos del juego (tipo ref, entidad item), Count es un número con el 1 ya rellenado. Mientras no se elija un objeto, la comprobación dice qué falta:

El stat.archetype de Stats Engine no tiene parámetro obligatorio, así que el mismo formulario vacío se acepta:

Cada acción y comando que describen los mods cargados aparece en la lista de la paleta, agrupado por categorías; el pie los cuenta:

Archivos de esquemas

Un mod incluye schemas/<mod>.json con hasta tres listas:

Actions — acciones de escenario (action <id> key=value …): sus parámetros;
Commands — comandos DSL como check o select: valores posicionales y parámetros con nombre;
Kinds — tipos de datos (item, character, shop…): los campos de sus entidades, la carpeta para archivos nuevos y el patrón de un id nuevo.

Los nombres y las descripciones son claves de traducción de la localización del propio mod, así que los formularios hablan todos los idiomas del juego.

Tipos de campo: text, locale (un texto en todos los idiomas), int, number, bool, choice (con Options), ref y ref_list (ids de un tipo), who, picture, formula, condition, scene, flag, label, list (una lista de objetos con campos propios), values, map, json. Un tipo desconocido se edita como texto.

Varios mods describen un mismo tipo

Los archivos se leen en el orden de carga de los mods:

una acción o un comando descritos de nuevo se sustituyen enteros por el mod posterior;
un tipo se fusiona campo a campo: el campo con la misma clave se sustituye y los campos nuevos se añaden.

Así Equipment añade sus campos al item de Items Engine sin tocar ese archivo:

{ "Kind": "item",
  "Fields": [
    { "Key": "Equip", "Type": "text", "Name": "equipment/schema/field/equip" },
    { "Key": "Archetypes", "Type": "ref_list", "Kind": "archetype", "Name": "equipment/schema/field/archetypes" }
  ] }

Cada campo recuerda qué mod lo describió («Descrito por el mod items_base» en la paleta). Un archivo de esquema roto se informa y se salta; los demás archivos siguen contando.

La regla es que cada mod describa sus propias acciones, comandos y tipos, junto a su código. Un mod puede describir la acción de otro para corregirla, y entonces gana el orden de carga.

Qué informa la comprobación

falta un parámetro — ausenta un parámetro obligatorio (error);
no existe el parámetro — la línea nombra un parámetro que la descripción no conoce (aviso);
valor incorrecto — no es un número entero, no es un número, no está entre las opciones (error, o aviso para sí/no y opciones);
referencia desconocida — el id nombra un objeto, personaje u otra entidad que ningún mod cargado define (error).

El validador informa de lo mismo como SCHEMA_MISSING_PARAM, SCHEMA_UNKNOWN_PARAM, SCHEMA_BAD_VALUE y SCHEMA_UNKNOWN_REF. La comprobación solo sabe lo que dicen las descripciones: una línea que acepta todavía puede hacer algo inesperado en el juego.

Si algo sale mal

Una acción no aparece en la paleta. Ningún mod cargado la describe; la acción sigue funcionando en los escenarios.
Un campo se muestra como caja de texto sencilla. Su tipo es desconocido, o el campo no tiene descripción alguna (el Editor de datos lo muestra entonces entre otros campos, como JSON).
Un formulario ignora tu esquema. Un mod más tarde en el orden de carga describió la misma acción y sustituyó la tuya.

5.9 KiB Raw Blame History