# Agrarian Art, UX, Code, Blueprint, And Asset Standards

## Purpose

Agrarian needs a consistent foundation before the project grows into many maps,
tiles, systems, artists, designers, and code contributors. These standards keep
the project readable, buildable, and aligned with the game's tone while still
leaving room for prototype speed.

This document covers:

- art direction;
- UX and HUD direction;
- Unreal content folders;
- asset naming;
- C++ coding standards;
- Blueprint standards;
- data asset standards;
- save/persistence standards.

## Art Direction

Agrarian should feel grounded, tactile, and region-specific. The world begins
hard and sparse, then becomes more ordered as players build shelter, storage,
farms, settlements, roads, and infrastructure.

Visual goals:

- believable real-world terrain first;
- natural materials and practical construction;
- visible player labor and wear;
- readable survival state without heavy fantasy language;
- environmental storytelling through camps, paths, water access, stored goods,
  fences, tools, and damaged or repaired structures;
- technology progression that visibly moves from hand-built to engineered.

Avoid:

- generic fantasy styling;
- neon sci-fi treatment for survival-era systems;
- overly clean buildings during early survival;
- decorative UI or props that obscure resource state;
- assets that ignore the represented real-world tile and biome.

Ground Zero target:

- coastal California terrain, scrub, grassland, rock, slope, wind, fog, and
  water access should guide early visual decisions;
- placeholder assets are acceptable only when clearly organized as prototype
  content;
- future production passes should replace generic starter shapes with
  region-appropriate materials, vegetation, rocks, shoreline treatment, and
  weathered survival props.

## Character Direction

MVP character selection should support realistic male and female young-adult
characters with average proportions. Characters should look practical and
believable in a survival setting.

Early rules:

- no exaggerated heroic silhouettes for default characters;
- clothing should read as practical, worn, and climate-aware;
- future MetaHuman use is acceptable if performance, licensing, and build size
  remain manageable;
- character customization should not block the first playable MVP.

## UX And HUD Direction

The UX should be quiet, readable, and useful under survival pressure. The game
should not feel like a spreadsheet, but players must understand why they are
hungry, thirsty, cold, injured, overloaded, or unable to craft.

HUD priorities:

- health;
- stamina;
- hunger;
- thirst;
- body temperature/exposure;
- injury;
- interaction prompt;
- carried weight or capacity when relevant;
- current weather/time cues;
- inventory/crafting/building feedback.

UX rules:

- show critical survival risk early and clearly;
- avoid permanent clutter for non-critical details;
- use diegetic cues where they help, but do not hide essential survival state;
- make interaction prompts short and specific;
- keep error messages actionable;
- keep admin/debug HUD separate from player-facing HUD;
- support keyboard/mouse and gamepad from the start where practical;
- avoid UI that requires precise small clicks during urgent survival actions.

Tone:

- direct and plain;
- no jokey system text for serious survival states;
- no technical implementation language in player-facing copy;
- no blockchain or wallet language in the survival HUD.

## Startup And Demo UX

The current demo startup flow should preserve:

- Agrarian Studio splash/startup identity;
- Unreal/Epic attribution where required;
- copyright and demo notice language;
- motto: `What survives after you are gone?`;
- version and beta/demo status where appropriate;
- transition into character selection before gameplay.

The startup sequence should be short enough for repeated testing. Long cinematic
presentation can come later.

## Content Folder Standards

All Agrarian-owned gameplay content belongs under:

```text
Content/Agrarian/
```

Current root folders:

```text
Content/Agrarian/Blueprints/
Content/Agrarian/DataAssets/
Content/Agrarian/Maps/
```

Standard target folders:

```text
Content/Agrarian/Audio/
Content/Agrarian/Blueprints/
Content/Agrarian/Characters/
Content/Agrarian/DataAssets/
Content/Agrarian/Developer/
Content/Agrarian/Environment/
Content/Agrarian/Maps/
Content/Agrarian/Materials/
Content/Agrarian/Prototypes/
Content/Agrarian/UI/
```

Blueprint subfolders:

```text
Content/Agrarian/Blueprints/Characters/
Content/Agrarian/Blueprints/Resources/
Content/Agrarian/Blueprints/Structures/
Content/Agrarian/Blueprints/Systems/
Content/Agrarian/Blueprints/Wildlife/
Content/Agrarian/Blueprints/World/
```

Data asset subfolders:

```text
Content/Agrarian/DataAssets/Items/
Content/Agrarian/DataAssets/Recipes/
Content/Agrarian/DataAssets/Resources/
Content/Agrarian/DataAssets/Structures/
Content/Agrarian/DataAssets/Wildlife/
Content/Agrarian/DataAssets/Weather/
```

Rules:

- Do not place Agrarian production assets in template root folders.
- Keep starter/template dependencies isolated until replaced.
- Keep experimental content in `Prototypes` or `Developer`.
- Do not commit Derived Data Cache, packaged builds, generated tile packages, or
  local editor output.
- Before moving existing `.uasset` files, use the Unreal Editor or validated
  redirector fixup path, not raw file moves.

## Asset Naming Standards

Use clear Unreal-style prefixes and descriptive names.

Core prefixes:

```text
BP_      Blueprint class
WBP_     Widget Blueprint
DA_      Data Asset
DT_      Data Table
E_       Enum asset
S_       Static mesh
SK_      Skeletal mesh
SM_      Static mesh, acceptable when imported source already uses SM_
M_       Material
MI_      Material instance
T_       Texture
NS_      Niagara system
A_       Animation sequence
ABP_     Animation Blueprint
L_       Level/map
IA_      Enhanced Input action
IMC_     Enhanced Input mapping context
SFX_     Sound effect
MX_      Music
```

Name shape:

