92 lines
4.1 KiB
Markdown
92 lines
4.1 KiB
Markdown
# Manastorm stage asset bridge
|
|
|
|
`import-existing-stage.mjs` promotes a real converted dungeon asset package
|
|
into the Manastorm staging layout. It accepts either a previously green dungeon
|
|
pack or paired Blender-conversion and Recast reports; it does not synthesize or
|
|
substitute geometry.
|
|
|
|
Each import is an explicit
|
|
`dungeon-pipeline/manastorm/imports/<stage-slug>.json` manifest containing:
|
|
|
|
- either the green source validation report and package manifest, or the
|
|
conversion and navigation reports for a newly converted package;
|
|
- reviewed visual, collision, and navigation GLB paths and checksums;
|
|
- original conversion evidence, such as the wow.export OBJ and Blender report;
|
|
- reviewed source anchor positions with `client`, `observed`, or `authored`
|
|
provenance.
|
|
|
|
`assets.visual` and `assets.collision` accept either the original single
|
|
descriptor object or an array of descriptors. `assets.navigation` remains one
|
|
descriptor. Compound descriptors retain a stable `id`, decoded
|
|
`triangleCount`, source `transform`, and `provenance` object in
|
|
`stage-source.json`, `optimized-manifest.json`, the import report, and the
|
|
shipping stage pack. All collision chunks retain the 100,000-triangle
|
|
per-chunk limit.
|
|
|
|
The importer validates every chunk and every provenance file before it changes
|
|
the active staging generation. It copies the complete set into a temporary
|
|
generation, then swaps the staging directory and anchor review together with
|
|
rollback. A bad checksum, missing chunk, incomplete Recast input list, or copy
|
|
failure leaves the previous generation intact.
|
|
|
|
For a dungeon that already has green wow.export, Blender conversion, and Recast
|
|
reports, scaffold that manifest and a five-anchor provisional review set with:
|
|
|
|
```powershell
|
|
node scripts/manastorm-assets/scaffold-converted-import.mjs <stage-slug> <dungeon-slug>
|
|
```
|
|
|
|
The scaffold chooses start, middle, and end vertices from the largest connected
|
|
navigation component, records placement-resolution statistics, and preserves
|
|
collision-cap and visual-review warnings. The resulting gameplay semantics are
|
|
provisional until encounter data and a playtest review confirm them.
|
|
|
|
For ADT-hybrid or other converted environments whose reviewed runtime fixture
|
|
does not yet list the collision assets, bake navigation directly from every
|
|
collision chunk recorded by the Blender conversion report:
|
|
|
|
```powershell
|
|
npm run dungeon:navmesh:conversion -- <dungeon-slug>
|
|
```
|
|
|
|
This command hashes and loads the full collision set from
|
|
`dungeon-pipeline/work/<dungeon-slug>/staging/environment/conversion-report.json`,
|
|
writes the navigation GLB and Recast report, and records the exact ordered
|
|
input paths and checksums. The scaffold/import steps reject a Recast report
|
|
whose input set differs from the reviewed collision descriptors.
|
|
|
|
The equivalent Node API is:
|
|
|
|
```js
|
|
import { bakeConversionNavigation } from "../dungeon-pipeline/recast-bake.mjs";
|
|
await bakeConversionNavigation("<dungeon-slug>");
|
|
```
|
|
|
|
The importer rejects checksum drift, unvalidated source packages, unreadable or
|
|
non-finite GLBs, collision chunks over 100,000 triangles, and anchors more than
|
|
2 meters from the actual navigation surface. Accepted anchors are projected
|
|
onto navigation triangles with `three-mesh-bvh`, retaining both their source
|
|
position and measured projection distance.
|
|
|
|
For any configured import:
|
|
|
|
```powershell
|
|
npm run manastorm:maps:import -- <slug>
|
|
node scripts/manastorm-pipeline/cli.mjs optimize <slug>
|
|
node scripts/manastorm-pipeline/cli.mjs pack <slug>
|
|
npm run manastorm:maps:validate
|
|
npm run manastorm:maps:khronos
|
|
```
|
|
|
|
`optimize` and `pack` consume the staged asset manifests, so the same commands
|
|
work for single-root, multi-root, and ADT-hybrid packages. Packing is the step
|
|
that updates the shipping directory and generated registry; do not run it
|
|
while another worker owns registry serialization.
|
|
|
|
The collection validator remains blocked until every catalog map has a package.
|
|
The Khronos gate recursively validates every shipping GLB, fails on errors or
|
|
warnings, and rejects an empty target so a zero-file run cannot pass silently.
|
|
Inspect the requested map's entry in
|
|
`dungeon-pipeline/manastorm/validation-report.json`; a packaged map is green
|
|
when its `blockers` array is empty.
|