RuntimeAssets

View source
ceramic.RuntimeAssets (Class)

Runtime utilities to compute asset lists/names from raw (relative) file list.

RuntimeAssets provides runtime access to asset information that is normally generated at compile-time by AssetsMacro. This allows dynamic asset discovery and loading, particularly useful for:

  • Hot-reloading during development
  • Dynamic content loading
  • User-generated content
  • Asset browsing tools

The class processes a flat list of asset paths and organizes them by:

  • Base name (filename without extension and density suffix)
  • Asset kind (image, sound, text, etc.)
  • Directory structure

It also handles density variants (e.g., @2x, @3x) and provides constant-style names for programmatic access.

// Create from a directory path
var runtimeAssets = RuntimeAssets.fromPath('assets/');

// Get all image asset names
var imageNames = runtimeAssets.getNames('image');
for (entry in imageNames) {
    trace('Image: ${entry.name} at ${entry.paths}');
}

// Get organized asset lists
var lists = runtimeAssets.getLists();
trace('All assets: ${lists.all}');
trace('Assets for "player": ${lists.allByName.get("player")}');
See: Assets, AssetsMacro

Static Members

fromPath(path: String): RuntimeAssets

Creates a RuntimeAssets instance by scanning a directory path. Only available on platforms with file system access.

Name Type Description
path String The directory path to scan for assets
Returns Description
RuntimeAssets RuntimeAssets instance, or null if file system access is not available

Instance Members

path: String

The root path of the assets directory, if created from a path. Will be null if created with a pre-computed asset list.

requestTransformedDir(callback: Function): Void

Requests the transformed assets directory path asynchronously. This is the temporary directory where processed assets are stored.

The method caches the result after the first query to avoid repeated platform calls. Multiple simultaneous requests are queued and resolved together.

Name Type Description
callback Function Function called with the transformed directory path (may be null if unavailable)
reset(allAssets: Array<String>, ?path: String): Void

Resets the runtime assets with a new list of files. Clears all caches and recomputes the asset organization.

Name Type Default Description
allAssets Array<String> New array of asset paths
path String (optional) Optional new root path
getNames(kind: String, ?extensions: Array<String>, ?dir: Bool = false): Array<AnonStruct>

Gets all asset names of a specific kind with their paths and constant names.

This method finds all assets matching the specified kind and optional extensions, returning structured information about each unique asset (by base name).

Name Type Default Description
kind String Asset type: 'image', 'text', 'sound', 'shader', 'font', 'atlas', 'database', 'fragments'
extensions Array<String> (optional) Optional additional file extensions to include (beyond the defaults for the kind)
dir Bool false Whether to search for directories instead of files
Returns Description
Array Array of asset entries with: - name: Base name without extension or density suffix - paths: All file paths for this asset (including variants) - constName: Constant-style name for code generation (e.g., "PLAYER_SPRITE")
getLists(): AnonStruct

Gets organized lists of all assets in various formats.

Returns a comprehensive view of all assets organized by:

  • Complete file lists
  • Directory lists
  • Files grouped by base name
  • Directories grouped by base name

The results are cached for performance.

Returns Description
AnonStruct Object containing: - all: Array of all asset file paths - allDirs: Array of all directory paths containing assets - allByName: Map of base names to their file variants - allDirsByName: Map of base directory names to their variants
getEncodableLists(): AnonStruct

Same as getLists(), but transforms Maps into JSON-encodable objects.

This is useful when you need to serialize the asset lists to JSON or send them over a network, as Maps cannot be directly JSON-encoded.

Returns Description
AnonStruct Same structure as getLists() but with Maps converted to Dynamic objects
new(allAssets: Array<String>, ?path: String): Void

Creates a new RuntimeAssets instance with a pre-computed list of asset paths.

Name Type Default Description
allAssets Array<String> Array of relative asset paths (e.g., ["images/player.png", "sounds/jump.ogg"])
path String (optional) Optional root path where these assets are located

Private Members

transformedDir: String
didQueryTransformedDir: Int
pendingTransformedDirCallbacks: Array<Function>
allAssets: Array<String>

All asset file paths in the collection

allAssetDirs: Array<String>

All unique directory paths containing assets

assetsByBaseName: Map

Map of base names to their file variants (including density variants)

assetDirsByBaseName: Map

Map of base directory names to their path variants

cachedNames: Map

Cache of computed asset names by kind and options

toAssetConstName(input: String): String

Converts an asset path to a constant-style name suitable for code generation.

Transformation rules:

  • Slashes (/) become double underscores (__)
  • Dots (.) become single underscores (_)
  • camelCase becomes CAMEL_CASE
  • Special characters are replaced with underscores
  • Result is all uppercase
Name Type Description
input String Asset path (e.g., "sprites/player.png")
Returns Description
String Constant name (e.g., "SPRITES__PLAYER")
isAsciiChar(c: String): Bool

Checks if a character is a valid ASCII alphanumeric character. Used for generating valid constant names.

Name Type Description
c String Single character string
Returns Description
Bool True if the character is 0-9, A-Z, or a-z
initData(): Void

Initializes internal data structures from the asset list.

This method:

  • Extracts all unique directories from file paths
  • Groups files by their base names (without extensions/variants)
  • Groups directories by their base names
  • Prepares the data for efficient querying