refactor: resolved metre layout is the runtime authority (L41, migration step 3); stamp covers plugin sources; R8

UVoxelStrateManager::Initialize resolves the layout width to integer micrometres before passages or
scheduling; each slot stores physical [bottom, top) bounds, transition mode/width and passage settings;
chunk indices remain a floor-based compatibility projection. The Core adapter derives interiors and L29
bands from those resolved values. verify: full-tier cost baseline is HEAD (or --baseline), tier timeout
7200 s with 1800 s per process; the source stamp now includes the plugin Source tree compiled on Linux
(it previously missed VoxelStrateManager.cpp and friends). Owner hashes identical to L37; fast, medium
and full PASS on a clean rebuild. Unreal manager/adapter edits are uncompiled on Windows.
Research R8: inventory of unit-bearing UPROPERTYs and a custom-version asset migration plan.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016dhxM43dnWvUu2B5Ph1iG1
This commit is contained in:
Fr0zkaandClaude Opus 5.5 committed 2026-10-23 19:36:51 +02:00
1 parent efa9e89468
commit 1abee91721
11 files changed
+662 -215

No files matched your search

@@ -0,0 +1,72 @@
# Unreal asset migration notes — resolved metre layout
Read-only schema review for L41. No Unreal source or assets changed; no build or tests run.
## Existing authored data
- `UVoxelStrateDefinition` is a `UPrimaryDataAsset`. Its persisted `StrateHeightInChunks` and
`TransitionBlendChunks` drive the vertical slot and lower-boundary transition. Their comments
still describe 4 m chunks, while `UVoxelSettings::StrateLayoutChunkSizeMeters` now defaults to
8 m. Keep the numeric fields as legacy authoring inputs and resolve them once using the layout
width selected for that world. Do not reinterpret the stored integers as metres or infer their
scale from the stale tooltip.
- `UVoxelSettings::InterStrateGapChunks` is another legacy chunk input. Per-strate
`FStratePassageConfig` is persisted with radii, reaches, placement distances, wander, wobble,
spiral radius and cascade ledge expressed in legacy voxels; style, connection count, and segment
counts are dimensionless/discrete. Retain the exact old effective voxel scale for each legacy
asset route, convert dimensional values once, then store the resolved physical passage request
and derived seed before any jobs are scheduled.
- L40/R6 confirms FI and SW already receive the same `LayoutChunkWidthSubvoxels` for layout
planning. Never apply an owner/Core ratio to layout bounds a second time. Keep that ratio only
in the legacy FI parameter adapter; convert passage and layout inputs at their own established
unit boundary.
## Season assets need a separate compatibility route
`UVoxelSeasonAsset` embeds the reviewed JSON plus copied schema/season/seed/hash metadata. Current
manifest schema v2 stores `height_in_chunks`, global `inter_strate_gap_chunks`, per-slot seed and
`top_world_z`/`bottom_world_z`; the composer derives those bounds with a fixed `* 32` convention.
The runtime validates those stored bounds against the live layout chunk width. V2 does not carry a
resolved transition width/band or passage config for generated slots; authored slots recover
content and passage settings through `source_definition_path`. The asset loader rejects a schema
version it does not recognize and verifies both hash copies.
For migration, keep a v2 reader/converter that interprets v2 under its original coordinate
convention, verifies its existing content hash first, then builds the new immutable metre snapshot.
Do not rewrite the embedded v2 JSON or silently add default passages: either action changes
identity or geometry. If a season is explicitly re-authored/exported in a new schema, include
resolved metre bounds, gap, interface transition/band records, per-strate seed and passage settings;
bump the manifest schema and generate a new canonical content hash. Record the source schema and
conversion policy in diagnostics so stale or ambiguous assets fail closed rather than guessing.
## Resolved snapshot and edge rules
The game-thread director should publish integer micrometre records before queueing work: half-open
strate bounds `[bottom, top)`, height, inter-strate gap, transition width, the exact L29 upper/lower
band bounds and mode, world/strate/passages seeds, and fully resolved passage descriptors. Copy
the L29 band endpoints and cap rules exactly; do not recompute a second approximation from chunk
indices in the adapter. Derive legacy chunk fields only as projections for streaming, old Blueprint
queries and logging.
Use one conversion and edge policy in manager and adapters. For an aligned half-open interval the
first chunk is `floor(bottom / chunkWidth)` and the inclusive last chunk is `ceil(top / chunkWidth)
- 1` (equivalently `top / chunkWidth - 1` when aligned). Use mathematical floor / Euclidean
division for negative Z, not C++ truncation toward zero. Quantize authored metres to integer
micrometres once with a documented tie rule; avoid converting through float chunk positions and
rounding again. Test exact lower/upper edges, one micrometre either side, negative boundaries,
zero gap, and adjacent bands in both adapter and manager.
## Version and identity risks
- Keep authored-schema version, resolved-layout schema, recipe/evaluator version, and source
content hash distinct. A derivation-only schema change may alter layout diagnostics; it must not
move the owner density/mesh hashes in this pure-refactor step.
- For old chunk/voxel assets, preserve physical dimensions with a versioned compatibility
conversion. Future metre-authored properties should be explicit and versioned; do not overwrite
old fields or treat their raw values as metres. Keep original asset paths/values available for
rollback and audit.
- `FStratePassageConfig` currently has no persisted passage seed, and season v2 lacks generated-slot
passage descriptors. Derive seeds with the existing stable world-seed/slot/connection salts and
record the result in the snapshot; do not base it on UObject pointer or load order.
- UHT/UBT validation is still required for any reflected schema/property migration. The Linux Core
checks cannot validate UObject serialization, cooked season references, or Blueprint compatibility.