Bevy All-in-One Documentation

A powerful 3D/2.5D game controller plugin for Bevy Engine.

Project maintained by yaskhan Hosted on GitHub Pages — Theme by mattgraham

Bevy Tutorial System Documentation

Table of Contents

Overview

System Purpose and Philosophy

The Bevy Tutorial System provides a comprehensive framework for creating, managing, and presenting interactive tutorial sequences within Bevy-based games. Designed with player experience as the primary focus, this system enables developers to craft educational content that seamlessly integrates with gameplay without disrupting immersion or flow. The architecture emphasizes flexibility, allowing tutorials to range from simple one-panel hints to complex multi-stage learning experiences with sophisticated game state management.

At its core, the system operates on a panel-based sequencing model where each tutorial consists of one or more informational panels presented in sequence. This approach provides natural breakpoints for player comprehension while maintaining a consistent interaction pattern (next/previous navigation). The system deliberately separates tutorial content definition from presentation logic, enabling content designers to focus on educational material while programmers handle integration concerns.

The philosophy driving this implementation centers on three key principles: non-intrusiveness (tutorials should enhance rather than interrupt gameplay), persistence (player progress through tutorials should be remembered across sessions), and configurability (developers should have fine-grained control over how tutorials affect game state). These principles manifest in features like optional single-play enforcement, cursor unlocking, input pausing, and time scale manipulation—all configurable per tutorial rather than globally enforced.

Key Features

The tutorial system delivers a robust set of capabilities designed to handle diverse educational scenarios within games:

Panel-Based Sequencing: Tutorials are constructed from sequential panels, each containing a title, descriptive text, and optional visual asset. This structure supports progressive disclosure of information, allowing complex mechanics to be broken into digestible segments. Panel navigation follows intuitive patterns (next/previous buttons) with automatic closure upon sequence completion.

Persistent Progress Tracking: Through the TutorialLog component attached to player entities, the system maintains a record of completed tutorials across game sessions. This enables sophisticated behaviors like preventing redundant tutorials for experienced players while ensuring newcomers receive necessary guidance. The persistence mechanism uses efficient HashSet storage for O(1) lookup performance.

Configurable Game State Management: Each tutorial definition includes boolean flags controlling four critical aspects of game interaction during presentation:

These flags operate independently, allowing precise control over player experience. For example, a combat tutorial might pause input and slow time without unlocking the cursor, while a menu navigation tutorial would unlock the cursor without affecting time scale.

Event-Driven Architecture: Tutorial lifecycle management occurs through a dedicated event system (TutorialEvent) with explicit lifecycle events (Open, NextPanel, PreviousPanel, Close). This decouples tutorial triggering from presentation logic, enabling tutorials to be initiated from diverse game contexts (collision detection, UI interactions, quest progression) without tight coupling.

Automatic UI Management: The system handles complete UI lifecycle management—creation, content population, state updates, and cleanup—without developer intervention beyond initial tutorial definition. UI elements automatically appear when tutorials activate and cleanly despawn upon completion, preventing entity leakage or visual artifacts.

Serialization Support: All core data structures implement Serde’s Serialize and Deserialize traits alongside Bevy’s Reflect derive macro, enabling seamless persistence to disk and editor integration. This facilitates save game compatibility and potential future tooling support.

Customizable Visual Presentation: While providing a functional default UI implementation, the system exposes component markers (TutorialRoot, TutorialTitleText, etc.) that enable complete visual customization through additional systems without modifying core logic.

Design Principles

The tutorial system architecture adheres to several foundational design principles that ensure maintainability, extensibility, and developer ergonomics:

Separation of Concerns: Content definition (Tutorial/TutorialPanel structs) remains completely separate from runtime state management (TutorialManager resource) and presentation logic (UI systems). This separation enables content designers to work with data structures without understanding runtime mechanics, while systems programmers can optimize presentation without affecting content pipelines.

Explicit State Transitions: All tutorial state changes occur through explicit events rather than implicit conditions. This design choice enhances debuggability and predictability—developers can trace tutorial progression through event logs rather than deciphering complex conditional logic scattered across systems.

Resource-Based Global State: The TutorialManager resource maintains global tutorial state (active tutorial ID, current panel index) rather than distributing this information across components. This centralization simplifies state reasoning and prevents synchronization issues that could arise from distributed state management.

Component-Based Player Tracking: While global state resides in a resource, player-specific progress tracking uses components (TutorialLog) attached to player entities. This hybrid approach correctly models the domain: tutorial progress is player-specific (hence component-based), while active presentation state is globally singular (hence resource-based).

Defensive Programming Practices: Systems implement robust error handling including tutorial ID validation before activation, bounds checking during panel navigation, and cleanup operations that handle edge cases (e.g., despawning UI when none exists). These practices prevent common runtime errors in tutorial sequences.

Performance-Conscious Implementation: The system minimizes runtime overhead through techniques like event queue batching (processing all pending events in a single pass), UI existence checking before updates (avoiding unnecessary queries), and efficient data structures (HashSet for played tutorials).

Extensibility by Design: Extension points are deliberately exposed through component markers and configurable flags rather than hard-coded behaviors. Developers can attach additional systems to TutorialRoot entities for custom animations, extend TutorialPanel with additional fields through composition, or implement alternative navigation schemes alongside the default button system.

Integration Capabilities

The tutorial system integrates seamlessly with common game architecture patterns and complementary systems:

Input System Coordination: Through configurable input pausing, the tutorial system cooperates with custom input state management systems. The manage_tutorial_game_state system interacts with an optional InputState resource, demonstrating a non-invasive integration pattern that respects game-specific input architectures.

