Game.TutorialObjectSelectedActivationSystem

Assembly: Game
Namespace: Game.Tutorials

Type: class TutorialObjectSelectedActivationSystem

Base: GameSystemBase

Summary:
System that detects when the player has selected or is using a specific prefab/tool and activates tutorials associated with that prefab. It scans entities that have an ObjectSelectionActivationData dynamic buffer and, when the currently selected prefab (or tool prefab) matches an entry in that buffer (and tool allowances match), it adds a TutorialActivated component to the corresponding entity. The logic runs as a Burst-compiled parallel job (ActivateJob) and uses an EntityCommandBufferSystem (ModificationBarrier4) to apply component additions safely from jobs.

This system: - Looks for entities with Buffer and without TutorialActivated or TutorialCompleted. - Resolves the currently selected prefab/entity from multiple tool systems (ToolSystem, ObjectToolSystem, NetToolSystem, AreaToolSystem, RouteToolSystem) and PrefabSystem. - Schedules a parallel IJobChunk (ActivateJob) to mark matching entities with TutorialActivated. - Integrates with Unity Entities Job System and Burst for performance.

Fields

private EntityCommandBufferSystem m_BarrierSystem
Holds the barrier system used to create EntityCommandBuffer for issuing commands (adding TutorialActivated) from jobs. The barrier used is ModificationBarrier4 obtained from the world on OnCreate.
private PrefabSystem m_PrefabSystem
Reference to PrefabSystem used to map prefabs to entities when tools supply a prefab reference.
private ToolSystem m_ToolSystem
Reference to the core ToolSystem used to determine the currently selected tool and selected entity (m_ToolSystem.selected).
private ObjectToolSystem m_ObjectToolSystem
Reference to the object placement tool, used to obtain its current prefab selection (if active).
private NetToolSystem m_NetToolSystem
Reference to the net tool, used to obtain its current prefab selection (if active).
private AreaToolSystem m_AreaToolSystem
Reference to the area tool, used to obtain its current prefab selection (if active).
private RouteToolSystem m_RouteToolSystem
Reference to the route tool, used to obtain its current prefab selection (if active).
private EntityQuery m_TutorialQuery
EntityQuery that matches entities with ObjectSelectionActivationData buffer and excludes entities already marked TutorialActivated or TutorialCompleted. Used to drive the job scheduling.
private TypeHandle __TypeHandle
Internal struct holding the BufferTypeHandle and EntityTypeHandle used by the job. Populated via __AssignHandles during system initialization.
private struct ActivateJob (nested)
Burst-compiled IJobChunk that iterates matching chunks, inspects the ObjectSelectionActivationData dynamic buffers and, when the selected prefab matches and tool conditions are satisfied, adds a TutorialActivated component to the entity via an EntityCommandBuffer.ParallelWriter.
private struct TypeHandle (nested)
Helper struct used to cache and assign the buffer/entity type handles from the SystemState for use in jobs.

Properties

This system exposes no public properties. All state is maintained privately and accessed through methods and job data.

Constructors

public TutorialObjectSelectedActivationSystem()
Default constructor. The system relies on OnCreate to collect references to required systems and prepare its EntityQuery. Marked with [Preserve] on the actual OnCreate method to survive code stripping/runtime.

Methods

