CraftEngine

https://github.com/xiao-momi/craft-engine
Admin
CraftEngine is a next-generation solution for custom content implementation that provides APIs and...
Tokens:10,308
Snippets:37
Trust Score:8.3
License:GPL-3.0
Update:9 months ago
Show doc for...
Tokens:
Raw
### Place Custom Blocks Programmatically with CraftEngine (Java)

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

Provides examples of how to place custom blocks in the game world using CraftEngine's API. It covers placing blocks by ID, with custom NBT properties, and specific block states with update options. This functionality requires the CraftEngine API, Bukkit's command handling, and Sparrow's NBT utility.

```java
import net.momirealms.craftengine.bukkit.api.CraftEngineBlocks;
import net.momirealms.craftengine.core.block.CustomBlock;
import net.momirealms.craftengine.core.block.ImmutableBlockState;
import net.momirealms.craftengine.core.block.UpdateOption;
import net.momirealms.craftengine.core.util.Key;
import net.momirealms.sparrow.nbt.CompoundTag;
import org.bukkit.Location;
import org.bukkit.command.Command;
import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;

public class BlockPlacementCommand implements CommandExecutor {

    @Override
    public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
        if (!(sender instanceof Player)) return false;
        Player player = (Player) sender;
        Location target = player.getTargetBlock(null, 10).getLocation();

        // Method 1: Place block by ID (uses default state)
        Key blockId = Key.of("default", "amethyst_torch");
        boolean success = CraftEngineBlocks.place(target, blockId, true);

        if (success) {
            player.sendMessage("Placed amethyst torch!");
        }

        // Method 2: Place block with custom properties
        CompoundTag properties = new CompoundTag();
        properties.putString("facing", "north");
        CraftEngineBlocks.place(target, blockId, properties, true);

        // Method 3: Place specific block state with update options
        CustomBlock block = CraftEngineBlocks.byId(blockId);
        if (block != null) {
            ImmutableBlockState state = block.defaultState();
            CraftEngineBlocks.place(target, state, UpdateOption.UPDATE_ALL, true);
        }

        return true;
    }
}
```

--------------------------------

### Place Furniture Entities (Java)

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This Java code provides examples of placing furniture entities using the Craft Engine API. It shows three methods: simple placement with a default variant, placement with a specified variant and sound option, and placement with custom NBT data. This is useful for programmatic control over furniture in the game world.

```java
import net.momirealms.craftengine.bukkit.api.CraftEngineFurniture;
import net.momirealms.craftengine.bukkit.entity.furniture.BukkitFurniture;
import net.momirealms.craftengine.core.entity.furniture.CustomFurniture;
import net.momirealms.craftengine.core.entity.furniture.FurnitureDataAccessor;
import net.momirealms.craftengine.core.util.Key;
import net.momirealms.sparrow.nbt.CompoundTag;
import org.bukkit.Location;
import org.bukkit.command.Command;
import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;

public class FurniturePlacementCommand implements CommandExecutor {

    @Override
    public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
        if (!(sender instanceof Player)) return false;
        Player player = (Player) sender;
        Location target = player.getLocation();

        // Method 1: Simple placement with default variant
        Key furnitureId = Key.of("default", "wooden_chair");
        BukkitFurniture chair = CraftEngineFurniture.place(target, furnitureId);

        if (chair != null) {
            player.sendMessage("Placed chair at: " + chair.getLocation());
            player.sendMessage("Furniture UUID: " + chair.getUniqueId());
        }

        // Method 2: Place with specific variant
        BukkitFurniture groundChair = CraftEngineFurniture.place(
            target.add(2, 0, 0),
            furnitureId,
            "ground",  // variant name
            true       // play sound
        );

        // Method 3: Place with custom data using CustomFurniture instance
        CustomFurniture furnitureConfig = CraftEngineFurniture.byId(furnitureId);
        if (furnitureConfig != null) {
            CompoundTag customData = new CompoundTag();
            customData.putString("owner", player.getName());
            customData.putString("variant", "ground");

            BukkitFurniture customChair = CraftEngineFurniture.place(
                target.add(4, 0, 0),
                furnitureConfig,
                FurnitureDataAccessor.of(customData),
                true
            );
        }

        return true;
    }
}
```

--------------------------------

### Detecting and Removing Furniture

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This section details how to detect furniture using ray tracing, check its properties, and remove it with options for drops and sound effects.

