Juan Sebastian Montoya
dfe87d63cc
# Add Touch Support and Documentation ## 📋 Summary This PR adds comprehensive touch support for mobile devices and tablets, enabling players to control the game using touch gestures. Additionally, a complete README.md file has been added to document the game features, controls, and gameplay mechanics. ## 🎯 Changes Made ### ✨ New Features - **Touch Controls**: Full touch support for smartphones and tablets - Touch and drag anywhere on the screen to move the player - Movement direction calculated relative to screen center - Smooth, responsive touch input handling - Multi-touch support with proper touch ID tracking - **Documentation**: Comprehensive README.md - Game overview and features - Detailed controls (keyboard and touch) - Game mechanics explanation - Technical details and architecture - Getting started guide - Tips for high scores ### 🔧 Technical Implementation #### Touch Event Handling - Added touch event listeners (`touchstart`, `touchmove`, `touchend`, `touchcancel`) - Implemented touch position tracking relative to screen center - Converted touch input to WASD key states for seamless integration - Proper touch ID tracking to handle multiple simultaneous touches - Touch movement threshold (10px) to prevent accidental movements #### Code Structure - Added touch-related properties to `Game` class: - `touchActive`, `touchStartX/Y`, `touchCurrentX/Y`, `touchId` - New methods: - `setupTouchControls()`: Initializes touch event listeners - `handleTouchStart()`: Handles touch initiation - `handleTouchMove()`: Updates touch position during drag - `handleTouchEnd()`: Resets touch state - `updateTouchMovement()`: Converts touch input to movement keys #### UI Updates - Updated instructions to mention touch controls - Responsive design maintained for mobile devices ## 📊 Statistics - **Files Changed**: 2 - `index.html`: +123 lines, -1 line - `README.md`: +171 lines (new file) - **Total Changes**: +293 insertions, -1 deletion - **Commits**: 2 ## 🧪 Testing ### Desktop Testing - ✅ Keyboard controls (WASD and Arrow Keys) still work correctly - ✅ No regression in existing functionality - ✅ Game performance unchanged ### Mobile Testing - ✅ Touch controls work on smartphones - ✅ Touch controls work on tablets - ✅ Movement is smooth and responsive - ✅ Touch input properly resets on touch end - ✅ Multiple touches handled correctly (only first touch tracked) ## 📱 Mobile Compatibility The game now fully supports: - iOS devices (iPhone, iPad) - Android devices (phones and tablets) - Other touch-enabled devices Touch controls use the center of the screen as a reference point, making it intuitive for users to drag in any direction to move. ## 🎮 User Experience Improvements 1. **Accessibility**: Game is now playable on mobile devices without keyboard 2. **Intuitive Controls**: Touch and drag is natural for mobile users 3. **Documentation**: README provides clear instructions for all users 4. **No Visual Clutter**: Touch controls work without on-screen joystick ## 🔍 Code Quality - Clean, maintainable code structure - Proper event handling with `preventDefault()` to avoid browser defaults - Touch events use `{ passive: false }` for proper scroll prevention - Consistent with existing code style and patterns - No breaking changes to existing functionality ## 📝 Notes - Touch controls integrate seamlessly with existing keyboard controls - Both input methods can work simultaneously (though not recommended) - Touch movement uses the same movement system as keyboard input - README includes comprehensive documentation for future developers ## ✅ Checklist - [x] Touch controls implemented and tested - [x] Mobile compatibility verified - [x] README.md created with comprehensive documentation - [x] No regression in desktop functionality - [x] Code follows existing patterns and style - [x] Instructions updated to mention touch controls --- **Ready for Review** 🚀 Reviewed-on: #4 Co-authored-by: Juan Sebastian Montoya <juansmm@outlook.com> Co-committed-by: Juan Sebastian Montoya <juansmm@outlook.com>
171 lines
5.8 KiB
Markdown
171 lines
5.8 KiB
Markdown
# 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!
|
|
|
|
## 🎮 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.
|
|
|
|
## ✨ Features
|
|
|
|
- **3D Graphics**: Beautiful 3D environment with shadows, lighting, and fog effects
|
|
- **Smooth Controls**: Responsive keyboard and touch controls
|
|
- **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
|
|
|
|
## 🎯 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 r128**: 3D graphics library
|
|
- **Vanilla JavaScript**: No frameworks required
|
|
- **HTML5 Canvas**: WebGL rendering
|
|
- **CSS3**: Modern styling and responsive design
|
|
|
|
### 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
|
|
|
|
### 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
|
|
|
|
- Modern web browser with WebGL support (Chrome, Firefox, Safari, Edge)
|
|
- 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:
|
|
|
|
```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
|
|
```
|
|
|
|
Then open `http://localhost:8000` in your browser.
|
|
|
|
## 📱 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!** 🎉
|
|
|