Game.Tutorials.TutorialSystem

Assembly: Assembly-CSharp
Namespace: Game.Tutorials

Type: class

Base: GameSystemBase, ITutorialSystem, IPreDeserialize

Summary:
Manager system for in-game tutorials and tutorial lists. Controls activation, progression, completion, locking/unlocking and telemetry for tutorial entities (tutorials, tutorial phases, tutorial lists). Integrates with PrefabSystem, AudioManager, UI, input control schemes and game settings to determine which tutorials to show and when, and to manually unlock features when tutorials complete.

Fields

private struct TypeHandle
Internal struct holding ComponentLookup/BufferLookup handles used by compiled jobs/queries. Used to access TutorialCompleted and TutorialAlternative lookups in a burst/checked context.
private PrefabSystem m_PrefabSystem
Reference to the game's PrefabSystem for resolving prefab metadata (names, tutorial phase prefabs, control scheme requirements, etc).
private AudioManager m_AudioManager
Reference to the AudioManager used to play UI/tutor sounds on tutorial start/completion.
private CityConfigurationSystem m_CityConfigurationSystem
Used to check city configuration options (e.g., whether unlocking map tiles is enabled).
private MapTilePurchaseSystem m_MapTilePurchaseSystem
Used to unlock map tiles when tutorials that gate that feature are completed.
private GameScreenUISystem m_GameScreenUISystem
Used to check whether menus are open (to avoid playing tutorial sounds while the menu is active).
private static readonly float kBalloonCompletionDelay = 0f
Default completion delay used for "balloon" tutorial phases (instant completion).
private static readonly float kCompletionDelay = 1.5f
Default completion delay used for regular tutorial phases after their triggers are satisfied.
private static readonly float kActivationDelay = 3f
Delay before the system will auto-activate the next tutorial (accumulated over frames).
private static readonly string kWelcomeIntroKey = "WelcomeIntro"
Settings key used to mark whether the welcome intro has been shown/passed.
protected static readonly string kListIntroKey = "ListIntro"
Settings key for marking tutorial list intro shown/passed.
private static readonly string kListOutroKey = "ListOutro"
Settings key for marking tutorial list outro shown/passed.
private EntityQuery m_TutorialConfigurationQuery
Query to fetch TutorialsConfigurationData singleton.
protected EntityQuery m_TutorialQuery
Query selecting tutorial entities (TutorialData excluding EditorTutorial).
private EntityQuery m_TutorialListQuery
Query selecting tutorial list entities (TutorialListData).
private EntityQuery m_TutorialPhaseQuery
Query selecting tutorial phase entities (TutorialPhaseData excluding EditorTutorial).
private EntityQuery m_ActiveTutorialListQuery
Query selecting active tutorial list entity.
protected EntityQuery m_ActiveTutorialQuery
Query selecting active tutorial entity.
private EntityQuery m_ActiveTutorialPhaseQuery
Query selecting active tutorial phase entity.
protected EntityQuery m_PendingTutorialListQuery
Query for tutorial lists that are pending activation (TutorialActivated + TutorialRef).
protected EntityQuery m_PendingTutorialQuery
Query for pending tutorial entities (activated but not active/completed).
protected EntityQuery m_PendingPriorityTutorialQuery
Query for pending priority tutorials (ReplaceActiveData) used to preempt active tutorials.
protected EntityQuery m_LockedTutorialQuery
Query for tutorials currently locked (Locked component).
private EntityQuery m_LockedTutorialPhaseQuery
Query for locked tutorial phases.
private EntityQuery m_LockedTutorialTriggerQuery
Query for locked tutorial triggers.
private EntityQuery m_LockedTutorialListQuery
Query for locked tutorial lists.
private EntityQuery m_SoundQuery
Query for ToolUXSoundSettingsData used to play tutorial start/complete sounds.
private EntityQuery m_ForceAdvisorQuery
Query for tutorials that should force advisor visibility (AdvisorActivationData).
private EntityArchetype m_UnlockEventArchetype
Archetype used to create unlock event entities when tutorials unlock features.
private float m_AccumulatedDelay
Accumulated time used for activation/completion delay checks.
protected TutorialMode m_Mode
Current tutorial mode (Default, Intro, ListIntro, ListOutro, etc). Changing mode updates settings keys as appropriate.
protected Setting m_Setting = SharedSettings.instance.userState
Reference to persistent user-state settings used to record which tutorials have been shown/passed.
private TypeHandle __TypeHandle
Instance of the internal TypeHandle struct used in some checks (compiler-generated binding).