```APIDOC
## Detecting and Removing Furniture

### Description
This API allows for the detection of furniture entities within a specified range using ray tracing from the player's perspective. It also provides functionality to check various properties of the detected furniture and to remove furniture entities, with options to control whether items are dropped and if a breaking sound is played.

### Methods

**Ray Tracing Furniture**
- **`CraftEngineFurniture.rayTrace(player, distance)`**: Ray traces from the player's position to detect furniture within the specified distance.
  - Returns a `BukkitFurniture` object if furniture is found, otherwise `null`.

**Checking Furniture Properties**
- **`CraftEngineFurniture.isFurniture(entity)`**: Checks if a given Bukkit `Entity` is a furniture entity.
- **`CraftEngineFurniture.isCollisionEntity(entity)`**: Checks if a given Bukkit `Entity` is a collision entity for furniture.
- **`CraftEngineFurniture.isSeat(entity)`**: Checks if a given Bukkit `Entity` represents a seat for furniture.

**Retrieving Furniture Instance**
- **`CraftEngineFurniture.getLoadedFurnitureByMetaEntity(entity)`**: Retrieves the `BukkitFurniture` instance associated with a furniture entity.
- **`CraftEngineFurniture.getLoadedFurnitureByCollider(entity)`**: Retrieves the `BukkitFurniture` instance associated with a furniture collision entity.

**Removing Furniture**
- **`CraftEngineFurniture.remove(entity, player, dropLoot, playBreakSound)`**: Removes a furniture entity.
  - **`entity`** (Entity): The furniture entity to remove.
  - **`player`** (Player): The player who is removing the furniture.
  - **`dropLoot`** (boolean): Whether to drop loot when the furniture is removed.
  - **`playBreakSound`** (boolean): Whether to play a breaking sound when the furniture is removed.
  - Returns `true` if the furniture was successfully removed, `false` otherwise.

### Request Example (Conceptual)

```java
// In a PlayerInteractEvent handler
Player player = event.getPlayer();
BukkitFurniture furniture = CraftEngineFurniture.rayTrace(player, 5.0);

if (furniture != null) {
    // Interact with furniture properties
    player.sendMessage("Looking at furniture: " + furniture.config.id());
}

// In a PlayerInteractEntityEvent handler
Entity clickedEntity = event.getRightClicked();
if (CraftEngineFurniture.isFurniture(clickedEntity)) {
    BukkitFurniture furniture = CraftEngineFurniture.getLoadedFurnitureByMetaEntity(clickedEntity);
    if (furniture != null) {
        CraftEngineFurniture.remove(clickedEntity, player, true, true);
    }
}
```

### Response Example (Conceptual)

**Success Response (when furniture is detected or removed)**
- Console/Chat messages indicating actions and furniture properties.

**Error Response (e.g., furniture not found, removal failed)**
- No specific error response objects shown in the provided Java code, typically handled by returning `null` or `false` from methods, or via exceptions.
```

--------------------------------

### Access CraftEngine Managers in Java

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This Java code snippet shows how to get the main CraftEngine plugin instance and use it to access core managers like BlockManager, ItemManager, FurnitureManager, and PackManager. It also demonstrates accessing the plugin's configuration and state, and triggering a resource pack generation.

```java
import net.momirealms.craftengine.core.plugin.CraftEngine;
import net.momirealms.craftengine.core.block.BlockManager;
import net.momirealms.craftengine.core.item.ItemManager;
import net.momirealms.craftengine.core.entity.furniture.FurnitureManager;
import net.momirealms.craftengine.core.pack.PackManager;
import net.momirealms.craftengine.core.plugin.Config;

public class ManagerAccessExample {

    public void accessManagers() {
        // Get CraftEngine instance
        CraftEngine plugin = CraftEngine.instance();

        // Access various managers
        BlockManager blockManager = plugin.blockManager();
        ItemManager<?> itemManager = plugin.itemManager();
        FurnitureManager furnitureManager = plugin.furnitureManager();
        PackManager packManager = plugin.packManager();

        // Access configuration
        Config config = plugin.config();

        // Check plugin state
        boolean isReloading = plugin.isReloading();
        boolean isInitializing = plugin.isInitializing();

        // Load/reload content
        if (!isReloading) {
            plugin.reload();
        }

        // Generate resource pack manually
        packManager.generateResourcePack();
    }
}

```

--------------------------------

### Handle Furniture Place Event (Java)

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This snippet demonstrates handling the FurniturePlaceEvent. It captures the player, the custom furniture being placed, and its location, then sends a notification message to the player.

```java
import net.momirealms.craftengine.bukkit.api.event.*;
import net.momirealms.craftengine.core.entity.furniture.CustomFurniture;
import org.bukkit.Location;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class CraftEngineEventListener implements Listener {

    @EventHandler
    public void onFurniturePlace(FurniturePlaceEvent event) {
        Player player = event.player();
        CustomFurniture furniture = event.furniture();
        Location location = event.location();

        player.sendMessage("Placed furniture: " + furniture.id() + " at " + location);
    }
}
```

--------------------------------

### Handle Resource Pack Generate Event (Java)

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This snippet shows how to handle the AsyncResourcePackGenerateEvent, which is triggered asynchronously during resource pack generation. It logs a message indicating that the resource pack generation process has started.

