diff --git a/AGRARIAN_DEVELOPMENT_ROADMAP.md b/AGRARIAN_DEVELOPMENT_ROADMAP.md index e6745c2..e76ab2d 100644 --- a/AGRARIAN_DEVELOPMENT_ROADMAP.md +++ b/AGRARIAN_DEVELOPMENT_ROADMAP.md @@ -249,7 +249,7 @@ Current tooling decisions: - [x] Create Earth-scale terrain/tile streaming design document. - [x] Create tile registry/database design document. - [x] Create real-world terrain source data evaluation document. -- [ ] Create economy and AGR design document. +- [x] Create economy and AGR design document. - [ ] Create art direction document. - [ ] Create UX/HUD direction document. - [ ] Create content naming conventions. @@ -723,7 +723,7 @@ Goal: Transition from temporary survival into lasting settlement and land stewar - [ ] Add simple trade UI. - [ ] Add ownership transfer. - [ ] Add local price notes if needed. -- [ ] Add AGR placeholder integration planning. +- [x] Add AGR placeholder integration planning. - [ ] Add transaction logging. --- @@ -1160,16 +1160,16 @@ These tracks run across all phases and must not be left as afterthoughts. ## D. AGR Integration -- [ ] Define what AGR does in MVP. -- [ ] Define what AGR does not do in MVP. -- [ ] Decide custodial vs non-custodial game wallet approach. -- [ ] Define testnet/devnet flow. -- [ ] Define transaction confirmation rules. -- [ ] Define in-game ledger rules. -- [ ] Define anti-fraud rules. -- [ ] Define market transaction logs. -- [ ] Define bridge between web wallet and game account. -- [ ] Define legal/compliance review points. +- [x] Define what AGR does in MVP. +- [x] Define what AGR does not do in MVP. +- [x] Decide custodial vs non-custodial game wallet approach. +- [x] Define testnet/devnet flow. +- [x] Define transaction confirmation rules. +- [x] Define in-game ledger rules. +- [x] Define anti-fraud rules. +- [x] Define market transaction logs. +- [x] Define bridge between web wallet and game account. +- [x] Define legal/compliance review points. ## E. Admin And Moderation @@ -1365,8 +1365,8 @@ These tracks run across all phases and must not be left as afterthoughts. - [ ] Add land claim prototype. - [ ] Add farming prototype if feasible. - [ ] Add simple barter placeholder if feasible. -- [ ] Define AGR integration design. -- [ ] Define account/wallet bridge design. +- [x] Define AGR integration design. +- [x] Define account/wallet bridge design. - [x] Add admin commands. - [ ] Add test feedback form/process. - [ ] Improve UI clarity. @@ -1435,7 +1435,7 @@ Earliest incomplete foundation items: - [x] Create the persistence design document. - [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. -- [ ] Create economy and AGR design document. +- [x] Create economy and AGR design document. - [ ] 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. @@ -1443,4 +1443,4 @@ Earliest incomplete foundation items: Immediate next item: -- [ ] Create economy and AGR design document. +- [ ] Create art direction, UX/HUD direction, coding standards, Blueprint standards, and asset/folder naming standards. diff --git a/Docs/EconomyAndAgrDesignDocument.md b/Docs/EconomyAndAgrDesignDocument.md new file mode 100644 index 0000000..5aaa80d --- /dev/null +++ b/Docs/EconomyAndAgrDesignDocument.md @@ -0,0 +1,478 @@ +# Agrarian Economy And AGR Design Document + +## Purpose + +Agrarian's economy should grow from the same survival foundation as the rest of +the game. Players should first trade because labor, time, risk, storage, +location, skills, and local resources matter. AGR can eventually add community +and real-world value, but it must not weaken the survival loop, create +pay-to-win pressure, or force legal/compliance decisions before the game is +ready. + +This document defines the MVP economy direction, what AGR does and does not do +early, and the design guardrails for later account, wallet, ledger, and market +systems. + +## Design Principles + +- Survival access must never depend on AGR. +- Early economy starts with barter, ownership transfer, and transaction logs. +- Labor, distance, scarcity, time, skill, storage, spoilage, and trust are the + first economic forces. +- The server owns all authoritative trades, ownership changes, and economy + records. +- AGR must not buy combat dominance, survival immunity, exclusive resources, or + unearned progression. +- No loot boxes, gambling loops, or fragmented paid DLC economy. +- Any real-money, token, wallet, or marketplace behavior requires legal and + compliance review before public use. +- Economy data should be auditable enough to investigate duplication, fraud, + griefing, and support disputes. + +## Economy Progression + +Agrarian's economy should emerge in stages. + +### Stage 1: Survival Barter + +The first playable economy is direct barter between players or through a simple +barter container. + +Useful early goods: + +- water containers; +- cooked or preserved food; +- sticks, stone, fiber, hide, and wood; +- basic tools; +- shelter materials; +- medicine or first-aid ingredients when added; +- local map knowledge and discovered safe routes. + +This stage does not need coins, prices, shops, or AGR. It needs secure transfer, +ownership, and logs. + +### Stage 2: Local Specialization + +As survival stabilizes, players should benefit from specializing: + +- toolmaker; +- hunter; +- fisher; +- gatherer; +- builder; +- farmer; +- livestock keeper; +- hauler; +- scout; +- guard; +- record keeper. + +The economy becomes more interesting when not every player can efficiently do +everything at once. + +### Stage 3: Settlements And Trust + +Once settlements exist, trade expands through: + +- shared storage; +- permissions; +- claims; +- reputation; +- contracts; +- local laws; +- debt or favor records; +- public trade posts. + +Trust should be local and earned. A player may have a strong reputation in one +settlement and be unknown or disliked elsewhere. + +### Stage 4: Regional Trade + +Regional economy should come from real distance and tile differences: + +- coastal vs inland resources; +- mountain, forest, river, and grassland advantages; +- travel time and carrying capacity; +- road, boat, horse, cart, tractor, and vehicle logistics; +- weather and seasonal risk; +- spoilage and preservation. + +Distance-based economy pressure is valuable because the world is intended to +grow by real terrain tiles. A resource should not feel globally available just +because one tile has it. + +### Stage 5: AGR Utility + +AGR should only enter meaningful gameplay after the core economy is already fun +without it. AGR can later support community value, account-linked services, +event participation, marketplace rails, creator/community rewards, or other +approved utility, but those uses must be designed around fairness and compliance. + +## MVP Economy Scope + +The MVP economy should prove only the smallest useful loop: + +- a player can offer items for trade; +- another player can accept or reject the trade; +- the server validates both inventories; +- ownership changes atomically; +- both players receive the correct result; +- a transaction record is written; +- the result survives persistence if the world is saved. + +Acceptable MVP implementations: + +- direct player-to-player trade window; +- barter container with explicit owner and recipient rules; +- admin/test command to create a known trade scenario. + +The simplest implementation should be chosen when development reaches the trade +feature. For the current foundation stage, the important outcome is the data +contract and guardrails. + +## MVP Non-Goals + +Do not include these in the first playable MVP: + +- real-money marketplace; +- AGR token transfers; +- wallet custody; +- blockchain confirmation requirements; +- player-run auction house; +- automated regional prices; +- global bank; +- paid boosts; +- purchasable survival advantages; +- staking, yield, or speculative mechanics; +- cash-out flows; +- cross-game asset promises. + +## Trade Flow + +Direct trade flow: + +1. Player A requests a trade with Player B. +2. Server verifies both players are alive, connected, close enough, and allowed + to trade. +3. Each player proposes item stacks from authoritative inventory. +4. Server locks the proposed items for the trade session. +5. Both players confirm. +6. Server revalidates inventories and item locks. +7. Server applies the exchange atomically. +8. Server writes a transaction record. +9. Server replicates updated inventories and trade result. + +Barter-container flow: + +1. Owner places items into a trade container or offer record. +2. Owner defines allowed recipient, settlement, or open offer scope. +3. Recipient places requested goods or accepts a posted exchange. +4. Server validates contents, ownership, permissions, and item state. +5. Server transfers ownership atomically. +6. Server writes a transaction record. + +Rules: + +- No client-authored inventory edits. +- No partial completion unless the trade type explicitly allows it. +- Locked trade items cannot be consumed, dropped, destroyed, or traded again. +- Disconnects cancel unconfirmed trades and unlock items. +- Confirmed trades must either fully apply or fully fail. + +## Ownership Transfer + +Ownership matters for support, permissions, settlements, theft rules, and +future legal/governance systems. + +Minimum ownership fields: + +```text +OwnerId +OwnerType +ItemOrObjectId +TileId +AcquiredAt +AcquisitionReason +SourceTransactionId +RecordVersion +``` + +Owner types can start simple: + +- player; +- container; +- settlement; +- unowned/world. + +Future owner types may include household, guild, town, government, market, or +contract escrow. + +## Transaction Logging + +Economy records should be append-only where practical. The goal is not full +financial infrastructure in the MVP; the goal is enough auditability to debug, +restore, and investigate. + +Minimum transaction record: + +```text +TransactionId +TransactionType +CreatedAt +TileId +ServerId +Participants +Inputs +Outputs +Status +FailureReason +GameBuildVersion +RecordVersion +``` + +Transaction types: + +- direct_trade; +- barter_container_trade; +- admin_grant; +- admin_remove; +- crafting_output; +- resource_harvest; +- ownership_transfer; +- settlement_storage_deposit; +- settlement_storage_withdrawal. + +MVP logs can be local structured files or database records depending on the +persistence implementation chosen at that time. Long term, economy logs should +move toward database-backed append-only records. + +## Pricing And Value + +MVP should not need hardcoded global prices. Early value comes from usefulness +and scarcity. + +Avoid early global price tables because: + +- different regions should value resources differently; +- player skill and labor should matter; +- spoilage and travel cost are contextual; +- a central price table can flatten the economy before it has a chance to + emerge. + +Useful future value signals: + +- local trade history; +- settlement bulletin boards; +- scarcity indicators; +- rough admin/debug economy reports; +- distance and transport cost estimates. + +## AGR Role In MVP + +AGR in the MVP is design-only and placeholder-level unless explicitly approved +later. + +AGR may do in MVP: + +- appear in documentation as the future community-value layer; +- reserve data fields where future AGR-linked transactions might reference an + account or ledger; +- support internal design discussions about fairness, compliance, and account + linking; +- remain disabled in gameplay builds. + +AGR must not do in MVP: + +- buy food, water, weapons, shelter, land, claims, resources, livestock, or + progression; +- replace barter or survival labor; +- create a paid advantage; +- require players to create a wallet; +- require blockchain/network connectivity to play; +- expose real-money value inside the game UI; +- be marketed as investment utility; +- be used in public testing without legal/compliance review. + +## Wallet And Account Approach + +Do not add wallet custody to the game client in the MVP. + +Recommended direction: + +- keep gameplay accounts separate from wallet identity at first; +- design an account-to-wallet bridge outside the Unreal client; +- prefer optional linking when real AGR utility is ready; +- avoid storing private keys, seed phrases, wallet passwords, or API tokens in + game saves, config files, source control, or Unreal assets; +- require explicit legal/security review before choosing custodial or + non-custodial flows. + +Custodial vs non-custodial decision: + +- MVP decision: deferred. +- Default until review: no wallet custody in game. +- Any future custodial system requires security, compliance, recovery, fraud, + support, and jurisdiction review. +- Any future non-custodial system requires UX, loss-risk, transaction clarity, + and support policy review. + +## Testnet And Devnet + +If AGR integration prototypes begin before public utility, use a devnet or +testnet-style environment only. + +Rules: + +- no mainnet transactions in early gameplay builds; +- no irreversible player-value transactions during gameplay prototyping; +- test credentials stay out of Git; +- test ledgers are clearly marked as non-production; +- transaction IDs are logged for debugging but do not drive survival outcomes. + +## Confirmation Rules + +Future AGR-linked actions should never block basic survival play. + +If a future feature needs external confirmation: + +- show a pending state outside critical survival loops; +- keep the game server authoritative for in-game item changes; +- time out clearly; +- reconcile duplicate or failed confirmations; +- log the external reference ID; +- never let the client claim confirmation without server verification. + +## In-Game Ledger Rules + +The in-game ledger is not the same as an external chain or payment network. + +The game ledger should track: + +- gameplay trades; +- ownership changes; +- admin grants/removals; +- settlement storage changes; +- future market offers; +- references to external AGR events if and when approved. + +The game ledger should not store: + +- private keys; +- seed phrases; +- wallet passwords; +- payment card data; +- raw personal financial data. + +## Anti-Abuse And Fairness + +Economy abuse will happen if the systems matter. + +Required protections: + +- server-authoritative inventory and ownership; +- atomic trade application; +- item locks during pending trades; +- transaction logs; +- admin-visible audit trail; +- duplicate transaction detection; +- rate limits for market-style endpoints when added; +- clear rollback/support procedure for confirmed exploit cases. + +Gameplay fairness protections: + +- no paid dominance; +- no purchasable survival immunity; +- no exclusive resource classes sold for money; +- no paid fast travel that invalidates logistics; +- no AGR-only tools required for normal progression. + +## Legal And Compliance Gates + +AGR or real-money utility cannot move beyond design/prototype until the project +has reviewed: + +- company/payment setup; +- EULA and terms; +- privacy policy; +- age/content rating implications; +- tax/reporting implications; +- virtual currency/token rules; +- consumer protection and refund expectations; +- sanctions/geographic restrictions if relevant; +- marketplace/storefront rules for Steam, Epic, and other platforms; +- marketing language restrictions. + +This document is a design guide, not legal advice. + +## Data Boundaries + +Economy data belongs with server-side persistence and audit records. Item +definitions remain in data assets. Tile metadata remains in the tile registry. + +Persist economy records: + +- transaction logs; +- ownership records; +- trade offers; +- settlement storage events; +- account link references once approved. + +Do not persist economy records in: + +- tile package cache; +- generated terrain packages; +- client-only UI settings; +- source-controlled secrets; +- raw Unreal starter/prototype assets. + +## Implementation Roadmap + +Near-term implementation order: + +1. Add item ownership fields where needed for placed objects and containers. +2. Add transaction record shape to persistence. +3. Add admin/debug transaction logging for inventory grants/removals. +4. Add simple barter container or direct trade flow. +5. Add server-authoritative item locking for pending trades. +6. Add trade smoke tests. +7. Add settlement/container permissions. +8. Add local reputation and dispute/audit tooling. +9. Revisit AGR account/wallet bridge only after core economy is stable. + +## Testing Gates + +Minimum trade test: + +1. Start a multiplayer session with two players. +2. Give each player a known item stack. +3. Start a trade. +4. Confirm both sides. +5. Verify inventories update correctly on server and clients. +6. Save and restart. +7. Verify ownership and inventory state persist. +8. Verify a transaction record exists. + +Minimum abuse test: + +1. Attempt to trade an item the player does not own. +2. Attempt to alter inventory client-side during trade. +3. Disconnect during an unconfirmed trade. +4. Attempt duplicate confirmation. +5. Confirm items are not duplicated, lost, or transferred without validation. + +Minimum AGR safety test before any public feature: + +1. Confirm AGR gameplay utility is disabled unless explicitly enabled. +2. Confirm no wallet secrets exist in saves, configs, logs, or assets. +3. Confirm survival gameplay works without account/wallet linking. +4. Confirm legal/compliance checklist has an owner before public exposure. + +## Open Questions + +- Whether the first trade implementation should be a direct player trade window + or a barter container. +- Exact persistence backend for transaction logs once multiplayer saves mature. +- Final account provider and platform account timing. +- Whether AGR ever touches in-game item exchange directly or remains a + community/account/service layer. +- Final custodial vs non-custodial wallet approach after legal/security review.