Assets

View source
Entity → ceramic.Assets (Class)

The main asset management class for Ceramic framework.

Handles loading, managing, and hot-reloading of various asset types including:

  • Images/Textures
  • Fonts (bitmap and TTF/OTF)
  • Atlases (texture atlases)
  • Text files
  • Binary data
  • Sounds/Audio
  • Databases (CSV)
  • Fragments (JSON-based UI/game fragments)
  • Shaders

Features:

  • Reference counting for memory management
  • Asset variants and density handling for multi-resolution support
  • Hot reloading when watching directories
  • Parent-child asset relationships
  • Custom asset type registration
  • Parallel/serial loading strategies
var assets = new Assets();
assets.addImage('hero.png');
assets.addFont('main.fnt');
assets.load();

Static Members

All active Assets instances in the application. Read-only array to prevent external modification.

All available asset paths in the project.

allDirs: Array<String>

All available directory paths in the project.

allByName: Map

Map of asset names to their available file paths. Useful for finding all variants of an asset.

allDirsByName: Map

Map of directory names to their paths.

flushAllInstancesImmediate(): Void
decodePath(path: String): AssetPathInfo

Decode an asset path to extract information about density, variant, etc.

Name Type Description
path String The asset path to decode
Returns Description
AssetPathInfo AssetPathInfo object containing parsed path information
addAssetKind(kind: String, add: Function, extensions: Array<String>, dir: Bool, types: Array<String>): Void

Register a custom asset kind that can be loaded by the asset system.

Name Type Description
kind String The unique identifier for this asset type (e.g., 'sprite', 'level')
add Function Function that handles adding this asset type to an Assets instance
extensions Array<String> File extensions associated with this asset type
dir Bool Whether this asset type is directory-based
types Array<String> Additional type information for the asset kind
getAssetsPath(): String

Get the base assets path for the current platform.

Returns Description
String The platform-specific assets path
assetNameFromPath(path: String): String

Get the asset name associated with a given file path.

Name Type Description
path String The file path to look up
Returns Description
String The asset name, or null if no asset uses this path
realAssetPath(path: String, ?runtimeAssets: RuntimeAssets): String
Name Type Default
path String
runtimeAssets RuntimeAssets (optional)
Returns
String
getReloadCount(realAssetPath: String): Int
Name Type
realAssetPath String
Returns
Int

Instance Members

immediate: Immediate
runtimeAssets: RuntimeAssets

If set, will be provided to each added asset in this Assets instance. Used for runtime asset loading from file system.

defaultImageOptions: AssetOptions

Default options applied to all image assets added to this instance. Can be overridden per asset.

loadMethod: AssetsLoadMethod

The loading method to use (SYNC or ASYNC). SYNC blocks until loading completes, ASYNC loads in background.

scheduleMethod: AssetsScheduleMethod

The scheduling method for loading multiple assets. PARALLEL loads all at once, SERIAL loads one at a time.

delayBetweenXAssets: Int

If > 0, adds a delay every X assets when loading in parallel. Useful to avoid overwhelming the system with too many concurrent loads.

reloadOnTextureDensityChange: Bool

Whether to automatically reload assets when texture density changes. Useful for supporting multiple screen resolutions.

parent: Assets

If provided, when requesting an asset, it will also check if the parent Assets instance has it and return it if that's the case.

atlasPacker: TextureAtlasPacker

A shared texture atlas packer that can be used to merge smaller textures together. Also required when loading some kind of assets, like .ase/.aseprite files.

hotReload: Bool

Set to true to enable hot reload. When enabled and used with watchDirectory(), assets will automatically reload when their files change on disk. Note: this won't do anything unless used in pair with watchDirectory(path)

destroy(): Void
flush(): Void

Destroy assets that have their refCount at 0. This is useful for cleaning up unused assets to free memory. Assets with refCount > 0 are still in use and won't be destroyed.

hasAsset(asset: Asset): Bool
Name Type
asset Asset
Returns
Bool
add(id: AssetId<Dynamic>, ?variant: String, ?options: Null<AssetOptions>): Void
Name Type Default
id AssetId<Dynamic>
variant String (optional)
options Null<AssetOptions> (optional)
addAll(?pathPattern: EReg): Void

Add all assets matching given path pattern (if provided). Automatically detects asset types based on file extensions.