```java
import net.momirealms.craftengine.bukkit.api.event.*;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class CraftEngineEventListener implements Listener {

    @EventHandler
    public void onResourcePackGenerate(AsyncResourcePackGenerateEvent event) {
        // Fired during resource pack generation (async)
        getLogger().info("Generating resource pack...");
    }
}
```

--------------------------------

### Placing Custom Blocks Programmatically

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This section details how to place custom blocks into the game world using the CraftEngine API. It covers placing blocks by their ID, with custom properties, and specific block states.

```APIDOC
## POST /api/blocks/place

### Description
Places a custom block at a specified location in the world.

### Method
POST

### Endpoint
/api/blocks/place

### Parameters
#### Path Parameters
None

#### Query Parameters
- **location** (Location) - Required - The world location where the block will be placed.
- **blockId** (Key) - Required - The unique identifier of the custom block to place.
- **properties** (CompoundTag) - Optional - Custom NBT properties to apply to the block.
- **updateOption** (UpdateOption) - Optional - Specifies how block updates should be handled.
- **update** (boolean) - Optional - Whether to trigger block updates.

#### Request Body
```json
{
  "location": {
    "world": "world_name",
    "x": 0.0,
    "y": 64.0,
    "z": 0.0
  },
  "blockId": {
    "namespace": "default",
    "path": "my_custom_block"
  },
  "properties": {
    "facing": "north"
  },
  "updateOption": "UPDATE_NEIGHBORS",
  "update": true
}
```

### Request Example
```java
// Example using Java API (conceptual, actual implementation depends on context)
Location loc = player.getLocation();
Key blockKey = Key.of("default", "amethyst_torch");
CompoundTag props = new CompoundTag();
props.putString("facing", "east");
CraftEngineBlocks.place(loc, blockKey, props, UpdateOption.UPDATE_ALL, true);
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates whether the block placement was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Accessing Loaded Custom Blocks

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This section demonstrates how to retrieve all custom blocks loaded by CraftEngine and access specific blocks by their unique keys. It also shows how to inspect the properties of a loaded block.

```APIDOC
## GET /api/blocks

### Description
Retrieves a map of all custom blocks currently loaded by CraftEngine.

### Method
GET

### Endpoint
/api/blocks

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **blocks** (Map<Key, CustomBlock>) - A map where keys are `net.momirealms.craftengine.core.util.Key` and values are `net.momirealms.craftengine.core.block.CustomBlock` representing the loaded custom blocks.

#### Response Example
```json
{
  "blocks": {
    "default:amethyst_torch": {
      "id": {
        "namespace": "default",
        "path": "amethyst_torch"
      },
      "states": [
        {
          "properties": {
            "facing": "east"
          },
          "luminance": 14
        },
        {
          "properties": {
            "facing": "west"
          },
          "luminance": 14
        }
      ],
      "settings": {
        "luminance": 14
      }
    }
  }
}
```

## GET /api/blocks/{key}

### Description
Retrieves a specific custom block by its unique key.

### Method
GET

### Endpoint
/api/blocks/{key}

### Parameters
#### Path Parameters
- **key** (string) - Required - The unique key of the custom block (e.g., `default:amethyst_torch`).

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **block** (CustomBlock) - The `net.momirealms.craftengine.core.block.CustomBlock` object corresponding to the provided key.

#### Response Example
```json
{
  "block": {
    "id": {
      "namespace": "default",
      "path": "amethyst_torch"
    },
    "states": [
      {
        "properties": {
          "facing": "east"
        },
        "luminance": 14
      }
    ],
    "settings": {
      "luminance": 14
    }
  }
}
```
```

--------------------------------

### Detect and Remove Furniture in Java

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This Java code snippet demonstrates how to detect furniture using ray tracing and how to remove furniture entities with their drops and sounds. It utilizes the CraftEngine API for entity interaction and event handling.

