spacegame/docs/03_TECH_STACK.md

# Tech Stack

## Engine & language
- **Unreal Engine 5** (latest stable release at time of starting, e.g. 5.4/5.5 —
  verify current LTS-ish version when you install).
- **C++ for core systems**, **Blueprint for iteration/content glue**. As a solo
  dev newer to Unreal: prototype gameplay logic in Blueprint first, then move
  performance- or replication-critical code (ship building grid, networked
  movement, inventory) into C++ once the design is proven. Don't build the whole
  game in Blueprint and don't build the whole game in C++ from day one either —
  the hybrid is standard Unreal practice, not a compromise.
- **Visual Studio 2022** (Windows) as the C++ IDE/toolchain.

## Version control
- **Git + Git LFS** for the project (binary assets — meshes, textures, audio —
  must go through LFS or the repo becomes unusable). This repo has been
  initialized; add a `.gitattributes` for LFS and an Unreal-appropriate
  `.gitignore` before the first Unreal project commit.
- Perforce is the more common choice at studios for large binary-heavy UE
  projects, but Git LFS is sufficient for a solo/small-team project and keeps
  your existing GitHub workflow.

## Networking (Core phase — session-based multiplayer)
- **Unreal's built-in actor replication** for gameplay state (ship position,
  block placement, inventory, damage).
- **Epic Online Services (EOS)** for session creation/discovery, friend invites,
  and cross-platform accounts — chosen over Steamworks-only APIs specifically
  because you want console support eventually. EOS is free and is the standard
  path to PC+console cross-play in Unreal.
- Dedicated server build target (headless `UnrealServer` build) so a session can
  be hosted without a full client running, even before persistence exists.

## Backend & persistence (Stretch phase — persistent shared world)
This is the biggest jump in complexity and the part most likely to get
descoped. Recommended shape when you get here:
- **Sharding by star system, not one seamless server.** Each star system
  instance runs as its own dedicated server process. Traveling between systems
  is a disconnect/reconnect to a different server instance (conceptually like
  EVE Online's per-constellation model, simplified). This avoids the single
  hardest unsolved problem in the genre (Star Citizen's seamless single-shard
  server meshing) and is achievable for a small team.
- **A backend service outside Unreal** for anything that must survive a server
  restart: player accounts, ship/base ownership and layout, galaxy generation
  seeds, and per-system deltas (what's been mined, what's been built).
  - Service layer: a small REST or gRPC API (Node.js, Go, or C# — pick whatever
    you're already comfortable with; this is a small service, not a place to
    learn a new language under pressure).
  - Database: **PostgreSQL**. Relational is the right fit for accounts,
    ownership, and structured ship/base data.
- **On-demand server orchestration**: system servers spin up when a player
  jumps in and idle down when empty, rather than running every possible system
  24/7. Start manual (a script that launches a server process per active
  system) — only reach for Kubernetes/Agones-style orchestration if you
  actually hit the scale that needs it.
- Cloud hosting: any provider works; budget is the main constraint here more
  than technical fit (AWS/GCP/a cheaper VPS host are all fine for the scale in
  02_REQUIREMENTS.md's non-functional target of "dozens per shard").

## Procedural generation
- **Seed-based deterministic generation**: a star system's layout and a
  planet's terrain/biome are derived from a seed, not stored wholesale. Only
  store *deltas* (player-built structures, depleted resource nodes) in the
  database — this is what makes a "big" galaxy cheap to persist.
- Noise library: Unreal's built-in noise nodes are fine to start; **FastNoise2**
  (available as a plugin) if you need more control/performance for terrain.
- Recommend deferring full procedural planet terrain until after Phase 3
  (02_REQUIREMENTS.md marks it Stretch) — hand-authored landing zones get you
  a playable game much faster and de-risk the building/survival/multiplayer
  work first.

## Planet rendering approach
- **Start with instanced landing zones**: a bounded terrain tile (built with
  UE5 **Landscape** + **World Partition** for streaming, **Nanite** for detail
  where useful) that you load into when landing, rather than a fully seamless
  planet sphere. This is explicitly the pragmatic call flagged in
  01_VISION.md — seamless space-to-surface (No Man's Sky/Star Citizen-style) is
  a well-known multi-year problem even for funded teams.
- If/when seamless landing becomes a real goal, that's a dedicated R&D phase on
  its own (large-scale floating-origin rendering, planet-scale LOD) — don't
  plan it into an early milestone.

## Ship/base construction system
- No first-party Unreal system does grid-based modular construction
  out of the box; this needs custom work:
  - A snap-grid attachment system (component-based: each block is an actor or
    instanced static mesh with defined attachment points).
  - Underlying systems (power, thrust, life support) modeled as data that
    blocks contribute to/consume from, independent of the visual mesh.
- Check the Unreal Marketplace/Fab for existing modular building or grid-snap
  plugins to jumpstart the visual/placement layer — but expect to write the
  systems layer (power/thrust/life-support simulation) yourself, since that's
  specific to this game's design.

## Tooling summary
| Purpose | Tool |
|---|---|
| Engine | Unreal Engine 5 (latest stable) |
| IDE | Visual Studio 2022 |
| Source control | Git + Git LFS |
| Multiplayer sessions/accounts | Epic Online Services |
| Backend API (Stretch) | Node.js/Go/C# REST or gRPC service |
| Database (Stretch) | PostgreSQL |
| Procedural noise | UE built-in, or FastNoise2 plugin |
| CI (once useful) | GitHub Actions or Jenkins for automated builds |