Repository navigation
[Epic] UE5/UE6-class rendering quality with raylib/Unity simplicity #126
Description
Outcome
Ship a rendering stack that can credibly target UE5/UE6-class image quality while keeping Bloom's public experience small enough for a raylib user and familiar enough for a Unity developer.
This is an execution roadmap, not another feature wishlist. The existing quality inventory in #11 remains the visual-gap backlog. This issue orders the architectural work, defines the proof required to call a feature complete, and links bounded child issues that can be assigned independently.
Product contract
Bloom should provide:
- a high-end desktop path with modern geometry, lighting, shadows, materials, temporal reconstruction, and hardware ray-query enhancements;
- explicit lower capability tiers for desktop iGPUs, mobile, and web, with intentional fallbacks rather than silent no-ops;
- reference-scene evidence for visual claims and GPU captures for performance claims;
- a simple TypeScript-facing workflow: load or create a scene, attach behavior, press run, and ship without hand-marshalling native pointers.
“UE quality” here does not mean cloning every Unreal subsystem. It means the engine has the foundational architecture and a measurable path to high-end output, with quality claims backed by images and timings.
Current assets to preserve
- Shared
wgpurenderer with deferred PBR, screen-probe GI, HW ray-query/SDF/Hi-Z fallbacks, mesh cards/WSRC, TSR/TAA, SSR, cascaded shadows, atmosphere, custom materials, path tracing, particles, decals, and profiling. - Jolt physics, world/prefab serialization, animation, audio, and broad platform targets.
- Existing reference tooling in
tools/bloom-reference,tools/cycles_reference, andtools/validate.sh. - Existing performance investigations under
docs/perf/and path-tracer design underdocs/pt/.
Execution order
Wave 0 — truth and release gates
- Make the path tracer and visual reference corpus trustworthy.
- Add deterministic visual/performance qualification.
- Make local and CI gates agree and block regressions.
- Define capability tiers and validate fallbacks.
No renderer rewrite may claim parity or improvement without passing this wave's gates.
Wave 1 — rendering foundations
- Compile the render graph: resource lifetimes, aliasing, validation, and topology caching.
- Establish capability-tiered global geometry/material/texture indirection.
- Execute perf ticket 009: GPU-driven rendering — indirect multi-draw + GPU cull #28 (GPU-driven submission) and then perf ticket 008: visibility buffer (Nanite-style) replaces 4-MRT G-buffer #27 (visibility buffer); preserve a compatibility path for unsupported/skinned/translucent content.
- Remove steady-state per-frame allocation/upload churn.
Wave 2 — high-impact quality systems
- Virtualized meshlet geometry with automatic LOD/HLOD and streaming.
- Virtual shadow maps and scalable many-light shadowing.
- Correct glTF transparency/transmission and a layered PBR material model.
- Temporal stability qualification and fixes across TSR/TAA, SSR, GI, and path tracing.
- Production asset cooking and asynchronous streaming.
Wave 3 — simple authoring and delivery
- A generated FFI contract with Perry-safe collection/buffer APIs.
- One-command native/web starters and a compile-tested example matrix.
- Unity-like component/lifecycle conveniences above the low-level API.
- A retained-mode game UI layer.
- Cross-platform shader/runtime asset packaging and UTF-8 correctness.
Existing specialized follow-ups
- watchOS: Metal-shader post-FX (chromatic aberration, film grain, sun shafts) #16 watchOS Metal post-FX umbrella (platform API limitation; coordinate with watchOS: SCNTechnique-based post-fx for 3D-layer effects #18)
- watchOS: SCNTechnique-based post-fx for 3D-layer effects #18 watchOS SCNTechnique post-FX path for the 3D layer
- Lumen follow-up: true CDF-based importance sampling for probe rays #19 true CDF probe importance sampling
- Lumen follow-up: variance-driven refinement probe layer #20 variance-driven refinement probes
- Lumen follow-up: multi-cascade SDF clipmap #21 multi-cascade SDF clipmaps
- Lumen follow-up: true octahedral corner wrap for WSRC borders #23 WSRC octahedral corner wrapping
- Lumen follow-up: benchmark harness for SSGI quality / convergence #24 GI benchmark harness (absorbed into the broader quality harness unless kept independently useful)
- Lumen follow-up: multi-bounce GI via WSRC feedback #25 WSRC multi-bounce feedback
- perf ticket 010: async compute for post-FX (blocked on wgpu multi-queue) #29 async compute when
wgpuexposes safe multi-queue support - perf ticket 012: cache 5 remaining per-frame bind groups (V1 regressed) #30 remaining bind-group caches after screenshot-diff coverage exists
- How to build the example projects? #48 legacy example build/runtime report (workflow under [DX] Ship a one-command starter and compile/run every canonical example #142; residual defects stay independently verifiable)
- aarch64 Linux build + runtime: XLookupString mismatch, max_color_attachments limit, lib name #55 aarch64 Linux/Asahi build and runtime negotiation (coordinate capability tiers in [Platform] Define renderer capability tiers and validate every fallback #138 and packaging in [Platform] Package shader runtime dependencies and enforce UTF-8 end to end #145)
- Default
render_scale=0.5+ TAA + no sharpening makes output blurry #56 sharp native defaults / quality presets - Web: Bloom WASM functions trap with 'unreachable' after FFI bridge fix (#73) #74 web WASM startup trap
Implementation-ready child issues
Wave 0 — truth and release gates
- [Rendering][P0] Restore deterministic path-tracing goldens and oracle correctness #127 — restore deterministic path-tracing goldens and oracle correctness
- [Quality][P0] Add deterministic reference-scene visual and GPU performance qualification #128 — deterministic reference-scene visual/GPU performance qualification
- [Platform] Define renderer capability tiers and validate every fallback #138 — renderer capability tiers and validated fallbacks
- [CI] Make local, PR, hardware, and release quality gates truthful #140 — truthful local, PR, hardware, and release gates
Wave 1 — rendering foundations
- [Renderer] Compile the render graph with lifetime planning, aliasing, and topology caching #129 — compiled render graph with lifetime planning, aliasing, and topology caching
- [Renderer] Add capability-tiered global material and texture indirection #130 — capability-tiered global material/texture indirection
- perf ticket 009: GPU-driven rendering — indirect multi-draw + GPU cull #28 — GPU-driven submission (existing prerequisite)
- perf ticket 008: visibility buffer (Nanite-style) replaces 4-MRT G-buffer #27 — visibility-buffer shading (existing prerequisite)
- [Renderer] Make the steady-state frame allocation-stable and upload-efficient #139 — allocation-stable, upload-efficient steady-state frame
Wave 2 — high-impact quality systems
- [Renderer] Build virtualized meshlet geometry with automatic LOD and streaming #131 — virtualized meshlet geometry, automatic LOD, and streaming
- [Renderer] Add virtual shadow maps with cached pages and scalable many-light shadows #132 — virtual shadow maps and scalable many-light shadows
- [Materials] Implement correct glTF alpha blending, transmission, volume, and refraction #133 — correct glTF alpha blending, transmission, volume, and refraction
- [Materials] Add a shared energy-conserving layered PBR model #134 — shared energy-conserving layered PBR
- [Rendering] Unify temporal history and eliminate TSR, SSR, GI, and PT instability #135 — unified temporal history and TSR/SSR/GI/PT stability
- [Assets] Build a deterministic versioned cooked asset database #136 — deterministic versioned cooked asset database
- [Runtime] Add asynchronous asset and world streaming with budgets and HLOD #137 — asynchronous asset/world streaming with budgets and HLOD
Wave 3 — simple authoring and delivery
- [API] Generate the FFI surface from one schema and remove pointer-only APIs #141 — generated FFI schema and Perry-safe collection APIs
- [DX] Ship a one-command starter and compile/run every canonical example #142 — one-command starter and compile/run-tested canonical examples
- [Framework] Add an optional Unity-like component and lifecycle facade #143 — optional Unity-like components and lifecycle facade
- [UI] Add a retained-mode runtime UI with layout, input, and accessibility #144 — retained-mode runtime UI
- [Platform] Package shader runtime dependencies and enforce UTF-8 end to end #145 — shader-runtime packaging and UTF-8 correctness
Definition of done for child issues
Every child issue must include, and every implementing PR must report:
- Architecture: ownership, data flow, public API impact, platform path, and fallback path.
- Correctness: automated unit/integration/golden coverage plus named reference scenes and camera poses.
- Quality: SSIM/FLIP or targeted semantic metrics against the pre-change image and, when relevant, the CPU path-traced reference.
- Performance: before/after GPU and CPU timings with vsync disabled, warm-up frames excluded, adapter/backend/resolution recorded, and VRAM impact stated.
- Compatibility: opaque, alpha-tested, translucent, skinned, instanced, custom-material, and missing-feature behavior explicitly considered.
- Documentation: public APIs, capability requirements, debug views, and migration notes updated in the same PR.
- No hidden fallback: requested unsupported behavior returns a capability result or documented fallback; it must not silently become a no-op.
Quality target scenes
At minimum, maintain fixed-camera coverage for:
examples/pbr-spheres— BRDF energy and material lobes;examples/sponza— interiors, GI leakage, shadowing, overdraw, and temporal stability;examples/bistro— open-world scale, texture/geometry pressure, atmosphere, and sunlight;examples/test-gltf-watch/assets/DamagedHelmet.glb— canonical glTF material fidelity;- a moving skinned/alpha-tested scene — deformation, disocclusion, foliage/hair-like coverage;
- a stress scene with at least 10,000 cullable meshlets/instances and hundreds of lights.
The harness must store scene/version/camera/config metadata beside each result so comparisons are reproducible.
Guardrails
- Preserve the current immediate-mode APIs and existing game source compatibility unless a separately documented migration is approved.
- Do not make bindless, ray query, mesh shaders, or multi-draw mandatory for every adapter.
- Do not optimize solely against a vsync-capped result; record uncapped pass timings.
- Do not update golden baselines until the diff is reviewed and the cause is documented.
- Avoid feature work that only adds a toggle. Each feature needs a useful default, a quality-tier assignment, and a diagnostic/debug view.
Source map
- Renderer:
native/shared/src/renderer/, especiallymod.rs,graph.rs,scene_pass.rs,material_*, andshaders/ - Scene/assets:
native/shared/src/models*.rs,native/shared/src/textures.rs,src/world/,tools/bloom-cook/ - Public API/FFI:
src/,native/shared/src/ffi_core/, platformnative/*/src/lib.rs,package.json - Validation:
native/shared/tests/golden_render.rs,tools/validate.sh,tools/bloom-reference/,.github/workflows/test.yml,scripts/ci-check.sh - Prior design:
docs/rfc/0001-material-render-graph.md,docs/perf/,docs/pt/,docs/tickets.md
Non-goals
- An editor clone of Unreal Editor.
- Requiring high-end hardware for baseline games.
- Treating a long checklist as evidence of quality.
- Landing all work in one PR or one renderer branch.
Activity
proggeramlug commentedon Jul 28, 2026
Open-issue reconciliation (2026-07-28): the repository currently has 34 open issues.
Current implementation sequence in draft PR #147 is evidence-first Wave 0 / temporal-foundation work: #127, #128, #135, and the focused Hi-Z SSGI qualification in #24. Completed prerequisites #129, #130, and #28 were still unchecked here; their checkboxes are now corrected. #27 remains deliberately deferred until an A/B demonstrates a net-positive visibility-buffer path.
Tracker discipline going forward: post issue updates only at evidence-bearing checkpoints (validated commit, quality/performance measurements, dependency or blocker change), link the exact PR/commit, and close only when the issue acceptance criteria are met. Exploratory attempts that are reverted will stay in the PR history or focused issue notes rather than creating misleading progress noise.
proggeramlug commentedon Jul 29, 2026
Wave 2 update: #132 is complete and closed on draft PR #147 at
69b7403; both the Wave 2 outcome and child-ticket checkboxes are now checked here.The completed VSM path includes bounded directional clipmaps, receiver demand, fixed shared residency, invalidation/cache reuse, CSM failover, seam-safe sampling, alpha-tested/skinned/dynamic caster coverage, debug views/per-light cost, fixed Sponza/Bistro motion qualification, 128-request point cubes, and 128-request one-page spot projections. All #132 acceptance boxes are complete. The final spot oracle and regression evidence are in
docs/evidence/issue-132-spot-lights-v1.{md,json}.proggeramlug commentedon Aug 9, 2026
Roadmap checkpoint: #27 now has a single-traversal depth + packed-ID path and in-pass reconstructed PBR composition in PR #147 (commit 9cebeef). On the governed Bistro Metal run it is 16.6% faster in GPU mean and 1.0% faster in total wall time than forward, while passing strict per-MRT parity and the scene visual gate. #27 remains open for discrete-Vulkan and broader moving/compatibility corpus qualification; it is still opt-in. After CI settles, the next planned rendering-quality slice is #135 unified temporal history/stability.
proggeramlug commentedon Aug 9, 2026
#131 has reached its first runtime checkpoint in c2a0bd2 / 10ccfc2 (PR #147): cooker/runtime now share one strict archive reader, indexed artifact identity is verified, coarse roots are pinned under a hard logical page budget, atomic group transitions use deterministic eviction, and missing detail resolves to the nearest fully resident ancestor.\n\nThe implementation remains explicitly unowned by the default renderer. Exact detached-HEAD A/B produced identical renderer-path telemetry across six captures and no timing regression. Full shared/golden/visibility/cooker/quality gates pass.\n\nNo #131 acceptance box is claimed yet because GPU allocation, staging overhead, per-frame IO budgets, traversal, 10M-triangle stress, and hardware qualification remain. Evidence:\nhttps://github.com/Bloom-Engine/engine/blob/codex/rendering-wip-integrated-20260727/docs/evidence/issue-131-runtime-residency-v1.md
proggeramlug commentedon Aug 9, 2026
Wave 2 / #131 progress is pushed in
6dbbb02+8368cdcon PR #147: Bloom now has explicit, fixed-capacity GPU storage for validated virtual-geometry pages, stable generation-safe mesh/page IDs, fixed GPU tables, pinned coarse roots, atomic group transitions, global deterministic LRU, bounded per-frame upload/eviction work, queue-fenced reuse, and exact Metal readback evidence.This does not change the established renderer or any pixels: the pool has no production owner and the compatibility model path remains intact. The complete quick lane and native/wasm
models3dchecks pass. #131 remains open; projected-error GPU traversal, culling, indirect visibility submission, streaming feedback, stress/motion qualification, and integrated/discrete staging captures are next.Detailed evidence: https://github.com/Bloom-Engine/engine/blob/codex/rendering-wip-integrated-20260727/docs/evidence/issue-131-gpu-page-pool-v1.md
proggeramlug commentedon Aug 9, 2026
Virtualized-geometry progress on child #131 is pushed in b863d12 with evidence in 5010f3e on PR #147.
The GPU now traverses the cooked cluster hierarchy by projected pixel error with conservative frustum/cone behavior, complete-child residency checks, resident-ancestor fallback, bounded missing-page requests, and explicit overflow telemetry. Real Metal output matches an independent CPU oracle across LOD thresholds, missing pages, culling, overflow, non-uniform transforms, camera cuts, and fast motion.
This remains isolated from the shipping renderer: no production owner, pass, draw, allocation, binding, branch, or pixel changed. The complete governed quick lane and native/wasm models3d checks pass.
Evidence: https://github.com/Bloom-Engine/engine/blob/codex/rendering-wip-integrated-20260727/docs/evidence/issue-131-gpu-hierarchy-traversal-v1.md
No parent or child acceptance checkbox changes yet. The next dependency is raw-page decode plus bounded indirect visibility emission with whole-batch compatibility fallback on overflow, followed by conservative Hi-Z and asynchronous streaming feedback.
proggeramlug commentedon Aug 9, 2026
UE-class rendering roadmap update: the virtualized-geometry path has advanced from GPU hierarchy selection to executable bounded indirect work and direct cooked-page vertex decoding.
Checkpoint: 92daf0e
Evidence: https://github.com/Bloom-Engine/engine/blob/74d114b/docs/evidence/issue-131-virtual-draw-emission-v1.md
This contributes the scalable geometry foundation: selected resident meshlets now become GPU-authored indirect commands, both lossless and packed cooked vertices decode directly from fixed page residency, partial selection failure suppresses the whole virtual batch, and actual Metal raster execution is proven. The established renderer remains byte-for-byte isolated because the new objects have no Renderer, scene, frame-graph, glTF, or FFI owner.
The next roadmap slice is not another isolated geometry primitive: it is the temporal instance/material-remap ABI needed to compose these virtual draws through #27 with the exact production PBR shader and current/previous transforms. That integration will remain opt-in until individual HDR/material/velocity/albedo MRT parity, Bistro/stress images, non-count platform fallback, and total GPU-time gates all pass.
proggeramlug commentedon Aug 9, 2026
Wave 2 progress in PR #147: #131 now has a qualified raw-page decoder, bounded indirect emission, and temporal/material render ABI. The latest code/evidence checkpoints are 1b4d828 and f2b71d6.
The latest governed quick lane passed with all existing goldens and visibility parity/runtime tests, and the shipping path remains unchanged because virtual geometry is still opt-in and unowned by Renderer/EngineState. Next is the first opt-in #131-to-#27 visibility integration, followed by per-MRT, Bistro/stress, timing, and adapter gates before any default activation.
proggeramlug commentedon Aug 9, 2026
Roadmap checkpoint: #131 now has a qualified raw virtual visibility raster and shared collision-free ID namespace (
6d1183d,688db93, evidence/docs1fce846). It remains opt-in/unattached with zero default renderer work or pixel change.Next is exact virtual PBR reconstruction and all-MRT parity through #27, followed by compatibility routing, bounded non-count submission, Bistro temporal/crack captures, stress, and timings. No parent acceptance box changes at this intermediate boundary.
proggeramlug commentedon Aug 9, 2026
Rendering roadmap checkpoint: virtualized geometry can now reconstruct and shade through the production PBR/material/lighting ABI without changing the default renderer.
Qualified code
9b3130f; evidence311b6ffindocs/evidence/issue-131-virtual-visibility-pbr-v1.{md,json}. Real Metal oracles cover temporal clips, normals/tangents including mirrored transforms, UV/tint/material/face state, mixed mesh encodings, and exact four-MRT production pipeline construction. The redundant mesh-table fetch was removed, keeping this net-positive and within the 8-storage-buffer core contract. Full quick CI passed in 122 seconds.The next roadmap slice is production visibility ownership/routing and MRT composition. Activation remains off until that slice and the bounded non-count fallback are independently qualified.
proggeramlug commentedon Aug 9, 2026
Rich Bistro user-validation checkpoint (2026-08-09):
Confirmed good in the user-driven interior/exterior walkthrough: glass, direct light, GI contribution, and directional shadows are visually consistent from all tested angles. Three remaining failures were isolated rather than attributed generically to "asset quality":
Both completed checkpoints are pushed to draft PR #147. No completed item added a production pass, draw, dispatch, texture, or bind group, and matched Bistro measurements show no frame-time regression.
proggeramlug commentedon Aug 10, 2026
Wave 2 materials checkpoint: #133 and #134 are now closed. The epic checklist now records correct alpha/transmission/volume/refraction and the shared layered-PBR model as complete. #134 final closure is
2b99693+ evidencee8d67e7, with process-isolated forward/visibility raw-MRT parity across every scalar lobe plus the combined material, layered forward/PT/reference response coverage, and zero shipping runtime cost from the qualification gate.