```java
import net.momirealms.craftengine.bukkit.api.CraftEngineFurniture;
import net.momirealms.craftengine.bukkit.entity.furniture.BukkitFurniture;
import org.bukkit.entity.Entity;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerInteractEntityEvent;
import org.bukkit.event.player.PlayerInteractEvent;

public class FurnitureInteractionHandler implements Listener {

    @EventHandler
    public void onPlayerInteract(PlayerInteractEvent event) {
        Player player = event.getPlayer();

        // Ray trace to find furniture player is looking at
        BukkitFurniture furniture = CraftEngineFurniture.rayTrace(player, 5.0);

        if (furniture != null) {
            player.sendMessage("Looking at furniture: " + furniture.config.id());
            player.sendMessage("Location: " + furniture.getLocation());
            player.sendMessage("Variant: " + furniture.dataAccessor.variant());

            // Check if furniture has seats
            if (!furniture.config.seats().isEmpty()) {
                player.sendMessage("This furniture has seats!");
            }
        }
    }

    @EventHandler
    public void onEntityInteract(PlayerInteractEntityEvent event) {
        Entity entity = event.getRightClicked();
        Player player = event.getPlayer();

        // Check if entity is furniture
        if (CraftEngineFurniture.isFurniture(entity)) {
            player.sendMessage("This is a furniture entity!");

            // Get the furniture instance
            BukkitFurniture furniture = CraftEngineFurniture.getLoadedFurnitureByMetaEntity(entity);

            if (furniture != null) {
                player.sendMessage("Furniture ID: " + furniture.config.id());

                // Remove furniture with drops and sound
                boolean removed = CraftEngineFurniture.remove(
                    entity,     // furniture entity
                    player,     // player removing it
                    true,       // drop loot
                    true        // play break sound
                );

                if (removed) {
                    player.sendMessage("Furniture removed!");
                }
            }
        }

        // Check if entity is a collision box
        if (CraftEngineFurniture.isCollisionEntity(entity)) {
            player.sendMessage("This is a furniture collision entity");
            BukkitFurniture furniture = CraftEngineFurniture.getLoadedFurnitureByCollider(entity);
            if (furniture != null) {
                player.sendMessage("Collision for: " + furniture.config.id());
            }
        }

        // Check if entity is a seat
        if (CraftEngineFurniture.isSeat(entity)) {
            player.sendMessage("This is a furniture seat");
        }
    }
}
```

--------------------------------

### Handle Furniture Interact Event (Java)

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This snippet demonstrates handling the FurnitureInteractEvent. It logs the player and the furniture interacted with, sending a message to the player and offering an option to cancel the default interaction.

```java
import net.momirealms.craftengine.bukkit.api.event.*;
import net.momirealms.craftengine.core.entity.furniture.CustomFurniture;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class CraftEngineEventListener implements Listener {

    @EventHandler
    public void onFurnitureInteract(FurnitureInteractEvent event) {
        Player player = event.player();
        CustomFurniture furniture = event.furniture();

        player.sendMessage("Interacted with furniture: " + furniture.id());

        // Cancel default interaction
        // event.setCancelled(true);
    }
}
```

--------------------------------

### Access Loaded Custom Blocks with CraftEngine (Java)

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

Demonstrates how to retrieve all custom blocks loaded by CraftEngine and access specific blocks by their unique keys. This is useful for inspecting the registry or performing actions on existing custom blocks. It requires the CraftEngine API and Bukkit event handling.

```java
import net.momirealms.craftengine.bukkit.api.CraftEngineBlocks;
import net.momirealms.craftengine.bukkit.api.event.CraftEngineReloadEvent;
import net.momirealms.craftengine.core.block.CustomBlock;
import net.momirealms.craftengine.core.util.Key;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import java.util.Map;

public class BlockRegistryListener implements Listener {

    @EventHandler
    public void onCraftEngineReload(CraftEngineReloadEvent event) {
        // Get all loaded custom blocks
        Map<Key, CustomBlock> blocks = CraftEngineBlocks.loadedBlocks();

        for (Map.Entry<Key, CustomBlock> entry : blocks.entrySet()) {
            Key id = entry.getKey();
            CustomBlock block = entry.getValue();

            // Assuming getLogger() is available in the context
            // getLogger().info("Loaded block: " + id + " with " +
            //     block.states().size() + " states");
        }

        // Get specific block by ID
        CustomBlock torch = CraftEngineBlocks.byId(Key.of("default", "amethyst_torch"));
        if (torch != null) {
            // Assuming getLogger() is available in the context
            // getLogger().info("Found amethyst torch with luminance: " +
            //     torch.settings().luminance());
        }
    }
}
```

--------------------------------

### Handle CraftEngine Reload Event (Java)

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This snippet demonstrates how to handle the CraftEngineReloadEvent, which is fired after CraftEngine loads or reloads its content. It logs the number of loaded blocks, items, and furniture.

