AgrarianGameArchive/Docs/CoreDesignDocument.md

# Agrarian Core Design Document

## Purpose

Agrarian is a persistent generational civilization simulator about rebuilding
human society from the ground up. It starts as a grounded survival game and
grows into stewardship, family, labor, trade, governance, technology, and
legacy.

The central question is:

> What survives after you are gone?

The core design goal is to make that question playable. A player's work should
leave evidence in the world, affect other players, and matter beyond a single
session.

## Design Pillars

### Civilization Is Built

The world should not hand players a finished civilization. Players begin with
hands, local resources, and limited knowledge. Tools, shelter, food systems,
settlements, trade, governance, and technology are built through player effort.

### Legacy Matters

Progress is not just a level number. Legacy includes knowledge, shelter,
stored supplies, land improvements, social trust, family lines, infrastructure,
maps, records, and institutions.

### The World Remembers

Agrarian should avoid seasonal wipes as a design crutch. The long-term game
should preserve meaningful history wherever feasible. If something changes or
decays, that change should be explainable inside the world.

### The Frontier Always Exists

The map should grow over time through real-world terrain tiles. New territory
creates room for exploration, settlement, conflict, opportunity, and fresh
stories without erasing old territory.

### Knowledge Is Progression

Players should become more capable because they learn recipes, techniques,
locations, seasons, risks, social relationships, and production chains.
Character skills can support that, but knowledge should remain the heart of
progression.

### Real Place, Believable Pace

Terrain, weather, day/night presentation, resources, water, elevation, and
biomes should be grounded in the real Earth region represented by each tile.
Travel and basic physical actions should stay close to believable real-world
pace. The MVP gameplay calendar uses `4 real hours = 1 in-game day`, while
sunlight and weather direction should still respect the represented region.

### Hard Beginnings, Earned Ease

The early game should be difficult, hands-on, inefficient, and a little
fragile. Progress should make survival less frantic through tools, storage,
shelter, food systems, domestication, teamwork, and infrastructure rather than
making the world feel artificial.

## Target Player Experience

The player should feel like they are entering a real place with limited means.
They should need to observe, gather, drink, eat, avoid exposure, improvise
tools, build shelter, and learn the land.

Over time, the same player should be able to look back and see a trail of
meaningful change:

- a safer camp;
- a reliable water source;
- stored food and materials;
- better tools;
- paths, markers, and local knowledge;
- domesticated plants or animals;
- trade relationships;
- a settlement;
- records, traditions, and inherited advantages.

The emotional arc should move from "I might not make it through the night" to
"what I build here may outlast me."

## MVP Experience

The first playable MVP is not the full civilization game. It is the smallest
strong proof that the survival foundation, real terrain direction, and
persistent world direction can work together.

The MVP starts on the Ground Zero tile and should prove:

- the player can enter the world after splash/startup and character selection;
- the map is based on a real 1 km x 1 km tile;
- the tile package can be served and verified from the tile server;
- basic survival pressure works;
- the player can gather resources;
- the player can drink or collect water;
- the player can craft at least one useful tool;
- the player can make or use fire;
- the player can build or use primitive shelter;
- weather and time influence survival;
- one meaningful death path exists;
- state can survive restart;
- at least two players can join the same server for a smoke test.

The MVP should feel like the beginning of Agrarian, not a generic Unreal
template or a generic survival sandbox.

## Core Loop

The first loop is:

1. Observe the environment.
2. Gather immediate resources.
3. Solve thirst, hunger, warmth, and shelter.
4. Craft better tools.
5. Reduce risk through storage, fire, shelter, and local knowledge.
6. Persist progress.
7. Return with an advantage and take on a larger goal.

The long-term loop expands into:

1. Improve survival reliability.
2. Domesticate plants and animals.
3. Build durable infrastructure.
4. Specialize labor and knowledge.
5. Trade and cooperate.
6. Govern shared spaces.
7. Preserve legacy for successors.
8. Push into new frontier tiles.

## World Model

Agrarian's long-term world is Earth-scale in intent. Tiles are 1 km x 1 km and
can be added over many years. The game should not require all tiles to exist at
launch. Instead, it should support a growing world where terrain data,
metadata, packages, cache rules, and server delivery can mature over time.

Important world commitments:

- real elevation and terrain should guide playable landforms;
- ocean depth, mountains, rivers, lakes, coastlines, biomes, and natural
  resources should come from real data where feasible;
