Transformations

A transformation turns the player into something else: a bigger hitbox, a different eye height, and usually a completely custom model. Think of the Hulk, a werewolf form or a giant robot suit. Transformations can also lock the player in place while they transform and make them invulnerable during it.

A transformation is made of three parts:

1. The transformation file (server side). It defines how long the transition takes, what happens to the hitbox, and so on.
2. A palladium:transformation ability in a power. As long as the ability is enabled, the player is transformed.
3. The transformation renderer (client side, optional). It defines the model and texture the player turns into.

Because the transformation and its renderer have their own files, several powers can use the same transformation without repeating anything.

---

The Transformation File

Transformations are placed at:

data/<namespace>/palladium/transformation/<id>.json

All fields are optional. An empty file {} is a valid transformation that just switches instantly and changes nothing on the server side, which is fine if you only need the custom model.

Field	Type	Default	Description
transition	Transition	instant	How long transforming and reverting take.
lock_movement	Phase	none	When the player can't walk or jump.
invulnerable	Phase	none	When the player can't take damage. Damage that bypasses invulnerability (like the void) still hits.
dimensions	Dimensions		The hitbox and eye height while transformed.
actions	Actions		Actions that run at the start and end of the transition.

Transition

Field	Type	Default	Description
in_duration	Time	0	How long it takes to transform, like "3s".
out_duration	Time	0	How long it takes to turn back.

If the ability gets enabled again while the player is still turning back, the transition simply turns around and continues from where it was. It doesn't start over.

Phases

lock_movement and invulnerable accept one of these:

Value	Meaning
none	Never.
transforming	Only while transforming.
reverting	Only while turning back.
both	While transforming and while turning back.

Movement is locked by reducing the movement speed and jump strength to zero. The player can still look around.

Dimensions

Sets the size of the hitbox while transformed. The values are in blocks, for a player of normal size.

Field	Type	Default	Description
width	Float		Required. The width of the hitbox when standing.
height	Float		Required. The height of the hitbox when standing.
eye_height	Float	scaled	The eye height when standing. If left out, it is scaled along with the height.
poses	Map<Pose, Size>	{}	Exact sizes for specific poses, with the same width, height and eye_height fields.

For a normal player the standing hitbox is 0.6 wide and 1.8 high, with the eyes at 1.62.

Poses you don't list in poses keep their usual proportions. For example, crouching normally makes a player a bit shorter, so a transformed player crouches by the same amount relative to their new height. The pose names are the vanilla ones: standing, crouching, swimming, fall_flying, sleeping and so on.

The dimensions work together with size changes. If the player is shrunk to half their size with the size system while transformed, the transformed hitbox is halved too.

Actions

Field	Description
on_transform_start	Runs when the player starts transforming.
on_transform_end	Runs when the transformation is complete.
on_revert_start	Runs when the player starts turning back.
on_revert_end	Runs when the player is back to normal.

Each one takes a single action or a list. The actions run for the player, with the transformation ability as the context.

---

The Ability

To actually transform, add a palladium:transformation ability to a power and point it to the transformation:

"transform": {
  "type": "palladium:transformation",
  "transformation": "mypack:hulk",
  "state": {
    "enabling": {
      "type": "palladium:key_bind",
      "behaviour": "toggle"
    }
  }
}

While the ability is enabled, the player is transformed. Once it gets disabled, they turn back. You can use every enabling handler and condition you like, a toggle key, holding a key, a condition like "is in water", and so on.

Multiple Transformations

A player can only be in one transformation at a time. If several transformation abilities are enabled at once, Palladium picks one like this:

1. The power with the highest priority wins. Powers from items come first, then powers from suits, then superpowers.
2. If the priority is the same, for example two abilities in the same power, the one that was enabled last wins.

When the winning transformation changes, the player first turns back from the old one and then transforms into the new one.

---

The Transformation Renderer

