Item physics

Item physics makes what you hold move like it has weight. A lantern sways when you turn, a bucket of water sloshes when you jump, and a charm on a stick keeps swinging after you stop. Punchy! runs a small damped pendulum for the whole item, and for single bones of a model part if you ask for it.

This page is for pack makers. It shows how to make an item swing, what every setting does, how to give one bone its own motion, and how to switch the motion off again.

Before you start

• Punchy! 3.0 or newer, with its F8 menu. Labels and behavior on this page are checked against Punchy! 3.0 for Fabric on Minecraft 26.3.
• Enable Item Physics must be on. It is on by default, in the Physics section of the Items & World tab of the F8 menu. See Settings and controls.
• For the whole item: a compat file in a resource pack. If you have none yet, make one as Resource packs shows, then read Compat rules. The pack from the recipes lists every file of the packs below.
• For single bones: a model part. If you have none yet, start with the Model parts overview.

How the pendulum works

The pendulum is not a rigid body. It is a spring with damping that turns two angles into a rotation around a pivot. One angle swings the item forward and back along your view. The other swings it from side to side.

Several things push on it:

• Turning the camera. Turning left or right kicks the sideways swing. Looking up or down kicks the forward swing. The setting force and the setting cameraSens scale these kicks.
• Where you look. Looking up or down moves the angle where the item comes to rest, up to its limits.
• Walking and sprinting. Steps add sway and a small bob.
• Jumping and landing. Taking off and landing give the item a kick, and so does the up or down speed in between.
• Taking a hit on a shield.
• A clip that starts on the arm. Starting an animation on that arm gives the item a small kick.

The setting motionSens scales the walking, shield and arm jump and landing pushes. The kick when you leave and meet the ground and the push from the up or down speed do not depend on it, apart from how far the up or down speed tilts the rest angle once motionSens is above 0.55. Changing the held item resets the swing.

With a shader pack active, the sideways swing is mirrored and turns around world axes instead of your view. If a swing looks different with your shader on, that is why.

The three modes

Where it applies

The pendulum can act on two things.

• The whole item. You write a physics entry in a compat file, and the whole held item swings around its pivot. The pivot is the small red cube the Hand Editor shows. See Tuning editor.
• Single bones. You write bone_physics in a model part, and each named bone swings around its own pivot, the pivot it has in the geometry file. The rest of the model stays where it is.

Punchy! already gives every lantern a swing. The stock lantern rule is FULL_PENDULUM with limitDeg 55, force 0.1, speed 1, cameraSens 0.25 and gravity 25. Your pack can change it, as the first recipe shows.

Change how a lantern swings

This compat file changes the stock lantern swing for every lantern, soul lantern and copper lantern. It gives the swing a smaller limit, a bigger kick and a longer sway. Copy it, then use the reference below to change the feel.

Punchy! reads compat files again on every reload, so you can edit the file and press F3+T again to try new values.

{
  "item": {
    "LANTERN": {
      "physics": {
        "name": "FULL_PENDULUM",
        "limitDeg": 40.0,
        "force": 0.4,
        "speed": 6.0,
        "cameraSens": 0.25,
        "gravity": 20.0,
        "motionSens": 0.3
      }
    }
  }
}

Your file wins over Punchy!‘s own stock rule because pack files sit above it. The settings you write replace the stock ones as a set, so a setting you leave out uses the default in the table below, not the stock lantern value.

Write it with the Bindings workspace

The Bindings workspace of Punchy! Studio writes the same file and checks it as you go.

Settings of a physics entry

A physics entry can be a mode name alone, an object, or a list. A name alone, such as "physics": "FORWARD_PENDULUM", sets the mode. On an itemSpecific entry without transforms, the item keeps the settings its kind already had. On a kind group that has poses, such as the stock lantern, the settings fall back to the defaults in the table below. A list uses the first entry that has a name.

The names are written in camelCase exactly as in the table. A name in snake case, such as limit_deg, is not read here. Bone physics, further down, reads both spellings.

No other value is limited. Numbers may be any decimal. A limit is in degrees.

What to change for which feel

