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.
This commit is contained in:
Joshua Deville
2026-07-08 13:47:02 -04:00
commit e437a18121
7 changed files with 410 additions and 0 deletions

30
.gitattributes vendored Normal file
View File

@@ -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

29
.gitignore vendored Normal file
View File

@@ -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

14
README.md Normal file
View File

@@ -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.

53
docs/01_VISION.md Normal file
View File

@@ -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.

112
docs/02_REQUIREMENTS.md Normal file
View File

@@ -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).

104
docs/03_TECH_STACK.md Normal file
View File

@@ -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 |

68
docs/04_ROADMAP.md Normal file
View File

@@ -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.