Skip to content

Game.Vehicles.ReferencesSystem

Assembly: Assembly-CSharp
Namespace: Game.Vehicles

Type: class ReferencesSystem

Base: GameSystemBase

Summary:
ReferencesSystem is an ECS system that maintains and updates cross-references for vehicle entities (cars, trailers, watercraft, aircraft, trains, parked vehicles, route vehicles, etc.). It contains several Burst-compiled IJobChunk implementations that:

  • initialize per-vehicle lane references (matching vehicles to concrete sub-lanes),
  • keep layout/controller relationships consistent (layout elements and controllers),
  • update and remove references when vehicles are created or deleted (update owner buffers, lane objects, search tree, route buffers, transport depot maintenance requirements, etc.).

The system interacts with the ModificationBarrier5 (for entity command buffers), the SearchSystem (for the moving-object search quad-tree), many ComponentLookup/BufferLookup handles, and the native quad-tree used to spatially index moving objects. Jobs use Burst and run in parallel where applicable. Because it performs structural changes via a command buffer, it also coordinates job dependencies with the modification barrier and the search system.

Fields

  • private ModificationBarrier5 m_ModificationBarrier
    Holds the game's modification barrier system used to produce EntityCommandBuffer instances for safe structural changes from jobs.

  • private Game.Objects.SearchSystem m_SearchSystem
    Reference to the SearchSystem used to obtain a moving-object NativeQuadTree and to register writers so spatial indexes are updated safely.

  • private EntityQuery m_CarQuery
    EntityQuery used to find created vehicles that have CarCurrentLane (and are not Temp). Used by the InitializeCurrentLaneJob scheduling.

  • private EntityQuery m_VehicleQuery
    EntityQuery that matches vehicles and either Created or Deleted (and not Temp). Drives UpdateVehicleReferencesJob.

  • private EntityQuery m_LayoutQuery
    EntityQuery matching Deleted + (LayoutElement or Controller). Drives UpdateLayoutReferencesJob.

  • private TypeHandle __TypeHandle
    Internal struct caching ComponentTypeHandle / ComponentLookup / BufferLookup and other handles to avoid repeated GetHandle/GetLookup calls each update. Assigned in OnCreateForCompiler.

Properties

  • This class exposes no public properties.

Constructors

  • public ReferencesSystem()
    Default constructor (preserved attribute present on class members). System initialization is done in OnCreate / OnCreateForCompiler.

Methods

  • protected override void OnCreate()
    Sets up internal systems and entity queries:
  • obtains ModificationBarrier5 and SearchSystem instances,
  • builds the m_CarQuery, m_VehicleQuery and m_LayoutQuery,

  • calls RequireAnyForUpdate so the system will run only when relevant entities exist.

  • protected override void OnUpdate()
    Main update method. It:

  • schedules InitializeCurrentLaneJob if m_CarQuery is non-empty,
  • schedules UpdateLayoutReferencesJob if m_LayoutQuery is non-empty,
  • schedules UpdateVehicleReferencesJob if m_VehicleQuery is non-empty (wiring its dependencies with the SearchSystem and ModificationBarrier),
  • registers the job handles with the SearchSystem and ModificationBarrier and combines dependencies into base.Dependency.

