TrackerModifier

Configuration options for tracker behavior

Overview

The TrackerModifier record class defines configuration options for a Tracker. It controls various behaviors such as visibility checks (sight trace), automatic damage animations, and damage tinting effects.

Package: kr.toxicity.model.api.tracker

Since: 1.15.2

Record Components

sightTrace

boolean sightTrace

Whether to perform sight tracing for visibility.

When enabled, the model is only visible to players who have line of sight to it.

Default: true

JSON Name: sight-trace

damageAnimation

boolean damageAnimation

Whether to play automatic damage animations when the entity takes damage.

Default: true

JSON Name: damage-animation

This only applies to EntityTracker. DummyTracker does not use this setting.

damageTint

boolean damageTint

Whether to apply a red tint when the entity is damaged.

Default: true

JSON Name: damage-tint

This only applies to EntityTracker. DummyTracker does not use this setting.

Constants

DEFAULT

public static final TrackerModifier DEFAULT = new TrackerModifier(true, true, true)

The default modifier configuration with all features enabled.

Methods

builder

public static @NotNull Builder builder()

Creates a new builder initialized with default values.

Returns: A new builder

toBuilder

public @NotNull Builder toBuilder()

Creates a new builder initialized with this modifier’s values.

Returns: A new builder

Builder

The TrackerModifier.Builder class provides a fluent API for constructing TrackerModifier instances.

sightTrace

public @NotNull Builder sightTrace(boolean sightTrace)

Sets whether to use sight tracing.

Parameters:

• sightTrace - true to enable sight tracing

Returns: This builder

damageAnimation

public @NotNull Builder damageAnimation(boolean damageAnimation)

Sets whether to enable damage animations.

Parameters:

• damageAnimation - true to enable damage animations

Returns: This builder

damageTint

public @NotNull Builder damageTint(boolean damageTint)

Sets whether to enable damage tinting.

Parameters:

• damageTint - true to enable damage tinting

Returns: This builder

build

public @NotNull TrackerModifier build()

Builds the TrackerModifier.

Returns: The created modifier

Usage Examples

Using Default Settings

import kr.toxicity.model.api.tracker.TrackerModifier;

// Use default (all features enabled)
TrackerModifier modifier = TrackerModifier.DEFAULT;

// Create tracker with default settings
Tracker tracker = api.createEntityTracker(entity, "model_name", TrackerModifier.DEFAULT);

Custom Configuration

// Build custom modifier
TrackerModifier modifier = TrackerModifier.builder()
    .sightTrace(true)           // Enable sight tracing
    .damageAnimation(false)     // Disable automatic damage animations
    .damageTint(true)           // Enable damage tinting
    .build();

Tracker tracker = api.createEntityTracker(entity, "model_name", modifier);

Modifying Existing Configuration

// Start from default and modify
TrackerModifier modifier = TrackerModifier.DEFAULT.toBuilder()
    .sightTrace(false)  // Disable sight tracing only
    .build();

Configuration Profiles

// Profile for boss entities (always visible)
public static final TrackerModifier BOSS_MODIFIER = TrackerModifier.builder()
    .sightTrace(false)          // Always visible, no line-of-sight check
    .damageAnimation(true)      // Show damage animations
    .damageTint(true)           // Show damage tint
    .build();

// Profile for decorative entities
public static final TrackerModifier DECORATION_MODIFIER = TrackerModifier.builder()
    .sightTrace(false)          // Always visible
    .damageAnimation(false)     // No damage animations
    .damageTint(false)          // No damage tint
    .build();

// Profile for stealth entities
public static final TrackerModifier STEALTH_MODIFIER = TrackerModifier.builder()
    .sightTrace(true)           // Requires line of sight
    .damageAnimation(true)      // Show damage animations
    .damageTint(false)          // Hide damage tint (harder to spot when hit)
    .build();

JSON Serialization

// TrackerModifier supports Gson serialization
Gson gson = new Gson();

// Serialize to JSON
TrackerModifier modifier = TrackerModifier.DEFAULT;
String json = gson.toJson(modifier);
// {"sight-trace":true,"damage-animation":true,"damage-tint":true}

// Deserialize from JSON
String json = "{\"sight-trace\":false,\"damage-animation\":true,\"damage-tint\":true}";
TrackerModifier modifier = gson.fromJson(json, TrackerModifier.class);

Configuration Files

# config.yml example
entity-models:
  zombie:
    model: "custom_zombie"
    modifier:
      sight-trace: true
      damage-animation: true
      damage-tint: true
  
  boss:
    model: "boss_model"
    modifier:
      sight-trace: false  # Always visible
      damage-animation: true
      damage-tint: true

// Loading from configuration
public TrackerModifier loadModifier(ConfigurationSection config) {
    return TrackerModifier.builder()
        .sightTrace(config.getBoolean("sight-trace", true))
        .damageAnimation(config.getBoolean("damage-animation", true))
        .damageTint(config.getBoolean("damage-tint", true))
        .build();
}

Feature Details

Sight Trace

When sightTrace is enabled:

• The model checks line of sight from each player’s eye location to the model location
• Players without line of sight will not see the model
• Useful for realistic visibility (models behind walls are hidden)
• Has a small performance cost for the raytrace calculation

When disabled:

• The model is visible to all players within render distance
• Better performance for models that should always be visible
• Recommended for bosses, decorations, and important entities

Damage Animation

When damageAnimation is enabled:

• The tracker automatically plays the “damage” animation when the entity takes damage
• Falls back to “hurt” animation if “damage” is not available
• Animation priority can be configured in the animation file

When disabled:

• No automatic damage animation
• You can still manually trigger animations with tracker.animate("damage")
• Useful when you want custom damage animation logic

Damage Tint

When damageTint is enabled:

• The model is tinted red when the entity takes damage
• Tint color can be customized with EntityTracker.damageTintValue(int)
• Tint duration is 10 tracker ticks (250ms) by default
• Uses TrackerUpdateAction.tint() internally

When disabled:

• No automatic damage tint
• You can still manually apply tints with tracker.update(TrackerUpdateAction.tint(color))
• Useful for custom damage indication logic or when tinting conflicts with other effects

Best Practices

1. Use Profiles: Create reusable modifier profiles for different entity types
2. Performance: Disable sightTrace for models that should always be visible
3. Consistency: Use the same modifier settings for similar entity types
4. Documentation: Document why you disabled certain features in comments
5. Testing: Test with different settings to find the best balance for your use case

See Also

• Tracker - Base tracker class that uses this modifier
• EntityTracker - Entity tracker that uses damage features
• DummyTracker - Dummy tracker (doesn’t use damage features)