424 lines
12 KiB
Markdown
424 lines
12 KiB
Markdown
# 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.
|