Prefab Instantiation (SaveablePrefabFactory)

Overview

SaveablePrefabFactory is Crystal Save’s dedicated instantiation utility for spawning SaveablePrefab assets in a safe, save-system-aware way. It acts as a one-stop shop for creating instances of prefabs that:

• Automatically get their SaveablePrefab component added if missing.

• Properly generate and register Unique IDs.

• Correctly hook into the save system so the object can be restored after a load.

• Avoid common pitfalls with features such as Remember Home Scenes, where Unity’s default Instantiate() can break persistence tracking.

---

Why not just use Instantiate()?

While Unity’s built-in Instantiate() works for most gameplay scenarios, it has limitations in the context of Crystal Save:

• Missing SaveablePrefab logic Unity’s Instantiate() won’t ensure that your spawned object has a SaveablePrefab component or that it’s registered with the save system.

• No Unique ID setup If you manually add SaveablePrefab after instantiation, you may forget to assign or regenerate its UniqueID, leading to conflicts or lost data.

• Remember Home Scenes instability If you use Remember Home Scenes, objects instantiated through Unity’s method may fail to correctly record their originating scene. This can cause them to be lost, duplicated, or misplaced when loading.

SaveablePrefabFactory ensures all of the above are handled automatically.

---

Key Advantages

Feature	Unity Instantiate()	SaveablePrefabFactory.Instantiate()
Ensures SaveablePrefab component exists	❌	✅
Auto-generates and registers Unique IDs	❌	✅
Automatically sets Prefab Asset ID	❌	✅
Registers with Crystal Save system	❌	✅
Works reliably with Remember Home Scenes	⚠️ Can bug out	✅
Optional scene targeting before spawn	❌	✅
Supports fresh Unique ID creation on demand	❌	✅

Basic Usage

1. Instantiate a SaveablePrefab

var instance = SaveablePrefabFactory.Instantiate(
    myPrefabAsset,                      // Prefab with (or without) SaveablePrefab component
    new Vector3(0, 0, 0),               // Position
    Quaternion.identity,                // Rotation
    parentTransform,                    // Optional parent
    true                                 // Register with save system
);

This will:

1. Instantiate the prefab at the given position/rotation.

2. Add SaveablePrefab if missing.

3. Generate/verify its Unique ID.

4. Store the reference to the original prefab asset.

5. Optionally register it with the save system so it will be saved.

---

2. Instantiate in a Specific Scene

var instance = SaveablePrefabFactory.Instantiate(
    myPrefabAsset,
    new Vector3(0, 0, 0),
    Quaternion.identity,
    "MySceneName" // Target scene by name
);

The factory will set the active scene to "MySceneName" before instantiation, ensuring the object is tracked in the correct scene.

---

3. Force a Fresh Unique ID

When you want a brand-new identity for the object (e.g., when cloning templates):

var instance = SaveablePrefabFactory.InstantiateWithFreshID(
    myPrefabAsset,
    new Vector3(0, 0, 0),
    Quaternion.identity
);

This will force a new Unique ID even if the prefab asset already has one, avoiding accidental ID collisions.

---

Remember Home Scenes Considerations

Remember Home Scenes tracks the originating scene of a prefab instance so it can be restored exactly where it came from.

• If you use Unity’s default Instantiate() There’s a high chance the origin tracking will fail—especially if the prefab wasn’t fully initialized with its SaveablePrefab data before registration.

• If you use SaveablePrefabFactory The prefab is:

  • Given its correct PrefabAssetID.

  • Registered in the Prefab Registry.

  • Flagged as added at runtime.

  • Fully aware of its home scene before being registered.

This prevents the "Home Scene bug-out" issue and guarantees correct restoration behavior.

---

When to Always Use SaveablePrefabFactory

• Spawning enemies, pickups, projectiles, or interactables that must survive across saves.

• Creating runtime objects in procedurally generated levels.

• Adding persistent objects during cutscenes or quests.

• Any object that uses Remember Home Scenes.

---

Summary

• Unity’s Instantiate() is fine for non-persistent, temporary objects.

• SaveablePrefabFactory.Instantiate() is the safe, persistence-aware alternative.

• It guarantees IDs, registration, prefab tracking, and scene awareness—eliminating common bugs in persistent object handling.