Block Actions

The fabricpy.actions module provides ready-made Java code snippets for common gameplay effects that you can return from a block’s event handlers (on_left_click, on_right_click, on_break).

Every function returns a plain Python string containing one or more Java statements. Combine multiple actions by returning a list from your hook method — the framework joins them automatically.

Quick Example

import fabricpy
from fabricpy.actions import apply_effect, play_sound, give_xp

class MagicBlock(fabricpy.Block):
    def __init__(self):
        super().__init__(
            id="mymod:magic_block",
            name="Magic Block",
            item_group=fabricpy.item_group.BUILDING_BLOCKS,
            loot_table=fabricpy.LootTable.drops_self("mymod:magic_block"),
        )

    def on_right_click(self):
        return [
            apply_effect("REGENERATION", 400, 1),
            play_sound("PLAYER_LEVELUP"),
            give_xp(50),
        ]

Replace Block

Swap the clicked block for a different one.

from fabricpy.actions import replace_block

def on_right_click(self):
    return replace_block("DIAMOND_BLOCK")
replace_block(block, *, pos_var='pos', world_var='world')[source]

Replace the block at the event position with another block.

Parameters:

  • block (str) – Blocks constant name, e.g. "DIAMOND_BLOCK", "AIR", "GOLD_BLOCK", "OBSIDIAN".

  • pos_var (str) – Name of the BlockPos variable in scope.

  • world_var (str) – Name of the Level variable in scope.

Returns:

Java code that replaces the block.

Return type:

str

Example:

replace_block("DIAMOND_BLOCK")
# → world.setBlockAndUpdate(pos, Blocks.DIAMOND_BLOCK.defaultBlockState());

Teleport Player

Move the player to absolute or relative coordinates.

from fabricpy.actions import teleport_player

# Relative: teleport 10 blocks up
def on_right_click(self):
    return teleport_player(0, 10, 0, relative=True)

# Absolute: teleport to world spawn
def on_left_click(self):
    return teleport_player(0, 64, 0)
teleport_player(x, y, z, *, relative=False, player_var='player', pos_var='pos')[source]

Teleport the player to a position.

Parameters:

  • x (float) – X coordinate (absolute, or offset when relative is True).

  • y (float) – Y coordinate (absolute, or offset when relative is True).

  • z (float) – Z coordinate (absolute, or offset when relative is True).

  • relative (bool) – When True the coordinates are offsets from the block position referenced by pos_var.

  • player_var (str) – Name of the player variable in scope.

  • pos_var (str) – Name of the BlockPos variable in scope (used when relative is True).

Returns:

Java code that teleports the player.

Return type:

str

Example:

teleport_player(100, 200, 100)  # absolute
teleport_player(0, 10, 0, relative=True)  # 10 blocks above the block

Launch Player

Apply a velocity impulse to the player (knock-back / launch upward).

from fabricpy.actions import launch_player

# Launch upward
def on_left_click(self):
    return launch_player(dy=2.5)

# Launch in a direction
def on_right_click(self):
    return launch_player(dx=1.0, dy=0.5, dz=1.0)
launch_player(dx=0.0, dy=1.0, dz=0.0, *, player_var='player')[source]

Launch the player upward or apply knockback.

Adds to the player’s velocity and marks it for immediate client sync.

Parameters:

  • dx (float) – Horizontal X velocity component.

  • dy (float) – Vertical Y velocity component (positive = upward).

  • dz (float) – Horizontal Z velocity component.

  • player_var (str) – Name of the player variable in scope.

Returns:

Java code that launches the player.

Return type:

str

Example:

launch_player(dy=2.0)  # launch straight up
launch_player(dx=3.0, dy=0.5, dz=0.0)  # knockback sideways

Apply Potion / Status Effect

Grant a potion effect (by Vanilla MobEffects field name).

from fabricpy.actions import apply_effect

# Speed II for 30 seconds (600 ticks)
def on_right_click(self):
    return apply_effect("SPEED", 600, 1)

# Night Vision for 1 minute (default amplifier 0)
def on_left_click(self):
    return apply_effect("NIGHT_VISION", 1200)
apply_effect(effect, duration=200, amplifier=0, *, player_var='player')[source]

Apply a potion / status effect to the player.

Parameters:

  • effect (str) – MobEffects constant name (Mojang mappings), e.g. "SPEED", "STRENGTH", "REGENERATION", "NIGHT_VISION", "INVISIBILITY", "JUMP_BOOST", "SLOW_FALLING", "POISON", "FIRE_RESISTANCE", "LUCK".

  • duration (int) – Duration in ticks (20 ticks = 1 second). Defaults to 200 (10 seconds).

  • amplifier (int) – Effect amplifier (0 = level I, 1 = level II, …).

  • player_var (str) – Name of the player variable in scope.