Time Management Integration: Time scale manipulation occurs through Bevy’s standard Time resource, ensuring compatibility with physics systems, animation timelines, and other time-dependent game mechanics. The system carefully preserves and restores the previous time scale upon tutorial completion to prevent state leakage.

UI System Compatibility: The tutorial UI implementation uses standard Bevy UI primitives (Node, Text, Button components) without custom render pipelines, ensuring compatibility with existing UI theming systems, resolution scaling solutions, and accessibility features.

Persistence Ecosystem: Serialization support enables integration with save game systems. TutorialLog components can be included in player entity serialization without special handling, while TutorialManager state (being transient presentation state) appropriately excludes itself from persistence.

Event System Interoperability: TutorialEvent operates within Bevy’s standard event ecosystem, allowing other systems to react to tutorial lifecycle events. For example, an analytics system could listen for TutorialEvent::Close to record completion metrics, or a sound system could trigger audio cues on panel transitions.

Modular Plugin Architecture: Implemented as a standard Bevy Plugin (TutorialPlugin), the system registers its resources, components, and systems through the conventional plugin interface. This enables straightforward integration into existing application builders with predictable initialization ordering.

Core Concepts

Tutorial Architecture

The tutorial system employs a layered architecture with three distinct layers that communicate through well-defined interfaces:

Content Layer: This layer consists of pure data structures (Tutorial and TutorialPanel) that define tutorial content independent of runtime concerns. Tutorials are stored in a HashMap within the TutorialManager resource, indexed by unique numeric identifiers. This layer focuses exclusively on “what” content exists without addressing “when” or “how” it appears.

State Management Layer: The TutorialManager resource serves as the central coordinator, maintaining active tutorial state (currently displayed tutorial ID and panel index) alongside the complete tutorial catalog. This layer handles state transitions triggered by events, enforces business rules (like single-play restrictions), and coordinates with game systems (time, input) based on tutorial configuration.

Presentation Layer: Multiple systems collaborate to transform state into visual representation. The update_tutorial_ui system manages UI entity lifecycle and content population, handle_tutorial_buttons processes player interactions with navigation controls, and manage_tutorial_game_state adjusts global game parameters (time scale, input state) according to tutorial requirements.

These layers communicate through unidirectional data flow: Content Layer → State Management Layer (via TutorialEvent) → Presentation Layer (via TutorialManager resource queries). This architecture prevents circular dependencies and simplifies debugging—state changes always originate from events, propagate through the manager, and manifest in UI updates.

Data Flow

Tutorial system data flow follows a precise sequence during each operational phase:

Initialization Phase:

  1. TutorialPlugin registers required resources (TutorialManager, TutorialEventQueue) and components during app construction
  2. Game code populates TutorialManager.tutorials HashMap with defined tutorial content
  3. Player entities receive TutorialLog components tracking completion history
  4. Systems register with Bevy’s scheduler for execution during Update stage

Activation Phase:

  1. Game logic emits TutorialEvent::Open(id) through TutorialEventQueue resource
  2. handle_tutorial_events system processes the event during its scheduled execution
  3. System validates tutorial existence and checks TutorialLog for play restrictions
  4. Upon validation, TutorialManager.active_tutorial_id and current_panel_index are set
  5. TutorialLog is updated to record tutorial initiation (for single-play enforcement)
  6. manage_tutorial_game_state system detects state change and applies configured game modifications (input pause, time scale)
  7. update_tutorial_ui system detects active tutorial and either creates new UI or updates existing UI content

Navigation Phase:

  1. Player interacts with UI buttons, triggering Interaction::Pressed events on Button entities
  2. handle_tutorial_buttons system detects interactions and emits corresponding TutorialEvents (NextPanel/PreviousPanel)
  3. handle_tutorial_events processes navigation events, updating current_panel_index with bounds checking
  4. update_tutorial_ui detects panel index change and refreshes UI content to match new panel data
  5. For NextPanel events reaching sequence end, active_tutorial_id is cleared, triggering cleanup phase

Deactivation Phase:

  1. Tutorial completion (final panel navigation) or explicit closure (Close button) clears active_tutorial_id
  2. manage_tutorial_game_state detects cleared state and restores original game parameters (input enabled, time scale reset)
  3. update_tutorial_ui detects cleared state and despawns entire UI hierarchy rooted at TutorialRoot entities
  4. System returns to idle state awaiting next TutorialEvent::Open

This data flow ensures deterministic behavior with clear cause-and-effect relationships between player actions and system responses. Each phase completes fully within a single frame update cycle, preventing partial state transitions that could cause visual glitches or input handling errors.

State Management

State management in the tutorial system distinguishes between persistent state (surviving across game sessions) and transient state (relevant only during active presentation):

Persistent State:

Transient Presentation State:

Game State Modifications:

This state separation ensures that tutorial progress survives game restarts while presentation state remains ephemeral. The design prevents common bugs where transient UI state accidentally persists across level loads or game sessions.

Event-Driven Control

The tutorial system implements a hybrid event processing model combining Bevy’s native event system with a custom queue resource to overcome event reader limitations in certain Bevy versions:

Event Types:

Event Processing Flow:

  1. Systems or game logic push TutorialEvent variants into TutorialEventQueue.0 vector
  2. handle_tutorial_events system drains the entire queue at the start of its execution
  3. Events are processed in FIFO order within a single frame
  4. Queue is emptied completely each frame to prevent event accumulation
  5. No events persist beyond the frame they were emitted