protected override void OnCreate()
Sets up references to required systems (ModificationBarrier4, PrefabSystem, ToolSystem, ObjectToolSystem, NetToolSystem, AreaToolSystem, RouteToolSystem) and creates the EntityQuery that selects entities with ObjectSelectionActivationData and excludes TutorialActivated and TutorialCompleted. Called once when the system is created.
protected override void OnUpdate()
Main update loop. If the query is not empty, determines the currently selected prefab/entity via GetSelection(out bool tool). If a valid selection exists, constructs and schedules the Burst-compiled ActivateJob as a parallel job across the query. The job is provided with buffer and entity type handles (via InternalCompilerInterface and __TypeHandle), the selection entity, the tool flag, and an EntityCommandBuffer.ParallelWriter from the barrier system. Adds the returned job handle to the barrier system for correct dependency handling.
private Entity GetSelection(out bool tool)
Determines the currently selected prefab/entity and whether the selection came from a tool. Logic:
If the active selected entity (m_ToolSystem.selected) has a PrefabRef component, this is treated as a non-tool selection (tool = false) and returns the referenced prefab entity.
Otherwise, if the active tool equals one of the specific tool systems (ObjectToolSystem, NetToolSystem, AreaToolSystem, RouteToolSystem) and that tool has a prefab set, returns the corresponding prefab entity (tool = true).
If no relevant selection is found, returns Entity.Null and sets tool = false. This method centralizes the platform-specific selection resolution used by ActivateJob.
private void __AssignQueries(ref SystemState state)
Internal method used by compiler-generated initialization. In this class implementation it creates and disposes an empty EntityQueryBuilder; real useful query assignment happens in OnCreate above.
protected override void OnCreateForCompiler()
Compiler helper that calls __AssignQueries and assigns type handles using the SystemState. Ensures the __TypeHandle has correct handles before jobs are scheduled.
private struct ActivateJob.Execute(...) (IJobChunk implementation)
For each chunk, retrieves BufferAccessor and the chunk's entity array. Iterates each element, calls Check on the DynamicBuffer. If Check returns true, enqueues adding TutorialActivated to that entity using the parallel EntityCommandBuffer. The job uses the entity index from the chunk (unfilteredChunkIndex) for parallel writer ordering.
private bool Check(DynamicBuffer<ObjectSelectionActivationData> datas)
Checks whether any entry in the buffer has m_Prefab equal to the system's m_Selection and, if m_Tool is true, that the entry allows tool activation (m_AllowTool). Returns true if a match is found; otherwise false.

Notes on related data types: - ObjectSelectionActivationData (dynamic buffer) — expected to contain fields: m_Prefab (Entity) and m_AllowTool (bool). Entities with this buffer are candidates for being activated when the matching prefab is selected. - TutorialActivated (component) — marker component added to an entity to indicate the tutorial should be activated. - TutorialCompleted (component) — marker component excluded by the query so already completed tutorials are not reactivated.

Performance and safety: - The ActivateJob is Burst-compiled for efficiency. - Uses EntityCommandBuffer.ParallelWriter to safely modify entity components from jobs. - Type handles are cached via __TypeHandle and retrieved through InternalCompilerInterface to satisfy safety checks.

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    m_BarrierSystem = base.World.GetOrCreateSystemManaged<ModificationBarrier4>();
    m_PrefabSystem = base.World.GetOrCreateSystemManaged<PrefabSystem>();
    m_ToolSystem = base.World.GetOrCreateSystemManaged<ToolSystem>();
    m_ObjectToolSystem = base.World.GetOrCreateSystemManaged<ObjectToolSystem>();
    m_NetToolSystem = base.World.GetOrCreateSystemManaged<NetToolSystem>();
    m_AreaToolSystem = base.World.GetOrCreateSystemManaged<AreaToolSystem>();
    m_RouteToolSystem = base.World.GetOrCreateSystemManaged<RouteToolSystem>();
    m_TutorialQuery = GetEntityQuery(
        ComponentType.ReadOnly<ObjectSelectionActivationData>(),
        ComponentType.Exclude<TutorialActivated>(),
        ComponentType.Exclude<TutorialCompleted>()
    );
}

Additional modding tips: - Ensure entities that should be activated by selection have an ObjectSelectionActivationData buffer populated with the proper prefab Entity references (use PrefabSystem.GetEntity when mapping Prefab objects to Entities). - If you extend or replace the activation logic, preserve the barrier/job pattern to avoid race conditions when adding components from jobs. - Test tool vs non-tool activation cases: entries in ObjectSelectionActivationData must have m_AllowTool set appropriately if activation should occur while the user is actively using a placement tool.