Oraxen

https://docs.oraxen.com
Admin
Oraxen is an open-source Minecraft plugin that enables the creation of custom items, blocks, and...
Tokens:47,854
Snippets:686
Trust Score:6.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Comprehensive hosting configuration example

Source: https://docs.oraxen.com/usage/hosting

A combined configuration example showing settings for all available hosting types.

```yaml
Pack:

  upload:

    enabled: true

    type: polymath #lobfile, polymath, self-host, or external

    polymath:

      server: atlas.oraxen.com # you can also host your own polymath instance

      secret: "oraxen" # change this if you host your own polymath to limit access to resource pack uploading

    lobfile:

      api-key: ""

      pack-name: Oraxen # Will use <pack-name>_<version> when using multi version packs

    self-host:

      host: "0.0.0.0" # The IP address to bind the HTTP server to (0.0.0.0 = listen on all interfaces)

      port: 8080 # The port the HTTP server will listen on

      domain: "localhost:8080" # The domain/IP:port that players will use to download the pack (e.g., "my-server.com:8080" or "192.168.1.100:8080")
```

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

### Full painting configuration example

Source: https://docs.oraxen.com/configuration/paintings

A complete example showing all configuration keys for a single painting entry.

```yaml

paintings:  

  oraxen:edna:  

    author: the_jan_craft  

    title: <red>Edna Painting  

    asset_id: oraxen:edna # This will reference plugins/Oraxen/pack/assets/oraxen/textures/painting/edna.png  

    width: 1  

    height: 1  

    include_in_random: false  


```

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

### Full Configuration Example

Source: https://docs.oraxen.com/compatibility/packlayer

A complete configuration file demonstrating all available settings for PackLayer.

```yaml
# PackLayer Configuration  

   

# Skip Mode - determines how PackLayer decides to skip duplicate packs  

# Options:  

#   HASH_ONLY    - Skip if SHA-1 hash matches (default, recommended)  

#   URL_ONLY     - Skip if URL matches  

#   HASH_OR_URL  - Skip if either hash OR URL matches  

#   HASH_AND_URL - Skip only if both hash AND URL match  

#   ALWAYS_SKIP  - Always skip pack sends (testing only)  

#   NEVER_SKIP   - Never skip (effectively disables plugin)  

skip-mode: HASH_ONLY  

   

# Server Filter - control which backend servers PackLayer applies to  

server-filter:  

  # Mode: DISABLED (all servers), WHITELIST, or BLACKLIST  

  mode: DISABLED  

  # List of server names (as defined in Velocity/BungeeCord config)  

  servers:  

    - lobby  

    - hub  

   

# Trusted Domains - always skip packs from these domains  

# Supports wildcards: *.example.com, cdn.example.com/*  

trusted-domains:  

  # - atlas.oraxen.com  

  # - cdn.example.com  

   

# Grace period (ms) after server switch before applying skip logic  

# Set to 0 to disable. Useful if backend servers intentionally re-send packs.  

server-switch-grace-ms: 0  

   

# Enable debug logging  

debug: false  

   

# Enable statistics tracking (packs skipped, bandwidth saved)  

statistics-enabled: true  
```

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

### Basic Item Configuration

Source: https://docs.oraxen.com/configuration/items/data/properties

Example of a basic item definition with material and name.

```yaml
my_item:  

  material: PAPER  

  itemname: "Cool Item"  
```

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

### Basic Item Component Configuration

Source: https://docs.oraxen.com/configuration/items/data/components

Example of defining a custom item with a specific stack size limit.

```yaml
my_item:  

  material: PAPER  

  Components:  

    max_stack_size: 2  
```

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

### Oraxen Skript Integration Examples

Source: https://docs.oraxen.com/compatibility/skript

A collection of event-based triggers and commands for handling Oraxen items, blocks, and furniture in Skript.

```skript
# Welcome players with a custom item  

on join:  

    give player oraxen item "welcome_gift"  

    send "&aWelcome! You received a custom gift!"  

  

# Custom wand effect  

on right click:  

    if player's tool is oraxen item "magic_wand":  

        strike lightning at target block  

        send "&eZap!" to player  

  

# Protect special blocks  

on oraxen block break of "admin_block":  

    if player does not have permission "oraxen.admin":  

        cancel event  

        send "&cYou don't have permission to break this!" to player  

  

# Custom furniture shop  

on oraxen furniture interact of "shop_counter":  

    open virtual chest inventory with 3 rows named "&6Shop" to player  

    # Add shop items...  

  

# Spawn furniture when placing a special item  

on place of diamond block:  

    if player's tool is oraxen item "furniture_spawner":  

        cancel event  

        place oraxen furniture "diamond_statue" at event-block's location  

        remove 1 of player's tool from player  

  

# Custom ore mining  

on oraxen block break of "ruby_ore":  

    if player's tool is oraxen item "ruby_pickaxe":  

        give player oraxen item "ruby" with amount 3  

    else:  

        cancel event  

        send "&cYou need a Ruby Pickaxe to mine this!" to player  

  

# Command to place furniture  

command /placefurniture <text>:  

    permission: oraxen.placefurniture  

    trigger:  

        place oraxen furniture arg-1 at player's target block  

        send "&aPlaced %arg-1%!" to player
```

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

### Check Version

Source: https://docs.oraxen.com/usage/commands

Displays the currently installed version of Oraxen. Requires the oraxen.command.version permission.

```text
/oraxen version
```

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

### Configure Item Mechanics

Source: https://docs.oraxen.com/configuration/items/mechanics

Example of defining a backpack mechanic within an item configuration file.

```yaml
my_backpack:  

  material: PAPER  

  Mechanics:  

    backpack:  

      rows: 4  

      title: "<red>Backpack"  
```

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

