Conditions

A model part can change what it plays depending on where the player is. Put a condition on an entry and Punchy! plays that entry’s clip only while the world matches: a flame that goes out under water, a lantern that flickers in the rain, glows at night or warms up beside a campfire. This page is for pack makers who already have a model part with an idle clip.

You will write one lantern with eight idle entries, see how Punchy! picks between them, set the same thing up in Punchy! Studio, and test every condition without leaving your desk.

Before you start

• You need a lantern model with item clips. The model and its texture are given below, so you can start from nothing. Model part definitions builds the same lantern, and Item clips explains how an entry plays a clip. Any model with a bone named lantern and a bone named flame works as it is. With other bone names, change them in the clip file below.
• You need Punchy! 3.0 or newer, from Modrinth or CurseForge. This page was checked against Punchy! 3.0 for Fabric on Minecraft 26.3.
• You need a resource pack, and it must be on. Resource packs shows how to make one and turn it on.
• The Studio steps need Punchy! Studio from Modrinth or CurseForge.

Make a lantern that reacts to the world

Every condition is a key inside a modelPartsAnimation entry. An entry plays only when all of its conditions pass. When several entries pass, the most specific one wins. First the files, then a short walk through the world to see them work.

The model and the texture

The definition below names a model and a texture. If you already built the lantern on Model part definitions, you have both and can skip this part. Otherwise make them here.

The model has two bones, lantern and its child flame. Save it as assets/minecraft/punchy/model_parts_items/geo/lantern.geo.json.

{
  "format_version": "1.12.0",
  "minecraft:geometry": [
    {
      "description": { "identifier": "geometry.lantern", "texture_width": 16, "texture_height": 16 },
      "bones": [
        {
          "name": "lantern",
          "pivot": [0, 0, 0],
          "cubes": [
            {
              "origin": [-3, 0, -3],
              "size": [6, 6, 6],
              "uv": {
                "north": { "uv": [0, 0], "uv_size": [16, 16] },
                "south": { "uv": [0, 0], "uv_size": [16, 16] },
                "east": { "uv": [0, 0], "uv_size": [16, 16] },
                "west": { "uv": [0, 0], "uv_size": [16, 16] },
                "up": { "uv": [0, 0], "uv_size": [16, 16] },
                "down": { "uv": [0, 0], "uv_size": [16, 16] }
              }
            }
          ]
        },
        {
          "name": "flame",
          "parent": "lantern",
          "pivot": [0, 6, 0],
          "cubes": [
            {
              "origin": [-1, 6, -1],
              "size": [2, 3, 2],
              "uv": {
                "north": { "uv": [0, 0], "uv_size": [16, 16] },
                "south": { "uv": [0, 0], "uv_size": [16, 16] },
                "east": { "uv": [0, 0], "uv_size": [16, 16] },
                "west": { "uv": [0, 0], "uv_size": [16, 16] },
                "up": { "uv": [0, 0], "uv_size": [16, 16] },
                "down": { "uv": [0, 0], "uv_size": [16, 16] }
              }
            }
          ]
        }
      ]
    }
  ]
}

The texture is a 16 by 16 PNG. Make a new 16 by 16 image in any paint program, fill it orange and save it as assets/minecraft/punchy/model_parts_items/textures/lantern.png. Every face of the model shows the whole image, so a flat color is enough, and the lantern and the flame share it.

The clip file

Eight clips, one for each entry. Save this as assets/minecraft/punchy/model_parts_items/animations/lantern_states.animation.json.

