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
typefield): handlers likepalladium:key_bindor the buyable variants. - A list of Conditions: automatically wrapped into a
palladium:conditionalhandler. 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:buyable
The ability starts locked. The player must click it in the power screen and pay the specified cost, which is consumed on purchase.
| Field | Type | Default | Description |
|---|---|---|---|
cost | Cost | — | Required. The cost that must be paid to unlock the ability. |
requires | Condition(s) | — | Optional additional conditions. Once purchased, these must still be fulfilled for the ability to be considered unlocked. |
Buy with XP levels:
"unlocking": {
"type": "palladium:buyable",
"cost": {
"type": "palladium:experience_level",
"xp_level": 5
}
}
Buy with items:
"unlocking": {
"type": "palladium:buyable",
"cost": {
"type": "palladium:item",
"ingredient": "minecraft:diamond",
"amount": 3
}
}
Buy with a scoreboard score:
"unlocking": {
"type": "palladium:buyable",
"cost": {
"type": "palladium:score",
"objective": "skill_points",
"amount": 10,
"icon": { "type": "palladium:item", "item": "minecraft:experience_bottle" },
"description": "Skill Points"
}
}
With an additional unlock condition:
"unlocking": {
"type": "palladium:buyable",
"cost": {
"type": "palladium:experience_level",
"xp_level": 10
},
"requires": [
{ "type": "palladium:has_effect", "effect": "minecraft:strength" },
{ "type": "palladium:crouching" }
]
}
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 | activation | How the key press maps to the enabled state. |
cooldown | Time (ticks or "Xs") | 0 | Cooldown after each activation (or forced deactivation for held/toggle). 0 = no cooldown. |
time | Time (ticks or "Xs") | 0 | Behaviour-dependent duration. See Behaviour table for details. Defaults to 1 tick for activation. |
"enabling": {
"type": "palladium:key_bind",
"key_bind": { "type": "palladium:ability_key" },
"behaviour": "toggle",
"cooldown": 20
}
Behaviour
| Value | Description | time meaning | cooldown meaning |
|---|---|---|---|
activation | Press once to activate for time ticks, then wait cooldown before pressing again. With the default time of 1 this behaves as a single-tick trigger (equivalent to the old action behaviour). | How long the ability stays active after the key is pressed. Defaults to 1 tick if unset. | Wait before the player can trigger again. |
toggle | Press to switch the ability on or off. When time > 0, pressing again while active cancels early — cooldown always applies on deactivation. | (optional) Max active duration. If 0, toggle is unlimited. | Applied after the timer expires or the player cancels early by pressing again. |
held | The ability is active while the key is held. When time > 0, the ability is force-deactivated after time ticks; releasing early also triggers cooldown. | (optional) Max hold duration in ticks. If 0, the ability can be held indefinitely. | Applied whenever the ability deactivates (both early release and hitting time). |
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:buyable",
"cost": {
"type": "palladium:experience_level",
"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" } ]
}
Single-use activation 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": "activation",
"cooldown": 40
}
}
Timed activation (active for 3 seconds, then 10 second cooldown)
"state": {
"enabling": {
"type": "palladium:key_bind",
"behaviour": "activation",
"time": "3s",
"cooldown": "10s"
}
}
Limited hold (hold for up to 5 seconds, 8 second cooldown on release)
"state": {
"enabling": {
"type": "palladium:key_bind",
"behaviour": "held",
"time": "5s",
"cooldown": "8s"
}
}
Timed toggle (press to activate for 4 seconds, press again to cancel early)
"state": {
"enabling": {
"type": "palladium:key_bind",
"behaviour": "toggle",
"time": "4s",
"cooldown": "10s"
}
}