### Define a Glyph Configuration

Source: https://docs.oraxen.com/configuration/glyphs

Example configuration for a custom glyph, defining texture, dimensions, and chat-related settings.

```yaml
farmer:  

  texture: default/chat/farmer  

  ascent: 8  

  height: 8  

  appearance:  

    font: "minecraft:default"  

    shadow_color: "#80000000"  

  chat:  

    tabcomplete: true  

    placeholders:  

      - ":farmer:"  

    permission: oraxen.chat.farmer
```

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

### Listening to Oraxen Events

Source: https://docs.oraxen.com/developers/api

Example of how to implement a Bukkit Listener to handle Oraxen events, specifically the OraxenItemsLoadedEvent.

```APIDOC
## Listening to Oraxen Events

### Description
Oraxen events are standard Bukkit events. You can listen to them by implementing the `Listener` interface and using the `@EventHandler` annotation.

### Example
```java
import io.th0rgal.oraxen.api.events.OraxenItemsLoadedEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class MyListener implements Listener {
    @EventHandler
    public void onItemsLoaded(OraxenItemsLoadedEvent event) {
        // Items were (re)parsed, rebuild your caches here
    }
}
```
```

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

### Configure a HUD element

Source: https://docs.oraxen.com/configuration/glyphs/huds

Example configuration for a balance HUD element, including positioning shifts and font switching.

```yaml
update_time_in_ticks: 40

huds:

  balance:

    permission: "oraxen.hud.balance"

    display_text: "<shift:100><font:balance_hud>%vault_eco_balance%<font:default><glyph:coin>"

    disabled_whilst_in_water: true

    enabled_by_default: true

    enable_for_spectator_mode: true
```

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

### Customized language entries

Source: https://docs.oraxen.com/usage/tutorials/d017g

Example of replacing branded strings with custom text or clearing them.

```json
{

  "menu.game": "",

  "menu.disconnect": "<gray>See you soon!",

  "menu.returnToGame": "Back to the server",

  "resourcePack.server.name": "Resource Pack"

}
```

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

### Manage Chest GUI Measurements

Source: https://docs.oraxen.com/compatibility/bedrock/feather/usage

Commands for starting, stopping, importing, listing, and removing chest GUI measurements.

```text
/feather gui import live
```

```text
/feather gui import live stop
```

```text
/feather gui import <name> [row]
```

```text
/feather gui list
```

```text
/feather gui remove <id>
```

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

### Default branded language entries

Source: https://docs.oraxen.com/usage/tutorials/d017g

Example of the default branded strings found in global.json.

```json
{

  "menu.game": "<glyph:logo>",

  "menu.disconnect": "<shift:-256><gray>See you soon!<shift:-142><glyph:menu_banner><shift:-327>",

  "menu.returnToGame": "Back to the Oraxen experience",

  "resourcePack.server.name": "Vanilla Mod"

}
```

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

### Get Oraxen Furniture Syntax

Source: https://docs.oraxen.com/compatibility/skript

Syntax patterns for retrieving the Oraxen furniture ID from entities, blocks, or locations.

```skript
oraxen furniture at %location/block/entity%  

%location/block/entity%'s oraxen furniture  
```

```skript
set {_furnitureId} to oraxen furniture at target entity  

if oraxen furniture at clicked entity is "wooden_chair":  

    make player sit  
```

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

### Configure AttributeModifiers with Display Modes

Source: https://docs.oraxen.com/configuration/items/data/properties

Examples of using the modern section format for AttributeModifiers to control tooltip visibility and custom text.

```yaml
AttributeModifiers:  
  hidden_armor:  
    attribute: ARMOR  
    amount: 5  
    operation: ADD_NUMBER  
    slot: CHEST  
    display:  
      type: hidden  # Completely hide from tooltip  
```

```yaml
AttributeModifiers:  
  fire_damage:  
    attribute: ATTACK_DAMAGE  
    amount: 10  
    operation: ADD_NUMBER  
    slot: MAINHAND  
    display:  
      type: override  
      text: "<red>+10 Fire Damage"  # Custom MiniMessage tooltip text  
```

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

### Compile the project

Source: https://docs.oraxen.com/developers/compiling

Build the project using the Gradle wrapper. Commands vary by operating system.

```bash
./gradlew build
```

```powershell
./gradlew build
```

```batch
gradlew build
```

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

### Show Recipes

Source: https://docs.oraxen.com/usage/commands

Opens the recipe showcase GUI for all recipes or a specific one.

```text
/oraxen recipes show <all|recipe_name>
```

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

### System Report

Source: https://docs.oraxen.com/usage/commands

Prints a report containing plugin, server, and OS information.

```text
/oraxen report
```

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

### Configure Oraxen welcome sound settings

Source: https://docs.oraxen.com/usage/tutorials/13lfg3

The default configuration for the welcome sound in settings.yml.

```yaml
Pack:  

  receive:  

    enabled: true  

    loaded:  

      actions:  

        sound:  

          enabled: true  

          type: oraxen:welcome  

          volume: 1.0  

          pitch: 1.0  
```

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

### Navigate to project directory

Source: https://docs.oraxen.com/developers/compiling

Change the current working directory to the cloned Oraxen folder.

```bash
cd oraxen
```

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

### Get Oraxen Item Syntax

Source: https://docs.oraxen.com/compatibility/skript

Syntax patterns for retrieving an ItemStack from an Oraxen item ID.

```skript
oraxen item %string%  

oraxen item from id %string%  
```

```skript
give player oraxen item "ruby_sword"  

set {_item} to oraxen item "emerald_pickaxe"  

drop oraxen item "custom_helmet" at player's location  
```

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

### Configure Resource Pack Upload Settings

Source: https://docs.oraxen.com/usage/settings

