GeoJSON Platformer - Action RPG Based on Real-World Trips

An innovative multiplayer action-RPG platformer where levels are generated from GeoJSON data representing real-world trips. Transform your travels into playable adventures!

🎮 Features

Authentication & Characters

• Google OAuth Login: Secure authentication via Google account
• Multi-Character System: Each player can create up to 3 unique characters
• Character Progression: Each character has independent stats, inventory, and progress
• Character Switching: Easily switch between your characters

Core Gameplay

• Action-RPG Platformer: Side-scrolling platformer with combat, NPCs, and item collection
• GeoJSON-Based Levels: Levels generated from real-world trip data (hiking routes, travel paths, etc.)
• Combat System:
  • Simple slash attacks for basic enemies
  • Magic spells with elemental requirements for special foes
  • Different enemy types: slashable, magical, armored, flying, bosses
• Multiplayer: Real-time multiplayer using WebSockets and MQTT
• Morality System: Killing NPCs increases "evil points"
• Economy: Collect gold, silver, and copper coins
• Buildings: Inns for rest, shops for trading, and special locations

Level Design

• Dynamic Generation: Coordinates from GeoJSON become platform positions
• Contextual Entities: Properties define enemies, NPCs, buildings, and collectibles
• Duration-Based: Short trips (5 min), long trips (15-20 min), or split multi-level journeys
• Themes: Forest, desert, mountain, snow, and more

Technical Stack

• Backend: Django with REST API
• Frontend: Phaser.js game engine with TypeScript
• Real-time: WebSockets (Django Channels) + MQTT
• Data: GeoJSON for trip definitions
• Rendering: HTML divs (replaceable with PNG sprites)

🏗️ Project Structure

browser-platformer/
├── backend/                          # Django backend
│   ├── geojson_platformer/          # Django project
│   │   ├── settings.py              # Configuration
│   │   ├── urls.py                  # URL routing
│   │   └── asgi.py                  # ASGI config for WebSockets
│   ├── game/                        # Main game app
│   │   ├── models.py                # Database models
│   │   ├── views.py                 # API endpoints
│   │   ├── serializers.py           # REST serializers
│   │   ├── admin.py                 # Django admin config
│   │   ├── geojson_processor.py     # GeoJSON → Levels converter
│   │   ├── mqtt_client.py           # MQTT integration
│   │   ├── consumers.py             # WebSocket handlers
│   │   └── fixtures/                # Sample data
│   ├── requirements.txt             # Python dependencies
│   └── manage.py                    # Django management
├── frontend/                        # Phaser.js frontend
│   ├── src/
│   │   ├── main.ts                  # Entry point
│   │   ├── scenes/
│   │   │   └── GameScene.ts         # Main game scene
│   │   ├── entities/
│   │   │   ├── Player.ts            # Player character
│   │   │   ├── Enemy.ts             # Enemy entities
│   │   │   ├── NPC.ts               # Non-player characters
│   │   │   └── Collectible.ts       # Coins and items
│   │   ├── services/
│   │   │   ├── api.ts               # Backend API client
│   │   │   └── websocket.ts         # WebSocket client
│   │   └── ui/
│   │       └── UIManager.ts         # UI overlay management
│   ├── index.html                   # HTML entry
│   ├── package.json                 # NPM dependencies
│   └── vite.config.ts               # Vite configuration
└── sample_trips/                    # Example GeoJSON trips
    ├── mountain_journey.geojson     # Mountain pass adventure
    ├── forest_path.geojson          # Forest trail
    └── desert_expedition.geojson    # Desert caravan route

📋 Prerequisites

• Python 3.10+
• Node.js 18+
• npm or yarn
• Google Cloud account (for OAuth - free)
• (Optional) MQTT broker (e.g., Mosquitto) for multiplayer

🚀 Quick Start

1. Backend Setup

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy environment file and configure Google OAuth
cp .env.example .env
# Edit .env and add your Google OAuth credentials
# See GOOGLE_OAUTH_SETUP.md for detailed instructions

# Run migrations
python manage.py makemigrations
python manage.py migrate