```java
import net.momirealms.craftengine.bukkit.api.event.*;
import net.momirealms.craftengine.core.block.CustomBlock;
import net.momirealms.craftengine.core.entity.furniture.CustomFurniture;
import org.bukkit.Location;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class CraftEngineEventListener implements Listener {

    @EventHandler
    public void onCraftEngineReload(CraftEngineReloadEvent event) {
        // Fired after CraftEngine loads/reloads all content
        getLogger().info("CraftEngine reloaded!");
        getLogger().info("Loaded " + CraftEngineBlocks.loadedBlocks().size() + " blocks");
        getLogger().info("Loaded " + CraftEngineItems.loadedItems().size() + " items");
        getLogger().info("Loaded " + CraftEngineFurniture.loadedFurniture().size() + " furniture");
    }

    @EventHandler
    public void onCustomBlockPlace(CustomBlockPlaceEvent event) {
        Player player = event.player();
        CustomBlock block = event.customBlock();
        Location location = event.location();

        player.sendMessage("Placed custom block: " + block.id() +
            " at " + location.getBlockX() + "," + location.getBlockY() + "," + location.getBlockZ());

        // Cancel placement if needed
        // event.setCancelled(true);
    }

    @EventHandler
    public void onCustomBlockBreak(CustomBlockBreakEvent event) {
        Player player = event.player();
        CustomBlock block = event.customBlock();
        Location location = event.location();

        player.sendMessage("Broke custom block: " + block.id());

        // Modify drops if needed
        // event.setDropLoot(false);
    }

    @EventHandler
    public void onCustomBlockInteract(CustomBlockInteractEvent event) {
        Player player = event.player();
        CustomBlock block = event.customBlock();

        player.sendMessage("Interacted with: " + block.id());
    }

    @EventHandler
    public void onFurniturePlace(FurniturePlaceEvent event) {
        Player player = event.player();
        CustomFurniture furniture = event.furniture();
        Location location = event.location();

        player.sendMessage("Placed furniture: " + furniture.id() + " at " + location);
    }

    @EventHandler
    public void onFurnitureBreak(FurnitureBreakEvent event) {
        Player player = event.player();
        CustomFurniture furniture = event.furniture();

        player.sendMessage("Broke furniture: " + furniture.id());

        // Control loot drops
        // event.setDropLoot(false);
    }

    @EventHandler
    public void onFurnitureInteract(FurnitureInteractEvent event) {
        Player player = event.player();
        CustomFurniture furniture = event.furniture();

        player.sendMessage("Interacted with furniture: " + furniture.id());

        // Cancel default interaction
        // event.setCancelled(true);
    }

    @EventHandler
    public void onResourcePackGenerate(AsyncResourcePackGenerateEvent event) {
        // Fired during resource pack generation (async)
        getLogger().info("Generating resource pack...");
    }
}
```

--------------------------------

### Handle Custom Block Interact Event (Java)

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This snippet illustrates handling the CustomBlockInteractEvent. It identifies the player and the custom block interacted with, sending a confirmation message to the player.

```java
import net.momirealms.craftengine.bukkit.api.event.*;
import net.momirealms.craftengine.core.block.CustomBlock;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class CraftEngineEventListener implements Listener {

    @EventHandler
    public void onCustomBlockInteract(CustomBlockInteractEvent event) {
        Player player = event.player();
        CustomBlock block = event.customBlock();

        player.sendMessage("Interacted with: " + block.id());
    }
}
```

--------------------------------

### Handle Furniture Break Event (Java)

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This snippet shows how to handle the FurnitureBreakEvent. It identifies the player and the furniture broken, informing the player and providing an option to control loot drops.

```java
import net.momirealms.craftengine.bukkit.api.event.*;
import net.momirealms.craftengine.core.entity.furniture.CustomFurniture;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class CraftEngineEventListener implements Listener {

    @EventHandler
    public void onFurnitureBreak(FurnitureBreakEvent event) {
        Player player = event.player();
        CustomFurniture furniture = event.furniture();

        player.sendMessage("Broke furniture: " + furniture.id());

        // Control loot drops
        // event.setDropLoot(false);
    }
}
```

--------------------------------

### Register External Item Source with CraftEngine (Java)

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This Java code demonstrates how to implement the ExternalItemSource interface to integrate custom items from other plugins into CraftEngine. It requires implementing the plugin(), build(), and id() methods. The registration is done in the plugin's onEnable method.

```java
import net.momirealms.craftengine.bukkit.item.BukkitItemManager;
import net.momirealms.craftengine.core.item.ExternalItemSource;
import net.momirealms.craftengine.core.item.ItemBuildContext;
import org.bukkit.inventory.ItemStack;
import org.bukkit.plugin.java.JavaPlugin;

public class MyItemSourceIntegration implements ExternalItemSource<ItemStack> {

    @Override
    public String plugin() {
        return "MyCustomItemsPlugin";
    }

    @Override
    public ItemStack build(String id, ItemBuildContext context) {
        // Build item from your plugin's API
        // Example: return MyCustomItemsAPI.getItem(id);

        // For demonstration, return null if item not found
        return MyCustomItemsAPI.getItemById(id);
    }

    @Override
    public String id(ItemStack item) {
        // Get your plugin's item ID from an ItemStack
        // Example: return MyCustomItemsAPI.getItemId(item);

        String customId = MyCustomItemsAPI.getItemId(item);
        return customId; // Return null if not from your plugin
    }
}

// In your plugin's onEnable method:
public class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        // Register external item source
        boolean registered = BukkitItemManager.instance()
            .registerExternalItemSource(new MyItemSourceIntegration());

        if (registered) {
            getLogger().info("Successfully integrated with CraftEngine!");
        } else {
            getLogger().warning("Failed to register external item source");
        }
    }
}

// Mock API class for demonstration
class MyCustomItemsAPI {
    public static ItemStack getItemById(String id) {
        // Your implementation
        return null;
    }

    public static String getItemId(ItemStack item) {
        // Your implementation
        return null;
    }
}

```