Sets the backend for hosting the generated resource pack, supporting Polymath, Lobfile, or self-hosting.

```yaml
Pack:  

  upload:  

    enabled: true  

    type: polymath  

    polymath:  

      server: atlas.oraxen.com  

      secret: "oraxen"  

    lobfile:  

      api-key: ""  

      pack-name: Oraxen  

    self-host:  

      host: "0.0.0.0"  

      port: 8080  

      domain: "localhost:8080"
```

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

### Implementing a Custom Hosting Provider

Source: https://docs.oraxen.com/developers/addpackhosting

A template class implementing the HostingProvider interface, supporting both no-args and configuration-based constructors.

```java
import io.th0rgal.oraxen.pack.upload.hosts.HostingProvider;  
import org.bukkit.configuration.ConfigurationSection;  
import java.io.File;  
import java.util.UUID;  

public class MyCustomHostingProvider implements HostingProvider {  

    // Set these during uploadPack  
    private byte[] sha1Bytes;  
    private String sha1String;  
    private UUID packUUID;  

    // Option 1: No-args constructor  
    public MyCustomHostingProvider() {  
        // Initialize with default settings  
    }  

    // Option 2: Configuration constructor (recommended)  
    public MyCustomHostingProvider(ConfigurationSection config) {  
        // Initialize with custom configuration from settings.yml  
        String apiKey = config.getString("api_key");  
        String endpoint = config.getString("endpoint");  
    }  

    @Override  
    public boolean uploadPack(File resourcePack) {  
        // Implement your upload logic here  
        // Return true if upload was successful, false otherwise  
        try {  
            // Your upload implementation  
            return true;  
        } catch (Exception e) {  
            e.printStackTrace();  
            return false;  
        }  
    }  

    @Override  
    public boolean uploadPack(File resourcePack, String packName) {  
        // Optional: use the generated pack name (useful for multi-version packs)  
        return uploadPack(resourcePack);  
    }  

    @Override  
    public String getPackURL() {  
        // Return the public URL where players can download the pack  
        return "https://your-cdn.com/packs/latest.zip";  
    }  

    @Override  
    public byte[] getSHA1() {  
        // Return SHA1 hash as byte array  
        return sha1Bytes;  
    }  

    @Override  
    public String getOriginalSHA1() {  
        // Return SHA1 hash as hex string  
        return sha1String;  
    }  

    @Override  
    public UUID getPackUUID() {  
        // Return unique identifier for this pack version  
        return packUUID;  
    }  
}  
```

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

### Get Oraxen Block Syntax

Source: https://docs.oraxen.com/compatibility/skript

Syntax patterns for retrieving the Oraxen block ID at a specific location.

```skript
oraxen block at %location/block%  

%location/block%'s oraxen block  
```

```skript
set {_blockId} to oraxen block at player's location  

if oraxen block at clicked block exists:  

    broadcast "This is an Oraxen block!"  
```

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

### Configure Welcome Sound in settings.yml

Source: https://docs.oraxen.com/faq

Modify the welcome sound settings within the settings.yml file to enable, disable, or change the sound properties.

```yaml
Pack:  

  receive:  

    loaded:  

      actions:  

        sound:  

          enabled: true  

          type: oraxen:welcome  

          volume: 1.0  

          pitch: 1.0  
```

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

### Get Oraxen ID Syntax

Source: https://docs.oraxen.com/compatibility/skript

Syntax patterns for retrieving the Oraxen ID from various game objects.

```skript
oraxen id of %itemstack/block/entity/location%  

%itemstack/block/entity/location%'s oraxen id  
```

```skript
set {_id} to oraxen id of player's tool  

broadcast "Block ID: %oraxen id of clicked block%"  

if oraxen id of target entity is "treasure_chest":  

    # do something  
```

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

### Implement Custom Mechanic Class

Source: https://docs.oraxen.com/developers/addmechanic

Example implementation of a Mechanic that stores a multiplier value on an item using PersistentDataContainer.

```java
import io.th0rgal.oraxen.OraxenPlugin;  
import io.th0rgal.oraxen.items.ItemBuilder;  
import io.th0rgal.oraxen.mechanics.Mechanic;  
import io.th0rgal.oraxen.mechanics.MechanicFactory;  
import org.bukkit.NamespacedKey;  
import org.bukkit.configuration.ConfigurationSection;  
import org.bukkit.persistence.PersistentDataType;  
  
public class DamageMultiplierMechanic extends Mechanic {  
    public static final NamespacedKey KEY = new NamespacedKey(OraxenPlugin.get(), "damage_multiplier");  
    private final double multiplier;  
  
    public DamageMultiplierMechanic(MechanicFactory factory, ConfigurationSection section) {  
        super(factory, section, (ItemBuilder item) ->  
                item.setCustomTag(KEY, PersistentDataType.DOUBLE, section.getDouble("multiplier", 1.0))  
        );  
        this.multiplier = section.getDouble("multiplier", 1.0);  
    }  
  
    public double getMultiplier() {  
        return multiplier;  
    }  
}
```

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

### Implement a Compatibility Provider

Source: https://docs.oraxen.com/developers/addcompatibility

Create a class extending CompatibilityProvider to handle custom logic, such as integrating MythicMobs drops with Oraxen items.