# Load sample data (enemies, NPCs, items)
python manage.py loaddata game/fixtures/sample_data.json

# Create demo trips from GeoJSON
python setup_demo.py

# Create superuser (for admin access)
python manage.py createsuperuser

# Run server
python manage.py runserver

The backend will be available at http://localhost:8000

Important: You must configure Google OAuth to use the game. See GOOGLE_OAUTH_SETUP.md for instructions.

2. Frontend Setup

cd frontend

# Install dependencies
npm install

# Run development server
npm run dev

The game will be available at http://localhost:3000

🎯 How to Play

Getting Started

1. Login: Click "Sign in with Google" to authenticate
2. Create Character: Create your first character (you can have up to 3)
3. Select Character: Choose which character to play
4. Pick a Trip: Select from available GeoJSON-based journeys
5. Start Adventure: Begin your journey!

Controls

• Arrow Keys: Move left/right
• Space: Jump
• Z: Slash attack (melee)
• X: Magic spell (costs mana)
• C: Interact with NPCs

Character Management

• Create Characters: Up to 3 characters per Google account
• Switch Characters: Return to character select to change characters
• Independent Progress: Each character has separate stats, inventory, and progression
• Delete Characters: Remove unwanted characters to make room for new ones

Game Mechanics

1. Navigate Platforms: Jump across platforms generated from trip coordinates
2. Combat Enemies: Use slash attacks or magic based on enemy type
3. Collect Coins: Gather gold, silver, and copper
4. Interact with NPCs: Talk to merchants, innkeepers, and quest givers
5. Visit Buildings: Rest at inns, trade at shops
6. Complete the Journey: Reach the end of the level
7. Track Progress: Your character's progress is automatically saved

Enemy Types

• Slashable: Defeated with basic attacks
• Magical: Require magic spells
• Armored: High defense, take reduced damage
• Flying: Airborne enemies
• Boss: Powerful end-level challenges

📊 Database Models

Core Models

• Player: Character stats, inventory, currency, morality (max 3 per user)
  • Fields: user (ForeignKey), character_slot (1-3), is_active
• Trip: GeoJSON data, difficulty, theme, duration
• Level: Generated level segments with platform data
• Enemy: Enemy templates with stats and weaknesses
• NPC: Non-combatant characters with dialogue
• Building: Inns, shops, towers, etc.
• Item: Weapons, armor, potions, spells
• PlayerInventory: Player's collected items (per character)
• LevelInstance: Active multiplayer sessions
• LevelProgress: Player completion tracking (per character)

🗺️ Creating Custom Trips

GeoJSON Format

Create a GeoJSON file with:

{
  "type": "Feature",
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [longitude, latitude],
      [longitude, latitude],
      ...
    ]
  },
  "properties": {
    "name": "Your Trip Name",
    "description": "Description",
    "difficulty": "easy|medium|hard|expert",
    "estimated_duration": 10,
    "theme": "forest|desert|mountain|snow",
    "background_story": "Your story here",
    "enemy_distribution": {
      "slashable": 50,
      "magical": 30,
      "armored": 15,
      "flying": 5
    },
    "npc_encounters": [
      {
        "type": "merchant",
        "location_index": 3,
        "name": "Trader Bob"
      }
    ],
    "buildings": [
      {
        "type": "inn",
        "location_index": 5,
        "name": "Rest Stop"
      }
    ]
  }
}

Loading Your Trip

1. Upload via Django Admin:

   • Navigate to http://localhost:8000/admin
   • Go to Trips → Add Trip
   • Paste your GeoJSON data
   • Fill in metadata
   • Save

2. Generate Levels:

   • In admin, select your trip
   • Click "Generate Levels" action
   • Levels will be created automatically

3. Or via API:

   curl -X POST http://localhost:8000/api/trips/ \
     -H "Content-Type: application/json" \
     -d @your_trip.geojson
   
   curl -X POST http://localhost:8000/api/trips/{id}/generate_levels/

🔧 API Endpoints

Authentication

• POST /api/auth/google/login/ - Initiate Google OAuth
• POST /api/auth/logout/ - Logout user
• GET /api/user/me/ - Get current user info

