Migrating manta-recon onto tosijs-3d-ensemble
manta-recon is where this format came from — src/prefab.ts and
src/prefab-runtime.ts are its ancestors, extracted for the reasons in
SPEC.md. This is the guide for putting it back, and it is short because the
formats barely diverged.
Tracked as manta-recon#1. The cross-project rule holds: nothing in this document changes a file in that repo — it says what its owner should do, and this copy ships with the package so it is reachable by anyone who only installed it.
Requires
tosijs-3d@^0.7.8. 0.1.0 advertised^0.7.0and imported a symbol only 0.7.8 exports, so it could not be imported on 0.7.4–0.7.7 — see the changelog. Use 0.1.1 or later.
Where it stands, measured
Run against static/prefabs/*.json as they are today:
| prefab | validates | builds | needs |
|---|---|---|---|
shielded-target.json |
clean | all 4 pieces | nothing |
ocean-rig.json |
one warning | all 3 pieces | a radar registration |
dome-facility.json |
7 errors | all 7 pieces | migrate |
pyramid-base.json |
6 errors | all 6 pieces | migrate |
All four build every piece already. The errors are one cause: 13 pieces
with no id.
And nothing of Manta's is lost — subsystems, piece-level values, zones,
points and top-level values all survive a load/save round trip. That was the
risk worth checking first, because a format that quietly drops a consumer's data
cannot be adopted and would not have shown up as an error.
The gate lives at src/manta-mvp.test.ts in this repo and re-runs the whole
table; it skips when the sibling checkout is absent.
Four steps
1. Migrate the files
cd ../tosijs-3d-ensemble
bun bin/migrate.ts ../manta-recon/static/prefabs/*.json # report
bun bin/migrate.ts --write ../manta-recon/static/prefabs/*.json # apply
Dry by default. It is idempotent, so re-running it is safe and the dry run cannot differ from the write.
It gives each id-less piece an id from its mesh name — "Dome Mystery" →
dome-mystery — and moves hp from the piece into features.destroyable.hp.
Ids are not derived from the array index on purpose: that is the fault this
format exists to refuse, and baking it into a file people hand-edit would make
it permanent.
docs/prefabs/*.json appear to be copies; migrate them too or delete them.
2. Register radar
ocean-rig uses a radar feature nobody has registered, so validate warns and
the feature does nothing at build. This should not come from us. Features are
a registry open to consumers, and a consumer's feature is meant to be
indistinguishable from a built-in — Manta registering its own is that property
being exercised, not a gap being filled:
import { registerFeature } from "tosijs-3d-ensemble";
registerFeature({
name: "radar",
icon: "📡",
schema: {
type: "object",
title: "Radar",
properties: {
/* … */
},
},
bind: (piece, cfg, ctx) => {
/* whatever prefab-runtime did */
},
});
3. Swap the imports
// was
import { validatePrefab, type Prefab } from "./prefab";
import { buildPrefab } from "./prefab-runtime";
// now
import {
validate,
buildEnsemble,
registerSceneFeatures,
type Ensemble,
} from "tosijs-3d-ensemble";
import { registerCombatPreset } from "tosijs-3d-ensemble/presets/combat";
registerSceneFeatures(); // sun, sky, ground, terrain, water, lamp…
registerCombatPreset(); // destroyable, turret, launcher, protector, blip,
// launchpad, and the roles Manta's files already use
The combat preset registers exactly the roles those prefabs use — structure,
target, power, generator, shield, critical — which is unsurprising,
since it was written from them.
Building one
import { buildEnsemble, placeMesh } from "tosijs-3d-ensemble";
const built = buildEnsemble(ensemble, {
scene, // <tosi-b3d>
origin, // where the ensemble's local origin sits
library: "enemies", // fallback for pieces that name no library of their own
placePiece: placeMesh, // ⚠️ REQUIRED for any ensemble with meshes
});
⚠️ placePiece does not default. It looks like it should, and this
package's own doc comment claimed it did until manta-recon#3 — with it omitted,
every piece is recorded and none is placed, which reported "20 of 20 built,
zero problems" and put no geometry in the scene.
It cannot default: placeMesh imports tosijs-3d, which needs a DOM at module
load, while buildEnsemble imports cleanly under plain Node — which is what
lets a generator validate and build headlessly. So the DOM dependency is yours
to declare. Omitting it now reports no-placer, and a piece the placer
declines reports no-body.
⚠️ Headless means the DEEP import. A generator with no browser writes:
import { buildEnsemble } from "tosijs-3d-ensemble/runtime/build";
import { validate } from "tosijs-3d-ensemble/format/validate";
The package's main entry also exports ensembleEditor, a custom element, so
evaluating the barrel needs HTMLElement and throws under Node. Tree-shaking
saves a bundler; a plain import() evaluates the whole module graph. In a
browser or through a bundler, import from 'tosijs-3d-ensemble' as usual.
⚠️ Three problem codes are new, and two are errors. no-placer and
no-body report at severity error, and meshes-unchecked as a warning — so a
document that validated clean under 0.2.0 can report problems under 0.3.0
without having changed. Each of them is a silence being broken rather than a
new rule: the old behaviour is what let a build report "20 of 20 built, zero
problems" with nothing in the scene. If your gate is
problems.some((p) => p.severity === 'error'), expect it to fire on a build
that never passed placePiece.
Two differences worth knowing:
validatereturns{severity, code, message, path}[]and never throws. An editor shows everything and keeps working; a generator decides whether to emit. Filter onseverity === 'error'wherevalidatePrefabused to throw.registerCombatPreset()returns a teardown, so the vocabulary can be swapped rather than only added.
4. Delete prefab.ts and prefab-runtime.ts
754 lines. src/main.ts and src/prefab-editor.ts are the only importers.
prefab-editor.ts, bench-gizmo.ts and bench-view.ts are a separate question
— this package has its own editor (ensembleEditor) but it is not yet a
drop-in replacement for the bench, so keep them until it is.
What "done" means
bun test in this repo, with the sibling checked out, reports all four prefabs
validating clean and building every piece. That is milestone 1, and it is the
proof the API is right — which is why it comes before building anything else on
top of it.
Upgrading from 0.3 to 0.4
Three things change underneath an existing document. None of them needs an edit to a well-formed file, but each can change what renders.
tosijs-3dis now^0.8.4. The sun runs a northern-hemisphere arc andstarfieldTiltno longer moves it (0.8.3), and everyPRNG-seeded output re-rolls (0.8.4). A seeded cloud field or galaxy looks different with the same document. Scenes tuned by eye should be looked at again.- Fetched urls must be https (or relative — and that now includes
localhost:
http://localhostis refused, usehttps://localhost), for libraries AND for fetched feature fields (starfieldData,starfieldCube,nebulaTexture,ground.texture,water.normalMap,clouds.model,sound.url). A refused url is reported byvalidateAND not fetched: the library is not mounted, the field never reaches its element. So a document that pointed at anhttp://host renders WITHOUT that library or field, where it used to render with it. Runvalidateover your files before upgrading;insecure-library-url/insecure-feature-urlname each one. - A fetched field must hold a string. Anything else is refused rather than stringified.
For manta-recon specifically, measured on 2026-09-26: its eight assemblies
(static/assemblies/*.json) declare no libraries and no fetched feature
fields, and 0.4's validate reports no url problem in any of them, so the url
rule does not touch them. What was NOT measured is the peer-floor change: the
moved sun and the re-rolled seeds are visual, and need eyes on a Manta scene.
Upgrading from 0.4 to 0.5
Three things change underneath an existing document:
An unset field now renders at its SCHEMA default, the value the editor's panel shows, where it used to render at the ELEMENT's default. For a field a document sets, nothing changes. For one it leaves out, these move:
feature field: was (element) → now (schema) groundwidth/height4 → 400 m,texturenone →checker,textureTiles8 → 20sunactiveDistance30 → 400,numCascades0 → 2,shadowTextureSize0 → 1024,shadowDarkness0.1 → 0.4skyboxtimeOfDay6.5 → 11 (realtimeScalewas already 0)lightintensity1 → 0.9fogmodelinear → exp2,density0.01 → 0.002,start/end60/120 → 100/4000,color#bfd9f2 → #8fa6b2,syncSkyboxoff → onwaterwaterSize128 → 2000,waveHeight0 → 0.3,windForce−5 → 6,waterColor#0066cc → #0a3d5cterrainseed,surfaceType(cylinder → "plane", which tosijs-3d does not have: 0.6 reverts it, see below),radius,horizScale, both amplitudes,tileSize,lodLevelscloudscount,altitude,thickness,spread,opacitysoundloop/autoplay/spatialSoundoff → on,maxDistance100 → 60reflectionsprobeSize0 (off) → 128,maxDistance100 → 200cameradistance12,heading-60°,elevation20° (ours; the bind already fell back to these)weatherCell(new in 0.5)a new cell is a storm: radius900,coverage1.7,storminess1,precipitation0.9The rule is not limited to scene features: every registered feature's top-level schema defaults now reach its bind and update, a consumer's own included (manta-recon's
radar,spawnerandpatrol-zonewere checked: their bind fallbacks already equal their schema defaults, so nothing moves). Defaults NESTED inside an object property (radar.boost.*) are not applied. A terrain's height is still its piece'syunless the document setsbaseHeight. The field counts were measured against tosijs-3d 0.8.9.To keep a scene exactly as it rendered, write the old value into the document. A key you REMOVE now resets to its default, rather than the element keeping the last value it had.
tosijs-3dis now^0.9.0, andmoonandsoundtake their schemas from it. Their accepted ranges widen (a moon'ssizeto 0.05°; a sound'svolumeto 2 and its distances tenfold), so nothing that validated before stops validating.terrain.biomeTemperaturechanged meaning in tosijs-3d 0.9.0. It is a real temperature now:0is 0 °C,1is 50 °C,-1is -50 °C (no longer "default"). It used to be the biome chart's0…1axis. Convert a value a document sets with(old - 0.36) / 0.8. A-1(the old "default") is read as the default andmigrate()removes it, so it needs nothing. A value left unset needs nothing either.
Upgrading from 0.5 to 0.6
A document needs no change to load, but one written by 0.5's editor may say
terrain.surfaceType: "plane", which tosijs-3d does not have (it samples as
a cylinder, so that is what it has always rendered). migrate() rewrites it
to "cylinder"; nothing changes on screen. Code may need changing in three
places:
- Peer
tosijs-3dis^0.10.9. The planet feature and the terrain pin take their schemas from 0.10.8, the planet ↔ terrain links need 0.10.9, and 0.10.8 fixes two leaks we had been working around. A game on tosijs-3d 0.9 or early 0.10 moves to 0.10.9 with it. - Deep imports that are gone, neither ever on the package entry:
boxTracker(editor/schema-panel): a panel's owndispose()releases its bound rows now.schemaPanel(…)returns aDisposablePanel; calldispose()when you drop it, as the editor does.applyEuler(runtime/node-transform): ab3d-destroyableturns its instance fromrx/ry/rzitself. Scale an element with the newscaleElement(element, scale), which takes the format'snumber | Vec3and keeps a per-axis scale through the element's re-renders. For a plain node,applyScaleis unchanged.
- A stretched piece now STAYS stretched after it is moved or turned. It
used to snap back to its uniform scale on the first edit, so an editor
session that "fixed" that by hand may have saved a different
scalethan was authored; worth a look in any document edited that way.
Upgrading from 0.6 to 0.7
- Peer
tosijs-3dis^0.10.14. It fixes projected ambient occlusion on library pieces (#107), typespanel3d'sdispose()(#104), gives a piece a per-axisstretch(#105), and adds the system panels the editor's chrome is on (#106). - The piece list's tables no longer select rows themselves, and singleton
environment features are on/off only (never deleted, duplicated or
renamed). Code driving the editor through its component API is unaffected;
includeFeature(name)is new. - The editor's panels are tosijs-3d system panels, drawn in the scene,
with buttons on the scene's system bar. They are no longer SVG overlays in
the editor's shadow root, so a page that styled or positioned them
(
.ensemble-editor-chrome) has nothing left to style;hideChromestill removes them. The editor gainsstore/EnsembleEditor.defaultStore(open and save through a host store) andhostActions.
Upgrading from 0.7 to 0.8
- Peer
tosijs-3dis^0.10.18. 0.10.15 stops system panels blinking when they rebuild, which the editor does on every edit, and adds panning to the default view controls. 0.10.16 adds effects andeffectRecipeSchema(); 0.10.17 addseffectSchema()for the effect element; 0.10.18 adds landform schemas and slider stops. - Nested ensembles build. A piece with
"ensemble": "<url or name>"is loaded and spliced in when its parent builds, with path ids (rig-a/pump). If you nested by hand before (a host that fetched a child and placed it itself, as Manta's missions did), you can let the document say it instead. A code that matchednested-not-supportedwill not see it again; matchnested-missing,nested-cycleornested-too-deep. BuiltEnsemble.ensembleis what was built, the flattened document. Code that compared it with the authored document by identity only differs when the document nests.- A store may implement
idFor(src)so a document opened bysrcsaves back to its entry;dataClientStoredoes. Nothing to do unless you wrote your own store.
Upgrading from 0.8.0 to 0.8.1
- Peer
tosijs-3dis^0.10.20. Nothing in a document or the editor's API changes. 0.10.19 makes its rig and effect tools mountable in a host's scene (tosijs-3d#122), which the editor builds on; 0.10.20 fixes its inline-SVG effect pictures throwing after a rebuild (tosijs-3d#124).
Upgrading from 0.8 to 0.9
- Peer
tosijs-3dis^0.11.4. tosijs-3d 0.11 removed nothing; its behaviour changes are in its own Migration.md (system panels from code, the glass gamepad, headset stick clicks). Nothing in a document or in ensemble's API changes. - A consumer feature that declares no properties now receives an empty
config. Declare the keys it reads in
schema.properties(or list them inx-accepts);"x-accepts": "*"keeps the old pass-through, deliberately.validatenames every key it drops.
Upgrading from 0.9 to 0.10
- Peer
tosijs-3dis^0.13.1, and since its 0.12.5 Babylon's packages are its OPTIONAL peers, so npm no longer installs them for you.<tosi-b3d>itself importsgui,loadersandmaterials, so any scene needs all four; install them with tosijs-3d:npm i @babylonjs/core @babylonjs/gui @babylonjs/loaders @babylonjs/materials. tosijs-3d 0.13.0 also removed the settings panel's Slow motion button; the editor's Time panel setstimeScaleitself. - Models are no longer drawn mirrored (tosijs-3d 0.12.0). It reaches every
library piece: models loaded through a
<tosi-b3d-library>are no longer drawn mirrored (0.11 drew each as its mirror image: text backwards, left and right swapped). Positions, rotations and scales in a document are unchanged, so a symmetric piece looks the same; an asymmetric one now looks as its model was authored. If you turned or placed a piece by eye to suit the mirrored picture, check it. Skinned models were never mirrored. - Property-panel sections open one at a time (tosijs-3d 0.11.5's
foldSectionsdefault): opening one shuts the others. The piece list keeps several open. Nothing in a document changes.