```java
import io.lumine.mythic.bukkit.MythicBukkit;  

import io.lumine.mythic.bukkit.events.MythicDropLoadEvent;  

import io.lumine.mythic.bukkit.utils.numbers.RandomDouble;  

import io.lumine.mythic.core.drops.Drop;  

import io.th0rgal.oraxen.compatibilities.CompatibilityProvider;  

import io.th0rgal.oraxen.api.OraxenItems;  

import io.th0rgal.oraxen.utils.MythicUtil;  

import org.bukkit.event.EventHandler;  

import org.bukkit.inventory.ItemStack;  

  

public class MythicMobsCompatibility extends CompatibilityProvider<MythicBukkit> {  

      

    @EventHandler  

    public void onMythicDropLoadEvent(MythicDropLoadEvent event) {  

        if (!event.getDropName().equalsIgnoreCase("oraxen")) return;  

  

        String line = event.getContainer().getLine();  

        String itemId = line.split(" ").length >= 2 ? line.split(" ")[1] : "";  

        if (!OraxenItems.exists(itemId)) return;  

  

        ItemStack oraxenItem = OraxenItems.getItemById(itemId).build();  

  

        Drop drop = MythicUtil.getOraxenDrop(line, event.getConfig(), oraxenItem, new RandomDouble("1-1"));  

        event.register(drop);  

    }  

}  
```

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

### Configure FurnitureUpdater settings

Source: https://docs.oraxen.com/usage/settings

Manages synchronization and repair logic for placed furniture items.

```yaml
FurnitureUpdater:  

  update_furniture: true  

  update_on_reload: false  

  update_on_load: false  

  experimental_furniture_type_update: false  

  experimental_fix_broken_furniture: false  
```

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

### Configure Lobfile hosting

Source: https://docs.oraxen.com/usage/hosting

Uses the Lobfile service for hosting, which supports multi-version packs.

```yaml
Pack:

  upload:

    enabled: true

    type: lobfile

    lobfile:

      api-key: ""

      pack-name: "Oraxen"
```

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

### Ingame Recipe Builder Commands

Source: https://docs.oraxen.com/usage/recipes

Commands used to initialize different recipe builders and save the resulting configuration.

```text
/oraxen recipes builder shaped

/oraxen recipes builder shapeless

/oraxen recipes builder furnace <cookingtime> <experience>

/oraxen recipes builder blasting <cookingtime> <experience>

/oraxen recipes builder campfire <cookingtime> <experience>

/oraxen recipes builder smoking <cookingtime> <experience>

/oraxen recipes builder stonecutting

/oraxen recipes save <name> [permission]
```

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

### Configure Material

Source: https://docs.oraxen.com/configuration/items/data/properties

Sets the base material for the item.

```yaml
myitem:  

  material: PAPER  
```

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

### Configure Sound Options

Source: https://docs.oraxen.com/configuration/sounds

Sets properties like volume, pitch, and attenuation distance for the sound entry.

```yaml
sounds:  

  - id: oraxen:welcome  

    sound: welcome  

    volume: 1.0  

    pitch: 1.0  

    weight: 1  

    attenuation_distance: 16  

    preload: false  
```

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

### Iris Dimension Deposit Configuration

Source: https://docs.oraxen.com/compatibility/generators/iris

Example of a standard deposit configuration block within an Iris dimension JSON file.

```json
"deposits": [  

  {  

    "minHeight": 19,  

    "maxPerChunk": 4,  

    "maxHeight": 150,  

    "minPerChunk": 1,  

    "minSize": 25,  

    "maxSize": 25,  

    "palette": [{ "block": "granite" }],  

    "varience": 2  

  }  

]
```

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

### Convert the pack for Bedrock

Source: https://docs.oraxen.com/compatibility/bedrock/feather/usage

Run this command to initiate the conversion process using the generated Oraxen pack.

```text
/feather convert oraxen
```

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

### Configure custom Polymath hosting

Source: https://docs.oraxen.com/usage/hosting

Points Oraxen to a self-hosted Polymath instance.

```yaml
Pack:

  upload:

    enabled: true

    type: polymath

    polymath:

      server: your-domain.example

      secret: "your-secret"
```

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

### Recipe Builder Commands

Source: https://docs.oraxen.com/usage/commands

Opens the interactive recipe builder for various recipe types.

```text
/oraxen recipes builder

/oraxen recipes builder shaped

/oraxen recipes builder shapeless

/oraxen recipes builder furnace <cookingtime> <experience>

/oraxen recipes builder blasting <cookingtime> <experience>

/oraxen recipes builder campfire <cookingtime> <experience>

/oraxen recipes builder smoking <cookingtime> <experience>

/oraxen recipes builder stonecutting
```

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

### Configure Cosmetic Backpack

Source: https://docs.oraxen.com/configuration/items/mechanics

Renders a cosmetic model on the player. Requires global configuration to be enabled.

```yaml
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
```

```yaml
backpack_cosmetic:  

  enabled: true
```

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

### Configure external hosting provider

Source: https://docs.oraxen.com/usage/hosting

Loads a custom class implementing HostingProvider for advanced upload control.

```yaml
Pack:

  upload:

    enabled: true

    type: external

    options:

      class: "com.example.MyHostingProvider"
```

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

### Configure GUI Model

Source: https://docs.oraxen.com/configuration/items/appearance

Sets a specific model for inventory and GUI contexts, while the main model is used for held items.

```yaml
my_item:  

  Pack:  

    model: weapons/swords/ice_sword_3d  

    gui_model: weapons/swords/ice_sword_icon  
```

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

### Configure Global Plugin Settings

Source: https://docs.oraxen.com/usage/settings

Manages housekeeping, language, generation, and MiniMessage formatting settings.

```yaml
Plugin:  

  keep_this_up_to_date: true  

  language: "english"  

  introduction:  

    enabled: true  

    console_sent: false  

  auto_update_paper_config: true  

  generation:  

    default_assets: true  

    default_configs: true  

  formatting:  

    inventory_titles: true  

    titles: true  

    subtitles: true  

    action_bar: true  

    anvil: true  

    signs: true  

    chat: true  

    books: true  
```

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

### Configure the disc item with jukebox_playable

