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.

Inventory data is defined in Docs/InventoryDataModel.md. The MVP model uses stable ItemId keys, design-time FAgrarianItemDefinition records, runtime and save-game FAgrarianItemStack records, and a server-authoritative UAgrarianInventoryComponent with replicated stack arrays. Pickup, drop, splitting, item use, equipment, carry capacity, persistence, and UI work should extend that contract rather than inventing parallel inventory state.

World pickups use AAgrarianItemPickup, an interactable replicated actor with a static mesh and either a definition-backed or inline FAgrarianItemStack. Player interaction already routes to the server through the Agrarian character, so pickups validate authority, produce a valid stack, add it to the player's inventory, and only then remove the pickup by destroying the world pickup actor. If the inventory is full or the stack is invalid, the pickup remains in the world for another attempt.

Developer item dropping is available through AgrarianDropItem ItemId Quantity. The command routes to the server, extracts stack data before spawning so display name and unit weight survive the drop, spawns an AAgrarianItemPickup in front of the player, and restores the removed stack if pickup spawning fails. This is the baseline behavior future UI-driven drop flows should call through rather than duplicating inventory mutation logic on the client.

Stack splitting is available through AgrarianSplitStack StackIndex SplitQuantity and UAgrarianInventoryComponent::SplitStackByIndex. Splitting is server-authoritative, validates the source stack index, quantity, and free slot capacity, copies the source stack metadata, reduces the source quantity, and creates a separate inventory slot. It intentionally does not re-merge the split stack through AddItem, because the UI needs an actual separate stack to support later drag/drop and partial drop flows.

MVP item use is available through AgrarianUseItem ItemId Quantity. The command routes to the server, extracts the requested stack quantity, applies a whitelisted item effect, and restores the stack if the item is not usable yet. For the first survival loop, food restores hunger, meat restores more hunger but adds sickness risk because it is raw, and bandage reduces injury severity with a small health bump. This gives UI item-use work a concrete authority path while leaving tools, structures, and future complex consumables blocked until they have explicit gameplay rules.

Dedicated equipment slots are intentionally deferred for the 0.1.E MVP. The current basic_tool item can remain an inventory item until an implemented system needs active hand, worn, backpack, armor, weapon, durability, animation, or mesh-attachment state. When that need appears, equipment should be added as server-authoritative, replicated, persisted slot state rather than as local UI selection only.

Carry capacity is active as an MVP placeholder through stack UnitWeight, inventory GetTotalWeight, and character movement penalties. The current character uses 25.0 comfort and 60.0 heavy item-weight thresholds, scales those thresholds by strength, and exposes current carried weight in the debug HUD. Future backpacks, containers, awkward-object rules, and hard overload limits should extend this total-weight path rather than creating a second carry model.

The MVP inventory UI is a compact AAgrarianDebugHUD inventory panel, enabled separately from the full developer HUD. It reads the replicated inventory stack array, shows occupied slots, total carried weight, and a short visible stack list, and leaves mutation actions on the existing server-authoritative commands and RPCs until a full UMG inventory screen is introduced.

Inventory persistence saves UAgrarianInventoryComponent::Items into FAgrarianSavedPlayer::Inventory and restores through UAgrarianInventoryComponent::RestoreSavedItems. Restore broadcasts OnInventoryChanged, which keeps the MVP HUD panel and future UI listeners in sync after load while preserving total weight as a derived value.

Time And Environment

The MVP gameplay calendar target is:

4 real hours = 1 in-game day

The current C++ default is:

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.

Temperature is authoritative on AAgrarianGameState. The MVP curve uses the active tile's sunrise and solar noon to place the daily low near sunrise and the daily high after solar noon, then applies weather modifiers for rain, cold wind, and storms. Regional daily low/high values provide the deterministic fallback. When a server-side weather adapter is available, it should set observed regional temperature and blend weight through the game-state hook rather than allowing clients to call public weather APIs directly. This keeps real-world temperature and weather tied to the represented map tile while preserving a deterministic fallback if an external provider is unavailable.

Primitive shelters expose a replicated protection volume and WeatherProtection rating. Server-side survival ticks calculate the best overlapping shelter protection for each character, replicate the current protection value, reduce ambient weather exposure and cold damage by that percentage, and trend the care-history shelter quality field toward the active protection level. The dev HUD shows current shelter protection so weather pressure can be tuned during MVP tests.

Weather exposure zones use AAgrarianWeatherExposureZone volumes placed by the Ground Zero setup script. They describe local ridge, coastal-wind, and drainage cooling effects with an exposure multiplier and temperature offset. Server-side survival ticks select the strongest overlapping zone effect, replicate the current multiplier and offset, then apply them to ambient body-temperature drift and cold damage after shelter protection. This lets future generated tiles add biome, slope, elevation, hydrology, and coastal modifiers without changing the core survival calculation.