Name Type Default Description
pathPattern EReg (optional) Optional regex pattern to filter asset paths haxe // Add all assets assets.addAll(); // Add only assets in 'sprites' folder assets.addAll(~/^sprites\/.*$/);
addImage(name: String, ?variant: String, ?options: Null<AssetOptions>): Void
Name Type Default
name String
variant String (optional)
options Null<AssetOptions> (optional)
addFont(name: String, ?variant: String, ?options: Null<AssetOptions>): Void
Name Type Default
name String
variant String (optional)
options Null<AssetOptions> (optional)
addAtlas(name: String, ?variant: String, ?options: Null<AssetOptions>): Void
Name Type Default
name String
variant String (optional)
options Null<AssetOptions> (optional)
addText(name: String, ?variant: String, ?options: Null<AssetOptions>): Void
Name Type Default
name String
variant String (optional)
options Null<AssetOptions> (optional)
addBinary(name: String, ?variant: String, ?options: Null<AssetOptions>): Void
Name Type Default
name String
variant String (optional)
options Null<AssetOptions> (optional)
addSound(name: String, ?variant: String, ?options: Null<AssetOptions>): Void
Name Type Default
name String
variant String (optional)
options Null<AssetOptions> (optional)
addDatabase(name: String, ?variant: String, ?options: Null<AssetOptions>): Void
Name Type Default
name String
variant String (optional)
options Null<AssetOptions> (optional)
addFragments(name: String, ?variant: String, ?options: Null<AssetOptions>): Void
Name Type Default
name String
variant String (optional)
options Null<AssetOptions> (optional)
addShader(name: String, ?variant: String, ?options: Null<AssetOptions>): Void
Name Type Default
name String
variant String (optional)
options Null<AssetOptions> (optional)
addAsset(asset: Asset): Asset

Add the given asset to this Assets instance. If an asset with the same kind and name already exists, it will be replaced.

Name Type Description
asset Asset The asset to add
Returns Description
Asset The previous asset if one was replaced, null otherwise
imageAsset(name: Either<String, AssetId<String>>, ?variant: String): ImageAsset
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
Returns
ImageAsset
fontAsset(name: Either<String, AssetId<String>>, ?variant: String): FontAsset
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
Returns
FontAsset
atlasAsset(name: Either<String, AssetId<String>>, ?variant: String): AtlasAsset
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
Returns
AtlasAsset
textAsset(name: Either<String, AssetId<String>>, ?variant: String): TextAsset
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
Returns
TextAsset
soundAsset(name: Either<String, AssetId<String>>, ?variant: String): SoundAsset
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
Returns
SoundAsset
databaseAsset(name: Either<String, AssetId<String>>, ?variant: String): DatabaseAsset
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
Returns
DatabaseAsset
fragmentsAsset(name: Either<String, AssetId<String>>, ?variant: String): FragmentsAsset
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
Returns
FragmentsAsset
shaderAsset(name: Either<String, AssetId<String>>, ?variant: String): ShaderAsset
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
Returns
ShaderAsset
asset(idOrName: Dynamic, ?kind: String, ?variant: String): Asset
Name Type Default
idOrName Dynamic
kind String (optional)
variant String (optional)
Returns
Asset
removeAsset(asset: Asset): Void
Name Type
asset Asset
moveAll(toAssets: Assets): Void

Move all assets owned by this Assets instance to the given toAssets object. Useful for transferring assets between scenes or asset groups.

Name Type Description
toAssets Assets The target Assets instance to move assets to
hasAnythingToLoad(): Bool

Returns true if there are assets that should be loaded. Checks for assets with status NONE (not yet loaded).

Returns Description
Bool True if there are unloaded assets, false otherwise
countAssetsWithStatus(status: Anonymous): Int
Name Type
status Anonymous
Returns
Int
load(?warnIfNothingToLoad: Bool = true, ?pos: Null<haxe.PosInfos>): Void

Load all assets that have been added to this instance. Emits progress events during loading and complete event when finished.

Name Type Default Description
warnIfNothingToLoad Bool true If true, logs a warning when there are no assets to load
pos Null<haxe.PosInfos> (optional) Source position for debugging (automatically provided)
ensure(id: AssetId<Dynamic>, ?variant: String, ?options: Null<AssetOptions>, done: Function): Void

Ensures and asset is loaded and return it on the callback. This will check if the requested asset is currently being loaded, already loaded or should be added and loaded. In all cases, it will try its best to deliver the requested asset or null if something went wrong.

Name Type Default
id AssetId<Dynamic>
variant String (optional)
options Null<AssetOptions> (optional)
done Function
ensureImage(name: Either<String, AssetId<String>>, ?variant: String, ?options: Null<AssetOptions>, done: Function): Void
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
options Null<AssetOptions> (optional)
done Function
ensureFont(name: Either<String, AssetId<String>>, ?variant: String, ?options: Null<AssetOptions>, done: Function): Void
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
options Null<AssetOptions> (optional)
done Function
ensureAtlas(name: Either<String, AssetId<String>>, ?variant: String, ?options: Null<AssetOptions>, done: Function): Void
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
options Null<AssetOptions> (optional)
done Function
ensureText(name: Either<String, AssetId<String>>, ?variant: String, ?options: Null<AssetOptions>, done: Function): Void
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
options Null<AssetOptions> (optional)
done Function
ensureSound(name: Either<String, AssetId<String>>, ?variant: String, ?options: Null<AssetOptions>, done: Function): Void
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
options Null<AssetOptions> (optional)
done Function
ensureDatabase(name: Either<String, AssetId<String>>, ?variant: String, ?options: Null<AssetOptions>, done: Function): Void
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
options Null<AssetOptions> (optional)
done Function
ensureShader(name: Either<String, AssetId<String>>, ?variant: String, ?options: Null<AssetOptions>, done: Function): Void
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
options Null<AssetOptions> (optional)
done Function
texture(name: Either<String, AssetId<String>>, ?variant: String): Texture