Source: https://docs.oraxen.com/usage/tutorials/23ho7

Define the item in your configuration file using the jukebox_playable component to link the song_key.

```yaml
moonlight_disc:  

  material: MUSIC_DISC_13  

  itemname: "<gold>Moonlight Disc"  

  Pack:  

    model: discs/moonlight_disc  

  Components:  

    jukebox_playable:  

      show_in_tooltip: true  

      song_key: "oraxen:moonlight"  
```

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

### Configure Item Name

Source: https://docs.oraxen.com/configuration/items/data/properties

Sets the display name using MiniMessage formatting.

```yaml
myitem:  

  itemname: "<red>My Cool Item"  
```

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

### Configure bottledexp mechanic

Source: https://docs.oraxen.com/configuration/items/mechanics

Sets the conversion ratio and global durability costs for experience bottling.

```yaml
Mechanics:

  bottledexp:

    ratio: 0.95
```

```yaml
bottledexp:

  enabled: true

  durability_cost: 10
```

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

### Manage Resource Pack

Source: https://docs.oraxen.com/usage/commands

Handles resource pack delivery and default asset extraction. Requires the oraxen.command.pack permission.

```text
/oraxen pack send [targets]

/oraxen pack extract_default [all|textures|models|sounds] [override]
```

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

### HostingProvider Interface

Source: https://docs.oraxen.com/developers/addpackhosting

The interface that must be implemented to create a custom pack hosting provider.

```APIDOC
## Interface: HostingProvider

### Description
Defines the contract for custom resource pack hosting providers. Implementations must handle the upload process and provide metadata about the hosted pack.

### Methods
- **uploadPack(File resourcePack)** (boolean) - Uploads the resource pack file. Returns true on success.
- **uploadPack(File resourcePack, String packName)** (boolean) - Optional override for handling specific pack names.
- **requiresNewInstancePerUpload()** (boolean) - Returns true if a new provider instance is needed for each upload.
- **getPackURL()** (String) - Returns the public URL for the resource pack.
- **getSHA1()** (byte[]) - Returns the SHA1 hash of the pack as a byte array.
- **getOriginalSHA1()** (String) - Returns the SHA1 hash as a hex string.
- **getPackUUID()** (UUID) - Returns the unique identifier for the pack version.
```

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

### Implement CustomCloudHostingProvider

Source: https://docs.oraxen.com/developers/addpackhosting

A template class implementing the HostingProvider interface to handle resource pack uploads and metadata retrieval. Ensure the SHA1 hash is correctly calculated as it is required for Minecraft client verification.

```java
import io.th0rgal.oraxen.pack.upload.hosts.HostingProvider;  

import org.bukkit.configuration.ConfigurationSection;  

import java.io.*;  

import java.net.URI;  

import java.net.http.*;  

import java.nio.file.Files;  

import java.security.MessageDigest;  

import java.util.UUID;  

  

public class CustomCloudHostingProvider implements HostingProvider {  

      

    private final String apiKey;  

    private final String uploadEndpoint;  

    private String packURL;  

    private byte[] sha1Bytes;  

    private String sha1String;  

    private UUID packUUID;  

      

    public CustomCloudHostingProvider(ConfigurationSection config) {  

        this.apiKey = config.getString("api_key", "");  

        this.uploadEndpoint = config.getString("endpoint", "");  

    }  

      

    @Override  

    public boolean uploadPack(File resourcePack) {  

        try {  

            // Calculate SHA1  

            MessageDigest sha1 = MessageDigest.getInstance("SHA-1");  

            byte[] packBytes = Files.readAllBytes(resourcePack.toPath());  

            this.sha1Bytes = sha1.digest(packBytes);  

            this.sha1String = bytesToHex(sha1Bytes);  

            this.packUUID = UUID.randomUUID();  

              

            // Upload to your service  

            HttpClient client = HttpClient.newHttpClient();  

            HttpRequest request = HttpRequest.newBuilder()  

                .uri(URI.create(uploadEndpoint))  

                .header("Authorization", "Bearer " + apiKey)  

                .header("Content-Type", "application/zip")  

                .POST(HttpRequest.BodyPublishers.ofFile(resourcePack.toPath()))  

                .build();  

                  

            HttpResponse<String> response = client.send(request,   

                HttpResponse.BodyHandlers.ofString());  

                  

            if (response.statusCode() == 200) {  

                // Parse response to get pack URL  

                this.packURL = parseUploadResponse(response.body());  

                return true;  

            }  

              

        } catch (Exception e) {  

            e.printStackTrace();  

        }  

        return false;  

    }  

      

    @Override  

    public String getPackURL() {  

        return packURL;  

    }  

      

    @Override  

    public byte[] getSHA1() {  

        return sha1Bytes;  

    }  

      

    @Override  

    public String getOriginalSHA1() {  

        return sha1String;  

    }  

      

    @Override  

    public UUID getPackUUID() {  

        return packUUID;  

    }  

      

    private String bytesToHex(byte[] bytes) {  

        StringBuilder result = new StringBuilder();  

        for (byte b : bytes) {  

            result.append(String.format("%02x", b));  

        }  

        return result.toString();  

    }  

      

    private String parseUploadResponse(String response) {  

        // Parse your API response to extract the pack URL  

        // This depends on your API's response format  

        return response; // Simplified  

    }  

}  
```

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

### Define armor inventory icons

Source: https://docs.oraxen.com/usage/tutorials/h2k8m

List the inventory icon filenames for each piece of the armor set.

```text
ruby_helmet.png  

ruby_chestplate.png  

ruby_leggings.png  

ruby_boots.png  
```

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

### Define a furniture item configuration

Source: https://docs.oraxen.com/usage/tutorials/f4q9x

