threejs-test/README.md

# 3D Coin Collector Game

A fun and engaging 3D game built with **Three.js** and **Entity Component System (ECS)** architecture. Test your reflexes as you collect coins while avoiding obstacles!

## 🎮 Game Overview

Navigate your character (a blue cube) through a 3D arena to collect golden coins while avoiding dangerous red obstacles. Each coin collected increases your score, but colliding with obstacles reduces your health. The game ends when your health reaches zero.

## 🏗️ Architecture

This game is built using the **Entity Component System (ECS)** pattern, making it highly scalable and maintainable. See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed documentation.

### Why ECS?

- **Scalable**: Easily add new features without modifying existing code
- **Performant**: Data-oriented design for better cache utilization
- **Flexible**: Mix and match components to create new entity types
- **Maintainable**: Clean separation of data (components) and logic (systems)
- **Testable**: Systems can be tested independently

## ✨ Features

### Game Features
- **3D Graphics**: Beautiful 3D environment with shadows, lighting, and fog effects
- **Smooth Controls**: Responsive keyboard and touch controls with easing
- **Dynamic Gameplay**: Moving obstacles that bounce off boundaries
- **Animated Coins**: Coins rotate and float with smooth animations
- **Health System**: Start with 100 health, lose 1 point per obstacle collision
- **Score Tracking**: Earn 10 points for each coin collected
- **Camera Follow**: Third-person camera that follows your player
- **Mobile Support**: Full touch control support for smartphones and tablets
- **Responsive Design**: Adapts to different screen sizes

### Technical Features
- **ECS Architecture**: Scalable entity component system
- **Zero Dependencies**: No npm packages, no build step, no bullshit
- **Native ES6 Modules**: Modern JavaScript, works directly in browsers
- **CDN-based**: Three.js loaded from CDN
- **Docker Support**: Simple nginx deployment
- **CI/CD**: Automated versioning and deployment pipeline

## 🎯 How to Play

1. **Objective**: Collect as many yellow coins as possible while avoiding red obstacles
2. **Scoring**: Each coin collected gives you 10 points
3. **Health**: You start with 100 health. Each collision with a red obstacle reduces health by 1
4. **Game Over**: When your health reaches 0, the game ends and displays your final score
5. **Restart**: Click "Play Again" to start a new game

## 🕹️ Controls

### Desktop
- **W** or **↑ Arrow Key**: Move forward
- **S** or **↓ Arrow Key**: Move backward
- **A** or **← Arrow Key**: Move left
- **D** or **→ Arrow Key**: Move right

### Mobile/Touch Devices
- **Touch and Drag**: Touch anywhere on the screen and drag to move your character
  - Drag up to move forward
  - Drag down to move backward
  - Drag left to move left
  - Drag right to move right
  - Movement is relative to the center of the screen

## 🎨 Game Elements

### Player
- **Appearance**: Blue cube with metallic material
- **Behavior**: Rotates while moving, stays within arena boundaries
- **Collision**: Pushed back when hitting obstacles

### Coins
- **Appearance**: Golden spheres with emissive glow
- **Behavior**: Rotate continuously and float up and down
- **Value**: 10 points each
- **Respawn**: A new coin spawns immediately after collection

### Obstacles
- **Appearance**: Red-orange boxes
- **Behavior**: Move randomly and bounce off arena boundaries
- **Damage**: -1 health per collision
- **Avoidance**: Stay away to preserve your health!

## 🛠️ Technical Details

### Built With
- **Three.js**: 3D graphics library (from CDN)
- **Native ES6 Modules**: No bundler needed
- **HTML5 Canvas**: WebGL rendering
- **CSS3**: Modern styling and responsive design
- **Pure JavaScript**: No frameworks, no dependencies

### ECS Architecture

```
├── src/
│   ├── ecs/              # Core ECS implementation
│   ├── components/       # Data containers (Transform, Velocity, etc.)
│   ├── systems/          # Logic processors (Movement, Collision, etc.)
│   ├── game/            # Game-specific code
│   └── main.js          # Entry point
```

**Components (Data)**:
- `Transform`: Position, rotation, scale
- `Velocity`: Movement speed with easing
- `MeshComponent`: Three.js mesh reference
- `Collidable`: Collision detection data
- `Health`: Hit points
- `Tags`: Entity type markers (Player, Coin, Obstacle)

**Systems (Logic)**:
- `InputSystem`: Keyboard and touch input
- `PlayerControlSystem`: Player movement with easing
- `MovementSystem`: Apply velocity to position
- `CollisionSystem`: Detect and handle collisions
- `CoinSystem`: Coin rotation and bobbing
- `ObstacleSystem`: Obstacle movement and bouncing
- `BoundarySystem`: Keep entities in bounds
- `RenderSystem`: Sync Three.js with ECS


## 📋 Requirements

- Modern web browser with WebGL support (Chrome, Firefox, Safari, Edge)
- JavaScript enabled
- Internet connection (for Three.js CDN)


## 🚀 Getting Started

### Development

1. **Clone the repository**
```bash
git clone <repository-url>
cd threejs-test
```

2. **Open in browser**

Uuse a simple HTTP server:

```bash
# Option 1: Python
python -m http.server 3000

# Option 2: Node (if you have it)
npx serve .

# Option 3: PHP
php -S localhost:3000
```

Then navigate to `http://localhost:3000`

**That's it!** The game uses:
- Native ES6 modules (no bundler needed)
- Three.js from CDN (no npm install)

### Docker

Build and run with Docker:
```bash
# Build
docker build -t threejs-game .

# Run
docker run -p 80:80 threejs-game
```

Or use docker-compose:
```bash
docker-compose up
```

## 📱 Mobile Compatibility

The game is fully optimized for mobile devices:
- Touch controls work on all touch-enabled devices
- Responsive UI that adapts to screen size
- Optimized performance for mobile browsers
- No joystick clutter - clean touch interface

## 🎮 Game Mechanics

### Movement
- Player moves at a constant speed of 0.15 units per frame
- Movement is constrained within the 30x30 arena
- Player rotates while moving for visual feedback

### Coin Collection
- Coins spawn randomly across the arena
- 10 coins are present at the start
- New coins spawn immediately after collection
- Coins have a collision radius of 0.8 units

### Obstacle Behavior
- 8 obstacles spawn at game start
- Each obstacle moves in a random direction
- Obstacles bounce off arena boundaries
- Obstacles have a collision radius of 1.5 units
- Spawn away from player's starting position

### Camera System
- Third-person camera follows the player
- Camera positioned 15 units behind the player
- Always looks at the player position
- Smooth camera movement

## 🏆 Tips for High Scores

1. **Stay Mobile**: Keep moving to avoid obstacles
2. **Plan Your Route**: Look ahead to plan coin collection paths
3. **Avoid Corners**: Obstacles can trap you in corners
4. **Watch Your Health**: Health is displayed in the top-left corner
5. **Practice**: The more you play, the better you'll get at avoiding obstacles!

## 🐛 Known Issues

None at the moment! If you encounter any issues, please report them.

## 📝 License

This project is open source and available for educational purposes.

## 🙏 Acknowledgments

- Three.js community for the excellent 3D library
- Built as a learning project for 3D web game development

---

**Enjoy the game and try to beat your high score!** 🎉