Interface VirtualEntityManager


public interface VirtualEntityManager
Manages virtual (client-side only) entities that possess server-side AI.

Virtual entities in Pulse are unique because they are backed by real NMS entities. This means they support:

  • Pathfinding and Navigation
  • Physics and Gravity
  • Standard Bukkit Events (Damage, Interact)
  • Metadata updates (Equipment, Names)
However, they are modified to be visible only to the target player and are strictly excluded from world saving logic.
  • Method Details

    • spawnEntity

      @NotNull <T extends Entity> T spawnEntity(@NotNull @NotNull Location location, @NotNull @NotNull Class<T> clazz)
      Spawns a virtual entity with native AI.

      The returned entity is a standard Bukkit entity proxy. You can use standard Bukkit API methods (e.g., entity.setCustomName()) to modify it.

      Note: This entity will NOT be saved to the disk. It will vanish on server restart or when the player disconnects.

      Type Parameters:
      T - The entity type.
      Parameters:
      location - The spawn location.
      clazz - The class of the entity to spawn (e.g. Zombie.class).
      Returns:
      The spawned Bukkit entity, visible only to this player.
    • isVirtualEntity

      boolean isVirtualEntity(@NotNull @NotNull Entity entity)
      Checks if the specified Bukkit entity is a virtual entity managed by Pulse.

      Use this in EventHandlers to distinguish between real mobs and per-player phantoms.

      Parameters:
      entity - The entity to check.
      Returns:
      true if the entity is virtual and owned by this player.
    • getEntities

      Gets a collection of all active virtual entities for this player.
      Returns:
      A collection of entities.
    • clearAll

      void clearAll()
      Removes all virtual entities belonging to this player.

      This is automatically called when the player quits to prevent memory leaks.

    • addViewers

      void addViewers(@NotNull @NotNull Entity entity, @NotNull @NotNull Player... players)
      Adds players to the viewers list of this virtual entity. They will instantly start seeing the entity and colliding with it.
    • removeViewers

      void removeViewers(@NotNull @NotNull Entity entity, @NotNull @NotNull Player... players)
      Removes players from the viewers list.

      Auto-Cleanup: If the viewers list becomes empty after removal, the virtual entity is automatically destroyed and removed from the world.

    • setViewers

      void setViewers(@NotNull @NotNull Entity entity, @NotNull @NotNull Player... players)
      Replaces the current viewers list with a new one.
    • getViewers

      Gets a list of UUIDs of all players currently seeing this entity.