Aetheria/docs/moddable-ship-authoring.md

160 lines
9.1 KiB
Markdown

# Moddable ship authoring: parallel proof
Status: design and proof lane. The existing `HullData` catalog records, Longinus and
Djinni prefabs, and their spawn path remain live until a complete mod ship passes
authoring, validation, loading, and play checks.
## LineArt proof from Quiet.blend
`C:\Users\Meta\Desktop\Quiet.blend` is a read-only source for this probe. At frame
1, `Quiet / Dexter Quiet Lineart` evaluates to 1,040 polylines with 3,125
points. Blender 5.2.2 wrote those coordinates, point radii and opacities,
material/layer names, cyclic flags, and RGBA into `Build/quiet.cc` without
changing the `.blend`. C# reopened the same typed record and counted the same
lines and points. A second line replacement preserved its record key, schema
ID, hull, model asset, and anchors byte for byte. `Build/quiet.cc` is an
ignored draft probe, not an installed ship.
The line positions remain 3D Blender world coordinates. The runtime can
lower them to a hologram or schematic view without regenerating LineArt.
LineArt evaluation depends on the source scene and camera, so a captured set
may be incomplete from another view. Gameplay cell occupancy remains the
authored `HullData.Shape` in the `.cc`; strokes do not decide armor or mount
footprints.
`tools/blender/aetheria_ships` is a separate Blender add-on in Brokkr's
sidebar. It uses Brokkr's configured CultLib Python source and edits only the
line slot of an existing `aetheria.ship_authoring` record. To try it, make
`F:\Projects\Brokkr\surfaces\blender` and this repo's `tools\blender` visible
to Blender's add-on search path, enable `brokkr_bridge` then
`aetheria_ships`, and install `msgpack` into Blender's Python environment.
Create a draft with `dotnet run --project tools/AetherDb -- ship-authoring
create <ship.cc> <stable-id> <name>`, choose that `.cc` in the **Aetheria
Ship** panel, select a Grease Pencil object, and press **Capture Ship Lines**.
`ship-authoring inspect <ship.cc>` reads drafts; `validate` requires complete
hull, model, and anchor authoring.
## Objective
A mod author edits one typed ship record in a `.cc` file, including the hull
schematic and every hardpoint. Blender, through Aetheria tooling built on
Brokkr, edits that same record while displaying its visual source. The game
assembles an instance from the record and its referenced asset package at
runtime. A mod package can be installed without opening the Unity Editor.
## Current mechanism
`GameData/Aetheria.cc` holds `HullData`: the cell shape, hardpoint footprints,
stats, and a Unity Addressables prefab GUID. `ZoneRenderer.LoadEntity` loads
that prefab and expects `ShipInstance`; `EntityInstance` and `ShipInstance`
match catalog hardpoint transform strings against manually wired prefab
arrays. The new FBX naming builder automates prefab wiring but still emits a
Unity prefab and is part of this existing path. Brokkr can capture Blender
collections and custom properties; the AetheriaEve Blender authoring v1
contract describes a future collection-to-CultMesh deploy lane, but that lane
is not yet an end-to-end ship loader in the current game.
## Target authority map for the parallel lane
- **Owner:** a versioned `ShipAuthoring` document in a mod-owned `.cc` file
owns the ship's authored hull, schematic, hardpoints, structural and
presentation associations, and asset references. A ship ID is stable across
display-name changes.
- **Inputs:** the authoring record; a Blender visual source identified by the
record; compiled mesh, texture, and material artifacts; references to gear
designs where the game requires them.
- **Outputs:** a validated runtime hull design and an assembled visual/physics
`ShipInstance`. The assembly and any catalog row are derived products.
- **Derived state:** Unity objects, component arrays, collision components,
particle emitters, and schematic UI. Installed equipment, damage, heat,
cargo, ownership, and position are live game state.
- **Forbidden writers:** Blender object names, Unity prefabs, generated catalog
rows, and runtime components may not independently decide the schematic,
hardpoint type or footprint, armor, drag, or mount identity. Geometry nodes
carry stable IDs; the `.cc` document gives them meaning.
- **Shared path:** Blender validation, command-line validation, editor preview,
and runtime loading read the same typed record and invoke the same semantic
validator. A bad mod is rejected before partial scene construction.
- **Cut line:** no existing ship path is removed during proof. Migration later
deletes or demotes the old ship-specific catalog/prefab authority for each
migrated hull; it does not keep two writable definitions of that hull.
At this proof stage, `ship-authoring validate` is the sole caller of the
semantic validator. The Blender capture command writes only line data and the
`inspect` command reads incomplete drafts. Editor preview and runtime loading
still need to be built. The current gameplay catalog and prefab loader do not
read these mod records.
## Runtime catalog seam
`CultCache` routes `ItemData` to one home backing store, and
`ActionGameManager.CultCache` holds that store for the entire play session.
Attaching each mod's `.cc` as another item store would violate the cache's
one-home invariant. `ship-authoring compose` instead derives one runtime catalog from
the shipped catalog and validated mod packages, preserving all shipped record
keys. Each mod's stable `ShipAuthoring.Id` yields separate deterministic keys
for its copied `HullData` and its runtime authoring record. The generated
catalog is disposable; the shipped catalog and each mod's source `.cc` remain
the owners. A player session opens one catalog snapshot and cannot hot-swap its
designs beneath existing entities.
Each immediate child of the mods directory has an ID matching its directory
name and contains `ship.cc` plus the GLB at the record's relative `ModelAsset`
path. Every referenced anchor uses an `aetheria.id` custom property exported
into a GLB node's `extras`. Compose checks the asset, unique IDs, and every
reference before atomically replacing the derived catalog. For example:
```text
dotnet run --project tools/AetherDb -- ship-authoring compose GameData/Aetheria.cc GameData/Aetheria.modded.cc GameData/Mods
```
This command does not yet make the game open `Aetheria.modded.cc`; the runtime
loader and a complete playable ship are still outstanding. In the Quiet probe,
206 shipped records became 208 derived records: one `mod-hull:quiet` and one
`mod-ship:quiet`. A missing GLB node ID was rejected without changing the
previous derived file. The probe's four anchors and zero hardpoints are only
a data-path smoke, not a playable Quiet design.
The construction boundary will resolve a mod hull's authoring record from its
derived key, load the package's compiled GLB at runtime, and build the
`ShipInstance` references from validated stable node IDs. It must fail before
scene construction when an asset or anchor is absent. [Unity glTFast's runtime
import](https://github.com/Unity-Technologies/com.unity.cloud.gltfast/blob/main/Packages/com.unity.cloud.gltfast/Documentation~/ImportRuntime.md)
is a candidate for the GLB step; it has not been added to the project.
## Proof gates
1. A typed `.cc` record round-trips between C# and Blender's Python runtime,
preserving unknown future fields and record identity.
2. Blender edits schematic cells and hardpoints in that record, and validates
their association with stable visual node IDs. The model supplies geometry,
not a second copy of hull semantics.
3. A command-line validator rejects malformed cells, overlapping or dangling
hardpoints, missing model nodes, and unresolved asset references with
precise errors. It changes no live catalog or scene on failure. The
composer now performs this check for a package before replacing its
derived catalog.
4. A packaged mod ship loads in a built Unity player without Unity Editor or
Blender installed. Runtime assembly creates the same components the
current `ShipInstance` expects and uses the existing simulation rules.
5. Spawn, equip, thrust, fire, shield, damage, save/reload, and schematic UI
work for the mod ship. Only then is a shipped hull eligible for migration.
## Structural and build budget
The proof reuses `HullData` simulation semantics, CultCache `.cc` persistence,
Brokkr's Blender host, and the current `ShipInstance` behavior. This pass adds
one authoring document type, one validator, and one Blender-facing editor
surface. A later pass needs one runtime construction boundary. It does not add
a daemon, a second gameplay
simulation, or another Unity prefab generator. The existing name-based FBX
builder remains available to existing content but is not an input to this
lane. Its retirement is a later cut, after migration.
Focused checks use `Aetheria.Shared` and `tests/Aetheria.Shared.Tests` under
`netstandard2.1` / `net10.0`, Python CultCache interoperability checks, and
the Unity 6000.3.24f1 Editor compile and play probe. No workspace-wide build
or new executable target is justified for schema work. The current catalog is
12.7 MB; it is not rewritten during the proof. The worktree starts clean from
`4b594e11`; unrelated Unity scene and material edits remain in the original
checkout.