Entity Components

Reading Components

// returns null if entity doesn't have this component
Velocity velocity = store.getComponent(ref, Velocity.getComponentType());

// or ensure it exists (creates default if missing)
Velocity velocity = store.ensureAndGetComponent(ref, Velocity.getComponentType());

Modifying Components

// replace component (or add if missing)
store.putComponent(ref, MyComponent.getComponentType(), new MyComponent(newValue));

// add new component (throws if exists)
store.addComponent(ref, MyComponent.getComponentType(), new MyComponent());

// add with default value
MyComponent comp = store.addComponent(ref, MyComponent.getComponentType());

// remove component (throws if missing)
store.removeComponent(ref, MyComponent.getComponentType());

// remove if exists (no-op if missing)
store.tryRemoveComponent(ref, MyComponent.getComponentType());

Common Components

Component	Purpose
TransformComponent	Position and rotation
Velocity	Movement velocity
HeadRotation	Head/look direction
ModelComponent	Visual model reference
BoundingBox	Collision bounds
UUIDComponent	Unique identifier
DisplayNameComponent	Entity display name
EntityStatMap	Entity stats (health, stamina, mana, etc.)
Invulnerable	Damage immunity flag
Intangible	Collision bypass flag
DespawnComponent	Auto-despawn timer
EffectControllerComponent	Status effects (buffs, debuffs, DoT)

Custom Components

Mods can register their own components via getEntityStoreRegistry(). Components registered with a string ID and BuilderCodec are automatically persisted when the entity is saved. See Storing Data for the full pattern.

ComponentAccessor

ComponentAccessor<EntityStore> is an interface implemented by both Store and CommandBuffer. Many APIs accept it to work in either context.

Implementation	Reads	Writes	Context
Store	Immediate	Immediate	Commands, event handlers, plugin code
CommandBuffer	Immediate	Queued/batched	ECS systems (tick, event systems)

In commands and plugin code, you typically have a Store directly - writes happen immediately.

In ECS systems, you receive a CommandBuffer - writes are queued and applied after all systems complete. This enables safe parallel processing.

// in a command - Store, immediate writes
public void execute(Ref<EntityStore> ref, Store<EntityStore> store, ...) {
    store.addComponent(ref, MyComponent.getComponentType(), component); // happens now
}

// in a system - CommandBuffer, batched writes
public void tick(..., CommandBuffer<EntityStore> buffer, ...) {
    buffer.addComponent(ref, MyComponent.getComponentType(), component); // queued
}