Add resource node persistence

AGRARIAN_DEVELOPMENT_ROADMAP.md

@@ -548,7 +548,10 @@ Target deliverable: A small group can join a server, spawn into one biome, gathe
   current MVP nodes preserve bare-hand gathering, while a basic tool in
   inventory improves yields for wood, fiber, and stone.
 - [x] Add bare-hand gathering fallback.
-- [ ] Add resource node persistence.
+- [x] Add resource node persistence. Added save records for existing map/tile
+  resource nodes keyed by stable node IDs, persistence capture/restore paths,
+  and Ground Zero placement support so only loaded tiles with actual resource
+  nodes contribute depletion state.
 - [x] Add replicated gathering feedback.
 
 ## 0.1.G Primitive Crafting

Docs/PersistenceDesignDocument.md

@@ -441,12 +441,19 @@ This document defines:
 
 Implementation work remains tracked separately in the roadmap.
 
+The MVP resource-node implementation stores depletion as existing map/tile
+actor state. Each `AAgrarianResourceNode` may define a stable
+`PersistenceNodeId`; otherwise the actor name is used as a fallback. Save files
+capture `RemainingHarvests` for resource nodes present in the loaded world and
+restore only matching existing nodes. This deliberately avoids spawning resource
+nodes from saves, keeping tile-authored resources owned by tile content while
+letting persistence remember depletion for active tiles.
+
 ## Open Questions
 
 - Should the first playable MVP use `USaveGame`, JSON, or a hybrid save
   backend?
 - What is the first stable `SaveFormatVersion` value?
-- Which resource nodes should persist depletion in Ground Zero?
 - Should disconnected players remain in world physically or be removed?
 - How much inventory should death/respawn preserve?
 - When do saves move from file-based records to database-backed records?

Docs/TechnicalDesignDocument.md

@@ -458,6 +458,15 @@ plants remain pure bare-hand gathering. Later nodes can disable
 `bAllowBareHandGathering` when the game has proper tool equipment, durability,
 and feedback UI.
 
+Resource node persistence is map/tile state, not a spawned-actor replay path.
+`UAgrarianSaveGame` stores `FAgrarianSavedResourceNode` records keyed by
+`AAgrarianResourceNode::PersistenceNodeId`, with the actor name as a fallback.
+`UAgrarianPersistenceSubsystem` captures only resource nodes that exist in the
+currently loaded world and restores matching existing nodes by stable id. This
+keeps the MVP compatible with later Earth-scale tiles: a tile contributes
+resource depletion state only when its resource actors actually exist, and tile
+generation/placement scripts should assign deterministic node ids.
+
 ### Wildlife Navigation
 
 MVP wildlife movement is server authoritative. `AAgrarianWildlifeBase` uses an

Docs/Terrain/GroundZeroResourcePass.md

@@ -69,6 +69,15 @@ immediate benefit:
 The rule is inventory-based until equipment slots, durability, and explicit
 active-hand state are implemented.
 
+## Persistence
+
+Ground Zero resource actors receive stable `PersistenceNodeId` values matching
+their placement labels. The persistence subsystem captures and restores only
+resource nodes that exist in the loaded world, so depletion records stay scoped
+to active map/tile content. Future generated Earth-scale tiles should follow the
+same rule: assign deterministic resource node IDs during placement and let the
+save system record depletion only for tiles whose resource actors are present.
+
 ## Follow-Up
 
 Future passes should replace the prototype meshes with real coastal scrub,

Scripts/setup_ground_zero_demo_map.py