Advantages of Queue Approach:

Event Safety Guarantees:

This event model provides reliable, predictable control over tutorial progression while remaining compatible with Bevy’s broader event ecosystem for analytics, logging, or system coordination purposes.

UI Lifecycle

The tutorial UI follows a strict lifecycle managed entirely by the update_tutorial_ui system without developer intervention:

Creation Phase:

Update Phase:

Navigation Handling:

Cleanup Phase:

This lifecycle management ensures tutorials never leave visual artifacts or orphaned entities, critical for games with frequent tutorial triggers. The system’s self-contained nature means developers never manually create, update, or destroy tutorial UI entities—only triggering events and defining content.

Component Reference

TutorialPanel

TutorialPanel represents a single informational unit within a tutorial sequence, designed to convey one coherent concept or instruction set. Each panel functions as an atomic learning moment with consistent presentation structure.

Structural Composition:

Design Considerations:

Content Guidelines:

Extension Points:

Tutorial

Tutorial aggregates multiple TutorialPanel instances into cohesive learning sequences with configurable runtime behaviors. Each tutorial represents a complete instructional unit covering related game mechanics or concepts.

Structural Composition:

Behavioral Semantics:

Content Strategy:

Performance Characteristics:

TutorialLog

TutorialLog tracks player-specific tutorial completion history as a component attached to player entities. This component enables personalized tutorial experiences based on player progression and prior knowledge.

Structural Composition:

Lifecycle Management:

Usage Patterns:

Design Rationale:

Integration Considerations:

Performance Characteristics:

TutorialRoot

TutorialRoot serves as marker component identifying the root entity of the tutorial UI hierarchy. This component enables reliable identification and manipulation of the entire tutorial interface through Bevy’s entity query system.

Architectural Role:

Query Patterns:

Lifecycle Characteristics:

Design Intent:

Extension Opportunities:

TutorialTitleText

TutorialTitleText marks the Text component entity displaying current panel’s title content. This marker enables targeted content updates and visual customization without affecting other UI text elements.

Architectural Role:

Update Mechanics:

Visual Design Intent:

Customization Points:

Accessibility Considerations:

TutorialDescriptionText

TutorialDescriptionText identifies the Text component entity presenting panel’s instructional content. This marker enables dynamic content updates while maintaining consistent visual treatment across panel transitions.

Architectural Role:

Content Characteristics:

Update Mechanics:

Styling Guidelines:

Content Best Practices:

Localization Support:

TutorialPanelImage

TutorialPanelImage marks the UI node entity designated for visual asset display within tutorial panels. This component enables dynamic image loading and presentation without rebuilding UI structure during panel navigation.

Architectural Role:

Visual Presentation:

Asset Loading Behavior:

Content Guidelines:

Performance Considerations:

Extension Opportunities:

TutorialButton

TutorialButton associates navigation actions with UI button entities through encapsulated TutorialEvent variants. This component bridges player interactions with tutorial state transitions without hard-coded button behaviors.

Structural Composition:

Interaction Flow:

  1. Player clicks button entity with TutorialButton component
  2. Bevy’s UI system updates Interaction component to Pressed state
  3. handle_tutorial_buttons system detects Changed on marked entities
  4. System pushes TutorialButton’s stored event into TutorialEventQueue
  5. handle_tutorial_events processes event during next system execution
  6. Tutorial state updates according to event semantics

Visual Feedback System:

Button Configuration:

Customization Points:

Accessibility Considerations:

Resource Reference

TutorialManager

TutorialManager serves as the central coordination resource maintaining global tutorial state and content catalog. This resource embodies the system’s state management layer, bridging content definitions with runtime presentation logic.

Structural Composition:

Lifecycle Management:

State Transition Semantics:

Concurrency Considerations:

Extension Patterns:

Performance Characteristics:

Debugging Support:

TutorialEventQueue

TutorialEventQueue implements a custom event buffering mechanism addressing limitations in Bevy’s native event system for certain version ranges. This resource provides reliable, frame-accurate event delivery critical for tutorial state consistency.

Structural Composition:

Processing Mechanics:

  1. Systems emit events by pushing TutorialEvent variants into queue.0 vector
  2. handle_tutorial_events system executes early in Update stage
  3. System drains entire vector into local collection before processing
  4. Events processed sequentially in drained order within single execution
  5. Queue remains empty after processing until next frame’s emissions

Advantages Over Native Events:

Usage Patterns:

Memory Management:

Thread Safety:

Migration Path:

Debugging Considerations:

Event Reference

TutorialEvent::Open

TutorialEvent::Open(u32) initiates tutorial presentation sequence for specified tutorial ID. This event represents the primary entry point for tutorial system interaction, triggering complete activation pipeline including validation, state setup, UI creation, and game state modifications.

Activation Pipeline:

  1. Event received by handle_tutorial_events system during processing phase
  2. System validates tutorial existence by querying TutorialManager.tutorials HashMap
  3. When tutorial found, system checks TutorialLog components on player entities for play restrictions
  4. play_only_once enforcement: if tutorial marked single-play AND ID exists in played_tutorials, activation aborted with warning log
  5. Upon successful validation:
    • TutorialManager.active_tutorial_id set to Some(id)
    • TutorialManager.current_panel_index reset to 0
    • TutorialLog.played_tutorials updated with tutorial ID (immediate tracking prevents duplicate triggers within session)
    • Info log emitted recording tutorial name for diagnostics
  6. Subsequent systems detect state change and apply presentation/game modifications

Validation Semantics:

