Preloader

View source
Entity → Visual → Quad → Layer → Scene → ceramic.Preloader (Class)

A scene that displays loading progress for preloadable resources.

The Preloader scene provides a visual loading screen with:

  • An animated Ceramic logo
  • A progress bar showing loading progress
  • Automatic transition to the loaded scene on completion

This is typically used as the initial scene when loading game assets or other resources that implement the Preloadable interface.

Example usage:

// Create a preloader for your main scene
var preloader = new Preloader(() -> {
    return new MainScene();
});

// The preloader will:
// 1. Display the Ceramic logo with animation
// 2. Initialize the preloadable (MainScene)
// 3. Show a progress bar
// 4. Automatically transition to MainScene when loaded

app.scenes.main = preloader;
See: Preloadable, PreloadStatus

Instance Members

preloadable: Preloadable

The preloadable object being loaded. This is set automatically when the preloader initializes.

progress: Int

Current loading progress value (0 to total).

total: Int

Total expected progress value. Progress percentage can be calculated as: progress / total * 100

preloadStatus: PreloadStatus

Current loading status.

See: PreloadStatus

The Ceramic logo visual displayed during loading. This is created automatically but can be accessed for customization.

progressForeground: Quad

The foreground (filled) portion of the progress bar. Its width is updated to reflect loading progress.

progressBackground: Quad

The background (empty) portion of the progress bar.

update(delta: Float): Void

Update method called every frame. Requests progress updates from the preloadable object.

Name Type Description
delta Float Time elapsed since last frame in seconds
updatePreload(progress: Int, total: Int, status: PreloadStatus): Void

Update the preloader with current loading progress. This method is called by the preloadable object to report its progress.

Name Type Description
progress Int Current progress value (0 to total)
total Int Total expected progress value
status PreloadStatus Current loading status
new(getPreloadable: Function): Void

Create a new preloader.

Name Type Description
getPreloadable Function A function that returns the preloadable object to load. This function is called after the logo animation completes. The returned object must implement the Preloadable interface.

Private Members

didCallUpdatePreload: Bool
preloaderIndex: Int
didSucceed: Bool
emitSuccess(): Void

Event emitted when the preloadable has successfully finished loading. The preloader will automatically transition to the loaded scene after this event.

getPreloadable(): Preloadable
Returns
Preloadable
create(): Void

Called when the scene is created. Initializes the loading screen graphics.

createGraphics(): Void

Create the loading screen graphics. Override this method to customize the loading screen appearance.

Create and animate the Ceramic logo. The logo is centered horizontally and positioned at 42% of screen height. After the animation completes, the preloadable is initialized and the progress bar is created.

animateScale(visual: Visual, targetScale: Float, ?complete: Function): Void

Animate a visual's scale and alpha with an elastic ease effect.

Name Type Default Description
visual Visual The visual to animate
targetScale Float The final scale value
complete Function (optional) Optional callback when animation completes
createProgressBar(?yRatio: Float = -1, ?widthRatio: Float = -1, ?backgroundColor: Color = 0x444444, ?foregroundColor: Color = 0xFFFFFF): Void

Create a progress bar that will be updated from current progress

Name Type Default Description
yRatio Float -1 The vertical position of the progress bar, relative to screen height (from 0 (top) to 1 (bottom))
widthRatio Float -1 The progress bar width, relative to screen width (1 meaning full width, 0.5 half width)
backgroundColor Color 0x444444 The progress bar background color
foregroundColor Color 0xFFFFFF The progress bar foreground color
updateProgressBar(): Void

Update the progress bar visual to reflect current loading progress. The foreground width is scaled proportionally to the progress/total ratio.

initPreloadable(): Void

Initialize the preloadable object. If the preloadable is a Scene, it's registered with the scene manager.

willEmitSuccess(): Void

Called before the success event is emitted. If the preloadable is a Scene, this triggers a scene transition to replace the preloader with the loaded scene.

Metadata

Name Parameters
:build ceramic.macros.EntityMacro.buildForCompletion()
:autoBuild ceramic.macros.EntityMacro.buildForCompletion()
:build tracker.macros.EventsMacro.build()
:autoBuild tracker.macros.EventsMacro.build()
:build tracker.macros.ObservableMacro.build()
:autoBuild tracker.macros.ObservableMacro.build()