Class Tracker

java.lang.Object
kr.toxicity.model.api.tracker.Tracker
All Implemented Interfaces:
AutoCloseable
Direct Known Subclasses:
DummyTracker, EntityTracker
public abstract class Tracker extends Object implements AutoCloseable
Represents the core controller for a specific model instance.

A Tracker manages the lifecycle, rendering, animation, and player interaction of a model. It coordinates with the RenderPipeline to update bone positions and send packets to players.

Since:
1.15.2

  • Field Details

    • TRACKER_TICK_INTERVAL

      public static final int TRACKER_TICK_INTERVAL
      The interval in milliseconds between tracker ticks.
      Since:
      1.15.2
      See Also:

    • MINECRAFT_TICK_MULTIPLIER

      public static final int MINECRAFT_TICK_MULTIPLIER
      The multiplier to convert tracker ticks to Minecraft ticks (50ms).
      Since:
      1.15.2
      See Also:

    • pipeline

      protected final RenderPipeline pipeline

    • modifier

      protected final TrackerModifier modifier

    • rotator

      protected ModelRotator rotator

    • scaler

      protected ModelScaler scaler

  • Constructor Details

    • Tracker

      public Tracker(@NotNull @NotNull RenderPipeline pipeline, @NotNull @NotNull TrackerModifier modifier)
      Creates a new tracker.
      Parameters:
      pipeline - the render pipeline
      modifier - the tracker modifier
      Since:
      1.15.2

  • Method Details

    • isScheduled

      public boolean isScheduled()
      Checks if the tracker's update task is currently scheduled.
      Returns:
      true if scheduled, false otherwise
      Since:
      1.15.2

    • rotation

      @NotNull public @NotNull ModelRotation rotation()
      Returns the current rotation of the model.
      Returns:
      the model rotation
      Since:
      1.15.2

    • rotation

      public final void rotation(@NotNull @NotNull Supplier<ModelRotation> supplier)
      Sets the supplier for the base model rotation.
      Parameters:
      supplier - the rotation supplier
      Since:
      1.15.2

    • rotator

      public final void rotator(@NotNull @NotNull ModelRotator rotator)
      Sets the model rotator strategy.
      Parameters:
      rotator - the rotator strategy
      Since:
      1.15.2

    • scaler

      @NotNull public @NotNull ModelScaler scaler()
      Returns the model scaler.
      Returns:
      the scaler
      Since:
      1.15.2

    • scaler

      public void scaler(@NotNull @NotNull ModelScaler scaler)
      Sets the model scaler.
      Parameters:
      scaler - the new scaler
      Since:
      1.15.2

    • task

      public void task(@NotNull @NotNull Runnable runnable)
      Schedules a task to run on the next tracker tick.
      Parameters:
      runnable - the task to run
      Since:
      1.15.2

    • frame

      public void frame(@NotNull @NotNull Tracker.ScheduledPacketHandler handler)
      Registers a handler to run every frame (tracker tick).
      Parameters:
      handler - the packet handler
      Since:
      1.15.2

    • tick

      public void tick(@NotNull @NotNull Tracker.ScheduledPacketHandler handler)
      Registers a handler to run every Minecraft tick (50ms).
      Parameters:
      handler - the packet handler
      Since:
      1.15.2

    • tick

      public void tick(long tick, @NotNull @NotNull Tracker.ScheduledPacketHandler handler)
      Registers a handler to run every N Minecraft ticks.
      Parameters:
      tick - the interval in Minecraft ticks
      handler - the packet handler
      Since:
      1.15.2

    • perPlayerTick

      public void perPlayerTick(@NotNull @NotNull BiConsumer<Tracker, PlatformPlayer> perPlayerHandler)
      Registers a handler to run every tick for each visible player.
      Parameters:
      perPlayerHandler - the per-player handler
      Since:
      1.15.2

    • schedule

      public void schedule(long period, @NotNull @NotNull Tracker.ScheduledPacketHandler handler)
      Schedules a handler to run periodically.
      Parameters:
      period - the period in tracker ticks
      handler - the packet handler
      Since:
      1.15.2

    • name

      @NotNull public @NotNull String name()
      Returns the name of the model being tracked.
      Returns:
      the model name
      Since:
      1.15.2

    • height

      public double height()
      Calculates the height of the model based on its head bone position.
      Returns:
      the height
      Since:
      1.15.2

    • isClosed

      public boolean isClosed()
      Checks if the tracker has been closed.
      Returns:
      true if closed, false otherwise
      Since:
      1.15.2

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable

    • close

      protected void close(@NotNull @NotNull Tracker.CloseReason reason)

    • despawn

      public void despawn()
      Despawns the model for all players without closing the tracker completely.
      Since:
      1.15.2

    • modifier

      @NotNull public @NotNull TrackerModifier modifier()
      Returns the tracker modifier.
      Returns:
      the modifier
      Since:
      1.15.2

    • pause

      public boolean pause(boolean pause)
      Pauses or resumes the tracker's ticking.
      Parameters:
      pause - true to pause, false to resume
      Returns:
      true if the state changed, false otherwise
      Since:
      1.15.2

    • forceUpdate

      public boolean forceUpdate(boolean force)
      Flags the tracker for a forced update on the next tick.
      Parameters:
      force - true to force update
      Returns:
      true if the state changed
      Since:
      1.15.2

    • spawn

      protected boolean spawn(@NotNull @NotNull PlatformPlayer player, @NotNull @NotNull PacketBundler bundler)
      Spawns the model for a specific player.
      Parameters:
      player - the target player
      bundler - the packet bundler
      Returns:
      true if spawned successfully
      Since:
      1.15.2

    • remove

      public boolean remove(@NotNull @NotNull PlatformPlayer player)
      Removes the model for a specific player.
      Parameters:
      player - the target player
      Returns:
      true if removed successfully
      Since:
      1.15.2

    • playerCount

      public int playerCount()
      Returns the number of players currently viewing the model.
      Returns:
      the player count
      Since:
      1.15.2

    • location

      @NotNull public abstract @NotNull PlatformLocation location()
      Returns the current location of the model.
      Returns:
      the location
      Since:
      1.15.2

    • animate

      public boolean animate(@NotNull @NotNull String animation)
      Plays an animation by name with default settings.
      Parameters:
      animation - the animation name
      Returns:
      true if the animation started
      Since:
      1.15.2

    • animate

      public boolean animate(@NotNull @NotNull String animation, @NotNull @NotNull AnimationModifier modifier)
      Plays an animation by name with a modifier.
      Parameters:
      animation - the animation name
      modifier - the animation modifier
      Returns:
      true if the animation started
      Since:
      1.15.2

    • animate

      public boolean animate(@NotNull @NotNull String animation, @NotNull @NotNull AnimationModifier modifier, @NotNull @NotNull Runnable removeTask)
      Plays an animation by name with a modifier and a completion task.
      Parameters:
      animation - the animation name
      modifier - the animation modifier
      removeTask - the task to run when the animation ends
      Returns:
      true if the animation started
      Since:
      1.15.2

    • animate

      public boolean animate(@NotNull @NotNull BlueprintAnimation animation, @NotNull @NotNull AnimationModifier modifier)
      Plays a blueprint animation with a modifier.
      Parameters:
      animation - the blueprint animation
      modifier - the animation modifier
      Returns:
      true if the animation started
      Since:
      1.15.2

    • animate

      public boolean animate(@NotNull @NotNull TrackerAnimation<?> animation)

    • animate

      public boolean animate(@NotNull @NotNull TrackerAnimation<?> animation, @NotNull @NotNull Runnable removeTask)

    • animate

      public boolean animate(@NotNull @NotNull BlueprintAnimation animation, @NotNull @NotNull AnimationModifier modifier, @NotNull @NotNull Runnable removeTask)
      Plays a blueprint animation on filtered bones.
      Parameters:
      animation - the blueprint animation
      modifier - the animation modifier
      removeTask - the task to run when the animation ends
      Returns:
      true if the animation started
      Since:
      1.15.2

    • stopAnimation

      public boolean stopAnimation(@NotNull @NotNull String animation)
      Stops an animation by name.
      Parameters:
      animation - the animation name
      Returns:
      true if the animation was stopped
      Since:
      1.15.2

    • stopAnimation

      public boolean stopAnimation(@NotNull @NotNull Predicate<RenderedBone> filter, @NotNull @NotNull String animation)
      Stops an animation on filtered bones.
      Parameters:
      filter - the bone filter
      animation - the animation name
      Returns:
      true if the animation was stopped
      Since:
      1.15.2

    • stopAnimation

      public boolean stopAnimation(@NotNull @NotNull Predicate<RenderedBone> filter, @NotNull @NotNull String animation, @Nullable @Nullable PlatformPlayer player)
      Stops an animation on filtered bones for a specific player (optional).
      Parameters:
      filter - the bone filter
      animation - the animation name
      player - the player (can be null)
      Returns:
      true if the animation was stopped
      Since:
      1.15.2

    • replace

      public boolean replace(@NotNull @NotNull String target, @NotNull @NotNull String animation, @NotNull @NotNull AnimationModifier modifier)
      Replaces a running animation on filtered bones.
      Parameters:
      target - the name of the animation to replace
      animation - the name of the new animation
      modifier - the modifier for the new animation
      Returns:
      true if the replacement occurred
      Since:
      1.15.2

    • replace

      public boolean replace(@NotNull @NotNull String target, @NotNull @NotNull BlueprintAnimation animation, @NotNull @NotNull AnimationModifier modifier)
      Replaces a running animation on filtered bones with a blueprint animation.
      Parameters:
      target - the name of the animation to replace
      animation - the new blueprint animation
      modifier - the modifier for the new animation
      Returns:
      true if the replacement occurred
      Since:
      1.15.2

    • listenHitBox

      public void listenHitBox(@NotNull @NotNull BiFunction<RenderedBone, HitBoxListener.Builder, HitBoxListener.Builder> function)
      Registers a hitbox-listener builder hook that is applied when hitboxes are created.

      This delegates to BoneEventDispatcher.handleCreateHitBox(BiFunction) in this tracker's render pipeline event dispatcher. 

      tracker.listenHitBox((bone, builder) -> builder.interact(event -> {
    // custom interaction handling
}));
      Parameters:
      function - the hitbox listener builder transformer
      Since:
      2.1.0

    • listenHitBox

      public <T extends HitBoxEvent> void listenHitBox(@NotNull @NotNull Class<T> eventClass, @NotNull @NotNull Consumer<T> consumer)
      Registers a hitbox event listener for newly created hitboxes.

      This is a convenience wrapper over listenHitBox(BiFunction). 

      tracker.listenHitBox(HitBoxInteractEvent.class, event -> {
    // custom interaction handling
});
      Type Parameters:
      T - event type
      Parameters:
      eventClass - target hitbox event class
      consumer - event consumer
      Since:
      2.1.0

    • createHitBox

      public boolean createHitBox(@NotNull @NotNull BaseEntity entity, @Nullable @Nullable HitBoxListener listener, @NotNull @NotNull BonePredicate predicate)
      Creates a hitbox for bones matching a predicate.
      Parameters:
      entity - the source entity for the hitbox
      listener - the hitbox listener
      predicate - the bone predicate
      Returns:
      true if any hitboxes were created
      Since:
      1.15.2

    • hitbox

      @Nullable public @Nullable HitBox hitbox(@NotNull @NotNull BaseEntity entity, @Nullable @Nullable HitBoxListener listener, @NotNull @NotNull Predicate<RenderedBone> predicate)
      Retrieves or creates a hitbox for a specific bone.
      Parameters:
      entity - the source entity
      listener - the hitbox listener
      predicate - the bone predicate
      Returns:
      the hitbox, or null if not found/created
      Since:
      1.15.2

    • createNametag

      public boolean createNametag(@NotNull @NotNull BonePredicate predicate, @NotNull @NotNull BiConsumer<RenderedBone, ModelNametag> consumer)
      Creates a nametag for bones matching a predicate.
      Parameters:
      predicate - the bone predicate
      consumer - a consumer to configure the nametag
      Returns:
      true if any nametags were created
      Since:
      1.15.2

    • update

      public <T extends TrackerUpdateAction> void update(@NotNull T action)
      Forces an update action on all bones.
      Type Parameters:
      T - the action type
      Parameters:
      action - the update action
      Since:
      1.15.2

    • update

      public <T extends TrackerUpdateAction> void update(@NotNull T action, @NotNull @NotNull Predicate<RenderedBone> predicate)
      Forces an update action on filtered bones.
      Type Parameters:
      T - the action type
      Parameters:
      action - the update action
      predicate - the bone predicate
      Since:
      1.15.2

    • update

      public <T extends TrackerUpdateAction> void update(@NotNull T action, @NotNull @NotNull BonePredicate predicate)
      Forces an update action on filtered bones.
      Type Parameters:
      T - the action type
      Parameters:
      action - the update action
      predicate - the bone predicate
      Since:
      1.15.2

    • tryUpdate

      public boolean tryUpdate(@NotNull @NotNull BiPredicate<RenderedBone, BonePredicate> action, @NotNull @NotNull BonePredicate predicate)
      Tries to apply an update action to bones matching a predicate.
      Parameters:
      action - the update action
      predicate - the bone predicate
      Returns:
      true if any bones were updated
      Since:
      1.15.2

    • bone

      @Nullable public @Nullable RenderedBone bone(@NotNull @NotNull BoneName name)
      Retrieves a bone by name.
      Parameters:
      name - the bone name
      Returns:
      the bone, or null if not found
      Since:
      1.15.2

    • bone

      @Nullable public @Nullable RenderedBone bone(@NotNull @NotNull String name)
      Retrieves a bone by name string.
      Parameters:
      name - the bone name
      Returns:
      the bone, or null if not found
      Since:
      1.15.2

    • bone

      @Nullable public @Nullable RenderedBone bone(@NotNull @NotNull Predicate<RenderedBone> predicate)
      Retrieves the first bone matching a predicate.
      Parameters:
      predicate - the bone predicate
      Returns:
      the bone, or null if not found
      Since:
      1.15.2

    • bones

      @NotNull public @NotNull @Unmodifiable Collection<RenderedBone> bones()
      Returns a collection of all bones in the model.
      Returns:
      the bones
      Since:
      1.15.2

    • displays

      @NotNull public @NotNull Stream<ModelDisplay> displays()
      Returns a stream of all model displays.
      Returns:
      the displays
      Since:
      1.15.2

    • hide

      public boolean hide(@NotNull @NotNull PlatformPlayer player)
      Hides the tracker from a specific player.
      Parameters:
      player - the target player
      Returns:
      true if hidden successfully
      Since:
      1.15.2

    • isHide

      public boolean isHide(@NotNull @NotNull PlatformPlayer player)
      Checks if the tracker is hidden from a specific player.
      Parameters:
      player - the target player
      Returns:
      true if hidden
      Since:
      1.15.2

    • show

      public boolean show(@NotNull @NotNull PlatformPlayer player)
      Shows the tracker to a specific player.
      Parameters:
      player - the target player
      Returns:
      true if shown successfully
      Since:
      1.15.2

    • handleCloseEvent

      public void handleCloseEvent(@NotNull @NotNull BiConsumer<Tracker, Tracker.CloseReason> consumer)
      Registers a handler for the tracker close event.
      Parameters:
      consumer - the handler
      Since:
      1.15.2

    • isSpawned

      public boolean isSpawned(@NotNull @NotNull UUID uuid)
      Checks if the model is spawned for a player (by UUID).
      Parameters:
      uuid - the player UUID
      Returns:
      true if spawned
      Since:
      1.15.2

    • isSpawned

      public boolean isSpawned(@NotNull @NotNull PlatformPlayer player)
      Checks if the model is spawned for a player.
      Parameters:
      player - the player
      Returns:
      true if spawned
      Since:
      1.15.2

    • renderer

      @NotNull public @NotNull ModelRenderer renderer()
      Returns the renderer associated with this tracker.
      Returns:
      the renderer
      Since:
      1.15.2

    • forRemoval

      @Internal public void forRemoval(boolean removal)
      Marks the tracker for removal.
      Parameters:
      removal - true to mark for removal
      Since:
      1.15.2

    • forRemoval

      @Internal public boolean forRemoval()
      Checks if the tracker is marked for removal.
      Returns:
      true if marked for removal
      Since:
      1.15.2

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object