@@ -864,6 +864,10 @@ def spawn_demo_actor(spec, height_values, materials, safe_spawn_location_xy=None
         raise RuntimeError(f"Could not spawn {spec['label']}")
 
     set_actor_label(actor, spec["label"])
+    try:
+        actor.set_editor_property("persistence_node_id", spec["label"])
+    except Exception:
+        pass
     material_key = material_key_for_actor_label(spec["label"])
     if material_key:
         apply_material_to_actor_meshes(actor, materials[material_key])

Scripts/verify_ground_zero_resources.py

@@ -65,6 +65,10 @@ def main():
             if actor.get_editor_property("remaining_harvests") <= 0:
                 failures.append(f"{label} has no remaining harvests")
 
+            persistence_node_id = str(actor.get_editor_property("persistence_node_id"))
+            if persistence_node_id != label:
+                failures.append(f"{label} persistence node id expected {label}, got {persistence_node_id}")
+
     if failures:
         raise RuntimeError("Ground Zero resource verification failed: " + "; ".join(failures))
 

Scripts/verify_resource_node_persistence.py

@@ -0,0 +1,74 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+EXPECTED = {
+    ROOT / "Source" / "AgrarianGame" / "AgrarianSaveGame.h": [
+        "struct FAgrarianSavedResourceNode",
+        "FName ResourceNodeId = NAME_None;",
+        "int32 RemainingHarvests = 0;",
+        "TArray<FAgrarianSavedResourceNode> ResourceNodes;",
+    ],
+    ROOT / "Source" / "AgrarianGame" / "AgrarianResourceNode.h": [
+        "FName PersistenceNodeId = NAME_None;",
+        "FName GetResourcePersistenceId() const;",
+        "FAgrarianSavedResourceNode CaptureResourceSaveState() const;",
+        "void ApplyResourceSaveState(const FAgrarianSavedResourceNode& SavedNode);",
+    ],
+    ROOT / "Source" / "AgrarianGame" / "AgrarianResourceNode.cpp": [
+        "AAgrarianResourceNode::GetResourcePersistenceId",
+        "PersistenceNodeId != NAME_None ? PersistenceNodeId : GetFName()",
+        "SavedNode.RemainingHarvests = RemainingHarvests;",
+        "RemainingHarvests = FMath::Clamp",
+        "ScheduleRespawnIfNeeded();",
+    ],
+    ROOT / "Source" / "AgrarianGame" / "AgrarianPersistenceSubsystem.h": [
+        "int32 CaptureResourceNodes(UAgrarianSaveGame* SaveGame) const;",
+        "int32 RestoreResourceNodes(const UAgrarianSaveGame* SaveGame) const;",
+        "void FindResourceNodes(TArray<AAgrarianResourceNode*>& OutResourceNodes) const;",
+    ],
+    ROOT / "Source" / "AgrarianGame" / "AgrarianPersistenceSubsystem.cpp": [
+        "SaveGame->ResourceNodes.Reset();",
+        "SaveGame->ResourceNodes.Add(SavedNode);",
+        "RestoreResourceNodes(SaveGame);",
+        "TActorIterator<AAgrarianResourceNode>",
+        "ResourceNode->ApplyResourceSaveState(*SavedNode);",
+    ],
+    ROOT / "Scripts" / "setup_ground_zero_demo_map.py": [
+        'actor.set_editor_property("persistence_node_id", spec["label"])',
+    ],
+    ROOT / "Scripts" / "verify_ground_zero_resources.py": [
+        'actor.get_editor_property("persistence_node_id")',
+        "persistence node id expected",
+    ],
+    ROOT / "Docs" / "TechnicalDesignDocument.md": [
+        "Resource node persistence is map/tile state",
+        "captures only resource nodes that exist in the",
+    ],
+    ROOT / "Docs" / "Terrain" / "GroundZeroResourcePass.md": [
+        "Ground Zero resource actors receive stable `PersistenceNodeId` values",
+        "resource nodes that exist in the loaded world",
+    ],
+    ROOT / "AGRARIAN_DEVELOPMENT_ROADMAP.md": [
+        "[x] Add resource node persistence.",
+    ],
+}
+
+
+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("Resource node persistence verification failed: " + "; ".join(missing))
+
+    print("PASS: resource node persistence captures loaded map/tile nodes by stable id and restores depletion state.")
+
+
+if __name__ == "__main__":
+    main()

Source/AgrarianGame/AgrarianPersistenceSubsystem.cpp

@@ -5,6 +5,7 @@
 #include "AgrarianGameState.h"
 #include "AgrarianInventoryComponent.h"
 #include "AgrarianPersistentActorComponent.h"
+#include "AgrarianResourceNode.h"
 #include "AgrarianSaveGame.h"
 #include "AgrarianSurvivalComponent.h"
 #include "EngineUtils.h"
@@ -240,6 +241,71 @@ int32 UAgrarianPersistenceSubsystem::RestorePlayers(const UAgrarianSaveGame* Sav
 	return RestoredCount;
 }
 
+int32 UAgrarianPersistenceSubsystem::CaptureResourceNodes(UAgrarianSaveGame* SaveGame) const
+{
+	if (!SaveGame)
+	{
+		return 0;
+	}
+
+	TArray<AAgrarianResourceNode*> ResourceNodes;
+	FindResourceNodes(ResourceNodes);
+
+	SaveGame->ResourceNodes.Reset();
+	for (const AAgrarianResourceNode* ResourceNode : ResourceNodes)
+	{
+		if (!ResourceNode)
+		{
+			continue;
+		}
+
+		const FAgrarianSavedResourceNode SavedNode = ResourceNode->CaptureResourceSaveState();
+		if (SavedNode.ResourceNodeId != NAME_None)
+		{
+			SaveGame->ResourceNodes.Add(SavedNode);
+		}
+	}
+
+	return SaveGame->ResourceNodes.Num();
+}
+
+int32 UAgrarianPersistenceSubsystem::RestoreResourceNodes(const UAgrarianSaveGame* SaveGame) const
+{
+	if (!SaveGame)
+	{
+		return 0;
+	}
+
+	TArray<AAgrarianResourceNode*> ResourceNodes;
+	FindResourceNodes(ResourceNodes);
+
+	int32 RestoredCount = 0;
+	for (AAgrarianResourceNode* ResourceNode : ResourceNodes)
+	{
+		if (!ResourceNode)
+		{
+			continue;
+		}
+
+		const FName ResourceNodeId = ResourceNode->GetResourcePersistenceId();
+		const FAgrarianSavedResourceNode* SavedNode = SaveGame->ResourceNodes.FindByPredicate(
+			[ResourceNodeId](const FAgrarianSavedResourceNode& Candidate)
+			{
+				return Candidate.ResourceNodeId == ResourceNodeId;
+			});
+
+		if (!SavedNode)
+		{
+			continue;
+		}
+
+		ResourceNode->ApplyResourceSaveState(*SavedNode);
+		RestoredCount++;
+	}
+
+	return RestoredCount;
+}
+
 bool UAgrarianPersistenceSubsystem::SaveCurrentWorld() const
 {
 	UAgrarianSaveGame* SaveGame = LoadOrCreateSave();
@@ -251,6 +317,7 @@ bool UAgrarianPersistenceSubsystem::SaveCurrentWorld() const
 	CaptureWorldState(SaveGame);
 	CapturePlayers(SaveGame);
 	CaptureWorldActors(SaveGame);
+	CaptureResourceNodes(SaveGame);
 	return WriteSave(SaveGame);
 }
 
@@ -268,6 +335,7 @@ bool UAgrarianPersistenceSubsystem::LoadCurrentWorld(int32& RestoredPlayerCount,
 	const bool bRestoredWorldState = RestoreWorldState(SaveGame);
 	RestoredPlayerCount = RestorePlayers(SaveGame);
 	RestoredWorldActorCount = RestoreWorldActors(SaveGame, bClearExistingActors);
+	RestoreResourceNodes(SaveGame);
 	return bRestoredWorldState;
 }
 
@@ -316,6 +384,26 @@ void UAgrarianPersistenceSubsystem::FindAgrarianPlayers(TArray<AAgrarianGameChar
 	}
 }
 