A kind group changes only the poses that name no mode. The stock lantern poses name FULL_PENDULUM, so to change the mode of a lantern, write it in itemSpecific.<item id>.physics.

Limits have two special cases. A limit of 0 on one side takes the limit of the other side. A limit of 0 on both sides holds the swing still.

Where a physics entry can go

Compat rules explains which rule wins when several apply.

Hand space

By default the pendulum swings in hand space. It turns the item first, and your item’s rotation and offset from transforms sit inside that swing. Set handSpace to false and Punchy! applies the rotation first, then swings the item. The offset still sits inside the swing.

{
  "item": {
    "LANTERN": {
      "physics": { "name": "FULL_PENDULUM", "handSpace": false }
    }
  }
}

If an item you turned a lot swings along a tilted line, try handSpace false and compare. Neither value is better in general. handSpace is a setting of the item as a whole. Bone physics does not have it.

A mode for each hand

A pose can name its own mode, so the two hands swing differently. The pose holds the mode as text.

{
  "itemSpecific": {
    "minecraft:end_rod": {
      "transforms": {
        "right": { "scale": 1.0, "offY": -0.05, "physics": "FULL_PENDULUM" },
        "left": { "scale": 1.0, "offY": -0.05, "physics": "FORWARD_PENDULUM" }
      }
    }
  }
}

• In an item entry of a kind group, and in an itemSpecific entry, a pose that names a mode keeps it. A pose without one takes the mode of the entry’s physics, if the entry has any.
• In those two kinds of entry, the settings of the entry’s physics object go to the sides that use the same mode as the entry. A side that names another mode runs with the defaults.
• For a custom group, the group’s physics replaces the mode that a pose names, and its settings go to both hands.
• A pose without scale draws at size 0 and the item vanishes. Give every side a scale.
• The physics of a pose is text. An object there drops the whole compat file.
• An unknown mode name in a pose counts as NONE.

Physics on single bones

A model part can make single bones swing, squash or tilt, while the rest of the model stays still. You write bone_physics in the definition. Each key is a bone name from the geometry file. Each value is a spec.

{
  "bone_physics": {
    "lantern": {
      "pendulum_mode": "full",
      "limit_deg": 35,
      "gravity": 22
    }
  }
}

This block sits in the model part definition, next to its other keys. A bone swings around its own pivot in the geometry. Put the pivot where the bone hangs from, such as the hook of a lantern. A pivot at [0, 0, 0] swings the bone around the model’s origin.

• The value can be one object of bones, or a list of such objects.
• When two specs name the same bone, a percent that is not 100 wins, a mode that is not NONE wins, and the later spec’s written settings replace the earlier ones. The creature and slime switches are on if either spec turns them on.
• A spec is kept only when it has a pendulum mode, enableCreaturePhysics or enableSlimePhysics. Limits alone, or percents alone, are dropped.
• The bone names must match the geometry exactly, including the letter case.
• Bones below a swinging bone move with it. Give a child its own spec to add a second swing on top.
• Bone physics also works from a compat file: bone_physics (or bonePhysics) inside an itemSpecific entry is merged over the definition’s. See Compat rules.
• A bone with physics is never camera transparent. See Definitions.

The next two sections give the keys. The definition page also lists them in Physics keys.

Keys of a bone spec

The pendulum keys mean the same as in a physics object, with the same defaults. Here they accept snake case, camelCase and a longer form with the word pendulum.

Any pendulum setting you write turns the bone’s settings into an explicit set. Settings you leave out use the defaults above.

Creature and slime feedback

These two effects react to the player’s jumps and falls. They are meant for things that live inside an item, such as a fish in a bucket or a slime in a jar.

Creature feedback

enableCreaturePhysics on a bone gives it the pose of a fish in a bucket: it tilts, rolls and shifts as you walk, jump, fall, land and turn the camera. Four percentages shape it. Each runs from 0 to 100, and 100 means no change. A value above 100 counts as 100, so a percentage can only calm the effect down.

