From 188ef7b509d33ee3bf63fa90c4dee647260fadff Mon Sep 17 00:00:00 2001
From: nathan <nathan@pacificao.com>
Date: Mon, 18 May 2026 19:19:00 -0700
Subject: [PATCH] Document player inventory persistence

---
 AGRARIAN_DEVELOPMENT_ROADMAP.md         | 5 ++++-
 Docs/PersistenceDesignDocument.md       | 6 ++++++
 Scripts/verify_inventory_persistence.py | 9 +++++++++
 3 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/AGRARIAN_DEVELOPMENT_ROADMAP.md b/AGRARIAN_DEVELOPMENT_ROADMAP.md
index 5163ee6..cf852f4 100644
--- a/AGRARIAN_DEVELOPMENT_ROADMAP.md
+++ b/AGRARIAN_DEVELOPMENT_ROADMAP.md
@@ -746,7 +746,10 @@ Target deliverable: A small group can join a server, spawn into one biome, gathe
   for nutrition, illness, injury, sleep, shelter, stress, workload, and
   treatment quality placeholders, while aging/generational effects remain
   deferred.
-- [ ] Save player inventory.
+- [x] Save player inventory. Player saves already persist
+  `FAgrarianSavedPlayer::Inventory` from `UAgrarianInventoryComponent::Items`
+  and restore through `RestoreSavedItems`, so inventory listeners and derived
+  carry weight refresh after load.
 - [x] Save placed structures.
 - [ ] Save resource depletion state if needed.
 - [ ] Save world time.
diff --git a/Docs/PersistenceDesignDocument.md b/Docs/PersistenceDesignDocument.md
index 46bfdbc..6f76785 100644
--- a/Docs/PersistenceDesignDocument.md
+++ b/Docs/PersistenceDesignDocument.md
@@ -423,6 +423,12 @@ treatment quality data for later generational and health systems. Version 0.1.M
 only persists and restores those placeholders; it does not apply aging,
 lifespan, inheritance, or generational outcome gameplay.
 
+Player inventory is stored through `FAgrarianSavedPlayer::Inventory`, copied
+from `UAgrarianInventoryComponent::Items`, and restored through
+`UAgrarianInventoryComponent::RestoreSavedItems`. Restore recomputes derived
+values and broadcasts inventory changes so HUD/debug listeners see loaded item
+state.
+
 ## Testing Gates
 
 Minimum persistence smoke test:
diff --git a/Scripts/verify_inventory_persistence.py b/Scripts/verify_inventory_persistence.py
index 49895ec..cba77e8 100644
--- a/Scripts/verify_inventory_persistence.py
+++ b/Scripts/verify_inventory_persistence.py
@@ -9,6 +9,7 @@ FILES = {
     "AgrarianPersistenceSubsystem.cpp": ROOT / "Source" / "AgrarianGame" / "AgrarianPersistenceSubsystem.cpp",
     "InventoryDataModel.md": ROOT / "Docs" / "InventoryDataModel.md",
     "TechnicalDesignDocument.md": ROOT / "Docs" / "TechnicalDesignDocument.md",
+    "PersistenceDesignDocument.md": ROOT / "Docs" / "PersistenceDesignDocument.md",
     "AGRARIAN_DEVELOPMENT_ROADMAP.md": ROOT / "AGRARIAN_DEVELOPMENT_ROADMAP.md",
 }
 
@@ -40,11 +41,19 @@ EXPECTED = {
         "`UAgrarianInventoryComponent::RestoreSavedItems`",
         "`OnInventoryChanged`",
     ],
+    "PersistenceDesignDocument.md": [
+        "`FAgrarianSavedPlayer::Inventory`",
+        "`UAgrarianInventoryComponent::Items`",
+        "`UAgrarianInventoryComponent::RestoreSavedItems`",
+        "broadcasts inventory changes",
+    ],
     "AGRARIAN_DEVELOPMENT_ROADMAP.md": [
         "[x] Add persistence for inventory.",
+        "[x] Save player inventory.",
         "`FAgrarianSavedPlayer::Inventory`",
         "`RestoreSavedItems`",
         "listeners are notified after load",
+        "carry weight refresh after load",
     ],
 }