DespawnComponent

Schedules automatic entity removal after a specified duration.

Access

DespawnComponent despawn = store.getComponent(ref, DespawnComponent.getComponentType());
Instant despawnTime = despawn.getDespawn();  // when entity will be removed (may be null)

Creating Despawn Timers

Use the static factory methods with a TimeResource:

TimeResource time = store.getResource(TimeResource.getResourceType());

// despawn in seconds (int)
DespawnComponent despawn = DespawnComponent.despawnInSeconds(time, 60);

// despawn in seconds (float for precision)
DespawnComponent despawn = DespawnComponent.despawnInSeconds(time, 30.5f);

// despawn in milliseconds
DespawnComponent despawn = DespawnComponent.despawnInMilliseconds(time, 5000L);

Or create with an explicit Instant:

TimeResource time = store.getResource(TimeResource.getResourceType());
Instant despawnAt = time.getNow().plus(Duration.ofMinutes(2));
DespawnComponent despawn = new DespawnComponent(despawnAt);

Adding to Entities

TimeResource time = store.getResource(TimeResource.getResourceType());

// when spawning via Holder
Holder<EntityStore> holder = EntityStore.REGISTRY.newHolder();
holder.addComponent(DespawnComponent.getComponentType(), DespawnComponent.despawnInSeconds(time, 120));

// on existing entity
store.putComponent(ref, DespawnComponent.getComponentType(), DespawnComponent.despawnInSeconds(time, 60));

Updating Despawn Timer

DespawnComponent despawn = store.getComponent(ref, DespawnComponent.getComponentType());
TimeResource time = store.getResource(TimeResource.getResourceType());

// reset timer to 30 seconds from now
despawn.setDespawnTo(time.getNow(), 30.0f);

// set to specific instant
despawn.setDespawn(time.getNow().plus(Duration.ofMinutes(5)));

Safe Update Helper

Use trySetDespawn to handle entities that may or may not have the component:

DespawnComponent.trySetDespawn(
    commandBuffer,
    timeResource,
    ref,
    store.getComponent(ref, DespawnComponent.getComponentType()),
    60.0f  // new lifetime in seconds, or null to remove
);

Removing Despawn (Make Permanent)

store.tryRemoveComponent(ref, DespawnComponent.getComponentType());

How It Works

The DespawnSystem runs each tick and checks entities with DespawnComponent:

Instant despawnInstant = despawn.getDespawn();
if (timeResource.getNow().isAfter(despawnInstant)) {
    commandBuffer.removeEntity(ref, RemoveReason.REMOVE);
}

Entities with Interactable component (being held/used) are excluded from despawn checks.

Common Use Cases

Entity Type	Typical Lifetime
Dropped items	120 seconds (from ItemEntityConfig.getTtl())
Projectiles (old system)	60 seconds
Projectiles (new system)	300 seconds (5 minutes)
Deployables	Configured via DeployableConfig.getLiveDurationInMillis()

Examples

Temporary Effect Entity

Holder<EntityStore> holder = EntityStore.REGISTRY.newHolder();
// ... add other components ...

TimeResource time = store.getResource(TimeResource.getResourceType());
holder.addComponent(DespawnComponent.getComponentType(), DespawnComponent.despawnInSeconds(time, 10));

store.addEntity(holder, AddReason.SPAWN);

Item Drop with Custom Lifetime

// items use ItemEntityConfig for TTL, but you can override:
DespawnComponent despawn = store.getComponent(itemRef, DespawnComponent.getComponentType());
TimeResource time = store.getResource(TimeResource.getResourceType());
despawn.setDespawnTo(time.getNow(), 300.0f);  // 5 minutes instead of default

Refresh Timer on Interaction

// e.g., reset despawn when item is touched but not picked up
DespawnComponent despawn = store.getComponent(ref, DespawnComponent.getComponentType());
TimeResource time = store.getResource(TimeResource.getResourceType());
despawn.setDespawnTo(time.getNow(), 120.0f);  // reset to 2 minutes

Persistence

The despawn time is stored as an absolute Instant, so it survives save/load correctly. If an entity was supposed to despawn while the server was offline, it will be removed shortly after the world loads.