Space4X - Persistent Multiplayer Space Strategy

A real-time, persistent multiplayer 4X space strategy game built in Unity, inspired by classic games like VGA Planets, TradeWars 2002, and Stars! The game combines long-term empire building with fast-paced trading in a shared, continuously-running galaxy.

Project Vision

Space4X creates a living, breathing galaxy where empires rise and fall over months while traders keep the economy buzzing minute by minute. The game runs 24/7 on dedicated servers, with all ships, starbases, and economies processing continuously whether players are online or offline.

How It All Ties Together

Core Architecture

• Unity + Mirror Networking - Authoritative server with client prediction
• MySQL Database - Persistent storage for galaxy state, player data, and game objects via MySqlConnector
• Configuration-Driven Design - All game mechanics controlled via editable settings files
• Dual-Scale Gameplay - Empire players act on hour/day cycles, Traders on minute/hour cycles

Galaxy Simulation

• BigBang System - Procedurally generates galaxies with natural star clustering and empty voids
• Persistent Universe - 5000x5000 sector galaxy with natural density gradients toward center
• Real-Time Processing - Server continuously processes ship movement, resource production, and fleet combat
• Ion Storm Weather - Dynamic hazards that move across the galaxy affecting FTL travel

Player Experience

• First-Person Flight - Pilot individual ships with full 6DOF controls through the galaxy
• Strategic Command - Issue orders to fleets and manage empire-scale operations
• Economic Simulation - Complex supply chains driven by player actions and NPC traders
• Asymmetric Gameplay - Empire builders vs Traders with different capabilities and objectives

Key Documents

• GAME_DESIGN.md - Complete gameplay design and controls
• CONSOLE_GUIDE.md - Console system usage and commands
• CONFIGURATION.md - Settings and server customization
• ConfgDetail.md - Auto-generated configuration reference

Asset index & usage scan

• The repository contains a filtered asset index that excludes Unity .meta files and backups. See docs/ASSET_INDEX.md for a human-readable index and docs/ASSET_INDEX.csv for a machine-readable CSV.
• A companion docs/ASSET_INDEX_REFERENCES.csv lists where important prefabs and prefab variables (for example playerControllerPrefab, shipPrefab, starbasePrefab) are referenced in code. This was produced by scanning Assets/Scripts/ for prefab variables and literal prefab paths to help locate where assets are instantiated or validated.

Quick Start

Database Setup

1. Install MySQL 8.0+ and create database:

   mysql -u root -p
   CREATE DATABASE space5x;
   CREATE USER 'space5x'@'localhost' IDENTIFIED BY 'BigBang';
   GRANT ALL PRIVILEGES ON space5x.* TO 'space5x'@'localhost';
   EXIT;
   
   mysql -u space5x -pBigBang space5x < db/schema.sql
   mysql -u space5x -pBigBang space5x < db/seed.sql

2. Configure MySQL connection (optional - defaults work for local dev):

• For repo reference, copy mysql_config.json.template to db/mysql_config.json and edit as needed (this file is for developer reference only).
• For standalone server builds, place mysql_config.json next to the executable or in config/mysql_config.json on the server.
• In the Editor the server will create a db/mysql_config.json from editor defaults (if missing). Standalone builds will create config/mysql_config.json when starting if none exists.

Unity Setup

1. Open the project in Unity 2020.3+
2. Load the MainScene
3. Press Play to start a local server
4. Press ~ to open the console and type /help
5. Use WASD + mouse to pilot your ship through the galaxy

The game automatically generates a galaxy on first run and saves all state to MySQL.

Persistence System

The game uses MySQL for persistent storage:

• Entity State: Ships, starbases, and player data saved to persist_records table
• Order Queue: Queued orders stored in orders table
• Contracts: Mission system data in contracts table
• Autosave: Server automatically saves world state every 60 seconds
• Server-Only: Database operations run only on dedicated server builds
• Config File: Connection settings in mysql_config.json (auto-created with defaults)

See docs/Linux_Server_Setup.md for production deployment configuration.

Gameplay Features

Ship System

• Movement: Ships have normal speed (0-100) plus optional FTL capabilities
• Orders Queue: Ships can be given multiple orders that execute in sequence
• Order Types:
  • Move to location
  • FTL Jump (traders only)
  • Attack target
  • Trade resources
  • Patrol route
  • Hold position
• Return Orders: Ships can be ordered to return after completing a task
• Customization: Ships are fully customizable with different classes and configurations

Starbase System