Basic YAML configuration for a furniture item using the DISPLAY_ENTITY mechanic.

```yaml
wooden_chair:  

  itemname: "<gold>Wooden Chair"  

  material: PAPER  

  Pack:  

    generate_model: false  

    model: furniture/wooden_chair  

  Mechanics:  

    furniture:  

      type: DISPLAY_ENTITY  

      barrier: true  

      hitbox:  

        width: 0.8  

        height: 1.0  

      rotatable: true  

      restricted_rotation: VERY_STRICT  
```

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

### Configure Miscellaneous Global Settings

Source: https://docs.oraxen.com/usage/settings

Manages global toggles for recipes, scoreboard/tablist visuals, and custom item display transformations.

```yaml
Misc:  

  reset_recipes: true  

  add_recipes_to_book: true  

  hide_scoreboard_numbers: false  

  hide_scoreboard_background: false  

  hide_tablist_background: false  

  armor_equip_event_bypass:  

    - FURNACE  

    - CHEST  

    - TRAPPED_CHEST  

  shield_display: '{"thirdperson_righthand":{"rotation":[0,90,0],"translation":[10,6,-4],"scale":[1,1,1]}}'  

  bow_display: '{"thirdperson_righthand":{"rotation":[-80,260,-40],"translation":[-1,-2,2.5],"scale":[0.9,0.9,0.9]}}'  

  crossbow_display: '{"thirdperson_righthand":{"rotation":[-90,0,-60],"translation":[2,0.1,-3],"scale":[0.9,0.9,0.9]}}'
```

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

### Configure Lore

Source: https://docs.oraxen.com/configuration/items/data/properties

Sets multiple lines of lore for the item.

```yaml
myitem:  

  lore:  

    - "<gold>My Cool Item"  

    - "<gray>Some extra description"  
```

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

### Define a CompatibilityProvider Class

Source: https://docs.oraxen.com/developers/addcompatibility

Base structure for creating a compatibility provider that manages plugin lifecycle and event listening.

```java
public class CompatibilityProvider<T extends Plugin> implements Listener {  

    protected String pluginName;  

    protected T plugin;  

    protected boolean isEnabled;  

  

    public void enable(String pluginName) {  

        // Called when target plugin is detected  

        // Registers this provider as a Bukkit listener  

    }  

  

    public void disable() {  

        // Called when compatibility is disabled  

        // Unregisters this provider's listeners  

    }  

}  
```

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

### Configure self-hosted HTTP server

Source: https://docs.oraxen.com/usage/hosting

Serves the resource pack directly from the Minecraft server machine. Multi-version packs are not supported with this method.

```yaml
Pack:

  upload:

    enabled: true

    type: self-host

    self-host:

      host: "0.0.0.0"

      port: 8080

      domain: "your-domain.example:8080"
```

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

### Configure MythicHUD pack path

Source: https://docs.oraxen.com/compatibility/mythichud

Set the copy_path in the MythicHUD configuration to point to the Oraxen uploads directory.

```yaml
copy-pack:  

  enabled: true  

  path: Oraxen/pack/uploads/MythicHud.zip  
```

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

### Configure Skip Mode

Source: https://docs.oraxen.com/compatibility/packlayer

Defines the logic used to detect duplicate resource packs. HASH_ONLY is the recommended default.

```yaml
# Skip Mode - determines how PackLayer decides to skip duplicate packs  

# Options:  

#   HASH_ONLY    - Skip if SHA-1 hash matches (default, recommended)  

#   URL_ONLY     - Skip if URL matches  

#   HASH_OR_URL  - Skip if either hash OR URL matches  

#   HASH_AND_URL - Skip only if both hash AND URL match  

#   ALWAYS_SKIP  - Always skip pack sends (testing only)  

#   NEVER_SKIP   - Never skip (effectively disables plugin)  

skip-mode: HASH_ONLY  
```

```yaml
skip-mode: HASH_ONLY  
```

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

### Configure Animated Glyphs

Source: https://docs.oraxen.com/configuration/glyphs

Sets up sprite sheet animations by defining frame count, playback speed, looping behavior, and horizontal offsets.

```yaml
animation:  

  frames: 12  

  fps: 12  

  loop: true  

  offset: 0    
```

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

### Define Item Appearance Configuration

Source: https://docs.oraxen.com/configuration/items/appearance

Defines the material, display name, and resource pack model paths for a custom item.

```yaml
ice_sword:  

  material: IRON_SWORD  

  itemname: "<gradient:#80d9ff:#1c7fd1>Ice Sword"  

  Pack:  

    model: weapons/swords/ice_sword  

    gui_model: weapons/swords/ice_sword_icon  

    generate_model: false  

    custom_model_data: 120001  

    models:  

      active: weapons/swords/ice_sword_active  

    damaged_textures:  

      - weapons/swords/ice_sword_cracked_1  

      - weapons/swords/ice_sword_cracked_2
```

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

### Configure a custom painting item

Source: https://docs.oraxen.com/usage/tutorials/491d3

Create an item configuration that utilizes the painting_variant component to link to the registered painting key.

```yaml
edna_painting:  

  material: PAINTING  

  itemname: "<gold>Edna Painting"  

  Components:  

    painting_variant: "oraxen:edna"  
```

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

### Configure ConfigsTools

Source: https://docs.oraxen.com/usage/settings

Controls model-data, glyph-code generation, and fallback item behavior.

```yaml
ConfigsTools:  

  skipped_model_data_numbers: []  

  disable_automatic_model_data: false  

  disable_automatic_glyph_code: false  

  error_item:  

    material: PODZOL  

    excludeFromInventory: false  

    injectId: false  
```

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

### Define a custom item with components

Source: https://docs.oraxen.com/configuration/items/data/components

