# new3d-v0.0.29 Refactor Report

- Generated: 2026-02-19 09:07:04 CET
- Baseline reviewed: `vibe.cybernoid.xyz/webgpu/new3d-v0_0_28.html`
- New version: `vibe.cybernoid.xyz/webgpu/new3d-v0_0_29.html`

## Baseline (v0.0.28) Analysis

`new3d-v0_0_28.html` is a high-complexity single-file Three.js cinematic scene with:

- Procedural world generation and many animated systems (terrain, galaxies, zodiac, monoliths, searchlights, torus knots, camera rigs, post FX).
- Strong animation architecture already in place (`animate()`), including dynamic DPR balancing, tape burst events, FOV events, camera cut logic, and glitch modulation.
- Large amount of inline hardcoded scene/effect data spread across creation functions (object definitions, paths, palettes, profile values, celestial definitions, etc.).
- No transport/player controls for timeline navigation.

## New Version (v0.0.29) Summary

Created a cleaner data-driven successor while preserving the animation logic and motion behavior:

- Added a central JSON data block (`<script type="application/json" id="sceneData">`) for scene/object/effect definitions.
- Added reusable template/data helpers (`mapTemplate`, device-aware value resolver, vector conversion).
- Kept animation equations and update flow intact, while routing object/effect definitions through JSON-driven construction.
- Added basic player transport UI: `Stop`, `Pause/Play`, `-10s`, `+10s`.

## Detailed Change List

### 1. Data-Driven Refactor

Moved key declarative data into JSON blocks and consumed it in runtime builders:

- Global metadata and opening credits timing/lines.
- Mobile/desktop profile presets.
- Scene camera/fog/background and post-FX size/intensity presets.
- Mystic galaxy cluster definitions.
- Mystic zodiac sign data + belt settings.
- Legacy celestial zodiac definitions.
- Planet, moon, and sun definitions.
- Moon/sun directional light configuration.
- Main light bank definitions and color palettes.
- Monument hologram material presets and major count parameters.
- Camera path point sets.
- Camera rig interval ranges.
- Playback defaults.

### 2. Templating / Construction Helpers

Introduced reusable helpers:

- `readJsonData(id)` for loading JSON config blocks.
- `vec3FromArray(arr)` for vector templating.
- `valueForDevice(mapOrValue)` for mobile/desktop data selection.
- `mapTemplate(items, mapper)` for efficient data-to-object construction loops.

Applied helpers in multiple systems (galaxies, celestial bodies, lights, paths, etc.).

### 3. Playback UI + Transport

Added fixed control panel (`#playerUi`) with:

- `Stop`
- `Pause` / `Play` toggle
- `-10s`
- `+10s`
- Live playback mode/time readout

### 4. Timeline Control Implementation

- Split simulation loop into `stepSimulation(dt, shouldRender)` and wrapper `animate()`.
- Added deterministic RNG (`mulberry32`) with persisted seed in URL params.
- Implemented seek workflow using URL parameters (`seed`, `seek`, `autopause`) and startup warmup simulation to exact target time.
- Added warmup path for jump/seek operations and reliable backward/forward transport behavior.

### 5. Animation Preservation

- Existing animation formulas and per-system update math were retained.
- Motion systems, camera behavior, glitch modulation, and post-FX dynamics were not redesigned; only data sourcing and loop orchestration were cleaned up.

## Notes

- The new file is intentionally additive and non-destructive: baseline `v0.0.28` remains unchanged.
- The new version is prepared for easier future tuning by editing JSON data blocks instead of scattered inline constants.