Skip to main content

Component schema

Managing data

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

FunctionDescriptionExample
setEnsures the component exists on the entity, then assigns the (optional) data to the component.ecs.GltfModel.set(world, eid, {schema})
removeRemoves the component from the entity.ecs.Hidden.remove(world, eid)
resetAdds, or resets the component to its default state.ecs.Quaternion.reset(world, eid)
hasReturns true if the component is present on the entity.ecs.Material.has(world, eid)
getReturns a read-only reference.ecs.Scale.get(world, eid).x
mutatePerform 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 } })
cursorReturns 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
acquireSame 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)
commitCalled 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)
dirtyMark 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:

TypeDescription
ecs.eidEntity reference
ecs.f3232-bit floating-point number
ecs.f6464-bit floating-point number
ecs.i3232-bit integer
ecs.ui88-bit unsigned integer
ecs.ui3232-bit unsigned integer
ecs.stringString
ecs.booleanBoolean

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:

CustomComponentSchema