⭐ Starbound

⚠️ AI-Generated Code Warning This project was fully generated by AI using this specific prompt. and has not been tested or reviewed by humans. It may contain errors, bugs, or security vulnerabilities. Use at your own risk.

An OGame/Travian/Civ 6/Stellaris inspired browser strategy game.

Architecture

starbound/
├── backend/          Rust · Axum · SQLx (SQLite local / PostgreSQL prod)
├── frontend/         TypeScript · Vite · Three.js (no framework)
├── tauri-app/        Tauri desktop shell
├── package.json      pnpm workspace root
└── pnpm-workspace.yaml

Quick Start — Local (SQLite, speed x5)

1. Backend

cd backend
cp .env.example .env          # tweak if needed
cargo run
# Server at http://localhost:3000

The .env.example defaults to:

• SQLite database (starbound.db auto-created)
• GAME_SPEED=5 (5× real-time for local testing)
• ALLOW_PLAYER_SPEED=true (speed buttons shown in UI)

2. Frontend

cd ..                 # workspace root
pnpm install
pnpm dev              # Vite dev server at http://localhost:5173

Then open http://localhost:5173 → register → play.

3. Tauri Desktop (optional)

# Requires Tauri CLI: cargo install tauri-cli
pnpm tauri:dev

---

Production (PostgreSQL)

cd backend
cp .env.production .env
# Fill in DATABASE_URL, JWT_SECRET
cargo build --release
./target/release/server

PostgreSQL requires PostGIS and btree_gist extensions (installed automatically by the migration if the DB user has superuser rights):

CREATE EXTENSION postgis;
CREATE EXTENSION btree_gist;

---

Game Speed System

Mode	.env setting	UI speed buttons
Local dev	GAME_SPEED=5	Shown (x1–x100)
LAN play	GAME_SPEED=1	Shown
Public server	GAME_SPEED=1 + ALLOW_PLAYER_SPEED=false	Hidden

How it works:

• All timers are stored in game ticks (not wall-clock seconds).
• real_tick_ms = tick_ms / game_speed — the tick fires faster at higher speed.
• Changing speed mid-game is instant: a unit with 10 ticks remaining still has 10 ticks remaining, but they arrive 5× sooner at x5 speed.
• Speed is persisted in server_config table and restored on restart.
• SSE broadcasts speed_changed so all clients resync their countdown timers.

---

Polling Strategy

The game does not use WebSockets. Instead:

Event	How the client learns
Unit arrival / fleet ETA	Poll /api/units when local timer expires
Construction complete	Poll /api/planets/:id when timer expires
Research complete	Poll /api/research when timer expires
Battle started	SSE battle_started event (instant)
Battle ended	SSE battle_ended event
Tick / speed change	SSE tick / speed_changed events
Missed SSE events (reconnect)	Poll /api/events/missed?since_id=N

---

3D Models

Currently using procedural placeholder geometry. To swap in real models:

1. Export as .glb (GLTF binary) with animations named idle, walk, fight.
2. Place in frontend/public/models/<unit_type>.glb.
3. In src/engine/models/placeholder.ts, replace createUnitModel() with:

import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
const loader = new GLTFLoader();
const gltf = await loader.loadAsync(`/models/${unitType}.glb`);
const mixer = new THREE.AnimationMixer(gltf.scene);
const actions = {
  idle:  mixer.clipAction(THREE.AnimationClip.findByName(gltf.animations, 'idle')),
  walk:  mixer.clipAction(THREE.AnimationClip.findByName(gltf.animations, 'walk')),
  fight: mixer.clipAction(THREE.AnimationClip.findByName(gltf.animations, 'fight')),
};

---

Views

View	Style	Entry
Planet surface	Civ 6 hex tiles	Default on login
Solar system	Stellaris	Click "🚀 Solar System" button
Galaxy map	Star points	(future: click hyperjump target)

---

Database Schema Highlights

• All timers in game ticks — speed changes don't invalidate existing orders.
• Lazy tile generation — only tiles players have explored exist in DB.
• Procedural universe — galaxies/systems/planets outside player activity are generated from seeds on demand, never stored.
• PostGIS on Postgres — space_pos geometry(PointZ) enables ST_DWithin proximity queries for "find all ships near coordinate X".
• btree_gist — unique constraint on battles(tile_id) prevents double-battle race conditions.
• SSE event log — sse_events table lets reconnecting clients fetch alerts they missed.