Unity Object Pooling

Gnosis Engine uses a centralized pooling system for managing Unity GameObjects efficiently. This system is driven by the UnityObjectPoolRegistry and allows for both inspector-driven setup and dynamic, data-driven prewarming.

Code path: Runtime/GnosisEngine/Adapters/Unity/Pooling/UnityObjectPoolRegistry.cs.

Configuration

The registry maintains a list of UnityPoolEntryConfig objects. Each entry defines how a specific prefab should be pooled.

Properties

Property	Description
`tag`	The unique identifier for the pool (e.g., `Explosion_Small`).
`prefabId`	The ID of the prefab in the Unity Asset Registry.
`prewarmCount`	Number of instances to instantiate during initialization.
`shouldExpand`	Whether the pool should grow if all instances are currently active.
`bucketName`	Optional name of the parent transform for organizational purposes.

Data-Driven Prewarming

The pooling system can be configured dynamically via the Gnosis state store. This is typically done through the Configuration Service by loading a JSON file into Persistent.configuration.pooling.

Example: `pooling.json`

pooling.json


[
  {
    "tag": "vfx_hit_spark",
    "prefabId": "vfx_hit_spark",
    "prewarmCount": 10,
    "shouldExpand": true,
    "bucketName": "VFX"
  }
]

Integration with Adapters

Many Unity adapters, such as the UnityAnimationAdapter, rely on this pooling system to manage particle effects and other transient GameObjects.

Lifecycle

Awake/Enable: The registry ensures it is initialized.
InitializePool: Creates the requested “buckets” (parent GameObjects) and instantiates the prewarm count for each entry.
Get/Return: Standard pooling operations using IUnityObjectPoolRegistry interface.