Character Management

• GET /api/characters/ - List user's characters (max 3)
• GET /api/characters/active/ - Get active character
• POST /api/characters/create/ - Create new character
• POST /api/characters/{id}/activate/ - Set active character
• DELETE /api/characters/{id}/delete/ - Delete character

Trips

• GET /api/trips/ - List all trips
• GET /api/trips/{id}/ - Get trip details
• POST /api/trips/ - Create new trip (requires auth)
• POST /api/trips/{id}/generate_levels/ - Generate levels

Levels

• GET /api/levels/ - List levels
• GET /api/levels/{id}/ - Get level details
• POST /api/levels/{id}/start_instance/ - Start multiplayer instance

Players

• GET /api/players/ - List players
• GET /api/players/{id}/ - Get player details
• POST /api/players/{id}/rest/ - Rest (restore health/mana)
• POST /api/players/{id}/add_currency/ - Add coins
• GET /api/players/{id}/inventory/ - Get inventory

Game Data

• GET /api/enemies/ - List enemy templates
• GET /api/npcs/ - List NPCs
• GET /api/items/ - List items
• GET /api/buildings/ - List buildings

Note: Most endpoints require authentication via JWT token.

🌐 Multiplayer Setup

Using WebSockets (Built-in)

WebSockets are configured by default via Django Channels. Multiple players can join the same level instance.

Using MQTT (Optional)

For advanced multiplayer with external MQTT broker:

1. Install MQTT Broker:

   # macOS
   brew install mosquitto
   brew services start mosquitto
   
   # Ubuntu/Debian
   sudo apt-get install mosquitto
   sudo systemctl start mosquitto

2. Configure Backend: Edit .env:

   MQTT_BROKER_HOST=localhost
   MQTT_BROKER_PORT=1883
   

3. Enable MQTT in Django: Uncomment in game/apps.py:

   from .mqtt_client import mqtt_client
   mqtt_client.connect()

🎨 Customization

Replacing Divs with Sprites

Currently, entities are rendered as colored divs. To use PNG sprites:

1. Add assets to frontend:

   frontend/public/assets/
   ├── player.png
   ├── enemy_slime.png
   ├── npc_merchant.png
   └── platforms/
   

2. Update entity classes: In Player.ts, Enemy.ts, etc., replace:

   this.sprite = scene.add.rectangle(x, y, 30, 40, 0x00FF00);

   With:

   this.sprite = scene.add.sprite(x, y, 'player');

3. Preload assets: In GameScene.ts preload():

   this.load.image('player', 'assets/player.png');

Adding New Enemy Types

1. Create in Django admin or via API
2. Update Enemy.ts color mapping
3. Add to level generator in geojson_processor.py

🧪 Development

Run Tests

# Backend
cd backend
python manage.py test

# Frontend
cd frontend
npm test

Code Structure

• Backend: Follow Django best practices
• Frontend: TypeScript with Phaser.js patterns
• GeoJSON Processing: geojson_processor.py handles conversion logic

📝 Future Enhancements

• Boss battles at level ends
• Quest system with objectives
• Crafting system
• Player-to-player trading
• Leaderboards
• Mobile support
• Real sprite assets
• Sound effects and music
• Save/load system
• Achievement system

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📜 License

MIT License - feel free to use this project for learning, experimentation, or building your own trip-based games!

🆘 Troubleshooting

Backend won't start

• Check Python version (3.10+)
• Ensure virtual environment is activated
• Run migrations: python manage.py migrate

Frontend won't start

• Check Node version (18+)
• Clear node_modules: rm -rf node_modules && npm install
• Check if backend is running on port 8000

No trips showing

• Run python setup_demo.py to load sample data
• Check Django admin for trips
• Ensure is_active=True on trips

WebSocket connection fails

• Ensure Django Channels is installed
• Check that ASGI application is configured
• Verify WebSocket URL in browser console

📧 Support

For questions or issues, please open a GitHub issue or contact the development team.

---

Transform your real-world adventures into epic platformer journeys! 🗺️🎮