Skip to content
Creray edited this page Nov 15, 2026 · 6 revisions

Tracks & Track Controllers

A Track provides normalized progress for an animation.

A Track Controller determines the track's target progress, while the track itself transitions towards that target. The track's duration specifies the number of ticks required to transition from progress 0 to 1.

Tracks are defined in the tracks array of a Mode.

🎞️ Tracks

Each track contains the following fields:

Field Type Description
id String The unique identifier of the track within the mode.
duration Float The number of ticks required for the track to transition from 0 to 1.
controller TrackController The controller responsible for determining the track's target progress.

An animation references a track using its track_id field. The animation uses the track's progress to determine which sprite to display.

A track's progress is normalized, ranging from 0 to 1. The controller determines its target progress, while the track itself handles the transition towards that value.

The duration specifies the number of ticks required for the track to transition from 0 to 1.

🏷️ Controller types

Targeted provides two types of track controllers:

  • Simple controllers — predefined controllers that can be referenced directly by their identifier.
  • Typed controllers — controllers that require additional configuration.

✨ Simple controllers

A simple controller is specified using its resource identifier:

{
  "id": "transition",
  "duration": 3,
  "controller": "targeted:transition_progress"
}

Targeted includes the following built-in simple controllers:

Controller Description
targeted:transition_progress Controls the track's progress when the mode is enabled or disabled.
targeted:health_percent Sets the track's progress according to the targeted living entity's health percentage.

targeted:transition_progress

This controller animates a track when its mode becomes active or inactive.

  • When the mode is enabled, the track progresses from 0 to 1.
  • When the mode is disabled, the track progresses from its current value back to 0.

This is useful for animations that should play when a crosshair mode appears or disappears.

targeted:health_percent

This controller sets the track's target progress to the targeted living entity's health percentage.

For example, an entity with 75% health will cause the track to move towards 0.75.

This is useful for health indicators and other animations that represent an entity's health.

⚙️ Typed controllers

Unlike simple controllers, typed controllers require an object containing a type field and any additional configuration fields.

targeted:block_property

This controller sets the track's progress according to the value of a block state property.

It requires two fields:

Field Type Description
block Block The identifier of the block to check.
property Property The name of the block state property to read.

The property value is converted into normalized progress based on its position among the property's possible values.

Example:

{
  "id": "block_state",
  "duration": 5,
  "controller": {
    "type": "targeted:block_property",
    "block": "minecraft:oak_log",
    "property": "axis"
  }
}

In this example, the track's progress is determined by the axis property of the targeted oak log.

The controller only updates the track when the targeted block matches the configured block.

targeted:delayed

This controller wraps another Track Controller, delaying its enable and disable operations by a configurable number of ticks.

It is useful when you want a crosshair animation to wait before starting or stopping.

Field Type Description
enable Int? Delay before enabling the wrapped controller, in ticks. Defaults to 0.
disable Int? Delay before disabling the wrapped controller, in ticks. Defaults to 0.
controller TrackController The controller to wrap.

Both enable and disable accept values from 0 to 1000.

Example:

{
  "id": "transition",
  "duration": 3,
  "controller": {
    "type": "targeted:delayed",
    "enable": 10,
    "disable": 5,
    "controller": "targeted:transition_progress"
  }
}

In this example:

  • The track waits 10 ticks before enabling its transition controller.
  • When disabled, it waits 5 ticks before disabling the wrapped controller.
  • The wrapped transition_progress controller continues updating the track during these delays.

See Creating Custom Modes for the overall mode structure and Rules, Triggers & Conditions for activating modes.

Clone this wiki locally