Skip to content

Game.Net.ReferencesSystem

Assembly:
Namespace: Game.Net

Type: class

Base: GameSystemBase

Summary:
ReferencesSystem is an ECS system that keeps network node/edge connectivity information in sync. It updates ConnectedEdge and ConnectedNode buffers for network edges and nodes, validates node references, removes references for deleted entities and rationalizes (chooses best) connections when multiple candidate edges attach to a node. The system uses multiple Burst-compiled jobs (IJobChunk, IJob, IJobParallelForDefer) to perform updates in parallel and leverages Unity's ECS ComponentLookup/BufferLookup/TypeHandle patterns. This is a core system for the net (roads/rails/etc.) subsystem — modders should be careful when changing net components or connected buffers as this system enforces invariants and cleans up references.

Fields

  • private EntityQuery m_EdgeQuery
    This query selects Edge components that have been Updated or Deleted. Used to produce an archetype chunk list of edges to process by UpdateEdgeReferencesJob, RationalizeConnectedNodesJob and AddConnectedNodeReferencesJob.

  • private EntityQuery m_NodeQuery
    This query selects Node components that have been Updated or Deleted. Used to schedule UpdateNodeReferencesJob which removes/cleans connected-edge references on nodes.

  • private EntityQuery m_TempEdgeQuery
    Query selecting temporary edges (Temp + Edge) that are not Updated/Deleted. Used by ValidateConnectedNodesJob to validate connected nodes for temporary edges.

  • private TypeHandle __TypeHandle
    Holds all component/lookup/buffer type handles used by the system (EntityTypeHandle, ComponentTypeHandles, ComponentLookup, BufferTypeHandle, BufferLookup, etc.). __TypeHandle.__AssignHandles(...) initializes these handles from the SystemState before scheduling jobs.

  • private struct UpdateNodeReferencesJob (nested)
    Burst-compiled IJobChunk that updates ConnectedEdge buffers on node archetype chunks. Removes references to edges that are marked Updated or removes all node references for Deleted nodes.

  • private struct ValidateConnectedNodesJob (nested)
    Burst-compiled IJobChunk used to validate ConnectedNode buffers (on temp edges) by removing references to deleted nodes.

  • private struct UpdateEdgeReferencesJob (nested)
    Burst-compiled IJob that iterates provided edge archetype chunks and updates node<->edge cross references. Removes references for deleted edges and accumulates ConnectedNodeValue entries for further rationalization.

  • private struct RationalizeConnectedNodesJob (nested)
    Burst-compiled IJobParallelForDefer that processes edges (deferred chunk list) and the multi-hashmap of connected node candidates to decide which edge actually connects to which node (choosing best fit, taking prefab local connect flags, building owners, elevations, tunnels, etc. into account). This job contains many helper methods (ClampCurvePosition, GetNodePosition, ValidateConnection, AllowConnection, GetTopOwner, etc.). It allocates small temporary NativeParallelHashMap/NativeList to compute curve bounds and node positions and disposes them before exit.

  • private struct AddConnectedNodeReferencesJob (nested)
    Burst-compiled IJob that adds ConnectedEdge references back to node buffers after rationalization — ensures nodes have connected-edge entries corresponding to edges that refer to them.

  • private struct ConnectedNodeValue (nested)
    A small value struct used by UpdateEdgeReferencesJob / RationalizeConnectedNodesJob to pair an edge Entity with a curve position (float) for a particular node key in the NativeParallelMultiHashMap.

Notes: many nested types are Burst-compiled jobs. They rely heavily on ComponentLookup/BufferLookup and are designed for safe parallel execution with Unity's Job system.

Properties

  • None (the system exposes no public properties).
    {{ This system is purely internal to the ECS flow and exposes behavior through its queries and scheduled jobs. Modders should not rely on public properties — instead use ECS queries or schedule systems that run after this system if you need to read the connected buffers. }}

Constructors

  • public ReferencesSystem()
    {{ Default constructor. The system relies on OnCreate to initialize its entity queries. The constructor itself is empty and preserved for ECS. }}

