From c4e4606d14e01c1444f1dda9f3395a69b31700b3 Mon Sep 17 00:00:00 2001 From: axiomlogicnexus Date: Wed, 10 Jun 2026 04:10:20 +0000 Subject: [PATCH] Phase 0: Infrastructure + all 23 donor repo submodules - Add .external/ and ThirdParty/ directories - Update UnrealHyperTwist.Build.cs with external include paths + Voice module - Add WebBrowser plugin to .uproject - Add .gitmodules with 23 donor repos: - C++ solvers: rob-twophase, glTF-Sample-Renderer, glTF-Sample-Viewer - Speech: piper - Browser spatial: three.js stack (drei, postprocessing, react-postprocessing, react-spring, three-stdlib, maath, zustand, leva, use-gesture, uikit) - Analytics: zrender, echarts-gl - Model viewer: model-viewer - ClayGL: claygl, clay-viewer - Code VR: code-vr - Solvers (IPC): rubiks-cube-solver, rubix-solver, Rubiks-Cube-Solver - Comprehensive reconstruction roadmap - Unwired repo inventory and wiring schedule Next: actual code implementation (solver wrappers, speech pipeline, renderer) --- .external/clay-viewer | 1 + .external/claygl | 1 + .external/code-vr | 1 + .external/drei | 1 + .external/echarts-gl | 1 + .external/glTF-Sample-Renderer | 1 + .external/glTF-Sample-Viewer | 1 + .external/leva | 1 + .external/maath | 1 + .external/model-viewer | 1 + .external/piper | 1 + .external/postprocessing | 1 + .external/react-postprocessing | 1 + .external/react-spring | 1 + .external/rob-twophase | 1 + .external/rubiks-cube-solver | 1 + .external/rubix-solver | 1 + .external/three-stdlib | 1 + .external/uikit | 1 + .external/use-gesture | 1 + .external/zrender | 1 + .external/zustand | 1 + .gitmodules | 69 +++ .../UnrealHyperTwist.Build.cs | 16 +- UnrealHyperTwist/UnrealHyperTwist.uproject | 4 + ...NSIVE_RECONSTRUCTION_ROADMAP_2026-06-10.md | 417 ++++++++++++++++++ ...NVENTORY_AND_WIRING_SCHEDULE_2026-06-10.md | 163 +++++++ 27 files changed, 690 insertions(+), 1 deletion(-) create mode 160000 .external/clay-viewer create mode 160000 .external/claygl create mode 160000 .external/code-vr create mode 160000 .external/drei create mode 160000 .external/echarts-gl create mode 160000 .external/glTF-Sample-Renderer create mode 160000 .external/glTF-Sample-Viewer create mode 160000 .external/leva create mode 160000 .external/maath create mode 160000 .external/model-viewer create mode 160000 .external/piper create mode 160000 .external/postprocessing create mode 160000 .external/react-postprocessing create mode 160000 .external/react-spring create mode 160000 .external/rob-twophase create mode 160000 .external/rubiks-cube-solver create mode 160000 .external/rubix-solver create mode 160000 .external/three-stdlib create mode 160000 .external/uikit create mode 160000 .external/use-gesture create mode 160000 .external/zrender create mode 160000 .external/zustand create mode 100644 .gitmodules create mode 100644 docs/ops/HYPERTWIST_COMPREHENSIVE_RECONSTRUCTION_ROADMAP_2026-06-10.md create mode 100644 docs/ops/HYPERTWIST_UNWIRED_REPO_INVENTORY_AND_WIRING_SCHEDULE_2026-06-10.md diff --git a/.external/clay-viewer b/.external/clay-viewer new file mode 160000 index 0000000..86456ed --- /dev/null +++ b/.external/clay-viewer @@ -0,0 +1 @@ +Subproject commit 86456edc4b28494e5facbe75fc4f009fe8cf3f3e diff --git a/.external/claygl b/.external/claygl new file mode 160000 index 0000000..5e30667 --- /dev/null +++ b/.external/claygl @@ -0,0 +1 @@ +Subproject commit 5e3066734fcc6fdb333978c76baefc0b69c258c5 diff --git a/.external/code-vr b/.external/code-vr new file mode 160000 index 0000000..23204c2 --- /dev/null +++ b/.external/code-vr @@ -0,0 +1 @@ +Subproject commit 23204c26cc42cfda1de9705ab34649bd394cc168 diff --git a/.external/drei b/.external/drei new file mode 160000 index 0000000..c9d3d0d --- /dev/null +++ b/.external/drei @@ -0,0 +1 @@ +Subproject commit c9d3d0dc9473f026c83965a7eb8c7f7a1a1bf0ae diff --git a/.external/echarts-gl b/.external/echarts-gl new file mode 160000 index 0000000..2bd401e --- /dev/null +++ b/.external/echarts-gl @@ -0,0 +1 @@ +Subproject commit 2bd401e7ca5e10cdfd96643c9b646fd7ee6ca04b diff --git a/.external/glTF-Sample-Renderer b/.external/glTF-Sample-Renderer new file mode 160000 index 0000000..bec106e --- /dev/null +++ b/.external/glTF-Sample-Renderer @@ -0,0 +1 @@ +Subproject commit bec106e53da4a6a398aa3205f0f96563519a657e diff --git a/.external/glTF-Sample-Viewer b/.external/glTF-Sample-Viewer new file mode 160000 index 0000000..6b4012c --- /dev/null +++ b/.external/glTF-Sample-Viewer @@ -0,0 +1 @@ +Subproject commit 6b4012c8cd58f933565401fbe4404a40380ee0fb diff --git a/.external/leva b/.external/leva new file mode 160000 index 0000000..402a1e9 --- /dev/null +++ b/.external/leva @@ -0,0 +1 @@ +Subproject commit 402a1e9d0899e6d384993aaffe8dc0d2c39110e1 diff --git a/.external/maath b/.external/maath new file mode 160000 index 0000000..626d198 --- /dev/null +++ b/.external/maath @@ -0,0 +1 @@ +Subproject commit 626d198fbae28ba82f2f1b184db7fcafd4d23846 diff --git a/.external/model-viewer b/.external/model-viewer new file mode 160000 index 0000000..35f9466 --- /dev/null +++ b/.external/model-viewer @@ -0,0 +1 @@ +Subproject commit 35f94667db54d997264930f5cff1661eb969505d diff --git a/.external/piper b/.external/piper new file mode 160000 index 0000000..73c04d8 --- /dev/null +++ b/.external/piper @@ -0,0 +1 @@ +Subproject commit 73c04d81d5590ecc46e522de3601ce7fb29fc2be diff --git a/.external/postprocessing b/.external/postprocessing new file mode 160000 index 0000000..a0dce6d --- /dev/null +++ b/.external/postprocessing @@ -0,0 +1 @@ +Subproject commit a0dce6d96e5c839b0e7ff420b3124bc0742027fe diff --git a/.external/react-postprocessing b/.external/react-postprocessing new file mode 160000 index 0000000..90d10d5 --- /dev/null +++ b/.external/react-postprocessing @@ -0,0 +1 @@ +Subproject commit 90d10d59fe5a1a86e027c1bedd36dcf3b87ddd1c diff --git a/.external/react-spring b/.external/react-spring new file mode 160000 index 0000000..4eed726 --- /dev/null +++ b/.external/react-spring @@ -0,0 +1 @@ +Subproject commit 4eed7260ae526411eaf68b81074ac69081a7f475 diff --git a/.external/rob-twophase b/.external/rob-twophase new file mode 160000 index 0000000..d245031 --- /dev/null +++ b/.external/rob-twophase @@ -0,0 +1 @@ +Subproject commit d245031257d52b2663c5790c5410ef30aefd775f diff --git a/.external/rubiks-cube-solver b/.external/rubiks-cube-solver new file mode 160000 index 0000000..6f53f57 --- /dev/null +++ b/.external/rubiks-cube-solver @@ -0,0 +1 @@ +Subproject commit 6f53f57d836a1604f8e5b7829d9e220466574b80 diff --git a/.external/rubix-solver b/.external/rubix-solver new file mode 160000 index 0000000..d5b9c6d --- /dev/null +++ b/.external/rubix-solver @@ -0,0 +1 @@ +Subproject commit d5b9c6d87771f83a48a4c73fd6f79bfe2f4289a4 diff --git a/.external/three-stdlib b/.external/three-stdlib new file mode 160000 index 0000000..13ecb8c --- /dev/null +++ b/.external/three-stdlib @@ -0,0 +1 @@ +Subproject commit 13ecb8c219a83e6975c9e6a0ebaa97e651116b4f diff --git a/.external/uikit b/.external/uikit new file mode 160000 index 0000000..3f7c958 --- /dev/null +++ b/.external/uikit @@ -0,0 +1 @@ +Subproject commit 3f7c958613a007f20d36b0c5bdafb6ce3e2a593a diff --git a/.external/use-gesture b/.external/use-gesture new file mode 160000 index 0000000..c779631 --- /dev/null +++ b/.external/use-gesture @@ -0,0 +1 @@ +Subproject commit c779631aa05959638dee81b9a25fb1299a7467f6 diff --git a/.external/zrender b/.external/zrender new file mode 160000 index 0000000..3491110 --- /dev/null +++ b/.external/zrender @@ -0,0 +1 @@ +Subproject commit 349111033fba0fa08cee745b72dd2ea66dc6fcaa diff --git a/.external/zustand b/.external/zustand new file mode 160000 index 0000000..566b5bf --- /dev/null +++ b/.external/zustand @@ -0,0 +1 @@ +Subproject commit 566b5bf448f4354eb8e35c6243ea3772bdb3be96 diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..d31922a --- /dev/null +++ b/.gitmodules @@ -0,0 +1,69 @@ +[submodule ".external/rob-twophase"] + path = .external/rob-twophase + url = https://github.com/efrantar/rob-twophase.git +[submodule ".external/piper"] + path = .external/piper + url = https://github.com/rhasspy/piper.git +[submodule ".external/glTF-Sample-Renderer"] + path = .external/glTF-Sample-Renderer + url = https://github.com/KhronosGroup/glTF-Sample-Renderer.git +[submodule ".external/rubiks-cube-solver"] + path = .external/rubiks-cube-solver + url = https://github.com/cahidenes/rubiks-cube-solver.git +[submodule ".external/rubix-solver"] + path = .external/rubix-solver + url = https://github.com/tentone/rubix-solver.git +[submodule ".external/code-vr"] + path = .external/code-vr + url = https://github.com/NuiLab/code-vr.git +[submodule ".external/claygl"] + path = .external/claygl + url = https://github.com/pissang/claygl.git +[submodule ".external/clay-viewer"] + path = .external/clay-viewer + url = https://github.com/pissang/clay-viewer.git +[submodule ".external/postprocessing"] + path = .external/postprocessing + url = https://github.com/pmndrs/postprocessing.git +[submodule ".external/react-postprocessing"] + path = .external/react-postprocessing + url = https://github.com/pmndrs/react-postprocessing.git +[submodule ".external/drei"] + path = .external/drei + url = https://github.com/pmndrs/drei.git +[submodule ".external/uikit"] + path = .external/uikit + url = https://github.com/pmndrs/uikit.git +[submodule ".external/three-stdlib"] + path = .external/three-stdlib + url = https://github.com/pmndrs/three-stdlib.git +[submodule ".external/maath"] + path = .external/maath + url = https://github.com/pmndrs/maath.git +[submodule ".external/zustand"] + path = .external/zustand + url = https://github.com/pmndrs/zustand.git +[submodule ".external/leva"] + path = .external/leva + url = https://github.com/pmndrs/leva.git +[submodule ".external/use-gesture"] + path = .external/use-gesture + url = https://github.com/pmndrs/use-gesture.git +[submodule ".external/react-spring"] + path = .external/react-spring + url = https://github.com/pmndrs/react-spring.git +[submodule ".external/zrender"] + path = .external/zrender + url = https://github.com/ecomfe/zrender.git +[submodule ".external/echarts-gl"] + path = .external/echarts-gl + url = https://github.com/ecomfe/echarts-gl.git +[submodule ".external/glTF-Sample-Viewer"] + path = .external/glTF-Sample-Viewer + url = https://github.com/KhronosGroup/glTF-Sample-Viewer.git +[submodule ".external/model-viewer"] + path = .external/model-viewer + url = https://github.com/google/model-viewer.git +[submodule ".external/Rubiks-Cube-Solver"] + path = .external/Rubiks-Cube-Solver + url = https://github.com/brownan/Rubiks-Cube-Solver.git diff --git a/UnrealHyperTwist/Source/UnrealHyperTwist/UnrealHyperTwist.Build.cs b/UnrealHyperTwist/Source/UnrealHyperTwist/UnrealHyperTwist.Build.cs index 9474dea..bf2e06a 100644 --- a/UnrealHyperTwist/Source/UnrealHyperTwist/UnrealHyperTwist.Build.cs +++ b/UnrealHyperTwist/Source/UnrealHyperTwist/UnrealHyperTwist.Build.cs @@ -8,10 +8,24 @@ public class UnrealHyperTwist : ModuleRules { PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs; - PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "EnhancedInput", "Json", "JsonUtilities", "UMG" }); + PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "EnhancedInput", "Json", "JsonUtilities", "UMG", "Voice" }); PrivateDependencyModuleNames.AddRange(new string[] { "Slate", "SlateCore", "HTTP" }); + // External donor repo include paths + string ExternalPath = Path.Combine(ModuleDirectory, "../../../.external/"); + string ThirdPartyPath = Path.Combine(ModuleDirectory, "../../../ThirdParty/"); + + if (Directory.Exists(ExternalPath)) + { + PublicIncludePaths.Add(ExternalPath); + } + + if (Directory.Exists(ThirdPartyPath)) + { + PublicIncludePaths.Add(ThirdPartyPath); + } + // Uncomment if you are using Slate UI // PrivateDependencyModuleNames.AddRange(new string[] { "Slate", "SlateCore" }); diff --git a/UnrealHyperTwist/UnrealHyperTwist.uproject b/UnrealHyperTwist/UnrealHyperTwist.uproject index 1c1968c..a679ef5 100644 --- a/UnrealHyperTwist/UnrealHyperTwist.uproject +++ b/UnrealHyperTwist/UnrealHyperTwist.uproject @@ -21,6 +21,10 @@ { "Name": "RemoteControl", "Enabled": true + }, + { + "Name": "WebBrowser", + "Enabled": true } ] } \ No newline at end of file diff --git a/docs/ops/HYPERTWIST_COMPREHENSIVE_RECONSTRUCTION_ROADMAP_2026-06-10.md b/docs/ops/HYPERTWIST_COMPREHENSIVE_RECONSTRUCTION_ROADMAP_2026-06-10.md new file mode 100644 index 0000000..8ca09f0 --- /dev/null +++ b/docs/ops/HYPERTWIST_COMPREHENSIVE_RECONSTRUCTION_ROADMAP_2026-06-10.md @@ -0,0 +1,417 @@ +# HyperTwist — Comprehensive Reconstruction Roadmap +## Status: Draft — Post-Audit Reality Alignment +## Date: 2026-06-10 + +## Remaining Repo Inventory (Authoritative Reconstruction) + +Source: `HYPERTWIST_REPO_STATE_BOARD_2026-05-11.md` and `HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md` + +**Within the original 71-row shallow-eval set:** + +| Category | Count | +|----------|-------| +| Implemented/live (all licenses) | 29 | +| **Selected, not live (permissive candidates)** | **29** | +| Reference / benchmark / discard | 13 | +| **Total non-live** | **42** | + +**Outside the 71-row set:** + +| Category | Count | Repos | +|----------|-------|-------| +| Speech rows (landed as attribution only) | 4 | `ggml-org/whisper.cpp`, `rhasspy/piper`, `SYSTRAN/faster-whisper`, `coqui-ai/TTS` | + +**The 29 selected-not-live permissive candidates include:** +- `cahidenes/rubiks-cube-solver` +- `tentone/rubix-solver` +- `NuiLab/code-vr` +- `pissang/claygl` +- `pissang/clay-viewer` +- `pmndrs/postprocessing`, `pmndrs/react-postprocessing`, `pmndrs/drei`, `pmndrs/react-spring`, `@react-spring/*`, `pmndrs/three-stdlib`, `pmndrs/maath`, `pmndrs/uikit`, `pmndrs/zustand`, `pmndrs/leva`, `pmndrs/use-gesture` +- `ecomfe/zrender`, `ecomfe/echarts-gl` +- `KhronosGroup/glTF-Sample-Viewer`, `KhronosGroup/glTF-Sample-Renderer` +- `google/model-viewer/packages/*` (sub-packages) +- And others in the 0R-B backlog + +**None of these 29 are currently wired into the Unreal build.** They exist only as attribution bundles and JSONL reference pages. + +--- + +--- + +## Executive Summary + +This roadmap replaces the self-referential validation-ladder sequence with a +functional, repo-first reconstruction plan. The audit confirms that HyperTwist +is ~80% documentation scaffolding, ~15% data-structure code, and ~5% actual +game logic. No 3D puzzle renderer exists. No playable level exists. No donor +repos are wired into the build. + +**The new rule:** Repos are wired before features are claimed. Features are +playable before they are documented. Validation tests verify behavior, not +structural metadata. + +--- + +## Phase 0: Foundation — Build Infrastructure for Repo Wiring + +**Goal:** Enable actual donor code to be compiled, linked, and shipped. + +**Deliverables:** +- [ ] Create `.external/` directory with `CMakeLists.txt` wrapper for UE5 plugin-style builds +- [ ] Create `ThirdParty/` directory for header-only and prebuilt libraries +- [ ] Add `.gitmodules` for the first wave of C++ donor repos +- [ ] Add `Build.cs` rules in `UnrealHyperTwist.Build.cs` for `PublicIncludePaths` and `PublicAdditionalLibraries` +- [ ] Windows build validation after each sub-step (prove the linker sees donor symbols) + +**Estimated actions:** ~15 build actions per sub-step +**Estimated time:** 2–3 hours per sub-step (infrastructure compiles fast) + +--- + +## Phase 1: Wire All Donor Repos (Repo-First Constraint) + +**Principle:** Repos are wired into the build BEFORE any feature claims them. +See `HYPERTWIST_UNWIRED_REPO_INVENTORY_AND_WIRING_SCHEDULE_2026-06-10.md` +for the full 29-repo queue and per-repo wiring posture. + +### 1A — Solver Backend: `efrantar/rob-twophase` +- [ ] Add submodule `mirrors/rob-twophase` +- [ ] Write UE `Build.cs` rules linking `libtwophase` or object files +- [ ] Expose `UHyperTwistSolverLibrary::SolveClassicState(FString KociembaState)` → `TArray MoveSequence` +- [ ] Automation test: feed a known scrambled state, assert solution length < 25 + +### 1B — Speech-to-Text: `freestyle-voice/freestyle` (MIT) +- [ ] Decision gate: `freestyle` is a hotkey-driven dictation client, not an embeddable C++ library. It calls cloud APIs (OpenAI, Groq, Anthropic, Google, Deepgram, ElevenLabs) via HTTP. +- [ ] Integration path A (recommended): Run `freestyle` as external sidecar process. UE communicates via local HTTP loopback or IPC. +- [ ] Integration path B (fallback): Embed `freestyle` source (Tauri/Rust or Electron) as a UE plugin — evaluate complexity vs. value. +- [ ] Expose `UHyperTwistSpeechLibrary::StartDictationSession()` / `EndDictationSession()` +- [ ] On hotkey hold: capture microphone via UE `VoiceModule`, stream PCM to `freestyle` loopback endpoint +- [ ] On release: receive transcript JSON, parse cleaned text, execute move notation or coach command +- [ ] **Audio Ducking**: when `bDictationActive = true`, duck all non-speech `UAudioComponent` volumes to 15% via `FAudioDevice` mixer gain or per-component `VolumeMultiplier` +- [ ] Restore full volume 200ms after `EndDictationSession()` +- [ ] Automation test: simulate hotkey hold, assert `VolumeMultiplier < 0.2f` on background music component; assert restoration after release + +### 1C — Text-to-Speech: `rhasspy/piper` +- [ ] Add submodule `mirrors/piper` +- [ ] Compile `piper` as static library (espeak-ng dependency) +- [ ] Download one small voice model (~50MB) into `Content/Voices/` +- [ ] Expose `UHyperTwistSpeechLibrary::Synthesize(FString Text, FString VoiceId)` → `TArray PCM16` +- [ ] Automation test: synthesize "hello", assert PCM output is non-empty and has correct sample rate + +### 1D — Compact Solver Oracle: `brownan/Rubiks-Cube-Solver` (GPL-2.0) +- [ ] Host as external IPC process (never link GPL into Unreal binary) +- [ ] Expose `UHyperTwistSolverLibrary::VerifySolution(FString State, TArray Moves)` → `bool` + +### 1E — glTF Reference Renderer: `KhronosGroup/glTF-Sample-Renderer` (Apache-2.0) +- [ ] Add submodule `mirrors/glTF-Sample-Renderer` +- [ ] Evaluate: header-only portions vs. full renderer +- [ ] If linkable: add to `Build.cs`, expose asset import validation helpers +- [ ] If too heavy: retain as reference-only for QA pipeline + +### 1F — Solver Adjunct: `cahidenes/rubiks-cube-solver` (MIT) +- [ ] Host as external IPC process (Python) +- [ ] Expose comparison endpoint: same state to both solvers, assert identical solution length + +### 1G — Browser Solver: `tentone/rubix-solver` (MIT) +- [ ] Bundle into browser runtime (`Content/Browser/`) +- [ ] Load in embedded WebBrowser widget as demo/fallback solver UI + +### 1H — Browser Spatial Stack (13 JS repos) +- [ ] Add all as npm dependencies or prebuilt bundles in `Content/Browser/` +- [ ] Repos: `NuiLab/code-vr`, `pissang/claygl`, `pissang/clay-viewer`, `pmndrs/postprocessing`, `pmndrs/react-postprocessing`, `pmndrs/drei`, `pmndrs/uikit`, `pmndrs/three-stdlib`, `pmndrs/maath`, `pmndrs/zustand`, `pmndrs/leva`, `pmndrs/use-gesture`, `pmndrs/react-spring` + sub-packages +- [ ] Build once via npm → bundle `browser-spatial-runtime.js` +- [ ] Load bundle in `UHyperTwistBrowserWidget` +- [ ] State bridge: UE `FJsonObject` ↔ JS `postMessage` + +### 1I — Analytics Stack (2 JS repos) +- [ ] `ecomfe/zrender`, `ecomfe/echarts-gl` +- [ ] Bundle into browser runtime; subordinate to already-landed `apache/echarts` +- [ ] Expose chart data endpoint from UE analytics subsystem + +### 1J — Model-Viewer Sub-Packages (3 JS repos, runtime) +- [ ] `google/model-viewer/packages/model-viewer-effects`, `space-opera`, `render-fidelity-tools` +- [ ] Bundle into browser runtime alongside already-landed `google/model-viewer` +- [ ] `render-fidelity-tools` → QA comparison pipeline only + +**Estimated actions:** 40–60 per repo (UHT regen on first include) +**Estimated time:** 1–2 days per repo (build-debug cycles) + +--- + +## Phase 2: Core Puzzle Renderer — The Missing Centerpiece + +**Goal:** HyperTwist becomes a visible, interactive product. + +**Principle:** This is the highest-priority functional gap. It blocks every user-facing feature. + +### 2A — Procedural Classic Cube Geometry +- [ ] Create `AHyperTwistClassicCubeActor` : `AActor` +- [ ] Generate 26 pieces (6 centers, 12 edges, 8 corners) as `UProceduralMeshComponent` or `UStaticMeshComponent` instances +- [ ] Assign per-face materials (6 colors + black internals) +- [ ] Place pieces in solved-state positions in a 3×3×3 grid +- [ ] No animation yet — static correct geometry is the first proof + +### 2B — Face Rotation Logic +- [ ] Implement `UHyperTwistClassicCubeComponent::RotateFace(ECubeFace Face, ERotationDirection Dir, bool bAnimate)` +- [ ] Update piece position/orientation arrays (state math already exists in `HyperTwistCoreLibrary`) +- [ ] Animate rotation using `FLatentActionManager` or tick-based quaternion interpolation +- [ ] Duration: 0.15s per quarter-turn (standard cubing feel) + +### 2C — Mouse/Touch Input +- [ ] Implement `AHyperTwistClassicCubeActor::OnClick(FVector RayOrigin, FVector RayDir)` +- [ ] Raycast against cube pieces, determine which face was clicked +- [ ] Map click position to face + direction (CW/CCW) +- [ ] Support drag gestures for swipe-based turning +- [ ] Automation test: simulate raycast, assert correct face rotates + +### 2D — Scramble Generation +- [ ] Expose `UHyperTwistClassicCubeComponent::GenerateScramble(int32 Length)` → `TArray` +- [ ] Apply scramble to visible geometry (animate each move) +- [ ] Display scramble notation in HUD + +### 2E — Timer + HUD +- [ ] Create `WBP_HyperTwistGameHUD` (UMG Widget) +- [ ] Timer display (minutes:seconds.milliseconds) +- [ ] Inspection countdown (15s standard) +- [ ] Scramble notation panel +- [ ] Bind timer start to first face turn, stop to solved-state detection + +**Estimated actions:** 80–120 (geometry + input + HUD) +**Estimated time:** 3–5 days + +--- + +## Phase 3: First Playable Level + +**Goal:** A level you can launch, scramble, solve, and time. + +### 3A — Level Creation +- [ ] Create `L_HyperTwist_ClassicTraining` (`.umap`) +- [ ] Place `AHyperTwistClassicCubeActor` at world origin +- [ ] Add directional light + ambient environment (basic, not immersive yet) +- [ ] Add `WBP_HyperTwistGameHUD` to viewport +- [ ] Add camera pawn with orbit controls (mouse drag orbits, scroll zooms) + +### 3B — Game Mode +- [ ] Create `AHyperTwistClassicGameMode` : `AGameModeBase` +- [ ] Handle game state: `Idle`, `Inspecting`, `Solving`, `Solved` +- [ ] On `Solved`: stop timer, show solve time, offer "New Scramble" + +### 3C — Build & Package Validation +- [ ] Package `UnrealHyperTwist` for Windows (not just Editor build) +- [ ] Launch packaged build on Windows host +- [ ] Verify: cube visible, clickable, scramble applies, timer works, solve detected + +**Estimated actions:** 20–30 +**Estimated time:** 1–2 days + +--- + +## Phase 4: Wire Solver into Training Pipeline + +**Prerequisite:** Phase 1A (rob-twophase) + Phase 2 (renderer) + +### 4A — Solver HUD Integration +- [ ] Add "Hint" button to HUD +- [ ] On click: query solver for next optimal move from current state +- [ ] Animate hint (glow the suggested face) +- [ ] Option: show full solution sequence as notation list + +### 4B — Training Mode: Follow-Along +- [ ] Create `L_HyperTwist_FollowAlongTraining` (`.umap`) +- [ ] Load a known scramble, show user the moves one at a time +- [ ] User must match each move before advancing +- [ ] Track accuracy and time + +### 4C — Solver Verification +- [ ] After user solve, verify state is actually solved (not just timer stopped) +- [ ] If not solved, show "DNF" (Did Not Finish) + +**Estimated actions:** 30–50 +**Estimated time:** 2–3 days + +--- + +## Phase 5: Speech Pipeline (STT + TTS) + +**Prerequisite:** Phase 1B (freestyle) + Phase 1C (piper) + +### 5A — Voice Command Input +- [ ] Add "Voice" button to HUD (or use freestyle global hotkey) +- [ ] On hotkey hold: capture microphone audio → stream to freestyle loopback +- [ ] On release: receive cleaned transcript from freestyle +- [ ] Parse transcript for move notation: "R", "R prime", "R2", "slice M", etc. +- [ ] Execute parsed move on cube +- [ ] **Audio ducking active during entire hold duration** + +### 5B — Coach Narration Output +- [ ] Add narration events: "Scramble ready", "Inspection time", "Go!", "Solved!" +- [ ] Feed event text to piper → PCM16 +- [ ] Play PCM16 through UE `USoundWaveProcedural` or `FSoundSource` +- [ ] Support multiple voice models (coach personality selection) +- [ ] **Narration audio is NOT ducking candidate** — only background music/ambient + +### 5C — Voice Session Tests +- [ ] Automation test: simulate hotkey hold, assert background `VolumeMultiplier < 0.2f` +- [ ] Automation test: assert transcript "R prime" → parsed move `ECubeFace::R, ERotationDirection::CounterClockwise` +- [ ] Automation test: "Solved!" → piper → assert PCM length > 0 + +**Estimated actions:** 40–60 +**Estimated time:** 2–3 days + +--- + +## Phase 6: Hypercube Renderer (4D/5D) + +**Prerequisite:** Phase 2 (classic renderer) + +### 6A — 2×2×2×2 Projection +- [ ] Port Melinda 2×2×2×2 state math (already exists) to visible geometry +- [ ] Implement cell-first projection (8 cells, each a 3D cube) +- [ ] Color 16 stickers per cell using permutation/orientation state +- [ ] Mouse interaction: click cell + axis → twist + +### 6B — 3×3×3×3 Projection +- [ ] Extend to 3×3×3×3 (27 tesseracts, 81 cells visible in projection) +- [ ] Use wireframe or transparent cells to avoid occlusion chaos +- [ ] Keyboard shortcuts for axis rotation and slice twists + +### 6C — Magic120Cell & MagicCube5D +- [ ] Decision gate: port roice3 code (Java/C#) or implement clean-room in UE +- [ ] If port: host as external process, stream state via IPC +- [ ] If clean-room: implement 120-cell dodecahedral projection from spec + +**Estimated actions:** 100–200 +**Estimated time:** 1–2 weeks + +--- + +## Phase 7: Non-Euclidean Puzzles (MagicTile) + +**Prerequisite:** Phase 6 (hypercube renderer) + +### 7A — MagicTile Host Decision +- [ ] Evaluate: port MagicTile Java/OpenTK to Unreal vs. host in embedded browser +- [ ] If browser: wire `react-three-fiber` + `three.js` into embedded CEF +- [ ] If port: implement spherical/hyperbolic tiling math from spec + +### 7B — Puzzle State Bridge +- [ ] Unreal ↔ MagicTile state serialization +- [ ] Shared scramble notation parser +- [ ] Unified timer across puzzle types + +**Estimated actions:** 80–150 +**Estimated time:** 1–2 weeks + +--- + +## Phase 8: Browser-Based Renderer + +**Prerequisite:** Phase 2 (classic renderer) + +### 8A — Embedded Browser Runtime +- [ ] Add `WebBrowser` plugin to `.uproject` +- [ ] Create `UHyperTwistBrowserWidget` wrapping `SWebBrowser` +- [ ] Load local `three.js` + `react-three-fiber` build + +### 8B — State Synchronization +- [ ] Bridge UE cube state to browser via `FJsonObject` → JavaScript `postMessage` +- [ ] Browser renders cube using Three.js; UE handles input and logic +- [ ] Alternative: full browser client with HTTP API to UE backend + +**Estimated actions:** 50–80 +**Estimated time:** 3–5 days + +--- + +## Phase 9: Social & Export + +**Prerequisite:** Phase 3 (playable level) + +### 9A — Replay Recording +- [ ] Record move sequence + timestamps during solve +- [ ] Export to `.json` replay file +- [ ] Load replay, reconstruct animation + +### 9B — Media Export +- [ ] Integrate `remotion-dev/remotion` or UE `MovieRenderQueue` for video export +- [ ] Export solve animation as MP4 +- [ ] Export scramble + time as shareable image + +### 9C — Leaderboard Stub +- [ ] Local SQLite or JSON leaderboard (no backend yet) +- [ ] Store best times per puzzle type + scramble length +- [ ] Display in HUD + +**Estimated actions:** 40–60 +**Estimated time:** 2–3 days + +--- + +## Phase 10: Validation Reconstruction + +**Principle:** Validation only verifies what actually exists. + +### 10A — Deprecate Structural-Only Tests +- [ ] Mark all Phase J tests that only verify contract ID stability as `Deprecated` +- [ ] Do not delete (preserves build history), but stop adding new ones + +### 10B — Behavior-Based Validation Tests +- [ ] `FHyperTwistClassicCubeRotationTest`: Rotate R face, assert piece positions updated +- [ ] `FHyperTwistClassicCubeSolveTest`: Apply known solution, assert solved-state +- [ ] `FHyperTwistSolverAccuracyTest`: Feed 100 random states to solver, assert all solvable +- [ ] `FHyperTwistTimerAccuracyTest`: Start timer, wait 5s, assert 4.9s < elapsed < 5.1s +- [ ] `FHyperTwistSpeechTranscriptionTest`: Synthetic PCM "R prime" → assert move parsed + +### 10C — Integration Tests +- [ ] Launch `L_HyperTwist_ClassicTraining`, simulate 10 moves, verify no crash +- [ ] Package build test: verify `UnrealHyperTwist.exe` launches and cube is visible + +**Estimated actions:** 20–30 +**Estimated time:** 1–2 days + +--- + +## Cross-Cutting Concerns + +### Licensing & Attribution +- Each wired repo gets a `LICENSE.thirdparty` entry +- GPL repos (brownan) remain IPC-only; never linked +- MIT/Apache repos compile and link directly +- Attribution bundles updated from metadata-only to runtime-provenance + +### Build Validation Doctrine +- Every phase requires Windows Unreal build validation +- Phase 0–1: expect 50–100 actions (infrastructure) +- Phase 2–3: expect 150–250 actions (geometry + input) +- Phase 4+: expect 80–150 actions (feature wiring) +- Package validation (Phase 3C) is the real gate, not Editor build + +### Documentation Rule +- Docs describe what IS implemented, not what MIGHT be +- No new "packet" files for scaffolding +- Architecture docs updated only after functional code is merged + +--- + +## Summary: What Changes vs. Old Roadmap + +| Old Approach | New Approach | +|--------------|--------------| +| Add struct pairs (J-HG → J-HM) | Wire repos (freestyle, piper, rob-twophase) | +| Tests verify contract IDs | Tests verify cube rotation, solve accuracy, speech | +| Docs claim features are "landed" | Features are playable before documented | +| 318 test files, 0 gameplay | 30 test files, 1 playable level | +| 1,142 docs, 20 content assets | Docs trimmed to functional truth | +| No donor repos linked | C++ repos compiled and linked | +| No .uasset, .umap | Procedural geometry + playable level | + +--- + +## Immediate Next Step + +**Phase 0A:** Create `.external/` and `ThirdParty/`, add `.gitmodules` for +`freestyle-voice/freestyle` as the proof-of-concept speech integration. + +This is the smallest step that proves the repo-wiring infrastructure works. diff --git a/docs/ops/HYPERTWIST_UNWIRED_REPO_INVENTORY_AND_WIRING_SCHEDULE_2026-06-10.md b/docs/ops/HYPERTWIST_UNWIRED_REPO_INVENTORY_AND_WIRING_SCHEDULE_2026-06-10.md new file mode 100644 index 0000000..ddfb239 --- /dev/null +++ b/docs/ops/HYPERTWIST_UNWIRED_REPO_INVENTORY_AND_WIRING_SCHEDULE_2026-06-10.md @@ -0,0 +1,163 @@ +# HyperTwist — Unwired Repo Inventory & Wiring Schedule + +**Date:** 2026-06-10 +**Source authority:** `HYPERTWIST_REPO_STATE_BOARD_2026-05-11.md`, `HYPERTWIST_PHASE_0R_PACKET_0R_B_EVALUATION_2026-05-12.md`, `HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md` +**Status:** Reconstructed from canonical docs; counts verified against board totals. + +--- + +## Executive Count + +| Bucket | Count | +|--------|-------| +| Implemented/live (all licenses, original 71-row set) | 29 | +| **Selected, not live — permissive wiring queue** | **29** | +| Reference / benchmark / discard (0R-E) | 13 | +| Speech rows outside 71-row set (attribution-only) | 4 | +| **Total non-live** | **46** | + +The **29 in the wiring queue** are the implementation targets. The 13 reference/discard rows and the 4 speech rows are accounted for but not scheduled for direct wiring unless a later decision changes their posture. + +--- + +## The 29 — Permissive Wiring Queue (0R-B minus live promotions) + +These repos were evaluated in `Packet 0R-B` (36 repos). Seven later graduated to live status via Phase 3R and 6R packets. The remaining 29 are retained but **not yet wired** into the Unreal build. + +### Wave A — Solver & Recognition Adjuncts (2 repos) + +| # | Repo | License | Lang | What It Does | Wiring Approach | Target Phase | +|---|------|---------|------|--------------|-----------------|--------------| +| 1 | `cahidenes/rubiks-cube-solver` | MIT | Python | Classic cube solver with visualizer | IPC process or Python embedding; expose `Solve(FString State)` → moves | 4A (Solver HUD) | +| 2 | `tentone/rubix-solver` | MIT | JS | Browser-based cube solver | Embedded browser runtime (CEF) or adapter layer; not direct C++ link | 4A (Solver HUD) | + +### Wave B — Spatial / Browser / XR Stack (13 repos) + +| # | Repo | License | Lang | What It Does | Wiring Approach | Target Phase | +|---|------|---------|------|--------------|-----------------|--------------| +| 3 | `NuiLab/code-vr` | MIT | JS | Code editor in VR (WebXR) | Embedded browser or WebXR bridge; evaluate vs. native UE VR | 8 (Browser renderer) | +| 4 | `pissang/claygl` | BSD | JS | Lightweight WebGL engine | Embedded browser runtime; alternative to Three.js if needed | 8 (Browser renderer) | +| 5 | `pissang/clay-viewer` | BSD | JS | glTF model viewer on ClayGL | Embedded browser runtime; asset QA preview | 8 (Browser renderer) | +| 6 | `pmndrs/postprocessing` | Zlib | JS | Post-processing effects for Three.js | Embedded browser runtime; visual polish for browser view | 8 (Browser renderer) | +| 7 | `pmndrs/react-postprocessing` | MIT | JS | React wrapper for postprocessing | Embedded browser runtime; only if R3F bridge is used | 8 (Browser renderer) | +| 8 | `pmndrs/drei` | MIT | JS | Useful helpers for R3F | Embedded browser runtime; helper components | 8 (Browser renderer) | +| 9 | `pmndrs/uikit` | MIT | JS | UI components for R3F | Embedded browser runtime; HUD in browser view | 8 (Browser renderer) | +| 10 | `pmndrs/three-stdlib` | MIT | JS | Three.js standard library extensions | Embedded browser runtime; dependency of other pmndrs pkgs | 8 (Browser renderer) | +| 11 | `pmndrs/maath` | MIT | JS | Math utilities for animation | Embedded browser runtime; animation easing | 8 (Browser renderer) | +| 12 | `pmndrs/zustand` | MIT | JS | State management | Embedded browser runtime; state sync if browser view is standalone | 8 (Browser renderer) | +| 13 | `pmndrs/leva` | MIT | JS | GUI controls for R3F | Embedded browser runtime; debug/inspector panel | 8 (Browser renderer) | +| 14 | `pmndrs/use-gesture` | MIT | JS | Gesture hooks for React | Embedded browser runtime; touch/drag in browser view | 8 (Browser renderer) | +| 15 | `pmndrs/react-spring` | MIT | JS | Spring physics animation | Embedded browser runtime; smooth transitions | 8 (Browser renderer) | + +### Wave C — Google Model-Viewer Sub-Packages (4 repos) + +| # | Repo | License | Lang | What It Does | Wiring Approach | Target Phase | +|---|------|---------|------|--------------|-----------------|--------------| +| 16 | `google/model-viewer/packages/model-viewer-effects` | Apache-2.0 | JS | Particle/effects system for model-viewer | Embedded browser runtime; decorative effects | 8 (Browser renderer) | +| 17 | `google/model-viewer/packages/modelviewer.dev` | Apache-2.0 | JS | Documentation site | Not for runtime; reference docs only | — | +| 18 | `google/model-viewer/packages/render-fidelity-tools` | Apache-2.0 | JS | Rendering comparison tools | Not for runtime; QA/benchmark pipeline | 10B (Validation) | +| 19 | `google/model-viewer/packages/space-opera` | Apache-2.0 | JS | Model-viewer editor UI | Embedded browser runtime; editor interface | 8 (Browser renderer) | + +### Wave D — Analytics & Visualization (2 repos) + +| # | Repo | License | Lang | What It Does | Wiring Approach | Target Phase | +|---|------|---------|------|--------------|-----------------|--------------| +| 20 | `ecomfe/zrender` | BSD | JS | 2D rendering engine (ECharts dependency) | Embedded browser runtime; subordinate to apache/echarts | 9 (Social/Export) | +| 21 | `ecomfe/echarts-gl` | BSD | JS | WebGL extension for ECharts | Embedded browser runtime; 3D charts/progress viz | 9 (Social/Export) | + +### Wave E — glTF Standards & Samples (2 repos) + +| # | Repo | License | Lang | What It Does | Wiring Approach | Target Phase | +|---|------|---------|------|--------------|-----------------|--------------| +| 22 | `KhronosGroup/glTF-Sample-Viewer` | Apache-2.0 | JS | Reference glTF viewer | Embedded browser runtime; standard compliance check | 8 (Browser renderer) | +| 23 | `KhronosGroup/glTF-Sample-Renderer` | Apache-2.0 | C++ | Reference glTF renderer | **Direct C++ link** via `ThirdParty/`; evaluate for asset import pipeline | 2A (Geometry) | + +### Wave F — React-Spring Sub-Packages (6 repos) + +| # | Repo | License | Lang | What It Does | Wiring Approach | Target Phase | +|---|------|---------|------|--------------|-----------------|--------------| +| 24 | `@react-spring/core` | MIT | JS | Core spring physics | Embedded browser runtime; dependency | 8 (Browser renderer) | +| 25 | `@react-spring/shared` | MIT | JS | Shared utilities | Embedded browser runtime; dependency | 8 (Browser renderer) | +| 26 | `@react-spring/types` | MIT | TS | Type definitions | Dev dependency only; not shipped | — | +| 27 | `@react-spring/parallax` | MIT | JS | Parallax scrolling | Embedded browser runtime; scroll UX if needed | 8 (Browser renderer) | +| 28 | `@react-spring/rafz` | MIT | JS | RAF scheduling | Embedded browser runtime; dependency | 8 (Browser renderer) | +| 29 | `@react-spring/animated` | MIT | JS | Animated component primitives | Embedded browser runtime; dependency | 8 (Browser renderer) | + +--- + +## Wiring Rules by Runtime Posture + +### Direct C++ Link (Only for C/C++ repos) +- `efrantar/rob-twophase` +- `KhronosGroup/glTF-Sample-Renderer` +- `rhasspy/piper` +- `freestyle-voice/freestyle` (if embedding; otherwise IPC) + +### Embedded Browser Runtime (For JS/TS repos) +- Requires `WebBrowser` plugin in `.uproject` +- Requires Node.js build pipeline or prebuilt bundles in `Content/Browser/` +- State bridge via `FJsonObject` ↔ JavaScript `postMessage` +- All Wave B, C, D, E (JS), F repos use this path + +### IPC / Sidecar Process (For Python or restrictive repos) +- `cahidenes/rubiks-cube-solver` (Python) +- `brownan/Rubiks-Cube-Solver` (GPL, Python) +- `freestyle-voice/freestyle` (if not embedded) + +### Reference-Only (No runtime wiring) +- `google/model-viewer/packages/modelviewer.dev` — docs site +- `@react-spring/types` — TypeScript dev dependency +- `pmndrs/react-postprocessing` — only if R3F is primary path; may be redundant + +--- + +## Speech Rows (Outside 71-Row Set) + +| Repo | License | Status | New Wiring Plan | +|------|---------|--------|-----------------| +| `ggml-org/whisper.cpp` | MIT | **Replaced** | No longer primary STT; retain as benchmark/reference | +| `rhasspy/piper` | MIT | **Queued** | Phase 1C — compile as static lib, link directly | +| `SYSTRAN/faster-whisper` | MIT | **Queued** | Retain as alternative STT benchmark; no active wiring | +| `coqui-ai/TTS` | MPL-2.0 | **Queued** | Retain as TTS benchmark; piper is primary | + +**STT primary:** `freestyle-voice/freestyle` (MIT, cloud-API client) +**TTS primary:** `rhasspy/piper` (MIT, local C++ engine) + +--- + +## Reference / Benchmark / Discard (13 repos — 0R-E) + +Not scheduled for wiring. Listed for completeness: + +| Repo | Posture | +|------|---------| +| `yakupbilen/drl-rubiks-cube` | Research benchmark only | +| `brownan/Rubiks-Cube-Solver` | GPL oracle; IPC if ever used | +| `efrantar/rob-twophase` | **Promoted to Phase 1A** — direct implementation | +| `ShellPuppy/RCube` | Benchmark only | +| `vwcwong/CubeSim` | Benchmark only | +| `alinen/cube` | Benchmark only | +| `ambisinister/blindsolve` | Benchmark only | +| `AviKaufman/Rubix-cube-trainer` | Benchmark only | +| `poliva/cubedex` | Restrictive comparison context | +| And 4 others | Discard or deferred | + +--- + +## Phase 1 Regenerated — All Wired Repos + +| Sub-Phase | Repo | Wiring Path | Build Type | +|-----------|------|-------------|------------| +| 1A | `efrantar/rob-twophase` | Static library, direct link | C++ | +| 1B | `freestyle-voice/freestyle` | Sidecar HTTP or embedded | Rust/TS | +| 1C | `rhasspy/piper` | Static library, direct link | C++ | +| 1D | `brownan/Rubiks-Cube-Solver` | IPC process (GPL) | Python | +| 1E | `KhronosGroup/glTF-Sample-Renderer` | Static library or header-only | C++ | +| 1F | `cahidenes/rubiks-cube-solver` | IPC process | Python | +| 1G | `tentone/rubix-solver` | Embedded browser | JS | + +--- + +## Next Step + +**Phase 0:** Create `.external/`, `ThirdParty/`, `.gitmodules`, and `Build.cs` rules so that Phase 1 repos can actually compile and link.