mod_validator/docs/es.md

Validator — revisar los mods sin jugar

El Validator lee cada mod del juego en marcha — manifiestos, archivos de datos, escenarios, parches de escenas y fuentes C# — e informa de lo que está roto o es sospechoso: una referencia a un objeto, escena o fondo que nadie declara, un comando de escenario desconocido, un parámetro incorrecto, una dependencia ausente. Se ejecuta en segundo plano cada vez que arranca un juego y escribe un informe, así que una errata se descubre antes de que un jugador llegue a la línea que la contiene.

Comprueba lo que se ve en los archivos. No juega la partida: un escenario que el Validator acepta todavía puede comportarse distinto de lo que el autor quería, y el código que construye id al vuelo no se puede seguir.

Un error y su corrección

Una línea de escenario que da al jugador carne de lobo, con una errata en el id del objeto:

scene: home_kitchen
priority: 0
---
action item.add id=food/wolf_meet count=1
end

Tras el siguiente arranque de Cthangover, el informe contiene:

{
  "severity": "error",
  "code": "REF_NOT_FOUND",
  "message": "item 'food/wolf_meet' is referenced but never declared",
  "mod": "cthangover_game",
  "file": "scenarios/doc_validator_demo.scenario",
  "line": 4,
  "suggestion": "declare item 'food/wolf_meet' or fix the reference",
  "related": null
}

El mod, el archivo y la línea señalan el error. Con food/wolf_meat el problema desaparece y el contador de errores del resumen baja en uno (de 18 a 17 en esta pasada).

Cómo se ejecuta y cómo leer el informe

• Arranca solo al entrar en un juego que lo incluye (Cthangover lo incluye con sus herramientas de desarrollo), cuando los mods ya están cargados, y corre en un hilo de fondo; no bloquea el juego.
• El registro recibe una línea por pasada: validator: started, 33 mod(s) queued, y después los totales de errores, avisos e informaciones.
• El informe se escribe en user://validation/report.json (en la carpeta de datos de usuario del juego). Contiene un resumen, los mods comprobados con sus versiones y sumas de comprobación, y la lista de incidencias.

Cada incidencia tiene:

• severity — error (algo está roto), warning (probablemente un fallo) o info (merece una mirada, por ejemplo un objeto al que nada remite);
• code — el tipo de problema, por ejemplo REF_NOT_FOUND, JSON_PARSE_ERROR, SCHEMA_MISSING_FIELD, SCHEMA_UNKNOWN_PARAM, DECL_UNUSED, DYNAMIC_KEY;
• mod, file, line — dónde corregirlo; suggestion — qué hacer.

Las informaciones DYNAMIC_KEY significan que la clave se construye al ejecutarse, de modo que el Validator no puede comprobarla; no son errores.

Qué se comprueba

Las comprobaciones corren en tres fases:

1. Esquema — manifest.json tiene un id y una version de texto; los archivos JSON se analizan.
2. Contratos — lo que cada mod declara y remite: entidades de todos los tipos (personajes, objetos, misiones, habilidades, recetas, acciones y los tipos descritos por esquemas), comandos y acciones de escenario con sus parámetros, parches de escenas, propiedades que el código C# lee y escribe.
3. Reconciliación — cada referencia tiene una declaración, depends cubre lo que el mod toma de otros, y se listan las declaraciones que nada usa.

Las acciones de escenario y sus parámetros se comprueban contra los esquemas que los mods incluyen (ver Schemas), con las mismas reglas que la paleta de comandos.

Ajustes

En la pestaña de ajustes del mod, dentro del gestor de mods:

• Enabled, Run on start — apagan la pasada;
• Parse C#, Parse GDScript (desactivado por defecto, lento), Parse scenarios — qué fuentes se leen;
• Write report, Report path — dónde va report.json;
• Block mods on error — está en los ajustes, pero en la versión actual no cambia nada: nunca se bloquean mods.

Si algo sale mal

1. No hay informe. El juego se cerró antes de acabar la pasada (Cthangover tarda cerca de medio minuto) o Write report está desactivado.
2. Muchas líneas DYNAMIC_KEY. Normal en código que construye claves; son informaciones.