Restore pooled Object

Crystal Save supports pooling-friendly saving of prefabs via the SaveablePrefab component (aka Remember Prefab). This allows you to dynamically spawn and despawn GameObjects (e.g. projectiles, enemies, pickups) while retaining their state during save/load operations.

When to Use

Use SaveablePrefab for GameObjects that are:

• Instantiated at runtime (pooled or manually spawned)

• Not part of the initial scene

• Need to be saved and restored during gameplay

---

📦 Setup: Making Your Prefab Saveable

1. Create or open your prefab in the Unity Editor.

2. Add the SaveablePrefab component:

   • Right-click the root of the prefab and choose: Add Component → Crystal Save → SaveablePrefab

3. (Optional) Add a RememberComposite (aka Remember Component):

   • Use this if your prefab needs to save multiple custom components.

   • It manages internal SaveableComponent types that do not need to be manually added.

   • Add via: Add Component → Crystal Save → Remember Components → Remember Component

   • Then click "Add Remember Component…" in the inspector to choose which ones to track.

4. Ensure a UniqueID exists:

   • This is automatically handled by SaveablePrefab or added via RememberComposite.

   • If Unity warns that a Unique ID is missing duplicated, use the “Check Duplicate Unqiue IDs” menu shown in the editor or click in the Remember Component on the Button UniqueID to create a new one.

---

🧠 Runtime Integration

Registering Pooled Prefabs

If your prefabs are instantiated via an object pooling system, make sure to:

• Call OnBeforeSpawn() right before spawning:

pooledObject.OnBeforeSpawn(); // refresh UniqueID and register

• Call OnBeforeDespawn() right before returning to pool:

pooledObject.OnBeforeDespawn(); // unregister from save system

These methods are part of the IPoolableSaveable interface that SaveablePrefab implements internally:

public void OnBeforeSpawn() {
    SetUniqueID(Guid.NewGuid().ToString());
    RegisterForSaving();
}

public void OnBeforeDespawn() {
    UnregisterFromSaving();
}

💾 Saving the Prefab

Crystal Save automatically tracks SaveablePrefab instances:

• When saving, Crystal Save serializes the prefab’s:

  • Position, rotation, scale

  • Custom SaveableComponent data

  • Rigidbody and Animator state

  • Visibility state (if PersistentVisibilityController is used)

  • Any runtime modifications captured through CaptureRuntimeModifications()

• When loading, Crystal Save:

  • Destroys all existing dynamic prefabs unless configured not to

  • Instantiates missing prefabs based on saved data

  • Reapplies saved state (position, visibility, physics, animation, etc.)

This behavior is driven by the PrefabManager, which automatically collects and restores all registered prefabs.

---

✅ Verification

To verify everything works:

1. Instantiate your pooled prefab.

2. Modify its transform or state at runtime.

3. Save the game using Crystal Save.

4. Close and reload the game.

5. The prefab should be restored with its correct state and position.

---

🛑 Limitations

• SaveablePrefab requires a unique instance per saved object. Do not assign the same UniqueID manually.

• Scene references (e.g., parenting to scene objects) may only work correctly if the parent is also saveable (requires UniqueID added automatically through Remember Component).

• Pooling systems that reset objects in a way that destroys components may interfere with proper restoration.

Example Code

// Spawning a pooled prefab
var obj = myPool.Spawn(prefab);
var saveable = obj.GetComponent<SaveablePrefab>();
saveable.OnBeforeSpawn();

// Despawning it later
saveable.OnBeforeDespawn();
myPool.Despawn(obj);