Add project planning docs and repo scaffolding

Vision, requirements, tech stack, and phased roadmap for the space
survival game, plus Unreal-appropriate .gitignore/.gitattributes
and Git LFS setup.

.gitattributes

@@ -0,0 +1,30 @@
+# Unreal binary/asset types via Git LFS
+*.uasset filter=lfs diff=lfs merge=lfs -text
+*.umap filter=lfs diff=lfs merge=lfs -text
+*.upk filter=lfs diff=lfs merge=lfs -text
+*.udk filter=lfs diff=lfs merge=lfs -text
+
+# Common asset source formats
+*.fbx filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.tga filter=lfs diff=lfs merge=lfs -text
+*.psd filter=lfs diff=lfs merge=lfs -text
+*.wav filter=lfs diff=lfs merge=lfs -text
+*.mp3 filter=lfs diff=lfs merge=lfs -text
+*.ogg filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.exr filter=lfs diff=lfs merge=lfs -text
+*.hdr filter=lfs diff=lfs merge=lfs -text
+*.ttf filter=lfs diff=lfs merge=lfs -text
+*.otf filter=lfs diff=lfs merge=lfs -text
+
+# Keep source/text files as normal git diffable text
+*.cpp text
+*.h text
+*.cs text
+*.ini text
+*.uproject text
+*.json text
+*.md text

.gitignore

@@ -0,0 +1,29 @@
+# Unreal Engine
+Binaries/
+Build/
+DerivedDataCache/
+Intermediate/
+Saved/
+.vs/
+*.VC.db
+*.opensdf
+*.opendb
+*.sdf
+*.sln
+*.suo
+*.xcodeproj
+*.xcworkspace
+
+# Generated project files (regenerated via "Generate Visual Studio project files")
+*.vcxproj
+*.vcxproj.filters
+*.vcxproj.user
+*.vcxproj.opendb
+
+# Compiled/packaged builds
+Plugins/*/Binaries/
+Plugins/*/Intermediate/
+
+# OS
+.DS_Store
+Thumbs.db

README.md

@@ -0,0 +1,14 @@
+# SpaceGame
+
+A multiplayer space survival game built in Unreal Engine 5: build and maintain a
+ship, explore a galaxy, land on planets, and establish a space station and
+planetary bases as a shared base of operations.
+
+## Docs
+- [Vision](docs/01_VISION.md) — pitch, reference games, scope reality check
+- [Requirements](docs/02_REQUIREMENTS.md) — functional requirements by system (MVP/Core/Stretch)
+- [Tech Stack](docs/03_TECH_STACK.md) — engine, networking, backend, tooling
+- [Roadmap](docs/04_ROADMAP.md) — phased build plan
+
+## Status
+Pre-Phase 0 — planning complete, Unreal project not yet created.

docs/01_VISION.md