Properties

protected virtual Dictionary<string, bool> ShownTutorials => SharedSettings.instance.userState.shownTutorials
Dictionary stored in user settings mapping prefab names (tutorial/tutorial-phase/tutorial-list) to whether they were shown/passed. Overrideable for testing/mocking.
public TutorialMode mode { get; set; }
Gets or sets the current tutorial mode. Setter also updates shown/passed settings when leaving Intro/ListIntro/ListOutro modes.
public Entity activeTutorial { get; }
Returns the currently active tutorial entity or Entity.Null if none.
public Entity activeTutorialPhase { get; }
Returns the currently active tutorial phase entity or Entity.Null if none.
public virtual bool tutorialEnabled { get; set; }
Global toggle (backed by SharedSettings.instance.gameplay.showTutorials). Setting false will reset mode to Default.
public Entity activeTutorialList { get; }
Returns the currently active tutorial list entity or Entity.Null if none.
public Entity tutorialPending { get; }
Convenience accessor that returns the next pending tutorial (FindNextTutorial()).
public Entity nextListTutorial { get; }
If a tutorial list is active, returns the next tutorial entity in the list that is not completed or active. Respects alternative completion and control-scheme validity.
public bool showListReminder { get; }
True when the active tutorial list is the configured intro list (TutorialsConfigurationData.m_TutorialsIntroList). Used to trigger list reminders.

Constructors

public TutorialSystem()
Default constructor (compiler-preserved). Initialization happens in OnCreate.

Methods