• Player starbases serve as production centers
• Build ships, research technology, store resources
• Multiple starbase types with different capabilities
• Configurable build times and costs

Resource System

• Multiple resource types (Fuel, Minerals, Food, etc.)
• Resources produced by planets in star systems
• Dynamic pricing based on supply and demand
• Trading between players and NPC starports

Configuration

The game uses a GameSettings system that can be configured via JSON:

{
  "mapSizeX": 50,
  "mapSizeY": 50,
  "starSystemChancePercentage": 10,
  "normalSpeedMax": 100,
  "traderFTLJumps": 5,
  "traderFTLCooldownSeconds": 300,
  "startingCredits": 10000,
  "serverTickRateSeconds": 1.0,
  "persistentGameplay": true
}

Configurable Elements

Races

• Multiple playable races with unique bonuses
• Production, Research, Trade, and Military modifiers
• Configurable via RaceConfiguration ScriptableObject

Ships

• Multiple ship classes (Scout, Trader, Frigate, Destroyer, Freighter)
• Customizable stats: hull, speed, cargo, weapons, shields
• Build costs and construction times
• Configurable via ShipConfiguration ScriptableObject

Starbases

• Various types: Outpost, Trading Station, Starbase, Fortress
• Different capabilities and costs
• Configurable via StarbaseConfiguration ScriptableObject

Game Flow

New Player Experience

1. Player creates account with username/password
2. Assigned a race (or can choose from available races)
3. Given starting credits
4. A starbase is created in a random, unowned star system
5. Player can immediately start building ships and giving orders

Playing the Game

1. Login: Player connects to the persistent game server
2. View Status: Check ship positions, resource levels, and ongoing orders
3. Issue Orders: Command ships to move, attack, or trade
4. Build: Queue ships for construction at starbases
5. Console Commands: Press ~ to open the console for listing objects, navigation, and testing (see CONSOLE_QUICKSTART.md)
6. Logout: Ships continue executing orders while offline
7. Return: Log back in to see progress and issue new orders

2D Display

• Top-down view of the galaxy
• Scrollable map showing all sectors
• Star systems appear as dots/icons
• Zoom in to see planets, ships, and starbases within a system
• Ship movement trails show historical paths

Technical Architecture

Server Components

• BigBang: Universe generation and initialization
• PersistenceService: MySQL persistence layer with autosave (server-only)
• OrdersService: Ship order queue execution system
• ContractsService: Mission/contract lifecycle management
• HazardsService: Dynamic space hazards (ion storms, anomalies)
• NetworkManager: Mirror server/host/client management with SectorInterest

Client Components

• playerManager: Client-side player interface
• RTS_Camera: 2D scrollable camera system
• MapClick: Sector selection and interaction

Networking

• Built on Unity Mirror for client-server networking
• Server-Authoritative: All game state mutations validated on server
• SyncVars: Real-time state synchronization (hull, cargo, position)
• Commands: Client requests with [Command(requiresAuthority=true)]
• ClientRpc: Server notifications to clients
• SectorInterest: Players only observe entities in their current sector
• KCP Transport: UDP-based transport on port 7777

Game Inspirations

VGA Planets

• Turn-based but we make it real-time
• Ship orders and waypoints
• Resource management
• Multiple races with unique abilities

TradeWars 2002

• Fast-paced trading gameplay
• Port trading system
• FTL jump mechanics for quick movement
• Persistent universe

Stars!

• Deep ship customization
• Strategic depth
• Long-term empire building
• Technology research

Development Status

This is an active development project implementing a complete rebuild of the Space4X game based on classic 4X strategy games.

Implemented Features

• ✅ Configurable universe generation
• ✅ Persistent server game loop
• ✅ Ship order queue system
• ✅ FTL jump mechanics for traders
• ✅ Player account system
• ✅ Starting starbase assignment
• ✅ Configurable game settings
• ✅ Race configuration system
• ✅ Ship template system
• ✅ Starbase configuration system

In Progress

• 🔨 Ship construction queue
• 🔨 Resource production system
• 🔨 Combat system
• 🔨 Technology research
• 🔨 Enhanced UI for ship/base management

Planned

• 📋 Diplomacy system
• 📋 Alliance mechanics
• 📋 Territory control
• 📋 Victory conditions
• 📋 Leaderboards and statistics

Contributing

This is a World Domination Software project. The goal is to create an engaging, persistent multiplayer experience that captures the best elements of classic space strategy games while adding modern real-time gameplay.