commit e437a181212d6e31ae18f5d67c2e5524a099db53 Author: Joshua Deville Date: Wed Jul 8 13:47:02 2026 -0400 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. diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..04b3c2a --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9f02a99 --- /dev/null +++ b/.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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..fabeef1 --- /dev/null +++ b/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. diff --git a/docs/01_VISION.md b/docs/01_VISION.md new file mode 100644 index 0000000..ebdc6e2 --- /dev/null +++ b/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. diff --git a/docs/02_REQUIREMENTS.md b/docs/02_REQUIREMENTS.md new file mode 100644 index 0000000..acaf523 --- /dev/null +++ b/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). diff --git a/docs/03_TECH_STACK.md b/docs/03_TECH_STACK.md new file mode 100644 index 0000000..83cc9f4 --- /dev/null +++ b/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 | diff --git a/docs/04_ROADMAP.md b/docs/04_ROADMAP.md new file mode 100644 index 0000000..2cf3114 --- /dev/null +++ b/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.