Skip to content

Game.Tutorials.TutorialObjectSelectionTriggerSystem

Assembly:
Assembly-CSharp

Namespace:
Game.Tutorials

Type:
public class

Base:
TutorialTriggerSystemBase

Summary:
This system watches the player's current object selection (via ToolSystem) and evaluates active tutorial object-selection triggers. When the selection changes to an entity that matches a trigger's prefab, the system marks the trigger as completed or transitions the tutorial to another phase. The actual per-trigger work is performed in a Burst-compiled, parallel IJobChunk (CheckSelectionJob) which reads ObjectSelectionTriggerData buffers and uses an EntityCommandBuffer.ParallelWriter to add/remove trigger-related components. The system also creates a small archetype used to spawn unlock events (Event + Unlock) and calls TutorialSystem.ManualUnlock when a trigger is completed (and not transitioning to another phase).

Fields

  • private ToolSystem m_ToolSystem
    Holds a reference to the game's ToolSystem used to obtain the currently selected object (ToolSystem.selected). Initialized in OnCreate via World.GetOrCreateSystemManaged().

  • private EntityArchetype m_UnlockEventArchetype
    Archetype used for creating unlock event entities (components: Event, Unlock). Created in OnCreate and passed to TutorialSystem.ManualUnlock when needed.

  • private Entity m_LastSelection
    Tracks the last selection observed to detect changes and avoid re-processing the same selection repeatedly.

  • private TypeHandle __TypeHandle
    Container for cached ECS type handles / buffer lookups used by the job (BufferLookup, BufferLookup, BufferTypeHandle, EntityTypeHandle). Populated in OnCreateForCompiler / __AssignHandles.

  • private EntityQuery m_ActiveTriggerQuery (inherited/used)
    Query used to select active object-selection triggers (reads ObjectSelectionTriggerData and TriggerActive, excludes TriggerCompleted). The system calls RequireForUpdate on this query so it only runs when triggers exist.

  • Nested types:

  • private struct CheckSelectionJob : IJobChunk
    Burst-compiled job that iterates matching chunks, inspects each entity's ObjectSelectionTriggerData buffer, compares entries' m_Prefab to the current selection, and adds/removes components (TriggerCompleted, TriggerPreCompleted, TutorialNextPhase) and triggers ManualUnlock as required.
  • private struct TypeHandle
    Helper struct that caches BufferLookup/BufferTypeHandle/EntityTypeHandle and provides __AssignHandles(ref SystemState) to initialize them.

Properties

  • None specific to this class. The system relies on fields and ECS queries for its state.

Constructors

  • public TutorialObjectSelectionTriggerSystem()
    Default parameterless constructor with [Preserve] attribute present on lifecycle methods. No custom construction logic beyond what's performed in OnCreate.

Methods

  • protected override void OnCreate()
    Initializes the system: obtains the ToolSystem, builds the active trigger EntityQuery (ObjectSelectionTriggerData + TriggerActive, exclude TriggerCompleted), creates the m_UnlockEventArchetype (Event + Unlock), and calls RequireForUpdate(m_ActiveTriggerQuery). Also used to set up any cached state required before updates.

  • protected override void OnUpdate()
    Main update loop:

  • If triggersChanged flag is set (from base), update m_LastSelection to the current selection.
  • When the selected entity changes (ToolSystem.selected != Entity.Null and differs from m_LastSelection), the system:
    • Reads the PrefabRef component from the selected entity to get the prefab Entity.
    • Constructs and schedules a CheckSelectionJob (Burst, parallel) with buffer lookups, type handles, the selection prefab, the unlock event archetype, and an EntityCommandBuffer.ParallelWriter from the barrier system.
    • Schedules the job in parallel over m_ActiveTriggerQuery and registers its JobHandle with the barrier system for producer tracking.

  • Effectively performs per-trigger checks and marks triggers completed or pre-completed, transitions phases, or calls TutorialSystem.ManualUnlock when appropriate.

  • private void __AssignQueries(ref SystemState state)
    Generated helper (called from OnCreateForCompiler) to initialize any EntityQueryBuilder usage. In this file it constructs an empty EntityQueryBuilder and disposes it; primarily present for compiler-generated wiring.

  • protected override void OnCreateForCompiler()
    Compiler-time initialization helper that calls __AssignQueries(ref base.CheckedStateRef) and __TypeHandle.__AssignHandles(ref base.CheckedStateRef) to populate cached handles for use during job scheduling.

  • Nested method: void CheckSelectionJob.Execute(...) (IJobChunk)
    Iterates entities and their ObjectSelectionTriggerData buffer entries. For each buffer entry:

  • If objectSelectionTriggerData.m_Prefab equals the current selection prefab:
    • If m_GoToPhase != Entity.Null: add TutorialNextPhase (with m_NextPhase) and TriggerPreCompleted to the trigger entity.
    • Else: add TriggerCompleted to the trigger entity and call TutorialSystem.ManualUnlock to spawn unlock events using m_UnlockEventArchetype and the provided unlock-related buffer lookups.
  • If the prefab does not match the selection: remove TriggerPreCompleted and TutorialNextPhase from the trigger entity (to clear pre-completed/transitions if selection changed away). The job uses EntityCommandBuffer.ParallelWriter to safely add/remove components from multiple chunks in parallel.

Usage Example

// Example: create a trigger entity that completes when a specific prefab is selected.
// (This is conceptual — real usage depends on your mod initialization context.)

// Assume entityManager and prefabEntity (Entity) are available:
Entity trigger = entityManager.CreateEntity();
var buffer = entityManager.AddBuffer<ObjectSelectionTriggerData>(trigger);

// Add a trigger entry that completes the trigger (no phase change)
buffer.Add(new ObjectSelectionTriggerData {
    m_Prefab = prefabEntity,
    m_GoToPhase = Entity.Null
});

// Mark the trigger as active so the TutorialObjectSelectionTriggerSystem will process it:
entityManager.AddComponentData(trigger, new TriggerActive());

// The TutorialObjectSelectionTriggerSystem will detect when ToolSystem.selected becomes the same prefabEntity
// and will add TriggerCompleted to 'trigger' and invoke any configured unlocks.