healer-man/scripts/runewaker-pipeline/RECIPE_SCHEMA.md

RuneWaker recipe schema

Two recipes keep environment conversion separate from population/mechanics. Paths are project-relative unless an environment variable supplies the preserved source root.

Environment recipe

Required top-level fields:

• schemaVersion: recipe format version.
• slug: HealerMan dungeon ID and asset directory name.
• title: display/source title.
• source: preserved WDB, primary ROS, config, and entrance evidence.
• coordinateSystem: source axes, units, and direction units.
• navigation: Recast settings. partition may select watershed or monotone; forceTiled is an explicit source-geometry workaround when a compact solo heightfield cannot triangulate its contours.
• review: human review states.
• exceptions: known limitations retained in metadata.

source fields:

• rootEnvironmentVariable / relativeDefault: source-root resolution.
• resourceRoot: normally Resource.
• wdb: WDB path relative to the source root.
• model: primary ROS relative to Resource.
• dungeonConfig / dungeonConfigId: server catalog join.
• entryLua / entryConstantPrefix: authoritative entry constants; or
• entryCoordinates: explicit position/direction with reviewRequired.

Optional source.wdbAssembly fields:

• mode: all-ros by default, or primary-only for a deliberate compatibility build.
• dynamicPlacements: reviewed dynamic object selectors. Each entry requires a stable id, kind, evidence, and either an exact WDB guid or normalized resource; optional initialState and collision describe the runtime contract.

Valid ROS placements not selected as dynamic are static. Filename hints are reported for review but never infer stateful behavior. Non-ROS descriptors, invalid transforms, missing resources, and exporter failures remain explicit unsupported records in the placement manifest.

The full placement transform is preserved as:

threeMatrix = S * inverse(primaryTRS) * placementTRS * inverse(S)
S = scale(metersPerSourceUnit, metersPerSourceUnit, -metersPerSourceUnit)

Population recipe

Required fields:

• dungeonId, zoneId, and runtimeIdPrefix.
• expectedActiveRows and expectedBossSpawns after the first refresh.
• files: snapshot, generated source, reports, environment/nav, actor outputs.
• source: source-root, catalogs, backup paths, SQL extraction instance.
• actors: unique reviewed source ROS models.
• templates: classification, display, combat, actor, and mechanics mappings.
• deferred: explicit later-pass list.

Template classifications are combat, boss, deferred-object, or unclassified. Generation refuses unclassified rows and combat/boss rows without a valid actor.

Optional template fields:

• title, archetype, primaryColor, accentColor, visualScale;
• hasLoot, spawnMask, objectiveNamePattern;
• combat: health/damage multipliers, movement, and leash overrides;
• attacks: reviewed HealerMan attack definitions;
• reason: why an object is deferred;
• source: forensic image/model/classification evidence.

source.scriptRoots may list reviewed Lua entry functions for dynamically created bosses that have no static SQL row. The boss-mechanics importer follows those roots and their callbacks exactly as it does for static boss rows.

Optional top-level scripted placement fields:

• scriptedSpawns: reviewed creatures created by Lua rather than stored as active zone rows. Each entry has a stable id, a combat/boss templateId, a sourceAnchorSpawnId, source evidence, and optional source-unit offset, controller row, direction, or objective: false for a boss companion.
• scriptedFormations: source LuaFunc_Matrix_Maker formations flattened to their initial positions. Each formation specifies its controller/anchor row, source direction and spacing, Lua root/evidence, and member template IDs with one-based rows and signed columns.

expected* values may be null only in a fresh scaffold. The explicit forensic refresh with --update-recipe pins them. A recipe should not be treated as production-ready until all classifications/models and counts are reviewed.