From 06666b1dc385a212963a5dde1cb534160a14b600 Mon Sep 17 00:00:00 2001
From: nathan <nathan@pacificao.com>
Date: Mon, 18 May 2026 19:26:30 -0700
Subject: [PATCH] Reserve container persistence schema

---
 AGRARIAN_DEVELOPMENT_ROADMAP.md               |  6 ++-
 Docs/PersistenceDesignDocument.md             |  8 ++++
 .../verify_container_persistence_schema.py    | 44 +++++++++++++++++++
 Source/AgrarianGame/AgrarianSaveGame.h        | 24 ++++++++++
 4 files changed, 81 insertions(+), 1 deletion(-)
 create mode 100644 Scripts/verify_container_persistence_schema.py

diff --git a/AGRARIAN_DEVELOPMENT_ROADMAP.md b/AGRARIAN_DEVELOPMENT_ROADMAP.md
index 305a5eb..8dd3b1d 100644
--- a/AGRARIAN_DEVELOPMENT_ROADMAP.md
+++ b/AGRARIAN_DEVELOPMENT_ROADMAP.md
@@ -762,7 +762,11 @@ Target deliverable: A small group can join a server, spawn into one biome, gathe
   `UAgrarianSaveGame::Weather`, provider `WeatherInputs`, and `WeatherDebug`,
   then restore mapped provider inputs when present or the saved enum weather
   otherwise.
-- [ ] Save containers.
+- [x] Save containers. The save schema now reserves
+  `FAgrarianSavedContainer` records with stable container ID, type, transform,
+  item stacks, and owner player ID; 0.1.M has no placed container actor yet, so
+  the current craftable `simple_container` remains covered by player inventory
+  persistence until placed containers arrive.
 - [ ] Add server-side save interval.
 - [x] Add manual admin save command.
 - [ ] Add load-on-server-start.
diff --git a/Docs/PersistenceDesignDocument.md b/Docs/PersistenceDesignDocument.md
index c8465b2..0128c7c 100644
--- a/Docs/PersistenceDesignDocument.md
+++ b/Docs/PersistenceDesignDocument.md
@@ -429,6 +429,14 @@ from `UAgrarianInventoryComponent::Items`, and restored through
 values and broadcasts inventory changes so HUD/debug listeners see loaded item
 state.
 
+Container persistence reserves `FAgrarianSavedContainer` records with stable
+container ID, container type ID, transform, item stacks, and owner player ID.
+Version 0.1.M does not yet have a placed container actor to capture; the current
+`simple_container` remains a craftable inventory item and is covered by player
+inventory persistence. The saved container array is intentionally present now
+so the first placed-container actor can use the same save format without a
+schema break.
+
 World time is stored in `UAgrarianSaveGame::WorldHours`. The persistence
 subsystem captures it from `AAgrarianGameState::WorldHours` during world save
 and restores it only on authority during world load.
diff --git a/Scripts/verify_container_persistence_schema.py b/Scripts/verify_container_persistence_schema.py
new file mode 100644
index 0000000..e41880d
--- /dev/null
+++ b/Scripts/verify_container_persistence_schema.py
@@ -0,0 +1,44 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+EXPECTED = {
+    ROOT / "Source" / "AgrarianGame" / "AgrarianSaveGame.h": [
+        "struct FAgrarianSavedContainer",
+        "FName ContainerId = NAME_None;",
+        "FName ContainerTypeId = NAME_None;",
+        "FTransform Transform;",
+        "TArray<FAgrarianItemStack> Inventory;",
+        "FString OwnerPlayerId;",
+        "TArray<FAgrarianSavedContainer> Containers;",
+    ],
+    ROOT / "Docs" / "PersistenceDesignDocument.md": [
+        "`FAgrarianSavedContainer`",
+        "Version 0.1.M does not yet have a placed container actor to capture",
+        "`simple_container` remains a craftable inventory item",
+    ],
+    ROOT / "AGRARIAN_DEVELOPMENT_ROADMAP.md": [
+        "[x] Save containers.",
+        "`FAgrarianSavedContainer`",
+        "`simple_container` remains covered by player inventory",
+    ],
+}
+
+
+def main() -> None:
+    missing = []
+    for path, snippets in EXPECTED.items():
+        text = path.read_text(encoding="utf-8")
+        for snippet in snippets:
+            if snippet not in text:
+                missing.append(f"{path.relative_to(ROOT)}: {snippet}")
+
+    if missing:
+        raise RuntimeError("Container persistence schema verification failed: " + "; ".join(missing))
+
+    print("PASS: container persistence schema is reserved without claiming placed-container capture.")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/Source/AgrarianGame/AgrarianSaveGame.h b/Source/AgrarianGame/AgrarianSaveGame.h
index 1ccc5d6..4447968 100644
--- a/Source/AgrarianGame/AgrarianSaveGame.h
+++ b/Source/AgrarianGame/AgrarianSaveGame.h
@@ -85,6 +85,27 @@ struct FAgrarianSavedResourceNode
 	bool bRespawnsForMvp = false;
 };
 
+USTRUCT(BlueprintType)
+struct FAgrarianSavedContainer
+{
+	GENERATED_BODY()
+
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Agrarian|Save")
+	FName ContainerId = NAME_None;
+
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Agrarian|Save")
+	FName ContainerTypeId = NAME_None;
+
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Agrarian|Save")
+	FTransform Transform;
+
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Agrarian|Save")
+	TArray<FAgrarianItemStack> Inventory;
+
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Agrarian|Save")
+	FString OwnerPlayerId;
+};
+
 UCLASS()
 class UAgrarianSaveGame : public USaveGame
 {
@@ -114,4 +135,7 @@ public:
 
 	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Agrarian|Save")
 	TArray<FAgrarianSavedResourceNode> ResourceNodes;
+
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Agrarian|Save")
+	TArray<FAgrarianSavedContainer> Containers;
 };