# DREAMWELL 3D Physics Benchmark
**Path:** `docs/architecture/DREAMWELL_3D_PHYSICS_BENCHMARK.md`
| Title | Dreamwell 3D Physics Benchmark — DreamMatter Timelapse |
| Version | 1.0.0 |
| Status | Internal Benchmark Specification |
| Audience | Engine, rendering, runtime, benchmark, QA, and release engineers |
| Purpose | Validate DreamMatter dynamic-to-static materialization under a bounded GPU budget |
| Duration | 30 seconds |
| Output | Real-time benchmark run + KPI log + optional capture/export artifact |
| Default Resolution | 1920 × 1080 |
| Default VRAM Budget | 2 GiB total benchmark budget |
| Scene Type | 3D |
| Assets Required | None |
| Determinism | Authority-side deterministic; GPU presentation benchmark is non-deterministic |
---
## 1. Purpose
This document defines the first canonical visual and performance benchmark for Dreamwell’s 3D DreamMatter pipeline.
The benchmark demonstrates one complete DreamMatter lifecycle in a controlled scene:
* a bounded white Dreamlet swarm begins on the **left** side of a black room
* the swarm initially occupies a **sphere-shaped dynamic state**
* the swarm travels smoothly toward the **right** side of the scene
* the swarm converges into a **cube target**
* the swarm settles and materializes into a stable render representation
* the materialized form remains visible as a static/baked-style object
* the object can optionally dissolve back into DreamMatter at the end of the run
This benchmark is not a content showcase. It is a technical benchmark designed to validate:
* DreamMatter runtime states
* Dreamlet-to-DreamFabric transitions
* Quantum Culling
* PBR scene-shell rendering
* shadow and post-processing interaction
* observer-scoped rendering behavior
* GPU-only simulation and render preparation
* bounded VRAM operation
* stable frame pacing and performance metrics
---
## 2. Benchmark goals
The benchmark must prove the following in one 30-second run:
1. DreamMatter can render a high-density dynamic swarm without CPU particle updates
2. Dreamlets can maintain a coherent sphere-like swarm state
3. Dreamlets can translate across the scene under GPU simulation
4. Dreamlets can converge to a new target topology
5. Dreamlets can enter settled and materialized states
6. The materialized object can render as a stable PBR scene object
7. The pipeline remains inside a fixed VRAM budget, default 2 GiB
8. The frame pipeline remains stable and measurable throughout all runtime states
9. All major KPIs are emitted in a structured benchmark log
10. The scene can run with no external assets, textures, or models
---
## 3. Benchmark summary
### 3.1 Visual description
The benchmark scene is a black enclosed room with:
* black floor
* black walls
* black ceiling
* one white Dreamlet swarm sphere on the left
* one white cube target on the right
* one directional sun light
* one basic PBR-compatible room material setup
* one post-process stack
* one global illumination baseline
The Dreamlet swarm is rendered as white matter-like particles or micro-geometry units. The room is dark, uncluttered, and asset-free to ensure that the benchmark is focused on DreamMatter behavior and pipeline cost.
### 3.2 Scene intent
This benchmark is intentionally minimal.
It exists to isolate:
* simulation cost
* culling cost
* assembly cost
* materialization cost
* static representation cost
* total frame cost across state transitions
---
## 4. Benchmark scene specification
### 4.1 World layout
A simple room centered at origin.
Recommended dimensions:
* room width: 20.0 meters
* room depth: 12.0 meters
* room height: 8.0 meters
Recommended coordinates:
* Dreamlet swarm origin center: `(-5.0, 1.5, 0.0)`
* target cube center: `(5.0, 1.5, 0.0)`
* camera origin: `(0.0, 3.0, 11.0)` looking toward `(0.0, 2.0, 0.0)`
### 4.2 Geometry
Only primitive geometry is allowed.
Required geometry:
* floor plane
* back wall
* left wall
* right wall
* ceiling plane
* target cube
* optional hidden room front cutout for camera framing
No imported models.
No textures.
No authored assets.
No animation clips.
### 4.3 Materials
All materials use engine-provided defaults only.
Room material:
* base color: near-black
* roughness: high
* metalness: low
* emissive: none
Dreamlet dynamic material:
* base color: white
* roughness: low-to-mid
* metalness: 0 unless explicitly testing metallic mode
* emissive: optional low white emissive, disabled by default
Target/materialized cube material:
* base color: white
* roughness: mid
* metalness: 0 by default
### 4.4 Lighting
Minimum required lighting:
* one directional “sun” light
* one ambient / IBL / flat GI baseline
* one post-process stack
Recommended default:
* directional light yaw: 35°
* directional light pitch: -45°
* white light color
* stable shadow map enabled
* IBL fallback allowed if no HDR environment is loaded
### 4.5 Post-processing
Required:
* HDR render target
* bloom enabled at conservative settings
* tonemap enabled
Optional:
* vignette disabled
* chromatic aberration disabled
* film grain disabled
The benchmark should measure DreamMatter, not stylization noise.
---
## 5. Benchmark runtime states
The benchmark explicitly covers all five DreamMatter runtime states.
### 5.1 Swarm state
The Dreamlets behave like a loose sphere-shaped cloud.
Visual target:
* a stable sphere silhouette with local motion
* visible internal turbulence or low-amplitude motion
* no convergence toward cube yet
### 5.2 Convergence state
The Dreamlets begin moving to the right and gradually align to cube target topology.
Visual target:
* smooth lateral translation
* narrowing swarm spread
* increasing shape coherence
* visibly changing from sphere distribution to cube-compatible distribution
### 5.3 Settled state
The Dreamlets stop behaving like a loose cloud and occupy a near-complete cube volume.
Visual target:
* low-motion clustered matter
* cube silhouette mostly complete
* small residual motion allowed
### 5.4 Materialized state
The cube becomes a stable render representation.
Visual target:
* stable white cube
* rendered as ordinary scene shell geometry or stable DreamFabric proxy
* no visible particle turbulence except where explicitly testing hybrid mode
### 5.5 Dissolution state
Optional final phase.
Visual target:
* cube breaks apart back into DreamMatter
* Dreamlets return to loose state
* benchmark ends after confirming reverse transition
---
## 6. 30-second timelapse specification
The benchmark run is fixed at 30 seconds.
### 6.1 Timeline
| 0.0s – 4.0s | Initialization / steady swarm | Warm-up, stabilize scene, display sphere swarm |
| 4.0s – 10.0s | Swarm state | Loose sphere maintained on left side |
| 10.0s – 18.0s | Convergence state | Swarm travels right and converges toward cube |
| 18.0s – 22.0s | Settled state | Cube silhouette completes, low-motion residual settling |
| 22.0s – 27.0s | Materialized state | Stable static/baked-style cube render representation |
| 27.0s – 30.0s | Dissolution state (optional but recommended) | Cube dissolves back to swarm |
### 6.2 Warm-up requirement
The benchmark must include an initial warm-up phase.
Warm-up purpose:
* stabilize shader pipelines
* stabilize GPU clocks where possible
* fill persistent caches
* avoid including one-time init transients in steady-state metrics
Warm-up capture policy:
* collect warm-up metrics separately
* do not merge warm-up into steady-state averages unless explicitly labeled
---
## 7. Camera and observer setup
### 7.1 Camera policy
The benchmark camera is fixed.
Required:
* no free-fly movement during canonical benchmark run
* no shake
* no motion blur
* no user input influence
Recommended framing:
* both sphere origin and target cube visible simultaneously
* room boundaries visible enough to validate lighting/shadows
* camera positioned to show lateral travel clearly
### 7.2 Observer context
The benchmark must still run through full observer-scoped logic.
Required observer values:
* observer position derived from camera or benchmark observer anchor
* observer layer fixed to active scene layer
* observer radius sufficient to contain the benchmark scene
* Quantum Culling still active and measurable
Why:
* this validates the real production path rather than a bypass path
---
## 8. Benchmark technical configuration
### 8.1 Required runtime configuration
* resolution: `1920x1080`
* fullscreen: disabled by default, windowed benchmark mode preferred
* VSync: off by default for raw performance measurement; optional secondary run with VSync on
* frame pacing capture: enabled
* debug overlays: off for canonical run
* profiler markers: on
* post-process: on
* PBR shell: on
* shadows: on
* IBL/GI baseline: on
* Quantum Culling: on
* DreamMatter: on
* mesh shader path: on if supported, else vertex fallback
### 8.2 Default DreamMatter config
These are recommended defaults for the first benchmark and may be revised after profiling.
* Dreamlet count target: 250,000 to 1,000,000 depending on hardware tier
* default reference count: 500,000 Dreamlets
* primitive class: white sphere-like or shard-like micro-geometry
* dynamic radius of initial sphere: 1.25 meters
* target cube edge length: 2.5 meters
* emission disabled after initialization; benchmark focuses on state transition rather than continuous spawning
* promotion/materialization threshold explicit and logged
### 8.3 VRAM budget
Default benchmark VRAM budget:
* **2 GiB total**
This includes:
* DreamMatter buffers
* meshlet buffers
* PBR buffers
* shadow maps
* HDR target
* bloom mips
* IBL resources
* indirect draw buffers
* readback buffers
* fallback/default resources
The benchmark must log:
* total VRAM reserved
* estimated VRAM active by subsystem
* peak VRAM during run
### 8.4 Hardware tiers
The benchmark should support at minimum:
* Tier A: modern desktop GPU with mesh shader support
* Tier B: modern desktop GPU without mesh shader support but with compute capability sufficient for fallback path
Benchmark reports must identify which path was used.
---
## 9. Formal benchmark pass graph
The benchmark uses the standard Dreamwell render graph.
### 9.1 Per-frame sequence
1. update observer context
2. upload observer uniform
3. run Quantum Culling
4. run DreamMatter simulate
5. run DreamMatter convergence/materialization logic
6. run DreamMatter cull/compact
7. update DreamFabric promotion cache if thresholds are met
8. render shadow pass
9. render main PBR scene
10. render DreamMatter dynamic geometry or DreamFabric static geometry as applicable
11. run post-process bloom + tonemap
12. present
13. record KPIs
### 9.2 Phase ownership
| Observer update | `ObserverChannel` |
| Culling | `QuantumCullPass` |
| Simulation | `DreamMatterSystem` |
| Materialization / promotion | `DreamMatterSystem` + `DreamFabric` + `Tapestry` |
| Main scene render | `GpuScene` / `DreamFabric` |
| Post-process | `PostProcessStack` |
| KPI capture | benchmark harness |
---
## 10. Algorithms used and where
### 10.1 Algorithm A — Observer context upload
**Used in:** every frame before GPU compute begins
**Why:** ensures the benchmark uses the same observer-scoped path as production scenes
**Benchmark expectation:**
* one observer uniform write per frame
* no redundant uploads
### 10.2 Algorithm B — Quantum Culling
**Used in:** every frame, before DreamMatter render preparation and meshlet rendering
**Why:** validates observer-scoped visible-work reduction even in a simple demo room
**Benchmark expectation:**
* visible cluster count is logged
* culled cluster count is logged
* culling cost is logged in GPU timings
### 10.3 Algorithm C — DreamMatter simulation
**Used in:** every frame in dynamic, convergence, and dissolution states
**Why:** validates GPU-only matter simulation and stable frame cost under load
**Benchmark expectation:**
* active Dreamlet count logged
* simulation pass timing logged
* no CPU-side per-Dreamlet update
### 10.4 Algorithm D — DreamMatter convergence
**Used in:** convergence state
**Why:** validates topology transition from sphere swarm to cube target
**Benchmark expectation:**
* convergence completion ratio logged
* assembly coherence metric logged
### 10.5 Algorithm E — Settling classifier
**Used in:** convergence-to-settled transition
**Why:** validates transition from loose matter to low-motion cluster
**Benchmark expectation:**
* settled cluster count logged
* threshold crossing timestamp logged
### 10.6 Algorithm F — Materialization promotion
**Used in:** settled-to-materialized transition
**Why:** validates conversion from expensive dynamic matter to stable scene-shell representation
**Benchmark expectation:**
* materialization promotion event logged
* static representation generation timing logged
* dynamic Dreamlet cost reduction logged
### 10.7 Algorithm G — Dissolution
**Used in:** final optional phase
**Why:** validates reverse transition and confirms reversible DreamMatter lifecycle
**Benchmark expectation:**
* dissolution start/end timestamps logged
* restored dynamic count logged
---
## 11. KPI specification
The benchmark must emit structured KPIs per phase and for the full run.
### 11.1 Global KPIs
* benchmark name
* build hash
* runtime version
* GPU adapter name
* backend used
* mesh shader path or fallback path
* resolution
* total run duration
* average FPS
* p50 frame time
* p90 frame time
* p95 frame time
* p99 frame time
* max frame time
* average GPU frame time
* peak VRAM usage
* total VRAM reserved
### 11.2 DreamMatter KPIs
* configured Dreamlet capacity
* active Dreamlet count by frame
* visible Dreamlet count by frame
* compacted Dreamlet count by frame
* settled Dreamlet count by frame
* materialized DreamFabric count by frame
* dissolution count if used
* dropped Dreamlet events due to overflow
### 11.3 Quantum Culling KPIs
* total clusters considered
* visible clusters
* culled clusters
* indirect draw count
* average cull pass time
* p95 cull pass time
### 11.4 State transition KPIs
* time to stable swarm
* time to convergence start
* time to convergence completion
* time to settled threshold
* time to materialization
* time to dissolution start
* time to dissolution completion
### 11.5 Render pass KPIs
* observer upload time
* Quantum Culling time
* DreamMatter simulate time
* DreamMatter convergence/materialization time
* shadow pass time
* main PBR pass time
* post-process time
* total GPU frame time
---
## 12. Acceptance criteria
### 12.1 Functional acceptance
The benchmark passes functionally if:
* the swarm is visible on the left at start
* the swarm travels smoothly to the right
* the swarm converges into a cube-like shape
* the cube settles visibly
* the cube materializes into a stable render representation
* the optional dissolution state completes successfully if enabled
* no external content assets are required
### 12.2 Performance acceptance
The benchmark passes performance if all declared target hardware tiers meet their minimum thresholds.
Recommended baseline release thresholds for the default 2 GiB / 1920×1080 test:
#### Tier A — mesh shader capable desktop GPU
* average FPS >= 60
* p95 frame time <= 20 ms
* no catastrophic frame spikes during materialization transition
* no VRAM overflow
#### Tier B — fallback path desktop GPU
* average FPS >= 30
* p95 frame time <= 33 ms
* no VRAM overflow
* transitions remain visually correct under fallback path
### 12.3 Stability acceptance
The benchmark fails if:
* device lost is triggered by benchmark load
* buffers overflow incorrectly
* indirect args become invalid
* materialization causes sustained corruption or instability
* promotion/demotion oscillates uncontrollably
* frame pacing becomes pathological during state changes
---
## 13. Benchmark implementation checklist
### 13.1 Scene setup
* [ ] Create black room from primitive geometry only
* [ ] Create left-side DreamMatter sphere initial condition
* [ ] Create right-side cube target representation
* [ ] Configure fixed camera
* [ ] Configure sun light
* [ ] Configure PBR scene shell
* [ ] Configure HDR + bloom + tonemap
* [ ] Configure GI/IBL baseline
### 13.2 DreamMatter setup
* [ ] Initialize Dreamlet pool
* [ ] Set bounded capacity
* [ ] Set sphere swarm initial distribution
* [ ] Set cube target topology
* [ ] Set convergence policy
* [ ] Set settled threshold
* [ ] Set materialization promotion threshold
* [ ] Set optional dissolution policy
### 13.3 Benchmark harness
* [ ] Add fixed 30-second benchmark controller
* [ ] Add phase timestamps
* [ ] Add per-pass GPU timing queries
* [ ] Add per-frame KPI logging
* [ ] Add VRAM accounting log
* [ ] Add final summary emission
* [ ] Add optional video capture hook
### 13.4 Output
* [ ] Human-readable console summary
* [ ] machine-readable JSON or benchmark envelope
* [ ] optional CSV frame log
* [ ] optional capture/export artifact
---
## 14. Suggested benchmark output schema
```json id="3fz4pk"
{
"benchmark": "dreamwell_3d_physics_benchmark_v1",
"duration_seconds": 30,
"resolution": { "width": 1920, "height": 1080 },
"gpu": {
"adapter": "<name>",
"backend": "vulkan",
"mesh_shader_path": true
},
"budgets": {
"vram_budget_bytes": 2147483648,
"vram_peak_bytes": 0
},
"dreammatter": {
"capacity": 500000,
"peak_active": 0,
"peak_visible": 0,
"peak_materialized_fabrics": 0,
"dropped_spawns": 0,
"dropped_promotions": 0
},
"timings": {
"frame_ms_avg": 0.0,
"frame_ms_p95": 0.0,
"gpu_frame_ms_avg": 0.0,
"quantum_cull_ms_avg": 0.0,
"simulate_ms_avg": 0.0,
"materialize_ms_avg": 0.0,
"shadow_ms_avg": 0.0,
"pbr_ms_avg": 0.0,
"post_ms_avg": 0.0
},
"states": {
"swarm_start_s": 0.0,
"convergence_start_s": 10.0,
"settled_start_s": 18.0,
"materialized_start_s": 22.0,
"dissolution_start_s": 27.0
}
}
```
---
## 15. Hot-path requirements for this benchmark
The benchmark must exercise the production path, not a special-case fake path.
### Required hot-path rules
* no per-frame Dreamlet allocation
* no per-frame shader or pipeline creation
* no per-particle CPU updates
* no synchronous readback in steady-state path
* no asset loading on the frame path
* no per-frame rebuild of room or target geometry
* no debug overlay in canonical benchmark run
### Specific gotchas to avoid
* do not animate the sphere and cube with CPU transforms alone and call it DreamMatter
* do not swap a hidden static cube in without logging the true materialization transition
* do not let post-process dominate frame cost in this benchmark
* do not let shadow settings mask DreamMatter cost by overwhelming the GPU budget
* do not use unbounded emitter behavior
* do not exceed VRAM budget and silently rely on driver paging
---
## 16. Recommended visual polish constraints
To keep the benchmark technically honest:
* white matter only
* black room only
* no textures required
* no imported HDRI required
* no decals
* no animated cameras
* no stylized grading
* no cinematic tricks that hide instability
The benchmark should look clean, minimal, and technically legible.
---
## 17. Benchmark variants
After the canonical benchmark is stable, the following variants are recommended.
### Variant A — mesh shader path
Default high-end run.
### Variant B — vertex fallback path
Same visual benchmark, no mesh shaders.
### Variant C — no post-process
Measures raw DreamMatter + PBR + shadow cost.
### Variant D — no materialization
Measures sustained dynamic swarm cost.
### Variant E — repeated dissolve/materialize loop
Stress-tests state transition stability.
---
## 18. Final release rule
This benchmark is considered release-ready only if:
* the visual state progression is correct
* the KPI output is complete
* the benchmark is reproducible
* the benchmark remains inside the declared VRAM budget
* the benchmark uses the real production render graph
* both mesh-shader and fallback paths are validated where applicable
* the benchmark is simple enough that future regressions are attributable
---
## 19. Summary
`DREAMWELL_3D_PHYSICS_BENCHMARK.md` defines the first canonical DreamMatter visual benchmark: a 30-second, asset-free, 1920×1080 black-room scene in which a white Dreamlet sphere swarm transitions through all DreamMatter runtime states while traveling from left to right and materializing into a cube. The benchmark is explicitly designed to validate DreamMatter, DreamFabric, Quantum Culling, PBR integration, bounded VRAM behavior, and hot-path cleanliness under one controlled, reproducible workload.