{
  "format_version": "1.8.0",
  "animations": {
    "lantern_sway": {
      "loop": true,
      "animation_length": 2,
      "bones": {
        "lantern": { "rotation": { "0": [0, 0, -3], "1": [0, 0, 3], "2": [0, 0, -3] } }
      }
    },
    "lantern_rain": {
      "loop": true,
      "animation_length": 1,
      "bones": {
        "lantern": { "rotation": { "0": [0, 0, -6], "0.5": [0, 0, 6], "1": [0, 0, -6] } }
      }
    },
    "lantern_night": {
      "loop": true,
      "animation_length": 2,
      "bones": {
        "flame": { "scale": { "0": [1, 1, 1], "1": [1.3, 1.3, 1.3], "2": [1, 1, 1] } }
      }
    },
    "lantern_storm_night": {
      "loop": true,
      "animation_length": 1,
      "bones": {
        "lantern": { "rotation": { "0": [0, 0, -8], "0.5": [0, 0, 8], "1": [0, 0, -8] } },
        "flame": { "scale": { "0": [1, 1, 1], "0.5": [1.4, 1.4, 1.4], "1": [1, 1, 1] } }
      }
    },
    "lantern_warm": {
      "loop": true,
      "animation_length": 2,
      "bones": {
        "flame": { "scale": { "0": [1.2, 1.2, 1.2], "1": [1.5, 1.5, 1.5], "2": [1.2, 1.2, 1.2] } }
      }
    },
    "lantern_murk": {
      "loop": true,
      "animation_length": 3,
      "bones": {
        "flame": { "scale": { "0": [1, 1, 1], "1.5": [0.8, 0.8, 0.8], "3": [1, 1, 1] } }
      }
    },
    "lantern_wet": {
      "loop": true,
      "animation_length": 2,
      "bones": {
        "lantern": { "rotation": { "0": [0, 0, -2], "1": [0, 0, 2], "2": [0, 0, -2] } },
        "flame": { "scale": { "0": [0.6, 0.6, 0.6], "1": [0.45, 0.45, 0.45], "2": [0.6, 0.6, 0.6] } }
      }
    },
    "lantern_still": {
      "loop": true,
      "animation_length": 1,
      "bones": {
        "lantern": { "rotation": [0, 0, 0] },
        "flame": { "scale": [0.1, 0.1, 0.1] }
      }
    }
  }
}

The definition

Save this as definitions/lantern.json in the same model_parts_items folder, in place of the lantern definition from Model part definitions. Punchy! uses only the first unnamed definition that covers an item (a definition that matches by customName or name wins over unnamed ones, whatever their order), so do not leave two lantern definitions side by side.

{
  "items": ["minecraft:lantern", "minecraft:soul_lantern"],
  "geo": "minecraft:punchy/model_parts_items/geo/lantern.geo.json",
  "texture": "minecraft:punchy/model_parts_items/textures/lantern",
  "animations": [
    "minecraft:punchy/model_parts_items/animations/lantern_states.animation.json"
  ],
  "modelPartsAnimation": [
    { "type": "idle", "animation": "lantern_sway" },
    {
      "type": "idle",
      "animation": "lantern_rain",
      "weather_detection": { "raining": true }
    },
    {
      "type": "idle",
      "animation": "lantern_night",
      "time_detection": { "min": 13000, "max": 23000 }
    },
    {
      "type": "idle",
      "animation": "lantern_storm_night",
      "weather_detection": { "raining": true },
      "time_detection": { "min": 13000, "max": 23000 }
    },
    {
      "type": "idle",
      "animation": "lantern_warm",
      "block_detection": {
        "blocks": ["minecraft:campfire", "minecraft:soul_campfire"],
        "radius": 3
      }
    },
    {
      "type": "idle",
      "animation": "lantern_murk",
      "biome_detection": { "biomes": ["minecraft:swamp", "minecraft:mangrove_swamp"] }
    },
    { "type": "idle", "animation": "lantern_wet", "in_water": true },
    {
      "type": "idle",
      "animation": "lantern_still",
      "inside_water": true,
      "disable_all_particles": true,
      "skip_blend_in": true,
      "skip_blend_out": true
    }
  ],
  "particles": [
    { "type": "minecraft:smoke", "bone": "flame", "rate": 3 }
  ]
}

All eight entries have "type": "idle". The first one has no condition. It is the plain idle, and it plays whenever no other entry passes. Each of the others adds one or two conditions:

The points decide which entry wins when several pass. Which entry plays explains them.

Put them in a pack

The pack holds these four files:

