SceneSystem

Core system responsible for managing scene lifecycle, transitions, and display hierarchy.

SceneSystem provides centralized management of scenes in a Ceramic application, handling their loading, transitions, and display. It supports multiple simultaneous scenes through named slots, with special handling for the main scene.

Key features:

• Main scene management: Primary scene with automatic screen binding
• Named scene slots: Support for multiple concurrent scenes (overlays, HUD, etc.)
• Automatic lifecycle: Handles preload → load → create → fade transitions
• Asset preservation: Option to keep assets when switching scenes
• Filter support: Post-processing effects for all root scenes
• Transition control: Configurable fade in/out behaviors

The system automatically updates active scenes and manages their transitions, ensuring smooth scene changes and proper resource management.

Example usage:

// Set main scene
app.scenes.main = new GameScene();

// Add overlay scene
app.scenes.set('hud', new HudScene());

// Configure transitions
app.scenes.keepAssetsForNextMain = true;
app.scenes.fadeOutWhenNextMainCanFadeIn = true;

Static Members #

Singleton instance of the scene system. Automatically created on first access.

Instance Members #

Read-only array containing all active scenes in the system. Includes both root scenes and child scenes.

Controls asset preservation when switching main scenes.

When true, assets from the previous main scene are transferred to the new main scene instead of being destroyed. This allows seamless transitions without reloading shared assets like textures, sounds, or fonts.

Useful for:

• Level transitions that share common assets
• Menu → gameplay transitions
• Reducing loading times between related scenes

Default: false

Controls automatic screen size binding for the main scene.

When true, the main scene's size will automatically match the screen dimensions and update when the screen is resized. This ensures the main scene always fills the entire display area.

Set to false if you need custom scene sizing or positioning.

Default: true

Controls the timing of scene transitions.

When true, the previous scene's fade-out animation is delayed until the new scene is fully loaded and ready to fade in. This creates smoother transitions by ensuring the new content is ready before removing the old.

When false, the previous scene fades out immediately, potentially showing a loading state or blank screen.

Default: true

The primary scene of the application.

Setting this property automatically handles scene transitions, including:

• Fading out the previous main scene
• Loading and initializing the new scene
• Managing asset preservation (if enabled)
• Binding to screen size (if enabled)

The main scene typically represents the core content of your application (game level, menu screen, etc.).

Controls automatic cleanup of replaced filters.

When true, filters are automatically destroyed when:

• Replaced by a new filter
• Set to null
• The scene system is destroyed

Set to false if you want to manage filter lifecycle manually or reuse filters across different contexts.

Default: true

Controls automatic scaling of scene filters.

When true, filters are automatically scaled to match screen dimensions, ensuring post-processing effects cover the entire display area. The filter and its content are scaled inversely to maintain proper rendering.

Set to false for custom filter sizing or when using filters that shouldn't match screen size.

Default: true

Post-processing filter applied to all root scenes.

When set, all root scenes are rendered through this filter, enabling global visual effects like:

• Color grading
• Blur or pixelation
• Shader-based effects

The filter automatically includes all root scenes and handles their proper rendering order.

Map of all root scenes indexed by their slot names.

Root scenes are directly managed by the scene system and rendered to screen. The 'main' slot contains the primary scene, while other slots can hold overlays, HUD elements, or secondary scenes.

Assigns a scene to a named slot in the scene system.

This method handles the complete lifecycle of scene assignment, including:

• Removing and cleaning up previous scenes in the slot
• Initializing and displaying the new scene
• Managing scene transitions and asset preservation
• Setting up proper parent-child relationships

Special handling for 'main' slot updates the main property.

Example:

// Add a HUD overlay
app.scenes.set('hud', new HudScene());

// Add a pause menu with asset sharing
app.scenes.set('pause', new PauseMenu(), true, true);

Retrieves a scene from the specified slot.

Useful for accessing secondary scenes like HUD, overlays, or other named scenes managed by the system.

Example:

var hudScene = app.scenes.get('hud');
if (hudScene != null) {
    hudScene.updateScore(100);
}

Private Members #

Updates filter scaling to match current screen dimensions.

Scales the filter to cover the screen while inversely scaling its content to maintain proper aspect ratio and sizing of contained scenes.

Updates all active scenes and handles auto-booting.

Called automatically each frame after regular updates. This method:

• Auto-boots scenes that have been added to the display hierarchy
• Updates active, non-paused scenes that have autoUpdate enabled
• Maintains filter scaling if autoScaleFilter is enabled

Creates a new SceneSystem instance.

Typically not called directly - use the shared singleton instance via SceneSystem.shared or through app.scenes.

Metadata #