Add technical design document
This commit is contained in:
@@ -0,0 +1,397 @@
|
||||
# Agrarian Technical Design Document
|
||||
|
||||
## Purpose
|
||||
|
||||
This document defines the technical shape of Agrarian at the foundation stage.
|
||||
It translates the core design direction into practical architecture decisions,
|
||||
runtime boundaries, data contracts, build lanes, and near-term implementation
|
||||
rules.
|
||||
|
||||
Detailed designs for multiplayer/networking, persistence, Earth-scale terrain
|
||||
streaming, economy/AGR, and art/code standards are intentionally split into
|
||||
their own roadmap documents.
|
||||
|
||||
## Current Technical Baseline
|
||||
|
||||
Agrarian is an Unreal Engine 5.7 C++ project with Blueprint assets layered on
|
||||
top for early gameplay content and testable prototype objects.
|
||||
|
||||
Current project direction:
|
||||
|
||||
- authoritative gameplay state lives on the server;
|
||||
- clients receive replicated state for UI and presentation;
|
||||
- core gameplay systems are C++ components or actors;
|
||||
- content-facing configuration uses Data Assets where possible;
|
||||
- MVP terrain starts with one real 1 km x 1 km Ground Zero tile;
|
||||
- tile packages can be served from the MVP map tile server;
|
||||
- Windows-Builder is the primary Unreal/Visual Studio build VM;
|
||||
- Ubuntu-Codex is the source-control and automation workstation;
|
||||
- Unraid `DevBox` hosts shared project storage and supporting VMs.
|
||||
|
||||
## Runtime Architecture
|
||||
|
||||
### Server Authority
|
||||
|
||||
The server is authoritative for gameplay outcomes.
|
||||
|
||||
Server-owned state includes:
|
||||
|
||||
- player survival values;
|
||||
- inventory changes;
|
||||
- crafting results;
|
||||
- world time;
|
||||
- weather state applied to gameplay;
|
||||
- resource depletion/harvest results;
|
||||
- wildlife state;
|
||||
- placed structures;
|
||||
- persistence save/load decisions.
|
||||
|
||||
Clients may request actions, but the server validates and applies results.
|
||||
|
||||
### Client Responsibilities
|
||||
|
||||
Clients are responsible for:
|
||||
|
||||
- player input;
|
||||
- camera and local presentation;
|
||||
- UI/HUD;
|
||||
- local animation;
|
||||
- local audio/visual feedback;
|
||||
- displaying replicated survival, inventory, weather, and world state;
|
||||
- local tile cache storage once streaming matures.
|
||||
|
||||
Clients should not directly call public weather APIs or mutate authoritative
|
||||
world state.
|
||||
|
||||
### Gameplay System Boundaries
|
||||
|
||||
Early runtime systems should remain small and explicit:
|
||||
|
||||
- `AAgrarianGameState`: world time, weather, ambient temperature, replicated
|
||||
environment state.
|
||||
- `UAgrarianSurvivalComponent`: health, hunger, thirst, stamina, body
|
||||
temperature, injury, and survival damage.
|
||||
- Inventory component/classes: item stacks, item definitions, resource intake,
|
||||
and crafting inputs/outputs.
|
||||
- Crafting component/classes: recipes, validation, output creation.
|
||||
- Interaction component/classes: player-facing use/gather/build entry points.
|
||||
- Resource actors: gatherable wood, stone, fiber, water, wildlife, and future
|
||||
natural resources.
|
||||
- Buildable actors: campfire, primitive shelter, frames, walls, roof panels,
|
||||
and later settlement infrastructure.
|
||||
- Persistence layer: save/load contracts for player and world state.
|
||||
|
||||
Blueprints can compose and expose these systems, but core replicated behavior
|
||||
should remain in C++ as much as practical.
|
||||
|
||||
## Time And Environment
|
||||
|
||||
The MVP gameplay calendar target is:
|
||||
|
||||
```text
|
||||
4 real hours = 1 in-game day
|
||||
```
|
||||
|
||||
The current C++ default is:
|
||||
|
||||
```text
|
||||
GameHoursPerRealMinute = 0.1
|
||||
```
|
||||
|
||||
That equals 6 in-game minutes per real minute, or 24 in-game hours over 4 real
|
||||
hours.
|
||||
|
||||
Day/night presentation should mimic the represented Earth region's local solar
|
||||
and weather context as the system matures. This means the gameplay calendar can
|
||||
be compressed while visual lighting, seasonal direction, and weather mapping
|
||||
still derive from the represented map tile.
|
||||
|
||||
Near-term technical work:
|
||||
|
||||
- add Ground Zero local time-zone metadata;
|
||||
- add sunrise/sunset lookup or approximation by latitude/longitude;
|
||||
- map real weather snapshots into internal Agrarian weather states;
|
||||
- cache weather snapshots server-side;
|
||||
- keep deterministic fallback weather when external data is unavailable.
|
||||
|
||||
## Terrain And Tile Delivery
|
||||
|
||||
### MVP Tile
|
||||
|
||||
The MVP starts with one real Ground Zero tile:
|
||||
|
||||
- 1 km x 1 km tile;
|
||||
- real elevation data imported into Unreal;
|
||||
- metadata tracked in JSON registry files;
|
||||
- static delivery package available from the map tile server.
|
||||
|
||||
### Tile Server
|
||||
|
||||
Current MVP endpoint:
|
||||
|
||||
```text
|
||||
http://maps.agrariangame.com:18080
|
||||
```
|
||||
|
||||
Current backing VM:
|
||||
|
||||
```text
|
||||
Agrarian-TileServer
|
||||
```
|
||||
|
||||
The tile server currently serves static files through nginx:
|
||||
|
||||
- `/health`
|
||||
- `/manifest.json`
|
||||
- `/ground_zero_tiles.json`
|
||||
- `/schemas/tile_registry.schema.json`
|
||||
- `/tiles/<tile_id>/v<package_version>/...`
|
||||
|
||||
The current tile client verification script proves:
|
||||
|
||||
- manifest download;
|
||||
- registry lookup;
|
||||
- package file download;
|
||||
- checksum validation;
|
||||
- neighbor metadata presence;
|
||||
- delete/redownload cache recovery.
|
||||
|
||||
### Long-Term Tile Direction
|
||||
|
||||
The long-term tile system should support:
|
||||
|
||||
- 1 km x 1 km canonical tile IDs;
|
||||
- versioned tile packages;
|
||||
- server-side registry and package metadata;
|
||||
- client local tile cache;
|
||||
- cache retention and scrub policy;
|
||||
- package revalidation and redownload;
|
||||
- tile adjacency/stitching contracts;
|
||||
- safe terrain updates that do not corrupt persisted player/world state.
|
||||
|
||||
The first implementation should stay static and simple until gameplay proves
|
||||
why a database-backed tile service is needed.
|
||||
|
||||
## Data Contracts
|
||||
|
||||
### Data Assets
|
||||
|
||||
Use Unreal Data Assets for designer-facing definitions such as:
|
||||
|
||||
- item definitions;
|
||||
- recipes;
|
||||
- gatherable resource configuration;
|
||||
- wildlife configuration;
|
||||
- buildable structure definitions;
|
||||
- future skill/knowledge definitions.
|
||||
|
||||
Data Assets should describe content. Server code should enforce gameplay rules.
|
||||
|
||||
### JSON Metadata
|
||||
|
||||
Use JSON files for external terrain/tile pipeline metadata while the pipeline is
|
||||
still early:
|
||||
|
||||
- tile registry;
|
||||
- terrain generation metadata;
|
||||
- heightmap metadata;
|
||||
- landform analysis;
|
||||
- water/shoreline analysis;
|
||||
- neighbor edge verification.
|
||||
|
||||
JSON metadata should have schemas when it becomes a contract. The tile registry
|
||||
already has an MVP schema.
|
||||
|
||||
### Save Data
|
||||
|
||||
Save data must be treated as a long-term compatibility contract. Do not store
|
||||
temporary prototype assumptions in a way that blocks future migration.
|
||||
|
||||
Persistence should include version fields for:
|
||||
|
||||
- save format;
|
||||
- game build;
|
||||
- tile package version;
|
||||
- world state records;
|
||||
- player records;
|
||||
- placed object records.
|
||||
|
||||
## Persistence Strategy
|
||||
|
||||
Persistence should begin narrow and explicit.
|
||||
|
||||
MVP persistence scope:
|
||||
|
||||
- player survival snapshot;
|
||||
- inventory snapshot;
|
||||
- placed campfire/shelter/basic structures;
|
||||
- depleted/changed resource nodes where needed;
|
||||
- world time/weather state;
|
||||
- active Ground Zero tile/package version.
|
||||
|
||||
Do not persist every temporary actor by default. Actors should opt into
|
||||
persistence with a stable identifier and a clear serialization contract.
|
||||
|
||||
Future persistence design should address:
|
||||
|
||||
- server database vs file save split;
|
||||
- migration/versioning;
|
||||
- world partition state;
|
||||
- tile package changes;
|
||||
- player-owned structures;
|
||||
- family/generation data;
|
||||
- economy and transaction records;
|
||||
- settlement governance records.
|
||||
|
||||
## Multiplayer Strategy
|
||||
|
||||
The MVP should prove at least two players on the same server.
|
||||
|
||||
Near-term rule:
|
||||
|
||||
- server validates gameplay actions;
|
||||
- replicated state is kept minimal;
|
||||
- client prediction is deferred unless interaction feels bad without it;
|
||||
- RPCs should be narrow and action-specific;
|
||||
- avoid letting Blueprint-only paths mutate critical authoritative state.
|
||||
|
||||
Detailed replication policy belongs in the multiplayer/networking design
|
||||
document.
|
||||
|
||||
## Build And Automation
|
||||
|
||||
### Windows Editor Build
|
||||
|
||||
Primary build path:
|
||||
|
||||
```text
|
||||
Scripts\BuildEditor-Windows.bat
|
||||
```
|
||||
|
||||
Codex runs this through Windows-Builder using:
|
||||
|
||||
```text
|
||||
/home/nathan/bin/winbuilder cmd 'set AGRARIAN_NO_PAUSE=1 && pushd \\DevBox\projects\AgrarianGameBulid && Scripts\BuildEditor-Windows.bat'
|
||||
```
|
||||
|
||||
### Unreal Python Verification
|
||||
|
||||
Command-mode Unreal Python scripts are used for repeatable editor validation:
|
||||
|
||||
- map checks;
|
||||
- Ground Zero terrain verification;
|
||||
- playable Blueprint verification;
|
||||
- resource and foliage placement checks.
|
||||
|
||||
These scripts should remain deterministic and safe to run repeatedly.
|
||||
|
||||
### Packaged Demo Builds
|
||||
|
||||
Investor/demo packages should be produced when a milestone version's roadmap
|
||||
items are complete. The build should use Ground Zero as the default map and
|
||||
include current splash/startup/copyright notices.
|
||||
|
||||
### Linux Dedicated Server
|
||||
|
||||
Dedicated server build instructions exist, but the MVP can continue proving
|
||||
gameplay through the current available server path until dedicated server
|
||||
packaging is required for closed testing.
|
||||
|
||||
## Infrastructure
|
||||
|
||||
Current supporting machines:
|
||||
|
||||
- `DevBox` Unraid: shared project storage and VM host.
|
||||
- `Ubuntu-Codex`: source-control/automation machine.
|
||||
- `Windows-Builder`: Unreal/Visual Studio/GPU build machine.
|
||||
- `Agrarian-TileServer`: dedicated Ubuntu VM for MVP tile delivery.
|
||||
|
||||
Current public tile DNS:
|
||||
|
||||
```text
|
||||
maps.agrariangame.com:18080
|
||||
```
|
||||
|
||||
Infrastructure rules:
|
||||
|
||||
- do not run project application services directly on the Unraid OS;
|
||||
- run services inside VMs or external hosts;
|
||||
- keep the tile server small and static for MVP;
|
||||
- keep GitHub/LFS usage within free-tier guardrails as long as practical;
|
||||
- avoid committing generated build output, local caches, or secrets.
|
||||
|
||||
## Source Control And Assets
|
||||
|
||||
The repo uses Git plus Git LFS for Unreal binary assets.
|
||||
|
||||
Rules:
|
||||
|
||||
- commit source, config, docs, scripts, and curated assets;
|
||||
- do not commit `Binaries/`, `Intermediate/`, `Saved/`, local build artifacts,
|
||||
or generated packages;
|
||||
- keep large generated terrain packages out of Git unless explicitly curated;
|
||||
- prefer small, focused commits tied to roadmap items;
|
||||
- do not commit credentials or machine-local configuration.
|
||||
|
||||
The project currently has unrelated `.uasset` modifications in the working tree
|
||||
from prior editor activity. Do not stage those unless intentionally addressing
|
||||
that content.
|
||||
|
||||
## Security And Secrets
|
||||
|
||||
Secrets must stay out of the repository and handoff files.
|
||||
|
||||
Examples:
|
||||
|
||||
- DigitalOcean API tokens;
|
||||
- server passwords;
|
||||
- Mailgun credentials;
|
||||
- database passwords;
|
||||
- private SSH keys;
|
||||
- admin reset files.
|
||||
|
||||
Use environment variables, machine-local config, or secret managers for
|
||||
credentials. Documentation may describe where a secret is expected, but should
|
||||
not include secret values.
|
||||
|
||||
## Testing Gates
|
||||
|
||||
Minimum gate for code changes:
|
||||
|
||||
- relevant C++ compiles through Windows-Builder;
|
||||
- relevant Unreal Python verification passes when touching maps/assets;
|
||||
- targeted script checks pass when touching scripts/data;
|
||||
- docs-only changes receive a text sanity check.
|
||||
|
||||
Minimum gate for milestone/demo builds:
|
||||
|
||||
- editor build succeeds;
|
||||
- Ground Zero map check passes;
|
||||
- playable loop smoke test passes;
|
||||
- package launches on Windows test machine;
|
||||
- current roadmap milestone is marked complete;
|
||||
- known blockers are documented.
|
||||
|
||||
## Near-Term Technical Priorities
|
||||
|
||||
Next technical foundation work should focus on:
|
||||
|
||||
- technical details for multiplayer/networking;
|
||||
- persistence contract and versioning;
|
||||
- Earth-scale tile streaming design;
|
||||
- real-weather provider adapter;
|
||||
- real-region day/night presentation;
|
||||
- local tile cache layout and retention;
|
||||
- MVP character-selection landing page;
|
||||
- first closed-test readiness gate.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should public tile serving remain on the LAN-hosted `Agrarian-TileServer` VM
|
||||
during closed testing, or move to an external cloud host before testers join?
|
||||
- Which persistence backend should replace or supplement file saves first?
|
||||
- How much client prediction is needed for gathering, inventory, and building?
|
||||
- What is the first stable dedicated server packaging target?
|
||||
- Which systems need migration/versioning before the first closed test?
|
||||
- How much real sunrise/sunset accuracy is needed before the MVP feels
|
||||
regionally grounded?
|
||||
Reference in New Issue
Block a user