{"id":34683900,"url":"https://github.com/deadronos/vibe-idle-bricks3d","last_synced_at":"2026-04-05T04:04:12.838Z","repository":{"id":326856166,"uuid":"1106480050","full_name":"deadronos/vibe-idle-bricks3d","owner":"deadronos","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-22T23:51:03.000Z","size":1336,"stargazers_count":0,"open_issues_count":13,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T05:03:08.500Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://deadronos.github.io/vibe-idle-bricks3d/","language":"TypeScript","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/deadronos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-11-29T10:36:47.000Z","updated_at":"2026-03-22T14:02:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/deadronos/vibe-idle-bricks3d","commit_stats":null,"previous_names":["deadronos/vibe-idle-bricks3d"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/deadronos/vibe-idle-bricks3d","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deadronos%2Fvibe-idle-bricks3d","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deadronos%2Fvibe-idle-bricks3d/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deadronos%2Fvibe-idle-bricks3d/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deadronos%2Fvibe-idle-bricks3d/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deadronos","download_url":"https://codeload.github.com/deadronos/vibe-idle-bricks3d/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deadronos%2Fvibe-idle-bricks3d/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31423889,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T02:22:46.605Z","status":"ssl_error","status_checked_at":"2026-04-05T02:22:33.263Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":"2025-12-24T21:38:06.145Z","updated_at":"2026-04-05T04:04:12.808Z","avatar_url":"https://github.com/deadronos.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Idle Bricks 3D\n\nA 3D \"idle breakout\" style game built with React, TypeScript, and React Three Fiber.\n\n![Game Screenshot](https://github.com/user-attachments/assets/222a29b0-f1c8-4134-9c5b-62c82498325c)\n\n## Features\n\n- 🎮 **3D Breakout Gameplay**: Watch balls automatically bounce and break bricks in a 3D arena\n- 🏗️ **Multiple Brick Layers**: Bricks are arranged in multiple rows and layers with varying health\n- ⚡ **Idle Mechanics**: The game plays itself - no input required!\n- 📈 **Upgrade System**: Spend points to upgrade ball damage, speed, or add more balls\n- 🎨 **Beautiful Visuals**: Colorful bricks, glowing edges, starfield background\n- 🖱️ **Interactive Camera**: Rotate and zoom to view the action from any angle\n- ⏸️ **Pause/Resume**: Control the game flow\n- 🏅 **Prestige / Meta Progression**: Ascend to gain meta bonuses (prestige mechanics) and long-term progression\n- 🏆 **Achievements**: Unlock progression and performance milestones\n- 💾 **Persistence / Rehydration**: Game progress is persisted to browser storage and rehydrated on load (storage key: `idle-bricks3d:game:v1`).\n\n## Tech Stack\n\n- **React 19** - UI framework\n- **TypeScript** - Type safety\n- **Vite** - Build tool and dev server\n- **React Three Fiber** - React renderer for Three.js\n- **Drei** - Useful helpers for R3F\n- **Three.js** - 3D graphics library\n- **Zustand** - State management\n- **Vitest** - Testing framework\n\n- **Rapier (physics)** - via @dimforge/rapier3d-compat (^0.19.3)\n- **Postprocessing** - via @react-three/postprocessing (^3.0.4)\n\nNote: common package versions used in this repository (see package.json for the full list):\n\n- @react-three/fiber: ^9.4.2\n- @react-three/drei: ^10.7.7\n- three: ^0.181.2\n- @dimforge/rapier3d-compat: ^0.19.3\n- @react-three/postprocessing: ^3.0.4\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 18+\n- pnpm (recommended) or npm / yarn\n\n### Installation\n\n```bash\n# Install dependencies (pnpm recommended)\npnpm install\n# or: npm install / yarn install\n\n# Start development server\npnpm run dev\n# or: npm run dev\n\n# Run tests (see scripts below)\npnpm run test\n# or: npm run test\n\n# Build for production\npnpm run build\n# or: npm run build\n```\n\n### Experimental: SharedArrayBuffer-based physics (POC)\n\nAn experimental POC is available that uses SharedArrayBuffer + Atomics to run the per-ball physics simulation in a worker with zero-copy in-place buffers. This is intended to demonstrate potential latency and CPU improvements for high ball counts.\n\nNotes:\n\n- This feature requires cross-origin isolation (COOP/COEP). Use `VITE_ENABLE_COOP=1` when running the dev server.\n\n- Enable the POC via `VITE_ENABLE_SAB=1`.\n\nExample (macOS / Linux):\n\n```bash\nVITE_ENABLE_COOP=1 VITE_ENABLE_SAB=1 npm run dev\n```\n\nExample (Windows PowerShell):\n\n```powershell\n$Env:VITE_ENABLE_COOP = '1'; $Env:VITE_ENABLE_SAB = '1'; npm run dev\n```\n\nWhen enabled, `FrameManager` will attempt to initialize the SAB worker and use it; otherwise the system falls back to the transferable-worker path or single-threaded simulation.\n\nSee `docs/SHAREDARRAYBUFFER.md` for more details and caveats about cross-origin isolation and testing.\n\n## Testing\n\nThe repository uses Vitest for unit and integration tests. Useful scripts are available in `package.json` (run with `pnpm` / `npm`):\n\n```bash\n# Run tests (headless / default)\npnpm run test\n\n# Run tests once (CI-friendly)\npnpm run test:run\n\n# Run tests in watch mode\npnpm run test:watch\n\n# Open the Vitest UI\npnpm run test:ui\n\n# Run tests with coverage\npnpm run test:coverage\n\n# Rapier/physics smoke tests\npnpm run test:rapier-smoke\n```\n\nA few notable directories and docs:\n\n- `engine/rapier/` contains the Rapier runtime, helpers and physics integration used by the game.\n- `store/persistence/` contains rehydration and storage helpers used to persist game progress.\n- `systems/` contains core game systems such as brick behaviors and effect event handling.\n- `memory/` (top-level) stores design docs and task tracking used by contributors and agents.\n\n## Contributing \u0026 development notes\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines. This project enforces formatting and linting rules via Prettier and ESLint and uses TypeScript in strict mode — please run the following locally before opening PRs:\n\n```bash\npnpm run format      # Prettier\npnpm run lint        # ESLint\npnpm run typecheck   # TypeScript strict build\npnpm run test:run    # Run all tests once\n```\n\nPlease follow the repository's coding guidelines and the spec-driven workflow in `.github/instructions` when adding larger changes.\n\nThere are also end-to-end tests under `tests/e2e` and a number of Rapier-focused smoke/integration tests under `src/test/rapier`.\n\n## How to Play\n\n1. **Watch**: Balls automatically bounce around and break bricks\n2. **Earn Points**: Each brick destroyed awards points based on its layer\n3. **Upgrade**: Spend points on upgrades:\n   - ⚔️ **Ball Damage**: Increase damage per hit\n   - 💨 **Ball Speed**: Make balls move faster\n   - 🔮 **New Ball**: Add more balls (up to 20)\n4. **Progress**: When all bricks are destroyed, a new wave spawns\n\n5. **Prestige / Meta progression**: When you reach later waves you can choose to 'prestige' (ascend) for permanent meta bonuses that accelerate future runs.\n\n6. **Achievements \u0026 Save**: Complete challenges to unlock achievements. Progress is saved and rehydrated on load (localStorage key: `idle-bricks3d:game:v1`).\n\n## Controls\n\n- **Mouse Drag**: Rotate camera\n- **Scroll**: Zoom in/out\n- **Pause Button**: Pause/resume the game\n\n- **Keyboard**: Space toggles pause/resume; `U` upgrades ball damage (keyboard shortcuts are handled by useKeyboardShortcuts).\n- **Mobile / Touch**: Mobile-friendly UI and an upgrade drawer are available (see UI/MobileUpgrades for touch controls).\n\n## Project structure\n\nThe repository's `src/` layout is richer than earlier summaries — here's the current high-level structure.\n\n```text\nsrc/\n├── App.css\n├── App.tsx\n├── index.css\n├── main.tsx\n├── assets/                # Static assets and images\n├── components/            # UI and 3D scene components\n│   ├── Arena.tsx\n│   ├── Ball.tsx\n│   ├── BallsInstanced.tsx\n│   ├── Brick.tsx\n│   ├── GameScene.tsx\n│   ├── GeometricBackground.tsx\n│   ├── PerfOverlay.tsx\n│   ├── GameScene/         # Scene-layered components used by GameScene.tsx\n│   │   ├── ArenaLayer.tsx\n│   │   ├── BallsLayer.tsx\n│   │   ├── BricksLayer.tsx\n│   │   └── SceneSetup.tsx\n│   ├── bricks/            # Instanced bricks helpers\n│   │   ├── BricksInstanced.tsx\n│   │   └── useInstancedBricks.ts\n│   ├── effects/           # Visual effect components (particles, floating text, camera rig)\n│   │   ├── CameraRig.tsx\n│   │   ├── FloatingText.tsx\n│   │   └── ParticleSystem.tsx\n│   └── ui/                # HUD \u0026 UI controls\n│       ├── UI.tsx\n│       ├── UI.css\n│       ├── UpgradesPanel.tsx\n│       ├── ScorePanel.tsx\n│       └── SettingsPanel.tsx\n├── engine/                # Low-level engine helpers, physics \u0026 rapier integration\n│   ├── collision.ts\n│   ├── FrameManager.tsx\n│   ├── picking.ts\n│   └── rapier/            # rapier runtime and helpers\n│       ├── rapierInit.ts\n│       └── RapierPhysicsSystem.ts\n├── store/                 # Zustand stores and slices, persistence helpers\n│   ├── createStore.ts\n│   ├── gameStore.ts\n│   ├── persistence.ts\n│   ├── achievements.ts\n│   ├── constants.ts\n│   └── slices/\n│       ├── balls.ts\n│       └── progression/\n├── systems/               # Game systems and behaviors\n│   ├── brickBehaviors.ts\n│   ├── EffectEventBus.ts\n│   └── behaviors/\n└── test/                  # Unit \u0026 integration tests (vitest)\n   ├── gameStore.test.ts\n   └── (many other test files)\n\n```\n\n## Documentation\n\nEvery source file in this repository is fully documented with JSDoc/TSDoc comments.\nThese comments provide detailed information about the purpose, parameters, and return values of all public functions, components, and interfaces.\n\nKey areas to explore:\n\n- `src/store/`: Comprehensive state management documentation (Zustand slices).\n- `src/engine/`: Physics integration and simulation loop details.\n- `src/components/`: Component props and rendering behavior.\n- `src/systems/`: Event bus and game behavior systems.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeadronos%2Fvibe-idle-bricks3d","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeadronos%2Fvibe-idle-bricks3d","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeadronos%2Fvibe-idle-bricks3d/lists"}