+void UAgrarianPersistenceSubsystem::FindResourceNodes(TArray<AAgrarianResourceNode*>& OutResourceNodes) const
+{
+	OutResourceNodes.Reset();
+
+	UWorld* World = GetWorld();
+	if (!World)
+	{
+		return;
+	}
+
+	for (TActorIterator<AAgrarianResourceNode> ActorIt(World); ActorIt; ++ActorIt)
+	{
+		AAgrarianResourceNode* ResourceNode = *ActorIt;
+		if (ResourceNode && !ResourceNode->IsPendingKillPending())
+		{
+			OutResourceNodes.Add(ResourceNode);
+		}
+	}
+}
+
 FString UAgrarianPersistenceSubsystem::GetPlayerPersistenceId(const AAgrarianGameCharacter* Character) const
 {
 	if (!Character)

Source/AgrarianGame/AgrarianPersistenceSubsystem.h

@@ -9,6 +9,7 @@
 class UAgrarianSaveGame;
 class UAgrarianPersistentActorComponent;
 class AAgrarianGameCharacter;
+class AAgrarianResourceNode;
 
 UCLASS()
 class UAgrarianPersistenceSubsystem : public UGameInstanceSubsystem
@@ -58,6 +59,12 @@ public:
 	UFUNCTION(BlueprintCallable, Category = "Agrarian|Persistence")
 	int32 RestorePlayers(const UAgrarianSaveGame* SaveGame) const;
 
+	UFUNCTION(BlueprintCallable, Category = "Agrarian|Persistence")
+	int32 CaptureResourceNodes(UAgrarianSaveGame* SaveGame) const;
+
+	UFUNCTION(BlueprintCallable, Category = "Agrarian|Persistence")
+	int32 RestoreResourceNodes(const UAgrarianSaveGame* SaveGame) const;
+
 	UFUNCTION(BlueprintCallable, Category = "Agrarian|Persistence")
 	bool SaveCurrentWorld() const;
 
@@ -67,5 +74,6 @@ public:
 protected:
 	void FindPersistentComponents(TArray<UAgrarianPersistentActorComponent*>& OutComponents) const;
 	void FindAgrarianPlayers(TArray<AAgrarianGameCharacter*>& OutPlayers) const;
+	void FindResourceNodes(TArray<AAgrarianResourceNode*>& OutResourceNodes) const;
 	FString GetPlayerPersistenceId(const AAgrarianGameCharacter* Character) const;
 };

Source/AgrarianGame/AgrarianResourceNode.cpp

