t1k:unity:dots-core:tutorial
| Field | Value |
|---|---|
| Module | dots-core |
| Version | 3.56.1 |
| Effort | low |
| Tools | — |
How to invoke
Section titled “How to invoke”/t1k:unity:dots-core:tutorialDOTS Tutorial — Step-Machine & UI Hooks
Section titled “DOTS Tutorial — Step-Machine & UI Hooks”Package:
com.the1studio.dots-tutorial— namespaceDOTSTutorialAssembly:DOTSTutorial.Runtime— depends onDOTSCore,Unity.Entities,Unity.BurstSee also:references/api-and-patterns.mdfor full component/system table and usage snippet
When This Skill Triggers
Section titled “When This Skill Triggers”- 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.CurrentStepIdto show/hide UI hints - Signalling step completion from gameplay systems
- Checking
TutorialFlow.IsFinishedto 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:
TutorialSystemcallsRequireForUpdate(pendingQuery)inOnCreate, so it only iterates when aTutorialStepCompletedEventis actually buffered — eliminating the former per-frame empty-buffer drain. - Iteration form:
OnUpdateuses idiomaticSystemAPI.Query<RefRW<TutorialFlow>, DynamicBuffer<TutorialStep>, DynamicBuffer<TutorialStepCompletedEvent>>()foreach, NOTEntities.ForEach(...).WithoutBurst().Run()—Entities.ForEachsource-gen fails when the lambda captures the managedthis.machinefield. TutorialStepMachineholds ALL transition logic as plain managed C# (Tick(ref flow, steps, events)): apply completion events → mark matching incomplete step done → sweep by ascendingOrderIndexfor the next step → writeCompletedStepCount/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)”| Type | Kind | Role |
|---|---|---|
TutorialFlow | IComponentData (singleton) | Tracks CurrentStepId, CompletedStepCount, IsFinished |
TutorialStep | IBufferElementData | Ordered step definition: StepId, OrderIndex, Completed |
TutorialStepCompletedEvent | IBufferElementData | Signal written by gameplay; drained by TutorialSystem (only when buffered — run-gated) |
TutorialSystem | SystemBase (managed) | Tier-3 bridge: run-gated; drives TutorialStepMachine and writes results back to TutorialFlow/TutorialStep |
TutorialStepMachine | plain managed class | Tier-3 transition logic — Tick(ref flow, steps, events); no Burst, no per-frame system overhead |
Minimal Authoring
Section titled “Minimal Authoring”// Baker / scene setup — add to the player entityvar 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);Signalling Completion
Section titled “Signalling Completion”// From any gameplay ISystem — write an event, TutorialSystem drains it next framevar events = SystemAPI.GetBuffer<TutorialStepCompletedEvent>(tutorialEntity);events.Add(new TutorialStepCompletedEvent { StepId = "tap_to_move" });Tier-2 UI Bridge (Recommended Pattern)
Section titled “Tier-2 UI Bridge (Recommended Pattern)”// MonoBehaviour — poll CurrentStepId to drive HUD hintsvoid Update(){ var flow = World.DefaultGameObjectInjectionWorld .EntityManager.GetComponentData<TutorialFlow>(tutorialEntity); hintLabel.text = flow.IsFinished ? "" : GetHint(flow.CurrentStepId.ToString());}Hard rules
Section titled “Hard rules”IsFinishedistrueonly when the step buffer is non-empty AND all steps haveCompleted == true. An entity with an emptyTutorialStepbuffer always hasIsFinished == false(seeTutorialSystemline 91). Bootstrap at least one step or guard withCompletedStepCount > 0 && IsFinished.- Ordering is by
OrderIndex, NOT by buffer insertion order.TutorialSystempicks the lowestOrderIndexamong incomplete steps each frame. DuplicateOrderIndexvalues produce non-deterministic current-step selection — keep them strictly increasing. - Mismatched StepIds are silently ignored.
TutorialStepCompletedEvententries whoseStepIdmatches no buffer element are drained and discarded without error. UseFixedString64Bytes-compatible snake_case ASCII identifiers (max 61 chars); longer strings will truncate silently in UTF-8 conversion. TutorialStepCompletedEventbuffer is cleared byTutorialStepMachine.Tick(called byTutorialSystemonly on frames where the buffer is non-empty — the system is run-gated viaRequireForUpdate). 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) —
TutorialSystemis a managedSystemBasedriving the plain-classTutorialStepMachine. Do NOT invest in complex ECS tutorial UI systems or newISystemtypes for presentation logic. Author UI hooks as Tier-2 managed MonoBehaviour readers ofTutorialFlowonly. TutorialSystem.OnUpdatemust useSystemAPI.Query<...>()foreach, NOTEntities.ForEach(...).Run()— the system captures the managedthis.machinefield, andEntities.ForEachsource-gen rejects managed-instance captures. Keep the idiomaticforeach (var (...) in SystemAPI.Query<...>())form for any managedSystemBasethat touches instance fields.