Configuration for a custom item including food nutrition, consumption mechanics, and cooldowns.

```yaml
myitem:  

  itemname: "<gold>Traveler's Meal"  

  material: BREAD  

  Components:  

    max_stack_size: 16  

    fire_resistant: false  

    food:  

      nutrition: 8  

      saturation: 9.6  

      can_always_eat: true  

    consumable:  

      consume_seconds: 1.6  

      animation: "eat"  

      sound: "entity.generic.eat"  

      has_consume_particles: true  

    use_remainder:  

      minecraft_type: "BOWL"  

      amount: 1  

    use_cooldown:  

      seconds: 1.0  

      group: "food_items"  

    tooltip_style: "oraxen:food/meal"  

    item_model: "oraxen:food/travelers_meal"
```

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

### Configure Miscellaneous Item Behaviors

Source: https://docs.oraxen.com/configuration/items/mechanics

Toggles various vanilla-like behaviors for the item.

```yaml
Mechanics:  

  misc:  

    breaks_from_cactus: true  

    burns_in_fire: true  

    burns_in_lava: true  

    disable_vanilla_interactions: false  

    can_strip_logs: false  

    piglins_ignore_when_equipped: false  

    compostable: false  

    allow_in_vanilla_recipes: true  

    prevent_renaming: true
```

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

### Define a Stonecutting Recipe

Source: https://docs.oraxen.com/usage/recipes

Simple recipe mapping one input item to one output item.

```yaml
polished_obsidian:  

  result:  

    oraxen_item: polished_obsidian_tile  

  input:  

    minecraft_type: OBSIDIAN
```

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

### Save Recipe

Source: https://docs.oraxen.com/usage/commands

Saves the current recipe builder state to disk with an optional permission requirement.

```text
/oraxen recipes save <name> [permission]
```

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

### Dump Logs

Source: https://docs.oraxen.com/usage/commands

Uploads the latest log file to mclo.gs for troubleshooting.

```text
/oraxen dump-log
```

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

### Open Item Browser

Source: https://docs.oraxen.com/usage/commands

Opens the Oraxen item browser GUI. Requires the oraxen.command.inventory.view permission.

```text
/oraxen inventory

/oraxen inv
```

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

### Manual trim configuration

Source: https://docs.oraxen.com/usage/tutorials/g7p4t

Settings to apply if auto_assign_settings is disabled.

```yaml
trim_pattern: oraxen:ruby  

ItemFlags:  

  - HIDE_ARMOR_TRIM  
```

```yaml
ruby_helmet:  

  itemname: "<red>Ruby Helmet"  

  material: CHAINMAIL_HELMET  

  trim_pattern: oraxen:ruby  

  ItemFlags:  

    - HIDE_ARMOR_TRIM  
```

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

### Change the welcome sound type

Source: https://docs.oraxen.com/usage/tutorials/13lfg3

Replace the type value with a valid Minecraft sound key to play a different sound.

```yaml
Pack:  

  receive:  

    enabled: true  

    loaded:  

      actions:  

        sound:  

          enabled: true  

          type: minecraft:block.note_block.pling  

          volume: 1.0  

          pitch: 1.0  
```

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

### Configure Resource Pack Status Feedback

Source: https://docs.oraxen.com/usage/settings

Defines actions to execute based on the status of the resource pack download and loading process.

```yaml
Pack:  

  receive:  

    enabled: true  

    loaded:  

      actions:  

        sound:  

          enabled: true  

          type: oraxen:welcome  

          volume: 1.0  

          pitch: 1.0  

        delay: 5  

        message:  

          enabled: false  

          type: ACTION_BAR  

          content: "<#55ffa4><bold>ResourcePack loaded"  

        commands:  

          console: []  

          player: []  

          opped_player: []  

    accepted:  

      actions:  

        message:  

          enabled: false  

          type: ACTION_BAR  

          content: "<#55ffa4><bold>ResourcePack accepted"  

        commands:  

          console: []  

          player: []  

          opped_player: []  

    denied:  

      actions:  

        message:  

          enabled: false  

          type: CHAT  

          content: "<red>You refused the ResourcePack..."  

        commands:  

          console: []  

          player: []  

          opped_player: []  

    failed_download:  

      actions:  

        message:  

          enabled: false  

          type: CHAT  

          content: "<red>You failed to download the ResourcePack..."  

        commands:  

          console: []  

          player: []  

          opped_player: []  

    failed_reload:  

      actions:  

        commands:  

          console: []  

          player: []  

          opped_player: []  

    downloaded:  

      actions:  

        commands:  

          console: []  

          player: []  

          opped_player: []  

    invalid_url:  

      actions:  

        commands:  

          console: []  

          player: []  

          opped_player: []  

    discarded:  

      actions:  

        commands:  

          console: []  

          player: []  

          opped_player: []
```

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

### Configure Toggle Light Mechanic

Source: https://docs.oraxen.com/configuration/items/mechanics

Adds interactive light levels to furniture and blocks that toggle on right-click.

```yaml
Mechanics:  

  toggle_light:  

    light: 5  

    toggle_light: 15  
```

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

### Implement Custom Compatibility Class

Source: https://docs.oraxen.com/developers/addcompatibility

Extend CompatibilityProvider to handle specific integration logic and event handling for a target plugin.

