3D Platformer Game

A dynamic 3D platformer game built with Three.js featuring random level generation, multiple enemy types, customizable settings, and a comprehensive leaderboard system.

Features

🎮 Gameplay

• 5 Progressive Levels with increasing difficulty
• Random Level Generation - every playthrough is unique
• Dynamic Lighting System - enemies emit light, levels get progressively darker
• 2-Hit Health System with visual feedback
• Jump-on-enemies combat mechanic
• Fireball Shooting with powerup system
• Shield Powerup with damage absorption
• Adjustable jump height for custom difficulty

🎯 Enemy Types

• Mobile Enemies - Track and chase the player
• Shooter Enemies - Fire projectiles at the player
• Flying Enemies - 3D movement with hovering behavior
• Teleporting Enemies - Randomly change positions

🏆 Progression System

• Scoring System with points for kills, powerups, and level completion
• SQLite Leaderboard with persistent high scores
• Save/Continue Game functionality
• Statistics Tracking (enemies killed, powerups collected, time played)

🎨 Customization

• Full Settings Menu with real-time configuration
• Customizable Colors for all game elements
• Lighting Controls (ambient, directional, enemy lights)
• Gameplay Settings (health, jump height, enemy spawn rates)
• 360° Skybox Support with fallback to solid colors

🖼️ Visual Features

• 3D Models Support with GLB loader and fallback geometry
• Particle Effects for explosions and impacts
• Dynamic Shadows and lighting
• Camera Following with smooth interpolation
• 360° Skybox support for immersive environments
• Modular code architecture for easy maintenance

Installation & Setup

Prerequisites

• Node.js (v14 or higher)
• npm

Quick Start

1. Clone or download the game files
2. Install dependencies:

   npm install

3. Start the server:

   npm start

4. Open your browser and navigate to http://localhost:3000

Development Mode

For development with auto-restart:

npm run dev

Optional: Add Custom Assets

• Place 3D models in models/ folder:
  • player.glb - Player character model
  • enemy1.glb - Mobile enemy model
  • enemy2.glb - Shooter enemy model
• Add skybox image to resources/sky.jpg for 360° environment

Controls

Key	Action
WASD or Arrow Keys	Move
Space	Jump
X	Shoot Fireball (when powerup active)

Game Mechanics

Level Progression

• Complete levels by killing all enemies and reaching the goal
• Platforms are randomly generated but always within jump reach
• Lighting gets darker as you progress through levels
• Enemy count increases with each level

Combat System

• Jump on enemies to kill them instantly
• Shoot fireballs when powerup is collected
• Take 2 hits before game over (or more with shield)
• Shield powerup absorbs damage and provides visual protection

Scoring

• Enemy Kills: 100 points (jump), 75 points (fireball)
• Powerup Collection: 50-75 points
• Level Completion: 200 × level number
• Game Completion: 1000 bonus points

Configuration

The game includes a comprehensive settings system accessible from the main menu:

Colors

• Sky colors (base and dark)
• Ground, goal, player, and enemy colors
• Powerup and particle effect colors

Lighting

• Ambient and directional light intensity
• Enemy and goal light distance
• Dynamic lighting effects

Gameplay

• Player and shield health
• Jump height adjustment
• Enemy spawn rates for different types

Skybox

• Toggle between 360° image and solid color
• Custom image path configuration

API Endpoints

The game includes a REST API for leaderboard functionality:

• GET /api/leaderboard - Retrieve top scores
• POST /api/leaderboard - Submit new score
• GET /api/player/:name/best - Get player's best score
• GET /api/stats - Game statistics
• GET /api/health - Server health check

File Structure

game/
├── index.html              # Main game page
├── package.json            # NPM dependencies
├── server.js              # Node.js server
├── scripts/               # Modular JavaScript files
│   ├── config.js          # Configuration system
│   ├── enemies.js         # Enemy management
│   ├── powerups.js        # Powerup system
│   ├── game.js            # Main game class
│   ├── gameLogic.js       # Core game mechanics
│   ├── gameActions.js     # Collision detection
│   ├── gameFlow.js        # Level progression
│   └── configUI.js        # Settings interface
├── styles/
│   └── style.css          # Game styling
├── models/                # 3D model assets (optional)
│   ├── player.glb
│   ├── enemy1.glb
│   └── enemy2.glb
├── resources/             # Skybox and other resources
│   └── sky.jpg           # 360° skybox image
└── database/              # SQLite database (auto-created)
    └── leaderboard.db

Technologies Used

• Three.js - 3D graphics and WebGL rendering
• Node.js & Express - Backend server
• SQLite - Database for leaderboards
• Vanilla JavaScript - Game logic and UI
• CSS3 - Styling and responsive design

Browser Compatibility

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Requires WebGL support for 3D rendering.

Troubleshooting

Game won't start

• Make sure Node.js is installed
• Run npm install to install dependencies
• Check that port 3000 is available

Buttons not working

• Check browser console for JavaScript errors
• Ensure all script files are loaded properly
• Try refreshing the page

Leaderboard not working

• Check browser console for errors
• Ensure server is running
• Verify SQLite database permissions

3D models not loading

• Check that GLB files are in the models/ folder
• Verify file names match exactly: player.glb, enemy1.glb, enemy2.glb
• Game will use fallback shapes if models are missing

Skybox not showing

• Ensure resources/sky.jpg exists
• Check that the image is a valid format
• Game will fallback to solid color if image fails to load

Contributing

Feel free to contribute to this project by:

• Adding new enemy types or mechanics
• Improving the 3D models and assets
• Enhancing the visual effects
• Optimizing performance
• Adding new features

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

• Built with Three.js
• Uses Express.js for server functionality
• SQLite for data persistence