@@ -0,0 +1,53 @@
+# Vision
+
+## Elevator pitch
+A multiplayer space survival game: crew a ship you build and maintain, warp across
+a galaxy of star systems, land on planets to explore and gather resources, and build
+persistent bases — both a space station and planetary outposts — as a shared base of
+operations with other players.
+
+## Reference pillars
+Three games anchor the scope. Each contributes a pillar; none should be copied wholesale.
+
+| Pillar | Reference | What we're taking |
+|---|---|---|
+| Modular ship construction & survival systems | Space Engineers / Empyrion | Grid-based building, power/thrust/hull as real systems you maintain, not cosmetic |
+| Procedural galaxy & planet landing | No Man's Sky | Seed-based generation, seamless-feeling landing, exploration-driven discovery |
+| Galaxy-scale travel | Elite Dangerous | Star map, jump/warp travel between systems, a galaxy big enough to feel unbounded |
+
+## Scope reality check
+
+Read this before getting attached to any specific milestone order.
+
+**Persistent shared-world multiplayer**, **full grid-based ship construction**, and
+**seamless procedural planets** are each, individually, the kind of feature a funded
+studio spends 1-3+ years getting right. Combined, and solo, this is a multi-year project
+even at hobbyist pace. That's not a reason not to build it — it's a reason to be
+deliberate about sequencing:
+
+1. **Architect for the full vision, build the small vision first.** Every system below
+   is designed so it *can* scale to persistent multiplayer and a full galaxy, but the
+   early phases run single-player or session-based, with one hand-built system and one
+   or two planets. See [04_ROADMAP.md](04_ROADMAP.md).
+2. **Cut scope at the hardest problems on purpose, not by accident.** The two hardest
+   technical problems here are (a) truly seamless space-to-planet-surface transitions,
+   and (b) a persistent world server that doesn't require you to run a 24/7 fleet alone.
+   The tech stack doc calls out the pragmatic version of each (instanced landing zones,
+   system-sharded servers) so you have something shippable, with a documented path to
+   the more ambitious version later.
+3. **Revisit ambition at each phase boundary.** It is completely reasonable to decide,
+   after Phase 3 or 4, that a session-based co-op game (players host, invite friends,
+   world doesn't need to persist on your infrastructure) is the right final scope rather
+   than a persistent MMO. That decision gets easier once you can see the game running.
+
+## Core pillars (functional)
+- **Fly & fight** a ship across open space in a galaxy of star systems.
+- **Build & maintain** that ship from modular components with real systems (power,
+  thrust, life support, hull integrity) that degrade and require upkeep.
+- **Warp** between star systems via a galaxy map.
+- **Land & explore** planets on foot (or surface vehicle), gather resources, encounter
+  hazards.
+- **Build bases** — a space station as a persistent home base, and planetary outposts —
+  that you and other players can return to, expand, and defend.
+- **Play together** — multiple players sharing ships, stations, and eventually a
+  persistent galaxy.

docs/02_REQUIREMENTS.md

@@ -0,0 +1,112 @@
+# Requirements
+
+Requirements are grouped by system. Each item is tagged:
+- **[MVP]** — needed for the first playable milestone (single-player/session, one system)
+- **[Core]** — needed before calling this "the game" (session-based multiplayer, full loop)
+- **[Stretch]** — the persistent-MMO / full-galaxy ambition; comes after Core is solid
+
+## 1. Ship
+- [MVP] Player can pilot a ship with 6-DOF or flight-model movement in open space.
+- [MVP] Ship has at least: hull, one power source, thrusters, one storage container.
+- [MVP] Ship systems can be damaged and repaired (hull integrity, component health).
+- [Core] Modular grid-based construction: attach/detach blocks (thrusters, power,
+  storage, weapons, life support) on a snap grid, similar to Space Engineers.
+- [Core] Power system: generation, consumption, and outage consequences (no thrust,
+  no life support) when under-powered.
+- [Core] Life support: oxygen and/or power must be maintained for crew to survive
+  aboard ship.
+- [Core] Ship persists between sessions (saved layout, inventory, damage state).
+- [Stretch] Multiple crew can occupy and operate the same ship simultaneously
+  (pilot, gunner, engineer roles).
+- [Stretch] Ship-to-ship combat with component-level damage (target the engine,
+  disable the shield generator, etc).
+
+## 2. Space Station (base of operations)
+- [MVP] A single hand-placed station exists as a hub: dock, restock, respawn point.
+- [Core] Players can build/expand the station from modular components (same
+  construction system as ships, non-mobile).
+- [Core] Station has persistent storage, crafting stations, and a docking system for
+  player ships.
+- [Core] Station respawn point on player death.
+- [Stretch] Multiple stations, player-founded, potentially claimable/ownable by a
+  group.
+- [Stretch] Station defense (turrets, shields) against NPC or player raids.
+
+## 3. Galaxy & Travel
+- [MVP] One star system, flyable, with a defined boundary.
+- [Core] Star map UI showing known systems and jump targets.
+- [Core] Warp/jump travel between systems with a travel-time or loading transition
+  (does not need to be seamless).
+- [Stretch] Procedurally generated galaxy (seeded), effectively unbounded number of
+  systems, generated on demand rather than pre-authored.
+- [Stretch] Points of interest per system (asteroid fields, derelicts, anomalies,
+  NPC factions/traders).
+
+## 4. Planets
+- [MVP] At least one landable planet/moon with a bounded, hand-authored surface
+  (an "instanced landing zone," not the full sphere).
+- [MVP] On-foot exploration: movement, basic environment hazards (e.g. no
+  atmosphere = needs suit oxygen).
+- [Core] Resource gathering on planet surface (mining/harvesting nodes feed back
+  into ship/station crafting).
+- [Core] Multiple biomes/planet types with distinct visuals and hazards.
+- [Core] Surface vehicle for faster traversal on larger landing zones (optional if
+  zones stay small).
+- [Stretch] Procedurally generated planet surfaces (seed-based terrain, biome
+  rules), replacing hand-authored zones.
+- [Stretch] Seamless space-to-surface transition (no loading screen) — explicitly
+  deferred; revisit only once everything else is solid, see 03_TECH_STACK.md.
+
+## 5. Planetary Bases
+- [Core] Same modular construction system usable on a planet surface (foundation-
+  anchored instead of free-floating).
+- [Core] Base provides shelter from surface hazards (atmosphere, temperature,
+  radiation as applicable) and a resource processing/crafting point.
+- [Stretch] Base persists and is visible/enterable by other players who land on the
+  same planet instance.
+- [Stretch] Environmental hazards that specifically threaten planetary bases
+  (storms, corrosive atmosphere, local wildlife).
+
+## 6. Survival Systems
+- [MVP] Player character has health and a suit resource (oxygen and/or power) that
+  depletes and must be resupplied.
+- [Core] Ship/station/base life support all tie into the same suit/oxygen model
+  consistently.
+- [Core] Hull/structure integrity as a maintainable resource (things break, need
+  repair materials).
+- [Stretch] Additional survival axes (temperature, radiation exposure, hunger) if
+  they add meaningful decisions rather than busywork.
+
+## 7. Multiplayer & Persistence
+- [MVP] Not networked — single player, local only. Prove the core loop first.
+- [Core] Session-based multiplayer: a host runs a session, friends join directly
+  (via Epic Online Services sessions), state persists only for that session/host.
+- [Stretch] Persistent shared world: player accounts, server-authoritative galaxy
+  state, ship/base ownership stored server-side, available across sessions without
+  a specific host needing to be online.
+- [Stretch] World sharded by star system: each system instance runs as its own
+  server process, spun up on demand (see 03_TECH_STACK.md) rather than one seamless
+  mega-server.
+- [Stretch] Permissions/ownership model for shared bases (who can build, access
+  storage, dock).
+- [Stretch] Basic anti-grief tooling (claim radius, lockable doors/containers).
+
+## 8. Progression & Economy
+- [Core] Crafting/tech tree gates access to better ship components and base
+  modules.
+- [Stretch] Trading between players and/or NPC factions.
+- [Stretch] Currency or barter economy tied to resources gathered.
+
+## 9. Non-Functional Requirements
+- **Platforms:** PC (Steam) at launch; architecture should not preclude console
+  porting later (drives Epic Online Services choice over Steam-only APIs).
+- **Performance target:** 60 fps on mid-range hardware (defer exact spec until an
+  art-direction pass; Nanite/Lumen usage affects this significantly).
+- **Concurrent players (Stretch phase):** design target of dozens of concurrent
+  players per shard/system server, not hundreds — keeps the backend tractable for a
+  solo/small team.
+- **Save integrity:** no permadeath data loss from a server crash mid-session
+  (autosave cadence + transactional persistence once a backend exists).
+- **Art style:** not yet decided — recommend committing to a style that reduces
+  asset-production burden for a solo dev (stylized/mid-poly beats photoreal for a
+  one-person or small team; revisit once Phase 1 is playable).

docs/03_TECH_STACK.md

@@ -0,0 +1,104 @@
+# 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 |

docs/04_ROADMAP.md

@@ -0,0 +1,68 @@
+# Roadmap
+
+Phased so there's a playable build at the end of every phase. Each phase is a
+"piece" in the sense you described — build it, play it, then move to the next.
+Reassess ambition at each phase boundary (see 01_VISION.md).
+
+## Phase 0 — Foundations
+- Install Unreal Engine 5, create the C++ project, set up Git LFS + `.gitignore`.
+- Learn-by-building: a basic pawn that flies in open space with simple physics
+  (no building, no planets yet).
+- Empty test level, no gameplay systems yet.
+- **Exit criteria:** you can fly a placeholder ship around an empty level.
+
+## Phase 1 — Core Ship Loop (single-player)
+- One hand-built ship with hull, power source, thrusters, storage (02_REQUIREMENTS §1 MVP).
+- Basic damage/repair on hull.
+- One hand-authored landable zone (planet or asteroid) with on-foot movement and
+  suit oxygen (02_REQUIREMENTS §4/§6 MVP).
+- Basic resource gathering that feeds a simple inventory.
+- **Exit criteria:** fly from a starting point, land, gather something, fly back.
+
+## Phase 2 — Construction System
+- Modular grid-based building for the ship (attach/detach blocks) (§1 Core).
+- Power/thrust/life-support modeled as real systems blocks contribute to.
+- **Exit criteria:** you can meaningfully redesign your ship, not just pilot a
+  fixed one.
+
+## Phase 3 — Space Station & Planetary Bases
+- A station hub: dock, restock, respawn (§2 MVP/Core).
+- Same construction system adapted for a station and for planet-anchored bases
+  (§5 Core).
+- **Exit criteria:** you have a home base in space and at least one on a planet.
+
+## Phase 4 — Multiplayer (session-based)
+- Integrate Epic Online Services sessions.
+- Replicate ship piloting, block placement, inventory, damage across clients.
+- One host, invited friends join — no persistent backend yet (§7 Core).
+- **Exit criteria:** you and a friend can fly the same ship and build together
+  in a session.
+
+### Decision point
+By here you'll know a lot more about how much solo/small-team bandwidth you
+have. This is the natural point to decide: stay session-based (simpler, still
+a complete game) or push into persistent-world territory (Phase 5+). Both are
+legitimate outcomes.
+
+## Phase 5 — Galaxy Expansion
+- Star map UI + warp travel between multiple hand-authored systems (§3 Core).
+- More planet variety (biomes, hazards) (§4 Core).
+- Crafting/tech tree progression (§8 Core).
+- **Exit criteria:** the game has a galaxy to explore, not just one system.
+
+## Phase 6 — Persistence & Procedural Galaxy (Stretch)
+- Backend service + PostgreSQL for accounts and ownership.
+- Seed-based procedural system/planet generation, storing only deltas.
+- Server-per-system sharding, on-demand instance orchestration.
+- **Exit criteria:** the world persists without a specific host needing to be
+  online, and the galaxy is effectively unbounded.
+
+## Phase 7 — Scale & Polish (Stretch)
+- Matchmaking, base permissions/anti-grief tooling.
+- Console porting (leaning on the EOS choice made in Phase 4).
+- Economy/trading, additional content.
+
+---
+
+**Next step:** Phase 0. Once Unreal Engine is installed and the project is
+created, we can start on the flight pawn and empty test level.