{
  "bone_physics": {
    "fish": {
      "enableCreaturePhysics": true,
      "impactInclinationPercent": 60,
      "fallInclinationPercent": 80,
      "impactTranslationPercent": 30,
      "fallTranslationPercent": 45
    }
  }
}

Two shapes of geometry get this without extra keys:

• A model with a bone fish and a pair of fins (right_fin and left_fin, or fin_right and fin_left) moves its fish bone and the bones under it like a pufferfish in a bucket.
• A model shaped like an axolotl, with a head bone, a body or body_root bone and a legs_front or leg1 bone, plays the axolotl pose when the definition has physicsFeedback set to true.

{
  "physicsFeedback": true
}

physicsFeedback (also fallingFeedBack and fallingFeedback) belongs at the root of the definition. It does nothing for other shapes. To change which axolotl texture shows, read Dynamic textures.

Slime squash

enableSlimePhysics on a bone squashes and stretches it like jelly. It stretches while you fall, squashes when you take off, and squashes and springs back when you land. Two percentages shape it. Each runs from 0 to 100, and 100 means no change.

A held slime ball or slime block wobbles by itself, with no keys at all. Enable Item Physics switches that off.

Creature buckets

When a resource pack gives an axolotl, tropical fish, pufferfish, cod, salmon or tadpole bucket its own item model, Punchy! animates the creature layer of that model. The layer is the part whose texture lives under item/ and has the creature’s name in it. Set enableCreaturePhysics to false in the physics object of the item to keep the creature still. The object needs a valid name, and NONE is enough.

{
  "itemSpecific": {
    "minecraft:axolotl_bucket": {
      "physics": { "name": "NONE", "enableCreaturePhysics": false }
    }
  }
}

Recipe: a lantern that swings from a staff

A staff with a lantern that hangs from a crook and swings when you turn and walk. The staff itself stays rigid. It uses the blaze rod and textures that ship with Minecraft, so you need no image.

The definition makes the bone lantern swing. The pivot of that bone in the geometry, [4, 15, 0], is the point where the lantern hangs from the crook.

{
  "items": ["minecraft:blaze_rod"],
  "geo": "mypack:punchy/model_parts_items/geo/lantern_staff.geo.json",
  "texture": "minecraft:block/oak_planks",
  "bone_textures": { "lantern": "minecraft:block/glowstone" },
  "bone_physics": {
    "lantern": {
      "pendulum_mode": "full",
      "limit_deg": 35,
      "force": 0.9,
      "speed": 4,
      "gravity": 22,
      "motion_sens": 0.5
    }
  }
}

{
  "format_version": "1.12.0",
  "minecraft:geometry": [
    {
      "description": {
        "identifier": "geometry.lantern_staff",
        "texture_width": 16,
        "texture_height": 16
      },
      "bones": [
        {
          "name": "staff",
          "pivot": [0, 0, 0],
          "cubes": [
            {
              "origin": [-0.5, 0, -0.5],
              "size": [1, 16, 1],
              "uv": { "north": { "uv": [0, 0], "uv_size": [4, 4] }, "south": { "uv": [0, 0], "uv_size": [4, 4] }, "east": { "uv": [0, 0], "uv_size": [4, 4] }, "west": { "uv": [0, 0], "uv_size": [4, 4] }, "up": { "uv": [0, 0], "uv_size": [4, 4] }, "down": { "uv": [0, 0], "uv_size": [4, 4] } }
            },
            {
              "origin": [0, 15, -0.5],
              "size": [5, 1, 1],
              "uv": { "north": { "uv": [0, 0], "uv_size": [4, 4] }, "south": { "uv": [0, 0], "uv_size": [4, 4] }, "east": { "uv": [0, 0], "uv_size": [4, 4] }, "west": { "uv": [0, 0], "uv_size": [4, 4] }, "up": { "uv": [0, 0], "uv_size": [4, 4] }, "down": { "uv": [0, 0], "uv_size": [4, 4] } }
            }
          ]
        },
        {
          "name": "lantern",
          "parent": "staff",
          "pivot": [4, 15, 0],
          "cubes": [
            {
              "origin": [3.5, 14, -0.5],
              "size": [1, 1, 1],
              "uv": { "north": { "uv": [0, 0], "uv_size": [4, 4] }, "south": { "uv": [0, 0], "uv_size": [4, 4] }, "east": { "uv": [0, 0], "uv_size": [4, 4] }, "west": { "uv": [0, 0], "uv_size": [4, 4] }, "up": { "uv": [0, 0], "uv_size": [4, 4] }, "down": { "uv": [0, 0], "uv_size": [4, 4] } }
            },
            {
              "origin": [1.5, 8, -2.5],
              "size": [5, 6, 5],
              "uv": { "north": { "uv": [0, 0], "uv_size": [4, 4] }, "south": { "uv": [0, 0], "uv_size": [4, 4] }, "east": { "uv": [0, 0], "uv_size": [4, 4] }, "west": { "uv": [0, 0], "uv_size": [4, 4] }, "up": { "uv": [0, 0], "uv_size": [4, 4] }, "down": { "uv": [0, 0], "uv_size": [4, 4] } }
            }
          ]
        }
      ]
    }
  ]
}

