Skip to content

Game.LaneReferencesSystem

Assembly: Game (assembly containing game systems)
Namespace: Game.Net

Type: class

Base: GameSystemBase

Summary:
LaneReferencesSystem is an ECS system responsible for maintaining and updating lane references in the transportation network. It keeps SubLane buffers on owner entities in sync with Lane entities, fixes path node references for skipped or temporarily processed lanes, and computes lane ordering/indices (master/slave grouping and flags) for use by pathfinding and vehicle routing. The system schedules several Burst-compiled jobs (IJobChunk and IJob) to perform these operations in parallel and uses a ModificationBarrier for deferred entity component changes. It also exposes a mechanism for other code to enqueue "skipped" lanes (NativeQueue) to be fixed later on the main update.

Fields

  • private ModificationBarrier4B m_ModificationBarrier
    Used to create EntityCommandBuffer.ParallelWriter for safely adding/removing components from jobs and to register producer job handles for the barrier.

  • private EntityQuery m_LanesQuery
    Query selecting Lane entities with an Owner and either Created or Deleted component and excluding SecondaryLane. Used to update SubLane buffers for owners.

  • private EntityQuery m_UpdatedOwnersQuery
    Query selecting owners that have SubLane buffer and Updated component. Used when only incremental updates are needed.

  • private EntityQuery m_AllOwnersQuery
    Query selecting all owners that have SubLane buffer. Used after a game load to force a full refresh.

  • private NativeQueue<Lane> m_SkipLaneQueue
    A NativeQueue used to collect lanes that must be "skipped" / fixed later. Allocated via GetSkipLaneQueue() with Allocator.TempJob and disposed internally after the fix jobs are scheduled.

  • private JobHandle m_SkipLaneDeps
    Holds dependencies from external jobs that write to m_SkipLaneQueue. Provided via AddSkipLaneWriter(JobHandle).

  • private bool m_Loaded
    Flag toggled by OnGameLoaded to indicate a full refresh is required on the next update.

  • private TypeHandle __TypeHandle
    Container of component/handle type handles used to build job data. Assigned in OnCreateForCompiler.

Properties

  • (none public)
    All component/handle lookups are handled internally via the TypeHandle struct and local job fields. There are no public properties on this system.

Constructors

  • public LaneReferencesSystem()
    Default constructor. Marked with [Preserve]. Initializes the GameSystemBase and relies on OnCreate to set up queries and barriers.

Methods

  • [Preserve] protected override void OnCreate()
    Initializes internal resources: retrieves/creates the ModificationBarrier4B system and sets up the following EntityQueries:
  • m_LanesQuery: select Lane + Owner and Created | Deleted, exclude SecondaryLane
  • m_UpdatedOwnersQuery: owners with SubLane buffer and Updated

  • m_AllOwnersQuery: owners with SubLane buffer (used after load) Registers required queries for the system.

  • protected override void OnGameLoaded(Context serializationContext)
    Called when the game finish-loading. Sets m_Loaded = true to request a full owner SubLane refresh on the next update.

  • private bool GetLoaded()
    Checks and consumes the m_Loaded flag (returns true once after a load, then resets it). Used to decide whether to schedule a full refresh (m_AllOwnersQuery) instead of incremental updates.

  • public NativeQueue<Lane> GetSkipLaneQueue()
    Allocates and returns a NativeQueue with Allocator.TempJob. This queue is used to enqueue lanes that need to be fixed later by the system (e.g., lanes that were "skipped" during path node computation). The system will take ownership of disposing the queue when scheduled jobs complete.

  • public void AddSkipLaneWriter(JobHandle dependency)
    Used by other code to provide a JobHandle dependency representing jobs that will write to the skip-lane queue returned by GetSkipLaneQueue(). The dependency is used to ensure FixSkippedLanes and FillNodeMap jobs run after producers finish.

  • [Preserve] protected override void OnUpdate()
    Main update loop:

  • If there are lanes (m_LanesQuery not empty), schedule UpdateLaneReferencesJob to ensure owner SubLane buffers reflect newly created/deleted lanes and to add SubLane entries with proper PathMethod flags.
  • If a skip-lane queue was created, build a temporary path-node map with FillNodeMapJob, schedule FixSkippedLanesJob (IJobChunk) to correct path nodes for skipped lanes and possibly add PathfindUpdated to lanes that changed, then dispose the queue and path-node map (handled with job dependencies). The system registers produced jobs with the ModificationBarrier4B.
  • Based on whether the system is in "loaded" state or not, select either m_AllOwnersQuery (full refresh) or m_UpdatedOwnersQuery (incremental) and schedule UpdateLaneIndicesJob (IJobChunk) which sorts sub-lanes, computes master/slave lane indices, sets slave flags (MultipleLanes, OpenStart/EndLeft/Right, Merging, etc.) and toggles TramTrack/TrainTrack components on owners if track type changes.

  • Adds job handles to the modification barrier where appropriate and updates base.Dependency.

  • private void __AssignQueries(ref SystemState state)
    Generated helper: currently creates (and disposes) an empty EntityQueryBuilder; kept for compiler compatibility.

  • protected override void OnCreateForCompiler()
    Compiler-time setup that calls __AssignQueries and assigns handles in __TypeHandle.