assets/minecraft/punchy/model_parts_items/
  definitions/lantern.json
  geo/lantern.geo.json
  textures/lantern.png
  animations/lantern_states.animation.json

Set the conditions in Punchy! Studio

Studio writes the same keys. The Animation tab has one row for each of the six conditions.

Set them on an entry

Text that is not valid JSON is refused with an error, and the row keeps its old value.

Test them without travelling

The Environment tab sets what Punchy! sees, and only that: the biome, the weather, the time of day, water, blocks around you, freezing and burning. Your world, its physics and its looks do not change. The overrides end when you leave the Model workspace.

These lines assume that the real world is clear and it is daytime, that you stand out of water, that you are outside a swamp and that no campfire is within 3 blocks. If a campfire is near, walk away from it first. For the rest, set Weather to Clear, Time of Day to 1000, Touching Water to No and Biome to minecraft:plains right after you open the Environment tab in step 1, and again after step 6, because Clear Overrides removes them.

The Biome field takes a biome id such as minecraft:swamp, and Punchy! then sees that biome everywhere around you. With the live link on, the hand in the camera view shows Punchy!‘s own reaction. The list does not model the short grace times described in Switching between entries, so in the game a condition can hold a moment longer than the list shows.

The checks

An entry can carry any of six condition keys. All of them must pass. Each one also counts for points when Punchy! ranks the entries.

Water

Two keys ask about water. They are not the same check.

• inside_water asks about your eyes. It is true while your eyes are under water. It is worth 3 points.
• in_water asks about your body. It is true when you are in water, when your eyes are under water, and when water touches your body anywhere from your feet to your chest. Punchy! looks at 27 points around you for that, so standing in a one block puddle or in a thin layer of flowing water counts. It is worth 2 points.

false means the opposite. "in_water": false passes only while you are dry. An entry with "in_water": true and "inside_water": false plays when you wade or swim with your head above the surface.

inside_water: true keeps passing for a very short moment, a tick or two, after your eyes leave the water. in_water has no such delay.

Use inside_water for the under water look of a model, and in_water for wading and the surface.

{ "type": "idle", "animation": "lantern_wet", "in_water": true }

Weather

weather_detection holds up to three flags.

• raining is true while it rains. A thunderstorm counts as rain.
• thundering is true during a thunderstorm.
• clear is true when it is neither raining nor thundering.

{ "type": "idle", "animation": "lantern_rain", "weather_detection": { "raining": true } }

The check follows the weather of the world, not the weather where you stand. It is true in a desert while it rains, in a snowy biome while it snows and under a roof. "raining": true keeps passing for a second or two after the game stops seeing rain, and the rain itself fades out slowly once the weather clears.

To tell a thunderstorm from plain rain, write the thundering entry above the raining entry. In a storm both pass with the same points, and the one higher in the file wins.

Time of day

time_detection compares the day clock with a window. The clock is the Overworld’s, counted in ticks from 0 to 23999.

{ "type": "idle", "animation": "lantern_night", "time_detection": { "min": 13000, "max": 23000 } }

Both ends are included. range is a shorter way to write the same window, and it replaces min and max when it has two values:

{ "type": "idle", "animation": "lantern_night", "time_detection": { "range": [13000, 23000] } }

A missing end is open. "min": 13000 alone means from 13000 to the end of the day. "max": 6000 alone means from the start of the day to 6000. When min is higher than max, the window runs through the turn of the clock from 23999 to 0, which is sunrise. { "min": 22000, "max": 2000 } covers the hours around sunrise. A time_detection with no ends at all passes at every hour.

A block nearby

block_detection looks at blocks around you. Punchy! starts from the block your feet are in and moves the start by offsetX, offsetY and offsetZ. "offsetY": -1 is the block you stand on. "offsetY": 1 is the block your head is in.

With a radius above 0, Punchy! looks at every block in a cube that reaches that far in every direction from the start, and the check passes if any of them matches.

{
  "type": "idle",
  "animation": "lantern_warm",
  "block_detection": {
    "blocks": ["minecraft:campfire", "minecraft:soul_campfire"],
    "radius": 3
  }
}