```java
import io.th0rgal.oraxen.compatibilities.CompatibilityProvider;  
import io.th0rgal.oraxen.OraxenPlugin;  
import org.bukkit.event.EventHandler;  

  

public class MyPluginCompatibility extends CompatibilityProvider<MyTargetPlugin> {  

      

    @Override  

    public void enable(String pluginName) {  

        super.enable(pluginName);  

        // Initialize your integration here  

        // Event listeners are automatically registered  

        OraxenPlugin.get().getLogger().info("MyPlugin compatibility enabled!");  

    }  

      

    @Override  

    public void disable() {  

        super.disable();  

        // Clean up your integration here  

        // Event listeners are automatically unregistered  

        OraxenPlugin.get().getLogger().info("MyPlugin compatibility disabled!");  

    }  

      

    @EventHandler  

    public void onMyPluginEvent(MyPluginEvent event) {  

        // Handle integration events here  

        // This will only be called when compatibility is enabled  

    }  

}  
```

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

### Configure Item Model Path

Source: https://docs.oraxen.com/configuration/items/appearance

Defines the path to a model JSON file relative to pack/models/.

```yaml
my_item:  

  Pack:  

    model: weapons/swords/ice_sword  
```

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

### Generation Configuration

Source: https://docs.oraxen.com/usage/settings

The YAML configuration block for defining resource pack generation behavior.

```yaml
Pack:

  generation:

    generate: true

    disable_mcmeta_generation: false

    multi_version_packs: false

    excluded_file_extensions: []

    appearance:

      item_properties: true

      model_data_ids: false

      model_data_float: false

      generate_predicates: false

    verify_pack_files: true

    fix_force_unicode_glyphs: true

    atlas:

      exclude_malformed_from_atlas: true

      generate: true

      type: "SPRITE"

    auto_generated_models_follow_texture_path: false

    compression: BEST_COMPRESSION

    obfuscation:

      type: NONE

    protection: true

    comment: "The content of this texture pack\n..."
```

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

### Configure display entity properties

Source: https://docs.oraxen.com/usage/tutorials/f4q9x

Adjust the scale and translation of a display-entity furniture model.

```yaml
Mechanics:  

  furniture:  

    type: DISPLAY_ENTITY  

    display_entity_properties:  

      scale:  

        x: 0.8  

        y: 0.8  

        z: 0.8  

      translation:  

        x: 0  

        y: 0.1  

        z: 0  
```

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

### Define a custom sound entry in sounds.yml

Source: https://docs.oraxen.com/usage/tutorials/d31l5f

Add a new sound event by specifying an id, category, and the path to the audio file within the sounds list.

```yaml
sounds:  

  - id: oraxen:welcome  

    category: records  

    sound: welcome.ogg  
```

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

### Manage Resource Packs with OraxenPack

Source: https://docs.oraxen.com/developers/api

Interact with the resource pack lifecycle, including retrieving the pack file, reloading, and uploading.

```java
import io.th0rgal.oraxen.api.OraxenPack;  

import java.io.File;  

  

public class MyPack {  

    public File getPackFile() {  

        return OraxenPack.getPack();  

    }  

  

    public void reload() {  

        OraxenPack.reloadPack();  

    }  

  

    public void upload() {  

        OraxenPack.uploadPack();  

    }  

}  
```

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

### Configure Legacy Display Name

Source: https://docs.oraxen.com/configuration/items/data/properties

Sets the legacy display name. This property is deprecated.

```yaml
myitem:  

  displayname: "<red>My Cool Item"  
```

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

### Configure Oraxen Sounds

Source: https://docs.oraxen.com/configuration/sounds

Define custom sounds with jukebox properties or replace existing game sounds using the YAML configuration format.

```yaml
settings:  

  automatically_generate: true  

  

sounds:  

  - id: oraxen:welcome  

    category: records  

    sound: welcome.ogg  

    stream: true  

    subtitle: "Welcome Song"  

    jukebox:  

      description: "<gold>Welcome <yellow>Song</yellow></gold>"  

      duration: 180s  

      comparator_output: 12  

      range: 8  

  

  - id: block.wood.place  

    replace: true  

  

  - id: block.wood.break  

    replace: true
```

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

### Reload Oraxen and enable datapack

Source: https://docs.oraxen.com/usage/tutorials/g7p4t

Commands to reload Oraxen and enable the generated trim datapack.

```text
/oraxen reload all  
```

```text
/datapack enable "file/oraxen_trim_armor"  
```

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

### Convert Custom Resource Pack

Source: https://docs.oraxen.com/compatibility/bedrock/feather/usage

Converts a resource pack ZIP file from a specified custom path. Requires the featherconvert.use permission.

```text
/feather convert --input=<file>
```

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

### Set painting author

Source: https://docs.oraxen.com/configuration/paintings

Define the author using MiniMessage formatting.

```yaml

paintings:  

  oraxen:edna:  

    author: the_jan_craft  


```

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

### Regenerate the Oraxen pack

Source: https://docs.oraxen.com/compatibility/bedrock/feather/usage

Execute this command in-game or via console to apply configuration changes.

```text
/oraxen reload pack
```

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

### Set painting title

Source: https://docs.oraxen.com/configuration/paintings

Define the display title using MiniMessage formatting.

```yaml

paintings:  

  oraxen:edna:  

    title: Edna  


```

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

### Enable Oversized GUI Rendering

Source: https://docs.oraxen.com/configuration/items/appearance

Allows the item to be rendered in an oversized format within GUI contexts.

```yaml
my_item:  

  Pack:  

    oversized_in_gui: true  
```

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

### Update Language Keys

Source: https://docs.oraxen.com/usage/tutorials/c82mx

Point the menu.game language key to the custom glyph in global.json.

```json
{

  "menu.game": "<glyph:esc_logo>",

  "menu.disconnect": "<gray>See you soon!",

  "menu.returnToGame": "Back to the server"

}
```

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

### Configure Item Template

Source: https://docs.oraxen.com/configuration/items/data/properties

Inherit properties from another item or define a reusable template.

```yaml
myitem:  

  template: base_sword  
```

```yaml
base_sword:  

  template: true  

  material: IRON_SWORD  
```
Tokens:
Raw