diff --git a/AGRARIAN_DEVELOPMENT_ROADMAP.md b/AGRARIAN_DEVELOPMENT_ROADMAP.md index e76ab2d..162e629 100644 --- a/AGRARIAN_DEVELOPMENT_ROADMAP.md +++ b/AGRARIAN_DEVELOPMENT_ROADMAP.md @@ -250,30 +250,30 @@ Current tooling decisions: - [x] Create tile registry/database design document. - [x] Create real-world terrain source data evaluation document. - [x] Create economy and AGR design document. -- [ ] Create art direction document. -- [ ] Create UX/HUD direction document. -- [ ] Create content naming conventions. -- [ ] Create folder conventions for Unreal assets. -- [ ] Create coding standards. -- [ ] Create Blueprint standards if using Blueprints. -- [~] Create data asset standards. -- [~] Create save/persistence standards. +- [x] Create art direction document. +- [x] Create UX/HUD direction document. +- [x] Create content naming conventions. +- [x] Create folder conventions for Unreal assets. +- [x] Create coding standards. +- [x] Create Blueprint standards if using Blueprints. +- [x] Create data asset standards. +- [x] Create save/persistence standards. ## 0.4 Project Structure - [x] Organize `Content/Agrarian/` root folder. -- [ ] Create folders for Characters. -- [ ] Create folders for Environment. -- [ ] Create folders for Items. -- [ ] Create folders for UI. -- [ ] Create folders for Systems. -- [ ] Create folders for Maps. -- [ ] Create folders for Materials. -- [ ] Create folders for Audio. -- [ ] Create folders for DataAssets. -- [ ] Create folders for Prototypes. -- [ ] Create folders for Developer-only test assets. -- [ ] Create naming convention for assets. +- [x] Create folders for Characters. +- [x] Create folders for Environment. +- [x] Create folders for Items. +- [x] Create folders for UI. +- [x] Create folders for Systems. +- [x] Create folders for Maps. +- [x] Create folders for Materials. +- [x] Create folders for Audio. +- [x] Create folders for DataAssets. +- [x] Create folders for Prototypes. +- [x] Create folders for Developer-only test assets. +- [x] Create naming convention for assets. - [x] Remove unused Combat, Platforming, and SideScrolling starter variant content. - [~] Move any starter content into clear prototype folders. Remaining ThirdPerson and LevelPrototyping assets are still referenced by current player Blueprints and automation. @@ -1436,11 +1436,11 @@ Earliest incomplete foundation items: - [x] Create the Earth-scale terrain/tile streaming design document. - [x] Launch near-term MVP map-tile serving cloud VM and prove Ground Zero tile lookup/download/cache flow. - [x] Create economy and AGR design document. -- [ ] Create art direction, UX/HUD direction, coding standards, Blueprint standards, and asset/folder naming standards. +- [x] Create art direction, UX/HUD direction, coding standards, Blueprint standards, and asset/folder naming standards. - [x] Organize `Content/Agrarian/` root folder and remove unused starter variant content. - [ ] Define what qualifies as the 6-month MVP and what is explicitly excluded. - [x] Define MVP day/night length, survival pressure target, success loop, failure conditions, first playable internal milestone, and closed-test readiness criteria. Immediate next item: -- [ ] Create art direction, UX/HUD direction, coding standards, Blueprint standards, and asset/folder naming standards. +- [ ] Define what qualifies as the 6-month MVP and what is explicitly excluded. diff --git a/Content/Agrarian/Audio/.gitkeep b/Content/Agrarian/Audio/.gitkeep new file mode 100644 index 0000000..65f0c49 --- /dev/null +++ b/Content/Agrarian/Audio/.gitkeep @@ -0,0 +1 @@ +# Keeps the Agrarian audio folder in source control. diff --git a/Content/Agrarian/Blueprints/Characters/.gitkeep b/Content/Agrarian/Blueprints/Characters/.gitkeep new file mode 100644 index 0000000..8597b80 --- /dev/null +++ b/Content/Agrarian/Blueprints/Characters/.gitkeep @@ -0,0 +1 @@ +# Keeps the Agrarian character Blueprint folder in source control. diff --git a/Content/Agrarian/Blueprints/Systems/.gitkeep b/Content/Agrarian/Blueprints/Systems/.gitkeep new file mode 100644 index 0000000..3d8cd6b --- /dev/null +++ b/Content/Agrarian/Blueprints/Systems/.gitkeep @@ -0,0 +1 @@ +# Keeps the Agrarian system Blueprint folder in source control. diff --git a/Content/Agrarian/Blueprints/UI/.gitkeep b/Content/Agrarian/Blueprints/UI/.gitkeep new file mode 100644 index 0000000..6f2cdae --- /dev/null +++ b/Content/Agrarian/Blueprints/UI/.gitkeep @@ -0,0 +1 @@ +# Keeps the Agrarian UI Blueprint folder in source control. diff --git a/Content/Agrarian/Characters/.gitkeep b/Content/Agrarian/Characters/.gitkeep new file mode 100644 index 0000000..da8b85a --- /dev/null +++ b/Content/Agrarian/Characters/.gitkeep @@ -0,0 +1 @@ +# Keeps the Agrarian character asset folder in source control. diff --git a/Content/Agrarian/DataAssets/Resources/.gitkeep b/Content/Agrarian/DataAssets/Resources/.gitkeep new file mode 100644 index 0000000..1fc8d62 --- /dev/null +++ b/Content/Agrarian/DataAssets/Resources/.gitkeep @@ -0,0 +1 @@ +# Keeps the Agrarian resource data asset folder in source control. diff --git a/Content/Agrarian/DataAssets/Structures/.gitkeep b/Content/Agrarian/DataAssets/Structures/.gitkeep new file mode 100644 index 0000000..087654f --- /dev/null +++ b/Content/Agrarian/DataAssets/Structures/.gitkeep @@ -0,0 +1 @@ +# Keeps the Agrarian structure data asset folder in source control. diff --git a/Content/Agrarian/DataAssets/Weather/.gitkeep b/Content/Agrarian/DataAssets/Weather/.gitkeep new file mode 100644 index 0000000..2cd96ef --- /dev/null +++ b/Content/Agrarian/DataAssets/Weather/.gitkeep @@ -0,0 +1 @@ +# Keeps the Agrarian weather data asset folder in source control. diff --git a/Content/Agrarian/DataAssets/Wildlife/.gitkeep b/Content/Agrarian/DataAssets/Wildlife/.gitkeep new file mode 100644 index 0000000..0559dcf --- /dev/null +++ b/Content/Agrarian/DataAssets/Wildlife/.gitkeep @@ -0,0 +1 @@ +# Keeps the Agrarian wildlife data asset folder in source control. diff --git a/Content/Agrarian/Developer/.gitkeep b/Content/Agrarian/Developer/.gitkeep new file mode 100644 index 0000000..22f9014 --- /dev/null +++ b/Content/Agrarian/Developer/.gitkeep @@ -0,0 +1 @@ +# Keeps the Agrarian developer-only asset folder in source control. diff --git a/Content/Agrarian/Environment/.gitkeep b/Content/Agrarian/Environment/.gitkeep new file mode 100644 index 0000000..4cbf81a --- /dev/null +++ b/Content/Agrarian/Environment/.gitkeep @@ -0,0 +1 @@ +# Keeps the Agrarian environment asset folder in source control. diff --git a/Content/Agrarian/Items/.gitkeep b/Content/Agrarian/Items/.gitkeep new file mode 100644 index 0000000..675fd8e --- /dev/null +++ b/Content/Agrarian/Items/.gitkeep @@ -0,0 +1 @@ +# Keeps the Agrarian item asset folder in source control. diff --git a/Content/Agrarian/Materials/.gitkeep b/Content/Agrarian/Materials/.gitkeep new file mode 100644 index 0000000..4afe89d --- /dev/null +++ b/Content/Agrarian/Materials/.gitkeep @@ -0,0 +1 @@ +# Keeps the Agrarian material asset folder in source control. diff --git a/Content/Agrarian/Prototypes/.gitkeep b/Content/Agrarian/Prototypes/.gitkeep new file mode 100644 index 0000000..f9e91fc --- /dev/null +++ b/Content/Agrarian/Prototypes/.gitkeep @@ -0,0 +1 @@ +# Keeps the Agrarian prototype asset folder in source control. diff --git a/Content/Agrarian/Systems/.gitkeep b/Content/Agrarian/Systems/.gitkeep new file mode 100644 index 0000000..dd8ee73 --- /dev/null +++ b/Content/Agrarian/Systems/.gitkeep @@ -0,0 +1 @@ +# Keeps the Agrarian system asset folder in source control. diff --git a/Content/Agrarian/UI/.gitkeep b/Content/Agrarian/UI/.gitkeep new file mode 100644 index 0000000..27e31ee --- /dev/null +++ b/Content/Agrarian/UI/.gitkeep @@ -0,0 +1 @@ +# Keeps the Agrarian UI asset folder in source control. diff --git a/Docs/ArtUxCodeAndAssetStandards.md b/Docs/ArtUxCodeAndAssetStandards.md new file mode 100644 index 0000000..cf70415 --- /dev/null +++ b/Docs/ArtUxCodeAndAssetStandards.md @@ -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.