Game.Objects.AttachSystem

Assembly:
Namespace: Game.Objects

Type: class

Base: GameSystemBase

Summary:
AttachSystem is an ECS System responsible for maintaining "attached" relationships between placeable objects (props, decorations, subobjects) and their parent net/building entities (nodes, edges, curves, placeholders). It runs two main jobs each frame (when relevant entities exist): - FindAttachedParentsJob: scans candidate parent archetypes (nodes/edges/placeholder entities) to find the closest/most appropriate parent for each object with an Attached component, computing curve positions and parent Entity references. - UpdateAttachedReferencesJob: applies changes to attachments (adds/removes Attachment components or updates SubObject buffers, flags for deletion for optional attachments, computes refunds for deleted temps) using a command buffer from a ModificationBarrier.

The system also queries for temp-subobject candidates and uses world systems (ModificationBarrier3, SimulationSystem) and component lookups to make attachment decisions consistent with owner relationships, placeholder creation, and geometry rules (placement flags, base collision, water/raised logic).

Fields

private ModificationBarrier3 m_ModificationBarrier
This barrier system is used to create an EntityCommandBuffer for safely adding/removing components (Attachment, Attached) and setting component data from jobs.
private SimulationSystem m_SimulationSystem
Reference to the SimulationSystem used to obtain the current simulation frame index (m_SimulationSystem.frameIndex) for economics/refund calculations.
private EntityQuery m_ObjectQuery
Query that finds all entities with Object + Attached and either Updated or Deleted. Required for system updates — represents the objects whose attachment should be checked/maintained.
private EntityQuery m_TempQuery
Query that finds temporary subobjects (Temp + SubObject) on archetypes that include Edge, Node or Placeholder and are not Deleted. Used as potential parent pools when objects are temporary.
private EntityQuery m_EconomyParameterQuery
Query to access singleton EconomyParameterData used when computing refunds for deleted temps in UpdateAttachedReferencesJob.
private TypeHandle __TypeHandle
Generated container for all EntityTypeHandle, ComponentTypeHandle and ComponentLookup/BufferLookup instances the system needs. The internal __AssignHandles method populates these handles from a SystemState.
public struct RemovedAttached
Helper struct (Compiler generated grouping) holding an entity pair with m_Entity and m_Parent. Not used directly in public API, present for internal bookkeeping.
private struct FindAttachedParentsJob (BurstCompile)
IJobParallelForDefer that inspects each "attached" object and searches parent archetype chunks to find a matching parent entity and curve position according to geometry, placement flags and owner rules. Uses many ComponentLookup and ComponentTypeHandle members and writes to Attached components via a ComponentLookup.
Responsibilities:
- Skip deleted chunks.
- For each attached entity, if a parent already set and it's a placeholder, attempt to resolve an actual parent.
- For unattached entities, evaluate proximity to node/edge/curve parents (considering geometry bounds, width/height ranges, water/raised flags, owner relationships) and set attached.m_Parent and attached.m_CurvePosition when a suitable parent is found.
- Supports optional attach geometry (GeometryFlags.OptionalAttach) and relocation/temporary logic with Temp flags.
private struct UpdateAttachedReferencesJob (BurstCompile)
IJob that iterates attached object chunks to synchronize Attachment components, SubObject buffers, and mark unattached optional objects for deletion/refund. Uses an EntityCommandBuffer to add/remove components after job completes.
Responsibilities:
- Build a NativeHashMap mapping placeholder parents to the new attached entity so placeholders can later be resolved to the real attachment.
- Ensure SubObject buffers on parent entities contain the subobject reference (try-add / remove as appropriate).
- For temps that are optional but orphaned, mark them for deletion and compute refund using Recent + EconomyParameterData.
- Add or remove the Attachment component on parent entities depending on whether they have an attached child.

Properties

(none)
AttachSystem does not expose public properties. It operates through ECS queries, lookups and jobs.

Constructors

public AttachSystem()
Default constructor. The system is [Preserve]-annotated OnCreate/OnUpdate are used to initialize queries and references to world systems.

Additional info: System initialization occurs in OnCreate where it grabs ModificationBarrier3 and SimulationSystem, creates required EntityQueries, and calls RequireForUpdate for the relevant queries so the system only runs when objects exist.

Methods

protected override void OnCreate() : System.Void
Initializes the system:
Obtains ModificationBarrier3 and SimulationSystem from the World.
Creates three EntityQueries: m_ObjectQuery (Object + Attached + (Updated|Deleted)), m_TempQuery (Temp + SubObject + (Edge|Node|Placeholder) - Deleted), and m_EconomyParameterQuery (singleton EconomyParameterData).
Calls RequireForUpdate on the object and economy queries so the system remains inactive unless needed.
Also prepares the TypeHandle via __AssignHandles in compiler-time helper (OnCreateForCompiler).
protected override void OnUpdate() : System.Void
Main update entry; schedules the two jobs and handles their dependencies:
Collects archetype chunk lists for objects (attached entities). If there are temp candidate parents, also collects parent chunks and schedules FindAttachedParentsJob in parallel over attached chunks (deferred job array) which inspects parent chunks.
Schedules UpdateAttachedReferencesJob (IJob) which runs after parent-finding completes (ensures new attachment info is visible) and performs final Attachment/SubObject/Temp-delete/refund updates using an EntityCommandBuffer from m_ModificationBarrier.
Disposes temporary native lists and registers job handles with m_ModificationBarrier.
protected override void OnCreateForCompiler() : System.Void
Compiler helper used to wire up generated handles and queries. It calls __AssignQueries and __TypeHandle.__AssignHandles to prepare the TypeHandle and queries at compile-time helper stage.
private void __AssignQueries(ref SystemState state) : System.Void
Generated helper — currently creates (and immediately disposes) an EntityQueryBuilder; used during compiled initialization. The system uses the explicit queries defined in OnCreate in most logic.
private struct TypeHandle.__AssignHandles(ref SystemState state) : System.Void
Populates all EntityTypeHandle, ComponentTypeHandle and ComponentLookup/BufferLookup fields used by the nested jobs. Called from OnCreateForCompiler to cache handles for safety/performance.

Usage Example

// Example: access the AttachSystem from another system or mod initialization
[Preserve]
protected override void OnCreate()
{
    base.OnCreate();

    // Get or create the AttachSystem in the current World
    var attachSystem = World.GetOrCreateSystemManaged<Game.Objects.AttachSystem>();

    // The system runs automatically based on its EntityQueries. You can force it to update
    // by enabling the objects that match its queries or by calling World.Update() on the simulation loop,
    // but normally you don't need to manually invoke its OnUpdate.
}

Notes: - AttachSystem is tightly integrated with the game's geometry and placement rules. When modding, be careful when altering Attached/Attachment/SubObject, PrefabRef, ObjectGeometryData or NetGeometryData structures as they affect how parents are found and how optional attachments are handled. - The system uses Burst-compiled jobs and Unity's DOTS low-level handles; to interact safely from managed code, prefer using EntityCommandBuffer or use the same component lookups in your own Burst jobs and respect chunk/temporal access patterns.