Game.Tutorials.TutorialEventActivationSystem

Assembly:
Assembly-CSharp (Game runtime assembly where Game.* types live)

Namespace:
Game.Tutorials

Type:
public class

Base:
Game.Common.GameSystemBase

Summary:
Manages a persistent NativeQueue of tutorial event entities that should be "activated" at the end of the frame. External jobs/systems can obtain access to the queue (and supply their JobHandle dependencies) so that this system will wait for those jobs to complete, dequeue the entities and add a TutorialActivated component to each entity using a command buffer obtained from the ModificationBarrier4 (an EntityCommandBufferSystem). The system ensures the queue is created on OnCreate and disposed on OnDestroy.

Fields

protected Unity.Entities.EntityCommandBufferSystem m_BarrierSystem
Holds a reference to the ModificationBarrier4 command buffer system (retrieved via World.GetOrCreateSystemManaged in OnCreate). Used to create an EntityCommandBuffer to make structural changes (adding TutorialActivated) at a safe point.
private Unity.Collections.NativeQueue<Unity.Entities.Entity> m_ActivationQueue
A persistent NativeQueue used to queue entities that should be activated. It is allocated with Allocator.Persistent in OnCreate and disposed in OnDestroy.
private Unity.Jobs.JobHandle m_InputDependencies
Accumulates job dependencies from writers via AddQueueWriter so OnUpdate can wait for those jobs to complete before reading/dequeueing the queue.

Properties

(none)
This class exposes no public properties. Interaction is through the GetQueue and AddQueueWriter methods.

Constructors

public TutorialEventActivationSystem()
Default public constructor. The class relies on Unity lifecycle methods (OnCreate / OnDestroy / OnUpdate) to initialize and tear down state.

Methods

public NativeQueue<Entity> GetQueue(out JobHandle dependency)
Returns the internal NativeQueue so other code can enqueue entities to be activated. Also outputs the current accumulated JobHandle (m_InputDependencies) via the out parameter so callers can combine/chain their own job dependencies with the system’s dependency. Note: when writing to the queue from jobs, callers should use the queue's AsParallelWriter() (or appropriate concurrent writer) from the returned queue and then call AddQueueWriter with the returned job handle.
public void AddQueueWriter(JobHandle dependency)
Combine the supplied dependency with the system's existing m_InputDependencies using JobHandle.CombineDependencies. This lets the activation system know about additional pending jobs that will write to the queue so it can wait for them to finish in OnUpdate.
protected override void OnCreate()
Initializes the system: calls base.OnCreate(), retrieves the ModificationBarrier4 EntityCommandBufferSystem from the World and allocates the m_ActivationQueue with Allocator.Persistent.
protected override void OnDestroy()
Disposes the NativeQueue to free memory. Calls base.OnDestroy() as well.
protected override void OnUpdate()
Main execution: completes m_InputDependencies (ensures any jobs that wrote to the queue have finished), creates an EntityCommandBuffer from m_BarrierSystem, then dequeues every entity and adds the TutorialActivated component to each via the command buffer. This performs the activation as a structural change at the appropriate point.

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    // (This is what the system already does)
    m_BarrierSystem = World.GetOrCreateSystemManaged<ModificationBarrier4>();
    m_ActivationQueue = new NativeQueue<Entity>(Allocator.Persistent);
}

// Example: how an external producer (job/system) could enqueue entities for activation
void ScheduleProducerWork(TutorialEventActivationSystem activationSystem)
{
    // Get current dependency and queue
    JobHandle existingDependency;
    var queue = activationSystem.GetQueue(out existingDependency);

    // If scheduling a job that will write to the queue, use AsParallelWriter and return its handle.
    var parallelWriter = queue.AsParallelWriter();
    var job = new MyProducerJob { writer = parallelWriter /*, ... */ }
               .Schedule(existingDependency);

    // Tell the activation system about this writer job so it will wait for it in OnUpdate
    activationSystem.AddQueueWriter(job);
}

// OnUpdate of the activation system will then:
[Preserve]
protected override void OnUpdate()
{
    m_InputDependencies.Complete(); // wait for producers
    var ecb = m_BarrierSystem.CreateCommandBuffer();
    Entity e;
    while (m_ActivationQueue.TryDequeue(out e))
    {
        ecb.AddComponent<TutorialActivated>(e);
    }
}

Notes and best practices: - When enqueuing from a job, use NativeQueue.AsParallelWriter() (or other thread-safe writer) and schedule the job. Then call AddQueueWriter with the job's handle so the activation system will wait before reading the queue. - The queue is allocated with Allocator.Persistent and disposed in OnDestroy; do not hold onto returned NativeQueue references beyond the lifetime of this system. - Structural changes (adding TutorialActivated) are performed via the ModificationBarrier4 command buffer to ensure safe Entity structural changes at the appropriate sync point.