Actor
Hierarchy
Implements
Index
Constructors
Properties
Accessors
Methods
- addChild
- addComponent
- addTag
- addTemplate
- clearComponents
- clone
- contains
- emit
- get
- getAncestors
- getComponents
- getDescendants
- getGlobalPos
- getGlobalRotation
- getGlobalScale
- has
- hasAll
- hasAllTags
- hasTag
- isKilled
- kill
- off
- on
- onCollisionEnd
- onCollisionStart
- onInitialize
- onPostCollisionResolve
- onPostKill
- onPostUpdate
- onPreCollisionResolve
- onPreKill
- onPreUpdate
- once
- removeAllChildren
- removeChild
- removeComponent
- removeTag
- unkill
- unparent
- within
Constructors
constructor
Properties
publicactions
Useful for quickly scripting actor behavior, like moving to a place, patrolling back and forth, blinking, etc.
Access to the Actor's built in [[ActionsComponent]] which forwards to the [[ActionContext|Action context]] of the actor.
publicactive
Whether this entity is active, if set to false it will be reclaimed
publicbody
The physics body the is associated with this actor. The body is the container for all physical properties, like position, velocity, acceleration, mass, inertia, etc.
publicchildrenAdded$
publicchildrenRemoved$
publiccollider
Access to the Actor's built in [[ColliderComponent]]
publiccomponentAdded$
publiccomponentRemoved$
publicreadonlycomponents
Current components on the entity
Do not modify
Use addComponent/removeComponent otherwise the ECS will not be notified of changes.
publicevents
Listen to or emit events for an entity
publicgraphics
Access to the Actor's built in [[GraphicsComponent]]
publicid
The unique identifier for the entity
publiclogger
Convenience reference to the global logger
publicmotion
Access the Actor's built in [[MotionComponent]]
publicname
publicpointer
Access to the Actor's built in [[PointerComponent]] config
publicscene
The current scene that the entity is in, if any
publictagAdded$
publictagRemoved$
publictransform
Access the Actor's built in [[TransformComponent]]
publicstaticdefaults
Accessors
publicacc
publicanchor
The anchor to apply all actor related transformations like rotation, translation, and scaling. By default the anchor is in the center of the actor. By default it is set to the center of the actor (.5, .5)
An anchor of (.5, .5) will ensure that drawings are centered.
Use
anchor.setToto set the anchor to a different point using values between 0 and 1. For example, anchoring to the top-left would beActor.anchor.setTo(0, 0)and top-right would beActor.anchor.setTo(0, 1).Returns Vector
Parameters
vec: Vector
Returns void
publicangularVelocity
Gets the rotational velocity of the actor in radians/second
Returns number
Sets the rotational velocity of the actor in radians/sec
Parameters
angularVelocity: number
Returns void
publiccenter
Get the center point of an actor (global position)
Returns Vector
publicchildren
Get the direct children of this entity
Returns readonly Entity<any>[]
publiccolor
publicdraggable
Returns boolean
Parameters
isDraggable: boolean
Returns void
publicglobalPos
The actor's world position taking into account parent relationships, scaling, rotation, and translation
Returns Vector
publicglobalRotation
The actor's rotation (in radians) taking into account any parent relationships
Returns number
publicglobalScale
The global scale of the Actor
Returns Vector
publicheight
Returns number
publicisInitialized
Gets whether the actor is Initialized
Returns boolean
publicisOffScreen
Indicates whether the actor is physically in the viewport
Returns boolean
publiclocalCenter
Get the local center point of an actor
Returns Vector
publicoffset
publicoldAcc
publicoldGlobalPos
Gets the global position vector of the actor from the last frame
Returns Vector
publicoldPos
publicoldVel
publicparent
Returns Entity<any>
publicpos
publicrotation
Gets the rotation of the actor in radians. 1 radian = 180/PI Degrees.
Returns number
Sets the rotation of the actor in radians. 1 radian = 180/PI Degrees.
Parameters
theAngle: number
Returns void
publicscale
publictags
Specifically get the tags on the entity from [[TagsComponent]]
Returns Set<string>
publictypes
The types of the components on the Entity
Returns ComponentCtor[]
publicvel
publicwidth
Returns number
publicz
Gets the z-index of an actor. The z-index determines the relative order an actor is drawn in. Actors with a higher z-index are drawn on top of actors with a lower z-index
Returns number
Sets the z-index of an actor and updates it in the drawing list for the scene. The z-index determines the relative order an actor is drawn in. Actors with a higher z-index are drawn on top of actors with a lower z-index
Parameters
newZ: number
new z-index to assign
Returns void
Methods
publicaddChild
publicaddComponent
publicaddTag
Adds a tag to an entity
Parameters
tag: string
Returns Entity<any>
publicaddTemplate
publicclearComponents
Returns void
publicclone
Creates a deep copy of the entity and a copy of all its components
Returns Actor
publiccontains
Tests whether the x/y specified are contained in the actor
Parameters
x: number
X coordinate to test (in world coordinates)
y: number
Y coordinate to test (in world coordinates)
recurse: boolean = false
checks whether the x/y are contained in any child actors (if they exist).
Returns boolean
publicemit
Emits an event for target
Type parameters
- TEventName: EventKey<ActorEvents>
Parameters
eventName: TEventName
The name of the event to publish
event: ActorEvents[TEventName]
Optionally pass an event data object to the handler
Returns void
get
Type parameters
- TComponent: Component
Parameters
type: ComponentCtor<TComponent>
Returns MaybeKnownComponent<TComponent, any>
publicgetAncestors
Returns a list of parent entities starting with the topmost parent. Includes the current entity.
Returns Entity<any>[]
publicgetComponents
Returns all component instances on entity
Returns Component[]
publicgetDescendants
Returns a list of all the entities that descend from this entity. Includes the current entity.
Returns Entity<any>[]
publicgetGlobalPos
Gets an actor's world position taking into account parent relationships, scaling, rotation, and translation
Returns Vector
Position in world coordinates
publicgetGlobalRotation
Gets this actor's rotation taking into account any parent relationships
Returns number
Rotation angle in radians
publicgetGlobalScale
Gets the global scale of the Actor
Returns Vector
publichas
Check if a component type exists
Type parameters
- TComponent: Component
Parameters
type: ComponentCtor<TComponent>
Returns boolean
hasAll
Verifies that an entity has all the required types
Type parameters
- TComponent: Component
Parameters
requiredTypes: ComponentCtor<TComponent>[]
Returns boolean
hasAllTags
Verifies that an entity has all the required tags
Parameters
requiredTags: string[]
Returns boolean
publichasTag
Check if a tag exists on the entity
Parameters
tag: string
name to check for
Returns boolean
publicisKilled
Indicates wether the actor has been killed.
Returns boolean
publickill
If the current actor is a member of the scene, this will remove it from the scene graph. It will no longer be drawn or updated.
Returns void
publicoff
Unsubscribe an event handler(s) from an event. If a specific handler is specified for an event, only that handler will be unsubscribed. Otherwise all handlers will be unsubscribed for that event.
Type parameters
- TEventName: EventKey<ActorEvents>
Parameters
eventName: TEventName
The name of the event to unsubscribe
handler: Handler<ActorEvents[TEventName]>
Optionally the specific handler to unsubscribe
Returns void
publicon
Subscribe an event handler to a particular event name, multiple handlers per event name are allowed.
Type parameters
- TEventName: EventKey<ActorEvents>
Parameters
eventName: TEventName
The name of the event to subscribe to
handler: Handler<ActorEvents[TEventName]>
The handler callback to fire on this event
Returns Subscription
publiconCollisionEnd
Fires once when 2 entities with a ColliderComponent separate after having been in contact.
Parameters
self: Collider
other: Collider
side: Side
lastContact: CollisionContact
Returns void
publiconCollisionStart
Fires once when 2 entities with a ColliderComponent first start colliding or touching, if the Colliders stay in contact this does not continue firing until they separate and re-collide.
Parameters
self: Collider
other: Collider
side: Side
contact: CollisionContact
Returns void
publiconInitialize
onInitializeis called before the first update of the actor. This method is meant to be overridden. This is where initialization of child actors should take place.Synonymous with the event handler
.on('initialize', (evt) => {...})Parameters
engine: Engine<any>
Returns void
publiconPostCollisionResolve
Fires after every resolution for a confirmed contact.
Parameters
self: Collider
other: Collider
side: Side
contact: CollisionContact
Returns void
publiconPostKill
Safe to override onPostKill lifecycle event handler. Synonymous with
.on('postkill', (evt) => {...})onPostKillis called directly after an actor is killed and remove from its current [[Scene]].Parameters
scene: Scene<unknown>
Returns void
publiconPostUpdate
Safe to override onPostUpdate lifecycle event handler. Synonymous with
.on('postupdate', (evt) =>{...})onPostUpdateis called directly after an actor is updated.Parameters
engine: Engine<any>
delta: number
Returns void
publiconPreCollisionResolve
Fires before every collision resolution for a confirmed contact
Parameters
self: Collider
other: Collider
side: Side
contact: CollisionContact
Returns void
publiconPreKill
Safe to override onPreKill lifecycle event handler. Synonymous with
.on('prekill', (evt) =>{...})onPreKillis called directly before an actor is killed and removed from its current [[Scene]].Parameters
scene: Scene<unknown>
Returns void
publiconPreUpdate
Safe to override onPreUpdate lifecycle event handler. Synonymous with
.on('preupdate', (evt) =>{...})onPreUpdateis called directly before an actor is updated.Parameters
engine: Engine<any>
delta: number
Returns void
publiconce
Once listens to an event once then auto unsubscribes from that event
Type parameters
- TEventName: EventKey<ActorEvents>
Parameters
eventName: TEventName
The name of the event to subscribe to once
handler: Handler<ActorEvents[TEventName]>
The handler of the event that will be auto unsubscribed
Returns Subscription
publicremoveAllChildren
Removes all children from this entity
Returns Entity<any>
publicremoveChild
publicremoveComponent
Removes a component from the entity, by default removals are deferred to the end of entity update to avoid consistency issues
Components can be force removed with the
forceflag, the removal is not deferred and happens immediatelyType parameters
- TComponent: Component
Parameters
typeOrInstance: TComponent | ComponentCtor<TComponent>
force: boolean = false
Returns Entity<Exclude<any, TComponent>>
publicremoveTag
Removes a tag on the entity
Removals are deferred until the end of update
Parameters
tag: string
Returns Entity<any>
publicunkill
If the current actor is killed, it will now not be killed.
Returns void
publicunparent
Unparents this entity, if there is a parent. Otherwise it does nothing.
Returns void
publicwithin
Returns true if the two actor.collider's surfaces are less than or equal to the distance specified from each other
Parameters
actor: Actor
Actor to test
distance: number
Distance in pixels to test
Returns boolean
The most important primitive in Excalibur is an
Actor. Anything that can move on the screen, collide with anotherActor, respond to events, or interact with the current scene, must be an actor. AnActormust be part of a [[Scene]] for it to be drawn to the screen.