Entity

Do not construct an Entity yourself - use the entity() method in World instead. Also, do not shallow/deep copy entity objects, only pass around references.

Return the entity ID.

ID is read-only, attempting to set it will throw an error.

Throw:

Returns a component by name (automatically created if it doesn't exist) For unregistered components, passing no arguments to this will create a {} component, if the component does not exist. The argument behavior is exactly the same as set().

Example:

const position = entity.access('position', 3, 4)

entity.access('anything').foo = 'bar'
// 'anything' now has { foo: 'bar' }

entity.access('anything', { foo: 'bar' }).foo2 = 'bar2'
// 'anything' now has { foo: 'bar', foo2: 'bar2' }

Attaches a currently detached entity back to a world. Do not use detached entities, get() may be safe, but avoid calling other methods The ID will be reassigned, so do not rely on this

Example:

entity.attach(world)

Creates a copy of this entity with all of the components cloned and returns it. Individual components are either shallow or deep copied, depending on component registration status and if a clone() method is defined.

Example:

const clonedEntity = entity.clone()

// How to define custom clone methods
world.component('foo', class {
  onCreate(bar, baz) {
    this.bar = bar
    this.baz = baz
    this.qux = false
  }
  setQux(qux = true) {
    this.qux = qux
  }
  cloneArgs() {
    return [this.bar, this.baz]
  }
  clone(target) {
    target.qux = this.qux
  }
})

Remove this entity and all of its components from the world. After an entity is destroyed, the object should be discarded, and it is recommended to avoid re-using it.

Example:

entity.destroy()

Removes this entity from the current world, without removing any components or data. It can be re-attached to another world (or the same world), using the attach() method. Do not use detached entities, get() may be safe, but avoid calling other methods The ID will be reassigned, so do not rely on this

Example:

entity.detach()

Deserializes data from JSON, creating new components and overwriting existing components. Defining fromJSON methods in your components will override the built-in behavior.

Example:

entity.fromJSON(serializedEntity)

Returns a component by name, or undefined if it doesn't exist

Example:

const position = entity.get('position')

Returns true if the entity has the specified component name.

Example:

entity.has('position')

Removes a component from the entity - has no effect when it doesn't exist. Can specify an onRemove() method in your component which gets called before it is removed. If nothing is specified, then nothing will be removed. Attempting to remove components that aren't set will be safely ignored.

Example:

entity.remove('position')

Low level method to set components directly. It is recommended to use set() instead, unless you know what you are doing. The onCreate method is not called, and it is expected that you pass an already initialized component. By default, an error will be thrown if you try calling this on a registered component, as that could have unintended consequences in your systems. This method can be useful for saving and restoring components without serialization.

Example:

entity.replace('position', position)

Adds a new component, or re-creates and overwrites an existing component

Example:

entity.set('position', 1, 2)
// If position was registered: { x: 1, y: 2 }
// If position was not registered: 1
// This is because only the first arg is used for unregistered components

entity.set('anonymousComponent', { keys: 'values' })

entity.set('someString', 'Any type of any value')

entity.set('thisCompIsUndefined', undefined)

entity.set('thisCompIsEmptyObject')

Serializes entire entity and components to JSON. Defining toJSON methods in your components will override the built-in behavior.

Example:

const serializedEntity = entity.toJSON()

Returns true if this is a valid, existing, and usable entity, which is attached to a world.

Example:

if (entity.valid()) {...}