--------------------------------

### Accessing and Giving Custom Items in Java

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This Java code defines a command executor for giving custom items to players. It utilizes CraftEngineItems.loadedItems() to list available items and BukkitItemManager.instance().buildCustomItemStack() to create item stacks. Players can receive items by specifying their ID in the command arguments. This is useful for in-game shops or custom item distribution systems.

```java
import net.momirealms.craftengine.bukkit.api.CraftEngineItems;
import net.momirealms.craftengine.bukkit.api.BukkitAdaptors;
import net.momirealms.craftengine.bukkit.item.BukkitItemManager;
import net.momirealms.craftengine.core.item.CustomItem;
import net.momirealms.craftengine.core.util.Key;
import org.bukkit.command.Command;
import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;
import org.bukkit.inventory.ItemStack;
import java.util.Map;

public class GiveItemCommand implements CommandExecutor {

    @Override
    public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
        if (!(sender instanceof Player)) return false;
        Player player = (Player) sender;

        if (args.length < 1) {
            // List all available custom items
            Map<Key, CustomItem<ItemStack>> items = CraftEngineItems.loadedItems();
            player.sendMessage("Available items (" + items.size() + "): ");
            items.keySet().forEach(key -> player.sendMessage("  - " + key));
            return true;
        }

        // Build custom item for player
        Key itemId = Key.of("default", args[0]);
        ItemStack item = BukkitItemManager.instance()
            .buildCustomItemStack(itemId, BukkitAdaptors.adapt(player));

        if (item != null) {
            player.getInventory().addItem(item);
            player.sendMessage("Given custom item: " + itemId);
        } else {
            player.sendMessage("Unknown item: " + itemId);
        }

        return true;
    }
}
```

--------------------------------

### Handle Custom Block Place Event (Java)

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This snippet shows how to handle the CustomBlockPlaceEvent. It retrieves the player, custom block, and location, then sends a message to the player indicating the placement. It also includes a commented-out option to cancel the event.

```java
import net.momirealms.craftengine.bukkit.api.event.*;
import net.momirealms.craftengine.core.block.CustomBlock;
import org.bukkit.Location;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class CraftEngineEventListener implements Listener {

    @EventHandler
    public void onCustomBlockPlace(CustomBlockPlaceEvent event) {
        Player player = event.player();
        CustomBlock block = event.customBlock();
        Location location = event.location();

        player.sendMessage("Placed custom block: " + block.id() +
            " at " + location.getBlockX() + "," + location.getBlockY() + "," + location.getBlockZ());

        // Cancel placement if needed
        // event.setCancelled(true);
    }
}
```

--------------------------------

### Define Amethyst Torch Block and Item (YAML)

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This snippet defines the Amethyst Torch as both an item and a block. It includes configurations for item name, texture, behavior, block settings like loot tables and particle effects, and crafting recipes.

```yaml
# File: blocks/amethyst_torch.yml

items:
  default:amethyst_torch:
    data:
      item-name: <!i><l10n:item.amethyst_torch>
    texture: minecraft:block/custom/amethyst_torch
    behavior:
      - type: wall_block_item
        block: default:amethyst_wall_torch
      - type: block_item
        block: default:amethyst_torch

  default:amethyst_standing_torch:
    data:
      item-name: <!i><l10n:item.amethyst_torch>
    model:
      type: minecraft:model
      path: minecraft:block/custom/amethyst_torch
      generation:
        parent: minecraft:block/template_torch
        textures:
          torch: minecraft:block/custom/amethyst_torch

blocks:
  default:amethyst_torch:
    loot:
      template: default:loot_table/basic
      arguments:
        item: default:amethyst_torch
    settings:
      template:
        - default:sound/wood
        - default:hardness/none
      overrides:
        push-reaction: destroy
        replaceable: false
        map-color: 24
        luminance: 15
        item: default:amethyst_torch
    state:
      state: redstone_torch[lit=false]
      entity-renderer:
        item: default:amethyst_standing_torch
        scale: 1.01
    behavior:
      - type: sturdy_base_block
        direction: down
        support-types:
          - center
      - type: liquid_flowable_block
      - type: simple_particle_block
        tick-interval: 10
        particles:
          - particle: smoke
            x: 0.5
            y: 0.7
            z: 0.5
          - particle: dust
            color: 138,43,226
            x: 0.5
            y: 0.7
            z: 0.5

  default:amethyst_wall_torch:
    loot:
      template: default:loot_table/basic
      arguments:
        item: default:amethyst_torch
    settings:
      template:
        - default:sound/wood
        - default:hardness/none
      overrides:
        push-reaction: destroy
        replaceable: false
        luminance: 15
    behavior:
      - type: directional_attached_block
      - type: liquid_flowable_block
      - type: wall_torch_particle_block
        particles:
          - particle: smoke
            x: 0.27
            y: 0.42
            z: 0.27
    states:
      properties:
        facing:
          type: horizontal_direction
      appearances:
        north:
          state: redstone_wall_torch[facing=north,lit=false]
          entity-renderer:
            item: default:amethyst_wall_torch
            scale: 1.04
            yaw: 90
        east:
          state: redstone_wall_torch[facing=east,lit=false]
          entity-renderer:
            item: default:amethyst_wall_torch
            scale: 1.04
            yaw: 180
      variants:
        facing=north:
          appearance: north
        facing=east:
          appearance: east

recipes:
  default:amethyst_torch:
    type: shaped
    pattern:
      - 'A'
      - 'B'
    ingredients:
      A: minecraft:amethyst_shard
      B: minecraft:stick
    result:
      id: default:amethyst_torch
      count: 1

```