The settings are examples. Raise limit_deg for a wider swing, and lower speed to calm it faster. Geometry and textures explains the geometry format.

Set it with the Model workspace

The Model workspace of Punchy! Studio sets the same thing with fields and shows a test rig.

A preset button in the Presets section fills the fields for you if you would rather start from one.

Studio’s stage does not simulate the pendulum of the whole item. Hold the item in the game, with the live link on, to judge that one.

Recipe: a sloshing bucket

A water bucket whose water tilts when you turn, wobbles when you walk, and squashes when you land. The bucket body stays still. The geometry below is a plain stand-in, so you need no image: it uses textures that ship with Minecraft. Bring your own bucket model instead if you have one. Only the bone names and the pivot of the water matter.

{
  "items": ["minecraft:water_bucket"],
  "geo": "mypack:punchy/model_parts_items/geo/slosh_bucket.geo.json",
  "texture": "minecraft:block/iron_block",
  "bone_textures": { "water": "minecraft:block/light_blue_concrete" },
  "bone_physics": {
    "water": {
      "pendulum_mode": "full",
      "limit_deg": 14,
      "force": 1.4,
      "speed": 3,
      "gravity": 30,
      "motion_sens": 0.6,
      "enableSlimePhysics": true,
      "slimeImpactPercent": 50,
      "slimeFallPercent": 40
    }
  }
}

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

The pivot [0, 4, 0] sits at the foot of the water, so the water tilts and squashes around its base. Move it up to the middle of the liquid if you want it to rock around its centre. To build a full bucket pack with models, clips and conditions, follow the bucket pack tutorial.

The pack from the recipes

The three recipes above fill one resource pack. This is every file of it, with the folders as the recipes use them. Nothing in it needs an image, because every model part uses a texture that ships with Minecraft. The name of the pack folder is yours to choose.

Item physics recipes/
  pack.mcmeta
  assets/
    minecraft/
      punchy/
        compat/
          lantern_swing.json
    mypack/
      punchy/
        model_parts_items/
          definitions/
            lantern_staff.json
            slosh_bucket.json
          geo/
            lantern_staff.geo.json
            slosh_bucket.geo.json

Put Item physics recipes in your resourcepacks folder and save this as pack.mcmeta. The numbers are for Minecraft 26.3. Resource packs has the other versions.

{
  "pack": {
    "description": "Item physics recipes",
    "pack_format": 97,
    "min_format": 97,
    "max_format": 97
  }
}

Bone physics presets

The Physics tab of the Model workspace in Punchy! Studio has six presets. Pressing one writes its settings into the selected bone. The values are plain bone physics keys, so you can type them by hand too.

Rope Link writes the values of the first link of a rope, and Fishing Line writes the values of the base of a line. Item Pendulum Default uses the same numbers as the defaults of the game. Here is Charm Chain as it lands in a definition:

{
  "bone_physics": {
    "charm": {
      "pendulum_mode": "full",
      "limit_deg": 30,
      "force": 10.3,
      "speed": 1,
      "camera_sens": 0.004,
      "gravity": 100,
      "motion_sens": 0.15
    }
  }
}