Usage Patterns:

Edge Cases:

Performance Characteristics:

Best Practices:

TutorialEvent::NextPanel

TutorialEvent::NextPanel advances tutorial presentation to subsequent panel within active sequence. This event drives forward progression through tutorial content, implementing boundary-aware navigation with automatic sequence completion.

Navigation Semantics:

  1. Event processed only when TutorialManager.active_tutorial_id is Some(id)
  2. System retrieves Tutorial instance via ID lookup in tutorials catalog
  3. Boundary check: if current_panel_index + 1 < panels.len(), increment index
  4. Boundary exceeded: current_panel_index at final panel (index == len() - 1)
    • TutorialManager.active_tutorial_id set to None
    • Tutorial automatically closed without requiring explicit Close event
    • UI cleanup and game state restoration triggered in subsequent systems
  5. No effect when no active tutorial—event silently ignored

Progression Characteristics:

Usage Patterns:

Edge Cases:

Performance Characteristics:

Design Rationale:

Best Practices:

TutorialEvent::PreviousPanel

TutorialEvent::PreviousPanel enables backward navigation within active tutorial sequence, allowing players to review previously displayed content. This event implements boundary-constrained reverse progression maintaining intuitive navigation semantics.

Navigation Semantics:

  1. Event processed only when TutorialManager.active_tutorial_id is Some(id)
  2. Boundary check: if current_panel_index > 0, decrement index by one
  3. Boundary enforced: at first panel (index == 0), event has no effect—index remains zero
  4. No automatic closure or special behaviors on reverse navigation
  5. Silently ignored when no active tutorial exists

Progression Characteristics:

Usage Patterns:

Edge Cases:

Performance Characteristics:

Design Rationale:

Best Practices:

TutorialEvent::Close

TutorialEvent::Close terminates active tutorial presentation immediately regardless of current panel position. This event provides explicit cancellation pathway complementing automatic closure at sequence end, returning game to normal state without completing tutorial sequence.

Termination Pipeline:

  1. Event received by handle_tutorial_events system during processing phase
  2. TutorialManager.active_tutorial_id set to None unconditionally
  3. current_panel_index value discarded—no preservation for potential resumption
  4. Info log emitted recording tutorial closure for diagnostics
  5. Subsequent systems detect state change:
    • manage_tutorial_game_state restores input state and time scale
    • update_tutorial_ui despawns entire UI hierarchy
    • Game returns to normal interaction state within same frame

State Restoration:

Usage Patterns:

Edge Cases:

Progress Tracking Semantics:

Performance Characteristics:

Design Rationale:

Best Practices:

System Reference

handle_tutorial_events

handle_tutorial_events system serves as the central state transition engine for the tutorial system, processing queued events and updating TutorialManager state with strict validation and boundary enforcement. This system executes early in the Update schedule to ensure state changes propagate to dependent systems within the same frame.

Execution Timing:

Event Processing Algorithm:

  1. Drain TutorialEventQueue.0 vector into local Vec collection
  2. Iterate drained events in FIFO order preserving emission sequence
  3. For each event, match variant and execute corresponding state transition logic:
    • Open(id): Validate existence → check play restrictions → update state → record completion
    • NextPanel: Bounds check → increment index or close tutorial
    • PreviousPanel: Bounds check → decrement index if not at start
    • Close: Clear active tutorial state unconditionally
  4. Each event processed atomically—partial failures do not affect subsequent events
  5. All state modifications occur through exclusive mutable access to TutorialManager resource

Validation Logic:

State Transition Guarantees:

Error Handling:

Performance Characteristics:

Concurrency Safety:

Debugging Support:

Extension Points:

update_tutorial_ui

update_tutorial_ui system manages complete lifecycle of tutorial user interface including creation, content population, state updates, and cleanup. This system transforms TutorialManager state into visual representation through Bevy UI entity manipulation without developer intervention.

Execution Timing:

State Detection Logic:

  1. Query TutorialManager resource for active_tutorial_id state
  2. Branch execution based on state:
    • Some(id): Active tutorial requires UI presentation
    • None: Inactive state requires UI cleanup if entities exist
  3. Active state further validated by checking tutorials catalog for ID existence
  4. Panel index bounds verified before content access to prevent panic conditions

UI Creation Pathway:

  1. Query TutorialRoot entities to determine UI existence
  2. If no TutorialRoot entities found AND active tutorial exists:
    • Invoke setup_tutorial_ui helper function
    • Construct complete UI hierarchy with parent-child relationships
    • Apply marker components to relevant entities for future queries
    • Populate initial content from current panel data
    • Entire hierarchy created within single commands scope for atomic appearance
  3. Creation occurs only once per tutorial activation—subsequent frames update existing UI

UI Update Pathway:

  1. When UI exists AND active tutorial state valid:
    • Query TutorialTitleText entities → update Text content with panel title
    • Query TutorialDescriptionText entities → update Text content with panel description
    • Query TutorialPanelImage entities → reload image asset if panel specifies image_path
    • Content updates occur through direct component mutation without hierarchy reconstruction
  2. Image updates conditional on path presence to avoid unnecessary asset server queries
  3. Text updates occur unconditionally—minimal cost compared to hierarchy rebuild

UI Cleanup Pathway:

  1. When active_tutorial_id is None AND TutorialRoot entities exist:
    • Iterate all TutorialRoot entities
    • Despawn each with recursive children removal
    • Complete cleanup prevents entity leakage across tutorial sessions
  2. Cleanup occurs immediately upon state transition—no delayed removal
  3. Despawn operations batched within single commands scope for efficiency