--------------------------------

### Handle Custom Block Break Event (Java)

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This snippet demonstrates handling the CustomBlockBreakEvent. It logs the player, custom block, and location, then informs the player about the broken block. It also includes a commented-out option to modify loot drops.

```java
import net.momirealms.craftengine.bukkit.api.event.*;
import net.momirealms.craftengine.core.block.CustomBlock;
import org.bukkit.Location;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class CraftEngineEventListener implements Listener {

    @EventHandler
    public void onCustomBlockBreak(CustomBlockBreakEvent event) {
        Player player = event.player();
        CustomBlock block = event.customBlock();
        Location location = event.location();

        player.sendMessage("Broke custom block: " + block.id());

        // Modify drops if needed
        // event.setDropLoot(false);
    }
}
```

--------------------------------

### Define Wooden Chair Furniture Item (YAML)

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This snippet configures a wooden chair as a piece of furniture. It specifies item properties, model, furniture behavior rules, interaction settings, sound effects, and visual elements like hitboxes and display transformations.

```yaml
# File: furniture/wooden_chair.yml

items:
  default:wooden_chair:
    material: nether_brick
    data:
      item-name: <!i><l10n:item.wooden_chair>
    model: minecraft:item/custom/wooden_chair
    behavior:
      type: furniture_item
      rules:
        ground:
          rotation: any
          alignment: any
      furniture:
        events:
          - template: default:rotatable_furniture_8
        settings:
          item: default:wooden_chair
          sounds:
            break: minecraft:block.bamboo_wood.break
            place: minecraft:block.bamboo_wood.place
        variants:
          ground:
            loot-spawn-offset: 0,0.4,0
            elements:
              - item: default:wooden_chair
                display-transform: NONE
                shadow-radius: 0.4
                shadow-strength: 0.5
                billboard: FIXED
                translation: 0,0.5,0
            hitboxes:
              - position: 0,0,0
                type: interaction
                blocks-building: true
                invisible: true
                width: 0.7
                height: 1.2
                interactive: true
                seats:
                  - 0,0,-0.1 0
        loot:
          template: default:loot_table/furniture
          arguments:
            item: default:wooden_chair

```

--------------------------------

### Convert Bukkit Types to CraftEngine Types using BukkitAdaptors (Java)

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This Java code shows how to use BukkitAdaptors to convert Bukkit objects like Player, World, Block, Entity, and ItemStack into their corresponding CraftEngine types. This allows access to CraftEngine-specific methods and functionalities.

```java
import net.momirealms.craftengine.bukkit.api.BukkitAdaptors;
import net.momirealms.craftengine.bukkit.plugin.user.BukkitServerPlayer;
import net.momirealms.craftengine.bukkit.world.BukkitWorld;
import net.momirealms.craftengine.core.item.Item;
import org.bukkit.Location;
import org.bukkit.World;
import org.bukkit.block.Block;
import org.bukkit.entity.Entity;
import org.bukkit.entity.Player;
import org.bukkit.inventory.ItemStack;

public class AdaptorExample {

    public void convertTypes(Player player, World world, Block block,
                            Entity entity, ItemStack itemStack) {

        // Convert Bukkit Player to CraftEngine ServerPlayer
        BukkitServerPlayer serverPlayer = BukkitAdaptors.adapt(player);

        // Access CraftEngine-specific player methods
        Location eyeLocation = serverPlayer.getEyeLocation();
        double interactionRange = serverPlayer.getCachedInteractionRange();

        // Convert Bukkit World to CraftEngine World
        BukkitWorld craftWorld = BukkitAdaptors.adapt(world);

        // Convert Bukkit Block to CraftEngine ExistingBlock
        var craftBlock = BukkitAdaptors.adapt(block);

        // Convert Bukkit Entity to CraftEngine Entity
        var craftEntity = BukkitAdaptors.adapt(entity);

        // Wrap ItemStack in CraftEngine Item wrapper
        Item<ItemStack> item = BukkitAdaptors.adapt(itemStack);

        // Check if item is custom
        if (item.isCustomItem()) {
            player.sendMessage("Custom item: " + item.customId().orElse(null));
        }
    }
}

```

--------------------------------

### Detect Custom Items and Retrieve IDs (Java)

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This Java snippet demonstrates how to check if an ItemStack is a custom item recognized by Craft Engine. It retrieves the custom item's ID and its associated definition, allowing access to behaviors and settings. It also shows how to check for a specific custom item ID.

```java
import net.momirealms.craftengine.bukkit.api.CraftEngineItems;
import net.momirealms.craftengine.core.item.CustomItem;
import net.momirealms.craftengine.core.util.Key;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerInteractEvent;
import org.bukkit.inventory.ItemStack;

public class CustomItemInteractionHandler implements Listener {

    @EventHandler
    public void onPlayerInteract(PlayerInteractEvent event) {
        Player player = event.getPlayer();
        ItemStack item = event.getItem();

        if (item == null) return;

        // Check if the item is a custom item
        if (CraftEngineItems.isCustomItem(item)) {
            // Get the custom item ID
            Key customId = CraftEngineItems.getCustomItemId(item);
            player.sendMessage("Using custom item: " + customId);

            // Get the CustomItem definition
            CustomItem<ItemStack> customItem = CraftEngineItems.byItemStack(item);
            if (customItem != null) {
                player.sendMessage("Item behaviors: " + customItem.behaviors().size());
                player.sendMessage("Max stack size: " + customItem.settings().maxStackSize());
            }

            // Check for specific custom item
            if (customId != null && customId.equals(Key.of("default", "amethyst_torch"))) {
                player.sendMessage("This is an amethyst torch!");
            }
        }
    }
}
```

--------------------------------

### Checking and Removing Custom Blocks with Loot Drops in Java

Source: https://context7.com/xiao-momi/craft-engine/llms.txt

This Java code demonstrates how to check if a broken block is a custom block using CraftEngineBlocks.isCustomBlock. If it is, the event is cancelled, and the block is removed with its loot drops, sounds, and particles using CraftEngineBlocks.remove. This is useful for custom block implementations that need specific break behaviors.

```java
import net.momirealms.craftengine.bukkit.api.CraftEngineBlocks;
import net.momirealms.craftengine.core.block.CustomBlock;
import net.momirealms.craftengine.core.block.ImmutableBlockState;
import org.bukkit.block.Block;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.block.BlockBreakEvent;

public class CustomBlockBreakHandler implements Listener {

    @EventHandler
    public void onBlockBreak(BlockBreakEvent event) {
        Block block = event.getBlock();
        Player player = event.getPlayer();

        // Check if it's a custom block
        if (CraftEngineBlocks.isCustomBlock(block)) {
            event.setCancelled(true); // Cancel vanilla break

            // Get the custom block state
            ImmutableBlockState state = CraftEngineBlocks.getCustomBlockState(block);
            if (state != null) {
                CustomBlock customBlock = state.owner().value();
                player.sendMessage("Breaking custom block: " + customBlock.id());

                // Remove with proper drops, sounds, and particles
                boolean removed = CraftEngineBlocks.remove(
                    block,      // block to remove
                    player,     // player breaking it
                    true,       // drop loot
                    false,      // is moving (for pistons)
                    true        // play break sound and particles
                );

                if (removed) {
                    player.sendMessage("Custom block removed!");
                }
            }
        }
    }
}
```

--------------------------------

### Configure Maven Repository for CraftEngine API

Source: https://github.com/xiao-momi/craft-engine/blob/main/README.md

This snippet shows how to add the CraftEngine Maven repository to your project's build configuration. This is necessary to fetch the CraftEngine API artifacts.

```gradle
repositories {
    maven("https://repo.momirealms.net/releases/")
}
```

--------------------------------

### Add CraftEngine API Dependencies to Project

Source: https://github.com/xiao-momi/craft-engine/blob/main/README.md

This snippet demonstrates how to include the CraftEngine core and Bukkit API dependencies in your project. These are compile-only dependencies, meaning they are required at compile time but not included in the final runtime artifact.

```gradle
dependencies {
    compileOnly("net.momirealms:craft-engine-core:0.0.66")
    compileOnly("net.momirealms:craft-engine-bukkit:0.0.66")
}
```
Tokens:
Raw