Returns:

Java code that applies the effect.

Return type:

str

Example:

apply_effect("SPEED", duration=600, amplifier=1)

Play Sound

Play a Vanilla sound event at the block position.

from fabricpy.actions import play_sound

def on_right_click(self):
    return play_sound("ENDER_DRAGON_GROWL")
play_sound(sound, volume=1.0, pitch=1.0, *, source='BLOCKS', pos_var='pos', world_var='world')[source]

Play a sound at the block position.

Parameters:

  • sound (str) – SoundEvents constant name (Mojang mappings — without the ENTITY_/BLOCK_/ITEM_ prefix), e.g. "LIGHTNING_BOLT_THUNDER", "ANVIL_LAND", "EXPERIENCE_ORB_PICKUP", "ENDER_DRAGON_GROWL".

  • volume (float) – Sound volume (1.0 = normal).

  • pitch (float) – Sound pitch (1.0 = normal, higher = faster).

  • source (str) – SoundSource constant: "BLOCKS", "PLAYERS", "HOSTILE", "NEUTRAL", "MASTER", etc.

  • pos_var (str) – Name of the BlockPos variable in scope.

  • world_var (str) – Name of the Level variable in scope.

Returns:

Java code that plays the sound.

Return type:

str

Note

Use Mojang-mapped field names (without ENTITY_/BLOCK_/ ITEM_ prefixes). A handful of SoundEvents fields are Holder<SoundEvent> rather than plain SoundEvent (e.g. NOTE_BLOCK_PLING, UI_BUTTON_CLICK). These are not compatible with this helper — use a plain SoundEvent field instead (the vast majority).

Example:

play_sound("ANVIL_LAND", volume=2.0, pitch=1.5)

Summon Lightning

Strike lightning at the block position (server-side only).

from fabricpy.actions import summon_lightning

def on_break(self):
    return summon_lightning()
summon_lightning(*, pos_var='pos', world_var='world')[source]

Summon a lightning bolt at the block position.

Only fires on the logical server (ServerLevel check).

Parameters:

  • pos_var (str) – Name of the BlockPos variable in scope.

  • world_var (str) – Name of the Level variable in scope.

Returns:

Java code that summons lightning.

Return type:

str

Example:

summon_lightning()

Drop Items

Spawn an item stack on the ground at the block position.

from fabricpy.actions import drop_item

def on_left_click(self):
    return [
        drop_item("DIAMOND", count=3),
        drop_item("EMERALD"),
    ]
drop_item(item, count=1, *, pos_var='pos', world_var='world')[source]

Drop item(s) at the block position.

Parameters:

  • item (str) – Items constant name, e.g. "DIAMOND", "GOLD_INGOT", "EMERALD", "IRON_INGOT".

  • count (int) – Number of items to drop.

  • pos_var (str) – Name of the BlockPos variable in scope.

  • world_var (str) – Name of the Level variable in scope.

Returns:

Java code that drops items.

Return type:

str

Example:

drop_item("DIAMOND", count=3)

Place Fire / Extinguish Area

Set fire at the block position or remove fire blocks in a cube around it.

from fabricpy.actions import place_fire, extinguish_area

def on_right_click(self):
    return place_fire()

def on_break(self):
    return extinguish_area(radius=5)
place_fire(*, above=True, pos_var='pos', world_var='world')[source]

Place fire at or above the block position.

Only places fire if the target position is currently air.

Parameters:

  • above (bool) – If True (default), place fire one block above pos. If False, place at pos directly.

  • pos_var (str) – Name of the BlockPos variable in scope.

  • world_var (str) – Name of the Level variable in scope.

Returns:

Java code that places fire.

Return type:

str

Example:

place_fire()             # fire above the block
place_fire(above=False)  # fire at the block position
extinguish_area(radius=3, *, pos_var='pos', world_var='world')[source]

Extinguish fire blocks in a cubic radius around the position.

Parameters:

  • radius (int) – Radius in blocks to scan for fire (default 3).

  • pos_var (str) – Name of the BlockPos variable in scope.

  • world_var (str) – Name of the Level variable in scope.

Returns:

Java code that replaces all FIRE blocks with AIR.

Return type:

str

Example:

extinguish_area(radius=5)

Give / Remove XP

Add or subtract experience points from the player.

from fabricpy.actions import give_xp, remove_xp

def on_right_click(self):
    return give_xp(100)

def on_left_click(self):
    return remove_xp(50)