Performance Optimizations:

Error Resilience:

Visual Consistency Guarantees:

Extension Opportunities:

handle_tutorial_buttons

handle_tutorial_buttons system processes player interactions with tutorial navigation controls, translating UI interaction states into TutorialEvent emissions for state management. This system provides responsive visual feedback while maintaining clean separation between presentation and state logic.

Interaction Detection:

  1. Query entities with three constraints:
    • Interaction component (Bevy UI standard interaction state)
    • TutorialButton component (custom marker with associated event)
    • Changed filter (process only entities with state changes this frame)
  2. Changed filter critical for performance—avoids processing static buttons every frame
  3. Query returns tuples of (Interaction, TutorialButton, BackgroundColor) for simultaneous state reading and visual feedback

State Transition Handling: For each matching entity, system evaluates current Interaction state:

Visual Feedback Characteristics:

Performance Characteristics:

Button State Management:

Concurrency Safety:

Extension Points:

Design Rationale:

manage_tutorial_game_state

manage_tutorial_game_state system coordinates global game parameters during tutorial presentation, applying configured modifications to time scale and input state while ensuring proper restoration upon completion. This system acts as integration layer between tutorial system and core game mechanics.

State Detection:

  1. Query TutorialManager resource for active_tutorial_id state
  2. Branch execution based on presence of active tutorial:
    • Some(id): Apply tutorial-specific game state modifications
    • None: Restore default game state parameters
  3. Tutorial catalog lookup validates configuration flags before applying modifications
  4. System designed to be non-invasive—only modifies state when explicitly configured

Input State Management:

Time Scale Management:

Cursor State Considerations:

State Restoration Guarantees:

Performance Characteristics:

Error Resilience:

Integration Patterns:

Design Philosophy:

Advanced Features

Single-Play Tutorials

The play_only_once feature provides sophisticated control over tutorial repetition, enabling personalized learning experiences that respect player expertise while ensuring newcomers receive necessary guidance. This feature operates through coordinated interaction between Tutorial definitions, TutorialLog components, and event processing logic.

Implementation Mechanics:

Player Experience Design:

Content Strategy Implications:

Edge Case Handling:

Performance Characteristics:

Analytics Integration:

Customization Opportunities:

Cursor Management

Cursor management during tutorials addresses the fundamental tension between gameplay interaction models and UI navigation requirements. While the tutorial system provides the unlock_cursor configuration flag, actual cursor state control requires integration with game-specific cursor management systems due to Bevy’s lack of standardized cursor API.

Architectural Approach:

Integration Pattern:

  1. Create cursor management system with appropriate access to window/input resources
  2. System queries TutorialManager resource each frame
  3. When active_tutorial_id becomes Some(id):
    • Retrieve tutorial configuration
    • If unlock_cursor true, release cursor confinement
  4. When active_tutorial_id becomes None:
    • Restore previous cursor confinement state
  5. System should cache previous state for accurate restoration

Cursor State Transitions:

Gameplay Considerations:

Technical Implementation Options:

Edge Cases:

Best Practices:

Input Pausing

Input pausing provides critical isolation between tutorial presentation and gameplay mechanics, preventing unintended player actions that could disrupt instructional moments or create negative experiences. This feature operates through configurable integration with game-specific input state management systems.

Implementation Architecture:

Input State Semantics:

Integration Requirements:

Player Experience Considerations:

Configuration Strategy:

Edge Case Handling:

Performance Characteristics:

Testing Recommendations:

Time Scale Control

Time scale manipulation enables sophisticated tutorial presentations including slow-motion demonstrations and complete pauses, providing players optimal conditions for observing complex mechanics. This feature leverages Bevy’s standard time management system for seamless integration with physics, animation, and gameplay systems.

Implementation Mechanics:

Time Scale Semantics:

Pedagogical Applications:

Configuration Guidelines:

Integration Considerations:

Edge Case Handling:

Performance Characteristics:

Player Experience Best Practices:

Visual Customization

Visual customization enables tutorial presentation to match game aesthetic and branding requirements while maintaining functional integrity. The system provides multiple extension points for styling modifications without requiring core system changes.

Customization Layers:

Extension Mechanisms:

Styling Best Practices:

Theming System Integration:

Animation Integration:

Localization Adaptations:

Accessibility Enhancements:

Panel Sequencing

Panel sequencing forms the pedagogical backbone of tutorial design, structuring information delivery to maximize comprehension and retention. The system’s linear sequencing model provides predictable navigation while supporting sophisticated content strategies through panel composition and ordering.

Sequencing Patterns:

Panel Composition Guidelines:

Navigation Semantics:

Content Density Management:

Pedagogical Effectiveness:

Analytics Integration:

Advanced Sequencing Techniques:

Persistent Progress Tracking

Persistent progress tracking ensures tutorial experiences adapt to individual player journeys across game sessions, preventing redundant presentations while maintaining accessibility for reference purposes. This feature leverages Bevy’s component serialization capabilities for seamless save game integration.

Tracking Architecture:

Persistence Mechanics:

Player Journey Considerations:

Edge Case Handling:

Privacy and Analytics:

Advanced Tracking Extensions:

Performance Characteristics:

Design Philosophy:

Integration Guide

Plugin Registration

Plugin registration establishes the tutorial system within your Bevy application’s architecture, initializing required resources and registering systems with the scheduler. Proper registration ensures seamless integration with existing game systems and correct initialization ordering.

Basic Registration:

