Predicted Hierarchy

Edit this page on GitHub →

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

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);
```
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);
```
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.