Helper [[Actor]] primitive for drawing UI's, optimized for UI drawing. Does not participate in collisions. Drawn on top of all other actors.

Hierarchy

Constructors

Properties

_engine: Engine
active: boolean = true

Whether this entity is active, if set to false it will be reclaimed

childrenAdded$: Observable<Entity> = ...
childrenRemoved$: Observable<Entity> = ...
componentAdded$: Observable<AddedComponent> = ...

Observable that keeps track of component add or remove changes on the entity

componentRemoved$: Observable<RemovedComponent> = ...
events: EventEmitter<ActorEvents> = ...

Listen to or emit events for an entity

id: number = ...

The unique identifier for the entity

logger: Logger = ...

Convenience reference to the global logger

scene: Scene<unknown> = null

The scene that the entity is in, if any

defaults: {
    anchor: Vector;
} = ...

Set defaults for all Actors

Type declaration

Accessors

  • get acc(): Vector
  • Gets the acceleration vector of the actor in pixels/second/second. An acceleration pointing down such as (0, 100) may be useful to simulate a gravitational effect.

    Returns Vector

  • set acc(theAcc): void
  • Sets the acceleration vector of teh actor in pixels/second/second

    Parameters

    Returns void

  • get actions(): ActionsComponent
  • 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.

    Returns ActionsComponent

  • get angularVelocity(): number
  • Gets the rotational velocity of the actor in radians/second

    Returns number

  • set angularVelocity(angularVelocity): void
  • Sets the rotational velocity of the actor in radians/sec

    Parameters

    • angularVelocity: number

    Returns void

  • get body(): BodyComponent
  • 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.

    Returns BodyComponent

  • get center(): Vector
  • Get the center point of an actor (global position)

    Returns Vector

  • get color(): Color
  • Sets the color of the actor's current graphic

    Returns Color

  • set color(v): void
  • Parameters

    Returns void

  • get draggable(): boolean
  • Returns boolean

  • set draggable(isDraggable): void
  • Parameters

    • isDraggable: boolean

    Returns void

  • get height(): number
  • Returns number

  • get isOffScreen(): boolean
  • Indicates whether the actor is physically in the viewport

    Returns boolean

  • get localCenter(): Vector
  • Get the local center point of an actor

    Returns Vector

  • get oldAcc(): Vector
  • Gets the acceleration of the actor from the last frame. This does not include the global acc [[Physics.acc]].

    Returns Vector

  • set oldAcc(theAcc): void
  • Sets the acceleration of the actor from the last frame. This does not include the global acc [[Physics.acc]].

    Parameters

    Returns void

  • get oldPos(): Vector
  • Gets the position vector of the actor from the last frame

    Returns Vector

  • set oldPos(thePos): void
  • Sets the position vector of the actor in the last frame

    Parameters

    Returns void

  • get oldVel(): Vector
  • Gets the velocity vector of the actor from the last frame

    Returns Vector

  • set oldVel(theVel): void
  • Sets the velocity vector of the actor from the last frame

    Parameters

    Returns void

  • get pos(): Vector
  • Gets the position vector of the actor in pixels

    Returns Vector

  • set pos(thePos): void
  • Sets the position vector of the actor in pixels

    Parameters

    Returns void

  • get rotation(): number
  • Gets the rotation of the actor in radians. 1 radian = 180/PI Degrees.

    Returns number

  • set rotation(theAngle): void
  • Sets the rotation of the actor in radians. 1 radian = 180/PI Degrees.

    Parameters

    • theAngle: number

    Returns void

  • get tags(): readonly string[]
  • Specifically get the tags on the entity from [[TagComponent]]

    Returns readonly string[]

  • get vel(): Vector
  • Gets the velocity vector of the actor in pixels/sec

    Returns Vector

  • set vel(theVel): void
  • Sets the velocity vector of the actor in pixels/sec

    Parameters

    Returns void

  • get width(): number
  • Returns number

  • get z(): number
  • 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

  • set z(newZ): void
  • 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

  • Internal

    Initializes this actor and all it's child actors, meant to be called by the Scene before first update not by users of Excalibur.

    It is not recommended that internal excalibur methods be overridden, do so at your own risk.

    Parameters

    Returns void

  • Internal

    It is not recommended that internal excalibur methods be overridden, do so at your own risk.

    Internal _prekill handler for [[onPostKill]] lifecycle event

    Parameters

    Returns void

  • Internal

    It is not recommended that internal excalibur methods be overridden, do so at your own risk.

    Internal _preupdate handler for [[onPostUpdate]] lifecycle event

    Parameters

    Returns void

  • Internal

    It is not recommended that internal excalibur methods be overridden, do so at your own risk.

    Internal _prekill handler for [[onPreKill]] lifecycle event

    Parameters

    Returns void

  • Internal

    It is not recommended that internal excalibur methods be overridden, do so at your own risk.

    Internal _preupdate handler for [[onPreUpdate]] lifecycle event

    Parameters

    Returns void

  • Adds a component to the entity

    Type Parameters

    Parameters

    • component: T

      Component or Entity to add copy of components from

    • force: boolean = false

      Optionally overwrite any existing components of the same type

    Returns Entity

  • Adds a copy of all the components from another template entity as a "prefab"

    Parameters

    • templateEntity: Entity

      Entity to use as a template

    • force: boolean = false

      Force component replacement if it already exists on the target entity

    Returns Entity

  • 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)

    • useWorld: boolean = true

      checks whether the x/y are contained in any child actors (if they exist).

    Returns boolean

  • Emits an event for target

    Type Parameters

    • TEventName extends 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

  • Parameters

    • eventName: string
    • Optional event: any

    Returns void

  • Gets an actor's world position taking into account parent relationships, scaling, rotation, and translation

    Returns Vector

    Position in world coordinates

  • Gets this actor's rotation taking into account any parent relationships

    Returns number

    Rotation angle in radians

  • Indicates wether the actor has been killed.

    Returns boolean

  • 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

  • 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 extends EventKey<ActorEvents>

    Parameters

    • eventName: TEventName

      The name of the event to unsubscribe

    • handler: Handler<ActorEvents[TEventName]>

      Optionally the specific handler to unsubscribe

    Returns void

  • Parameters

    • eventName: string
    • handler: Handler<unknown>

    Returns void

  • Parameters

    • eventName: string

    Returns void

  • Subscribe an event handler to a particular event name, multiple handlers per event name are allowed.

    Type Parameters

    • TEventName extends 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

  • Event signatures

    Parameters

    • eventName: string
    • handler: Handler<unknown>

    Returns Subscription

  • onInitialize is 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

    Returns void

  • Safe to override onPostKill lifecycle event handler. Synonymous with .on('postkill', (evt) => {...})

    onPostKill is called directly after an actor is killed and remove from its current [[Scene]].

    Parameters

    Returns void

  • Safe to override onPostUpdate lifecycle event handler. Synonymous with .on('postupdate', (evt) =>{...})

    onPostUpdate is called directly after an actor is updated.

    Parameters

    Returns void

  • Safe to override onPreKill lifecycle event handler. Synonymous with .on('prekill', (evt) =>{...})

    onPreKill is called directly before an actor is killed and removed from its current [[Scene]].

    Parameters

    Returns void

  • Safe to override onPreUpdate lifecycle event handler. Synonymous with .on('preupdate', (evt) =>{...})

    onPreUpdate is called directly before an actor is updated.

    Parameters

    Returns void

  • Once listens to an event once then auto unsubscribes from that event

    Type Parameters

    • TEventName extends 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

  • Parameters

    • eventName: string
    • handler: Handler<unknown>

    Returns Subscription

  • 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 force flag, the removal is not deferred and happens immediately

    Type Parameters

    • ComponentOrType extends string | Component<string>

    Parameters

    • componentOrType: ComponentOrType
    • force: boolean = false

    Returns Entity

  • If the current actor is killed, it will now not be killed.

    Returns void

  • Internal

    Called by the Engine, updates the state of the actor

    Parameters

    • engine: Engine

      The reference to the current game engine

    • delta: number

      The time elapsed since the last update in milliseconds

    Returns void

  • 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