FragmentsAsset

An asset that loads and manages fragment data from .fragment files.

Fragments in Ceramic are reusable groups of visuals and entities that can be instantiated from data files. They support:

• Multiple visual elements and entities with properties
• Timeline-based animations with keyframes
• Components that can be attached to fragment items
• Hot-reloading for development

Fragment files can be in two formats:

1. Legacy format: Direct JSON representation of FragmentData objects
2. Version 1 format: Structured format with schema support that gets converted at load time

Example usage:

// Load a fragments asset
var fragmentsAsset = new FragmentsAsset('myFragments.fragment');
fragmentsAsset.onComplete(this, success -> {
    if (success) {
        // Access fragment data
        var menuFragment = fragmentsAsset.fragments.get('mainMenu');
        // Create a Fragment instance from the data
        var fragment = new Fragment();
        fragment.fragmentData = menuFragment;
    }
});
fragmentsAsset.load();

Instance Members #

A map of fragment IDs to their corresponding FragmentData objects. This property is populated after successfully loading the fragments file. Each fragment can be accessed by its ID and used to create Fragment instances.

The property is observable, so you can react to changes when fragments are loaded:

fragmentsAsset.onFragmentsChange(this, (fragments, prevFragments) -> {
    if (fragments != null) {
        // Fragments loaded successfully
        for (id in fragments.keys()) {
            trace('Loaded fragment: ' + id);
        }
    }
});

Loads the fragments file from the specified path.

The loading process:

1. Loads the JSON file as text
2. Parses the JSON data
3. Detects the format version (legacy or version 1)
4. Converts version 1 format to runtime format if needed

Supports hot-reload on platforms that allow it - the file will be automatically reloaded when it changes on disk.

Destroys the fragments asset and clears the loaded fragment data from memory.

Private Members #

Converts version 1 fragment format to the runtime format.

This method handles the transformation of the newer fragment file format that includes additional metadata and schema information. It processes:

• Fragment metadata (id, dimensions, color, transparency)
• Visual and entity items with their properties
• Component configurations
• Schema references for entity types

Event when fragments field changes.

Called when asset files change on disk (hot-reload support). Automatically reloads the fragments file if it has been modified.

Metadata #