• List block ids in blocks, or one id in block. block is read only when blocks is empty or missing.
• A leading # makes the entry a tag: "block": "#minecraft:campfires" matches every block in that tag. An id with no : gets the minecraft namespace.
• Water is the block minecraft:water. A block that only holds water, such as a waterlogged slab, is its own block and does not match it.
• The cube grows quickly: radius 1 looks at 27 blocks, radius 2 at 125, radius 3 at 343 and radius 5 at 1331. Punchy! repeats the check every tick, so keep the radius as small as the effect needs.

A biome

biome_detection has the same shape as block_detection, with biome and biomes in place of block and blocks. It reads the biome at the start point and, with a radius, in the cube around it.

{
  "type": "idle",
  "animation": "lantern_murk",
  "biome_detection": { "biomes": ["minecraft:swamp", "minecraft:mangrove_swamp"] }
}

A tag matches every biome in it. These vanilla tags are handy:

A biome from a data pack or a mod is written with its own namespace. A particle emitter can also be limited to biomes with its own trigger_biomes token, covered on Particles.

Several checks on one entry

Write the checks side by side. They all must pass, and their points add up. The entry lantern_storm_night in the example asks for rain and for the night window:

{
  "type": "idle",
  "animation": "lantern_storm_night",
  "weather_detection": { "raining": true },
  "time_detection": { "min": 13000, "max": 23000 }
}

It has 2 points, so it beats both the rain entry and the night entry on a rainy night.

Which entry plays

Punchy! asks for a moment on every game tick. For an idle clip the moment is idle. It goes through the list like this:

1. It keeps the entries of that type whose items filter fits the stack and whose conditions all pass right now.
2. Every condition an entry writes is worth points. inside_water is worth 3, in_water 2, and each of block_detection, weather_detection, time_detection and biome_detection 1.
3. Any entry with points beats every entry without. Among the entries with points, the highest total wins.
4. Equal totals go to the entry that comes first in the file. Entries with no conditions also go by file order.

The points count what is written, not how strict it is. "in_water": false is worth 2 and an empty "weather_detection": {} is worth 1. Points only rank the entries that pass. An entry that fails never plays, whatever it is worth.

Here is what the lantern plays in different places, using the entries in their file order:

The campfire row is a tie. Both entries have 1 point, and lantern_night is higher in the file, so the campfire loses. To make the campfire win, move the lantern_warm entry above lantern_night. To make a combination win, give it its own entry with both conditions, as lantern_storm_night does.

One definition can cover several items. Add "items": ["minecraft:soul_lantern"] to an entry to limit it to that item. Punchy! checks the filter before it counts points.

Always keep one plain idle. With no entry that passes and no plain entry, the model stays in its rest pose.

Conditions on other moments

Conditions work on every type, not just idle. Here an attack plays a different clip while you touch water (only the modelPartsAnimation list of the definition is shown):

{
  "modelPartsAnimation": [
    { "type": "attack", "animation": "lantern_swing" },
    { "type": "attack", "animation": "lantern_swing_wet", "in_water": true }
  ]
}

The two clips are yours to make. When no entry of the asked moment passes, Punchy! plays the matching idle entry instead. A clip that was started by an entry with conditions stops being played once those conditions stop passing. Punchy! then hands over to the idle that fits the world now, or, when there is none, lets the model blend out over a second. Item clips lists the moments.

Switching between entries

When the world changes, Punchy! switches to the entry that now wins. You decide how it looks.

