Quick Start Guide

Get Empire Builder up and running in just a few minutes!

Prerequisites

Before you begin, ensure you have:

  • Python 3.11 or higher installed

  • Git for cloning the repository

  • Internet connection for Supabase integration

  • A Supabase account (free tier available)

Step 1: Installation

  1. Clone the Repository

    git clone https://github.com/logan-code-del/empire-builder-game.git
cd empire-builder-game

  2. Install Dependencies

    pip install -r requirements.txt

    This installs all required packages including Flask, Supabase client, and other dependencies.

Step 2: Supabase Setup

  1. Create a Supabase Project

    • Go to https://supabase.com

    • Sign up for a free account

    • Create a new project

    • Wait for the project to be ready (usually 1-2 minutes)

  2. Get Your Credentials

    From your Supabase dashboard: - Go to Settings → API - Copy your Project URL - Copy your anon/public key - Copy your service_role key

  3. Set Up Database Schema

    In your Supabase dashboard: - Go to SQL Editor - Run the schema from supabase_auth_schema_uuid.sql

    -- This creates the necessary tables for users, empires, battles, etc.
-- The file contains all required table definitions

Step 3: Configuration

  1. Create Environment File

    Copy the template and add your credentials:

    cp .env.template .env

  2. Edit .env File

    Open .env in your text editor and add your Supabase credentials:

    # Supabase Configuration
SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_ANON_KEY=your-anon-key-here
SUPABASE_SERVICE_KEY=your-service-key-here
SECRET_KEY=your-flask-secret-key-here

    Important: Replace the placeholder values with your actual Supabase credentials.

Step 4: Launch the Game

  1. Start the Server

    python app_supabase.py

    You should see output similar to:

    Supabase connected successfully
* Running on http://127.0.0.1:5000
* Debug mode: on

  2. Open Your Browser

    Navigate to: http://localhost:5000

  3. Create Your Account

    • Click “Register” to create a new account

    • Fill in username, email, and password

    • Click “Create Account”

  4. Start Playing!

    • Log in with your new account

    • Create your first empire

    • Begin building and expanding

First Steps in the Game

Once you’re logged in and have created an empire:

  1. Build Your First City - Click “Build City” on the dashboard - Choose a location on the map - Start with basic buildings (houses, farms)

  2. Manage Resources - Monitor your gold, food, and materials - Build resource-generating buildings - Balance production and consumption

  3. Train Units - Build military buildings (barracks, stables) - Train basic units (soldiers, archers) - Prepare for defense and expansion

  4. Explore Multiplayer - View other players on the leaderboard - Send diplomatic messages - Consider forming alliances

Troubleshooting

Common Issues:

“Supabase connection failed”

  • Check your internet connection

  • Verify your Supabase credentials in .env

  • Ensure your Supabase project is active

“Registration failed” or 400 errors

  • Make sure you’ve run the database schema

  • Check that your service key has proper permissions

  • Verify Row Level Security policies are set up correctly

“Port already in use”

  • Another application is using port 5000

  • Kill the existing process or change the port:

python app_supabase.py --port 5001
Import errors

  • Ensure you’re in the empire directory

  • Reinstall dependencies: pip install -r requirements.txt

  • Check Python version: python --version

Database connection issues

  • Verify your .env file has the correct credentials

  • Check Supabase project status in the dashboard

  • Ensure your IP is not blocked by Supabase

Getting Help

If you encounter issues:

  1. Check the logs in your terminal for error messages

  2. Review the installation guide for detailed setup instructions

  3. Test your setup using the debug scripts in the project

  4. Report bugs on the project’s GitHub issues page

Next Steps

Now that you have Empire Builder running:

  • Read the Game Mechanics guide to understand gameplay

  • Explore the API Reference for advanced features

  • Check the Development Guide if you want to contribute

  • Join the community to connect with other players

Congratulations! You’re now ready to build your empire! 🏰