Skip to content

Game.Simulation.WatercraftNavigationSystem

Assembly:
Namespace: Game.Simulation

Type: class

Base: GameSystemBase

Summary:
WatercraftNavigationSystem is the ECS system responsible for updating watercraft navigation each simulation tick. It gathers entities that represent watercraft and their navigation data and runs several Burst-compiled jobs (including a parallel IJobChunk) to: - build and maintain navigation lanes and path segments for ships, - select optimal lanes and handle lane changes, - reserve lanes and group reservations, - update lane signals and lane reservation components, - apply lane-related side effects (pollution, etc.), - update lane objects via LaneObjectUpdater, - interact with spatial search trees (net/area/object) and various component lookups.

The system uses an EntityQuery to operate on watercraft entities, schedules parallel jobs (JobChunk) and follow-up single-threaded jobs, and registers read access with the game's search systems. It runs on a reduced update frequency (update interval 16 with offset 8) to spread work across frames.

Fields

  • private Game.Net.SearchSystem m_NetSearchSystem
    Holds a reference to the net search system (road/lanes search quadtree provider). Used to obtain a read-only search tree for lane queries when scheduling navigation jobs.

  • private Game.Areas.SearchSystem m_AreaSearchSystem
    Reference to the area search system. Used to obtain area search trees for area-lane navigation and target finding.

  • private Game.Objects.SearchSystem m_ObjectSearchSystem
    Reference to the object search system. Used to obtain static and moving object search trees for collision and lane finding.

  • private EntityQuery m_VehicleQuery
    Query used to select watercraft entities to process. The query requires components such as Watercraft, Transform, Target, PrefabRef, UpdateFrame, PathElement, PathOwner, WatercraftCurrentLane, WatercraftNavigation and navigation lane buffers.

  • private LaneObjectUpdater m_LaneObjectUpdater
    Helper that collects and applies lane object updates produced while processing navigation. It returns a LaneObjectCommandBuffer used by the UpdateNavigationJob and later applies its results.

  • private TypeHandle __TypeHandle
    Internal type handle struct used to cache and assign the many ComponentTypeHandle / ComponentLookup / BufferLookup instances needed by the burst jobs.

Properties

This class exposes no public properties.

Constructors

  • public WatercraftNavigationSystem()
    Default constructor. The system is normally created and managed by the World; the constructor simply initializes the managed system instance.

  • protected override void OnCreate()
    Called when the system is created. The system sets up its EntityQuery, gets references to the search systems, creates the LaneObjectUpdater and calls RequireForUpdate with the vehicle query so it only runs when watercraft exist.

Methods

  • public override int GetUpdateInterval(SystemUpdatePhase phase)
    Returns the update interval used by this system. The system returns 16 (runs every 16 frames of its phase), used to spread CPU work across frames.

  • public override int GetUpdateOffset(SystemUpdatePhase phase)
    Returns the update offset used by this system. The system returns 8, used together with the interval to stagger updates.

  • protected override void OnCreate()
    (See Constructors) Initializes system members and the entity query. It calls base.OnCreate(), fetches the net/area/object search systems from World and prepares the LaneObjectUpdater. It calls RequireForUpdate(m_VehicleQuery) so that the system only runs when applicable entities exist.

  • protected override void OnUpdate()
    Main update entry. Allocates NativeQueues for lane reservations, lane effects and lane signals, constructs and schedules:

  • UpdateNavigationJob (burst IJobChunk) scheduled parallel over the vehicle query (performs the bulk of navigation work),
  • UpdateLaneReservationsJob (single-threaded IJob) to write lane reservation components,
  • ApplyLaneEffectsJob to apply queued side effects (pollution),
  • UpdateLaneSignalsJob to update LaneSignal components,
  • GroupLaneReservationsJob (internal helper used to group reservations; used inside the job chain),

  • and integrates LaneObjectUpdater results. It also registers job handles with the search systems (AddNetSearchTreeReader / AddSearchTreeReader / AddStaticSearchTreeReader / AddMovingSearchTreeReader) to ensure safe concurrent reads, and sets base.Dependency to the combined job handles.

  • protected override void OnCreateForCompiler()
    Internal helper used by generated code path to assign ComponentTypeHandle/ComponentLookup handles and to call __AssignQueries. Used for compile-time bookkeeping of handles.

  • private void __AssignQueries(ref SystemState state)
    Internal helper used by OnCreateForCompiler to create/assign any EntityQueryBuilder placeholders; kept for compiler compatibility.

  • private struct TypeHandle.__AssignHandles(ref SystemState state)
    (Not directly called by user code) Assigns all ComponentTypeHandle / ComponentLookup / BufferLookup fields inside the TypeHandle for use in jobs. This method is in the nested TypeHandle struct.

  • Nested job structs (Burst compiled) used internally (summaries):

  • UpdateNavigationJob : IJobChunk — The core job. Iterates vehicle chunks and updates navigation lanes, fills navigation paths, selects lanes, checks blockers, computes targets, reserves lanes, enqueues signals/effects/reservations, and updates per-entity navigation components and buffers.
  • GroupLaneReservationsJob : IJob — Dequeues lane reservations, sorts and groups them for efficient batched processing.
  • UpdateLaneSignalsJob : IJob — Dequeues lane signals and updates LaneSignal components with highest priority petitioners.
  • UpdateLaneReservationsJob : IJob — Dequeues lane reservation items and updates LaneReservation component entries (next offset/priorities).
  • ApplyLaneEffectsJob : IJob — Dequeues lane side-effects and applies pollution/effects to the owner entities.

Most of the heavy logic is contained inside UpdateNavigationJob and helper iterators (WatercraftLaneSelectIterator, WatercraftLaneSpeedIterator, VehicleCollisionIterator, etc.) which are used to compute lane selection, speeds, blockers and movement targets.

Usage Example

// Systems of this type are normally created and managed by the World.
// Example: get the system instance from your mod code and (if needed) inspect it.
var navSystem = World.GetOrCreateSystemManaged<Game.Simulation.WatercraftNavigationSystem>();

// Typical pattern inside your own SystemBase/ISystem to ensure ordering:
// Require the watercraft navigation system to run before/after yours by
// retrieving it and using its update interval/offset or by manipulating system order.
[UnityEngine.Scripting.Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    // Ensure any data your system needs is ready when watercraft navigation runs,
    // or schedule dependencies appropriately in OnUpdate().
}

Notes: - This system is Burst-compiled in places and relies on many component lookups and native containers. Modifying its internal behavior requires careful thread-safety and Burst compatibility considerations. - The system intentionally runs at a lower frequency (GetUpdateInterval = 16) to amortize cost across frames; do not assume it runs every simulation tick.