Skip to main content

Entities

Entities are the backbone of Easel games. Spawn entities, and then attach state, components, and behaviors to bring them to life. See Learn > Entities for a broader overview of how entities work in Easel.

info

This is a template for a standard entity in Easel, which you can adapt depending on your situation:

pub fn hero.Hero([owner]) {
    use body=hero
    let radius=1
    Body(pos=@(0, 0))
    PolygonSprite(shape=Circle(radius=), color=#00ff00)
    PolygonCollider(shape=Circle(radius=), category=Category:Default)
}

A standard entity in Easel has three components:

  1. A Body, which gives it a position in space.
  2. A PolygonSprite or ImageSprite, which gives it a visual representation on screen.
  3. A PolygonCollider, which gives it a physical shape that can collide with other entities and push them around.

Because our hero entity has their own Body, the function begins with a use body=hero statement. This makes the sprite, collider and any future components (e.g. sounds, cameras, particle effects) automatically follow the hero's position and rotation. See Context to learn more.

Many entities also take an owner parameter, which is the player who owns the entity. This is needed because in Easel, every game is multiplayer by default, so we need to be able to distinguish which player owns the entity. This lets you do things like take inputs from the player (e.g. ButtonDown or Pointer).

BeforeDespawn​

await this.BeforeDespawn

Waits until just before the entity is despawned.

Despawn​

this.Despawn -> boolean

Immediately despawns the entity, removing it from the world. Returns true if this still exists and was just despawned. Returns false if this does not exist or is nullish.

DespawnBefore​

this.DespawnBefore(parent)

Causes this to be despawned just before parent is despawned, whenever that occurs. An entity can have multiple parents. Each call to DespawnBefore adds another parent. The entity will despawn whenever the first of its parents despawns.

Exists​

this.Exists -> boolean
Exists(this) -> boolean

Returns true if the entity still exists, false if it has been despawned or is not an entity.

Expire​

this.Expire

Registers to despawn this entity in the next reap phase, which is normally later in the tick. Sometimes despawning an entity in the middle of processing can cause problems, as there may be currently-executing code that is still using the entity. This is sometimes a safer than calling Despawn directly.

Query​

Query(filter?, against?=, [owner?]) -> array

Returns an array of all entities that match the given criteria.

  • filter (Categories): Each entity's Category must overlap at least one of these categories. Defaults to Category:All.

  • against (Flags): Filters entities based on their alliance status with owner. For an entity to match, the alliance status between the owner parameter and the Owner of the Entity must overlap with against. Defaults to Alliance:All. See Alliance flags for all possible values.

  • owner (Entity): The player who is performing the query. Affects how the against filter is interpreted.

Only entities with their Category property assigned will be considered by this function, even if filter is Category:All. If no entities match, returns an empty array.

QueryAny​

QueryAny(filter?, against?=, [owner?]) -> entity

Finds the first entity that matches the given criteria.

  • filter (Categories): The entity's Category must overlap at least one of these categories. Defaults to Category:All.

  • against (Flags): Filters entities based on their alliance status with owner. For an entity to match, the alliance status between the owner parameter and the Owner of the Entity must overlap with against. Defaults to Alliance:All. See Alliance flags for all possible values.

  • owner (Entity): The player who is performing the query. Affects how the against filter is interpreted.

Only entities with their Category property assigned will be considered by this function, even if filter is Category:All. If no entity matches, returns undefined.

QueryCount​

QueryCount(filter?, against?=, [owner?]) -> number

Returns the Number of entities that match the given criteria.

  • filter (Categories): Each entity's Category must overlap at least one of these categories. Defaults to Category:All.

  • against (Flags): Filters entities based on their alliance status with owner. For an entity to match, the alliance status between the owner parameter and the Owner of the Entity must overlap with against. Defaults to Alliance:All. See Alliance flags for all possible values.

  • owner (Entity): The player who is performing the query. Affects how the against filter is interpreted.

Only entities with their Category property assigned will be considered by this function, even if filter is Category:All.

Spawn​

Spawn |use this| { } -> entity

Spawns a new entity.

The subblock defines the main behavior for the entity. The main behavior block will execute concurrently with the rest of the game. When the entity despawns, its main behavior will be terminated (along with all other behaviors attached to the entity).

This function will return as soon as the subblock reaches an await and goes to sleep.

await Spawn |use this| { }

Spawns a new entity, then waits for it to despawn before continuing.

The subblock defines the main behavior for the entity. The main behavior block will execute concurrently with the rest of the game. When the entity despawns, its main behavior will be terminated (along with all other behaviors attached to the entity).

Subspawn​

this.Subspawn |use this| { } -> entity

Spawns a new subentity with this as its parent. When the parent despawns, the subentity will be despawned first.

The subblock defines the main behavior for the new entity, and will execute concurrently with the rest of the game. When the subentity despawns, all of its behaviors will be terminated.

This function returns as soon as its delve block reaches an await and goes to sleep.

await this.Subspawn |use this| { }

Spawns a new subentity with this as its parent, then waits for it to despawn before continuing. When the parent despawns, the subentity will be despawned first.

The subblock defines the main behavior for the new entity, and will execute concurrently with the rest of the game. When the subentity despawns, all of its behaviors will be terminated.

World​

World -> entity

Returns the global entity World. This entity exists before the game starts and will exist until the game ends. It can never be despawned. World can be used to create global properties, behaviors, signals, etc.