App

App class is the root instance of any ceramic app.

App serves as the main entry point and lifecycle manager for Ceramic applications. It handles initialization, update loops, rendering, and provides global access to core systems and settings.

Key responsibilities:

• Application lifecycle management (ready, update, draw)
• Default asset loading and management
• Screen and audio system initialization
• Settings and persistent data management
• Error handling and crash reporting
• Background/foreground state transitions

The App instance is a singleton accessible via app static property or through the ceramic.Shortcuts.app convenience reference.

Static Members #

Shared App instance singleton.

Instance Members #

true if the app is currently running its update phase.

Computed fps of the app. Read only. Value is automatically computed from last second of frame updates.

Current frame number

Current frame delta time (never above settings.maxDelta)

Current frame real delta time (the actual elapsed time since last frame update)

Backend instance

Screen instance

Audio instance

App settings

Systems are objects to structure app work/phases and update cycle

Logger. Used by log shortcut

Visuals (ordered) Active list of visuals being managed by ceramic. This list is ordered and updated at every frame. In between, it could contain destroyed visuals as they are removed only at the end of the frame for performance reasons.

Pending visuals: visuals that have been created this frame but were not added to the visual list yet

Pending destroyed visuals: visuals that have been destroyed this frame but were not removed to the visual list yet

All groups of entities in this app

Shared instance of Input

All active render textures in this app

App level assets. Used to load default assets (font, texture, shader) required to make ceramic work properly.

Default textured shader. This is the shader used for any visual (quad or mesh) that don't have a custom shader assigned.

Default white texture. When a quad or mesh doesn't have a texture assigned, it will use the default white texture instead to render as plain flat coloured object. This means that the same default shader is used and everything can be batched together (textured & non-textured in the same batch).

Default font used by Text instances.

Project directory. May be null depending on the platform.

App level persistent data. This is a simple key-value store ready to be used. Don't forget to call persistent.save() to apply changes permanently.

Shared text input manager. Usually not used directly as is. You might want to use EditText component instead.

Converters are used to transform field data in Fragment instances. This map is matching a type (as string, like "Array<Float>") with an instance of a ConvertField subclass.

All active timelines in this app.

Shared scene system.

Schedule immediate callback that is garanteed to be executed before the next time frame (before elements are drawn onto screen)

Schedule callback that is garanteed to be executed when no immediate callback are pending anymore.

Execute and flush every awaiting immediate callback, including the ones that could have been added with onceImmediate() after executing the existing callbacks.

Schedule a callback to be executed after a specific number of update frames.

Remove a previously scheduled extended update callback

Quit the application. Works on desktop (windows, mac, linux), unity. Can also work on web by closing the window if electron plugin is enabled and the app is running via electron instead of a regular browser.

Get a group with the given id.

Shared arcade system. (arcade plugin)

Shared nape system. (nape plugin)

Private Members #

Array of callbacks to be executed immediately before the next frame. These callbacks are guaranteed to run before visual updates and rendering.

Current capacity of immediate callbacks array to optimize array operations

Current number of pending immediate callbacks

Array of callbacks to be executed after all immediate callbacks are done

Current capacity of post flush immediate callbacks array

Current number of pending post flush immediate callbacks

List of functions that will be called and purged when update iteration begins. Useful to run some specific code once exactly before update event is sent.

Fired when the app is ready and the game logic can be started.

Fired as many times as there are frames per seconds. It is in sync with screen FPS but used for everything that needs to get updated depending on time (ceramic.Timer relies on it). Use this event to update your contents before they get drawn again.

Fired right before update event and can be used when you want to run garantee your code will be run before regular update event.

Fired right after update event and can be used when you want to run garantee your code will be run after regular update event.

Fired right before default assets are being loaded.

Fired when the app hits an critical (uncaught) error. Can be used to perform custom crash reporting. If this even is handled, app exit should be performed by the event handler.

Fired when the app will enter background state.

CAUTION: Can execute outside main thread!

Fired when the app did finish entering background state.

CAUTION: Can execute outside main thread!

Fired when the app will enter foreground state.

CAUTION: Can execute outside main thread!

Fired when the app did finish entering foreground state.

CAUTION: Can execute outside main thread!

Fired right before sorting all visuals. Visual are sorted at each frame depending on their properties: depth, texture, blending, shader...

Fired right after all visuals have been sort.

Fired right before drawing phase of visuals.

Fired right after drawing phase of visuals.

Fired if the app is running low on memory. (not be implemented by all platforms/targets).

CAUTION: Can execute outside main thread!

Fired when the app terminates.

CAUTION: Can execute outside main thread!

Internal method to handle execution of extended update callbacks

When backend is ready, initialize core systems and load default assets. Steps:

1. Initialize persistent data and text input
2. Bind settings
3. Run pre-init callbacks
4. Initialize field converters and collections
5. Load default shaders, fonts and textures

Bind app settings to their corresponding backend implementations. Currently handles FPS target synchronization.

Initialize all field converters used to transform field data in Fragment instances. Registers default converters for common types like:

• Textures, Fonts, Colors
• Maps and Arrays
• Components

Initialize collections from app info configuration. Loads collection data from assets and instantiates collection entries.

Called when all default assets are loaded. Proceeds with running any pending loaders.

Run pending loaders sequentially until none remain, then trigger app ready state.

Initialize app ready state:

• Run platform specific initialization
• Setup debug entity tracking if enabled
• Configure screen
• Setup update/render pipeline
• Configure input handling

Update method called before the app is fully ready. Handles basic asset and immediate callback processing.

Main update method called every frame once the app is ready. Handles:

• Frame timing and FPS management
• System updates
• Input processing
• Visual hierarchy updates
• Entity lifecycle

Main render method called every frame. Handles the complete rendering pipeline:

• Begins draw phase
• Renders all visible visuals
• Ends draw phase
• Handles display buffer swapping

Synchronize pending visuals into the main visuals list.

Remove destroyed visuals from the main visuals list. Uses an efficient gap-closing algorithm to maintain array density.

Metadata #