give_xp(amount, *, player_var='player')[source]

Give experience points to the player.

Parameters:

  • amount (int) – Number of experience points to give.

  • player_var (str) – Name of the player variable in scope.

Returns:

Java code that gives XP.

Return type:

str

Example:

give_xp(100)
remove_xp(amount, *, player_var='player')[source]

Remove experience points from the player.

Parameters:

  • amount (int) – Positive number of experience points to remove.

  • player_var (str) – Name of the player variable in scope.

Returns:

Java code that removes XP (passes a negative value internally).

Return type:

str

Example:

remove_xp(50)

Damage / Heal Nearby Entities

Affect all LivingEntity instances within a radius of the block.

from fabricpy.actions import damage_nearby, heal_nearby

def on_right_click(self):
    return damage_nearby(8.0, radius=10.0)

def on_break(self):
    return heal_nearby(4.0, radius=5.0)
damage_nearby(amount, radius=5.0, *, exclude_player=True, pos_var='pos', world_var='world', player_var='player')[source]

Damage nearby living entities with magic damage.

Parameters:

  • amount (float) – Damage amount (half-hearts).

  • radius (float) – Search radius in blocks (default 5).

  • exclude_player (bool) – If True (default), the triggering player is excluded from the damage.

  • pos_var (str) – Name of the BlockPos variable in scope.

  • world_var (str) – Name of the Level variable in scope.

  • player_var (str) – Name of the player variable in scope.

Returns:

Java code that damages nearby entities.

Return type:

str

Example:

damage_nearby(6.0, radius=8.0)
heal_nearby(amount, radius=5.0, *, pos_var='pos', world_var='world')[source]

Heal nearby living entities.

Parameters:

  • amount (float) – Health to restore (half-hearts).

  • radius (float) – Search radius in blocks (default 5).

  • pos_var (str) – Name of the BlockPos variable in scope.

  • world_var (str) – Name of the Level variable in scope.

Returns:

Java code that heals nearby entities.

Return type:

str

Example:

heal_nearby(4.0, radius=10.0)

Delayed Action (Timer)

Schedule a block of Java code to run after a delay (in ticks, 20 = 1 second).

from fabricpy.actions import delayed_action, give_xp

# Give XP 3 seconds after right-click
def on_right_click(self):
    return delayed_action(give_xp(100), ticks=60)
delayed_action(action_code, ticks=20, *, world_var='world')[source]

Schedule an action to run after a delay.

Wraps the given Java code in a TickTask scheduled on the server, guarded by a ServerLevel instanceof check.

Parameters:

  • action_code (str) – Java code to execute after the delay. This is typically produced by another action helper.

  • ticks (int) – Delay in game ticks (20 ticks ≈ 1 second).

  • world_var (str) – Name of the Level variable in scope.

Returns:

Java code that schedules the delayed action.

Return type:

str

Example:

delayed_action(give_xp(100), ticks=40)   # give XP after 2 seconds
delayed_action(summon_lightning(), ticks=60)

Sculk Sensor Game Event

Emit a GameEvent that sculk sensors can detect.

from fabricpy.actions import sculk_event

def on_break(self):
    return sculk_event("LIGHTNING_STRIKE")
sculk_event(event, *, pos_var='pos', world_var='world', player_var='player')[source]

Emit a game event that sculk sensors can detect.

Parameters:

  • event (str) – GameEvent constant name, e.g. "BLOCK_CHANGE", "BLOCK_DESTROY", "EXPLODE", "STEP", "ENTITY_SHAKE", "NOTE_BLOCK_PLAY", "INSTRUMENT_PLAY", "LIGHTNING_STRIKE".

  • pos_var (str) – Name of the BlockPos variable in scope.

  • world_var (str) – Name of the Level variable in scope.

  • player_var (str) – Name of the player variable in scope (emitter).

Returns:

Java code that emits the game event.

Return type:

str

Example:

sculk_event("BLOCK_CHANGE")
sculk_event("EXPLODE")

Composing Actions

All action functions return plain Java strings. Return them as a list to combine multiple actions in a single handler:

from fabricpy.actions import (
    apply_effect, give_xp, play_sound, summon_lightning,
)
from fabricpy.message import send_message

def on_right_click(self):
    return [
        send_message("Let the ritual begin!"),
        apply_effect("FIRE_RESISTANCE", 600),
        summon_lightning(),
        give_xp(50),
        play_sound("WITHER_SPAWN"),
    ]

All Java imports are detected automatically — you never need to manage them yourself.

Full Example

See examples/block_actions.py for a complete runnable example that demonstrates every action in a single mod.