The safe Ground Zero spawn is selected by Scripts/setup_ground_zero_demo_map.py from declared candidate coordinates and a known safe fallback coordinate. The setup validates the selected player start against terrain elevation, terrain slope, a minimum above-terrain Z offset, freshwater spacing, and resource-cluster spacing before saving the map. Scripts/verify_ground_zero_safe_spawn.py rechecks the placed AGR_DemoPlayerStart against the same constraints so future map, resource, water, or terrain changes cannot silently move the player below sea level, into steep terrain, into water, or into a dense resource cluster.

The Ground Zero map also contains AGR_GroundZeroMapBoundary, a native AAgrarianMapBoundaryVolume centered on the 1 km x 1 km MVP tile. For the MVP, the boundary clamps server-authoritative player pawns back inside the loaded tile with a small padding rather than allowing players to walk into missing neighbor terrain. The actor exposes a warning distance hook so later UI can present an in-world or HUD notice before a clamp occurs.

Developer testing supports server-authoritative developer travel through AgrarianTravel X Y Z on AAgrarianGamePlayerController. The command teleports the controlled pawn to explicit Unreal world coordinates, stops any current character movement, and reports the destination to the issuing player. AgrarianTravelHome returns the player to the validated Ground Zero safe-spawn fallback near AGR_DemoPlayerStart, above sea level and above terrain by the same safe offset used by the map setup pass.

First-pass sky and lighting use AAgrarianSkyLightingController. The controller owns movable sun, skylight, and exponential-height-fog components and reads the replicated AAgrarianGameState time, active tile sunrise/sunset, weather state, and mapped cloud cover. It adjusts sun pitch, sun intensity/color, sky-light intensity, and fog density every tick so the Ground Zero demo visually tracks the represented local day/night cycle and current weather without hard-coded static light settings. The Ground Zero map setup script places this controller and removes the earlier static demo sun/skylight/fog actors.

First-pass weather audio uses AAgrarianWeatherAudioController. The controller owns ambient, rain, wind, and storm audio components with assignable loop sound slots. It reads replicated weather state, provider wind speed, provider cloud data, and local night/day state, then fades component volumes so rain, wind, and storm cues follow the same authoritative weather mapping used by temperature and lighting. The current MVP can ship without final sound assets because the controller is silent until loops are assigned; placeholder or final audio can be added by setting the exposed sound properties on the placed controller or a Blueprint child.

The first real-weather adapter is UAgrarianWeatherProviderSubsystem. It uses Open-Meteo forecast requests keyed by tile center latitude/longitude, parses the current temperature, daily low/high, precipitation, wind, humidity, cloud cover, pressure, provider timestamp, and weather code, then applies the mapped state to AAgrarianGameState on the server. It is tile-driven rather than Ground-Zero hard-coded: Scripts/generate_tile_weather_manifest.py emits every source-backed, generated, validated, packaged, or published tile with center coordinates, while placeholder/unknown tiles are skipped. Future source-backed tiles therefore become weather-eligible when their registry entries are added.

Ground Zero weather lookup coordinates are explicit in the tile registry. The current MVP tile gz_us_ca_pacifica_utm10n_e544_n4160 uses its tile center, latitude 37.5925 and longitude -122.4995, as the canonical real-world weather lookup point. Scripts/generate_tile_weather_manifest.py reads weather_lookup_metadata when present, falls back to the tile center for source-backed tiles, and emits the provider routing used by the weather subsystem.

Open-Meteo is the first global MVP weather source. The provider contract is stored in Data/Weather/open_meteo_mvp_source.json, including the forecast endpoint, requested current/daily variables, tile lookup rule, and Agrarian mapping notes. Scripts/verify_open_meteo_mvp_source.py validates the static contract and can perform a live Open-Meteo request for every source-backed tile in Data/Tiles/tile_weather_manifest.json. This keeps the provider global for all future real tiles instead of adding one-off Ground Zero weather code.

NOAA/NWS is the US-only fallback and enrichment path. The provider contract is stored in Data/Weather/noaa_nws_us_fallback.json. The weather provider subsystem can check whether an active tile center coordinate is inside the approximate NWS coverage window, request api.weather.gov/points/{lat},{lon}, follow properties.forecastGridData, and parse gridded temperature, precipitation probability, and wind speed as fallback inputs. The NWS path is only used for eligible US/NWS-covered tiles; Open-Meteo remains the global source for all tiles.

Real-weather snapshots are cached server-side in UAgrarianWeatherProviderSubsystem::ServerWeatherSnapshotCache. Cache keys use provider plus tile ID, and the default TTL is 15 minutes. Server requests first try to apply a fresh cached snapshot to AAgrarianGameState; only cache misses call Open-Meteo or NOAA/NWS. Clients never call Open-Meteo or NOAA/NWS directly. They receive weather, temperature, source, and state through replicated game state fields.

