AgrarianGameArchive/Docs/TechnicalDesignDocument.md

# 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; completed for the current C++ game-state default.
- add sunrise/sunset lookup or approximation by latitude/longitude; completed as a tile-aware NOAA approximation in `AAgrarianGameState`.
- map real weather snapshots into internal Agrarian weather states;
- cache weather snapshots server-side;
- keep deterministic fallback weather when external data is unavailable.

The repeatable solar metadata data path is
`Scripts/generate_tile_solar_metadata.py`. It reads the tile registry and emits
metadata only for source-backed, generated, validated, packaged, or published
tiles with explicit time-zone data. Placeholder/unknown tiles are skipped so the
future Earth-scale registry does not generate or fetch data for theoretical
tiles that do not exist yet.

Calendar conversion helpers live in `AAgrarianGameState` and keep the MVP target
of `4 real hours = 1 in-game day`. The same game state now exposes replicated
calendar year/day, absolute-day, season, real-hour conversion, long-task
progress, and crop-season fit helpers. Crop checks use the active tile's
growing-zone profile, including frost-free days and a crop safety buffer, so a
long-maturity crop can be rejected or marked marginal in regions with short
seasons.

The repeatable growing-zone metadata data path is
`Scripts/generate_tile_growing_zone_metadata.py`. It reads the tile registry and
emits metadata only for source-backed, generated, validated, packaged, or
published tiles with explicit growing-zone data. Ground Zero currently uses a
conservative Pacifica coastal profile; later regional expansion should replace
or enrich these overrides with authoritative zone, climate, and temperature
datasets.

## 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?