Home

— Main Options —

life_time

Type: Integer | Example: 300 | Positive only

Specifies the lifetime of the particle in ticks (game ticks, where 20 ticks = 1 second).

---

animation_type

Type: String | Example: random_static | Default Value: random

Defines how the particle's textures animate over time.

Possible values:

• "stretch": Plays each texture to fit the life_time.
• "onetime": Plays an animation for the duration of life_time at the speed of animation_speed, and then dies.
• "loop": Loops the animation continuously.
• "random": Chooses a random texture each time for the duration of animation_speed.
• "random_static": Chooses a random texture once when the particle spawns and keeps it static.

---

animation_speed

Type: Double | Example: 1.0 | Default Value: 1.0

Controls the speed of the texture animation. 1.0 is normal speed, 2.0 is twice as fast, 0.5 is half speed. Negative values reverse the animation.

Similar to adjusting the frame rate in animated textures for blocks or items in resource packs.

---

size

Type: Object or Array | Example: {"width": 8, "height": 8} | Default Value: Static size with width/height 8

Defines the size of the particle. Can be static or dynamic.

Static Size:

{
  "width": 8.0,
  "height": 8.0
}

• width and height: Pixel dimensions of the particle.

Dynamic Size:

{
  "sizes": {
    "0": {"width": 4.0, "height": 4.0},
    "50": {"width": 8.0, "height": 8.0},
    "100": {"width": 4.0, "height": 4.0}
  },
  "interpolation": "linear_interpolation"
}

• sizes: An object where keys are percentages of the particle's life (0-100), and values are size objects.
• interpolation: Type of interpolation between sizes. Possible: "linear_interpolation", "smooth_interpolation", etc.

This allows particles to grow, shrink, or change size over time, like scaling animations in resource pack models.

---

textures

Type: Array of Strings | Example: ["inventory_particles:drip/water_drip_0.png"] | Default Value: []

List of texture paths for the particle. These are PNG files in the iparticles atlas.

Textures are cycled based on animation_type. Think of it as defining frames for an animated sprite, similar to how you define multiple layers in item models.

holders

Type: Array of Objects | Example: See below | Default Value: []

List of items that trigger particle spawning. Each holder defines spawn conditions.

Holder Fields:

name

Type: String | Example: "Water Bucket Drip" | Default Value: Auto-generated

Optional name for the holder, used for debugging. Helps identify configurations in logs.

item

Type: String | Example: "minecraft:water_bucket" | Required

Item ID or tag. Use # prefix for tags (e.g., "#minecraft:boats").

This specifies which items in the inventory will spawn these particles, like targeting specific items in recipes or models.

nbt_conditions_match

Type: String | Example: "any" | Default Value: "any"

How to combine NBT conditions: "all" (all must match), "any" (at least one), "none" (none must match).

nbt_conditions

Type: Array of Objects | Example: [{"this_name": "Damage", "this_type": "int", "check_value": ["0"]}] | Default Value: []

Conditions based on item's NBT data. Each object represents an NBT node.

NBT Condition Fields:

• this_name: Name of the NBT tag.
• this_type: Type of the tag (e.g., "int", "string", "list", "compound").
• check_value: Array of strings to check against the tag's value.
• next_match: How to combine nested conditions ("all", "any", "none").
• next: Array of nested conditions.

This allows particles only for enchanted items or damaged tools, similar to conditional models in resource packs.

spawn_area

Type: String | Example: "water_bucket_drip.png" | Default Value: "standard.png"

Path to a PNG mask file in spawn_areas/ that defines where particles can spawn. White pixels allow spawning, black pixels do not.

Like defining emissive areas in block textures, but for particle spawn positions.

spawn_count

Type: Array of Integers | Example: [1, 3] | Default Value: [0, 0]

Range of particle count per spawn event. [min, max].

Controls how many particles appear at once, balancing visual effect with performance.

spawn_frequency

Type: Array of Integers | Example: [20, 80] | Default Value: [0, 0]

Frequency of spawns in ticks. [min, max] interval between spawns.

Determines how often new particles are created, like timing in animated textures.

color

Type: String or Object | Example: "#FF0000" | Default Value: ""

Particle color. Options:

• "": Default color (white).
• "#RRGGBB": Hex color code.
• "nbt": Color from item's NBT.
• "nbt_list": List of colors from NBT.
• Object for advanced color settings (e.g., gradients).

Allows tinting particles, similar to color overlays in entity models.

speed_coefficient

Type: Double | Example: 0.3 | Default Value: 0.0

Multiplier for particle speed. Positive values speed up, negative slow down.

Adjusts overall movement speed without changing physics details.

physics

Type: Object | Example: See structure above | Default Value: Default physics with no movement

Defines particle movement and rotation.

base

Base movement physics.

x_speed, y_speed, angle_speed

Type: Object | Each controls speed in X, Y, or rotation angle.

Each contains:

• impulse: Initial speed range [min, max].
• impulse_bidirectional: If true, impulse can be negative.
• acceleration: Constant acceleration.
• acceleration_bidirectional: If acceleration can be negative.
• max_acceleration: Max acceleration range [min, max].
• max: Max speed range [min, max].
• braking: Deceleration factor.
• turbulence: Random speed variation [min, max].
• cursor_impulse_inherit_coefficient: How much speed inherits from mouse movement.

This simulates realistic physics, like gravity or wind, beyond static vanilla particles.

rotation

Rotation settings for particle and texture.

particle, texture

Type: Object | Controls rotation of the particle body or its texture.

Each contains:

• spawn_angle: Initial rotation range [min, max] in degrees.
• rotate_in_movement_direction: If true, rotates to face movement direction.
• speed: Rotation speed settings (same as base speed).

Allows spinning or directional effects, like rotating items in GUIs.