Skip to content

t1k:unity:dots-core:tutorial

FieldValue
Moduledots-core
Version3.56.1
Effortlow
Tools—
/t1k:unity:dots-core:tutorial

Package: com.the1studio.dots-tutorial — namespace DOTSTutorial Assembly: DOTSTutorial.Runtime — depends on DOTSCore, Unity.Entities, Unity.Burst See also: references/api-and-patterns.md for full component/system table and usage snippet

  • Implementing a tutorial flow or FTUE (first-time user experience) sequence
  • Advancing a tutorial to the next step when a gameplay event fires
  • Reading TutorialFlow.CurrentStepId to show/hide UI hints
  • Signalling step completion from gameplay systems
  • Checking TutorialFlow.IsFinished to unlock post-tutorial content

Architecture — Tier Direction (Tier-3 shipped in H2)

Section titled “Architecture — Tier Direction (Tier-3 shipped in H2)”

TutorialSystem is now a managed SystemBase (NOT a Burst ISystem) that acts as a thin bridge: it drives a Tier-3 plain managed class, TutorialStepMachine, and writes the result back into the ECS TutorialFlow / TutorialStep components. Step orchestration is UI/event-driven with no hot-path requirement, so it does not belong in Burst.

  • Run-gate: TutorialSystem calls RequireForUpdate(pendingQuery) in OnCreate, so it only iterates when a TutorialStepCompletedEvent is actually buffered — eliminating the former per-frame empty-buffer drain.
  • Iteration form: OnUpdate uses idiomatic SystemAPI.Query<RefRW<TutorialFlow>, DynamicBuffer<TutorialStep>, DynamicBuffer<TutorialStepCompletedEvent>>() foreach, NOT Entities.ForEach(...).WithoutBurst().Run() — Entities.ForEach source-gen fails when the lambda captures the managed this.machine field.
  • TutorialStepMachine holds ALL transition logic as plain managed C# (Tick(ref flow, steps, events)): apply completion events → mark matching incomplete step done → sweep by ascending OrderIndex for the next step → write CompletedStepCount / CurrentStepId / IsFinished → clear the event buffer.

Do NOT add new Burst ISystem types for tutorial UI presentation. For HUD hints, use a Tier-2 MonoBehaviour bridge that reads TutorialFlow via SystemAPI and drives Canvas elements (see “Tier-2 UI Bridge” below).

Key Types (full API in references/api-and-patterns.md)

Section titled “Key Types (full API in references/api-and-patterns.md)”
TypeKindRole
TutorialFlowIComponentData (singleton)Tracks CurrentStepId, CompletedStepCount, IsFinished
TutorialStepIBufferElementDataOrdered step definition: StepId, OrderIndex, Completed
TutorialStepCompletedEventIBufferElementDataSignal written by gameplay; drained by TutorialSystem (only when buffered — run-gated)
TutorialSystemSystemBase (managed)Tier-3 bridge: run-gated; drives TutorialStepMachine and writes results back to TutorialFlow/TutorialStep
TutorialStepMachineplain managed classTier-3 transition logic — Tick(ref flow, steps, events); no Burst, no per-frame system overhead
// Baker / scene setup — add to the player entity
var buffer = baker.AddBuffer<TutorialStep>(entity);
buffer.Add(new TutorialStep { StepId = "tap_to_move", OrderIndex = 0 });
buffer.Add(new TutorialStep { StepId = "pick_up_item", OrderIndex = 1 });
buffer.Add(new TutorialStep { StepId = "open_backpack", OrderIndex = 2 });
baker.AddBuffer<TutorialStepCompletedEvent>(entity);
baker.AddComponent<TutorialFlow>(entity);
// From any gameplay ISystem — write an event, TutorialSystem drains it next frame
var events = SystemAPI.GetBuffer<TutorialStepCompletedEvent>(tutorialEntity);
events.Add(new TutorialStepCompletedEvent { StepId = "tap_to_move" });
// MonoBehaviour — poll CurrentStepId to drive HUD hints
void Update()
{
var flow = World.DefaultGameObjectInjectionWorld
.EntityManager.GetComponentData<TutorialFlow>(tutorialEntity);
hintLabel.text = flow.IsFinished ? "" : GetHint(flow.CurrentStepId.ToString());
}
  • IsFinished is true only when the step buffer is non-empty AND all steps have Completed == true. An entity with an empty TutorialStep buffer always has IsFinished == false (see TutorialSystem line 91). Bootstrap at least one step or guard with CompletedStepCount > 0 && IsFinished.
  • Ordering is by OrderIndex, NOT by buffer insertion order. TutorialSystem picks the lowest OrderIndex among incomplete steps each frame. Duplicate OrderIndex values produce non-deterministic current-step selection — keep them strictly increasing.
  • Mismatched StepIds are silently ignored. TutorialStepCompletedEvent entries whose StepId matches no buffer element are drained and discarded without error. Use FixedString64Bytes-compatible snake_case ASCII identifiers (max 61 chars); longer strings will truncate silently in UTF-8 conversion.
  • TutorialStepCompletedEvent buffer is cleared by TutorialStepMachine.Tick (called by TutorialSystem only on frames where the buffer is non-empty — the system is run-gated via RequireForUpdate). Do NOT accumulate events across multiple frames expecting them to persist; write and let the machine drain within the same frame the event is buffered.
  • InternalBufferCapacity(0) on both buffer types — no inline storage; both always heap-allocate. This is intentional (tutorial is low-frequency, 1–20 steps typical). Do not raise the capacity expecting a performance gain.
  • Tier-3 migration SHIPPED (H2) — TutorialSystem is a managed SystemBase driving the plain-class TutorialStepMachine. Do NOT invest in complex ECS tutorial UI systems or new ISystem types for presentation logic. Author UI hooks as Tier-2 managed MonoBehaviour readers of TutorialFlow only.
  • TutorialSystem.OnUpdate must use SystemAPI.Query<...>() foreach, NOT Entities.ForEach(...).Run() — the system captures the managed this.machine field, and Entities.ForEach source-gen rejects managed-instance captures. Keep the idiomatic foreach (var (...) in SystemAPI.Query<...>()) form for any managed SystemBase that touches instance fields.