Add Agrarian standards documentation
This commit is contained in:
@@ -0,0 +1,423 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user