Game.Tutorials.TutorialAreaTriggerSystem

Assembly: Game
Namespace: Game.Tutorials

Type: class

Base: TutorialTriggerSystemBase

Summary:
System that watches area entities and active tutorial area triggers. When areas are created or updated that match an active AreaTriggerData (matching prefab and flags), the system marks the trigger entity as completed (TriggerPreCompleted for the first-time check, TriggerCompleted otherwise) and issues an unlock event via an EntityCommandBuffer. Implementation uses a Burst-compiled IJobChunk (CheckModifiedAreasJob) to efficiently process chunks in parallel and relies on an EntityQuery for modified areas and an active trigger query required for update.

---

Fields

• private Unity.Entities.EntityQuery m_AreaModificationQuery
  Query that selects area entities with PrefabRef + Area that have the Updated component (and excludes Deleted/Temp/Native). Used to detect modified/created areas to compare against active triggers.

• private Unity.Entities.EntityQuery m_AreaQuery
  Query that selects all area entities with PrefabRef + Area (excluding Deleted/Temp/Native). Used when doing the first-time check over all areas.

• private Unity.Entities.EntityArchetype m_UnlockEventArchetype
  Archetype created to spawn unlock event entities (Event + Unlock components) when a trigger fires.

• private TypeHandle __TypeHandle
  Container struct that stores Component/Buffer/Entity type handles used by the job; populated via __AssignHandles and used when constructing jobs and lookups.

• private struct CheckModifiedAreasJob (nested)
  Burst-compiled IJobChunk that performs the core logic: it receives a list of area-modification archetype chunks and, for every active trigger entity, checks whether any modified/created area matches the trigger's prefab and flags. When matching, it adds completion marker components and invokes TutorialSystem.ManualUnlock to enqueue unlock events via the provided EntityCommandBuffer. This job holds buffer and component type handles and a parallel command buffer writer.

• private struct TypeHandle (nested)
  Holds BufferTypeHandle/BufferLookup/ComponentTypeHandle/EntityTypeHandle instances used to access component data in jobs. It exposes __AssignHandles(ref SystemState) to populate those handles from a SystemState.

Properties

• None declared on this class. (All state is managed via private fields and nested type handles; inherited members may exist on the base class.)

Constructors

• public TutorialAreaTriggerSystem()
  Default constructor. Marked with [Preserve] on lifecycle methods; constructor is empty and relies on OnCreate to initialize queries and archetypes.

Methods

• protected override void OnCreate()
  Initializes queries: m_AreaModificationQuery (PrefabRef + Area + Updated), m_AreaQuery (PrefabRef + Area), and m_ActiveTriggerQuery (AreaTriggerData + TriggerActive, excluding TriggerCompleted). Creates m_UnlockEventArchetype (Event + Unlock). Calls RequireForUpdate(m_ActiveTriggerQuery) so the system only updates if there are active triggers.

• protected override void OnUpdate()
  Main update logic. If base.triggersChanged is true, it performs a first-time check against all areas (uses m_AreaQuery) and constructs a CheckModifiedAreasJob with m_FirstTimeCheck = true. Otherwise, if there are modified areas (m_AreaModificationQuery not empty), constructs CheckModifiedAreasJob with m_FirstTimeCheck = false. Both code paths:

• Obtain archetype chunk lists asynchronously (ToArchetypeChunkListAsync) and schedule the job in parallel with JobChunkExtensions.ScheduleParallel.
• Use InternalCompilerInterface to get runtime BufferTypeHandle / BufferLookup / ComponentTypeHandle / EntityTypeHandle from __TypeHandle and base.CheckedStateRef.
• Use a parallel EntityCommandBuffer from the system's barrier system to add components and spawn unlock events.

• Dispose the chunk list via jobData.m_AreaModificationChunks.Dispose(base.Dependency) and register the dependency with m_BarrierSystem.

• private void __AssignQueries(ref SystemState state)
  Compiler-generated helper used by OnCreateForCompiler; currently empty aside from a temporary EntityQueryBuilder dispose (no custom query assignments beyond OnCreate).

• protected override void OnCreateForCompiler()
  Compiler-only initialization helper called by generated code: calls base.OnCreateForCompiler(), invokes __AssignQueries(ref base.CheckedStateRef), and calls __TypeHandle.__AssignHandles(ref base.CheckedStateRef) to populate the type handles for job construction.

• TypeHandle.__AssignHandles(ref SystemState state)
  Assigns the BufferTypeHandle, BufferLookup, EntityTypeHandle and ComponentTypeHandle fields from the provided SystemState. Called before scheduling jobs so the job has correct type handles.

• CheckModifiedAreasJob.Execute(in ArchetypeChunk chunk, int unfilteredChunkIndex, bool useEnabledMask, in v128 chunkEnabledMask)
  IJobChunk Execute implementation. For each trigger entity in the given chunk, it calls the private Check(DynamicBuffer) to determine if any area modifications match the trigger. If a match is found, it adds TriggerPreCompleted (first-time) or TriggerCompleted, and calls TutorialSystem.ManualUnlock with the relevant buffers and the parallel command buffer to issue unlocks.

• CheckModifiedAreasJob.Check(DynamicBuffer triggerDatas) : bool
  Iterates the provided list of m_AreaModificationChunks. For each chunk it determines AreaTriggerFlags based on presence of Created and Updated component types on that chunk. Then for each AreaTriggerData in the trigger buffer, if the trigger's flags intersect the current area flags it compares the PrefabRef of entities in the chunk to areaTriggerData.m_Prefab. Returns true if any match is found (meaning the trigger should fire).

Notes on concurrency and safety: - The job uses a NativeList obtained via ToArchetypeChunkListAsync; that list is disposed after scheduling with Dispose(base.Dependency). - Command buffer usage is AsParallelWriter() so AddComponent calls use the unfilteredChunkIndex to generate unique ordering. - BufferLookup and BufferTypeHandle accesses are obtained via InternalCompilerInterface lookups and the __TypeHandle prepared during OnCreateForCompiler.

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();

    // This system already sets up:
    // - m_AreaModificationQuery = PrefabRef + Area + Updated (excl Deleted/Temp/Native)
    // - m_AreaQuery = PrefabRef + Area (excl Deleted/Temp/Native)
    // - m_ActiveTriggerQuery = AreaTriggerData + TriggerActive (excl TriggerCompleted)
    // and creates the unlock event archetype.

    // If you extend this system, call base.OnCreate() and then modify queries/archetypes as needed.
}

{{ Additional info: - Purpose: This system links in-game area changes (creation/updates) to tutorial triggers that target specific prefabs and area change types. When a trigger condition is satisfied, it both marks the trigger completed and queues unlock events to grant tutorial progression or UI unlocks. - Performance: Designed for large-scale data by using Burst-compiled IJobChunk scheduled in parallel and minimizing main-thread work. The matching algorithm checks prefab equality by comparing PrefabRef.m_Prefab values. - Extending: To add new trigger types or different matching rules, either extend AreaTriggerData and the Check logic in the job or create a new job that uses the same pattern (chunk lists + parallel command buffer). - Important components referenced: AreaTriggerData, AreaTriggerFlags, Area, PrefabRef, Created, Updated, TriggerActive, TriggerCompleted, TriggerPreCompleted, UnlockRequirement, ForceUIGroupUnlockData, TutorialSystem.ManualUnlock, Event, Unlock. }}