{"id":50316466,"url":"https://github.com/msitarzewski/opwv","last_synced_at":"2026-05-29T00:03:29.652Z","repository":{"id":321262672,"uuid":"1083827780","full_name":"msitarzewski/opwv","owner":"msitarzewski","description":"An immersive WebXR experience featuring 360° organic particle animations in virtual reality. Explore seven unique environments with distinct physics systems, from flocking behaviors to orbital mechanics, using Vision Pro spatial UI and hand tracking.","archived":false,"fork":false,"pushed_at":"2025-10-30T17:12:15.000Z","size":349,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T04:12:38.826Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/msitarzewski.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-26T19:39:43.000Z","updated_at":"2025-10-30T17:25:58.000Z","dependencies_parsed_at":"2025-10-28T19:09:33.640Z","dependency_job_id":"9bcd4a93-6ce5-498f-928b-b1f0cf3ef8cb","html_url":"https://github.com/msitarzewski/opwv","commit_stats":null,"previous_names":["msitarzewski/opwv"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/msitarzewski/opwv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msitarzewski%2Fopwv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msitarzewski%2Fopwv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msitarzewski%2Fopwv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msitarzewski%2Fopwv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/msitarzewski","download_url":"https://codeload.github.com/msitarzewski/opwv/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msitarzewski%2Fopwv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33631002,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-29T00:03:26.749Z","updated_at":"2026-05-29T00:03:29.642Z","avatar_url":"https://github.com/msitarzewski.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Organic Particle WebGL Visualizer (OPWV)\n\nAn immersive WebXR experience featuring 360° organic particle animations in virtual reality. Explore seven unique environments with distinct physics systems, from flocking behaviors to orbital mechanics, using Vision Pro spatial UI and hand tracking.\n\n![License](https://img.shields.io/badge/license-MIT-blue.svg)\n![Three.js](https://img.shields.io/badge/Three.js-v0.169.0-green.svg)\n![Vite](https://img.shields.io/badge/Vite-v5.4.10-purple.svg)\n![WebXR](https://img.shields.io/badge/WebXR-Immersive-orange.svg)\n\n## ✨ Features\n\n### VR Experience\n- **WebXR Immersive Mode**: Full 360° VR experience with hand tracking support\n- **Vision Pro Spatial UI**: Floating glassmorphic cards with gaze-based selection and hand gestures\n- **Seven Unique Environments**: Each with distinct physics and visual styles\n  - **Sphere**: Classic flocking behaviors with organic motion\n  - **Nebula**: Brownian motion with large, glowing particles\n  - **Galaxy**: Orbital mechanics with Newtonian gravity\n  - **Lattice**: Spring physics with breathing grid structure\n  - **Vortex**: Flow field creating centripetal tornado motion\n  - **Ocean**: Wave equation with sine wave propagation\n  - **Hypercube**: 4D rotation with tesseract projection\n- **Speed Control**: Adjust animation speed (0.25x-2.0x) for productivity or meditation\n- **Persistent Settings**: Speed preferences saved across sessions\n\n### Visual Quality\n- **Generative Beauty**: Unique, procedurally-generated animations\n- **Seeded Randomization**: Reproducible visuals via URL parameters (`?seed=12345`)\n- **Harmonious Color Palettes**: HSL-based analogous color schemes\n- **Adaptive Performance**: Maintains smooth 72fps in VR (60fps fallback)\n- **1000 Particles**: Distributed in spherical space for immersive viewing\n\n## 🚀 Demo\n\n**Requirements**: WebXR-compatible VR headset (Meta Quest, Vision Pro, Vive, Index, etc.)\n\n```bash\nnpm install\nnpm run dev\n```\n\nVisit the local server URL in your VR browser or use a tunneling service (ngrok, cloudflared) for device testing.\n\n### Try Different Seeds\n\n- `?seed=12345` - Specific reproducible environment colors\n- `?seed=67890` - Different color palette\n- No parameter - Random seed on each load\n\n### VR Controls\n\n- **Gaze Selection**: Look at environment cards and dwell for 0.8s to select\n- **Hand Gestures** (Vision Pro): Pinch-and-drag on speed slider\n- **Controller Input**: Point and trigger on UI elements\n- **UI Toggle**: Look down to see floating orb, select to show/hide environment menu\n\n## 🎯 Status\n\n**VR Environments Milestone**: ⏳ 62.5% Complete (5/8 tasks)\n\nCompleted:\n- ✅ MVP Phase (10/10 tasks) - Core particle system and rendering\n- ✅ XR Test Milestone (6/6 tasks) - WebXR 360° immersive mode\n- ✅ VR-01: Environment System Architecture\n- ✅ VR-02: VR-Only Migration (removed 2D mode)\n- ✅ VR-03: Spatial UI Framework (Vision Pro hand tracking)\n- ✅ VR-04: Speed Control System (0.25x-2.0x range)\n- ✅ VR-05: Environment Presets (7 unique physics systems)\n\nIn Progress:\n- ⏳ VR-06: Landing Page (1.25hr remaining)\n- ⏳ VR-07: Environment Transitions (2.25hr remaining)\n- ⏳ VR-08: Testing and Optimization (2.75hr remaining)\n\n**Bundle Size**: 617.72 kB (158.13 kB gzipped)\n\n## 🛠️ Tech Stack\n\n- **Three.js** v0.169.0 - WebGL rendering, scene management, WebXR integration\n- **WebXR API** - Immersive VR sessions with hand tracking\n- **XRHandModelFactory** - Vision Pro hand mesh rendering\n- **Vite** v5.4.10 - Build tool for fast development and optimized production bundles\n- **simplex-noise** v4.0.3 - Organic motion and noise field generation\n- **JavaScript ES6+** - Modern module-based architecture with async imports\n\n## 📦 Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/msitarzewski/opwv.git\ncd opwv\n\n# Install dependencies\nnpm install\n\n# Start development server\nnpm run dev\n\n# Build for production\nnpm run build\n\n# Preview production build\nnpm run preview\n```\n\n## 🏗️ Project Structure\n\n```\nopwv/\n├── src/\n│   ├── particles/\n│   │   ├── ParticleSystem.js    # Multi-mode particle management\n│   │   ├── Particle.js          # Individual particle class\n│   │   └── behaviors/           # Physics behavior modules\n│   │       ├── flocking.js      # Cohesion, alignment, separation\n│   │       ├── brownian.js      # Random walk motion\n│   │       ├── orbital.js       # Newtonian gravity simulation\n│   │       ├── spring.js        # Hooke's law spring physics\n│   │       ├── flow.js          # Flow field dynamics\n│   │       ├── wave.js          # Sine wave propagation\n│   │       └── rotation.js      # 4D tesseract rotation\n│   ├── environments/\n│   │   ├── Environment.js       # Environment configuration schema\n│   │   ├── EnvironmentManager.js # Multi-environment orchestration\n│   │   └── presets/             # Environment preset definitions\n│   │       ├── sphere.js        # Classic flocking\n│   │       ├── nebula.js        # Brownian motion\n│   │       ├── galaxy.js        # Orbital mechanics\n│   │       ├── lattice.js       # Spring physics grid\n│   │       ├── vortex.js        # Flow field tornado\n│   │       ├── ocean.js         # Wave equation\n│   │       └── hypercube.js     # 4D rotation\n│   ├── ui/\n│   │   ├── SpatialUI.js         # Main UI manager\n│   │   ├── EnvironmentCard.js   # Environment selection cards\n│   │   ├── SpeedControlPanel.js # Speed adjustment interface\n│   │   ├── UIToggleOrb.js       # Floating UI toggle button\n│   │   ├── GazeController.js    # Gaze-based interaction\n│   │   ├── GazeCursor.js        # Visual reticle feedback\n│   │   └── ControllerInput.js   # Hand/controller input handler\n│   ├── utils/\n│   │   ├── random.js            # Seeded random utilities\n│   │   ├── noise.js             # 3D simplex noise wrapper\n│   │   ├── colors.js            # HSL palette generation\n│   │   ├── performance.js       # VR FPS monitoring\n│   │   ├── webxr.js             # WebXR detection utilities\n│   │   └── SpeedControl.js      # Speed state management\n│   └── main.js                  # Entry point, VR session, render loop\n├── memory-bank/                 # Project documentation\n│   ├── projectbrief.md          # Vision and goals\n│   ├── systemPatterns.md        # Architecture patterns\n│   ├── techContext.md           # Technical stack\n│   └── tasks/                   # Task documentation\n├── milestones/                  # Milestone task definitions\n│   ├── mvp/                     # MVP tasks (completed)\n│   ├── xr-test/                 # XR Test tasks (completed)\n│   └── vr-environments/         # VR Environments tasks (in progress)\n├── index.html                   # Minimal HTML shell with WebXR\n├── package.json\n├── vite.config.js\n└── prd.md                       # Product Requirements Document\n```\n\n## 🎨 How It Works\n\nThe VR experience combines multiple systems to create an immersive particle environment:\n\n### Environment System\nEach of the seven environments uses a unique physics simulation:\n\n1. **Sphere (Flocking)**: Craig Reynolds' boids algorithm\n   - Cohesion: Move toward nearby particles\n   - Alignment: Match velocity with neighbors\n   - Separation: Avoid crowding\n   - Simplex noise for organic drift\n\n2. **Nebula (Brownian)**: Random walk motion with momentum damping\n\n3. **Galaxy (Orbital)**: Newtonian gravity (F = GMm/r²) around central mass\n\n4. **Lattice (Spring)**: Hooke's law spring physics on 9×9×9 grid\n\n5. **Vortex (Flow)**: Centripetal force field with upward spiral\n\n6. **Ocean (Wave)**: Sine wave equation with phase propagation\n\n7. **Hypercube (4D Rotation)**: Tesseract projection with rainbow spectrum\n\n### Spatial UI Framework\n- **Vision Pro Hand Tracking**: XRHandModelFactory renders hand meshes\n- **Gaze Controller**: Camera raycasting with 0.8s dwell timer\n- **Controller Input**: WebXR hand/controller support with haptic feedback\n- **Canvas-Based Cards**: 512×683px glassmorphic UI elements\n- **Arc Layout**: UI arranged in 120° arc at 3.5 units distance\n\n### Technical Features\n- **Speed Control**: Smooth lerping (0.3s) between speed multipliers\n- **localStorage Persistence**: Settings saved across sessions\n- **Adaptive Performance**: Particle count reduces if FPS drops below target\n- **Seeded Randomization**: Mulberry32 PRNG for reproducible palettes\n- **Code Splitting**: Dynamic imports for environment presets\n\n## 🎮 Controls\n\n### VR Interaction\n- **Gaze Selection**: Look at UI elements and dwell for 0.8s (progress ring shows timing)\n- **Hand Pinch** (Vision Pro): Pinch-and-drag on speed slider for continuous adjustment\n- **Controller Trigger**: Point and trigger on environment cards or speed controls\n- **UI Toggle Orb**: Look down to see floating orb, select to show/hide environment menu\n\n### URL Parameters\n- `?seed=12345` - Specific reproducible color palette\n\n## 📊 Performance\n\n- **VR Target**: 72fps (Meta Quest, Vision Pro native framerate)\n- **Fallback Target**: 60fps for other VR headsets\n- **Bundle Size**: 617.72 kB (158.13 kB gzipped)\n- **Particle Count**: 1000 in spherical space (adaptive 100-1000+ based on performance)\n- **Build Time**: ~800ms\n- **Code Splitting**: Environment presets loaded dynamically (0.58-2.5 kB per preset)\n\n### WebXR Browser Support\n\n**Desktop VR** (via VR headset browser or link):\n- ✅ Chrome (latest) - Meta Quest, SteamVR\n- ✅ Edge (latest) - Windows Mixed Reality, SteamVR\n- ✅ Firefox Reality - Limited support\n\n**Standalone VR**:\n- ✅ Meta Quest Browser (Quest 2, Quest 3, Quest Pro)\n- ✅ Vision Pro Safari (visionOS)\n- ✅ Pico Browser (Pico 4, Pico Neo)\n\n**Requirements**:\n- WebXR Device API support\n- `immersive-vr` session mode\n- Optional: `hand-tracking` feature for Vision Pro gestures\n\n## 🧪 Testing\n\nComprehensive testing guides available:\n- `TESTING.md` - Original 2D mode testing (88+ test points)\n- `TESTING-XR.md` - VR-specific testing procedures (849 lines)\n  - WebXR session lifecycle testing\n  - Vision Pro hand tracking verification\n  - Environment switching validation\n  - Speed control interaction testing\n  - Performance profiling in VR\n  - Cross-headset compatibility\n\n## 🗺️ Roadmap\n\n### ✅ MVP Phase (Complete)\n- Three.js particle system with organic motion\n- Seeded randomization and color palettes\n- Adaptive performance system\n- Production-ready build\n\n### ✅ XR Test Milestone (Complete)\n- WebXR 360° immersive viewing mode\n- Spherical particle space (1000 particles)\n- VR headset support (Meta Quest, Vision Pro, SteamVR)\n- VR rendering loop with timestamp-based delta\n\n### ⏳ VR Environments (In Progress - 62.5% Complete)\n- ✅ Environment system architecture\n- ✅ VR-only migration (removed 2D mode)\n- ✅ Vision Pro spatial UI with hand tracking\n- ✅ Speed control system (0.25x-2.0x)\n- ✅ Seven environment presets with unique physics\n- ⏳ Landing page for non-VR browsers\n- ⏳ Smooth environment transitions\n- ⏳ Final testing and optimization\n\n### 🔮 V1.1 (Future)\n- Custom environment editor\n- Particle parameter tuning UI\n- Audio-reactive mode\n- Export/share environment configurations\n- Social features (leaderboards, challenges)\n\n### 🌟 V2.0 (Future)\n- Multiplayer shared VR spaces\n- Hand gesture particle manipulation\n- Procedural environment generation\n- VR meditation/productivity modes\n- Integration with productivity tools\n\n## 📄 License\n\nMIT License - see LICENSE file for details\n\n## 👤 Author\n\n**msitarzewski**\n- Email: msitarzewski@gmail.com\n- GitHub: [@msitarzewski](https://github.com/msitarzewski)\n\n## 🙏 Acknowledgments\n\n- **Three.js community** for excellent WebGL and WebXR abstractions\n- **Craig Reynolds** for boids flocking algorithm\n- **simplex-noise** library maintainers for organic motion\n- **WebXR Device API** specification authors\n- **Vision Pro** team for spatial computing innovations\n- **Mind's Eye (1990)** for aesthetic inspiration\n\n## 📚 Documentation\n\nComprehensive project documentation available in `memory-bank/`:\n- `projectbrief.md` - Vision and goals\n- `systemPatterns.md` - Architecture patterns\n- `techContext.md` - Technical decisions and trade-offs\n- `progress.md` - Current status and completed milestones\n- `activeContext.md` - Current sprint focus\n- `tasks/2025-10/README.md` - October 2025 development log (31 tasks documented)\n\n## 🐛 Issues\n\nFound a bug or have a suggestion? Please open an issue on GitHub.\n\n## 🌐 Links\n\n- **Repository**: https://github.com/msitarzewski/opwv\n- **Issues**: https://github.com/msitarzewski/opwv/issues\n- **WebXR Spec**: https://www.w3.org/TR/webxr/\n\n---\n\n**Built with ❤️ using Three.js, WebXR, and Vision Pro spatial computing**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsitarzewski%2Fopwv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmsitarzewski%2Fopwv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsitarzewski%2Fopwv/lists"}