Skip to content

Game.Objects.ContainerClearSystem

Assembly:
Namespace: Game.Objects

Type: class

Base: GameSystemBase

Summary:
ContainerClearSystem is an ECS system used during the New Game startup to trim empty sub‑object buffers from object entities. It inspects entities that have SubObject, Game.Net.SubNet and Game.Areas.SubArea buffers (and an Object component but are not Buildings) and compares the instance buffers to the prefab definitions. If the instance buffers are empty and the prefab has no corresponding sub entries, the system removes the corresponding buffer components (or all of them at once). Additionally, if the prefab defines effect buffers but the entity has no EnabledEffect buffer, the system will add that buffer. This reduces archetype/component clutter for newly created worlds.

Fields

  • private LoadGameSystem m_LoadGameSystem
    ContainerClearSystem caches a reference to the LoadGameSystem to check the current load context (NewGame vs loading existing saves). The system only performs its clearing work when the load context is Purpose.NewGame.

  • private EntityQuery m_EntityQuery
    The query selects entities that contain SubObject, Game.Net.SubNet, Game.Areas.SubArea and Object components and explicitly excludes Building. This query is required for the system to run and is used to schedule the worker job.

  • private ComponentTypeSet m_SubTypes
    A ComponentTypeSet prebuilt with writable component types SubObject, Game.Net.SubNet and Game.Areas.SubArea. This is used to remove multiple components at once via an EntityCommandBuffer when appropriate.

  • private TypeHandle __TypeHandle
    Holds the various ComponentTypeHandles, BufferTypeHandles and BufferLookups used by the job. The handles are assigned in OnCreateForCompiler and used to obtain the appropriate handles when scheduling the job.

Properties

  • None

Constructors

  • public ContainerClearSystem()
    Default constructor. The system uses Preserve attributes on lifecycle methods; construction is trivial and initialization occurs in OnCreate.

Methods

  • protected override OnCreate() : System.Void
    Initializes the system: obtains the LoadGameSystem instance, constructs the entity query (SubObject, Game.Net.SubNet, Game.Areas.SubArea, Object; exclude Building) and sets up m_SubTypes. The query is marked as required for update (RequireForUpdate) so the system will only run when matching entities exist.

  • protected override OnUpdate() : System.Void
    Runs each frame (but effectively only does work during New Game). If LoadGameSystem.context.purpose == Purpose.NewGame, it schedules a parallel ContainerClearJob over the m_EntityQuery. The job inspects each entity in the query and:

  • Checks instance buffers lengths (SubObject, SubNet, SubArea) and whether the prefab contains corresponding sub buffers (via BufferLookup on prefab).
  • If all three sub buffers are absent on both the instance and prefab, it removes the entire component set (m_SubTypes) from the entity.
  • If only some are absent, it individually removes the empty buffer components.

  • If the prefab has effect buffers but the entity lacks an EnabledEffect buffer, the job adds an EnabledEffect buffer to the entity. The job is scheduled with an EntityCommandBuffer.ParallelWriter and completed before playback; the ECB is then played back on the EntityManager and disposed.

  • protected override OnCreateForCompiler() : System.Void
    Internal initialization used by generated code / compiler-time wiring. Assigns query placeholders and calls TypeHandle.__AssignHandles to populate the component/buffer handles for subsequent job scheduling.

  • private void __AssignQueries(ref SystemState state)
    Internal; currently creates and disposes a temporary EntityQueryBuilder. Present for completeness of the compiled system scaffolding.

  • TypeHandle.__AssignHandles(ref SystemState state)
    Assigns EntityTypeHandle, BufferTypeHandles, ComponentTypeHandle and BufferLookups that the ContainerClearJob needs. Called from OnCreateForCompiler so the job can obtain correct handles at scheduling time.

  • ContainerClearJob.Execute(in ArchetypeChunk chunk, int unfilteredChunkIndex, bool useEnabledMask, in v128 chunkEnabledMask)
    The Burst‑compiled chunk job that implements the clearing logic described above. It:

  • Reads entity array, PrefabRef components and buffer accessors for instance data.
  • Uses BufferLookup to check prefab buffer definitions (prefabRef.m_Prefab).
  • Uses an EntityCommandBuffer.ParallelWriter to remove/add components in a thread‑safe manner.
  • Tests all three sub-buffer types together and individually to decide whether to remove the whole set or individual buffer components. The job is scheduled in parallel across matching chunks.

Usage Example

// ContainerClearSystem runs automatically as a GameSystemBase in the world.
// It will run its trimming logic only when a NewGame is started (LoadGameSystem.context.purpose == Purpose.NewGame).
// Example: if you want to test or simulate its behavior in a mod test, create entities with PrefabRef and SubObject/SubNet/SubArea buffers.
// The system will remove empty instance buffers when the prefab itself does not define those sub items.

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    // ContainerClearSystem is initialized by the game framework.
    // No manual wiring is required; ensure your prefabs/components are registered correctly if you add new sub buffers.
}

Notes and modder tips: - This system runs only during new game initialization to avoid modifying saved data on load. - The job uses BufferLookup on prefabs — if you add dynamic prefab buffers in a mod, ensure the prefab buffers are present on the prefab entity so clearing logic behaves as expected. - Because changes are applied via an EntityCommandBuffer scheduled with the job and then played back on the main thread, you should not expect immediate structural changes inside the job body; they are committed after PlayBack. - The job is Burst compiled and uses parallel scheduling; be careful to use thread-safe API and avoid managed containers inside the job.