Components #

A component is an object that can store data but should have no behavior (as that's handled by systems). You'll typically have many instances of a component type, each held in an entity. (Though sometimes you'll have singletons.)

In Becsy, a component type is just a class with a default, empty constructor, and a schema that specifies the type of each field so that Becsy can allocate the right kind of storage:

import {Type} from '@lastolivegames/becsy';

class ComponentA {
  static schema = {
    booleanValue: Type.boolean,
    integerValue: {type: Type.uint32, default: 10},
    stringValue: {type: Type.dynamicString(32)}
  };
}

import {component, field, Type} from '@lastolivegames/becsy';

@component class ComponentA {
  @field.boolean declare booleanValue: boolean;
  @field({type: Type.uint32, default: 10}) declare integerValue: number;
  @field.dynamicString(32) declare stringValue: string;
}

Each field in the schema represents one property on the component's instances, and can also be used to set default values. Some component types are used just as tags and don't store any data, in which case your should omit the schema to enable some optimizations.

While you should generally keep behavior out of components — lest you fall into an object-oriented architecture instead — we think it's fine and useful to, for example, define generic getters and setters on your component classes to assist with data wrangling. This is especially the case if you're packing multiple values into a field using bit-level operations to lower your memory footprint.

Field types #

Unless otherwise stated, the types are strict and don't accept null or undefined as values.

Numeric vectors #

When you need a component to hold some numeric values of the same type, you can of course declare them as separate fields. However, it often makes sense to treat them as a single, composite value, whether for better organization, for increased performance due to cache locality, or to fit in with a third party API. In that case you can declare a vector field instead:

@component class MovingEntity {
  @field.float64.vector(3)
  declare position: [number, number, number] & {asTypedArray(): Float64Array};
  @field.float64.vector(3)
  declare velocity: [number, number, number] & {asTypedArray(): Float64Array};
}

world.build(sys => {
  const player = sys.createEntity(
    MovingEntity, {position: [10, 0, 10], velocity: [1.5, 0.2, 0.1]}
  );
  const mover = player.write(MovingEntity);
  for (let i = 0; i < move.position.length; i++) {
    move.position[i] += mover.velocity[i];
  }
});

class MovingEntity {
  static schema = {
    position: Type.vector(Type.float64, 3),
    velocity: Type.vector(Type.float64, 3)
  };
}

world.build(sys => {
  const player = sys.createEntity(
    MovingEntity, {position: [10, 0, 10], velocity: [1.5, 0.2, 0.1]}
  );
  const mover = player.write(MovingEntity);
  for (let i = 0; i < mover.position.length; i++) {
    move.position[i] += mover.velocity[i];
  }
});

This declares two fields, each a vector of exactly three float64 numbers. A vector's number elements will be stored together compactly by Becsy, and the vector will appear as an array-like object with a length property and indexed accessors for its properties. You can access the elements individually, and you can also assign an array of the correct length to the field, which will get its elements copied into the component. You can even iterate over it with a for..of loop, but be careful: for better performance, a vector has a single iterator that will be reset for everyone each time you start iterating, and the iterator will only work for as long as the vector's entity handle remains valid itself.

Additionally, a vector has an asTypedArray() method that returns a typed array view onto the underlying data, which can be useful with low-level APIs. While this requires an allocation it doesn't actually copy any data around, so it's still pretty light-weight.

For better readability, you can also name the vector's elements and access them that way:

@component class MovingEntity {
  @field.float64.vector(['x', 'y', 'z'])
  declare position: [number, number, number] & {x: number, y: number, z: number};
  @field.float64.vector(['x', 'y', 'z'])
  declare velocity: [number, number, number] & {x: number, y: number, z: number};
}

world.build(sys => {
  const player = sys.createEntity(
    MovingEntity, {position: [10, 0, 10], velocity: {x: 1.5, y: 0.2, z: 0.1}}
  );
  const mover = player.write(MovingEntity);
  mover.position[0] += mover.velocity.x;
  mover.position.x += mover.velocity[1];
  mover.position.z += mover.velocity.z;
});

class MovingEntity {
  static schema = {
    position: Type.vector(Type.float64, ['x', 'y', 'z']),
    velocity: Type.vector(Type.float64, ['x', 'y', 'z'])
  };
}

world.build(sys => {
  const player = sys.createEntity(
    MovingEntity, {position: [10, 0, 10], velocity: {x: 1.5, y: 0.2, z: 0.1}}
  );
  const mover = player.write(MovingEntity);
  mover.position[0] += mover.velocity.x;
  mover.position.x += mover.velocity[1];
  mover.position.z += mover.velocity.z;
});

You can then access the elements interchangeably either by index or by name, and assign either an array or an object to the field, whichever's more convenient.

Finally, you can specify a custom class to use for the array-like value. This can be useful if you're using a library that provides a vector-like abstract data type with useful methods that you'd like to be able to use directly on your Becsy data. It differs from using Type.object because the data is still stored by Becsy in a multithreading-compatible fashion, and fungible instances of the custom class are used as a thin veneer on top. To achieve this, the vector's array-like and named element properties are used to override the class's ones, which works well for simple ADTs but can break the host class in more complex cases — you won't know until you try.

Here's a made-up example that incorporates all of the above:

class Vector3 {
  x: number;
  y: number;
  z: number;

  add(that: Vector3): void {
    this.x += that.x;
    this.y += that.y;
    this.z += that.z;
  }
}

const v3Type = Type.vector(Type.float64, ['x', 'y', 'z'], Vector3);

@component class MovingEntity {
  @field(v3Type) declare position: Vector3;
  @field(v3Type) declare velocity: Vector3;
}

world.build(sys => {
  const player = sys.createEntity(
    MovingEntity, {position: [10, 0, 10], velocity: [1.5, 0.2, 0.1]}
  );
  const mover = player.write(MovingEntity);
  mover.position.add(mover.velocity);
});

class Vector3 {
  x: number;
  y: number;
  z: number;

  add(that: Vector3): void {
    this.x += that.x;
    this.y += that.y;
    this.z += that.z;
  }
}

const v3Type = Type.vector(Type.float64, ['x', 'y', 'z'], Vector3);

class MovingEntity {
  static schema = {
    position: v3Type,
    velocity: v3Type
  };
}

world.build(sys => {
  const player = sys.createEntity(
    MovingEntity, {position: [10, 0, 10], velocity: [1.5, 0.2, 0.1]}
  );
  const mover = player.write(MovingEntity);
  mover.position.add(mover.velocity);
});

Referencing entities #

Applications often need to establish relationships between entities, and Becsy caters for this need directly with Type.ref and Type.backrefs properties.

A Type.ref field holds a reference to any other single entity, or null to indicate that it's empty. It will automatically be nulled out if the target entity is deleted, though its previous value remains accessible via System.accessRecentlyDeletedData until the reference is overwritten or the deleted entity purged.

A Type.backrefs field automatically builds a list of references to the entity on which its component resides. Becsy automatically processes reference changes and entity deletions to keep the list current and it cannot be modified manually. The order of the entities in the list is arbitrary.

A backrefs field can be configured in a few different ways:

• By default, with no parameters, all references to the entity will be included. This is the cheapest option as Becsy needs to maintain such backrefs for itself anyway.
• If you specify a component type then only references from components of that type will be included. This is the most expensive option as Becsy needs to allow for the possibility of multiple ref properties in a component pointing to the same entity.
• If you specify both a component type and the name of a ref field name in that component then only references from that field will be included. This is more expensive than the default of all references but safer, as the backrefs won't pick up any other references that you might add later to your application. It's also cheaper than specifying just a component type.
• Finally, by default you cannot read backrefs properties when operating under System.accessRecentlyDeletedData conditions. If you need to do that then pass an extra flag to the type constructor to track deleted backrefs, but be aware that this will effectively double the cost of the field.

The backrefs field type lets you build 1-N relationships where the N is unbounded. For example, you could model an inventory this way:

@component class Packed {
  @field.ref declare holder: Entity;
}

@component class Inventory {
  @field.backrefs(Packed, 'holder') declare contents: Entity[];
}

world.build(sys => {
  const player = sys.createEntity(Inventory, Health, /* etc */);
  const potion = sys.createEntity(Potion, {healing: 200});
  const sword = sys.createEntity(Sword, {damage: 50});

  // Put both items in the player's inventory
  potion.add(Packed, {holder: player});
  sword.add(Packed, {holder: player});
  player.read(Inventory).contents;  // [potion, sword] in any order

  // Remove the sword from the inventory
  sword.remove(Packed);
  player.read(Inventory).contents;  // [potion]

  // Destroy the potion
  potion.delete();
  player.read(Inventory).contents;  // []
});

class Packed {
  static schema = {
    holder: Type.ref
  };
}

class Inventory {
  static schema = {
    contents: Type.backrefs(Packed, 'holder')
  };
}

world.build(sys => {
  const player = sys.createEntity(Inventory, Health, /* etc */);
  const potion = sys.createEntity(Potion, {healing: 200});
  const sword = sys.createEntity(Sword, {damage: 50});

  // Put both items in the player's inventory
  potion.add(Packed, {holder: player});
  sword.add(Packed, {holder: player});
  player.read(Inventory).contents;  // [potion, sword] in any order

  // Remove the sword from the inventory
  sword.remove(Packed);
  player.read(Inventory).contents;  // [potion]

  // Destroy the potion
  potion.delete();
  player.read(Inventory).contents;  // []
});

To build an N-N relationship you'll need to reify the relationship itself as an entity to provide a level of indirection to the links. Here's an example of a symmetric relationship:

@component class Friendship {
  @field.ref declare a: Entity;
  @field.ref declare b: Entity;
}

@component class Person {
  @field.backrefs(Friendship) declare friendships: Entity[];
}

world.build(sys => {
  const p1 = sys.createEntity(Person);
  const p2 = sys.createEntity(Person);
  const p3 = sys.createEntity(Person);

  // Set up some friendships
  const f1 = sys.createEntity(Friendship, {a: p1, b: p2});
  const f2 = sys.createEntity(Friendship, {a: p1, b: p3});
  p1.read(Person).friendships;  // [f1, f2] in any order
  p1.read(Person).friendships.map(f => f.a === p1 ? f.b : f.a);  // [p2, p3] in any order
})

class Friendship {
  static schema = {
    a: Type.ref,
    b: Type.ref
  };
}

class Person {
  static schema = {
    friendships: Type.backrefs(Friendship)
  };
}


world.build(sys => {
  const p1 = sys.createEntity(Person);
  const p2 = sys.createEntity(Person);
  const p3 = sys.createEntity(Person);

  // Set up some friendships
  const f1 = sys.createEntity(Friendship, {a: p1, b: p2});
  const f2 = sys.createEntity(Friendship, {a: p1, b: p3});
  p1.read(Person).friendships;  // [f1, f2] in any order
  p1.read(Person).friendships.map(f => f.a === p1 ? f.b : f.a);  // [p2, p3] in any order
})

Validating component combos #

In the ECS paradigm every entity can have one component of each type. However, not all component combinations will make sense in your application, and some might have deleterious effects on the systems processing them. While in principle you could "just be careful" to not put together incompatible components that can be hard to do in practice as your application grows.

You can enlist Becsy's help in checking for invalid component combinations by defining a static validate method on any component type. All such validation methods will be called on all entities that had component added or removed by a system, after that system has finished executing. (So even though a validation method is defined on a specific component type for convenience, it can actually validate any components on all entities.)

Here's an example where we want to forbid combining component types B and C together if an entity also has a component of type A:

@component class A {
  static validate(entity: Entity): void {
    if (entity.has(A) && entity.hasAllOf(B, C)) {
      throw new Error('cannot combine both B and C with A');
    }
  }
}

@component class B {}
@component class C {}

world.build(sys => {
  const entity = sys.createEntity(A, B, C);
  // not an error yet -- we could still fix things by removing A, B or C
});
// but once the system finishes an error is thrown

class A {
  static validate(entity: Entity): void {
    if (entity.has(A) && entity.hasAllOf(B, C)) {
      throw new Error('cannot combine both B and C with A');
    }
  }
}

class B {}
class C {}

world.build(sys => {
  const entity = sys.createEntity(A, B, C);
  // not an error yet -- we could still fix things by removing A, B or C
});
// but once the system finishes an error is thrown

A validation method can only check for the presence of components using the "has" family of methods on Entity. It cannot read the entity to access the field values, so your component constraints cannot depend on data values. Validators are also exempt from the system's access entitlements — they can check for the presence or absence of every type of component.

Component enums #

A very common restriction on component combinations is to allow at most one from a list of types to be present on an entity. This is similar to "enums" in many programming languages and is often used to implement state machines. Becsy supports this pattern directly and throws in a few extra features to boot.

You can define an enum and populate it with component types like so:

class A {}
class B {}
class C {}
// Define an enum of component types A, B, and C.
const myEnum = World.defineEnum('myEnum', A, B, C);

const myEnum = World.defineEnum('myEnum');
@component(myEnum) class A {}
@component(myEnum) class B {}
@component(myEnum) class C {}

Any component types can be members of an enum, including ones with data fields. The enum name parameter is optional but will make any error message more useful. Passing the enum or any one of its members into the world's defs will automatically pull in all the rest.

In general, enum components are used just like normal ones, and the enum itself can be used to represent the list of its members in any API that deals with components. The following chapters will also call out enum-specific features in each area.

Storage strategies #

Behind the scenes, rather than putting field values in properties of individual objects, Becsy stores them in contiguous, homogeneous buffers. All the values for field foo of all components of type A are stored in one buffer, all the values for field bar in another, and so on. There are different strategies for allocating and indexing these buffers that offer trade-offs between memory usage and performance. (Note, though, that except for the compact storage strategy, performance differences only show up in the performance build).

You can select a storage strategy per component type by filling in a static options object in the class. For example:

@component class A {
  static options = {
    storage: 'packed',
    capacity: 1000
  }
}

class A {
  static options = {
    storage: 'packed',
    capacity: 1000
  }
}

You can also set a default storage strategy for components that don't specify one by passing defaultComponentStorage to the World.create options. The default default is packed (elastic).

The available strategies are as follows, in order from fastest and most memory hungry to slowest and smallest.

• sparse: This strategy allocates storage for every possible entity up front, indexed directly by entity ID. This is very fast as there's no indirect indexing step but can be extremely wasteful unless all or nearly all entities have a component of the given type. (You cannot specify a capacity or an initialCapacity for this strategy.)

• packed: This strategy allocates storage for a full index lookup table (up to 4 bytes for every possible entity), but uses smaller buffers for the actual field values. If you know the maximum number of components of a given type you can set the value buffers to a fixed size using the capacity option. If you don't know, the strategy defaults to an elastic variant that will grow the buffers as needed (though never shrink them). You can set the initialCapacity of these elastic buffers, but note that they're slower than the fixed size ones even if they never actually get resized.

• compact: This strategy uses both a small index lookup table and smaller value buffers, but accessing a value requires a linear scan of the index so it's only recommended if you have no more than a handful of components of a given type. Like the packed strategy there are both fixed size and elastic variants. This strategy is automatically applied to any component types used as singletons.