Fragment

View source
Entity → Visual → Quad → Layer → ceramic.Fragment (Class)

A fragment is a powerful container that manages groups of entities and visuals loaded from fragment data files (.fragment).

Fragments provide:

  • Dynamic entity instantiation from data definitions
  • Timeline-based animation support with tracks and keyframes
  • Component system integration
  • Hierarchical entity management
  • Asset loading and dependency management

Fragments are commonly used for:

  • UI layouts and screens
  • Reusable game objects and prefabs
  • Animated sequences and cutscenes
  • Data-driven content that needs to be loaded/unloaded dynamically
See: FragmentData, FragmentItem, Timeline

Static Members

cacheData(fragmentData: FragmentData): Void

Cache fragment data for later retrieval by ID. This allows fragments to reference other fragments efficiently.

Name Type Description
fragmentData FragmentData The fragment data to cache
getData(fragmentId: String): Null<FragmentData>

Retrieve cached fragment data by ID. The data must have been previously cached with cacheData().

Name Type Description
fragmentId String The ID of the fragment data to retrieve
Returns Description
Null<FragmentData> The cached fragment data, or null if not found

Instance Members

assets: Assets

The asset manager used to load resources referenced by this fragment. If not provided, the fragment will use the default app assets.

entities: Array<Entity>

Array of all entity instances created from fragment items. This includes all types of entities: visuals, components, and other objects.

Array of fragment item definitions loaded from fragment data. Each item describes an entity to be instantiated with its properties.

Array of timeline track data for animating entity properties. Each track defines keyframe animations for a specific entity field.

fps: Int

Frames per second for timeline animations. Affects the playback speed of all timeline tracks in this fragment. Default is 30 FPS.

fragmentData: FragmentData

The fragment data that defines this fragment's content. Setting this property will instantiate/update all entities and animations.

resizable: Bool

Whether this fragment can be resized. When true, the fragment dimensions can be changed after initialization.

autoUpdateTimeline: Bool

Whether the timeline should automatically update each frame. Set to false to manually control timeline playback. Default is true.

pendingLoads: Int

Number of pending asset loads. When this reaches 0, the fragment becomes ready.

timeline: Timeline

The timeline instance managing animations for this fragment. Created automatically when tracks are added.

ready: Bool

Whether the fragment has finished loading all assets and is ready to use. Becomes true when all pending loads complete.

fragmentComponents: ReadOnlyMap<String, Component>

Components defined at the fragment level (not on individual entities). These are separate from components added via component() or the components property. Setting this property will add/remove/update components as needed.

paused: Bool

Whether the timeline playback is paused. Setting this to true stops all animations in the fragment.

scheduleWhenReady(owner: Entity, cb: Function): Void

Schedule a callback to be executed when the fragment is ready. If already ready, the callback is executed immediately.

Name Type Description
owner Entity The entity that owns this callback (for cleanup)
cb Function The callback to execute when ready
putItem(item: FragmentItem): Entity

Create or update an entity from a fragment item definition. If an entity with the same ID already exists, it will be updated. Otherwise, a new entity is created and added to the fragment.

Name Type Description
item FragmentItem The fragment item definition
Returns Description
Entity The created or updated entity instance
get(itemId: String): Entity

Get an entity by its ID.

Name Type Description
itemId String The ID of the entity to retrieve
Returns Description
Entity The entity instance, or null if not found
getItem(itemId: String): FragmentItem

Get a fragment item definition by ID.

Name Type Description
itemId String The ID of the item to retrieve
Returns Description
FragmentItem The fragment item definition, or null if not found
getItemByName(name: String): FragmentItem

Get a fragment item definition by name.

Name Type Description
name String The name of the item to retrieve
Returns Description
FragmentItem The fragment item definition, or null if not found
typeOfItem(itemId: String): String

Get the entity class name for a fragment item.

Name Type Description
itemId String The ID of the item
Returns Description
String The fully qualified class name of the entity type
removeItem(itemId: String): Void

Remove an entity and its item definition from the fragment. The entity will be destroyed.

Name Type Description
itemId String The ID of the item to remove
removeAllItems(): Void

Remove all entities and item definitions from the fragment. All entities will be destroyed.

destroy(): Void
putTrack(?entityType: String, track: TimelineTrackData): Void

Create or update a timeline track for animating entity properties. The track will be added to the fragment's timeline, creating it if needed.

Name Type Default Description
entityType String (optional) Optional entity type. If not provided, will be resolved from the entity ID.
track TimelineTrackData The track data containing entity ID, field name, and keyframes
getTrack(entity: String, field: String): TimelineTrackData

Get timeline track data for a specific entity field.

Name Type Description
entity String The entity ID
field String The field name being animated
Returns Description
TimelineTrackData The track data, or null if not found
removeTrack(entity: String, field: String): Void

Remove a timeline track for a specific entity field.

Name Type Description
entity String The entity ID
field String The field name being animated
createTimelineIfNeeded(): Void

Create the timeline instance if it doesn't exist yet. Called automatically when tracks or labels are added.

putLabel(index: Int, name: String): Void

Create or update a timeline label at a specific position. Labels can be used to mark important points in the animation.

Name Type Description
index Int The timeline position (frame index)
name String The label name
indexOfLabel(name: String): Int

Get the timeline position of a label by name.

Name Type Description
name String The label name
Returns Description
Int The frame index, or -1 if the label doesn't exist
labelAtIndex(index: Int): String

Get the label name at a specific timeline position.

Name Type Description
index Int The frame index
Returns Description
String The label name, or null if no label exists at that position
removeLabel(name: String): Void

Remove a timeline label by name.

Name Type Description
name String The label name to remove
removeLabelAtIndex(index: Int): Void

Remove a timeline label at a specific position.

Name Type Description
index Int The frame index where the label should be removed
new(?assets: Assets): Void

Create a new fragment instance.

Name Type Default Description
assets Assets (optional) Optional asset manager for loading resources. If not provided, uses the default app assets.

Private Members

basicTypes: Map
cachedFragmentData: Map
emitReady(): Void

Event emitted when the fragment becomes ready. All assets are loaded and entities are instantiated.

willEmitReady(): Void
typeOfItemField(item: FragmentItem, field: String): String
Name Type
item FragmentItem
field String
Returns
String
putItemField(isFragment: Bool, item: FragmentItem, instance: Entity, field: String, value: Dynamic, converter: ConvertField<Dynamic, Dynamic>): Void
Name Type
isFragment Bool
item FragmentItem
instance Entity
field String
value Dynamic
converter ConvertField<Dynamic, Dynamic>
isManagedComponent(): Void
putTracksForItem(itemId: String): Void
Name Type
itemId String

Metadata

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