Nested/Burst jobs (summary):

  • UpdateLaneReferencesJob : IJobChunk (BurstCompile)
    Reads Entity and Owner components and various lane type markers (PedestrianLane, CarLane, TrackLane, ParkingLane, ConnectionLane) to compute PathMethod flags for each SubLane entry. Adds new SubLane entries to owner buffers or removes entries if lane entity has Deleted.

  • FillNodeMapJob : IJob (BurstCompile)
    Consumes a NativeQueue and builds a NativeHashMap mapping a lane's start/middle/end nodes to a canonical PathNode that points to the middleNode (secondaryNode: false). Used to repair path node references for lanes flagged as skipped.

  • FixSkippedLanesJob : IJobChunk (BurstCompile)
    Uses the path-node map produced by FillNodeMapJob to update stored PathNode references in Lane data for lanes that may have been skipped. Also inspects connected edges and sub-lanes of neighboring edges to potentially update start/end/middle nodes and set PathfindUpdated component on modified lanes via the command buffer.

  • UpdateLaneIndicesJob : IJobChunk (BurstCompile)
    For each owner with a SubLane buffer, builds a temporary list of SubLaneOrder entries and sorts them to compute grouping (master/slave), indices, master min/max, slave min/max/subindex/masterindex and slave flags (MultipleLanes, OpenStart/EndLeft/Right, Merging). Also detects track-type changes and adds/removes TramTrack/TrainTrack components on owner entities via the modification barrier.

  • SubLaneOrder (struct)
    Sorting helper used by UpdateLaneIndicesJob to order sub-lanes by group and index.

  • TypeHandle (struct)
    Holds all Entity/Component/Buffer type handles and a method __AssignHandles(ref SystemState) to obtain them from the current SystemState.

Notes and caveats: - Many of the jobs use Burst and NativeCollections and assume proper synchronization via JobHandles. When using GetSkipLaneQueue(), callers must call AddSkipLaneWriter with the producer job handle so the system schedules its consumer jobs after the producer completes. - GetSkipLaneQueue allocates with Allocator.TempJob and the system disposes the queue internally (via a job dependency). Do not attempt to dispose it yourself. - The system uses a ModificationBarrier4B to apply structural changes (Add/Remove component) from job threads. It registers producer JobHandles on the barrier so changes are safely applied.

Usage Example

// Example: enqueue skipped lanes from another job and inform LaneReferencesSystem about the dependency.

public partial struct SomeProducerJob : IJob
{
    public NativeQueue<Lane>.ParallelWriter skipLaneWriter;
    public void Execute()
    {
        // Enqueue lanes that need to be fixed later
        // skipLaneWriter.Enqueue(lane);
    }
}

// Elsewhere in a system that has a reference to LaneReferencesSystem instance:
[Preserve]
protected override void OnUpdate()
{
    // Acquire the queue from the LaneReferencesSystem (allocates Allocator.TempJob)
    NativeQueue<Lane> skipQueue = laneReferencesSystem.GetSkipLaneQueue();

    // Create and schedule a producer job that enqueues lanes
    SomeProducerJob producer = new SomeProducerJob
    {
        skipLaneWriter = skipQueue.AsParallelWriter()
    };
    JobHandle prodHandle = producer.Schedule();

    // Tell LaneReferencesSystem about the producer dependency so it waits for the writer
    laneReferencesSystem.AddSkipLaneWriter(prodHandle);

    // Do not dispose skipQueue here – LaneReferencesSystem will dispose it when its jobs complete.
    // Continue with other work...
}