The renderer decides what the transformed player looks like. It is placed at:

assets/<namespace>/palladium/transformation_renderers/<id>.json

The ID has to match the transformation's ID. So data/mypack/palladium/transformation/hulk.json is drawn by assets/mypack/palladium/transformation_renderers/hulk.json. A transformation without a renderer still works, the player just keeps their normal look.

Field	Type	Default	Description
model_layer	Skin Typed Value		Required. The model. Can be a different model for wide and slim skins, and can use variables like dynamic models.
texture	Texture (Reference)		Required. The texture of the model. Can be a dynamic texture.
apply_vanilla_movement	Boolean	true	Makes the model walk, swim, crouch, swing its arms and look around like a normal player.
crouch	Boolean or Crouch Settings	true	How the model crouches. Only used with apply_vanilla_movement.
bone_mapping	Map<String, String>	{}	Tells Palladium which bones of your model are the vanilla ones, if they are named differently.
first_person	First Person Settings	the vanilla arm bones	Which bones are shown as arms in first person, and where.
item_bones	Item Bones	the vanilla bones	Which bones held items and helmets are attached to.
enable_hand_items	Boolean	true	Whether held items are shown on the model.
enable_head_item	Boolean	true	Whether helmets and heads are shown on the model.
transition	Transition Visuals		Animations played while transforming and turning back.

While fully transformed, the normal player model and its armor are replaced by your model. Render layers, trails and the name tag still show up. To show a render layer only on the transformed model, give it a transformation field (see render layers).

Crouch Settings

true uses the vanilla crouch, false turns crouching off for the model, for example if you already handle it with your own animations. For a bulky model the vanilla offsets often look off, so you can adjust them:

Field	Default	Description
body_rotation	28.65	How far the body leans forward, in degrees.
arm_rotation	22.92	How far the arms move forward, in degrees.
head_y	4.2	How far the head moves down, in pixels.
body_y	3.2	How far the body moves down, in pixels.
arm_y	3.2	How far the arms move down, in pixels.
leg_z	4	How far the legs move back, in pixels.

First Person Settings

first_person has a right_arm and a left_arm entry, each with these fields:

Field	Type	Default	Description
bone	String	"right_arm" / "left_arm"	The bone shown as this arm. Nested bones work too, like "body.right_arm".
offset	Vector3	[0, 0, 0]	Moves the arm on screen, in pixels.
rotation	Vector3	[0, 0, 0]	Rotates the arm on screen, in degrees.
scale	Float	1	Scales the arm.

Big arms often cover half of the screen in first person. Moving them a bit outwards and down with offset, or making them smaller with scale, fixes that.

Item Bones

Field	Default	Description
right_arm	"right_arm"	The bone right hand items are held in.
left_arm	"left_arm"	The bone left hand items are held in.
head	"head"	The bone helmets and heads are put on.

Transition Visuals

Field	Type	Default	Description
in_animation	Identifier		Animation played while transforming.
out_animation	Identifier		Animation played while turning back.
show_during_transition	Boolean	false	Shows the custom model during the transition already, on top of the normal model.
animation_out_blend	Time	0	How long the animation takes to blend out once the transition is over.

The length of the transition itself is set in the transformation file, not here.

---

Examples

Simple: A Model Swap

A power that swaps the player model for a werewolf with a key press. No transition and no hitbox change.

data/mypack/palladium/transformation/werewolf.json

{}

assets/mypack/palladium/transformation_renderers/werewolf.json

{
  "model_layer": "mypack:werewolf#main",
  "texture": "mypack:textures/entity/werewolf.png"
}

data/mypack/palladium/power/werewolf.json (excerpt)

"abilities": {
  "transform": {
    "type": "palladium:transformation",
    "transformation": "mypack:werewolf",
    "state": {
      "enabling": {
        "type": "palladium:key_bind",
        "behaviour": "toggle"
      }
    }
  }
}

Medium: Hulk With a Transition

A three second transformation. The player is stuck in place and can't be hurt while transforming, and grows into a bigger hitbox. A roar plays once it's done. The big arms are moved out of the way in first person.

data/mypack/palladium/transformation/hulk.json

{
  "transition": {
    "in_duration": "3s",
    "out_duration": "2s"
  },
  "lock_movement": "both",
  "invulnerable": "transforming",
  "dimensions": {
    "width": 0.9,
    "height": 2.4,
    "eye_height": 2.15
  },
  "actions": {
    "on_transform_end": {
      "type": "palladium:run_command",
      "command": "playsound minecraft:entity.ravager.roar player @a ~ ~ ~"
    }
  }
}

assets/mypack/palladium/transformation_renderers/hulk.json

{
  "model_layer": "mypack:hulk#main",
  "texture": "mypack:textures/entity/hulk.png",
  "first_person": {
    "right_arm": { "offset": [2, 1, 0], "scale": 0.8 },
    "left_arm": { "offset": [-2, 1, 0], "scale": 0.8 }
  },
  "transition": {
    "in_animation": "mypack:hulk.transform"
  }
}

Advanced: A Suit That Overrides a Power

The player has a Kryptonian superpower that transforms them into a glowing "solar flare" form while it's toggled on. They also own an armor suit that turns them into a mech while worn. Suits have a higher priority than superpowers, so wearing the suit wins over the solar form, even if the solar form was turned on later. Taking the suit off turns the player back, and since the solar ability is still enabled, they go straight into the solar form again.

The mech doesn't let you crouch like a player, so the model's crouch is turned off, and its bones are named differently than the vanilla ones.

data/mypack/palladium/transformation/mech.json

{
  "transition": {
    "in_duration": "2s",
    "out_duration": "2s"
  },
  "lock_movement": "both",
  "invulnerable": "both",
  "dimensions": {
    "width": 1.4,
    "height": 3.2,
    "eye_height": 2.9,
    "poses": {
      "crouching": { "width": 1.4, "height": 3.2, "eye_height": 2.9 }
    }
  }
}

assets/mypack/palladium/transformation_renderers/mech.json

{
  "model_layer": "mypack:mech#main",
  "texture": "mypack:textures/entity/mech.png",
  "crouch": false,
  "bone_mapping": {
    "body": "torso",
    "right_arm": "torso.right_cannon",
    "left_arm": "torso.left_cannon"
  },
  "item_bones": {
    "right_arm": "torso.right_cannon",
    "left_arm": "torso.left_cannon"
  },
  "first_person": {
    "right_arm": { "bone": "torso.right_cannon", "offset": [4, 2, -2], "rotation": [0, -10, 0] },
    "left_arm": { "bone": "torso.left_cannon", "offset": [-4, 2, -2], "rotation": [0, 10, 0] }
  },
  "enable_head_item": false,
  "transition": {
    "in_animation": "mypack:mech.assemble",
    "out_animation": "mypack:mech.disassemble",
    "animation_out_blend": "10t"
  }
}

data/mypack/palladium/power/mech_suit.json (excerpt, given by the suit set)

"abilities": {
  "mech": {
    "type": "palladium:transformation",
    "transformation": "mypack:mech"
  }
}

data/mypack/palladium/power/kryptonian.json (excerpt)

"abilities": {
  "solar_flare": {
    "type": "palladium:transformation",
    "transformation": "mypack:solar_flare",
    "state": {
      "enabling": {
        "type": "palladium:key_bind",
        "behaviour": "toggle"
      }
    }
  }
}

A render layer that only shows on the mech, like glowing cannon lights:

assets/mypack/palladium/render_layers/mech_lights.json

{
  "transformation": "mypack:mech",
  "model_layer": "mypack:mech#main",
  "texture": "mypack:textures/entity/mech_lights.png",
  "render_type": "palladium:glow"
}