• A blend. The change from one idle to another blends over 0.6 seconds. The flame eases from one state to the next.
• A cut. "skip_blend_in": true on the entry you switch to cuts the change, and so does "skip_blend_out": true on the entry you switch from. Either one is enough. lantern_still has both, so the flame snaps to an ember the moment your head goes under and snaps back as it comes up, after a short grace.
• From weather to water. When an entry with weather_detection is playing and the next one asks for in_water: true or inside_water: true, Punchy! always cuts at once.
• Grace times. A rain entry keeps passing for a second or two after the game stops seeing rain, and an entry with "inside_water": true for a moment after you leave the water. An entry with keep_looping also holds on briefly when its conditions flicker, except entries with a weather condition. The rain and water graces apply only to entries that ask for true.
• Blending from the current pose. On entries that are not idle, blend_from_current_origin (also written blendFromCurrentOrigin, rebase_blend_in or rebaseBlendIn) set to true makes the clip blend in from the pose the arm holds at that moment. Idle entries already blend in that way, and skip_blend_in still cuts instead on either kind.
• An intro and a loop. keep_looping names a clip that loops after the entry’s own clip ends, while the entry still passes. Item clips shows it with an under water entry.
• Particles and physics. disable_all_particles silences every emitter while the entry plays, and disable_physics_bones lists bones that ignore the item’s physics. Both follow the entry that wins. Neither is a condition.

Condition keys

These keys go inside an entry, next to type and the clip name. Item clips lists the other keys of an entry.

An id with no : gets the minecraft namespace. A leading # makes it a tag.

Things that fail without a message

Punchy! does not report these. The Lint panel in Studio’s Definition tab catches the first one.

• A value of the wrong kind drops the whole definition. A text where a list belongs ("blocks": "minecraft:lava"), or a list where a single value belongs ("in_water": [true], "biome": ["minecraft:desert"], "radius": [2]), makes Punchy! throw the file away. The lantern then draws as a plain lantern. Entries that are not objects are skipped, and the rest are kept.
• A misspelled key inside an entry is ignored. "weather_detecion" is not a condition, so the entry has no condition at all. It becomes a plain idle, and if it sits above your real plain idle, it wins every time.
• A misspelled key inside a condition object is ignored too, and the check passes. "weather_detection": { "rain": true } has no raining flag. It passes in every kind of weather and still earns its point.
• A check with nothing to check passes. "blocks": [], a biome_detection with no targets and a time_detection with no ends pass every time. They still earn their point.
• An id that does not exist never matches. A typo in minecraft:soul_campfre makes the entry wait forever. A tag written without its #, such as minecraft:logs, is read as a block called logs, which does not exist.
• Whole numbers only. min, max, radius and the offsets are integers. Write 13000, not 13000.5, which drops the whole definition.

Why my entry does not play

• A better entry wins. Another entry passes with more points, or with the same points higher in the file. Studio’s Specificity line and What Reacts Now list show it. See Which entry plays.
• The rain entry plays in the wrong place. The rain check reads the weather of the world. It is true in a desert during rain and under a roof. To limit a rain entry to some biomes, add a biome_detection to the same entry.
• The time never matches. Check the window against the table in Time of day. Night is 13000 to 23000, and the clock counts from sunrise at 0, not from midnight.
• The campfire is outside the cube. The cube is centered on the block your feet are in, moved by the offsets. A campfire 4 blocks away needs "radius": 4. Studio’s Add Virtual Block lets you test the offset without building anything.
• The water entry never wins. It is a type: "in_water" entry with no condition keys, written below a plain idle. Give it "type": "idle" and "in_water": true instead.
• The water entry replaces the plain idle everywhere. It is a type: "in_water" entry with no condition keys, written above your plain idle. Give it "type": "idle" and "in_water": true instead.
• The swim pose still plays. disable_swim_animation is not a condition. Any entry with it whose items filter fits the stack stops the swim pose on that hand, whatever the world is doing.
• The clip is picked but nothing moves. The clip name is wrong, or the clip does not loop. See Why my clip does not play.
• I changed the file and nothing happened. Reload with F3+T. A file with a missing comma is dropped as a whole.

Related pages

• Model parts overview for how the parts fit together.
• Model part definitions for the items, geometry and texture an entry belongs to.
• Item clips for the clip files, the moments and keep_looping.
• Particles for emitters that react to biomes and clips.
• Dynamic textures to change a texture by what the item holds.
• Torch pack tutorial for a flame that goes out under water.
• Bucket pack tutorial for a model that changes with the water around it.
• Punchy! Studio for the Model workspace.