# From the sanctuary to a world This is the expansion plan for FMVisual, written for scene authors and newcomers. The hillside sanctuary is the working reference. Streaming, walkable terrain and multiple lighting zones described below are future work, not current capabilities. ## The world we are aiming for Leave the shaded arcade, follow a stepped garden path, pass beneath the aqueduct, and reach one of the houses that is currently a distant silhouette. Turn around: the sanctuary should still sit on its hill, with the same roofline and afternoon light. Return through its gate and find the same stone, fabric and sheltered shade. That journey is a better first target than an enormous empty map. A world needs recognizable places, traversable connections and consistency when you return. Its richness comes from changes of scale: a carved edge near your hand, overlapping balconies across a street, a tower beyond the next ridge and hills behind it. The current whole-world working target is **one million purposeful triangles**, with materials, lighting, route and visual review qualified together. See the authoritative [world geometry profile](WORLD-GEOMETRY-PROFILE.md); the existing single-assembly 500,000-triangle software guard remains separate. ## A large world with a small working set Store the world's description separately from the objects currently on the GPU. A region can exist as an address, terrain recipe and saved changes while its individual windows, furniture and lighting textures are absent from memory. As the visitor moves, prepare the next place and release detail behind them. | Representation | What it contains | What changes as you travel | | --- | --- | --- | | World description | Region IDs, coordinates, seeds, roads, landmarks and authored overrides | Stable identity; edits are saved separately | | Distant context | Terrain silhouette, roof masses, large vegetation groups and atmosphere | Cheap levels of detail; broad geographical continuity | | Approaching region | Terrain, coarse buildings, route collision and prefetched assets | Becomes ready before the visitor can reach it | | Nearby place | Detailed architecture, material maps, navigation, shadows and local GI | Highest detail follows the visitor within measured limits | | Persistent changes | Open doors, moved objects and authored edits keyed by stable IDs | Survives unloading and recreating a region | These are overlapping responsibilities, not necessarily concentric circles. A tower across the valley may need a silhouette from far away. A building behind the camera may still cast a visible shadow or appear in the pool reflection. Navigation must be ready before rendering detail becomes necessary. Visibility alone is therefore an insufficient unloading rule. ## What we already have The nearby sanctuary is fully resident. Its approximately 42-unit longest span uses 118 voxels at Balanced quality, spacing about .356 world units, and 499,200 padded base cells. The 650-by-650-unit landscape is separate context, excluded from nearby voxelization and shadows. It is not currently walkable. There is one active lighting volume. Walking preserves eye height and uses rectangular floor regions and simple obstacles. There is no terrain following, stair physics, regional streaming or saved world state. Three.js supplies the current VXGI algorithms; the framework owns their integration and lifecycle. A direct-light preview can commission geometry and routes, but cannot qualify indirect light, doorway bounce continuity or voxel density. Confirm the actual backend before comparing lighting. WebGPU must be available and initialize successfully in the browser view used for the full renderer. ## Keep separate budgets A distant scene can be cheap to light and still expensive to draw. Keeping it out of the voxel volume is one saving; triangles, materials, shadows, texture memory, reflections and CPU construction each need their own limit. | Budget | Starting evidence or constraint | Expansion rule | | --- | --- | --- | | Nearby diffuse lighting | Sanctuary Balanced: 499,200 base cells; existing scene cap 550,000 | Preserve approximately .356 spacing for this quality. Do not enlarge one grid to cover the valley. Qualify each new zone and total resident zones separately. | | Shadow detail | Current fitted maps preserve about 55 texels per world unit | Keep a nearby coverage policy. Far context needs an explicitly cheaper shadow policy, rather than expanding the same map. | | Hard allocation guards | Longest-axis voxel requests above 256 and shadow dimensions above 4096 are rejected | Guards prevent runaway requests; being below them does not establish affordability. | | Resource residency | Local repeated sanctuary visits: 16 geometries, 42 textures, approximately 194 MB renderer-tracked allocations | Establish a new baseline for overlap, then repeat long round trips. Counters must plateau after caches settle. Include transient peak allocations. | | Frame delivery | Same-camera ABBA comparison against the preceding reference | Record warmup, adapter, viewport, settings, median and p95 frame intervals. Preserve moving-camera visual quality as well as average cost. | | CPU creation and upload | No streaming baseline yet | Measure region construction and upload spikes; build in bounded batches and cancel obsolete requests. | | Asset transfer and storage | Current procedural world needs no third-party scene download | If assets are introduced, budget compressed transfer, decoded memory, cache size and cold-start latency independently. | Base cells are not bytes: directional volumes, filtered levels, shadow textures, intermediate images and temporal buffers add allocations. Two overlapping zones can require substantially more memory than one. We must measure that peak before choosing how many can coexist. Renderer counters are not complete driver VRAM. There is no qualified universal frame-rate or memory promise yet. At fixed spacing, doubling all three dimensions costs about eight times the base cells. Adding a long, narrow passage can be affordable; enclosing a whole valley in one detailed three-dimensional light grid cannot scale the same way. ## The implementation sequence ### 1. Give places stable addresses Introduce a world manifest with a version, world seed, region IDs, placement, neighbours, terrain revision and landmarks. Use region-local geometry with a separate world position. Derive procedural variation from stable IDs rather than object creation order. Save authored changes as overrides to that recipe. A regenerated house must keep its identity, doorway, height and street alignment. Keep the sanctuary as a fixed reference region. At genuinely large coordinates, introduce a camera-relative floating origin; preserve logical coordinates so rebasing does not move saved places. A curved planet additionally needs a curved terrain and coordinate model; an ever-larger flat mesh is not a planet implementation. ### 2. Build one connected route with a trustworthy floor Choose one distant house and author a route to it. Define a shared terrain-height function in world coordinates so neighbouring tiles agree at their edges. Establish terrain levels of detail with stitched edges or skirts, consistent normals and stable transitions. Place the path, foundations and vegetation from the same data. Add ground sampling, slope limits, steps and route obstacles before allowing travel downhill. Today’s planar containment remains useful inside the sanctuary, but removing its boundary would expose an unimplemented terrain-navigation problem. Test the route at boosted speed and while backtracking, including the joins between interior floors, stairs and terrain. ### 3. Qualify overlapping lighting zones FMV-25 already tracks this gate. Begin with two connected bounded places and a shared doorway. Load the destination before crossing; preserve walls and occluders needed by both sides. Compare fixed views on either side and through the opening. Do not brighten the doorway with an arbitrary fade and call it correct transport. The current backend owns one volume. Multiple zones need an explicit renderer contract for selection or blending, shared occluders, shadows and history resets. Measure the period when both zones and their buffers coexist. If it exceeds the device budget, reduce retained resources or revisit the lighting representation before adding another zone. Independent transport factorization can continue alongside this work, but is not already a streaming implementation. ### 4. Stream a bounded set of regions Use an explicit lifecycle: requested → building → ready → active → retiring → released, with failure and cancellation paths. Prepare collision and destination geometry before granting access. Keep the coarse terrain available throughout. Promote detailed geometry only when ready; maintain agreement with its silhouette. Use different load and unload distances, plus a short retention policy, so pacing across a threshold does not repeatedly destroy and rebuild the same place. Prioritize the likely route while retaining backtracking coverage. Limit concurrent work and bytes in flight. Every request carries a generation ID; a late response must not resurrect a region already cancelled or replaced. Cache ownership must be explicit. Region objects release their references; shared material/texture caches dispose only after the last owner releases them. Test delayed assets, failed requests, rapid turns, teleportation and scene disposal while builds are pending. A stalled request must leave a usable, intentional place rather than a hole in the ground. ### 5. Extend the architectural vocabulary Build a kit of columns, arch profiles, balconies, fabric, stone courses, doors and rooflines. Instance repeated meshes, batch compatible geometry, and share material atlases where appropriate. Use geometric detail for silhouettes and parallax; use normal/roughness detail for fine surface structure that need not change shape. Variation should respect a place: shared floor heights, streets that connect, roof drainage, foundations on slopes and sunlight reaching courts. Seeded variation supplies rhythm; authored landmarks supply memory. Limit transparent layers, moving shadows and reflective water because their costs extend beyond triangle count. Evaluate low-detail substitutions during motion, not only in still screenshots. Weather and time of day come later, with defined lighting invalidation and update budgets. ## How we decide whether an extension fits 1. Freeze reference cameras, route, lighting study, viewport, device and quality. Capture the sanctuary before changing it. Keep the original atrium fixture. 2. State the new region’s navigation, voxel spacing, shadow detail and residency limits before implementing it. Calibrate absolute frame and memory targets on each supported device rather than borrowing a headline from another machine. 3. Compare before/after in alternating ABBA order after warmup. Report frame intervals as frame intervals; use GPU times only with supported timestamp queries. 4. Walk the full route out and back, turn quickly at thresholds and inspect silhouettes, thin edges, shaded doorways and reflections. Check temporal trails and detail transitions at the faster movement speed too. 5. Repeat region transitions until caches settle; run sustained cycles with fixed bounds on retained regions, queued work and allocations. Test cold loads and disposal mid-load. Explain any growth instead of accepting a short average. 6. Ship the extension only when its visual and resource gates pass together. If it does not fit, simplify far detail, reduce uploads or shorten residency before degrading the nearby stonework and light that define this project. ## The next demonstration **Walk from the sanctuary to one house, enter its shaded interior, and return.** One route, two detailed places, persistent identities, stable terrain joins and a measured overlap budget. That demonstrates the machinery needed for a district. Then connect districts through cheaper countryside and keep repeating the same contract. The world's stored extent can grow while the expensive working set stays bounded. It will still need authoring, testing and storage proportional to what we choose to make distinctive. See [World boundaries](WORLD-BOUNDARIES.md), [Framework API](FRAMEWORK.md), [Radius quality gates](EXPANSION-01.md) and [Factorization](FACTORIZATION.md). Current whole-world target: **one million purposeful triangles**, qualified with materials, light, route and complete-render evidence. See [World geometry profile](WORLD-GEOMETRY-PROFILE.md). The existing 500,000-triangle single-assembly software guard is separate and unchanged.