Predicted Hierarchy

The Predicted Hierarchy system provides a set of methods for dynamically creating, deleting, and managing objects within the simulation. These methods allow developers to interact with the hierarchy in a way that feels natural and Unity-like, while ensuring that all changes are predictable and synchronized with the server.

Key Methods

1. Object Creation:

   • Create Methods:

     • Instantiates objects in the simulation.

     • Supports creating objects from prefab IDs or GameObject references.

     • Optionally allows specifying position and rotation.

     • Returns a PredictedObjectID to uniquely identify the created object.

     public PredictedObjectID? Create(int prefabId);
     public PredictedObjectID? Create(int prefabId, Vector3 position, Quaternion rotation);
     public PredictedObjectID? Create(GameObject prefab);
     public PredictedObjectID? Create(GameObject prefab, Vector3 position, Quaternion rotation);

   • TryCreate Methods:

     • Attempts to create an object and returns a boolean indicating success.

     • Outputs the PredictedObjectID of the created object.

     • Fails if prefab id is invalid or prefab isn't part of the registered prefab list.

     public bool TryCreate(int prefabId, out PredictedObjectID id);
     public bool TryCreate(GameObject prefab, out PredictedObjectID id);

2. Object Deletion:

   • Delete Methods:

     • Removes objects from the simulation using their PredictedObjectID.

     • Handles both pooled and non-pooled objects.

     public void Delete(PredictedObjectID id);
     public void Delete(PredictedObjectID? id);

3. Object Retrieval:

   • GetGameObject:

     • Retrieves the GameObject associated with a PredictedObjectID.

     public GameObject GetGameObject(PredictedObjectID? id);

   • GetComponent:

     • Retrieves a specific component from the GameObject associated with a PredictedObjectID.

     public T GetComponent<T>(PredictedObjectID? id) where T : Component;

   • TryGetId:

     • Retrieves the PredictedObjectID associated with a GameObject.

     public bool TryGetId(GameObject go, out PredictedObjectID id);

   • TryGetGameObject:

     • Retrieves the GameObject associated with a PredictedObjectID and returns a boolean indicating success.

     public bool TryGetGameObject(PredictedObjectID? id, out GameObject go);

Prefabs and Pooling

• Predicted object creation uses a central PredictedPrefabs asset referenced by PredictionManager.

• Prefabs can opt into pooling; pooled instances are kept under a hidden parent for fast reuse.

• When reconciling, pooled objects may be disabled/enabled; avoid parenting critical visuals to the root identity if you rely on SetActive state — or use PredictedTransform’s optional graphics unparenting.

Spawning Network Identities

• Use PredictedIdentitySpawner to mirror a set of NetworkIdentity objects between server and clients based on prediction state.

• The spawner coordinates early spawn, observer assignment, ownership, and finalization in both server and verified client passes.

Best Practices

• Only create/destroy from within simulation code paths (or via machine/state transitions) to keep behavior deterministic under replay.

• Prefer TryCreate and check the boolean to handle invalid or unregistered prefabs gracefully.

• Store and pass around PredictedObjectID rather than GameObject to remain resilient across rollbacks.