AgrarianGameArchive/Docs/ArtUxCodeAndAssetStandards.md

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.

MVP Realism Target Rules

Investor-facing art work should move the project toward grounded realism even when the current asset is still an MVP proxy. A proxy is acceptable when it locks down gameplay scale, silhouette, material family, biome placement, or interaction readability that can survive into production. A cosmetic throwaway is not acceptable when it creates a style, color language, or object read that will have to be discarded before MVP.

Realism preservation rules:

• use real-world biome references for terrain color, vegetation density, water, rock, weather, shelter, tools, wildlife, and clothing decisions;
• prefer Agrarian-owned proxy meshes and materials over engine template assets so replacements can be staged without changing gameplay contracts;
• keep survival objects readable through practical construction logic: fuel, stone, ash, fabric, branches, stored goods, water edges, and worn surfaces;
• use lighting and fog that imply Pacific coastal conditions without requiring cinematic hardware settings;
• document any visible proxy that remains in investor builds, including what production-quality asset family should replace it;
• avoid cosmetic-only changes that make the world prettier while moving it away from the long-term realistic tone.

Current 0.1.O visual passes are production-directed proxies, not final art: character bodies, survival objects, foliage silhouettes, water-source dressing, and Ground Zero biome materials are expected to be replaced with higher-fidelity assets, but their scale, placement, material families, and gameplay readability should survive.

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:

Content/Agrarian/

Current root folders:

Content/Agrarian/Blueprints/
Content/Agrarian/DataAssets/
Content/Agrarian/Maps/

Standard target folders:

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:

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:

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:

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:

Prefix_Category_SpecificName_Variant

Examples:

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:

Content/Agrarian/UI/

or, while still organized by Blueprint type:

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:

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.