Methods

  • protected override void OnCreate() : System.Void
    {{ Initializes entity queries used by the system:
  • m_EdgeQuery selects Edge + (Updated | Deleted)
  • m_NodeQuery selects Node + (Updated | Deleted)

  • m_TempEdgeQuery selects Temp + Edge and excludes Updated/Deleted These queries determine which archetype chunks are processed by the various jobs scheduled in OnUpdate. The method is marked with [Preserve] to ensure it remains available for reflection/IL stripping. }}

  • protected override void OnUpdate() : System.Void
    {{ Main system update. High-level flow:

  • If there are node changes, schedule UpdateNodeReferencesJob to remove or update connected-edge entries on node buffers. Also optionally schedule ValidateConnectedNodesJob for temporary edges.
  • If there are edge changes, gather edge archetype chunks (ToArchetypeChunkListAsync), create a NativeParallelMultiHashMap to accumulate connected-node candidates, then:
    • Run UpdateEdgeReferencesJob to populate the map and update ConnectedEdge buffers.
    • Schedule RationalizeConnectedNodesJob (IJobParallelForDefer) to select valid connections per node using rich prefab/owner/elevation/building rules.
    • Schedule AddConnectedNodeReferencesJob to add resulting ConnectedEdge entries to node buffers.
  • Manage dependencies and dispose of Native collections after jobs complete.

Jobs are Burst-compiled for performance; proper job dependency chaining and disposal is observed. Modders changing connected-buffer layout or node/edge component semantics must ensure compatibility with these jobs. }}

  • protected override void OnCreateForCompiler() : System.Void
    {{ Helper used by the generated/compiled code path to assign query(s) and type handles for the compiler/reflection path. Calls __AssignQueries(...) and __TypeHandle.__AssignHandles(...). This is an internal integration point. }}

  • private void __AssignQueries(ref SystemState state) : System.Void
    {{ Internal helper (used by OnCreateForCompiler) which currently constructs/disposes an EntityQueryBuilder; in the decompiled code it is a no-op aside from creating an EntityQueryBuilder(Allocator.Temp). This exists to satisfy the compiler-generated setup routine. }}

  • private struct TypeHandle.__AssignHandles(ref SystemState state) : System.Void
    {{ Initializes all stored type handles (entity, component handles, buffer handles, and lookup handles) from the provided SystemState. This must be called on the main thread before using the handles inside jobs. It maps the TypeHandle's fields to the Unity ECS runtime handles. }}

Additional job helper methods (inside RationalizeConnectedNodesJob):
- ClampCurvePosition, GetNodePosition, AreNeighbors, GetOriginals, ValidateConnection, GetTopOwner, AllowConnection, GetElevationFlags — these implement the complex geometry and prefab-based validation rules used to decide whether an edge actually connects to a node and to compute safe curve position ranges.

Usage Example

// Run your custom system after ReferencesSystem so connected buffers are stable
[UpdateAfter(typeof(Game.Net.ReferencesSystem))]
public class MyNetReaderSystem : GameSystemBase
{
    [Preserve]
    protected override void OnUpdate()
    {
        // It is now safe to read ConnectedEdge/ConnectedNode buffers updated by ReferencesSystem.
        // For example, query nodes and iterate ConnectedEdge buffer to inspect adjacent edges.
    }
}

{{ YOUR_INFO: Tips for modders - If you modify ConnectedEdge or ConnectedNode buffer layouts or semantics, update ReferencesSystem (and its jobs) accordingly — it assumes specific data layout and semantics. - The system relies on many prefab component lookups (PrefabRef, NetData, NetGeometryData, LocalConnectData, BuildingData, ServiceUpgradeData, etc.) to validate connections; changes to prefab data may affect rationalization logic. - Jobs are Burst-compiled; be mindful when adding managed code or non-Burst-friendly constructs inside nested job structs. - To extend or influence connection selection, consider placing a system with [UpdateAfter(typeof(Game.Net.ReferencesSystem))] that reacts to already-rationalized connected buffers rather than modifying this system unless you need to change core connection rules. - Temporary native containers (NativeParallelMultiHashMap, NativeList, NativeParallelHashMap) are allocated and disposed across job dependencies — ensure any additional allocations follow the same lifecycle and are disposed on the correct job handle. }}