Entity

View source
ceramic.Entity (Class) → Project, App, AsepriteData, Asset, Assets, Audio, AudioFilter, AudioMixer, AutoTiler, BackgroundQueue, BitmapFont, Camera, Click, DoubleClick, DynamicData, EditText, FileWatcher, GifCapture, Group, Input, KeyBinding, KeyBindings, LdtkData, Logger, LongPress, ParticleEmitter, Renderer, Screen, Script, SelectText, Shader, Sound, SpineData, SpineMontage, State, StateMachineBase, System, Systems, Task, Texture, TextureAtlas, TextureAtlasPacker, TextureTilePacker, TilemapEditor, Timeline, TimelineTrack, Timelines, Tween, VisibleBounds, Visual, VisualArcadePhysics, VisualNapePhysics, VisualTransition, WatchDirectory, ceramic._Spine.DispatchSlotInfo, elements.Context, elements.DragDrop, elements.ItalicText, elements.TabFocus, tracker.Autorun, tracker.DynamicEvents, tracker.History, tracker.Model, tracker.SerializeModel, tracker.ShareModel
Implements: Lazy, tracker.Events

Base class for all entities in the Ceramic framework.

An Entity is the fundamental building block of Ceramic, providing lifecycle management, event handling, component system support, and automatic memory management. All game objects, visuals, and systems extend from this class.

Key features:

  • Automatic lifecycle management with destroy() and dispose()
  • Component-based architecture support
  • Event system integration
  • Autorun support for reactive programming
  • Tween integration for animations
  • Memory leak protection with proper cleanup

Instance Members

Optional identifier for this entity. Can be used to retrieve specific entities by their ID.

destroyed: Bool

Whether this entity has been destroyed. Once destroyed, an entity should not be used anymore.

disposed: Bool

Whether this entity has been marked for disposal. Disposed entities will be destroyed at the end of the current frame.

Array of Autorun instances associated with this entity. Autoruns are automatically destroyed when the entity is destroyed.

Public components mapping containing all components attached to this entity. Components can be created using the component() method or via macro-based component fields. Setting this property will replace all existing components.

destroy(): Void

Destroy this entity. This method is automatically protected from duplicate calls. That means calling multiple times an entity's destroy() method will run the destroy code only one time. As soon as destroy() is called, the entity is marked destroyed=true, even when calling destroy() method on a subclass (a macro is inserting a code to mark the object as destroyed at the beginning of every destroy() override function.

dispose(): Void

Schedules destroy at the end of the current frame. This is useful to avoid destroying entities during iteration or event handling. The entity will be marked as disposed immediately but actual destruction happens later.

unbindEvents(): Void

Remove all event handlers from this entity. This method is automatically called during destruction to prevent memory leaks. Subclasses will have this method automatically filled by the Events macro.

autorun(run: Function, ?afterRun: Function): tracker.Autorun

Creates a new Autorun instance with the given callback associated with the current entity.

Name Type Default Description
run Function The run callback
afterRun Function (optional)
Returns Description
tracker.Autorun The autorun instance
tween(?easing: Anonymous, duration: Float, fromValue: Float, toValue: Float, update: Function): Tween

Start a tween animation associated with this entity. The tween will automatically be destroyed when this entity is destroyed.

Name Type Default Description
easing Anonymous (optional) The easing function to use for the animation
duration Float The duration of the tween in seconds
fromValue Float The starting value of the tween
toValue Float The ending value of the tween
update Function Callback function called on each frame with current value and progress (0-1)
Returns Description
Tween The created Tween instance for chaining or manual control
eagerTween(?easing: Anonymous, duration: Float, fromValue: Float, toValue: Float, update: Function): Tween

Start an eager tween associated with this entity. This is the same as a regular tween, except that it will start updating itself using current frame's delta time instead of next frame like in a regular tween.

Name Type Default Description
easing Anonymous (optional) The easing to use
duration Float The duration of the tween
fromValue Float The start value of the tween
toValue Float The end value of the tween
update Function An update function called at each iteration of the tween
Returns Description
Tween The instance of the created Tween object
className(): String

Get the class name of this entity without the package path.

Returns Description
String The simple class name (e.g., "Entity" instead of "ceramic.Entity")
clearComponents(): Void

Remove and destroy all components attached to this entity. This is automatically called during entity destruction.

component(?name: String, ?component: Null<component.C>, ?hasField: Bool = false): component.C

Get or set a component on this entity.

When called with just a name, retrieves the component with that name. When called with a component instance, attaches it to this entity.

Name Type Default Description
name String (optional) The name to identify the component. If null, uses the component's class name
component Null<component.C> (optional) The component instance to attach. If null, retrieves existing component
hasField Bool false Internal flag indicating if this component has a corresponding field
Returns Description
component.C The component instance (either retrieved or newly attached)
hasComponent(name: String): Bool

Check if this entity has a component with the given name.

Name Type Description
name String The name of the component to check
Returns Description
Bool True if the component exists, false otherwise
removeComponent(name: String): Void

Remove and destroy a component from this entity.

Name Type Description
name String The name of the component to remove
new(): Void

Create a new entity.

script
scriptContent: ScriptContent
script
script: Script

Private Members

emitDispose(entity: Entity): Void

dispose event

Name Type
entity Entity
emitDestroy(entity: Entity): Void

destroy event

Name Type
entity Entity
checkAutoruns(_: Entity): Void
Name Type
_ Entity
toString(): String

String representation of this entity.

Returns Description
String String in format "ClassName" or "ClassName(id)" if id is set

Metadata

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