A horror clown maze game built with React, Three.js, and React Three Fiber. Trapped in Beppo's nightmare circus tent labyrinth, navigate to escape before your sanity runs out.
Live Demo: https://arcade-cabinet.github.io/Beppo-Laughs/
- Frontend Framework: React 19 + TypeScript
- Build Tool: Astro 5 (wraps Vite internally)
- 3D Graphics: Three.js + React Three Fiber
- Routing: Wouter
- State Management: Zustand
- Styling: Tailwind CSS 4
- Testing: Vitest + Playwright
- Linting: Biome
- Node.js 24.x (specified in
.nvmrc) - pnpm 10.12.1+
# Install dependencies
pnpm install
# Run development server
pnpm run devThe app will be available at http://localhost:5000
# Build for production
pnpm run build
# Build outputs to dist/# Run unit tests
pnpm run test
# Run with coverage
pnpm run test:coverage
# Watch mode
pnpm run test:watch# Run E2E tests
pnpm run test:e2e
# Run E2E tests in UI mode
pnpm run test:e2e:ui# Check code quality
pnpm run lint
# Auto-fix issues
pnpm run lint:fix- Fear (Red): Increases when exploring unknown areas
- Despair (Blue): Increases when backtracking through known areas
- Dynamic sanity meters affecting visual effects
- SDF-based villain rendering
- Procedurally generated maze from seed
- Blockades requiring collected items to pass
- Multiple endings based on sanity levels
- Desktop: Mouse-controlled lever to accelerate/brake
- Mobile: Touch controls with lever and directional buttons
- Navigation: Choose direction at junctions
The project is automatically deployed to GitHub Pages via GitHub Actions when changes are pushed to the main branch.
- Code is pushed to
main - CI runs tests and builds the project with
VITE_BASE_PATH=/Beppo-Laughs - Build artifacts are uploaded to GitHub Pages
- Site is live at
https://arcade-cabinet.github.io/Beppo-Laughs/
See docs/GITHUB_PAGES_FIX.md for detailed deployment configuration.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- All code must pass Biome linting
- Unit tests should be added for new features
- E2E tests should cover critical user paths
- Type checking must pass (some pre-existing errors are known)
- GitHub Pages Deployment Fix - Routing configuration for subpath deployment
- Vision Document - Game design and horror mechanics
- Architecture - Technical architecture details
- Agents Guide - Guide for AI development agents
Beppo Laughs is a first-person horror maze game where:
- You're trapped in a circus tent labyrinth
- Your sanity depletes as you explore (fear) and backtrack (despair)
- Villains create blockades that require specific items to pass
- Find the exit before losing your sanity
- Each playthrough is unique based on the seed
MIT License - see LICENSE file for details
- Three.js and React Three Fiber communities
- Playwright for E2E testing
- Biome for ultra-fast linting