# cube-world

**Repository Path**: jerryzu/cube-world

## Basic Information

- **Project Name**: cube-world
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cube World

## Table of Contents

* [About](#about)
* [Features](#features)
* [Live Demo](#live-demo)
* [Screenshots](#screenshots)
* [Prerequisites](#prerequisites)
* [Running Locally](#running-locally)
* [Controls](#controls)
* [How It Works](#how-it-works)
* [Tech Stack](#tech-stack)
* [Contributing](#contributing)
* [License](#license)

![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)
![Three.js](https://img.shields.io/badge/Three.js-000000?logo=three.js&logoColor=white)
![Vite](https://img.shields.io/badge/Vite-646CFF?logo=vite&logoColor=white)
![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)

## About

Cube World is a procedurally generated 3D driving experience on the surface of a cube. A tiny car navigates an interconnected road network that spans all six faces, while periodic slice rotations instantly rearrange tiles between faces, reshaping the world around it.

Built with [Three.js](https://threejs.org/) and TypeScript. Runs entirely in the browser — no server required.

[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://buymeacoffee.com/probello3)

## Features

- **Multi-Face Road Network** — Procedurally generated roads that wrap seamlessly across all 6 cube faces
- **Slice Rotations** — Periodic rotations instantly move rows/columns of tiles between faces, rearranging the world while the car drives
- **Day/Night Cycle** — Dynamic lighting with sunrise, sunset, street lights, and glowing windows
- **Multiple Camera Modes** — Follow cam, top-down, cinematic, and hood cam with air freshener
- **Destination System** — Visit POI markers scattered across the cube for points
- **Ambient Audio** — Engine sounds, wind, and environmental audio
- **Crash & Reset** — Landing on a non-road tile after a rotation triggers a particle burst, a brief tumble animation, and a full world regeneration
- **Rich Scenery** — Buildings, houses, schools, parks, farms, ponds with ducks, cemeteries with ghosts, construction sites, golf courses, and more
- **Smart Building Orientation** — Buildings and schools face adjacent roads automatically
- **Particle Effects** — Chimney smoke, fountain spray, and atmospheric particles
- **Traffic Lights & Stop Signs** — Functional intersection decorations
- **People & Pedestrians** — Tiny people populate the world
- **Mobile Friendly** — Touch controls, responsive UI, collapsible control panel
- **PWA Ready** — Installable as a progressive web app

## Live Demo

**🎮 [Play Cube World](https://paulrobello.github.io/cube-world/)**

## Screenshots

| Day Mode | Scenery | Night Mode |
|----------|---------|------------|
| ![Day Overview](https://raw.githubusercontent.com/paulrobello/cube-world/main/screenshots/day-overview.png) | ![Day Scenery](https://raw.githubusercontent.com/paulrobello/cube-world/main/screenshots/day-scenery.png) | ![Night Mode](https://raw.githubusercontent.com/paulrobello/cube-world/main/screenshots/night-mode.png) |

## Prerequisites

- [Node.js](https://nodejs.org/) 18+ (for local development)

## Running Locally

```bash
# Clone the repository
git clone https://github.com/paulrobello/cube-world.git
cd cube-world

# Install dependencies
npm install

# Start dev server
npm run dev

# Build for production
npm run build
```

## Controls

### Desktop
| Input | Action |
|-------|--------|
| Drag | Rotate camera (when paused) |
| Scroll | Zoom |
| Double-click | Regenerate world |
| Space | Pause / Resume |
| D | Toggle debug labels |

### Mobile
| Input | Action |
|-------|--------|
| Drag | Rotate camera (when paused) |
| Pinch | Zoom |
| Double-tap | Regenerate world |

### Control Panel
| Button | Function |
|--------|----------|
| 🔄 Cycle / ☀️ Day / 🌙 Night | Day/night mode |
| 📷 Follow / 🔽 Top-Down / 🎬 Cinematic / 🚗 Hood | Camera mode |
| ⏸️ Pause / ▶️ Resume | Pause simulation |
| 🔀 Regenerate World | New random world |
| 🔊 Sound / ❌ Sound | Toggle audio |
| 🌲 Freshener / ❌ Freshener | Toggle hood cam air freshener |
| 📍 POI Markers / ❌ POI Markers | Toggle destination markers |

All preferences are saved to localStorage.

## How It Works

1. **Road Generation** — A path-finding algorithm creates a connected road network that snakes across multiple cube faces, using adjacency rules for seamless face-to-face transitions
2. **Tile Classification** — Road tiles are classified as straight, turn, T-junction, or crossroads based on entry/exit directions
3. **Scenery Placement** — Non-road tiles are filled with randomized scenery (buildings, parks, farms, etc.) that automatically orient to face adjacent roads
4. **Car Navigation** — The car follows the road path, wrapping between cube faces with smooth orientation transitions
5. **Slice Rotations** — Periodic rotations instantly move rows/columns of tiles between faces, adjusting tile orientations, building facing directions, and the car's position and heading as needed
6. **Crash Detection** — After each rotation, the car checks if it's still on a road tile; if not, a particle burst fires, the cube spins briefly as a visual reset cue, and the world regenerates from scratch

## Tech Stack

| Component | Technology |
|-----------|------------|
| 3D Engine | [Three.js](https://threejs.org/) r183 |
| Language | TypeScript 5.9 |
| Bundler | [Vite](https://vitejs.dev/) 7 |
| Deployment | GitHub Pages (CI/CD) |

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see [LICENSE](LICENSE) for details.

---

*Created by [Paul Robello](https://github.com/paulrobello)*