Spawning & Removal

Spawning Entities

Basic Pattern

1. Create a Holder with required components
2. Add to the world’s EntityStore via addEntity()

// in a command or event handler with access to Store<EntityStore>
Holder<EntityStore> holder = EntityStore.REGISTRY.newHolder();

// transform is required for positioned entities
TransformComponent transform = new TransformComponent(
    new Vector3d(x, y, z),
    new Vector3f(0, yaw, 0)
);
holder.addComponent(TransformComponent.getComponentType(), transform);

// add entity-specific components
holder.addComponent(MyComponent.getComponentType(), new MyComponent());

// spawn it
Ref<EntityStore> ref = store.addEntity(holder, AddReason.SPAWN);
if (ref != null) {
    // entity spawned successfully
}

AddReason Values

Value	Use Case
SPAWN	New entity creation
LOAD	Loading from storage/serialization

Spawning Items

Use ItemComponent.generateItemDrop() for item entities:

Holder<EntityStore> itemHolder = ItemComponent.generateItemDrop(
    componentAccessor,
    itemStack,
    position,
    rotation,
    velocityX, velocityY, velocityZ
);

if (itemHolder != null) {
    Ref<EntityStore> itemRef = componentAccessor.addEntity(itemHolder, AddReason.SPAWN);
}

Or use ItemUtils for dropping from an entity:

// drop item from player/NPC
ItemUtils.dropItem(entityRef, itemStack, componentAccessor);

// throw with velocity
ItemUtils.throwItem(entityRef, itemStack, throwSpeed, componentAccessor);

Removing Entities

Via Entity Reference

Entity entity = EntityUtils.getEntity(ref, store);
if (entity != null) {
    entity.remove(); // fires EntityRemoveEvent
}

Via Store

Holder<EntityStore> holder = store.removeEntity(ref, RemoveReason.REMOVE);

RemoveReason Values

Value	Use Case
REMOVE	Permanent deletion (death, despawn)
UNLOAD	Temporary removal (chunk unload, teleport)

When using UNLOAD, the returned Holder can be re-added later with AddReason.LOAD.