Get a loaded texture by name.

Name Type Default Description
name Either<String, AssetId<String>> The texture name or asset ID
variant String (optional) Optional variant suffix
Returns Description
Texture The texture, or null if not found
font(name: Either<String, AssetId<String>>, ?variant: String): BitmapFont

Get a loaded font by name.

Name Type Default Description
name Either<String, AssetId<String>> The font name or asset ID
variant String (optional) Optional variant suffix
Returns Description
BitmapFont The font, or null if not found
atlas(name: Either<String, AssetId<String>>, ?variant: String): TextureAtlas
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
Returns
TextureAtlas
sound(name: Either<String, AssetId<String>>, ?variant: String): Sound

Get a loaded sound by name.

Name Type Default Description
name Either<String, AssetId<String>> The sound name or asset ID
variant String (optional) Optional variant suffix
Returns Description
Sound The sound, or null if not found
text(name: Either<String, AssetId<String>>, ?variant: String): String

Get loaded text content by name.

Name Type Default Description
name Either<String, AssetId<String>> The text asset name or asset ID
variant String (optional) Optional variant suffix
Returns Description
String The text content, or null if not found
bytes(name: Either<String, AssetId<String>>, ?variant: String): haxe.io.Bytes
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
Returns
haxe.io.Bytes
shader(name: Either<String, AssetId<String>>, ?variant: String): Shader

Get a loaded shader by name.

Name Type Default Description
name Either<String, AssetId<String>> The shader name or asset ID
variant String (optional) Optional variant suffix
Returns Description
Shader The shader, or null if not found
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
Returns
Array<haxe.DynamicAccess<String>>
Name Type Default
name Either<String, AssetId<String>>
variant String (optional)
Returns
haxe.DynamicAccess<FragmentData>
iterator(): Iterator
Returns
Iterator
watchDirectory(?path: String, ?hotReload: Bool = true): WatchDirectory

Watch the given asset directory for changes. Any file change will fire assetFilesChange event and optionally trigger hot reload.

This is particularly useful during development to see asset changes without restarting. Behavior may differ depending on the platform.

Name Type Default Description
path String (optional) The assets path to watch. If null, uses the default assets path from project configuration. You can use ceramic.macros.DefinesMacro.getJsonDefine('assets_path') to get the default.
hotReload Bool true If true (default), assets will automatically reload when their files change
Returns Description
WatchDirectory WatchDirectory instance used internally * haxe // Watch default assets directory with hot reload assets.watchDirectory(); * // Watch custom path without hot reload assets.watchDirectory('/path/to/assets', false); * Note: When using web target via electron, add ceramic_use_electron define.
new(): Void

Private Members

customAssetKinds: Map
reloadCountByRealAssetPath: Map
lastModifiedByRealAssetPath: Map
addedAssets: Array<Asset>
assetsByKindAndName: Map
pendingAtlasPackers: Array<TextureAtlasPacker>
incrementReloadCount(realAssetPath: String): Void
Name Type
realAssetPath String
emitComplete(success: Bool): Void

Emitted when all assets have finished loading.

Name Type Description
success Bool True if all assets loaded successfully, false if any failed
emitUpdate(asset: Asset): Void

Emitted when an individual asset is updated (loaded, reloaded, etc).

Name Type Description
asset Asset The asset that was updated
emitProgress(loaded: Int, total: Int, success: Bool): Void

Emitted during loading to report progress.

Name Type Description
loaded Int Number of assets loaded so far
total Int Total number of assets to load
success Bool True if all loaded assets succeeded so far
emitAssetFilesChange(newFiles: ReadOnlyMap<String, Float>, previousFiles: ReadOnlyMap<String, Float>): Void

Emitted when watched asset files change on disk.

Name Type Description
newFiles ReadOnlyMap<String, Float> Map of file paths to their modification times after change
previousFiles ReadOnlyMap<String, Float> Map of file paths to their modification times before change
assetDestroyed(_: Entity): Void
Name Type
_ Entity
addPendingAtlasPacker(atlasPacker: TextureAtlasPacker): Void
Name Type
atlasPacker TextureAtlasPacker

Metadata

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