App::new()
    .add_plugins(DefaultPlugins)
    .add_plugins(TutorialPlugin)
    // ... other plugins and systems
    .run();

Initialization Order Considerations:

Custom Initialization Patterns:

Plugin Configuration Options:

System Execution Ordering:

Testing Integration:

Migration from Prior Versions:

Tutorial Definition

Tutorial definition transforms educational content into structured data the system can present, requiring careful attention to pedagogical design alongside technical specification. Well-constructed tutorials balance informational density with player comprehension capacity.

Content Structure:

Panel Authoring Guidelines:

Configuration Strategy:

Content Creation Workflow:

  1. Identify learning objective for tutorial sequence
  2. Decompose objective into 3-7 atomic concepts for individual panels
  3. Author panel content following progressive disclosure principles
  4. Select appropriate configuration flags based on interaction requirements
  5. Assign unique ID within semantic namespace
  6. Register tutorial with TutorialManager during initialization
  7. Test tutorial flow with target audience for comprehension validation

Localization Preparation:

Asset Management:

Validation Practices:

Version Control Considerations:

Player Entity Setup

Player entity setup establishes the per-player state tracking required for personalized tutorial experiences, ensuring completion history persists across game sessions and adapts to individual player journeys.

Component Attachment:

Entity Query Patterns:

Persistence Integration:

Multiplayer Considerations:

New Game+ Implementation:

Edge Case Handling:

Performance Characteristics:

Testing Recommendations:

Triggering Tutorials

Tutorial triggering bridges game events with educational content delivery, requiring thoughtful integration to provide timely guidance without disrupting gameplay flow. Effective triggering balances player need with contextual appropriateness.

Trigger Sources:

Trigger Implementation Patterns:

  1. Spatial trigger example: 
    // System detecting player in tutorial zone
fn movement_tutorial_trigger(
    player_query: Query<&Transform, With<Player>>,
    tutorial_zones: Query<(&Transform, &TutorialZone)>,
    mut event_queue: ResMut<TutorialEventQueue>,
    tutorial_logs: Query<&TutorialLog>,
) {
    for (player_transform, (zone_transform, zone)) in 
        player_query.iter().zip(tutorial_zones.iter()) {
        if player_transform.translation.distance(zone_transform.translation) < zone.radius {
            if !has_completed(&tutorial_logs, zone.tutorial_id) {
                event_queue.0.push(TutorialEvent::Open(zone.tutorial_id));
            }
        }
    }
}
  2. Interaction trigger example: 
    // System detecting first weapon pickup
fn weapon_tutorial_trigger(
    mut pickup_events: EventReader<WeaponPickupEvent>,
    mut event_queue: ResMut<TutorialEventQueue>,
    tutorial_logs: Query<&TutorialLog>,
) {
    for event in pickup_events.read() {
        if event.is_first_weapon && !has_completed(&tutorial_logs, 2000) {
            event_queue.0.push(TutorialEvent::Open(2000));
        }
    }
}

Contextual Appropriateness:

Trigger Validation:

Progressive Triggering:

Analytics Integration:

Edge Case Handling:

Best Practices:

Custom UI Integration

Custom UI integration enables tutorial presentation to match game aesthetic and functional requirements beyond default implementation, leveraging marker components and system composition for non-invasive customization.

Customization Approaches:

  1. Styling override: Modify visual properties of existing UI through additional systems
  2. Component extension: Attach additional components to tutorial UI entities for enhanced behaviors
  3. Complete replacement: Despawn default UI and construct custom alternative hierarchy
  4. Hybrid approach: Retain default structure with selective replacements for specific elements

Styling Override Pattern:

// System applying custom theme to tutorial UI
fn apply_tutorial_theme(
    root_query: Query<Entity, With<TutorialRoot>>,
    mut background_query: Query<&mut BackgroundColor, With<TutorialRoot>>,
    theme: Res<GameTheme>,
) {
    for (entity, mut bg) in root_query.iter().zip(background_query.iter_mut()) {
        bg.0 = theme.tutorial_background_color;
        // Additional styling queries for title, description, buttons...
    }
}

Complete Replacement Pattern:

  1. Register system after update_tutorial_ui with #[system(order = 2)]
  2. Query TutorialRoot entities created by default system
  3. Despawn entire hierarchy recursively
  4. Construct custom UI hierarchy with equivalent functionality
  5. Maintain TutorialButton components on navigation controls for event integration

Extension Component Pattern:

// Custom component for tutorial-specific animations
#[derive(Component)]
struct TutorialEntranceAnimation {
    elapsed: f32,
    duration: f32,
}

// System adding animation component to new tutorial UI
fn add_tutorial_animations(
    mut commands: Commands,
    new_roots: Query<Entity, (With<TutorialRoot>, Added<TutorialRoot>)>,
) {
    for entity in new_roots.iter() {
        commands.entity(entity).insert(TutorialEntranceAnimation {
            elapsed: 0.0,
            duration: 0.3,
        });
    }
}

Layout Customization:

Theming System Integration:

Animation Integration:

Localization Adaptations:

Accessibility Enhancements:

Performance Considerations:

Game State Coordination

Game state coordination ensures tutorial presentation harmonizes with broader game systems, preventing conflicts and maintaining coherent player experience during educational moments. This coordination spans input handling, time management, physics simulation, and audio presentation.

Input System Integration:

Time Management Coordination:

Physics Simulation Considerations:

Audio System Coordination:

Camera System Integration:

AI System Coordination:

State Restoration Guarantees:

Coordination System Pattern:

