Component schema

Managing data

Almost all components and attributes follow the same API for managing their data.

Function	Description	Example
set	Ensures the component exists on the entity, then assigns the (optional) data to the component.	ecs.GltfModel.set(world, eid, {schema})
remove	Removes the component from the entity.	ecs.Hidden.remove(world, eid)
reset	Adds, or resets the component to its default state.	ecs.Quaternion.reset(world, eid)
has	Returns true if the component is present on the entity.	ecs.Material.has(world, eid)
get	Returns a read-only reference.	ecs.Scale.get(world, eid).x
mutate	Perform an update to the component within a callback function. Return true to indicate no changes made.	ecs.Position.mutate(world, eid, (cursor) => { cursor.x++ }) ecs.Position.mutate(world, eid, (cursor) => { if (cursor.x > 10) { cursor.x = 10 return false } else { return true // Not mutated } })
cursor	Returns a mutable reference. Cursors are reused so only one cursor for each component can exist at a time.	const position = ecs.Position.cursor(world, eid) position.x = position.x + 1
acquire	Same behavior as cursor, but commit must be called after the cursor is done being used.	const quaternion = ecs.Quaternion.acquire(world, eid) Object.assign(quaternion, newQuaternion)
commit	Called after acquire. An optional third argument determines whether the cursor was mutated or not.	ecs.Quaternion.commit(world, eid) ecs.Quaternion.commit(world, eid, false)
dirty	Mark the entity as having been mutated. Only needed in a specific case where systems are mutating data.	position.x = 2 ecs.Position.dirty(world, eid)

Data types

Component data is stored in a tightly packed format which means we need to declare the schema of every component up front.

The supported types of data are:

Type	Description
ecs.eid	Entity reference
ecs.f32	32-bit floating-point number
ecs.f64	64-bit floating-point number
ecs.i32	32-bit integer
ecs.ui8	8-bit unsigned integer
ecs.ui32	32-bit unsigned integer
ecs.string	String
ecs.boolean	Boolean

It is not currently possible to store dynamically sized objects or lists. This is something we’re still thinking about, and welcome hearing about your use cases.

Example

An example schema might look like:

{
  level: ecs.ui8,
  health: ecs.ui32,
  isFlying: ecs.boolean,
  weaponObject: ecs.eid,
}

This would be surfaced in the Custom Component’s UI as: