Falling Alchemy

Provides an alchemy system based on falling block physical interactions, supporting highly customizable recipe configurations. Core Extension: Deeply integrated with CraftTweaker, supporting probability control, complex condition logic, event listening, and sound effect control.

Demo: https://www.bilibili.com/video/BV1aKJVzsEzo

Features

✅ Core Mechanisms

• Custom falling blocks (Sand/Gravel/Anvil, etc.)
• Detect and replace specified items within range
• Support for multiple output generation and quantity proportion control

⚙️ Advanced Configuration

• Recipe Success Rate (0.0~1.0)
• Block Retention Chance (0.0~1.0)
• Single Processing
• Input protection under falling anvils
• Block displacement detection and extra output calculation
• Detection radius adjustment
• Custom Failure/Success sound effects
• NBT Fuzzy Matching (fuzzyNBT)
• Recipe Execution Priority (priority)

🌦️ Condition System

• Biome restriction
• Time range (MC Time 0~24000)
• Weather state (Clear/Rain/Thunder)
• Height restriction
• Moon phase restriction

Configuration Guide

Quick Start

import mods.fallingalchemy.FallingAlchemy;
import mods.fallingalchemy.ConsumedItem;

// 1. Create ConsumedItem object
val coalReq = FallingAlchemy.createConsumedItem(
    <minecraft:coal_ore>.withTag({Unbreakable: 1 as byte}),  // Match item
    3,                  // Required count (optional, default 1)
    true,               // Match NBT (optional, default false)
    true                // Fuzzy NBT match (optional, default false)
);

// 2. Create Builder
val builder = FallingAlchemy.addConversion(
    <minecraft:anvil>,                                   // Trigger block
    [coalReq],                                           // Inputs
    [<minecraft:diamond>]                                // Outputs
);

// 3. Chain configuration parameters
builder.setRadius(2.0)              // Set radius
       .setSingle(true)             // Enable single processing (only one recipe per fall event)
       .setRescueItems(true)        // Enable item protection (prevents remaining coal from being destroyed by the anvil)
       .setSuccessChance(0.8)       // 80% success rate
       .addHeightCondition(0, 60)   // Height restriction
       .register();                 // Register recipe

Method Explanation

FallingAlchemy.addConversion(IItemStack fallingBlock, ConsumedItem[] inputs, IItemStack[] outputs) Returns a ConversionBuilder object.

Builder Methods

ConsumedItem Parameters:

• IIngredient ingredient: The input item
• int requiredCount: Required quantity (Optional, default is 1)
• bool matchNBT: Whether to strictly match NBT (Optional, default is false)
• bool fuzzyNBT: When matchNBT=true, only validates if existing tags match (does not check for extra tags) (Optional, default is false)

Script Example

import mods.fallingalchemy.FallingAlchemy;
import mods.fallingalchemy.ConsumedItem;
import mods.fallingalchemy.event.FallingConversionPreEvent;
import mods.fallingalchemy.event.FallingConversionPostEvent;

// Scenario: Anvil falls on "Enchanted Golden Apple" and "Stick named Magic" -> Generates "Nether Star"
val builder = FallingAlchemy.addConversion(
    <minecraft:anvil>, // Trigger block
    [
        // NBT Strict Match Example: Must be Enchanted Golden Apple (Metadata 1)
        FallingAlchemy.createConsumedItem(<minecraft:golden_apple:1>, 1),

        // NBT + Fuzzy Match Example:
        // Requires a stick named "Magic"
        // Params: Item, Count(1), MatchNBT(true), FuzzyMatch(true - allows extra tags)
        FallingAlchemy.createConsumedItem(<minecraft:stick>.withTag({display: {Name: "Magic"}}), 1, true, true)
    ],
    [<minecraft:nether_star>] // Output
);

// Chain detailed configuration
builder.setRadius(2.5)                            // Detection radius 2.5 blocks
       .setSuccessChance(0.8)                     // 80% success rate
       .setKeepBlockChance(0.0)                   // Anvil always disappears (0% keep)
       .setPriority(100)                          // High priority, checked before other recipes
       .setSingle(true)                           // Process only one recipe per fall to prevent consuming entire stacks
       .setRescueItems(true)                      // Rescue remaining materials from anvil damage
       .setSuccessSound("minecraft:ui.toast.challenge_complete", 1.0, 1.0)
       .setFailureSound("minecraft:entity.item.break", 1.0, 0.8)
       .addHeightCondition(0, 60)                 // Can only happen underground (Y < 60)
       .addMoonPhaseCondition(0)                  // Must be Full Moon
       .register("apple");                        // Register with ID


// Pre Event: Triggered when recipe matches successfully but before items are generated (Can cancel, modify outputs)
events.onFallingConversionPre(function(event as FallingConversionPreEvent) {
        if (event.id == "apple") {
            // Example: Double rewards if it is raining
            if (event.world.raining) {
                event.addOutput(<minecraft:nether_star>); // Add an extra Nether Star
            }
            // Example: Cancel if player is unlucky
            if (event.world.random.nextInt(100) < 5) {
                event.cancel(); // Cancel execution, items are not consumed
            }
        }
    }
});

// Post Event: Triggered after the recipe has fully executed
events.onFallingConversionPost(function(event as FallingConversionPostEvent) {
    // Log the location where alchemy occurred
    print(event.position.x ~ "," ~ event.position.y ~ "," ~ event.position.z);
});

Condition System

Condition Types

Special Notes:

• Weather condition auto-correction: When requireThundering=true is set, it will automatically enable the requirement for rain.
• Height condition supports single value mode: addHeightCondition(100) means trigger at exactly Y=100.

Event System

The mod provides Pre (Before execution) and Post (After execution) events, allowing dynamic control via ZenScript.

Import event classes at the start of your script:

import mods.fallingalchemy.event.FallingConversionPreEvent;
import mods.fallingalchemy.event.FallingConversionPostEvent;

1. Pre Event (FallingConversionPreEvent)

Trigger: Recipe matched successfully, just before consumption and output generation. Usage: Cancel recipe, modify outputs, add extra logic.

1. Post Event (FallingConversionPostEvent)

Trigger: After recipe execution is complete and items are generated. Usage: Logging, statistics, spawning extra effects.

// Pre Event Listener
events.onFallingConversionPre(function(event as FallingConversionPreEvent) {

    // Method 1: Check by ID (Recommended)
    // Requires using .register("my_recipe_id") during registration
    if (event.id == "my_recipe_id") {
        if (event.world.raining) {
            event.addOutput(<minecraft:slime_ball>); // Extra output when raining
        }
        return;
    }

    // Method 2: Check by Falling Block
    if (event.fallingBlock.definition.id == "minecraft:anvil") {
        // 5% Chance to fail
        if (event.world.random.nextInt(100) < 5) {
            event.cancel(); 
            print("Alchemy unexpectedly failed!");
        }
    }
});

// Post Event Listener
events.onFallingConversionPost(function(event as FallingConversionPostEvent) {
    print("Alchemy Success! ID: " + event.id + " Pos: " + event.position.x + "," + event.position.y);
});

Sound System

Sound Configuration

// Specify directly in the builder
builder.setSuccessSound("Sound ID", Volume, Pitch);

Sound Parameter Specs:

• Volume Range: 0.1 ~ 2.0 (Default 1.0)
• Pitch Range: 0.5 ~ 2.0 (Default 1.0)
• Resource Format: Use standard Minecraft sound IDs, e.g., "minecraft:entity.lightning.thunder"

FAQ

❓ Recipe not triggering

• Confirm the falling block is registered.
• Check if detection radius covers item positions.
• Verify if set conditions are met.

❓ Sound not playing

• Confirm Sound ID is correct (Use F3+H to view item/sound IDs).
• Check if Volume/Pitch parameters are within legal range.

❓ Multiple input matching issues

• Check NBT matching mode of consumed items.
• Ensure total count of all consumed items meets the requirement.

❓ Priority not working

• Check if priority parameter is set (Default 0).
• High priority recipes should have larger values (e.g., 10 > 5).

Todo

• √ Sound effects for alchemy success/failure
• √ Y-Axis limit conditions
• √ Recipe events
• √ Cross-dimension condition support (Temporarily implementable via Biome conditions)
• - Support for "Alchemy" based on the block the falling block lands on (Can be implemented via events)

License: MIT

Feedback: Submit Issue