Real-weather provider values are mapped into FAgrarianMappedWeatherInputs before they affect gameplay. The mapped snapshot keeps tile ID, tile center coordinate, temperature, precipitation, wind, cloud cover, humidity, pressure, visibility, and provider weather code available alongside the collapsed Agrarian weather state. Open-Meteo fills those fields directly where available; NOAA/NWS fills them from grid data where available and derives provisional visibility/weather-state values until a deeper provider-specific mapping pass is added.

The applied weather state also has a replicated debug snapshot: FAgrarianWeatherDebugSnapshot. It records the weather source, provider timestamp, tile ID, tile center coordinate, provider weather code, input values, and final in-game EAgrarianWeatherType after mapping. Save files persist both the mapped inputs and the applied debug snapshot so weather issues can be traced back to a specific provider response and tile without inferring those values from separate systems.

Deterministic fallback weather keeps the game playable when external providers are disabled, unreachable, or return unusable data. The fallback snapshot is derived from tile ID and Agrarian day, then mapped through the same FAgrarianMappedWeatherInputs path as live providers. It produces seasonal daily low/high temperatures, current temperature, cloud cover, humidity, wind, pressure, precipitation, visibility, and the collapsed Agrarian weather state. Fallback snapshots use provider deterministic-fallback and are cached server-side with the normal weather cache TTL.

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:

http://maps.agrariangame.com:18080

Current backing VM:

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.

Gatherable Resources

The 0.1.F resource baseline uses AAgrarianResourceNode for simple gatherable world resources. Wood, fiber, stone, and edible plants each have item definitions or yield definitions, resource Blueprints, deterministic Ground Zero placements, replicated remaining harvest counts, and bare-hand gathering through the shared interaction path.

Stone specifically is represented by DA_Item_Stone and BP_StoneResourceNode. Ground Zero includes stone nodes in slope, exposed terrain, and valley-edge positions so primitive tools, campfires, and early construction recipes have an in-world source instead of relying on debug grants. Edible plants are represented by BP_EdiblePlantResourceNode, which yields the MVP food item from scrub, grassland, and drainage-candidate forage patches.

Freshwater gathering uses AAgrarianWaterSource instead of the depleting resource-node class. The placed BP_FreshWaterSource is still an IAgrarianInteractable, appears through the same focused interaction prompt, and restores thirst through UAgrarianSurvivalComponent::AddWater on server authority. This keeps drinking compatible with the existing replicated survival component while leaving later container filling, water quality, and source depletion rules for future water-system work.

For the MVP, renewable MVP resource nodes respawn only after they are fully depleted. Wood, fiber, and edible plant nodes are renewable because they represent surface materials and forage that should return during continued prototype play. Stone remains nonrespawning because it represents a slower geologic resource and should push players to explore once local easy stone is gone. Respawn timing is configurable per Blueprint through bRespawnsForMvp, RespawnDelaySeconds, and MaxHarvests; the native node uses a server-side timer and restores replicated RemainingHarvests when the delay expires.

Tool requirement rules remain inventory-based for the MVP because dedicated equipment slots are deferred. A resource node can declare RequiredToolItemId, bAllowBareHandGathering, and ToolQuantityBonus. Current Ground Zero wood, fiber, and stone nodes still allow bare-hand gathering so the first survival loop cannot deadlock before the player can craft a tool. When the player has a basic_tool in inventory, those nodes grant an extra unit per harvest. Edible plants remain pure bare-hand gathering. Later nodes can disable bAllowBareHandGathering when the game has proper tool equipment, durability, and feedback UI.

Wildlife Navigation

MVP wildlife movement is server authoritative. AAgrarianWildlifeBase uses an AI controller and Unreal navigation when nav data exists: wander targets are chosen from reachable nav points, chase/flee targets are projected onto navmesh, and movement requests use MoveToLocation. If a test map or early generated tile has no nav data, wildlife falls back to direct movement input so damage, flee, chase, and harvest loops remain functional while map navigation is being authored.

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:

Scripts\BuildEditor-Windows.bat

Codex runs this through Windows-Builder using:

/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:

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.

Performance Profiling

Agrarian gameplay code exposes a dedicated Unreal stat group named STATGROUP_Agrarian. Use stat Agrarian during editor or packaged sessions for game-specific cycle counters, and capture Unreal Insights traces for matching CPU scopes. The current markers cover authoritative game-state time/weather ticking, survival ticking, sky-light refresh, weather-audio refresh, foliage instance mutation, and weather-provider request/parse/fallback work.

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?