Add economy and AGR design

2026-05-15 01:53:37 -07:00
parent 1c601d2eaa
commit d02062d073
2 changed files with 494 additions and 16 deletions
@@ -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.
+- [x] Define what AGR does in MVP.
- [ ] Define what AGR does not do in MVP.
+- [x] Define what AGR does not do in MVP.
- [ ] Decide custodial vs non-custodial game wallet approach.
+- [x] Decide custodial vs non-custodial game wallet approach.
- [ ] Define testnet/devnet flow.
+- [x] Define testnet/devnet flow.
- [ ] Define transaction confirmation rules.
+- [x] Define transaction confirmation rules.
- [ ] Define in-game ledger rules.
+- [x] Define in-game ledger rules.
- [ ] Define anti-fraud rules.
+- [x] Define anti-fraud rules.
- [ ] Define market transaction logs.
+- [x] Define market transaction logs.
- [ ] Define bridge between web wallet and game account.
+- [x] Define bridge between web wallet and game account.
- [ ] Define legal/compliance review points.
+- [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.
+- [x] Define AGR integration design.
- [ ] Define account/wallet bridge 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.
@@ -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.