Home
Three ways to enter¶
| Entry | What you will find |
|---|---|
| xPRIMEray Runtime | Curved-ray observatory and diagnostics |
| Portable Observatory | Public ontology: Scene → Transport Lens → Plate → Evidence |
| Project Glowing Heart | Protocol and artifact trail |
| Observation Atlas | Observer field guide, not a ranking |
Observatory Atlas is the chapter tour. Observation Atlas is the observer map.
What xPRIMEray Is¶
A null-geodesic integrator where curved rays are first-class primitives. Transport is solved, not faked with lens shaders or post-process distortion. GRIN and Gordon-metric fields define an effective spacetime; the renderer solves the correct eikonal transport through it.
A visual diagnostics platform. The engine finds hits, seams, high-curvature regions, unstable domains, and boundary-layer events from scene data — then reveals their structure through an expanding library of overlay modes: film overlays, heatmaps, contact sheets, domain maps, curvature contours, and transport ownership graphs.
A structured diagnostic infrastructure connecting renderer behavior to theoretical frameworks. Six-layer Cathedral Probe overlays, scheduler resonance DOE, domain telemetry, oracle reference comparison, and transport island microscopy separate independent failure layers that naive per-pixel analysis conflates.
Current Renderer State¶
| Category | Count | Examples |
|---|---|---|
| Ready to ship | 20+ systems | GRIN fields, boundary layers, hit detection, overlays, 46 fixture scenes, observatory scripts |
| In progress | 4 systems | WormholePrototypeRig, TestBench recipes, atomic orbital observatory fixture |
| Research / diagnostic only | 5 systems | ReferenceTransportOracle, SceneTransportMemory, MetricHeuristicIntegrator (4 open TODOs) |
| Active overlays | 21 modes | FilmOverlay2D, step budget heatmap, domain ownership map, curvature contours, observatory contact sheets |
| Proposed overlays | 13 modes | Celestial Boundary Overlay, Bulk-to-Boundary Dual View, Curvature Domain Map, S-Matrix Event Ledger |
→ Full Feature Index · Release Readiness Audit · Overlay Master List
Observatory & Audit Navigator¶
| Document | Purpose |
|---|---|
| Overview / Transport Observatory | How all systems fit together; gallery; recommended next actions |
| Feature Index | Master feature map with quick-reference tables |
| Release Readiness Audit | Ship-readiness classification; cleanup list; packaging exclusions |
| Optical Transport Feature Map | Transport system completeness; engine feature candidates; gap analysis |
| Overlay Master List | All 34 overlay modes — existing, partial, and proposed |
| Inspiration Cards | Thinkers and concepts linked to engine features (Pasterski, Noether, MTW, Maxwell, Feynman) |
Project Glowing Heart¶
Project Glowing Heart is the active Core extraction and bridge track for xPRIMEray. The current public-safe state is metadata-first: Core emits standalone preview artifacts, the Godot side has static fixture exports, and the bridge has shared fixture, schema, observer, and reconciliation packets. It does not claim parity, runtime equivalence, closure equivalence, or pixel comparison readiness.
| Latest bridge artifact | Status |
|---|---|
| Shared fixture schema and instance | Preview draft / candidate |
| Shared observer contract | Preview contract |
| Core and Godot observer instances | Metadata generated |
| Observer reconciliation | Pixel comparison not ready |
| Public demo posture | Safe with limits; no parity or validation claims |
→ Project Glowing Heart v1.8.1 Observer Reconciliation · Shared Observer Contract · Public Demo Readiness
What This Is¶
- A null-geodesic integrator — curved rays are first-class primitives. Transport is solved, not faked with lens shaders or post-process distortion.
- A GRIN and Gordon-metric renderer — refractive-index fields define an effective spacetime; the renderer solves the correct eikonal transport through it.
- A hermetic validation harness — every render run is classified: source hit, background hit, portal, absorbed, escaped.
escaped_no_hit = 0is the contract. - A multi-scene wormhole system — two causally isolated overspaces joined at a topological throat, each rendered with full curved-ray physics.
- A transport diagnostics platform — six-layer Cathedral Probe overlays, scheduler resonance DOE, domain telemetry, oracle reference comparison, and transport island microscopy.
Current Milestone: Curved-Field Validation Ladder¶
Four-panel diagnostic layout: rendered frame with curved transport active · hit-normal vector overlay · camera cross-section minimap showing field geometry in the vertical camera plane · transport/field overlay with ownership seams and oracle comparison context. Oracle replay failures: 0. All 64 sampled pixels sealed at step 0.02.
The curved-field validation ladder is the first end-to-end validation packet for curved ray transport in xPRIMEray. It runs the complete diagnostic stack — ReferenceTransportOracle step-size convergence, six-layer Cathedral Probe overlay, camera cross-section minimap, and curved-vs-control storyboard — against a GRIN field scene with curved transport active. The result confirms that the oracle, diagnostic infrastructure, and transport ownership machinery operate correctly under non-trivial geodesic curvature.
| Measurement | Value |
|---|---|
| Oracle step | 0.0015625 (8× finer than production floor) |
| Sampled pixels | 64 |
| Oracle replay failures | 0 |
| Sealed at step 0.02 | 64 / 64 |
| Mean decision-risk delta (0.00625 vs 0.003125) | 0.000090 |
| Comparability status | warning — control scene differs by camera pose key |
All 64 sampled pixels achieve Stable classification at the coarsest tested step, with near-zero risk delta between the two finest steps. No transport topology anomalies were identified in this scene. The comparability warning records that the baseline used the domain_resolver_stress scene while the curved run used curved_minimal_backdrop; a matched-pose control was not available at run time — the storyboard is evidence that the ladder infrastructure wires correctly under this constraint, not a head-to-head geometry comparison.
Core Capabilities¶
Transport¶
| Capability | Status |
|---|---|
| RK4 null-geodesic integration (eikonal ODE) | ✅ Production |
GRIN field sources (FieldSource3D, spatially varying n(x)) |
✅ Production |
| Gordon effective metric framing | ✅ Production |
| Tiered metric hierarchy (Tier 0 GRIN → Tier 3 exotic) | ✅ Production |
| Morris-Thorne wormhole topology (causal observer ladder) | ✅ Production |
| Dual-scene overspace composition | ✅ Production |
| Derivative-aware adaptive step control | ✅ Production |
In-Game Overlays (live, no render pass required)¶
| Overlay | Toggle |
|---|---|
| Dual-reality straight-reference inset | EnableDualRealityResearchMode |
| Curvature heatmap (5 metric modes) | DualRealityOverlayMode |
| Semantic wireframe glyphs (portals, fields, BLVs) | WireframeReferenceOverlay |
| Collision radar (projected AABB/sphere bounds) | DualRealityCollisionRadarOverlayEnabled |
| Hit normal vectors + film gradient normals | FilmOverlay2D |
| Debug ray polylines | DebugOverlayOwnedByFilm |
| Top-down / oblique research overlay | WormholeResearchOverlay |
Experimental Feature Flags¶
EnableDomainTelemetry— exports per-pixel renderer diagnostics:domain_id,domain_confidence,boundary_confidence,selection_flip,normal_discontinuity.EnableDomainAwareFirstHitResolver— experimental domain-aware first-hit heuristic. Off by default. RequiresEnableDomainTelemetry.EnableTileMetricsScaffold— tile-metrics subsystem: reorder simulation, execution, and persistent-priors scheduling.EnableObjectSeededTileScheduler— tile ordering seeded from projected scene object centroids.
Validation and Diagnostics¶
The hermetic fixture rule enforces complete pixel classification on every run. Fixture 011 (six-checkpoint wormhole observer ladder) is the canonical validation sequence.
The bridge (post-throat backstep) is the confirmed transport anomaly: 366 segments/crossing vs. 50–153 at all other checkpoints (z-score 4.40). Three independent anomaly detectors agree. Domain-aware analysis separates three transport regimes (near-side, bridge anomaly, far-side) via PCA and k-means clustering (k=3, ARI=0.595).
The Cathedral Probe framework — six passive diagnostic layers composited over a single render — separates scheduler-induced global banding from localized topology failure. The key finding: transport instability is topological and localized, not globally smoothable. Scheduler decorrelation (tile traversal) eliminates horizontal banding; it does not eliminate local geometry seam instability. Those are two independent failure layers.
The ReferenceTransportOracle measures transport stability against a fine-step reference (0.0015625) without feeding results back into the renderer — a guardrail enforced in code, not by convention. Oracle microscopy surfaces transport topology that phase-space diagnostics miss.
Current Research Frontier¶
Cathedral Probe — Scheduler Resonance and Dual-Layer Transport Failure¶
Six-layer Cathedral Probe diagnostic contact sheet — domain resolver stress scene, step_length=0.015, row traversal. From left: beauty render, geometric wireframe, transport ownership map, risk probe markers, spacetime transport diagram, transport continuity vectors.
Scheduler stride sweep (56-cell DOE). Stride 1: ~31% band coverage across all step lengths. Stride 4: < 0.7%. Traversal cadence — not physics precision — is the primary amplifier of row-global banding.
Traversal mode comparison at step_length=0.015. Scheduler decorrelation reduces banding across modes. Local corner instability persists unchanged — two independent failure layers confirmed.
→ Cathedral Probe architecture paper
Transport Island Microscopy — Oracle-Guided Precision Closure¶
Following scheduler decorrelation, a ReferenceTransportOracle ROI sweep identified a compact unresolved transport island (x=36..44, y=31..37). Dense island microscopy (289 samples) confirmed precision closure: all pixels seal at step 0.00625, with zero oracle replay failures. The island was not independently flagged by the Cathedral Probe continuity vectors — demonstrating that oracle microscopy surfaces transport topology that phase-space diagnostics miss.
| Island measurement | Value |
|---|---|
| ROI sweep unresolved pixels | 54 / 320 comparisons (16.9%) |
| Island bbox | x=36..44, y=31..37 |
| Dense pass samples | 289 |
| Sealed at step 0.00625 | true (289/289) |
| Mean decision-risk delta (0.00625 vs 0.003125) | 0.000189 |
| Oracle replay failures | 0 |
→ Transport Island Microscopy paper
Architecture¶
xPRIMEray uses a tiered transport hierarchy: Tier 0 GRIN ray integration → Tier 1 metric parameter extraction → Tier 2 Gordon Metric bridge → Tier 3 exotic metrics. The multi-scene wormhole system joins two causally isolated overspaces at the wormhole throat. The hermetic fixture rule (escaped_no_hit = 0) enforces complete pixel classification.
→ Architecture overview — pipeline, stored-hit system, domain emergence, Gordon metric math → Architecture subsystems — subsystem contracts and data-flow diagrams
Read Next¶
Research papers¶
| Paper | Description |
|---|---|
| Cathedral Probe architecture | Scheduler resonance DOE, dual-layer failure model, six-layer overlay methodology |
| Transport Island Microscopy | Oracle-guided precision closure, island identification, convergence ladders |
| Paper 001 — Causal Observer Ladders | Six-checkpoint wormhole fixture, transport anomaly z-scores, regime clustering |
| Paper 004 — Hermetic Throat Validation | Coverage contract, bridge anomaly evidence, throat-depth maps |
Diagnostics and analysis¶
| Document | Description |
|---|---|
| Phase coherence field | Per-pixel coherence scores correlating banding with domain-boundary transitions |
| Domain ownership analysis | Transport regime decomposition, spectral ruling-out of oscillatory model |
| Feature maturity matrix | What is live in-game vs. harness-only vs. post-process only |
| Visual milestone inventory | Chronological archaeology of all rendered output artifacts |
Reference¶
| Document | Description |
|---|---|
| Glossary | Null geodesic · GRIN · Gordon metric · domain boundary · phase coherence |
| Hermetic fixture rule | What 100% pixel classification means and why it matters |
| Spec index | All active specifications |
Repository¶
github.com/AetherTopologist/GD_xPRIMEray
License: MIT — academic, commercial, and creative use welcome. Citation templates: papers/shared_bibliography.bib