// Example coordination system for camera handling
fn tutorial_camera_coordinator(
    manager: Res<TutorialManager>,
    mut cameras: Query<&mut Transform, With<Camera3d>>,
    mut state: Local<Option<OriginalCameraState>>,
) {
    if let Some(id) = manager.active_tutorial_id {
        if let Some(tutorial) = manager.tutorials.get(&id) {
            if tutorial.requires_camera_adjustment && state.is_none() {
                // Cache original state
                if let Ok(mut transform) = cameras.get_single_mut() {
                    *state = Some(OriginalCameraState { 
                        position: transform.translation, 
                        rotation: transform.rotation 
                    });
                    // Apply tutorial camera position
                    transform.translation = tutorial.camera_position;
                }
            }
        }
    } else if let Some(original) = state.take() {
        // Restore original state
        if let Ok(mut transform) = cameras.get_single_mut() {
            transform.translation = original.position;
            transform.rotation = original.rotation;
        }
    }
}

Testing Recommendations:

Serialization Setup

Serialization setup enables tutorial progress tracking to persist across game sessions, leveraging Bevy’s Reflect and Serde integration for seamless save game compatibility. Proper configuration ensures player completion history survives application restarts without manual intervention.

Reflect Registration:

Serde Integration:

Save Game Integration:

Serialization Format Considerations:

Version Migration Strategy:

// Example migration system for tutorial ID changes
fn migrate_tutorial_logs(
    mut logs: Query<&mut TutorialLog>,
    version: Res<SaveVersion>,
) {
    if version.0 < 12 {
        // Tutorial ID 1000 renamed to 1100 in version 12
        for mut log in logs.iter_mut() {
            if log.played_tutorials.remove(&1000) {
                log.played_tutorials.insert(1100);
            }
        }
    }
}

Security Considerations:

Performance Characteristics:

Testing Recommendations:

Debugging Support:

Usage Patterns

First-Time Player Onboarding

First-time player onboarding represents the most critical application of tutorial systems, establishing foundational mechanics understanding that shapes entire player experience. Effective onboarding balances comprehensive instruction with engagement preservation, avoiding overwhelming newcomers while ensuring essential competence.

Onboarding Sequence Design:

Tutorial Structure for Onboarding:

Trigger Strategy:

Player State Considerations:

Analytics Integration:

Edge Case Handling:

Best Practices:

Contextual Help Systems

Contextual help systems provide just-in-time guidance triggered by player behavior or environmental context, offering targeted assistance without disrupting gameplay flow. These systems complement mandatory onboarding with adaptive support responsive to individual player needs.

Trigger Mechanisms:

Help Content Strategy:

Player Agency Preservation:

Implementation Pattern:

// Behavioral trigger detecting repeated jump failures
fn jump_hint_trigger(
    mut failure_streak: Local<u32>,
    mut last_failure_time: Local<f32>,
    jump_events: EventReader<JumpFailedEvent>,
    time: Res<Time>,
    mut event_queue: ResMut<TutorialEventQueue>,
    tutorial_logs: Query<&TutorialLog>,
) {
    for _ in jump_events.read() {
        if time.elapsed_seconds() - *last_failure_time < 2.0 {
            *failure_streak += 1;
        } else {
            *failure_streak = 1;
        }
        *last_failure_time = time.elapsed_seconds();
        
        if *failure_streak >= 3 && !has_completed(&tutorial_logs, 1005) {
            event_queue.0.push(TutorialEvent::Open(1005)); // Jump timing hint
            *failure_streak = 0; // Reset after trigger
        }
    }
}

Adaptive Difficulty Integration:

Analytics for Optimization:

Multiplayer Considerations:

Accessibility Integration:

Feature Introduction Sequences

Feature introduction sequences gradually unveil game systems as players progress, preventing cognitive overload while maintaining discovery excitement. These sequences strategically time mechanic reveals to match player readiness and narrative context.

Progressive Unveiling Strategy:

Tutorial Sequencing Example:

  1. Session 1 (First 15 minutes):
    • Movement and camera control (Tutorial 1000)
    • Basic interaction and object manipulation (Tutorial 1001)
    • Core combat loop: attack, block, dodge (Tutorial 2000)
  2. Session 2 (First level completion):
    • Special ability acquisition and basic usage (Tutorial 2100)
    • Environmental interaction: levers, doors, platforms (Tutorial 1100)
    • Inventory management fundamentals (Tutorial 3000)
  3. Session 3 (Mid-game progression):
    • Advanced combat: combos, counters, special moves (Tutorial 2200)
    • Crafting system introduction (Tutorial 4000)
    • Character progression systems (Tutorial 5000)
  4. Late game (Mastery phase):
    • Expert techniques and optimization strategies (Tutorial 2300)
    • System interactions and emergent gameplay (Tutorial 6000)
    • Speedrun techniques and advanced challenges (Tutorial 7000)

Contextual Integration Patterns:

Player Readiness Assessment:

Analytics-Driven Refinement:

Edge Case Handling:

Best Practices:

Progressive Complexity Tutorials

Progressive complexity tutorials structure learning experiences to gradually increase cognitive demand, respecting cognitive load theory while building comprehensive mechanic understanding. These tutorials decompose complex systems into sequenced learning moments that scaffold player competence.

Cognitive Load Management:

Tutorial Structure Example - Advanced Combat: Panel 1 (Foundation):

Panel 2 (Variation):

Panel 3 (Application):

Panel 4 (Integration):

Scaffolding Techniques:

Adaptive Sequencing:

Assessment Integration:

Analytics for Optimization:

Edge Case Handling:

