Repository navigation
Native Plume Renderer
The Native Plume Renderer (runtime/render/native_renderer.cpp, runtime/render/native_feed.cpp, src/render_queue.cpp, src/native_world.cpp, src/bone_pose.cpp, src/car_damage.cpp, src/native_shadows_flares.cpp, src/native_effects_imm.cpp, src/native_fog.cpp, src/native_texstate.cpp) replaces PlayStation 2 VU1 microcode execution and GS rasterization with a commercial-grade native GPU pipeline built on Plume (the MIT render interface behind RT64 and Unleashed Recompiled, supporting Vulkan on Windows/Linux and Metal on macOS).
Why Plume Instead of Filament? Filament was evaluated and rejected (
docs/NATIVE_RENDERER.md): it reorders draws internally (breaking the PS2's strict submission-order transparency), its material model cannot express all PS2 GS alpha-blend equations(A - B) * C + D(including reverse-subtract shadow volume passes), it only builds with MSVC on Windows (incompatible with our LLVM-MinGW toolchain), and no shipped game uses it. Plume gives us direct, low-overhead command-list control over Vulkan and Metal on a single shared device.

Every Plume draw originates directly in a decompiled EE C++ function (src/*.cpp) verified to 0 mismatches by EOD_DIFF—never by guessing cameras or geometry from raw VU1/GS traffic. From the same per-frame decompiled scene feed, Plume renders two looks switchable mid-race in 1 frame (<= 33 ms) via F9 (or controller L1 + R1 + R3):
| Feature | PS2 Classic Look (ModernRenderer=0) |
Modern Remastered Look (ModernRenderer=1) |
|---|---|---|
| Draw Order & State | Strict game submission order; exact GS TEST_1, ALPHA_1, ZBUF_1, CLAMP_1, and TEX1 state reconstructed from decompiled EE setters (ee_state). |
Opaque/alpha passes fed by the same decompiled scene records; blend equations always come from the game's render state so fx / emissive_light cards never render as solid walls. |
| Lighting & Materials | Exact VU1 microcode lighting (min(TOPS+5 + max(0, n·vf12)*TOPS+4, 128)), car body TFX HIGHLIGHT2 specular (max(0, 1152(n·h) - 1056)), and prelit V4-5 world vertex colors (Cv * Ct >> 7). |
Filament's published BRDF & IBL math in our own HLSL (native_shaders.hlsl) driven by 2,728 tagged textures in material_table.json: clear-coat car paint, chrome, glass, rubber, dirt, asphalt, sky IBL, and screen-space reflections (SSR). |
| Shadows | Full-resolution extruded 3D shadow volumes (MSCAL 4, 0x34C208/0x34C4B0): pass 1 additive front-faces (Cd + Cs), pass 0 subtractive back-faces (Cd - Cs), composited at intensity / 128.0 (PS2 320×512 cap removed!). |
Cascaded directional sun shadows + soft contact grounding. |
| Particles & VFX | Exact PS2 camera-aligned rotated quads (VU1 0x08E0 particles, 0x01B8 simple sprites, 0x05E0 atlas sprites, 0x304D50 lens flares). |
Depth-faded soft GPU particles, multi-layered volumetric fire/smoke for exploding chickens & exhaust flames, GPU embers/sparks, HDR emissive bloom, and dynamic point-light flashes on nearby cars and terrain. |
Water (AFTON.TRK) |
Decompiled WaterDraw (0x325728) & WaterSimulate (0x325E40) wave ripple strips in 1P and 2P/4P split-screen. |
Animated wave surface with fresnel reflections and depth refraction. |
| Textures & Scale | Native CLUT textures with exact TEX1 mipmap LOD (LOD = -log2approx(Q) << L + K) plus support for 4K .eodhtx HOSTTEX overrides at RenderScale 1x–8x+. |
Full trilinear/anisotropic mip chains, 4K/8K HOSTTEX overrides, and PBR roughness/metallic/normal parameterization. |
All 3D geometry in Test Drive: Eve of Destruction is stored on disc as prebuilt PlayStation 2 VIF1 DMA command streams inside 4SPS chunks (.mod standalone MODL v9 files and track.grf GRAF v18 embedded mrModel records).
Our standalone C++17 decoder (runtime/render/vif_mesh.{h,cpp}, ported from tools/vif_mesh.py and verified by tools/tests/vif_mesh_test.cpp) decodes the entire retail disc in 157–160 ms on a single thread (12.3 million vertices/second, 180× faster than Python):
-
Retail Census Verified (
0errors,0mismatches vs. Python reference):-
72
0TSRv6 archives · 505MODL/GRAFmembers · 34,564 models · 44,5844SPSparts · 67,551 VU1 batches · 1,969,433 vertices · 1,113,759 triangles.
-
72
Each 4SPS part has its byte size at +0x04, 16-byte null-terminated texture name at +0x08, damage/visibility group at +0x18 (bits 0..15 = group 0..31, bit 16 = 0x10000 body livery paintable flag), VIF qword count qwc at +0x34, and raw VIF1 stream starting at +0x38.
Inside VU1 data memory, each batch (terminated by an MSCAL or MSCNT kick) unpacks:
| VU1 Qword Address | VIF UNPACK Format |
Decoded Attribute & Mathematical Formula |
|---|---|---|
qword 0 |
V1-32 |
Vertex count n = word0 & 0x7FFF (bit 15 set). |
qword 2 + 3i |
V3-16 / V3-8 / V3-32 (offset mode) |
3D Position: track.grf), q199.xyz holds the world-space translation offset! |
qword 1 + 3i (Normals) |
V4-8 offset, STROW = (65536.0f, 65536.0f, 65536.0f, 0x7F80)
|
Signed Unit Normal (recognised by unpacked X lane & 0xFFFFFF00 == 0x47800000; 601,688 vertices across cars, props, drivers): ADC strip-restart flag = byte 3 bit 7. |
qword 1 + 3i (Prelit Colors) |
V4-5 (16-bit R5G5B5A1) or non-0x47800000 V4-8
|
Prelit Vertex Color (1,367,745 vertices across all track.grf MSCAL 0x4E/MSCNT world geometry, paint.mod, envsky, sci_wall): 0x80 = 1.0× neutral brightness, 248 = 1.9375× highlight), ADC = bit 15. Decoded with fix_winding = false and drawn with no backface culling! |
qword 3 + 3i |
V2-16 (offset mode) |
Texture UV: |
qword 150.. |
V4-8 offset (STROW = (0, 0, 32768.0f, 32768.0f)) or V1-8
|
Dual-Bone Skin Word (read in reverse vertex order at TOP + 149 + n - k): bone_a, bone_b (VU1 qword bases), weights |
qword 198 / 199 |
V4-32 |
q198 = (u_offset, v_offset, k_lod_delta, flags); q199 = (pos_x_off, pos_y_off, pos_z_off, w). |
Every 3D and effect primitive drawn by Plume is captured at its decompiled EE entry point:
| Native Kind | Decompiled EE Entry Points (src/*.cpp) |
VU1 Program Replaced | What Plume Draws |
|---|---|---|---|
1. queue (Cars, Props, Characters, Cockpit) |
0x34BDA8 (ModelSubmitVu1Packets), 0x34B140, 0x34C9C0, 0x34C930, 0x34C860, 0x34AF98 (RenderQueueFlush in src/render_queue.cpp) |
0x02A8, 0x02E0 (MSCAL 0x5C), 0x0318 (MSCAL 0x63), 0x24B0
|
Static and posed 3D models sorted by layer/texture bucket with exact camera projection screen_matrix (1.3e-6 max error vs. VU1 vf4..vf7). |
2. world (Track Scene & Sky Dome) |
0x214B68 (WorldFrameRender), 0x3582B8 (MlistVisibilityCalc), 0x358BD0 (WorldRenderPass 0..4), 0x35DEE0, 0x35CBB8, 0x223858 (SkyDraw), 0x223800 (SkyDestroy) in src/native_world.cpp
|
0x0270 (MSCAL 0x4E), 0x0618, 0x0920, 0x0350 (MSCAL 0x6A sun-facing quads) |
All visible track leaves per pass (mlist scratchpad visibility bytes & 0x7F == req), 32-part sky dome with cone culling, and CPU-expanded camera-facing foliage/billboard quads (0xAC..0xAF sun quad corners). |
3. water (Woodly Water Body) |
0x326168 (WaterDrawIfPresent), 0x325728 (WaterDraw), 0x325E40 (WaterSimulate) in src/native_world.cpp
|
0x0270 via immediate API |
Animated wave surface (*(0x3DC134)) on Woodly (AFTON.TRK) with car splash simulation ( |
4. shadow (Extruded 3D Shadow Volumes) |
0x34C7D0 (ShadowBegin), 0x34C798 (ShadowEnd), 0x34C208 (ShadowSubmit), 0x34C4B0 (ShadowSubmitMasked), 0x35D170 (ShadowEmitBatchPass), 0x35D298 (ShadowEmitBatch) in src/native_shadows_flares.cpp
|
0x0020 (MSCAL 4, vu1_0x3BE4C0) |
Model-space vertex extrusion along light vector vf1 = -M^T * L up to extrudeLen (0x4D7D18), rendered into a full-resolution host shadow buffer (pass 1 additive, pass 0 subtractive) and composited at intensity / 128.0. |
5. flare (Sun Glare & Light Flares) |
0x304D50 (FlareRender), 0x20F2D8 (ViewportRenderFinish) in src/native_shadows_flares.cpp
|
0x0270 (0x303CB8 2D quads) |
Sun glare (0x3DBB40) and point-light lens flares (0x3DBB48, up to 32 entries/bucket at 0x3D94F4), with the PS2 single-viewport restriction lifted in 2P/4P (SplitScreenParity=1). |
6. particle (Smoke, Dust, Sparks, Dirt) |
0x363B98 (ParticleBegin), 0x3639D0 (ParticleAdd), 0x363B68 (ParticleEnd), 0x363FF8 (ParticlePacketReserve) in src/native_effects_imm.cpp
|
0x08E0 (vu1_029b295eacf3f666.bin) |
Camera-aligned rotated quads using the 79-entry (cos, sin) table (0x4D87B4) and vertical sky-gradient shading rgb * (1 - 0.5*scale*(1 - up_dot)). |
7. sprite (Simple & Atlas Effect Sprites) |
0x363F48/0x363DE8/0x363F18/0x364548 (Simple) & 0x363D78/0x363C18/0x363D48/0x3642B8 (Atlas) in src/native_effects_imm.cpp
|
0x01B8 (Simple), 0x05E0 (Atlas) |
Explosion fireballs (chicken detonations), exhaust flames, and effect cards with per-sprite UV atlas rectangles. |
8. immediate (General & Sphere-Tested Immediate Prims) |
0x35DF10 (ImmediateBegin), 0x361468, 0x361708 (ImmediateVertex), 0x361BC8 (ImmediateEnd), 0x364D18, 0x34EE70/0x361ED8/0x361C30, 0x35CAA0 in src/native_effects_imm.cpp
|
0x0270 (MSCAL 0x4E) |
Dynamic triangle strips and indexed triangles (0x35CAA0), plus sphere-cull-tested static immediate VIF refs (0x361ED8). |
9. cockpit (Interior Overlay Quad) |
0x219C48 → 0x34DB70 → 0x35CAA0 (ra == 0x21A064) in src/native_effects_imm.cpp
|
0x0270 |
Non-queue cockpit stack quad when 0x2114A8() != -1 (while main cockpit interior car+0x228 and posed gauges draw via queue). |
| Stage | Scope & Technical Milestone | Verification Status & Evidence (docs/NATIVE_RENDERER_SUCCESS.md) |
|---|---|---|
| R0 |
Plume Device Ownership: runtime/render/plume_device.cpp creates and owns the single Vulkan 1.3 instance/device; legacy GS borrows handles for zero-copy composition. |
DONE: Offline GS replay MD5s (1ae45b16... at 1x, 8a86f217... at 6x) unchanged. |
| R1 |
Queued 3D Objects (0x34AF98): Cars, props, and characters drawn by Plume from decompiled src/render_queue.cpp. |
DONE: 798,780/798,780 race records drawn (P1 = 100%); max projection error 1.3e-6 vs. VU1 vf4..vf7; GPU frame time dropped from 12.8 ms to 9.8 ms at 6x. |
| R2 |
Track World, Sky & Water (0x214B68): 10 functions in src/native_world.cpp (WorldFrameRender, MlistVisibilityCalc, WorldRenderPass, SkyDraw, WaterDraw, WaterSimulate). |
DONE: EOD_DIFF 0 mismatches across 18,432+ checked calls; 100% P1 leaf & water equality across Woodly 1P, Career Free Roam, Dundas 1P/2P, and Anoka Battle; Woodly water verified (1,232/1,232). |
| R3 |
Skinned Characters & 157-Bone Car Deformation: src/bone_pose.cpp (0x34C9F8, 0x35DBD8, 0x35A810, 0x35DD28, 0x34CA18), src/car_damage.cpp (0x17B918, 0x18CA98, 0x18AFE0), src/debris_pool.cpp (0x1B3068, 0x1E1E88, 0x1E29C0, 0x1B3180, 0x1B3190). |
DONE: P2 bit-identical bone palette words (241,920/241,920) and VU1 dent words (581,652/581,652); 99.91% of 4.67M non-clip posed vertices within <= 1/16 px of GS (p99 = 0.0625 px); wheel/panel debris pools expanded (105 live wheels, 34 live panels). |
| R4 |
Shadows, Flares, Particles, Sprites & Immediate Geometry: 28 live-reachable functions in src/native_shadows_flares.cpp and src/native_effects_imm.cpp; VU1 0x25F0 -> 0x2630 traced to 0x3620A8 GIFtag template setup. |
DONE: >= 1,000 EOD_DIFF checks on every live function (0 mismatches); 100% P1 equality across all 9 native kinds and all 10 camera views; PS2 320×512 shadow RT cap removed; EOD_NATIVE_ONLY=1 dropped GS primitives reduced by 90.8% (133,823 → 12,337, leaving only 2D/HUD for R7). |
| R5 |
Classic Visual Parity (P3) & Unthrottled LOD (P10): tools/p3_compare.py (MAE, p99, SSIM, fog/sky error vs. software GS replay), src/native_fog.cpp (0x33ECB8, 0x3653F8, 0x365428, 0x365540), src/native_texstate.cpp (0x3652A8, 0x3654E0, per-run q198.z K kicks, GS log2approx(Q) mipmap sampler, 2-pass AFAIL FB_ONLY/ZB_ONLY). |
Phase A1 & A2 Landed: Proved retail PS2/Xbox never enable PRIM.FGE (0 fogged pixels in retail replays); exact EE state match across 1.86M world draws; Gilroy Night SSIM improved from 0.9338 to 0.9561 (MAE 2.44, sky MAE 1.79). Shadow composite & near-plane depth clamp polish in progress for final SSIM >= 0.98. |
| R6 |
Modern PBR & GPU VFX: Connect all 2,728 material_table.json records (resolving 318 low-confidence textures) and replace flat 2004 billboard quads in Modern mode with depth-faded volumetric GPU fire/smoke/sparks & dynamic point-light flashes. |
Specified & In Progress: material_table.json tagged; Modern PBR shaders & GPU particle VFX pipeline designed. |
| R7 |
Native 2D / HUD & Emulator Removal (S4 = 0): Move PATH2/PATH3 GS transfers (MenuRun, HudDrawLeftRaceRows, HudDrawRightSpeedRows, GTEX v4 fonts, CANV v1 canvases, .PSS movies) to Plume and cut VU1/GS emulation from the frame loop (eliminating all 58 synchronous VRAM readbacks/frame). |
Planned (Next after R5/R6): Targets the final ~35 2D GS primitives/frame remaining after R4. |
| R8 |
macOS Metal, Speed Sign-Off (S1–S3), Photo Mode (P11) & Creation Kit (P13): plume_metal.cpp, 8K Photo Mode (< 2 s), fullscreen Tracy + EOD_GPU_PROF sign-off at 60+ FPS. |
Planned. |
| R9 |
Creation Kit & World Editor (R9a–R9e): Standalone 3D World Editor (tools/world_editor/) with 37 Cars & Wrecks, Ghost Place, Scatter Brush, SOBL barrier flattening, ILIN road editor, 4K HOSTTEX swap, and embedded PIE. |
Phase 1 & Priority P1–P10 Implemented: Verified by tools/world_editor/test_editor.py. |
Nothing counts as complete without measured numerical proof against these gates across the 11-Scene Verification Suite (1. Afton Jump Race 1P · 2. Afton/Dennison/Dundas 2P & 4P Split-Screen · 3. Career Free Roam Day · 4. Career Free Roam Night / Anoka Night · 5. Car Dealer · 6. Garage / Paint / Upgrades · 7. Front-End Menus · 8. Loading Screen · 9. Memory Card Screen · 10. .PSS Movie · 11. Heavy Demolition Crash Replay):
-
P1 (Object Parity): Per frame, objects submitted by the game (
queue,world,water,shadow,flare,particle,sprite,immediate,cockpit) == objects drawn by Plume on 100% of frames. -
P2 (Animation & Damage Parity): Bone palettes (
0x34C9F8) and 157-bone car dent offsets (Bone.mvl/0x35DD28) are bit-identical to EE outputs; posed vertices within<= 1/16 px(0.0625 px) of GS reference at 1x. -
P3 (Classic Parity): Plume PS2 Classic look at 1x vs. offline software GS replay of the same frame (
tools/p3_compare.py): per-channelMAE <= 1/255,p99 <= 8/255,SSIM >= 0.98, fog and sky pixels within<= 2/255. -
P4 (Clean Modern Look): Filament BRDF/IBL math in native HLSL with cascaded sun shadows, sky IBL, SSR, clear-coat paint, chrome, glass, and water refraction from
material_table.json. No unrequested vignette, color grade, or haze; fog/sky within<= 4/255of the game's setters. -
P5 (Instant Toggle):
F9switches Classic ↔ Modern in 1 frame (<= 33 ms) with 0 MB GPU memory growth over 100 toggles. -
P6 (Reference Integrity): Offline GS replay of recorded race dumps reproduces reference VRAM MD5s (
f30d64c0.../1ae45b16...at 1x,8a86f217...at 6x). - P7 (Determinism): Solo replay and 2-instance netplay produce identical lap times, physics, and results with 0 desyncs.
-
P8 (Split-Screen Parity): 2P/4P views match 1P object lists, world passes 0..4, draw distance, LOD, sun glare/flares (
0x304D50), and Woodly (AFTON.TRK) water (0x325728). - P9 (Share-Worthy Remaster): 6x and 8x Modern captures show dynamic sun shadows, reflections, and sky IBL with zero shimmer or pop-in.
-
P10 (Unthrottled Maximum Detail):
Detail=maximumforces highest car (Low1.mod) and world LOD at every visible distance across 1P and split-screen. -
P11 (8K Photo Mode): Pause, free camera (orbit, fly, roll, FOV, DOF, no HUD), and export
7680×4320PNG in< 2 s. -
P12 (Video-Ready Pacing): 5-minute Tracy race capture with video recording active:
0missed vblanks,p99 <= 16.7 ms. -
P13 (Modded Art Parity): Creation Kit 4K/8K car and track textures (
.eodhtx) render in both Classic and Modern looks with no seams or fallbacks.
-
S1 (Target Floor — i5-7600K + Radeon Pro 580):
RenderScale 6, max LOD, Modern look, fullscreen vsync: locked 60 FPS,0missed vblanks,p99 CPU <= 12 ms,p99 GPU <= 14 msover 5-min race + 2-min free roam. -
S2 (Minimum Floor — Intel UHD 620-class Vulkan iGPU):
RenderScale 1–2, PS2 Classic look: locked 60 FPS,0missed vblanks. -
S3 (Modern Hardware / Apple Silicon M2 Pro):
RenderScale 6–8+, max LOD: 60–240+ FPS with zero synchronous VRAM readback stalls. -
S4 (Zero Emulated Graphics in Frame Path):
0VU1 microprogram runs,0emulated GS primitives rasterized, and0synchronous VRAM readbacks per frame across the entire 11-scene suite.
-
D1: Readable C++ replaces every function in the subsystem (
config/hle.txtwrap/diff_run). -
D2:
EOD_DIFFproves 0 mismatches over>= 1,000checked calls on every code path reached by the scene suite. - D3: P6 and P7 hold with the C++ replacement active.
-
D4:
ninja -C build eodboots through menus, race, and career, exiting cleanly with 0 heap errors (EOD_HEAP_CHECK=1). -
D5: Documented in
docs/<SUBSYSTEM>.mdwith guest addresses, struct layouts, call graphs, and open edges.
Test Drive: Eve of Destruction (SLUS_209.10) Static Recompilation & Creation Kit · Target ELF SHA-256: 4f60053dc141365f5ae50737622f8408be30ced513b4c109427c926461f2e2ae · Repository · Tutorials · Architecture · Plume Renderer · File Formats · Symbols · World Editor
- All Tutorials (1–7 Overview)
- 1. Zero-Friction ISO Setup & Controls
- 2. Your First Track Mod & PIE
- 3. Deleting Fences & SOBL Barriers
- 4. Cars, Wrecks & Scatter Brush
- 5. AI Pathfinding (
ILIN) & Custom Modes - 6. 4K Textures, Skyboxes & NASCAR Cars
- 7. Packaging & Sharing
.eodmodMods
-
Architecture Overview
- EE, VU1, GS, IOP, Memory Map & PS2 Limits
-
Native Plume Renderer
- Stages R0–R8, VIF Decoder, Classic/Modern & Gates
-
File Formats Encyclopedia
- All 24 FourCC Formats, 72 Archives & 7,329 Assets
-
Decompiled Subsystems & Symbols
- Addresses, HLE Hooks,
EOD_DIFF, Physics & AI
- Addresses, HLE Hooks,
-
World Editor & Creation Kit
- ADRs 01–08, JTBD Matrix, Fishbones & Toolchain