VolatileEntities

VolatileEntities es un marco basado en ECS para Hytale que te permite crear y gestionar entidades no persistentes o controladas por tiempo, sin dejar “basura” en el mundo.

Está diseñado para:

• dar un control detallado sobre la vida útil de la entidad (distancia, tiempo de espera, desconexión del propietario, etc.),
• limpiar automáticamente las entidades al reiniciar el servidor,
• e incluso asegurar la limpieza después de desinstalar tu plugin.

Características clave

Persistencia no automática al reiniciar

Cualquier entidad con un VolatileComponent se elimina automáticamente en el primer tick después de un reinicio del servidor, gracias a:

• la bandera expiredOnLoad manejada por el códec del componente (VolatileComponent.CODEC),
• y el VolatileTickSystem que elimina las entidades volátiles “cargadas desde el disco”.

Esto garantiza que las entidades volátiles nunca sobrevivan a un reinicio, incluso si fueron guardadas en el disco.

TTL flexible en tiempo de ejecución (mientras el plugin está en ejecución)

Usando VolatileConfig y VolatilePolicy, puedes controlar con precisión cuánto tiempo debe vivir una entidad en tiempo de ejecución:

• IDLE_TIMEOUT – despawn después de X ticks o segundos de actividad,
• MAX_DISTANCE – despawn cuando esté demasiado lejos de una entidad vinculada,
• LINKED_ENTITY_INVALID – despawn si la entidad vinculada se vuelve inválida,
• CUSTOM – lógica de despawn completamente personalizada a través de un predicado en VolatileContext.

Todos estos se evalúan por VolatileTickSystem mientras tu plugin está cargado.

Combinación de políticas

Las políticas son no exclusivas.

Una sola entidad volátil puede combinar múltiples políticas al mismo tiempo. La entidad será eliminada tan pronto como cualquier condición de política se cumpla.

Por ejemplo, una entidad puede:

• despawn después de 10 segundos de inactividad (IDLE_TIMEOUT),
• O despawn si se mueve demasiado lejos de un objetivo (MAX_DISTANCE),
• O ser eliminada cuando su propietario se desconecta (OWNER_DISCONNECT).

Esto te permite expresar ciclos de vida complejos sin código personalizado.

VolatileEntities.builder()
    .withinDistance(targetRef, 30f)
    .idleTimeoutSeconds(10f)
    .ownedBy(playerUuid)
    .spawn(commandBuffer);

Combinando políticas volátiles (Ejemplo)

Este ejemplo demuestra cómo varias reglas de VolatilePolicy pueden combinarse dentro de un solo VolatileConfig.

Las políticas son no exclusivas: una entidad puede tener varias reglas de ciclo de vida aplicadas al mismo tiempo.

La entidad será eliminada tan pronto como cualquier condición de política se cumpla.

Ejemplo: Entidad vinculada a un chunk vinculada a otra entidad

VolatileConfig.VolatileConfigBuilder configBuilder = VolatileConfig.builder()
        // Eliminar automáticamente la entidad cuando su chunk se descargue
        .policy(VolatilePolicy.CHUNK_UNLOAD)

        // Eliminar inmediatamente tan pronto como una condición de política se vuelva inválida
        .removeOnInvalid(true);

// Opcionalmente vincula esta entidad volátil a otra (por ejemplo, un mob o NPC)
if (linkedEntity != null) {
        configBuilder
        .policy(VolatilePolicy.LINKED_ENTITY_INVALID)
        .linkedEntity(linkedEntity);
}

VolatileConfig config = configBuilder.build();
return new VolatileComponent(config);

TTL absoluto usando DespawnComponent de Hytale (seguro para descarga/carga de chunk)

VolatileEntities se integra limpiamente con los sistemas de Hytale vanilla:

• DespawnComponent + DespawnSystem manejan TTL absoluto en tiempo real,
• la política USE_DESPAWN_TTL le dice a VolatileEntities que delegue completamente el manejo de TTL a DespawnComponent.

Esto significa:

• TTL se basa en tiempo real (TimeResource), no en ticks,
• descargas / recargas de chunk son seguras,
• si el tiempo de despawn ya está en el pasado cuando el chunk se recarga, la entidad se elimina inmediatamente.

Por lo tanto, puedes elegir entre:

• TTL en tiempo de ejecución, solo en línea (IDLE_TIMEOUT), o
• TTL absoluto que continúa contando incluso mientras está descargado (USE_DESPAWN_TTL + DespawnComponent).

Limpieza después de desinstalar el plugin

Para resolver el clásico problema de “entidades dejadas atrás después de eliminar un mod”, VolatileEntities utiliza un patrón de mantener vivo:

