Swimming

This recipe takes you from a few swim and dive clips to a player that swims at the surface, under the water and straight up or down, and dives into a pool from a height. You wire the clips in a compat file, then add sneak tucks, so that sneaking in the air turns the dive into a cannonball or a belly flop. It is for anyone who already has clips (see How to create custom animations) and wants them to play in water.

The clips and settings come from the example pack provided by Crafto, Fluid & Foolish, the Punchy! Moves animation pack used for every Moves demo on this wiki.

Before you start

• Punchy! Moves installed. See Getting started.
• A resource pack with an assets/punchy_moves/animations/ folder and a compat/ folder beside it. How to create custom animations shows how to make the pack, and Punchy! Studio’s New Pack makes one for you.
• The swim and dive clips. The examples use the clip names of the example pack provided by Crafto, so they work as they stand only with that pack on. With your own clips, put your names in.

The clips you need

A swim needs one clip to start with. Three give you a surface swim, an underwater swim and a vertical swim. A dive is an air clip, and everything else about it is optional. These are the clips of the example pack provided by Crafto, with how each one plays. To build the same set yourself, name your clips as in the first column and save them in .animation.json files in assets/punchy_moves/animations/:

Make them the way Walk cycle makes a loop. In Blockbench, set Loop Mode to Loop for the clips that loop. For an air clip, leave it as Play Once (Hold On Last Frame plays the same in the mod): Punchy! Moves plays it once and keeps its last pose while you fall on. In Punchy! Studio, tick Loop for the clips that loop and leave it unticked for an air clip.

How the game picks a swim clip

You swim when you are in water deep enough to swim in and the pack has at least one swim clip. Each moment, one clip plays:

• vertical while you hold the jump key or the sneak key, but not both, so you rise or sink.
• underwater while your head is under the water.
• surface otherwise, with your head above the water.

A clip that is missing is replaced by another, so a pack with only surface still swims everywhere. The swim clip plays faster the faster you swim, plays backward when you swim backward, and slows to a stop when you stop. Wading through shallow water with your head above it is not swimming: that has its own walk_on_water pose, in the compat files reference.

Wire the swim and a plain dive

This compat file plays the three swim clips and a dive. The dive is the dive clip in the air, with the dive_loop clip as a small sway over it, then the dive_loop clip in the water.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "swimming": {
        "surface": "swimming_overwater",
        "underwater": "swimming_underwater",
        "vertical": "swimming_vertical"
      },
      "water_dive": {
        "air": "dive",
        "loop": "dive_loop"
      }
    }
  }
}

Now try it in game.

Video coming soon

What happens in a dive

Knowing the order of events makes every key below easier to place.

• The start. A dive starts when you are in the air and water lies straight below you, with only air between. The drop has to be at least trigger_distance blocks, counting what you have already fallen and what is left to the water. It is 3 by default. The air clip then plays once and holds its last frame while you fall on, and the dive’s loop clip plays over it as a small sway.
• The entry. When you reach the water, a plain dive plays its contact clip if the pack has one, then goes on to loop. A dive with no contact clip keeps its last pose in the water and goes on to loop. The loop clip plays one cycle, or ends sooner when you start to move, rise or sink. The example pack provided by Crafto has no contact clip. The step from the air into the water blends over entry_blend_seconds.
• The hand-over. Once the dive’s clips are done, the swim clip takes over, blended over swim_blend_seconds. A dive with neither a contact clip nor a loop hands over to swimming at once. For the hand-over to happen, the pack needs at least one swim clip.

Add sneak tucks

A tuck changes the dive while you are in the air. Sneak early and you curl into a cannonball. Sneak later and you flop flat for a belly flop. Four keys name the clips, and one sets how early counts as early:

• sneak_air is the cannonball’s air clip, and sneak_loop its loop.
• late_sneak_air is the belly flop’s air clip, and late_sneak_loop its loop.
• sneak_window_seconds is how long after the dive starts a sneak still picks the cannonball. It is 0.3 seconds by default.

Here is the whole file with the tucks of the example pack provided by Crafto. Every number in this file is the default, written out so you can see it: change one only when you want a different feel.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "swimming": {
        "surface": "swimming_overwater",
        "underwater": "swimming_underwater",
        "vertical": "swimming_vertical",
        "surface_body_depth": 0.12,
        "surface_grace_distance": 1.35,
        "vertical_tilt_degrees": 30.8,
        "sprint_playback_multiplier": 1.25
      },
      "water_dive": {
        "air": "dive",
        "loop": "dive_loop",
        "trigger_distance": 3,
        "entry_blend_seconds": 0.45,
        "swim_blend_seconds": 0.6,
        "sneak_air": "cannonball",
        "sneak_loop": "cannonball_loop",
        "late_sneak_air": "belly_flop",
        "late_sneak_loop": "belly_loop",
        "sneak_window_seconds": 0.3
      }
    }
  }
}

Put it in the same compat file as before, in place of the old text. In Blockbench’s route, reload with F3+T. In Studio, press Apply, then export again with Ctrl+E. Then test all three dives from the same platform.

Video coming soon

A few rules decide how tucks behave:

• The first sneak decides. A dive takes one tuck at most. Letting go of the sneak key does not undo it.
• The tuck’s air clip starts when you sneak. The dive’s own clip blends into it, and the tuck’s loop, if it has one, sways over it from then on.
• A tuck plays no contact clip. In the water it keeps the tuck’s last pose and goes on with the tuck’s loop. If the tuck has no loop, you go straight into the swim.
• A missing tuck leaves the plain dive. If the tuck you picked has no air clip, the dive stays the plain dive.
• Every dive starts as the plain dive. With sneak_air or late_sneak_air in the pack, a dive begins with air, and a pack without air plays no dive at all. In a pack with tucks, alternate_air, alternate_loop and alternate_chance are not used.

Keys of swimming

Keys of water_dive

The full list of keys, with the lava dive and walk_on_water, is in the compat files reference.

Things that stop a swim or a dive

• The dive never starts. Check that nothing but air lies between you and the water, down to 48 blocks. A block of any other kind in the way ends the check. Check that the drop is at least trigger_distance, that the pack has an air clip (in a pack without tucks, alternate_air also starts a dive), and that you are not climbing, crawling or flying with elytra or in creative flight.
• No dive after a jump out of the water. A dive needs you to have stood on the ground since you were last in water or lava. Jump out of a pool and drop back in, and you swim straight away.
• A tuck does nothing. The tuck you picked has no air clip. Early sneaks need sneak_air, and late sneaks need late_sneak_air. Give both, or the dive stays plain on the side you left out.
• The dive plays and then nothing swims. The hand-over needs a swim clip. Add surface, underwater or vertical.
• The whole file is ignored. One key the format does not accept makes the game skip the entire file. See Things that drop a whole file, and Why a clip does not play when the file loads but a clip stays silent.

Related pages

• Compat files, the reference for every key.
• Camera and features, where swimming and diving sit among the other moments the camera and body react to.
• Walk cycle, for making a looping clip and wiring it.
• How to create custom animations, for making the clips themselves.