Skip to content

Game.Creatures.ReferencesSystem

Assembly: Assembly-CSharp (game assembly)
Namespace: Game.Creatures

Type: class

Base: GameSystemBase

Summary:
ReferencesSystem is a Unity ECS system used by the game to keep entity-level references for creature entities in sync. It reacts to creatures being Created or Deleted and updates related data structures and components: owned creature buffers on owners, CurrentTransport components for residents/pets, passenger buffers on vehicles, lane object buffers (Net lane indexing) or a moving spatial search tree for creatures not on a lane, and removal/cleanup when creatures are deleted. The heavy work is performed in a Burst-compiled IJobChunk (UpdateCreatureReferencesJob) scheduled from OnUpdate; the system also uses a ModificationBarrier5 to perform structural changes and a SearchSystem to get a moving search tree writer.

Fields

  • private ModificationBarrier5 m_ModificationBarrier
    This barrier is used to create an EntityCommandBuffer for structural changes that must be applied safely while jobs are running (adding/removing components, etc.). It is acquired from the World in OnCreate.

  • private Game.Objects.SearchSystem m_SearchSystem
    Reference to the game's SearchSystem which provides access to a moving search tree (spatial index) used to locate and query non-lane creatures. The search tree writer is requested when scheduling the job.

  • private EntityQuery m_CreatureQuery
    Query that matches all Creature entities and requires Created or Deleted changes (and excludes Temp). This query drives RequireForUpdate so the system only updates when relevant creature entities change.

  • private TypeHandle __TypeHandle
    Holds component type handles and lookups used by the job. The generated TypeHandle struct contains EntityTypeHandle, multiple ComponentTypeHandle (read-only), ComponentLookup and BufferLookup instances. __TypeHandle is initialized for the compiler path in OnCreateForCompiler.

Properties

  • None.
    This system exposes no public properties.

Constructors

  • public ReferencesSystem()
    Default constructor. The system relies on OnCreate to initialize runtime references (ModificationBarrier5, SearchSystem, EntityQuery).

Methods

  • protected override void OnCreate()
    Initializes the system: obtains the ModificationBarrier5 and SearchSystem from the World, builds the creature EntityQuery (Creature with Created/Deleted change filter, excluding Temp), and calls RequireForUpdate(m_CreatureQuery) so the system only runs when creatures appear/disappear.

  • protected override void OnUpdate()
    Creates and schedules the Burst-compiled UpdateCreatureReferencesJob. The job receives type handles and lookups extracted from __TypeHandle (via InternalCompilerInterface.Get... calls), the moving search tree from m_SearchSystem (out dependency), and an EntityCommandBuffer from m_ModificationBarrier. After scheduling the job, the system registers the search tree writer and the modification barrier producer handle, and assigns the job handle to base.Dependency.

  • protected override void OnCreateForCompiler()
    Compiler-time initialization path: assigns queries and calls __TypeHandle.__AssignHandles to bind the component type lookups used by generated code.

  • [MethodImpl(MethodImplOptions.AggressiveInlining)] private void __AssignQueries(ref SystemState state)
    Compiler helper used to create/assign queries for the system. In the decompiled code it creates an EntityQueryBuilder and disposes it (placeholder used by generated code).

  • (nested) private struct UpdateCreatureReferencesJob : IJobChunk
    Burst-compiled job that processes archetype chunks of Creature entities. For chunks with the Created component present it:

  • Adds creatures to their owner's OwnedCreature buffer.
  • Sets CurrentTransport.m_CurrentTransport for Residents and Pets to the creature entity when appropriate.
  • Adds passengers to vehicle passenger buffers.
  • For entities with HumanCurrentLane or AnimalCurrentLane that have a lane buffer, adds a LaneObject entry to that lane buffer; otherwise, computes bounds (using Transform, PrefabRef and ObjectGeometryData) and adds an entry to the moving search tree. For chunks without Created (i.e. deletions), it:
  • Removes creatures from owner buffers.
  • Removes CurrentTransport components from citizens/pets if they pointed to the deleted creature (via CommandBuffer).
  • Removes passengers from vehicle buffers.
  • Removes lane objects from lane buffers or removes entries from the search tree.

The job uses multiple ComponentTypeHandle and BufferLookup to access and mutate data safely in jobs, and writes to the provided EntityCommandBuffer for structural changes.

  • (nested) private struct TypeHandle
    Generated struct that stores all the EntityTypeHandle, ComponentTypeHandle, ComponentLookup, and BufferLookup used by the job. It has a method __AssignHandles(ref SystemState) which initializes all handles from a SystemState (used for JIT/AOT/compiler paths).

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    // Acquire the modification barrier and search system used by this system.
    m_ModificationBarrier = base.World.GetOrCreateSystemManaged<ModificationBarrier5>();
    m_SearchSystem = base.World.GetOrCreateSystemManaged<Game.Objects.SearchSystem>();

    // Build the query to monitor creature entities and require it for update.
    m_CreatureQuery = GetEntityQuery(new EntityQueryDesc
    {
        All = new ComponentType[1] { ComponentType.ReadOnly<Creature>() },
        Any = new ComponentType[2]
        {
            ComponentType.ReadOnly<Created>(),
            ComponentType.ReadOnly<Deleted>()
        },
        None = new ComponentType[1] { ComponentType.ReadOnly<Temp>() }
    });
    RequireForUpdate(m_CreatureQuery);
}

Note: The real reference implementation also schedules a Burst IJobChunk (UpdateCreatureReferencesJob) in OnUpdate which performs the bulk of the reference synchronization work. Modders generally don't need to reimplement that logic unless changing ownership/transport/lane behaviors; instead they can read or interact with the data structures updated by this system (OwnedCreature buffers, CurrentTransport component, lane buffers, and the SearchSystem moving search tree).