• VolatileDespawnKeepAliveSystem actualiza continuamente un DespawnComponent vanilla en entidades volátiles (excepto aquellas que usan USE_DESPAWN_TTL),
• mientras tu plugin esté instalado, la fecha límite de despawn se empuja constantemente hacia adelante,
• una vez que tu plugin es eliminado, la última fecha límite de despawn eventualmente se alcanza.

En ese momento, el núcleo de Hytale DespawnSystem limpia automáticamente todas las entidades volátiles restantes, incluso si tu plugin ya no está presente.

Sin escaneos manuales del mundo. Sin entidades huérfanas.

Políticas avanzadas

Además de las políticas de TTL básicas, el marco admite:

• CHUNK_UNLOAD – elimina automáticamente entidades volátiles cuando su chunk se descarga (manejadas por VolatileChunkUnloadSystem, un EntityEventSystem<ChunkUnloadEvent>).

• OWNER_DISCONNECT – marca o elimina entidades volátiles propiedad de un jugador cuando se desconectan (manejadas por VolatileOwnerDisconnectListener, escuchando PlayerDisconnectEvent).

Combinadas, estas políticas forman un robusto conjunto de herramientas de ciclo de vida para entidades temporales.

Casos de uso típicos

Usa VolatileEntities para marcar:

• hologramas,
• proyectiles,
• efectos visuales,
• NPCs temporales,
• entidades de ayuda o marcador

como volátiles, para que:

• despawn en reinicio,
• opcionalmente sigan reglas de tiempo de ejecución (tiempo de espera, distancia, propiedad, lógica personalizada),
• y aún se garantice su limpieza después de la desinstalación del plugin.

Ejemplos de uso

1) Marcar una entidad existente como volátil (solo reinicio)

Si ya generas una entidad manualmente (por ejemplo, un holograma), puedes simplemente adjuntar un VolatileComponent para hacerla no persistente.

holder.addComponent(
    VolatileComponent.getComponentType(),
    VolatileComponent.restartOnly()
);

Resultado:

• la entidad vive mientras el servidor esté en funcionamiento,
• se elimina en el primer tick después de un reinicio,
• la limpieza de seguridad de desinstalación aún se aplica.

2) TTL absoluto (10 segundos en tiempo real)

Para despawn una entidad después de una cantidad fija de tiempo real, incluso a través de descargas de chunk, combina DespawnComponent con USE_DESPAWN_TTL:

holder.addComponent(
    DespawnComponent.getComponentType(),
    DespawnComponent.despawnInSeconds(time, 10f)
);

VolatileConfig cfg = VolatileConfig.builder()
    .policy(VolatilePolicy.USE_DESPAWN_TTL)
    .build();

holder.addComponent(
    VolatileComponent.getComponentType(),
    new VolatileComponent(cfg)
);

Aquí:

• Hytale maneja el TTL por sí mismo,
• VolatileEntities no actualiza el tiempo de despawn,
• la limpieza de reinicio y desinstalación aún está garantizada.

3) Marcar una entidad ya existente como volátil

Puedes marcar una entidad como volátil después de que ya exista:

store.putComponent(
    ref,
    VolatileComponent.getComponentType(),
    VolatileComponent.restartOnly()
);

No se requiere lógica de respawn o despawn manual.

Referencia API (Resumen rápido)

VolatileComponent – métodos de fábrica

• restartOnly() – solo en tiempo de ejecución, eliminado al reiniciar
• withTimeout(int ticks) / withTimeoutSeconds(float seconds, int tickRate)
• withinDistance(Ref<EntityStore> target, float distance)
• linkedTo(Ref<EntityStore> target)
• ownedBy(UUID playerUuid)
• useDespawnTtl()

VolatileConfig

Presets y constructores para control avanzado:

• chunkBound()
• linkedTo(ref)
• withinDistance(ref, distance)
• ownedBy(playerUuid)
• withTimeout(ticks)
• useDespawnTtl()
• custom(ctx -> { ... })

VolatileEntities.builder()

Para conveniencia, la API de constructor proporciona una forma fluida de generar entidades volátiles:

VolatileEntities.builder()
    .at(new Vector3d(x, y, z))
    .with(MyComponent.TYPE, new MyComponent(...))
    .withinDistance(targetRef, 50f)
    .idleTimeoutSeconds(10f)
    .spawn(commandBuffer);

Instalación

Coloca el VolatileEntities JAR en la carpeta de plugins de tu servidor.

Declara una dependencia en el manifiesto de tu plugin:

{
  "Group": "Ender_Griefeur99",
  "Name": "MyPlugin",
  "Version": "1.0.0",
  "Main": "fr.ender_griefeur99.myplugin.MyPlugin",
  "ServerVersion": "*",
  "IncludesAssetPack": false,
  "Dependencies": {
    "Ender_Griefeur99:VolatileEntities": "*"
  }
}