class

PointClickEngine::Core::SceneManager

Inherits PointClickEngine::Core::ISceneManager < PointClickEngine::Core::GameConstants < Reference < Object

Manages all scene-related operations including loading, transitions, and caching

The SceneManager centralizes scene handling logic that was previously scattered throughout the Engine class. It provides a clean API for scene operations and handles caching, preloading, and transition effects.

Features

  • Scene loading and caching
  • Smooth scene transitions with callbacks
  • Scene preloading for performance
  • Error handling for missing scenes
  • Scene validation and integrity checking
  • Memory management for unused scenes

Usage

manager = SceneManager.new
manager.add_scene(scene)
manager.change_scene("main_menu")

Constructors

new(engine : Engine | Nil, event_bus : Events::EventBus | Nil)
Source
new(engine : Engine | Nil = nil)
Source

Instance methods

add_scene(scene : Scenes::Scene) : Result(Nil, SceneError)

Add a scene to the manager

Validates the scene and adds it to the available scenes collection. Does not make the scene active - use change_scene for that.

  • scene : The scene instance to add

Returns a Result indicating success or failure

Source
add_scenes(scenes : Array(Scenes::Scene)) : Result(Nil, SceneError)

Add multiple scenes at once

Validates and adds multiple scenes to the manager. If any scene fails validation, none are added.

  • scenes : Array of scene instances to add
Source
cache_stats

Get cache statistics

Source
change_scene(name : String, activation_options : ActivationOptions = ActivationOptions.new) : Result(Scenes::Scene, SceneError)

Change to a different scene

Transitions from the current scene to the specified scene. Handles exit callbacks for the current scene, loads the new scene if needed, and executes enter callbacks for the new scene.

The force_reload parameter can be used to reload the scene from cache even if it's already loaded, useful for resetting scene state.

Callback Order

  1. Exit callbacks for current scene
  2. Transition callbacks
  3. Scene activation
  4. Enter callbacks for new scene

Performance

Scenes are cached after first load for faster subsequent transitions. Use force_reload to bypass cache when scene state needs resetting.

  • name : Name of the scene to activate
  • force_reload : Whether to reload from disk even if cached

Returns a Result with the activated scene or an error

Source
change_scene_with_reload(name : String, force_reload : Bool = false) : Result(Scenes::Scene, SceneError)
Source
change_scene_with_transition(name : String, transition_type : String = "fade", duration : Float32 = 1.0_f32, player_position : RL::Vector2 | Nil = nil, activation_options : ActivationOptions = ActivationOptions.new) : Result(Nil, SceneError)

Change scene with a transition effect

Performs a scene change with a visual transition effect. The transition will play, changing the scene at the midpoint of the effect.

  • name : Name of the scene to transition to
  • transition_type : Type of transition effect (fade, dissolve, slide_left, etc.)
  • duration : Duration of the transition in seconds
  • player_position : Optional position to place the player in the new scene

Returns a Result with success or error

Source
clear_cache

Clear all cached scenes

Source
current_scene

Currently active scene

Source
event_bus

Optional EventBus for publishing scene events

Source
event_bus=(event_bus : Events::EventBus | Nil)

Optional EventBus for publishing scene events

Source
get_scene(name : String) : Result(Scenes::Scene, SceneError)

Get a scene by name

Returns the scene if found, or an error if not found.

  • name : Name of the scene to retrieve
Source
get_sequence(name : String) : Actions::ActionRunner | Nil

Get a registered action sequence

  • name : Name of the sequence to retrieve
Source
has_scene?(name : String) : Bool

Check if a scene exists

  • name : Name of the scene to check
Source
has_sequence?(name : String) : Bool

Check if a sequence exists

  • name : Name of the sequence to check
Source
log_activation_diagnostics
Source
log_activation_diagnostics=(log_activation_diagnostics : Bool)
Source
max_cache_size=(size : Int32)

Set maximum cache size

  • size : Maximum number of scenes to keep cached
Source
on_scene_enter(name : String, &block : -> Nil)

Add a callback to be executed when entering a scene

  • name : Name of the scene
  • &block : Callback to execute on enter
Source
on_scene_exit(name : String, &block : -> Nil)

Add a callback to be executed when exiting a scene

  • name : Name of the scene
  • &block : Callback to execute on exit
Source
on_scene_transition(name : String, &block : -> Nil)

Add a callback to be executed during scene transition

  • name : Name of the scene
  • &block : Callback to execute during transition
Source
preload_scene(name : String) : Result(Scenes::Scene, SceneError)

Preload a scene without activating it

Loads a scene into the cache for faster switching later. Useful for preloading scenes during loading screens or idle time.

  • name : Name of the scene to preload

Returns the preloaded scene or an error

Source
register_sequence(name : String, runner : Actions::ActionRunner)

Register an action sequence (for global sequences)

  • name : Name of the sequence
  • runner : The ActionRunner instance
Source
reload_scene(name : String) : Result(Scenes::Scene, SceneError)

Reload a scene from its definition

Forces a scene to reload, clearing any cached state. Useful for implementing "restart level" functionality.

  • name : Name of the scene to reload
Source
remove_scene(name : String) : Result(Nil, SceneError)

Remove a scene from the manager

Removes a scene from the available scenes. Cannot remove the currently active scene.

  • name : Name of the scene to remove
Source
scene_enter_callbacks

Scene enter callbacks (called when scene becomes active)

Source
scene_exit_callbacks

Scene exit callbacks (called when scene becomes inactive)

Source
scene_names

Get list of all scene names

Source
scenes

Collection of all loaded scenes

Source
sequences

Action sequence registry (for global sequences loaded from game config)

Source
start_scene

Starting scene name

Source
start_scene=(start_scene : String | Nil)

Starting scene name

Source
transition_callbacks

Scene transition callbacks

Source

Nested types