Feature/Refactor to use ecs architecture (#14)

Reviewed-on: #14
Co-authored-by: Juan Sebastian Montoya <juansmm@outlook.com>
Co-committed-by: Juan Sebastian Montoya <juansmm@outlook.com>

README.md

@@ -1,15 +1,28 @@
 # 3D Coin Collector Game
 
-A fun and engaging 3D game built with Three.js where you control a player to collect coins while avoiding obstacles. Test your reflexes and see how high you can score!
+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
+- **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
@@ -18,6 +31,14 @@ Navigate your character (a blue cube) through a 3D arena to collect golden coins
 - **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
@@ -64,23 +85,41 @@ Navigate your character (a blue cube) through a 3D arena to collect golden coins
 ## 🛠️ Technical Details
 
 ### Built With
-- **Three.js r128**: 3D graphics library
-- **Vanilla JavaScript**: No frameworks required
+- **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
 
-### Game Architecture
-- **Object-Oriented Design**: Uses ES6 classes with inheritance
-- **GameObject Base Class**: Common functionality for all game entities
-- **Modular Classes**: Player, Coin, and Obstacle extend GameObject
-- **Game Loop**: Smooth 60 FPS animation using requestAnimationFrame
+### 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
 
-### Features Implementation
-- **Shadow Mapping**: PCF soft shadows for realistic lighting
-- **Fog Effect**: Atmospheric depth with distance fog
-- **Collision Detection**: Distance-based collision system
-- **Boundary Constraints**: Prevents player and obstacles from leaving the arena
-- **Touch Event Handling**: Full support for multi-touch devices
 
 ## 📋 Requirements
 
@@ -88,27 +127,53 @@ Navigate your character (a blue cube) through a 3D arena to collect golden coins
 - JavaScript enabled
 - Internet connection (for Three.js CDN)
 
+
 ## 🚀 Getting Started
 
-1. **Clone or Download** this repository
-2. **Open** `index.html` in your web browser
-3. **Start Playing** immediately - no installation required!
-
-### Local Server (Optional)
-For best performance, you can run a local server:
+### Development
 
+1. **Clone the repository**
 ```bash
-# Using Python 3
-python -m http.server 8000
-
-# Using Python 2
-python -m SimpleHTTPServer 8000
-
-# Using Node.js (with http-server)
-npx http-server
+git clone <repository-url>
+cd threejs-test
 ```
 
-Then open `http://localhost:8000` in your browser.
+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