Skip to main content

Entities

An Entity in is an empty container for Components which store data, alone an Entity has little behavior.

They are useful for defining bare bones game objects with custom behavior.

If you want a batteries included prebuilt Entity use an Actor, read more here. Remember an Excalibur Actor is just an Entity with a list of prebuilt components and some useful apis built over them.

Entity​

Entities have no behavior by default, only a few lifecycle hooks onInitialize, and a concept of parent/children.

Building and adding an entity to a game is pretty straightforward.

typescript
const game = new ex.Engine({...});
const entity = new ex.Entity();
const entityWithName = new ex.Entity({name: 'Named Entity'});
game.currentScene.add(entity);
typescript
const game = new ex.Engine({...});
const entity = new ex.Entity();
const entityWithName = new ex.Entity({name: 'Named Entity'});
game.currentScene.add(entity);

Child Entities​

Entities can be added as children of other entities, once added child entities move relative to their parents.

  • Entity.parent - Returns the parent of this entity, if one exists otherwise returns null

  • Entity.children - Returns the list of child entities, otherwise returns an empty list

  • Entity.unparent() - Removes this entity from its parent this entity

  • Entity.addChild(entity) - Add a child to this entity

  • Entity.removeChild(entity) - Remove a child

  • Entity.removeAllChildren() - Removal all children

Lifecycle​

  • onInitialize happens before first update
  • onPreUpdate happens at the beginning of update
  • onPostUpdate happens at the end of the update

Components​

Components can be added and removed from an entity. Only 1 instance of a component type can be part of an entity at at time.

When removing components removal is deferred until the end of the update, unless forced. Deferred removal is useful to prevent bugs where an entity is only partially processed by all applicable systems.

typescript
const entity = new ex.Entity()
entity.addComponent(new ex.TransformComponent())
// Remove by type or instances
entity.removeComponent(ex.TransformComponent)
// Force removal
entity.removeComponent(ex.TransformComponent, true)
typescript
const entity = new ex.Entity()
entity.addComponent(new ex.TransformComponent())
// Remove by type or instances
entity.removeComponent(ex.TransformComponent)
// Force removal
entity.removeComponent(ex.TransformComponent, true)

Components can be retrieved by type name, however if the component doesn't exist undefined will be returned.

typescript
const entity = new ex.Entity()
const maybeTransform = entity.get(ex.TransformComponent)
if (maybeTransform) {
  console.log(maybeTransform.pos)
}
typescript
const entity = new ex.Entity()
const maybeTransform = entity.get(ex.TransformComponent)
if (maybeTransform) {
  console.log(maybeTransform.pos)
}

Entities can be checked for components as well

typescript
const entity = new ex.Entity()
if (entity.has(ex.TransformComponent)) {
  console.log('Entity has a transform component')
}
typescript
const entity = new ex.Entity()
if (entity.has(ex.TransformComponent)) {
  console.log('Entity has a transform component')
}

All the components can be retrieved at once

typescript
const components: Component[] = entity.getComponents()
typescript
const components: Component[] = entity.getComponents()

Tags​

Tags are special components that are only types. Useful when the presence of a component is all that is needed.

  • Entity.addTag("someTag") - Add a tag to an entity
  • Entity.removeTag("someTag") - Remove a tag on an entity
  • Entity.hasTag("someTag") - Check if a tag exists

Templates aka Prefab​

  • Entity.addTemplate(TemplateEntity)

EntityManager​

  • EntityManager.getById(entityId)
  • EntityManager.getByName(entityName)