Shortcuts

Convenience static accessors and utility methods for common Ceramic functionality.

Shortcuts provides quick access to frequently used Ceramic singletons and utilities, eliminating the need for repetitive code. By importing this class with import ceramic.Shortcuts.*;, you gain direct access to app, screen, audio, input, and other core systems. This import is done by default via import.hx in Ceramic projects.

Key features:

• Static accessors: Direct access to app, screen, audio, input, settings, log, systems
• Observation utilities: Methods for managing autorun scopes (unobserve, reobserve, cease)
• Conditional execution: until() macro for reactive condition checking
• Debug assertions: assert() macro for development-time validation

Usage examples:

import ceramic.Shortcuts.*;

// Direct access to singletons
app.onUpdate(this, update);
screen.onResize(this, handleResize);
audio.playSound(mySound);

// Wait for condition on observable player health field
until(player.health <= 0, () -> {
    showGameOver();
});

// Debug assertion
assert(player != null, "Player must exist");

Static Members #

Shared app instance

Shared screen instance

Shared audio instance

Shared input instance

Shared settings instance

Shared logger instance

Systems manager

Temporarily stops observing property changes in the current autorun scope.

Use this when you need to read observable properties without creating dependencies in the current autorun. Must be paired with reobserve() to restore observation.

Example:

autorun(() -> {
    // This creates a dependency
    var x = observable.value;

    unobserve();
    // This read doesn't create a dependency
    var y = observable.otherValue;
    reobserve();
});

Resumes observing property changes after a call to unobserve().

Restores the autorun's ability to track dependencies on observable properties. Always pair this with a preceding unobserve() call.

Stops and destroys the current autorun from within its own callback.

Use this to create one-shot autoruns or to stop an autorun based on internal conditions. The distinctive name 'cease' avoids conflicts with common method names.

Example:

autorun(() -> {
    if (condition.met) {
        doSomething();
        cease(); // This autorun won't run again
    }
});

Creates an autorun that waits for a condition to become true, then executes a callback once.

This macro provides a reactive way to wait for conditions without polling. The condition is checked whenever any observed properties within it change. Once true, the callback executes and the autorun is automatically destroyed.

Syntax variations:

// Auto-attach to 'this' if available (common in Entity subclasses)
until(player.isReady, () -> startGame());

// Explicitly attach to null (no owner)
until(null, player.isReady, () -> startGame());

// Attach to specific entity (cleaned up when entity is destroyed)
until(myEntity, player.isReady, () -> startGame());

The autorun is automatically cleaned up:

• When the condition becomes true (after callback execution)
• When the owner entity is destroyed (if attached)

Debug-time assertion that validates expressions evaluate to true.

Assertions help catch logic errors during development. They are:

• Active in debug builds (or when -D ceramic_assert is set)
• Completely removed from release builds (zero runtime cost)
• Logged as errors with optional custom messages

Examples:

assert(player != null);
assert(health > 0, "Player health must be positive");
assert(items.length < maxItems, 'Too many items: ${items.length}');

Failed assertions:

• Log an error with the expression and optional reason
• Throw an exception to halt execution
• Can print stack traces with -D ceramic_assert_print_stack

Private Members #