```text
Prefix_Category_SpecificName_Variant
```

Examples:

```text
BP_Resource_WoodNode
BP_Structure_PrimitiveShelter
DA_Item_Wood
DA_Recipe_Campfire
WBP_HUD_Survival
L_GroundZeroTerrain_Test
MI_WoodWeathered_01
T_GroundZero_ScrubAlbedo
```

Rules:

- Use ASCII letters, numbers, and underscores.
- Do not use spaces in asset names.
- Do not use vague names like `NewBlueprint`, `Test2`, or `FinalFinal`.
- Include `Prototype` or place in `Prototypes` for throwaway work.
- Include `_Test` only for test maps/assets.
- Preserve stable item and recipe IDs once used by saves.
- Do not rename persisted data assets without a migration plan.

## Data Asset Standards

Data assets describe content. C++ and server authority enforce rules.

Required data asset behavior:

- stable ID field such as `ItemId` or `RecipeId`;
- human-readable display name;
- short description where player-facing;
- version or migration notes once the asset can affect saves;
- conservative defaults that do not break multiplayer;
- no secrets, credentials, local file paths, or machine-specific values.

Rules:

- Item IDs and recipe IDs use stable snake_case or FName-safe identifiers.
- Display text can change; IDs should not change casually.
- Data assets can expose tuning, but server code validates outcomes.
- Save data stores IDs and quantities, not copied data asset contents.
- Any asset referenced by a save, recipe, loot table, or trade record must have
  a compatibility note before removal.

## Save And Persistence Standards

Persistent records are long-lived contracts.

Rules:

- Include record version fields.
- Include game build/version where useful.
- Include tile ID and tile package version when position or world state matters.
- Store IDs and state, not full static definitions.
- Keep terrain/tile metadata external and referenced by ID.
- Log migrations.
- Back up saves before destructive migrations.
- Never store passwords, private keys, wallet secrets, API tokens, or admin
  credentials.

Save-facing assets:

- item data assets;
- recipe data assets;
- placed structure classes;
- tile IDs/package versions;
- future account/player IDs.

Renames/removals of save-facing assets need a migration or compatibility alias.

## C++ Coding Standards

Agrarian is a hybrid Unreal project: C++ owns core replicated gameplay and
Blueprints assemble content and presentation.

Style:

- follow Unreal Engine C++ conventions;
- use `A`, `U`, `F`, `E`, and `I` prefixes correctly;
- prefer explicit, small classes over broad manager objects;
- keep server authority clear in naming and implementation;
- keep comments short and useful;
- avoid storing gameplay truth only in Blueprint when C++ authority exists.

Headers:

- include `CoreMinimal.h` first unless a file has a specific Unreal reason not
  to;
- forward declare where practical;
- include generated header last;
- keep public API small.

Replication:

- server validates gameplay requests;
- replicated properties use `OnRep` when clients need presentation updates;
- do not trust client inventory, survival, crafting, trade, or placement data;
- RPCs should be narrow and action-specific.

Categories:

- use `Agrarian|SystemName` for public Blueprint-exposed properties/functions;
- keep existing categories consistent when touching a class;
- do not expose internal-only state to Blueprint unless a designer or test path
  needs it.

Testing expectations:

- compile after C++ changes;
- add or update automation tests when changing shared gameplay contracts;
- run relevant Unreal command-mode checks when touching maps, assets, or
  Blueprint-dependent flows.

## Blueprint Standards

Blueprints are for content assembly, presentation, and designer-facing
configuration. They should not hide authoritative logic that needs to be
validated, replicated, tested, or migrated.

Rules:

- Use parent C++ classes for replicated gameplay actors when possible.
- Keep event graphs small and readable.
- Move repeated logic into functions, macros, components, or C++.
- Name variables clearly and avoid ambiguous temporary names.
- Do not store secrets or machine-specific paths in Blueprint defaults.
- Do not create critical inventory, survival, trade, or persistence changes
  purely on the client.
- Keep debug-only Blueprint behavior visibly labeled and out of production
  paths.

Blueprint naming:

- `BP_Resource_*`
- `BP_Structure_*`
- `BP_Wildlife_*`
- `BP_World_*`
- `BP_System_*`
- `WBP_*` for widgets.

Blueprint validation checklist:

- Does it have the correct parent class?
- Are replicated properties owned by the server?
- Are exposed defaults intentional?
- Does it live in the correct folder?
- Does it reference prototype/template content knowingly?
- Does it pass map load and relevant smoke automation?

## UI Asset Standards

Use `WBP_` for Widget Blueprints and place them under:

```text
Content/Agrarian/UI/
```

or, while still organized by Blueprint type:

```text
Content/Agrarian/Blueprints/UI/
```

Player-facing widgets should be separated from:

- debug HUDs;
- admin tools;
- automation/test widgets;
- startup/demo notice widgets.

HUD assets should keep stable names once referenced by game mode, player
controller, or packaged demo startup paths.

## Prototype And Developer Content

Prototype content is allowed, but it must be obvious.

Use:

```text
Content/Agrarian/Prototypes/
Content/Agrarian/Developer/
```

Rules:

- prototype assets can be fast and rough;
- production systems should not depend on prototype assets without a roadmap
  note;
- before packaging investor/demo builds, check visible prototype content and
  decide whether it is acceptable for that build;
- delete unused prototype content when it is no longer referenced.

## Review Checklist

Before committing content or code:

- asset is under the correct folder;
- asset name has the correct prefix;
- save-facing IDs are stable;
- Blueprint changes do not bypass server authority;
- C++ changes compile;
- data assets do not contain secrets or machine-local paths;
- UI text is player-facing, clear, and not technical;
- large assets pass storage-policy review;
- roadmap and handoff updates are included when completing roadmap items.