The scheduled jobs perform the bulk of the logic for adding/removing references, updating buffers and the moving-object search tree, and enqueue structural changes through the command buffer.

  • protected override void OnCreateForCompiler()
    Internal assignment helper used at compile-time to assign the TypeHandle handles; it calls __AssignQueries and assigns the handles contained in __TypeHandle.

  • private void __AssignQueries(ref SystemState state)
    Internal helper used by OnCreateForCompiler (the implementation only uses an EntityQueryBuilder for compiler wiring in the compiled code).

  • private struct TypeHandle (nested)
    Holds ComponentTypeHandle, ComponentLookup, BufferLookup and EntityTypeHandle instances used by job structs. It contains a method __AssignHandles(ref SystemState) to fetch and cache those handles.

  • private struct InitializeCurrentLaneJob : IJobChunk (nested, BurstCompile)
    Reads Transform and CarCurrentLane and finds the best matching sub-lane for a vehicle's CarCurrentLane when the stored lane refers to a master lane. If it finds a matching sub-lane it updates CarCurrentLane.m_Lane and CarCurrentLane.m_CurvePosition accordingly. Uses ComponentLookup and BufferLookup for lane data, master lane groups, curves and owner-sub-lane buffers.

  • private struct UpdateLayoutReferencesJob : IJobChunk (nested, BurstCompile)
    Ensures layout <-> controller references remain consistent when layout elements or controllers are deleted. It:

  • clears Controller.m_Controller on vehicles referencing a deleted controller,

  • removes LayoutElement entries from a controller's layout buffer if the controller no longer references that vehicle.

  • private struct UpdateVehicleReferencesJob : IJobChunk (nested, BurstCompile)
    The largest job. For Created vehicles it:

  • adds vehicles to owner-owned-vehicle buffers,
  • sets CarKeeper.m_Car for personal cars,
  • adds vehicles to lane object buffers or the moving-object search tree (using ObjectGeometryData to compute bounds when needed),
  • adds route vehicles to route buffers.

For Deleted vehicles it: - removes entries from owner buffers, guest buffers, route buffers, - removes lane objects and updates lanes (using AddLaneComponent via the command buffer when necessary), - removes entities from the moving-object search tree, - updates transport depot maintenance requirements based on odometer distances and vehicle maintenance ranges.

The job uses a nested generic helper AddLaneComponent(Entity lane, T component) to add a lane component (and to mirror the component to matching master/sub-lanes when slave/master relationships are present). It also uses many ComponentLookup/BufferLookup handles and a NativeQuadTree for spatial indexing.

  • private void __AssignHandles(ref SystemState state) (method on TypeHandle)
    Populates all the cached ComponentTypeHandle/ComponentLookup/BufferLookup fields from the SystemState. This reduces runtime overhead from repeated handle lookups.

Nested types (summary)

  • InitializeCurrentLaneJob (IJobChunk, BurstCompile) — maps vehicles from master lanes to their concrete sub-lane based on proximity and lane-group matching.
  • UpdateLayoutReferencesJob (IJobChunk, BurstCompile) — keeps layout/controller references consistent.
  • UpdateVehicleReferencesJob (IJobChunk, BurstCompile) — handles adding/removing references and updating data structures on vehicle creation/deletion, and adds/removes lane objects and search-tree entries.
  • TypeHandle (private struct) — caches type/lookup handles used by the jobs.

Notes & Modding tips

  • The system uses Burst and IJobChunk (ECS) with command buffers and a shared NativeQuadTree. Avoid calling into these internals from the main thread or other systems without respecting job dependencies — use the available system APIs or create your own systems with correct dependency handling.
  • Structural changes are performed via the ModificationBarrier5 command buffer. If you create systems that interact with these same components/queries, make sure to coordinate job handles (AddJobHandleForProducer / AddMovingSearchTreeWriter) so you don't create race conditions.
  • Many component types used here are engine/internal (CarCurrentLane, TrainCurrentLane, LaneObject, etc.). Changing them directly may break engine invariants — prefer high-level APIs unless you fully control synchronization.
  • The system is performance-sensitive (spatial indexing, lane buffers, route buffers). When writing mods that interact with lane objects or moving search trees, limit updates and use batches where possible.

Usage Example

A minimal example showing how a GameSystemBase-derived class typically initializes itself (this mirrors the pattern ReferencesSystem uses for OnCreate):

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    // Create/obtain other systems and queries here, for example:
    // m_ModificationBarrier = base.World.GetOrCreateSystemManaged<ModificationBarrier5>();
    // m_SearchSystem = base.World.GetOrCreateSystemManaged<Game.Objects.SearchSystem>();
    // Build EntityQuery instances via GetEntityQuery(...) as needed.
}

If you need to interact with ReferencesSystem from another system, obtain it from the same World (be careful: many of its members are private/internal):

var refs = base.World.GetExistingSystemManaged<Game.Vehicles.ReferencesSystem>();
// Use public APIs only — most internals are private/internal and require correct synchronization.

If you plan to schedule jobs that touch the same components/lookups as ReferencesSystem, make sure to combine dependencies properly and respect the system's command buffer / search-tree writer registration to avoid race conditions.