For a run of bones that hang one from the next, such as a rope or a chain, select the first bone of the run and press Build Rope Chain, Build Fishing Line or Build Charm Chain. Studio gives that bone and each single child below it its own pendulum, and blends the settings from the first link to the last.

• Build Rope Chain goes from the Rope Link first link (limit 32, force 5.5, speed 1.35, camera sensitivity 0.003, gravity 45, motion sensitivity 0.11) to the last link (limit 13, force 1.8, speed 1.1, camera sensitivity 0.003, gravity 35, motion sensitivity 0.06).
• Build Fishing Line goes from the base (above) to the tip (limit 48, force 1.5, speed 0.52, camera sensitivity 0.0019, gravity 138, motion sensitivity 0.33).
• Build Charm Chain gives every link the Charm Chain numbers.

The Bindings workspace has a Bone Physics panel for a single item. Add Bone starts a new bone with the Item Pendulum Default preset so that Punchy! keeps it. The chain builders are in the Model workspace only.

Turn physics off

• Everywhere. Switch off Enable Item Physics in the Physics section of the Items & World tab of the F8 menu. The pendulums stop, and so does the slime wobble of a held slime ball or slime block.

• For an item. Set itemSpecific.<item id>.physics to NONE.

• For a kind group. item.<GROUP>.physics set to NONE changes only the poses that name no mode. The stock lantern poses name FULL_PENDULUM, so use itemSpecific for lanterns.

• For single bones. List them in disable_physics_bones. Bones named there, and the bones below them, ignore the swing of the whole item. Bone physics written for them still works. The alias disable_pendulum_bones is read when disable_physics_bones is missing.

  {
    "disable_physics_bones": ["handle", "frame", "cap"]
  }

• For single bones while a clip plays. An animation entry in modelPartsAnimation can carry its own disable_physics_bones. While that entry plays, its list replaces the definition’s list, even when the list is empty. See Definitions and Item clips.

• While an animation plays. The timeline tokens disable_pendulum and disable_pendulum_physics fade the swing of the item on the arm that plays the clip out and back in. See Animation reference.

Things that stop a swing

• A mode that is not spelled out. In a compat file the mode must be NONE, FULL_PENDULUM or FORWARD_PENDULUM. The short words full and forward work only in bone physics. In a physics entry of a group or an item, any other name makes Punchy! ignore the whole entry.
• Settings without a name. A physics object with limits but no valid name does nothing.
• Snake case in a compat file. limit_deg and the other snake case names are not read in a physics object. Use limitDeg.
• A pose without physics. If you write transforms in an itemSpecific entry for an item that normally swings, such as a lantern, write physics next to them, or that item stops swinging. In an item group entry, the group’s physics fills a pose that has none.
• Enchantment variants. An entry of enchantment_variants reads only its particle lists. A physics or bone_physics key inside a variant is not read.
• An object in a pose. A pose takes the mode as text. An object in the physics of a pose drops the whole compat file, with no message.
• A bone spec without a mode. Limits and percentages alone are dropped. Add pendulum_mode, enableCreaturePhysics or enableSlimePhysics.
• A wrong bone name. Bone names are case sensitive, and a name that is not in the geometry does nothing.
• A pivot at the origin. A bone with pivot [0, 0, 0] swings around the model’s origin and can seem to fly off. Put the pivot where the bone hangs.
• Cubes without per-face UVs. A model made only of short uv cubes draws without physics. Give each cube a uv object with its faces, as in the recipes above.
• A reload not done. Press F3+T after every change.
• Physics switched off. If nothing moves at all, check Enable Item Physics first.

Other problems with a pack are collected on Troubleshooting.

Related pages

• Model parts overview for the model that physics acts on.
• Definitions for bone_physics next to every other definition key.
• Compat rules for where physics and bone_physics go and which rule wins.
• Tuning editor for the pivot of an item.
• Settings and controls for Enable Item Physics.
• Punchy! Studio for the Physics tab and the Bindings workspace.
• Flags reference for every key in one list.