đ§ Mechanics
Overviewâ
Mechanics define the behavior and functionality of Oraxen items. They allow you to create simple or complex interactions, or implement custom features such as furniture, blocks, and unique abilities. Mechanics are controlled by the mechanics section in each item config.
Configurationâ
Mechanics are configured per item in .yml files inside plugins/Oraxen/items.
đ plugins
đ Oraxen
đ items
- đ weapons.yml
- đ foods.yml
my_backpack:
material: PAPER
mechanics:
backpack:
rows: 4
title: "<red>Backpack"
Enabling/Disabling Mechanicsâ
To improve performance, Oraxen allows you to disable / enable mechanics via the mechanics.yml file at plugins/Oraxen/mechanics.yml.
You can disable mechanics you don't use or need.
itemtype:
enabled: false
soulbound:
enabled: true
backpack:
enabled: true
music_disc:
enabled: true
Mechanicsâ
đĄī¸ spear_lunge
A charged attack mechanic that lets the player lunge forward and hit entities in front of them.
my_spear:
material: IRON_SWORD
pack:
generate_model: false
model: default/spear_inactive
mechanics:
spear_lunge:
active_model: default/spear_active
intermediate_models:
- default/spear_frame0
- default/spear_frame1
smooth_frames: 2
charge_ticks: 20
lunge_velocity: 0.8
max_range: 5.0
damage: 10.0
min_damage: 2.0
knockback: 0.8
hitbox_radius: 0.5
min_charge_percent: 0.25
charge_slowdown: 0.5
max_hold_ticks: 60
max_targets: 3
particles:
enabled: true
charge: CRIT
lunge: SWEEP_ATTACK
hit: DAMAGE_INDICATOR
sounds:
enabled: true
charge: ITEM_TRIDENT_RIPTIDE_1
lunge: ENTITY_PLAYER_ATTACK_SWEEP
hit: ENTITY_PLAYER_ATTACK_STRONG
Options
active_model defines the model shown at full charge.
intermediate_models defines optional animation frames during charging.
smooth_frames controls how many transition frames are used.
charge_ticks defines how long full charge takes.
lunge_velocity, max_range, damage, min_damage, knockback, hitbox_radius, min_charge_percent, charge_slowdown, max_hold_ticks, and max_targets control the attack behavior.
Minecraft version
1.21.4+ for model swapping during charge
⥠thor
Spawns lightning bolts when the item is used.
mechanics:
thor:
lightning_bolts_amount: 5
random_location_variation: 1.5
delay: 20000
charges: -1
Options
lightning_bolts_amount defines how many bolts are spawned.
random_location_variation defines a random offset in blocks applied to each strike position on the X and Y axes.
delay defines the cooldown in milliseconds.
charges defines how many uses the item has before being consumed. Use -1 for unlimited uses.
𩸠lifeleech
Steals health from the target when the player hits them.
mechanics:
lifeleech:
amount: 2
Options
amount defines how many half-hearts are leeched.
𩹠bleeding
Applies bleed damage over time on hit.
mechanics:
bleeding:
chance: 0.3
duration: 100
damage_per_interval: 0.5
interval: 20
Options
chance defines the chance to apply bleeding.
duration defines the total duration in ticks.
damage_per_interval defines how much damage each tick cycle deals.
interval defines the delay between bleed damage ticks.
đĨ energyblast
Creates a particle cone attack that damages entities in front of the player.
mechanics:
energyblast:
delay: 20000
length: 5
damage: 10.0
charges: -1
particle:
type: REDSTONE
size: 1
color:
red: 0
green: 255
blue: 255
Options
delay defines the cooldown in milliseconds.
length defines the length of the blast.
damage defines how much damage it deals.
charges defines how many uses the item has before being consumed.
particle configures the particle effect. REDSTONE supports custom size and color.
â ī¸ witherskull
Launches wither skulls on use.
mechanics:
witherskull:
charged: false
delay: 3000
charges: -1
Options
charged controls whether the skull can break blocks.
delay defines the cooldown in milliseconds.
charges defines how many uses the item has before being consumed.
đĨ fireball
Launches an exploding fireball on use.
mechanics:
fireball:
delay: 3000
yield: 2.0
speed: 1.0
charges: 5
Options
delay defines the cooldown in milliseconds.
yield defines the explosion power.
speed defines projectile speed.
charges defines how many uses the item has before being consumed.
đĨ knockback_strike
A combo-based mechanic that applies a stronger knockback effect after a configurable number of consecutive hits.
mechanics:
knockback_strike:
required_hits: 15
knockback_horizontal: 2.0
knockback_vertical: 1.2
reset_time: 80
play_sound: true
sound_type: ENTITY_ENDER_DRAGON_HURT
sound_volume: 1.5
sound_pitch: 0.8
particle:
type: DUST
count: 200
spread: 0.5
Options
required_hits defines how many consecutive hits are needed before the effect triggers.
knockback_horizontal and knockback_vertical define the knockback force.
reset_time defines how long the combo can idle before it resets.
play_sound, sound_type, sound_volume, and sound_pitch configure the sound effect.
particle.type, particle.count, and particle.spread configure the particle burst.
đž harvesting
Automatically harvests and replants crops in an area.
mechanics:
harvesting:
cooldown: 10000 # 10 seconds
radius: 5
height: 3
Options
cooldown defines the delay between uses in milliseconds.
radius defines the horizontal area around the clicked block.
height defines how far above the clicked block the mechanic checks.
âī¸ mining
Breaks additional blocks at configured offsets from the mined block.
mechanics:
mining:
- "0,1,0"
- "0,-1,0"
- "1,0,0"
- "-1,0,0"
Options
Each entry is an integer x,y,z offset along fixed world axes. The pattern does not rotate with the player's facing or the mined face. 0,0,0 is mined normally and does not need to be listed. Duplicate offsets are ignored.
Global configuration
mining:
enabled: true
call_events: true
call_events controls whether Oraxen calls block break events for the extra blocks. Known to cause issues with some enchantment plugins when enabled.
đĨ smelting
Automatically smelts supported mined blocks.
mechanics:
smelting:
play_sound: true
Options
play_sound controls whether a sound is played during smelting.
Global configuration
smelting:
enabled: true
blacklist_cooked:
- WET_SPONGE
blacklist_cooked defines drops that should never be smelted.
đ§Ē bottledexp
Converts player experience into experience bottles.
mechanics:
bottledexp:
ratio: 0.95
Options
ratio defines how much experience is converted into bottles.
Global configuration
bottledexp:
enabled: true
durability_cost: 10
đĒ¨ bedrockbreak
Allows the item to break bedrock.
mechanics:
bedrockbreak:
hardness: 10
probability: 1
Options
hardness defines the delay between break animation updates.
probability defines the chance to receive the bedrock drop.
delay defines the delay in ticks before breaking starts.
Global configuration
bedrockbreak:
enabled: true
disable_on_first_layer: false
durability_cost: 500
This mechanic uses Oraxen's packet handling. On legacy servers without native packet support, PacketEvents is required.
đ§ watering
Creates a watering can system with linked empty and filled items.
empty_watering_can:
displayname: "<gray>Empty Watering Can"
material: PAPER
mechanics:
watering:
filledCanItem: filled_watering_can
filled_watering_can:
displayname: "<aqua>Filled Watering Can"
material: PAPER
mechanics:
watering:
emptyCanItem: empty_watering_can
Options
filledCanItem defines which item the empty can becomes when filled.
emptyCanItem defines which item the filled can becomes after watering.
đ food
Lets any item behave like food with custom hunger, saturation, replacement items, and potion effects.
mechanics:
food:
hunger: 10
saturation: 10
replacement:
oraxen_item: any_oraxen_itemid
effect_probability: 0.35
effects:
hunger:
amplifier: 1
duration: 20
is_ambient: true
has_particles: true
has_icon: true
night_vision:
duration: 60
Options
hunger and saturation define the food values.
replacement defines which item replaces the consumed item.
effect_probability defines the chance that the listed effects are applied.
effects defines potion effects and their settings.
On 1.20.5+, prefer the food component instead of this legacy mechanic.
đ backpack
Turns an item into portable storage.
backpack:
displayname: backpack
material: PAPER
unstackable: true
mechanics:
backpack:
rows: 4
title: "<red>Backpack"
open_sound: "entity.shulker.open"
close_sound: "entity.shulker.close"
blocked-items:
- shulker_box
- minecraft:ender_chest
- oraxen:another_backpack
Options
rows defines the inventory size.
title defines the backpack GUI title.
open_sound and close_sound define the sounds played when the backpack opens and closes.
volume and pitch define the sound volume and pitch (both default to 1.0).
blocked-items defines items that cannot be stored in the backpack. Vanilla item IDs can be namespaced or unnamespaced, while Oraxen item IDs require the oraxen: prefix. Blocking shulker_box also blocks every colored shulker box.
Use unstackable: true for backpack items. Stackable materials can cause duplication issues.
đŊ backpack_cosmetic
Displays a cosmetic backpack on players and equipped armor stands using packet-based armor stands.
leather_backpack:
material: LEATHER_CHESTPLATE
pack:
generate_model: true
parent_model: item/generated
textures:
- leather_backpack
mechanics:
backpack_cosmetic:
slot: CHEST
offset:
x: 0.0
y: 0.2
z: -0.2
scale: 0.8
view_distance: 48
hide_while_swimming: true
hide_while_gliding: true
Options
slot defines where the item must be equipped or stored for the cosmetic to render. The special value INVENTORY triggers from anywhere in the inventory except the hands.
model optionally overrides the displayed model.
offset defines the rendered position relative to the player.
scale defines the rendered size.
view_distance defines the maximum visible distance.
hide_in_spectator, small, and visible_to_self control extra render behavior.
hide_while_swimming defines whether the backpack gets hidden when swimming (defaults to true when not defined).
hide_while_gliding defines whether the backpack gets hidden when gliding (defaults to true when not defined).
Global configuration
backpack_cosmetic:
enabled: true
armor_stand_enabled: true
armor_stand_range: 128
armor_stand_enabled enables cosmetic displays on equipped armor stands (defaults to true). Disable it to keep only player backpacks.
armor_stand_range sets the armor-stand scan range in blocks (defaults to 128).
đĩ music_disc
Creates a custom music disc that plays a configured sound.
mechanics:
music_disc:
song: "minecraft:my_music_disc_song.mysong"
Options
song defines the namespaced sound key from sound.yml.
On 1.21+, prefer the jukebox playable component instead of this legacy mechanic.
đ¨ durability
Applies custom durability behavior to an Oraxen item.
mechanics:
durability:
value: 5000
Options
value defines the durability value used by the mechanic.
On 1.20.5+, prefer the durability component instead of this legacy mechanic.
âī¸ efficiency
Applies a mining speed boost while the item is held. Negative values apply mining fatigue instead.
mechanics:
efficiency:
amount: 2
Options
amount defines the haste or mining fatigue level.
đĨ¤ consumable
Makes the item consumable on right-click.
mechanics:
consumable: {}
𧴠consumable_potion_effects
Applies potion effects when the item is consumed or used.
mechanics:
consumable_potion_effects:
speed:
amplifier: 1
duration: 600
ambient: false
particles: true
icon: true
regeneration:
amplifier: 0
duration: 200
Options
Each subsection key is a potion effect type.
amplifier, duration, ambient, particles, and icon control the effect behavior.
𧰠misc
Groups several smaller vanilla-behavior toggles into one mechanic.
mechanics:
misc:
disable_vanilla_interactions: false
can_strip_logs: false
piglins_ignore_when_equipped: false
compostable: false
allow_in_vanilla_recipes: true
prevent_renaming: true
Options
disable_vanilla_interactions disables normal vanilla interactions.
can_strip_logs controls whether the item can strip logs.
piglins_ignore_when_equipped makes piglins ignore the player when the item is worn.
compostable controls whether the item can be composted.
allow_in_vanilla_recipes controls whether vanilla recipes can use the item.
prevent_renaming controls whether the item can be renamed.
On modern versions, several of these behaviors are better handled with components.
đ ī¸ repair
Lets an item repair another item using either a percentage or a fixed amount.
mechanics:
repair:
ratio: 0.10
fixed_amount: 10
Options
Use either ratio or fixed_amount for a given repair item.
Global configuration
repair:
enabled: true
oraxen_durability_only: false
â¨ī¸ commands
Runs configured commands as console, player, or opped player.
mechanics:
commands:
cooldown: 5000 # 5 seconds
permission: "my.awesome.perm"
one_usage: true
console:
- "kill %p%"
player:
- "spawn"
opped_player:
- "give diamond_sword 1"
Options
cooldown defines the delay between uses in milliseconds.
permission defines a required permission node.
one_usage consumes one item on use.
console, player, and opped_player define command lists for each sender type.
𧊠custom
Runs configurable actions when an event happens with the item. Each subsection is a freely named variant with its own event and actions.
mechanics:
custom:
my_variant:
event: CLICK:right:block
one_usage: false
cooldown: 40
conditions:
- '#player.isSneaking()'
actions:
- '[console] say <player> used the item'
- '[message] <green>Hello <player>!'
Options
event defines the trigger. Supported types are BREAK, CLICK, INV_CLICK, DROP, PICKUP, EQUIP, UNEQUIP, and DEATH. CLICK accepts optional parameters as CLICK:<right|left|all>:<air|block|all>.
one_usage consumes one item when the actions run. Defaults to false.
cooldown defines the delay between uses in ticks.
conditions defines optional expressions evaluated on the player. All must pass for the actions to run.
actions defines the actions to run. Supported prefixes are [console], [player], [message], [actionbar], and [sound]. <player> is replaced by the player name. A variant without actions is ignored.
đĄī¸ armor_effects
Applies potion effects while armor or hats are equipped.
mechanics:
armor_effects:
night_vision:
duration: 10
amplifier: 0
ambient: true
particles: true
icon: true
mechanics:
armor_effects:
night_vision:
requires_full_set: true
duration: 10
amplifier: 0
Options
Each subsection key is a potion effect type.
requires_full_set makes the effect apply only when the full armor set is worn.
duration, amplifier, ambient, particles, and icon control the effect behavior.
Global configuration
armor_effects:
enabled: true
delay_in_ticks: 20
delay_in_ticks defines how often effects are reapplied (defaults to 20). It is also the default duration for each effect.
⨠aura
Shows particles while the player holds the item.
mechanics:
aura:
type: simple
particle: PORTAL
Options
type supports simple, ring, and helix.
particle defines the Bukkit particle type to render.
đŠ hat
Lets the item be worn on the player's head.
mechanics:
hat: {}
On 1.21.2+, prefer the equippable component instead of this legacy mechanic.
đī¸ skinnable
Allows the item texture to be changed by an item using the skin mechanic.
mechanics:
skinnable: {}
𧹠itemtype
Overrides the item type detected by Oraxen blocks.
mechanics:
itemtype:
value: SUPER_MATERIAL
Options
value must match an item type declared for the relevant block mechanic.
đ soulbound
Prevents the item from being lost on death, optionally with a configurable lose chance.
mechanics:
soulbound:
lose_chance: 0
Options
lose_chance is a value from 0 to 1.
đĄ toggle_light
Adds interactive lighting to furniture, noteblocks, and stringblocks that can be toggled by right-clicking.
mechanics:
toggle_light:
light: 5
toggle_light: 15
Options
light defines the base light level that is always active.
toggle_light defines the alternate light level applied when the player toggles the item.
đ¨ skin
Makes the item act as a skin source for skinnable items. Both items must use the same base material.
mechanics:
skin:
consume: true
Options
consume defines whether one skin item is consumed on use.
𧹠block
Makes the item placeable as a block.
mechanics:
block:
type: FULL # FULL, STRING, CHORUS, STAIR, SLAB, DOOR, TRAPDOOR, GRATE, BULB
light: 15
block-sounds:
break-sound: block.wood.break
place-sound: block.wood.place
placeable:
floor: true # top of blocks
wall: true # sides of blocks
roof: false # underside of blocks
allow:
- minecraft:grass
disallow:
- minecraft:dirt
custom-variation: 5
appearance: # Also supports textures
model: crystalmush_log
events: # Run actions when a placed block is clicked
- click: right # both, left, right
actions:
- command: 'say "<Player> clicked this block"'
executor: CONSOLE # PLAYER, CONSOLE, OP-PLAYER
condition: 'player.hasPermission("myserver.block.use")'
- message: '<green>Hi <Player>!'
breaking: # New drop & breaking config section
- when: # When the tool is...
- minecraft:iron_axe
- minecraft:golden_axe
- minecraft:diamond_axe
- minecraft:netherite_axe # Also supports tags via "#<tag>"
hardness: 2 # Hardness when these tools are used
drops: # Drops when this tool is used
- item: crystalmush_log
probability: 1.0
silk-touch: any # Drop with or without Silk Touch
fortune: 1 # Percentage (1 = 100%) to increase the loot amount per fortune level
durability:
remove: 1 # Remove or add durability when breaking.
add: 0
- else: # Anything that is not covered by another `when` section
hardness: 4
drops:
- item: crystalmush_log
probability: 1.0
durability:
remove: 2 # Remove or add durability when breaking.
add: 0
events runs commands and messages when a placed block is clicked. See click events for filters, executors, conditions, and migration details.
Each loot entry can use silk-touch to control whether it drops based on the breaking tool.
anyorfalse(default); Drop with or without Silk Touch.requiredortrue; drop only with Silk Touch.forbidden; drop only without Silk Touch.
This allows one block to drop itself with Silk Touch and different loot without it.
magic_ore:
mechanics:
block:
type: FULL
breaking:
- when: ["#minecraft:pickaxes"]
hardness: 3
drops:
- item: magic_ore
silk-touch: required
probability: 1.0
- item: magic_shard
silk-touch: forbidden
amount: 2..4
fortune: 0.5
probability: 1.0
đĒ furniture
Creates custom placed furniture using item frames, display entities, armor stands, or other supported furniture render types.
table:
mechanics:
furniture:
type: DISPLAY_ENTITY
barrier: true
barriers:
- origin
- z: 1
hitboxes:
- 0,0,0 1,3 # Hitbox with 0,0,0 offset from the furniture with the size 1x3.
- 1,0,3 0.5,2.5 # Hitbox with 1,0,3 offset from the furniture with the size 0.5x2.5.
seats:
- 0,0,0 # Seat offset relative to the furniture center, uses furniture yaw.
- 0.5,0,0 90 # Seat offset with a fixed yaw.
restricted_rotation: VERY_STRICT
rotatable: true
lights:
- 0,1,0 15 # Light offset with level 15.
hardness: 5
breakable: true
events:
- click: right
actions:
- command: 'say "<Player> clicked this furniture"'
executor: CONSOLE
condition: 'player.hasPermission("myserver.furniture.use")'
- message: '<green>Hi <Player>!'
item: different_item_id
farmland_required: false
farmblock_required: false
blocklocker:
can_protect: true
protection_type: CONTAINER
limited_placing:
floor: true
wall: false
roof: false
type: ALLOW
block_types:
- GRASS_BLOCK
storage:
type: STORAGE
rows: 5
title: "<red>My Storage"
jukebox:
active_model: opened
volume: 1.0
pitch: 1.0
permission: "oraxen.jukebox.play"
evolution:
delay: 6000
next_stage: my_plant_stage2
probability: 0.5
text_entity:
text:
- "<gold>Workshop Table"
offset: { x: 0.0, y: 1.2, z: 0.0 }
display_entity_properties:
display_transform: NONE
brightness:
block_light: 15
sky_light: 0
scale:
x: 1
y: 1
z: 1
translation:
x: 0
y: 0
z: 0
tracking_rotation: FIXED
view_range: 1
interpolation_duration: 0
interpolation_delay: 0
shadow_strength: 0
shadow_radius: 0
displayWidth: 0
displayHeight: 0
armor_stand_properties:
scale:
x: 1
y: 1
z: 1
translation:
x: 0
y: 0
z: 0
drop:
silktouch: false
loots:
- { oraxen_item: table, probability: 1.0 }
Options
type defines the furniture render type. Common values are DISPLAY_ENTITY, ITEM_FRAME, GLOW_ITEM_FRAME, and ARMOR_STAND.
barrier and barriers add solid collision areas. hitboxes defines interaction areas, formatted as <x>,<y>,<z> <width>,<height>, and supports one or more entries.
seats adds seats, formatted as <x>,<y>,<z> or <x>,<y>,<z> <yaw>. Offsets are relative to the furniture center and are rotated with the furniture. Omit yaw to use the furniture yaw.
restricted_rotation (NONE, STRICT, or VERY_STRICT) and rotatable control placement rotation.
lights, hardness, and drop define placed behavior. lights entries use <x>,<y>,<z> <level> for per-offset light sources. drop also supports fortune, minimal_type, and best_tools.
events runs actions when a player clicks furniture barriers or hitboxes. See click events.
breakable controls whether players can break the furniture. It defaults to false when an event listens for left or both clicks, allowing hits to trigger actions without removing the furniture; otherwise it defaults to true. Set it explicitly to override this behavior.
item defines an alternate display item when placed.
limited_placing, blocklocker, and storage add placement rules, protection, and container behavior. limited_placing also supports block_tags, oraxen_blocks, and a radius_limitation subsection with radius and amount. storage also supports open_sound, close_sound, open_animation, close_animation, volume, and pitch.
jukebox lets the furniture play music discs and swap to an active model.
evolution, farmland_required, and farmblock_required support plant and farming setups. evolution also supports light_boost, rain_boost, and bone_meal subsections.
text_entity, text_entities, and display_entity_properties configure attached text displays and display entity rendering. Text displays also support line_width, background_color, text_opacity, see_through, shadow, default_background, alignment, billboard, scale, view_range, and refresh_ticks. Display entity properties support display_transform, scale, translation, brightness.block_light, brightness.sky_light, tracking_rotation, view_range, interpolation_duration, interpolation_delay, shadow_strength, shadow_radius, displayWidth, and displayHeight.
armor_stand_properties configures armor-stand furniture scale and translation; armor stands can also reuse display_entity_properties.scale and display_entity_properties.translation for convenience.
modelengine_id is also supported for ModelEngine-based furniture.
storage on furniture requires a barrier or barriers. For modern servers, DISPLAY_ENTITY furniture also supports hitboxes and display_entity_properties.
Click Eventsâ
Placed blocks and furniture share the events format. Add it under mechanics.block or mechanics.furniture.
my_furniture:
material: PAPER
mechanics:
furniture:
type: DISPLAY_ENTITY
barrier: true
breakable: false
events:
- click: both
actions:
- command: 'say <Player> clicked this furniture'
executor: CONSOLE
condition: 'player.hasPermission("myserver.furniture.use")'
- message: '<green>Hello <Player>!'
conditions:
- '!player.hasPermission("myserver.furniture")'
- '#server.getOnlinePlayers().size() > 10'
click accepts left, right, or both (default). Actions run in order.
command uses PLAYER (default), CONSOLE, or OP-PLAYER as its executor.
message sends MiniMessage text to the clicking player. <Player> (also <player> or <PLAYER>) inserts the player's name. PlaceholderAPI placeholders work when installed.
Conditionsâ
Set condition for one check or conditions for a list; every check must pass for that action to run. Checks can use expressions based on methods and properties available on the server's Player or Server API.
player / #player refers to the clicking player, and server / #server to the server.
For example, player.hasPermission("myserver.furniture.use") checks a permission and #server.getOnlinePlayers().size() > 10 checks the player count. Prefix a check with ! to require it to be false, as in !player.hasPermission("myserver.furniture.bypass"). Comparisons include ==, !=, >, and <.
Conditions are per action; without one, the action runs on a matching click. An invalid check skips its action and logs a warning. For available methods, see the Paper Player API and Paper Server API.