@@ -4,6 +4,7 @@
 #include "AgrarianGameCharacter.h"
 #include "AgrarianInventoryComponent.h"
 #include "AgrarianItemDefinitionAsset.h"
+#include "AgrarianSaveGame.h"
 #include "Components/StaticMeshComponent.h"
 #include "TimerManager.h"
 #include "Net/UnrealNetwork.h"
@@ -94,6 +95,40 @@ void AAgrarianResourceNode::OnRep_RemainingHarvests()
 	UpdateDepletedState();
 }
 
+FName AAgrarianResourceNode::GetResourcePersistenceId() const
+{
+	return PersistenceNodeId != NAME_None ? PersistenceNodeId : GetFName();
+}
+
+FAgrarianSavedResourceNode AAgrarianResourceNode::CaptureResourceSaveState() const
+{
+	FAgrarianSavedResourceNode SavedNode;
+	SavedNode.ResourceNodeId = GetResourcePersistenceId();
+	SavedNode.RemainingHarvests = RemainingHarvests;
+	SavedNode.bRespawnsForMvp = bRespawnsForMvp;
+	return SavedNode;
+}
+
+void AAgrarianResourceNode::ApplyResourceSaveState(const FAgrarianSavedResourceNode& SavedNode)
+{
+	if (!HasAuthority() || SavedNode.ResourceNodeId == NAME_None || SavedNode.ResourceNodeId != GetResourcePersistenceId())
+	{
+		return;
+	}
+
+	RemainingHarvests = FMath::Clamp(SavedNode.RemainingHarvests, 0, FMath::Max(1, MaxHarvests));
+	if (RemainingHarvests > 0)
+	{
+		if (UWorld* World = GetWorld())
+		{
+			World->GetTimerManager().ClearTimer(RespawnTimerHandle);
+		}
+	}
+
+	UpdateDepletedState();
+	ScheduleRespawnIfNeeded();
+}
+
 bool AAgrarianResourceNode::HasRequiredTool(const AAgrarianGameCharacter* Interactor) const
 {
 	if (RequiredToolItemId == NAME_None)

Source/AgrarianGame/AgrarianResourceNode.h

@@ -6,6 +6,7 @@
 #include "GameFramework/Actor.h"
 #include "TimerManager.h"
 #include "AgrarianInteractable.h"
+#include "AgrarianSaveGame.h"
 #include "AgrarianTypes.h"
 #include "AgrarianResourceNode.generated.h"
 
@@ -32,6 +33,9 @@ public:
 	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Agrarian|Resource")
 	TObjectPtr<UAgrarianItemDefinitionAsset> YieldItemDefinition;
 
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Agrarian|Resource|Persistence")
+	FName PersistenceNodeId = NAME_None;
+
 	UPROPERTY(EditAnywhere, BlueprintReadWrite, ReplicatedUsing = OnRep_RemainingHarvests, Category = "Agrarian|Resource", meta = (ClampMin = "0"))
 	int32 RemainingHarvests = 5;
 
@@ -60,6 +64,15 @@ public:
 	virtual bool CanInteract_Implementation(const AAgrarianGameCharacter* Interactor) const override;
 	virtual void Interact_Implementation(AAgrarianGameCharacter* Interactor) override;
 
+	UFUNCTION(BlueprintCallable, Category = "Agrarian|Resource|Persistence")
+	FName GetResourcePersistenceId() const;
+
+	UFUNCTION(BlueprintCallable, Category = "Agrarian|Resource|Persistence")
+	FAgrarianSavedResourceNode CaptureResourceSaveState() const;
+
+	UFUNCTION(BlueprintCallable, Category = "Agrarian|Resource|Persistence")
+	void ApplyResourceSaveState(const FAgrarianSavedResourceNode& SavedNode);
+
 protected:
 	UFUNCTION()
 	void OnRep_RemainingHarvests();

Source/AgrarianGame/AgrarianSaveGame.h

@@ -46,6 +46,21 @@ struct FAgrarianSavedWorldActor
 	TMap<FName, float> NumberState;
 };
 
+USTRUCT(BlueprintType)
+struct FAgrarianSavedResourceNode
+{
+	GENERATED_BODY()
+
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Agrarian|Save")
+	FName ResourceNodeId = NAME_None;
+
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Agrarian|Save")
+	int32 RemainingHarvests = 0;
+
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Agrarian|Save")
+	bool bRespawnsForMvp = false;
+};
+
 UCLASS()
 class UAgrarianSaveGame : public USaveGame
 {
@@ -72,4 +87,7 @@ public:
 
 	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Agrarian|Save")
 	TArray<FAgrarianSavedWorldActor> WorldActors;
+
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Agrarian|Save")
+	TArray<FAgrarianSavedResourceNode> ResourceNodes;
 };