Best Practices:

Checkpoint-Based Guidance

Checkpoint-based guidance delivers targeted tutorials at natural progression points, aligning educational moments with gameplay structure to minimize disruption while maximizing relevance. This approach leverages level design and progression systems as tutorial delivery framework.

Checkpoint Identification:

Guidance Delivery Patterns:

Implementation Example - Boss Preparation:

// System triggering boss preparation tutorial
fn boss_prep_tutorial(
    player_query: Query<&LevelProgress>,
    mut event_queue: ResMut<TutorialEventQueue>,
    tutorial_logs: Query<&TutorialLog>,
) {
    for progress in player_query.iter() {
        if progress.next_boss == BossType::Minotaur 
           && progress.boss_attempts == 0
           && !has_completed(&tutorial_logs, 2500) {
            // Trigger minotaur-specific preparation tutorial
            event_queue.0.push(TutorialEvent::Open(2500));
        }
    }
}

Tutorial Content Strategy:

Player Agency Preservation:

Analytics Integration:

Multiplayer Considerations:

Progressive Disclosure:

Edge Case Handling:

Best Practices:

Optional Tutorial Access

Optional tutorial access empowers players to seek guidance on demand, respecting player agency while providing safety net for confusion or forgotten mechanics. This approach transforms tutorials from interruptions into player-controlled resources enhancing autonomy and reducing frustration.

Access Mechanisms:

Content Organization Strategy:

Implementation Pattern - Pause Menu:

// System handling tutorial selection from pause menu
fn pause_menu_tutorial_selection(
    interaction_query: Query<(&Interaction, &TutorialSelection), Changed<Interaction>>,
    mut event_queue: ResMut<TutorialEventQueue>,
) {
    for (interaction, selection) in interaction_query.iter() {
        if *interaction == Interaction::Pressed {
            // Optional tutorials never enforce play_only_once restrictions
            event_queue.0.push(TutorialEvent::Open(selection.tutorial_id));
        }
    }
}

Player Experience Design:

Content Strategy for Optional Tutorials:

Analytics Integration:

Progressive Disclosure:

Edge Case Handling:

Best Practices:

Multi-Stage Learning Paths

Multi-stage learning paths structure extended skill development across multiple gameplay sessions, recognizing that complex mechanic mastery requires distributed practice rather than single-session instruction. These paths transform tutorials from isolated moments into cohesive learning journeys.

Learning Path Architecture:

Progress Tracking System:

Implementation Example - Combat Learning Path: Stage 1 (Foundation - Tutorial 2000):

Stage 2 (Application - Tutorial 2100):

Stage 3 (Integration - Tutorial 2200):

Stage 4 (Mastery - Tutorial 2300):

Stage 5 (Expert - Tutorial 2400):

Adaptive Progression:

Analytics Integration:

Motivation Systems:

Edge Case Handling:

Best Practices:

Best Practices

Content Design

Content design forms the pedagogical foundation of effective tutorials, transforming mechanical explanations into engaging learning experiences that respect player intelligence while ensuring comprehension. Superior content design balances informational density with cognitive load management.

Cognitive Load Theory Application:

Text Content Guidelines:

Visual Content Strategy:

Sequencing Principles:

Progressive Disclosure Implementation:

Content Validation Process:

Localization Preparation:

Accessibility Integration:

Content Freshness Maintenance:

Player Experience

Player experience design ensures tutorials enhance rather than disrupt gameplay flow, respecting player agency while providing necessary guidance. Exceptional tutorial experiences feel like natural extensions of gameplay rather than artificial interruptions.

Flow State Preservation:

Player Agency Respect:

Pacing Optimization:

Emotional Design Considerations:

Contextual Appropriateness:

Feedback Loop Design:

Frustration Prevention:

Retention Optimization:

Analytics-Driven Refinement:

Best Practices Checklist:

Performance Optimization

Performance optimization ensures tutorial systems operate efficiently without impacting frame rate or memory usage, critical for maintaining smooth gameplay during educational moments. Well-optimized tutorials deliver seamless experiences indistinguishable from core gameplay performance.

UI Entity Management:

Asset Loading Strategy:

System Execution Efficiency:

Memory Footprint Management:

Time Scale Considerations:

Platform-Specific Optimizations:

Profiling Methodology:

Optimization Priorities:

  1. Eliminate frame rate drops during tutorial activation/deactivation transitions
  2. Minimize memory footprint of inactive tutorial systems (should be near zero)
  3. Reduce asset loading stalls through preloading and asynchronous strategies
  4. Optimize UI entity count and component complexity for efficient queries
  5. Implement platform-specific adaptations respecting hardware constraints

Common Performance Pitfalls:

Testing Recommendations:

State Management

State management ensures tutorial systems maintain consistent, predictable behavior across complex gameplay scenarios including interruptions, edge cases, and system interactions. Robust state management prevents visual artifacts, input handling errors, and progression corruption.

State Separation Principles:

State Transition Safety:

Restoration Guarantees:

Interruption Handling:

Multi-System Coordination:

Serialization Safety:

Edge Case Coverage:

Debugging Support:

Testing Strategy:

Common State Management Bugs:

Best Practices Checklist:

UI/UX Guidelines

UI/UX guidelines ensure tutorial interfaces provide intuitive, accessible interactions that enhance learning without introducing friction or cognitive overhead. Exceptional tutorial UI feels like natural extension of game interface rather than disconnected overlay.

Visual Hierarchy Principles:

Color Theory Application:

Typography Guidelines:

Interaction Design:

Layout Responsiveness: