Ability State Handlers

State handlers control the lifecycle of an ability. They are set on the state field of an ability definition inside a power JSON.

"state": {
  "unlocking": { ... },
  "enabling":  { ... }
}

Both fields are optional. Omitting unlocking means the ability is always unlocked; omitting enabling means the ability is always enabled.

Each field accepts one of two forms:

• A typed handler object (using the type field): handlers like palladium:key_bind or the buyable variants.
• A list of Conditions: automatically wrapped into a palladium:conditional handler. A list is treated as AND (all must pass).

You cannot combine multiple handlers together; if you need complex logic, use the condition system instead.

---

Unlocking Handlers

Unlocking determines whether the player has access to the ability at all. A locked ability is displayed with a "lock" icon and cannot be enabled.

Condition shorthand

Passing a list of conditions directly is a shorthand for palladium:conditional. This covers the majority of unlocking use cases.

"unlocking": [
  { "type": "palladium:has_effect", "effect": "minecraft:strength" },
  { "type": "palladium:crouching" }
]

---

palladium:conditional

Unlocks the ability automatically when a condition is fulfilled.

Field	Type	Default	Description
conditions	Condition(s)	—	Required. The condition(s) that must be true for the ability to be unlocked.

"unlocking": {
  "type": "palladium:conditional",
  "conditions": { "type": "palladium:has_effect", "effect": "minecraft:strength" }
}

"unlocking": {
  "type": "palladium:conditional",
  "conditions": [
    { "type": "palladium:has_effect", "effect": "minecraft:strength" },
    { "type": "palladium:crouching" }
  ]
}

---

palladium:experience_level_buyable

The ability starts locked. The player must click it in the power screen and spend XP levels to unlock it permanently.

Field	Type	Default	Description
xp_level	Integer	—	Required. Number of XP levels consumed on purchase.
requires	Condition(s)	—	Optional additional conditions. Once unlocked/purchased, these conditions need to be fulfilled for the ability to be unlocked.

"unlocking": {
  "type": "palladium:experience_level_buyable",
  "xp_level": 5,
  "requires": [
    { "type": "palladium:has_effect", "effect": "minecraft:strength" },
    { "type": "palladium:crouching" }
  ]
}

---

palladium:item_buyable

The ability starts locked. The player must click it in the power screen and have the required items in their inventory, which are consumed on purchase.

Field	Type	Default	Description
ingredient	Ingredient	—	Required. Item(s) accepted as payment. Supports vanilla ingredient system.
amount	Positive Integer	1	Number of items consumed.
requires	Condition(s)	—	Optional additional conditions. Once unlocked/purchased, these conditions need to be fulfilled for the ability to be unlocked.

"unlocking": {
  "type": "palladium:item_buyable",
  "ingredient": "minecraft:diamond",
  "amount": 3
}

"unlocking": {
  "type": "palladium:item_buyable",
  "ingredient": "#minecraft:planks",
  "amount": 3
}

---

palladium:score_buyable

The ability starts locked. The player must click it in the power screen and have enough points on a scoreboard objective, which are subtracted on purchase.

Field	Type	Default	Description
objective	String	—	Required. Name of the scoreboard objective.
amount	Positive Integer	1	Score points consumed on purchase.
icon	Icon	—	Required. Icon shown on the buy screen.
description	Text Component	—	Required. Label shown on the buy screen (e.g. "Skill Points").
requires	Condition(s)	—	Optional additional conditions. Once unlocked/purchased, these conditions need to be fulfilled for the ability to be unlocked.

"unlocking": {
  "type": "palladium:score_buyable",
  "objective": "skill_points",
  "amount": 10,
  "icon": "minecraft:experience_bottle",
  "description": "Skill Points"
}

---

Enabling Handlers

Enabling determines whether the ability is currently active. An unlocked but disabled ability has no effect.

Condition shorthand

Passing a list of conditions directly is a shorthand for palladium:conditional. This covers the majority of unlocking use cases.

"unlocking": [
  { "type": "palladium:has_effect", "effect": "minecraft:strength" },
  { "type": "palladium:crouching" }
]

---

palladium:conditional

Enables the ability automatically whenever a condition holds. Evaluated every tick.

Field	Type	Default	Description
conditions	Condition(s)	—	Required. The condition(s) that must be true for the ability to be active.

"enabling": {
  "type": "palladium:conditional",
  "conditions": { "type": "palladium:has_effect", "effect": "minecraft:strength" }
}

"enabling": {
  "type": "palladium:conditional",
  "conditions": [
    { "type": "palladium:has_effect", "effect": "minecraft:strength" },
    { "type": "palladium:crouching" }
  ]
}

---

palladium:key_bind

Enables the ability in response to a player key press. The exact behavior depends on the behaviour field.

Field	Type	Default	Description
key_bind	Key Bind Type	palladium:ability_key	Which key triggers this handler.
behaviour	Behaviour	action	How the key press maps to the enabled state.
cooldown	Time (ticks or "Xs")	0	Cooldown after each activation. 0 = no cooldown.
time	Time (ticks or "Xs")	0	Only used with activation behaviour. Determines how long the ability stays active after a press.

"enabling": {
  "type": "palladium:key_bind",
  "key_bind": { "type": "palladium:ability_key" },
  "behaviour": "toggle",
  "cooldown": 20
}

Behaviour

Value	Description
action	The ability activates for one tick when the key is pressed. Supports cooldown.
toggle	Each press switches the ability on or off.
held	The ability is active only while the key is held down. Supports cooldown (maximum time it can be held).
activation	The key starts a timed activation. The ability stays enabled for time ticks, then enters cooldown before it can be triggered again.

Key Bind Types

palladium:ability_key (default)

The dedicated Palladium ability keybind (configurable by the player in the controls menu). No extra fields.

"key_bind": { "type": "palladium:ability_key" }

Since this is the default, it can be omitted entirely from the handler.

palladium:jump

Triggers on the player's jump key.

Field	Type	Default	Description
cancel_jump	Boolean	false	When true, the jump action itself is suppressed while this handler is active.

"key_bind": {
  "type": "palladium:jump",
  "cancel_jump": true
}

palladium:mouse_click

Triggers on a mouse button press.

Field	Type	Default	Description
click_type	left_click | right_click | middle_click	—	Required. Which mouse button to listen to.
cancel_interaction	Boolean	false	When true, the normal click interaction (attack / use) is suppressed.

"key_bind": {
  "type": "palladium:mouse_click",
  "click_type": "right_click",
  "cancel_interaction": true
}

---

Examples

Always unlocked, enabled by toggle key

"state": {
  "enabling": {
    "type": "palladium:key_bind",
    "behaviour": "toggle"
  }
}

Buy with XP, then hold jump to activate

"state": {
  "unlocking": {
    "type": "palladium:experience_level_buyable",
    "xp_level": 10
  },
  "enabling": {
    "type": "palladium:key_bind",
    "key_bind": { "type": "palladium:jump", "cancel_jump": true },
    "behaviour": "held"
  }
}

Condition-based unlock, condition-based enable

"state": {
  "unlocking": [ { "type": "palladium:has_power", "power": "test:parent_power" } ],
  "enabling": [ { "type": "palladium:sneaking" } ]
}

Action with cooldown (right-click shoots, 2 second cooldown)

"state": {
  "enabling": {
    "type": "palladium:key_bind",
    "key_bind": { "type": "palladium:mouse_click", "click_type": "right_click", "cancel_interaction": true },
    "behaviour": "action",
    "cooldown": 40
  }
}