protected override void OnCreate()
Initializes queries, system references, archetypes and disables the system until appropriate. Binds entity queries to select tutorials, phases, lists, sounds and advisor activation entities.
public virtual void OnResetTutorials()
Resets all runtime tutorial state, clears components and sets mode to Intro (if in game/editor mode). Used when starting a new game or resetting tutorials.
private bool IsCompleted(Entity tutorial, BufferLookup<TutorialAlternative> alternativeData, ComponentLookup<TutorialCompleted> completionData)
Checks whether a tutorial (or any of its alternatives) is marked completed.
protected override void OnGamePreload(Purpose purpose, GameMode gameMode)
Called during preload. Resets state and sets Enabled based on whether we're in game mode.
protected override void OnGameLoadingComplete(Purpose purpose, GameMode gameMode)
Final setup after loading completes; reads settings, handles auto-unlock of map tiles if necessary, sets initial intro/list modes, and forces advisor visibility where required.
private void ResetState()
Reset runtime state variables, clears active tutorial/list and accumulated delays.
private void ReadSettings()
Reads saved shown/passed settings and applies them to tutorial/list/phase entities (adds TutorialShown/TutorialPhaseShown or marks completed/cleans up accordingly).
private void SetTutorialShown(Entity entity, bool updateSettings = true)
Marks a tutorial/tutorial-phase/tutorial-list as shown in ECS (adds TutorialShown/TutorialPhaseShown) and optionally stores that in persistent settings. Also recurses to UI groups.
private void ForceAdvisorVisibility()
Finds entities that request forced advisor visibility and applies ForceAdvisor to them.
private void ForceAdvisor(Entity entity)
Ensures the Advisor is visible for a tutorial/tutorial-phase (adds ForceAdvisor component and applies to nested phase/group entities).
[Preserve] protected override void OnUpdate()
Regular update tick: when in Default mode and tutorials enabled, manages activation/replacement of active tutorial and list, checks phase completion and clears locks when tutorials are disabled.
public void ForceTutorial(Entity tutorial, Entity phase, bool advisorActivation)
Immediately force-activates a tutorial (adds ForceActivation, optionally AdvisorActivation) and sets it as active (calls SetTutorial).
private void SetTutorial(Entity tutorial, bool passed = false)
Overload to set active tutorial without specifying phase.
public void SetTutorial(Entity tutorial, Entity phase, bool passed)
Sets active tutorial and phase, cleans up previous active tutorial/phase and marks shown components. Resets accumulated delay.
public void SetTutorial(Entity tutorial, Entity phase)
Shortcut overload that calls SetTutorial(tutorial, phase, passed: false).
private void SetTutorialPhase(Entity tutorialPhase, bool passed)
Switches currently active phase: cleans up previous phase, activates new phase, triggers unlock events, plays tutorial-start sound and activates trigger components if present.
public void CompleteCurrentTutorialPhase()
Completes the active tutorial phase and advances to the next phase if configured via triggers; otherwise completes the tutorial.
public void CompleteCurrentTutorialPhase(Entity nextPhase)
Completes the current phase and either moves to nextPhase (or the next in sequence) or completes the tutorial. Honors ForceTutorialCompletion component.
private void UpdateActiveTutorial()
Ensures the active tutorial progresses when phase triggers are satisfied, activates next tutorial if none active and tutorials are enabled, and handles replacement logic.
private bool ShouldReplaceActiveTutorial()
Logic that determines if the active tutorial should be replaced by a pending tutorial (skips if ForceActivation or ReplaceActiveData flags apply).
private void CleanupTutorial(Entity tutorial, bool passed = false, bool updateSettings = true)
Cleans up a tutorial's active state and its phases; if passed==true, marks tutorial completed, updates settings, triggers telemetry and manual unlocks.
private void UpdateSettings(Entity tutorial, bool passed = false)
Overload that resolves a prefab name and calls UpdateSettings(string, bool) to persist shown/passed state.
private void UpdateSettings(string name, bool passed)
Store shown/passed status in the persistent ShownTutorials dictionary and apply/save the Setting if changed.
private void CleanupTutorialPhase(Entity tutorialPhase, bool passed = false, bool updateSettings = true)
Cleans up phase-specific active components, optionally marks phase completed and unlocks associated triggers or features.
private void ActivateNextTutorial(bool delay = false)
Activates the next available tutorial. If delay==true, waits until accumulated delay exceeds kActivationDelay.
private Entity FindNextTutorial()
High-level decision: picks the best next tutorial between pending priority tutorials, regular pending tutorials and the active list's next entry, using priority integers.
private Entity FindNextTutorial(EntityQuery query)
Returns the entity with the lowest m_Priority in the supplied query or Entity.Null if empty.
private bool CheckCurrentPhaseCompleted(out Entity nextPhase)
Checks whether the active tutorial phase's trigger has been completed and whether the configured completion delay has passed. Returns nextPhase if available.
private static float GetCompletionDelay(TutorialPhaseData phase)
Returns the appropriate completion delay for a phase (phase override, balloon phases => 0, otherwise default).
private Entity GetNextPhase(Entity tutorial, Entity currentPhase, Entity nextPhase)
Resolves the next phase in a tutorial sequence, validating control-scheme compatibility via IsValidControlScheme.
private Entity GetFirstTutorialPhase(Entity tutorial)
Returns the first tutorial phase entry that is valid for the current control scheme.
public static bool IsValidControlScheme(Entity phase, PrefabSystem prefabSystem)
Checks if a tutorial phase prefab supports the currently active control scheme (keyboard/mouse or gamepad) or supports All.
private void ClearTutorialLocks()
Clears tutorial-related locks for tutorials, phases, triggers and lists (triggers manual unlocking where necessary) and handles map tile unlocking if configured.
private void ClearLocks(EntityQuery query)
Iterates query entities and calls ClearLock for each.
private void ClearLock(Entity entity)
Checks an entity's UnlockRequirement buffer and manually unlocks the entity if its unlock requirements indicate it should be released when the entity itself is fulfilled (RequireAll flag).
public void SetAllTutorialsShown()
Marks all tutorials and phases as shown (adds TutorialShown/TutorialPhaseShown for each entity in corresponding queries).
public void CompleteTutorial(Entity tutorial)
Plays tutorial completed sound (if available) and cleans up the tutorial as passed.
public static void ManualUnlock(Entity entity, EntityArchetype unlockEventArchetype, EntityManager entityManager)
Creates unlock events for an entity and any forced UI group unlocks if the entity's unlock requirements indicate it should be unlocked; variant using EntityManager directly.
public static void ManualUnlock(Entity entity, EntityArchetype unlockEventArchetype, EntityManager entityManager, EntityCommandBuffer commandBuffer)
CommandBuffer-based overload for creating unlock events (used in command buffer contexts).
public static void ManualUnlock(Entity entity, EntityArchetype unlockEventArchetype, ref BufferLookup<ForceUIGroupUnlockData> forcedUnlocksFromEntity, ref BufferLookup<UnlockRequirement> unlockRequirementsFromEntity, EntityCommandBuffer.ParallelWriter commandBuffer, int sortKey)
Parallel/Job-friendly overload for issuing unlock events from within a job using buffer lookups and an EntityCommandBuffer.ParallelWriter.
private void UpdateActiveTutorialList()
Manage active tutorial list progression: check intro state, completion of the current list, and replacement/activation of lists.
private void CompleteCurrentTutorialList()
Completes the current tutorial list, optionally unlocking map tiles if this list gates that feature, and clears active list.
private void ActivateNextTutorialList()
Finds and sets the next tutorial list (FindNextTutorialList).
private void CheckListIntro()
When the active list is the configured intro list and intro/list-notifications haven't been shown, sets mode to ListIntro and updates settings.
private bool NonListTutorialPending()
Returns true when a pending tutorial exists that is not part of the currently active list.
private bool CheckCurrentTutorialListCompleted()
Checks if all tutorial entries in the active list are completed (uses internal TypeHandle lookups for alternatives/completion checks).
private bool ShouldReplaceActiveTutorialList()
Determines whether the active tutorial list should be replaced (not activated) by checking if it's already been activated.
private Entity FindNextTutorialList(EntityQuery query)
Returns the tutorial list entity with the lowest priority from the given query or Entity.Null.
private void SetTutorialList(Entity tutorialList, bool passed = false, bool updateSettings = true)
Activate or deactivate a tutorial list, marking shown/completed and updating settings. Handles intro/outro mode transitions for configured tutorial intro list.
private void CleanupTutorialList(Entity tutorialList, bool passed = false, bool updateSettings = true)
Clean up list activation state, mark completed if passed, call ManualUnlock and optionally cleanup member tutorials.
public void SkipActiveList()
Convenience method to complete the active tutorial list immediately.
public void PreDeserialize(Context context)
Part of IPreDeserialize: clears transient tutorial components before deserialization.
private void ClearComponents()
Remove runtime components (Active/Shown/Completed/PhaseActive/etc) from all tutorial/list/phase entities to prepare for fresh state or serialization transitions.
[MethodImpl(MethodImplOptions.AggressiveInlining)] private void __AssignQueries(ref SystemState state)
Compiler/IL-generated helper for assigning queries on OnCreateForCompiler. No runtime logic to modify.
protected override void OnCreateForCompiler()
Compiler-only method used in generated code paths to assign queries and typehandles before runtime use.

Usage Example

// Get the system from the world and force a tutorial to start immediately.
// tutorialEntity and phaseEntity should be valid tutorial/phase entity references.
var tutorialSystem = World.DefaultGameObjectInjectionWorld.GetExistingSystemManaged<Game.Tutorials.TutorialSystem>();
tutorialSystem.ForceTutorial(tutorialEntity, phaseEntity, advisorActivation: true);

// Alternatively, mark all tutorials as shown (useful for debug or "Don't show tutorials again")
tutorialSystem.SetAllTutorialsShown();

{{ Notes: - TutorialSystem integrates closely with ECS entities representing tutorials, phases and lists. Most API surface accepts Entity handles rather than prefab names. - Persistent shown/completed state is stored in SharedSettings.instance.userState.shownTutorials and updated when tutorials/lists/phases are marked shown/passed. - Use ManualUnlock overloads when implementing custom unlock logic in jobs/command buffers. }}