This directory contains game design documents describing what we're building from a player-facing perspective. For technical implementation details, see Technical Design Documents.
What belongs here:
- Player experience and game mechanics
- UI/UX from the player's perspective
- Game systems (colonists, building, world, etc.)
- Gameplay features and content
- Player-facing requirements
What does NOT belong here (goes in technical/):
- Architecture and system design
- Implementation details (algorithms, data structures)
- Tools and infrastructure
- Performance optimization
- MVP Scope — What's included in each development phase
- Game Overview — Core concept, world mechanics
- Visual Style — Art direction, aesthetics
- UI Design — Interface design system, screen specs, mocks
Location: ui/
The interface design ("Salvage"), the design system that builds it, and the spec for every screen. Extracted from the prototype under docs/ui-prototype/.
| Document | Description |
|---|---|
| UI Design Index | Entry point for everything below |
| Design Language | Salvage: principles, palette, typography, texture, motion |
| Tokens | Every design value (readable); canonical in tokens.json |
| Components | The 14 primitives: variants, props, states, behavior |
| Icons | The 51-glyph line-icon set |
| Screens | Pre-game flow and in-game HUD specs |
| Mocks | Rendered shots of every screen and state |
Organized by topic area. Each folder contains related design documents.
Location: game-systems/colonists/
Everything about colonist behavior, needs, and mechanics.
| Document | Description |
|---|---|
| README | Overview and navigation |
| AI Behavior | Decision hierarchy, autonomous behavior |
| Needs System | Physical needs, mood, breakdowns |
| Memory System | What colonists know |
| Attributes | Personality, backstory |
| Skills | Learning, progression |
| Work Priorities | Work assignment |
| Equipment & Inventory | Worn slots, belt slots, weight-based pack, item size |
Location: game-systems/world/
World mechanics, rooms, resources, and entity interactions.
| Document | Description |
|---|---|
| Entity Capabilities | How entities advertise what they do |
| Rooms | Room types, detection, bonuses |
| Crafting | Resource chains, recipes |
| Building & Construction | Freeform foundations, walls, doors/windows, rooms |
Location: features/
Discrete player-facing features.
| Document | Description |
|---|---|
| Game Start Experience | Main menu → gameplay flow |
| Player Control | Observation, command, direct control |
| Asset Manager | Designer/agent tool to browse, preview, validate assets (technical overlap) |
| Storage System | Item storage, priority hauling |
| Vector Graphics | Asset workflow, animations |
| Multiplayer | Co-op, multiplayer design |
| Debug Server | Developer tools (technical overlap) |
| Document | Description |
|---|---|
| Competitive Analysis | Analysis of similar games |
Do NOT create "MVP Scope" sections in individual docs. Instead reference:
**MVP Status:** See [MVP Scope](./mvp-scope.md) — This feature: Phase XUse relative paths for links within docs/:
See [Needs System](./game-systems/colonists/needs.md)When consolidating or superseding documents, add a "Historical Addendum" section at the bottom preserving the original content.
- Technical Design Documents — How things are implemented
- Development Log — Implementation history
- Project Status — Current work