VoxelForge/Standalone/Research/WorldAssemblerM3/Research8/shared-notes.md

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(equivalentlytop / 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.