- tile packages should be versioned;
- clients should cache tiles locally and redownload them when needed;
- unused local tiles can eventually be scrubbed by cache policy;
- player state must not be corrupted when terrain data improves.

## Time And Weather

Agrarian separates gameplay calendar pacing from real-world environmental
context.

For the MVP:

- gameplay calendar target: `4 real hours = 1 in-game day`;
- day/night presentation should mimic the represented real region;
- weather should come from or map toward the represented real region;
- time and weather should affect survival pressure.

For the long-term game:

- crops, livestock, aging, pregnancy, spoilage, disease, healing, soil
  recovery, and seasons should use the Agrarian calendar;
- skill and infrastructure should improve efficiency, yield, quality,
  reliability, and capacity;
- natural biological time should not be shortened casually just to make
  progression faster.

## Survival Philosophy

Survival should be grounded and legible. Players should usually understand why
they are in danger.

Core pressures:

- thirst;
- hunger;
- cold and exposure;
- injury and damage;
- weather;
- darkness;
- limited carrying capacity;
- unreliable early fire and shelter;
- inefficient early gathering.

Death should be possible. Starting over should hurt. The cost does not need to
be fully generational in the MVP, but it should be enough for survival to
matter.

## Progression Philosophy

Progression should favor capability over abstraction.

Better players and communities should gain:

- better tools;
- better shelter;
- safer water;
- more reliable food;
- storage;
- preserved materials;
- local map knowledge;
- recipes and techniques;
- domestication;
- infrastructure;
- labor specialization;
- trade;
- governance;
- inherited advantages.

Skills should not turn the game into a speed-run abstraction. They should make
players more competent inside a believable world.

## Multiplayer And Society

Agrarian should support cooperation from the foundation. Even the MVP should be
validated with at least two players joining the same server.

The long-term social direction includes:

- shared labor;
- trade;
- land use;
- family and inheritance;
- records and agreements;
- settlement governance;
- conflict and consequences;
- community value around AGR without pay-to-win mechanics.

The game should make cooperation powerful without making solo survival
impossible at the start.

## Economy And AGR

AGR should have both in-game and real-world community value, but it must not
become pay-to-win. Economy design should come after the survival and persistence
foundation is stable.

Early economy design must protect:

- fair access to survival;
- no loot boxes;
- no fragmented DLC model;
- no purchasable dominance;
- clear separation between community value and gameplay fairness.

## Non-Goals For The First Playable MVP

Do not block the first playable MVP on:

- full Earth-scale streaming;
- polished public release UX;
- Steam or Epic launch setup;
- complete farming and livestock systems;
- complete family/generation systems;
- full economy or AGR utility;
- mature settlement governance;
- polished final character art;
- full real-weather provider integration;
- complete sunrise/sunset astronomy accuracy.

## Design Risks

Primary risks:

- too much realism can become tedious;
- too much compression can break the core identity;
- real-world terrain can become a data pipeline project before the survival
  loop is fun;
- persistence can preserve bugs if data contracts are weak;
- economy and AGR can damage trust if introduced before gameplay fairness is
  clear;
- scope can drift into the long-term vision before the MVP is playable.

Mitigation:

- keep the MVP narrow;
- make each system prove one playable thing before expanding;
- document data contracts early;
- separate prototype content from real game content;
- preserve build and restore paths;
- test with real players before adding more breadth.

## Current Design Decisions

- Ground Zero is the first MVP tile.
- The MVP tile is 1 km x 1 km.
- The MVP gameplay calendar target is `4 real hours = 1 in-game day`.
- Day/night presentation should mimic the represented Earth region.
- Weather should map toward the represented Earth region.
- Real-world travel pace remains a core commitment.
- The public tile endpoint currently uses `maps.agrariangame.com:18080`.
- The first tile server runs inside the dedicated `Agrarian-TileServer` VM.
- Unused Unreal starter variants have been removed.
- ThirdPerson and LevelPrototyping content remain temporarily while still
  referenced by current player Blueprint and prototype automation.

## Follow-Up Documents

This core design document intentionally leaves detailed implementation to the
next foundation documents:

- technical design document;
- multiplayer/networking design document;
- persistence design document;
- Earth-scale terrain/tile streaming design document;
- economy and AGR design document;
- art direction, UX/HUD direction, coding standards, Blueprint standards, and
  asset/folder naming standards.