# Table of Contents - [Welcome to Oraxen docs | Oraxen Docs](#welcome-to-oraxen-docs-oraxen-docs) - [Frequently Asked Questions | Oraxen Docs](#frequently-asked-questions-oraxen-docs) - [Custom Items | Oraxen Docs](#custom-items-oraxen-docs) - [Creating Content | Oraxen Docs](#creating-content-oraxen-docs) - [Item Appearance | Oraxen Docs](#item-appearance-oraxen-docs) - [Item Components | Oraxen Docs](#item-components-oraxen-docs) - [Dyeable Items | Oraxen Docs](#dyeable-items-oraxen-docs) - [All Mechanics | Oraxen Docs](#all-mechanics-oraxen-docs) - [Combat Mechanics | Oraxen Docs](#combat-mechanics-oraxen-docs) - [Unknown](#unknown) - [Custom Mechanic | Oraxen Docs](#custom-mechanic-oraxen-docs) - [Miscellaneous Mechanics | Oraxen Docs](#miscellaneous-mechanics-oraxen-docs) - [Farming Mechanics | Oraxen Docs](#farming-mechanics-oraxen-docs) - [Shader Based Armors (1.18-1.19.4) | Oraxen Docs](#shader-based-armors-1-18-1-19-4-oraxen-docs) - [Backpack Cosmetic | Oraxen Docs](#backpack-cosmetic-oraxen-docs) - [Custom Block Mechanics | Oraxen Docs](#custom-block-mechanics-oraxen-docs) - [ClickAction Mechanic | Oraxen Docs](#clickaction-mechanic-oraxen-docs) - [NoteBlock | Oraxen Docs](#noteblock-oraxen-docs) - [ChorusBlock Mechanic | Oraxen Docs](#chorusblock-mechanic-oraxen-docs) - [StringBlock | Oraxen Docs](#stringblock-oraxen-docs) - [Furniture | Oraxen Docs](#furniture-oraxen-docs) - [Furniture Position | Oraxen Docs](#furniture-position-oraxen-docs) - [Commands | Oraxen Docs](#commands-oraxen-docs) - [Default Items | Oraxen Docs](#default-items-oraxen-docs) - [Display Entity Furniture | Oraxen Docs](#display-entity-furniture-oraxen-docs) - [FarmBlock Mechanic | Oraxen Docs](#farmblock-mechanic-oraxen-docs) - [ShapedBlock | Oraxen Docs](#shapedblock-oraxen-docs) - [Plant Evolution / Farming Mechanic | Oraxen Docs](#plant-evolution-farming-mechanic-oraxen-docs) - [Custom Armors | Oraxen Docs](#custom-armors-oraxen-docs) - [Component Based Armors (1.21.2+) | Oraxen Docs](#component-based-armors-1-21-2-oraxen-docs) - [Trims Based Armors (1.20-1.21.1) | Oraxen Docs](#trims-based-armors-1-20-1-21-1-oraxen-docs) - [World Generators | Oraxen Docs](#world-generators-oraxen-docs) - [Custom GUI | Oraxen Docs](#custom-gui-oraxen-docs) - [Glyphs & HUD Elements | Oraxen Docs](#glyphs-hud-elements-oraxen-docs) - [Custom HUD | Oraxen Docs](#custom-hud-oraxen-docs) - [Plugin API | Oraxen Docs](#plugin-api-oraxen-docs) - [GLSL Customization | Oraxen Docs](#glsl-customization-oraxen-docs) - [Branding & Customization | Oraxen Docs](#branding-customization-oraxen-docs) - [Text Effects | Oraxen Docs](#text-effects-oraxen-docs) - [Resource Pack Hosting | Oraxen Docs](#resource-pack-hosting-oraxen-docs) - [Understanding the Basics | Oraxen Docs](#understanding-the-basics-oraxen-docs) - [Plugin Settings | Oraxen Docs](#plugin-settings-oraxen-docs) - [Resource Pack Merging Guide | Oraxen Docs](#resource-pack-merging-guide-oraxen-docs) - [sound.yml Configuration | Oraxen Docs](#sound-yml-configuration-oraxen-docs) - [Crucible | Oraxen Docs](#crucible-oraxen-docs) - [Recipes | Oraxen Docs](#recipes-oraxen-docs) - [ModelEngine | Oraxen Docs](#modelengine-oraxen-docs) - [MythicHUD | Oraxen Docs](#mythichud-oraxen-docs) - [MMOItems | Oraxen Docs](#mmoitems-oraxen-docs) - [PackLayer - Proxy Resource Pack Optimization | Oraxen Docs](#packlayer-proxy-resource-pack-optimization-oraxen-docs) - [MythicMobs | Oraxen Docs](#mythicmobs-oraxen-docs) - [Iris World Generator | Oraxen Docs](#iris-world-generator-oraxen-docs) - [Skript Integration | Oraxen Docs](#skript-integration-oraxen-docs) - [Custom Ore Generator | Oraxen Docs](#custom-ore-generator-oraxen-docs) - [BossShopPro | Oraxen Docs](#bossshoppro-oraxen-docs) - [Terralith Datapack Integration | Oraxen Docs](#terralith-datapack-integration-oraxen-docs) - [Archived Compatibilities | Oraxen Docs](#archived-compatibilities-oraxen-docs) - [CrateReloaded | Oraxen Docs](#cratereloaded-oraxen-docs) - [TrMenu | Oraxen Docs](#trmenu-oraxen-docs) - [EpicWorldGenerator | Oraxen Docs](#epicworldgenerator-oraxen-docs) - [Custom Hosting Service | Oraxen Docs](#custom-hosting-service-oraxen-docs) - [Create Your Own Compatibility | Oraxen Docs](#create-your-own-compatibility-oraxen-docs) - [RealisticWorldGenerator | Oraxen Docs](#realisticworldgenerator-oraxen-docs) - [API | Oraxen Docs](#api-oraxen-docs) - [Custom Mechanics | Oraxen Docs](#custom-mechanics-oraxen-docs) - [Vendor Guidelines | Oraxen Docs](#vendor-guidelines-oraxen-docs) --- # Welcome to Oraxen docs | Oraxen Docs [Skip to Content](https://docs.oraxen.com/#nextra-skip-nav) Getting Started Copy page Welcome to Oraxen docs ====================== _Looking for the old documentation? Visit the [legacy GitBook site](http://oraxen.gitbook.io/)  ._ **Are you an AI?** Check [/llms.txt](https://docs.oraxen.com/llms.txt) or add `.md` to any page URL to get raw markdown and save tokens. What Is Oraxen?[](https://docs.oraxen.com/#what-is-oraxen) ----------------------------------------------------------- Oraxen is a Minecraft plugin which allows the creation of new items & blocks using custom textures and models. It also handles resourcepack generation, upload and storage (using Polymath), and is entirely open source with an extensible API. How Does It All Work?[](https://docs.oraxen.com/#how-does-it-all-work) ----------------------------------------------------------------------- When a Spigot server starts with Oraxen installed, the plugin will read all the item configurations (your .yml files inside /plugins/oraxen/items) and use them to generate .json models that link your .png textures to your new items. After this, Oraxen zips the resources using an optimized algorithm and uploads it to a polymath instance. Polymath is a free and opensource software written in Python to host Minecraft resourcepacks. By default Oraxen will use an Oraxen supplied Polymath instance, hosted in Switzerland on an oracle virtual private server. Whenever a player connects to your server, Oraxen will link them to the polymath instance which then sends them the resourcepack. Install Oraxen In Seconds![](https://docs.oraxen.com/#install-oraxen-in-seconds) --------------------------------------------------------------------------------- Installing Oraxen is a fairly straight forward process: 1. Drop the Oraxen .jar file into your `/plugins/` folder. 2. Restart your server. ### Auto-Downloaded Dependencies[](https://docs.oraxen.com/#auto-downloaded-dependencies) Oraxen automatically downloads required dependencies at runtime: * **CommandAPI** - Downloaded automatically for your server version * **PacketEvents** - Downloaded automatically with the correct version for your Minecraft setup ### Optional Dependencies[](https://docs.oraxen.com/#optional-dependencies) * **[ProtocolLib](https://www.spigotmc.org/resources/protocollib.1997/)**  - Recommended but not mandatory. That’s it! Although, we highly recommend heading into your settings.yml config and making any desired adjustments (then restarting once more) before continuing! Oraxen has been tested with Spigot and Paper 1.18 -> 1.21.6 (Paper 1.21.11+ fully supported) For Minecraft 1.21.2+, using the latest version of Oraxen is advised. Oraxen is developed and designed for use with [Paper](https://mcserverjars.com/paper)  , [Spigot](https://mcserverjars.com/spigot)  , or [Folia](https://papermc.io/software/folia)   server software. Download server jars from [MCServerJars.com](https://mcserverjars.com/)  . For older Minecraft versions, start by installing Oraxen 1.183.0 to get compatible configuration files. You can then update the jar file accordingly. ### Folia Support[](https://docs.oraxen.com/#folia-support) Oraxen includes native support for [Folia](https://papermc.io/software/folia)  , PaperMC’s multithreaded server fork. On Folia servers, Oraxen automatically uses region-based and entity-based schedulers to ensure thread-safe operations. No additional configuration is required - Oraxen will detect Folia at startup and use the appropriate scheduling APIs. Next Steps[](https://docs.oraxen.com/#next-steps) -------------------------------------------------- Once installed, explore the documentation: * **[Creating Content](https://docs.oraxen.com/creating-content) ** - Create custom items, blocks, furniture, armors, and UI elements * **[Plugin Setup](https://docs.oraxen.com/plugin-setup/understanding-the-basics) ** - Configure plugin settings, pack hosting, and more * **[Commands & Recipes](https://docs.oraxen.com/usage/commands) ** - Learn the available commands and how to create recipes * **[Compatibility](https://docs.oraxen.com/compatibility/crucible) ** - Integrate with other plugins like MythicMobs, MMOItems, and world generators Last updated on January 3, 2026 [FAQ](https://docs.oraxen.com/faq "FAQ") --- # Frequently Asked Questions | Oraxen Docs [Skip to Content](https://docs.oraxen.com/faq#nextra-skip-nav) FAQ Copy page Frequently Asked Questions ========================== ### Is Oraxen A Mod?[](https://docs.oraxen.com/faq#is-oraxen-a-mod) No, Oraxen is not a mod in the usual sense of the word. It’s a minecraft plugin that allows you to add items, blocks and similar kinds of cool stuff to the game - all with an automatically installed resource pack. ### Does Oraxen Support Folia?[](https://docs.oraxen.com/faq#does-oraxen-support-folia) Yes! Oraxen has native support for [Folia](https://papermc.io/software/folia)  , PaperMC’s multithreaded server fork. Oraxen automatically detects Folia at startup and uses region-based and entity-based schedulers to ensure all operations are thread-safe. No additional configuration is needed. ### Oraxen Is Using Its Own Resource Pack, Can I Still Use Mine?[](https://docs.oraxen.com/faq#oraxen-is-using-its-own-resource-pack-can-i-still-use-mine) Yes. More information about how to do this can be found [here](https://docs.oraxen.com/plugin-setup/pack-merging)   ### I Use Bungee/Velocity But The Pack Keeps Reloading When Players Switch Servers?[](https://docs.oraxen.com/faq#i-use-bungeevelocity-but-the-pack-keeps-reloading-when-players-switch-servers) This is because the player technically leaves one server and joins another. Therefore, Minecraft removes and sends the resourcepack. If you want to prevent this you can get [BungeePackLayer](https://www.spigotmc.org/resources/%E2%9C%82%EF%B8%8F-bungee-pack-layer-optimize-resource-pack-sending.94978/)  . This is a Bungee/Velocity plugin which will prevent the pack from being resent (unless it is different). A pack will be different if the config files on all servers are not identical. ### Can I Disable The Default Assets And Configs Oraxen Comes With?[](https://docs.oraxen.com/faq#can-i-disable-the-default-assets-and-configs-oraxen-comes-with) Absolutely. Your `settings.yml` file contains options to disable both of these: `Plugin: generation: default_assets: false # Disables default textures/models/sounds default_configs: false # Disables default item configurations` **Note:** Required files will still be generated even when disabled: * `glyphs/required.yml` - Contains essential UI glyphs (exit icons, etc.) * Core plugin configurations (settings.yml, mechanics.yml, etc.) When `default_assets: false`, Oraxen will NOT generate: * 13 default item config files (armors, blocks, weapons, furniture, etc.) * Default textures and models in the resource pack * 5 glyph files (emoji, interface, animations, chat\_tags) When `default_configs: false`, only the required glyph file and core configs remain. ### How Do I Disable Or Change The Welcome Sound?[](https://docs.oraxen.com/faq#how-do-i-disable-or-change-the-welcome-sound) Of course, `settings.yml` contains configurable actions to perform when the pack is sent to a user, including a sound by default. The example below shows where you can disable or change the sound as you desire. To **disable** the sound, set `enabled: false`. To **change** the sound, modify the `type`, `volume`, or `pitch` values. `receive: enabled: true loaded: actions: sound: # Set to false to disable the welcome sound # Set to true to enable the welcome sound enabled: true type: minecraft:welcome # Change this to use a different sound volume: 1.0 # 0.0 to 1.0 pitch: 1.0 # 0.5 to 2.0` ### Does Oraxen Replace Any Vanilla Items?[](https://docs.oraxen.com/faq#does-oraxen-replace-any-vanilla-items) The goal of Oraxen is to add things to the game without losing features, so the short answer is no. However, Minecraft has some limitations (you can’t really add new blocks or armors for example) so we had to make a choice (a choice that can be undone by disabling the related mechanics): - new blocks will use vanilla unused noteblock variations: this can create issues in constructions made using those unusual variations. ### When I Add An Item, Why Does It Break The Textures Of Others Already Created?[](https://docs.oraxen.com/faq#when-i-add-an-item-why-does-it-break-the-textures-of-others-already-created) By default (pre 1.21.4), Oraxen automatically picks custom model data values for your items and generates them in the most optimized way. Every item, which does not use the exact same model, needs to have a different custom model data value. When adding a new item to Oraxen and setting it’s custom model data value manually, you can break other items by accidentally setting the same value on two or more different items. Don’t forget to reload the plugin with `/o reload all` **AND** your resource pack using `/o pack send @a`(you can also disconnect and reconnect to the server) ### Why Do My Textures Work When I Use Optifine But Not In Vanilla?[](https://docs.oraxen.com/faq#why-do-my-textures-work-when-i-use-optifine-but-not-in-vanilla) It is no longer possible to use upper case in folder, texture or model names with vanilla resource packs since minecraft 1.11, however optifine still supports it. Please never use upper case to avoid problems. ### How Do I Update Oraxen?[](https://docs.oraxen.com/faq#how-do-i-update-oraxen) Here is a great video that can help you: [https://youtu.be/LkansZwVaPY](https://youtu.be/LkansZwVaPY)   ### How Do I Hide Item Tooltips?[](https://docs.oraxen.com/faq#how-do-i-hide-item-tooltips) [https://github.com/lolgeny/item-tooltip-remover](https://github.com/lolgeny/item-tooltip-remover)   ### Where Do I Suggest New Features Or Report An Issue?[](https://docs.oraxen.com/faq#where-do-i-suggest-new-features-or-report-an-issue) First option: Login to github and submit an issue to the official repo: [git.io/oraxen](https://github.com/Th0rgal/Oraxen)   Second option: Join [the discord](https://discord.gg/2ng6q3JNQ7)  , get your Oraxen verified rank, then go to the support channel where you can open a ticket. ### How Do I Just Use Oraxen’s Mechanics?[](https://docs.oraxen.com/faq#how-do-i-just-use-oraxens-mechanics) Go to your settings.yml file and set the following options: `upload: enabled: false Pack: generation: generate: false compression: BEST_COMPRESSION protection: false dispatch: send_pack: false enable_configs_updater: false Misc: reset_recipes: false auto_update_items: false` The configurations do not go in that exact order. Once you’ve changed these lines, delete what is inside the /Oraxen/pack, /Oraxen/items and /Oraxen/glyphs paths and restart the server. Last updated on January 3, 2026 [Getting Started](https://docs.oraxen.com/ "Getting Started") [Overview](https://docs.oraxen.com/creating-content "Overview") --- # Custom Items | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/items#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") ItemsGetting Started Copy page Custom Items ============ Oraxen lets you create custom items with unique textures, models, and abilities. Items are the foundation of all custom content in Oraxen. What You Can Create[](https://docs.oraxen.com/creating-content/items#what-you-can-create) ------------------------------------------------------------------------------------------ | Item Type | Examples | Key Features | | --- | --- | --- | | Weapons | Swords, axes, bows | Custom damage, abilities, durability | | Tools | Pickaxes, shovels, hoes | Mining abilities, custom efficiency | | Food | Custom consumables | Hunger, effects, custom eating | | Materials | Gems, ingots, components | For crafting recipes | | Equipment | Armor pieces | See [Custom Armors](https://docs.oraxen.com/creating-content/armors) | Configuration Overview[](https://docs.oraxen.com/creating-content/items#configuration-overview) ------------------------------------------------------------------------------------------------ | Section | Purpose | Documentation | | --- | --- | --- | | `displayname` | Item name with colors | Use MiniMessage format | | `material` | Base Minecraft item | Any valid material | | `Pack` | Textures and models | [Item Appearance](https://docs.oraxen.com/creating-content/items/appearance) | | `Components` | Vanilla data components | [Components](https://docs.oraxen.com/creating-content/items/components) | | `Mechanics` | Special abilities | [Abilities](https://docs.oraxen.com/creating-content/items/abilities) | Basic Item Structure[](https://docs.oraxen.com/creating-content/items#basic-item-structure) -------------------------------------------------------------------------------------------- `my_item: displayname: "My Item" material: DIAMOND_SWORD Pack: generate_model: true parent_model: "item/handheld" textures: - my_item.png Mechanics: durability: value: 2000` Place your texture files in the `plugins/Oraxen/pack/textures/` folder. Oraxen automatically generates the resource pack. Next Steps[](https://docs.oraxen.com/creating-content/items#next-steps) ------------------------------------------------------------------------ * [Item Appearance](https://docs.oraxen.com/creating-content/items/appearance) - Textures, models, and custom visuals * [Components](https://docs.oraxen.com/creating-content/items/components) - Enchantments, attributes, lore * [Abilities](https://docs.oraxen.com/creating-content/items/abilities) - Special powers and mechanics * * * Tutorial: Create Your First Item[](https://docs.oraxen.com/creating-content/items#tutorial-create-your-first-item) ------------------------------------------------------------------------------------------------------------------- Let’s create a custom Onyx Axe step by step. 1\. Let’s start by creating textures[](https://docs.oraxen.com/creating-content/items#1-lets-start-by-creating-textures) ------------------------------------------------------------------------------------------------------------------------- For this tutorial I will make a simple item in 2d and Oraxen will generate the model, but if you want you can use software like [cubik.studio](https://cubik.studio/)   (paid) or [blockbench](https://www.blockbench.net/)   (free + opensource) which are both excellent. Here’s what I did in 16x16 (so it still looks like vanilla minecraft) on Photoshop: ![photoshop screenshot](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fphotoshop.7dc8f6a5.png&w=3840&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) I then save the file under the name _onyx\_axe.png_. 2\. The basic configuration[](https://docs.oraxen.com/creating-content/items#2-the-basic-configuration) -------------------------------------------------------------------------------------------------------- I couldn’t decide where to add my axe (is it more of a tool or a weapon?) so I created my **super\_cool\_items.yml** file under items directory. Here is what I wrote: `onyx_axe: displayname: "<#6f737d>Onyx Axe" material: DIAMOND_AXE` So I put a name to my item and chose to use the diamond axe as a base. In the [Components](https://docs.oraxen.com/creating-content/items/components) section you will see many other possibilities of additional modifications (like how to use enchantments, itemflags, attributes, etc). 3\. Let’s assign the texture to the item[](https://docs.oraxen.com/creating-content/items#3-lets-assign-the-texture-to-the-item) --------------------------------------------------------------------------------------------------------------------------------- Normally you would need to create json files manually: one for the model and another to specify when to display it. With Oraxen, you just specify the textures for your item. Oraxen handles all the resource pack generation automatically—see [Item Appearance](https://docs.oraxen.com/creating-content/items/appearance) for full details. `onyx_axe: displayname: "Onyx Axe" material: DIAMOND_AXE Pack: generate_model: true parent_model: "item/handheld" textures: - onyx_axe.png` As you can see I’ve set parent\_model to “item/handheld”, it is the parent model used by tools while the one used by stuff like diamonds for example is “item/generated”, this is what defines how the item appears in the hand (if you don’t do this your weapon may be held weridly). I also need to drag my **onyx\_axe.png** texture into the **/pack/textures** folder of Oraxen. From this configuration I could normally already restart the server and see my item but I want to add cool powers to it. You can also use a json model to create 3d items, see [Item Appearance](https://docs.oraxen.com/creating-content/items/appearance) for the documentation. 4\. Let’s improve our item with mechanics[](https://docs.oraxen.com/creating-content/items#4-lets-improve-our-item-with-mechanics) ----------------------------------------------------------------------------------------------------------------------------------- In the configuration of each item you can add a mechanics section and add lots of cool things in it. By the way, if you find that there are not enough cool features (although I try to add as many as possible) you can add some via other plugins that use Oraxen’s api (see [Create your own Mechanic](https://docs.oraxen.com/developers/mechanics) ). I would like my axe to have a huge durability and to be able to break bedrock. Here is what I wrote: `onyx_axe: displayname: "Onyx Axe" material: DIAMOND_AXE Pack: generate_model: true parent_model: "item/handheld" textures: - onyx_axe.png Mechanics: durability: value: 20000 bedrockbreak: delay: 0 period: 10 probability: 0.5` A durability of 20,000 is ludicrous, to compare diamond tools have a 1,561 one. I put a probability of 0.5 for loot when you mine the bedrock with it because I want the bedrock block to remain difficult to obtain. For some mechanics it is necessary to use ProtocolLib, this is the case for bedrockbreak 5\. Let’s try it![](https://docs.oraxen.com/creating-content/items#5-lets-try-it) ---------------------------------------------------------------------------------- I begin by restarting the server and when it is good I will install the texture pack.zip pack generated in the /pack/ folder of Oraxen. I give myself the axe from the inventory via /o inv and this is what I get: ![Me and my onyx axe](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2F2019-11-01_10.02.47.57f41680.png&w=1920&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) I’m also able to mine bedrock: ![Me breaking bedrock with my onyx axe](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2F2019-11-01_10.03.22.cda359d8.png&w=1920&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) If you have come this far, congratulations you have created your own item 👍 ### Video Tutorial[](https://docs.oraxen.com/creating-content/items#video-tutorial) Last updated on January 3, 2026 [Overview](https://docs.oraxen.com/creating-content "Overview") [Appearance & Models](https://docs.oraxen.com/creating-content/items/appearance "Appearance & Models") --- # Creating Content | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content#nextra-skip-nav) Creating ContentOverview Copy page Creating Content ================ Oraxen allows you to create a wide variety of custom content for your Minecraft server. This section covers everything you need to know about creating: Content Types[](https://docs.oraxen.com/creating-content#content-types) ------------------------------------------------------------------------ | Type | Description | Get Started | | --- | --- | --- | | [Items](https://docs.oraxen.com/creating-content/items) | Custom weapons, tools, food, and more | Start here for basic custom content | | [Blocks](https://docs.oraxen.com/creating-content/blocks) | Custom ores, decorative blocks, plants | Choose between NoteBlock, StringBlock, or ChorusBlock | | [Furniture](https://docs.oraxen.com/creating-content/furniture) | 3D models like chairs, tables, machines | For complex interactable objects | | [Armors](https://docs.oraxen.com/creating-content/armors) | Custom armor sets with unique textures | Multiple methods for different MC versions | | [Glyphs & HUD](https://docs.oraxen.com/creating-content/glyphs-hud) | Custom emojis, GUI textures, HUD elements | For UI customization | Quick Start[](https://docs.oraxen.com/creating-content#quick-start) -------------------------------------------------------------------- New to Oraxen? Follow this recommended learning path: 1. **[Understanding the Basics](https://docs.oraxen.com/plugin-setup/understanding-the-basics) ** - Learn how Oraxen works 2. **[Create Your First Item](https://docs.oraxen.com/creating-content/items) ** - Make a simple custom item 3. **[Item Appearance](https://docs.oraxen.com/creating-content/items/appearance) ** - Add textures and models 4. **[Add Abilities](https://docs.oraxen.com/creating-content/items/abilities) ** - Give your items special powers How Content Creation Works[](https://docs.oraxen.com/creating-content#how-content-creation-works) -------------------------------------------------------------------------------------------------- All custom content in Oraxen follows a similar pattern: `my_custom_item: displayname: "My Item" material: DIAMOND_SWORD Pack: generate_model: true parent_model: "item/handheld" textures: - my_texture.png Mechanics: # Add special abilities here` 1. **Define the item** - Set display name, base material 2. **Configure appearance** - Textures, models, colors 3. **Add mechanics** - Special abilities and behaviors 4. **Test in-game** - Use `/oraxen reload` and `/oraxen give` Last updated on January 17, 2026 [FAQ](https://docs.oraxen.com/faq "FAQ") [Getting Started](https://docs.oraxen.com/creating-content/items "Getting Started") --- # Item Appearance | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/items/appearance#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Items](https://docs.oraxen.com/creating-content/items "Items") Appearance & Models Copy page Item Appearance =============== Unlike most other plugins that allow you to create custom items, Oraxen supports the creation of a texture pack: you can define directly in the configuration what you want your items to look like and it will take care of generating the pack. For Minecraft, the appearance of each item is managed by a json file called the model. Oraxen can generate these files automatically. ### How Oraxen handles item models[](https://docs.oraxen.com/creating-content/items/appearance#how-oraxen-handles-item-models) Oraxen supports multiple systems for item appearance on 1.21.4+. **These systems can be combined** for maximum compatibility. Pre-1.21.4 servers always use legacy predicate overrides. **Default behavior:** * **Pre-1.21.4**: Legacy predicates (forced, regardless of settings) * **1.21.4+**: Item Model Definitions (`item_properties: true`) ### Appearance Systems (1.21.4+)[](https://docs.oraxen.com/creating-content/items/appearance#appearance-systems-1214) On 1.21.4+, you can enable multiple appearance systems in `settings.yml`: `Pack: generation: appearance: item_properties: true # Use item_model component (default) model_data_ids: false # Use custom_model_data.strings with select model_data_float: false # Use custom_model_data.floats with range_dispatch generate_predicates: false # Generate legacy predicates (not needed on 1.21.4+)` **Available systems:** | Setting | Pack Output | Item Component | Use Case | | --- | --- | --- | --- | | `item_properties` | `assets/oraxen/items/.json` | `item_model` component | **Default.** Clean 1.21.4+ setup using item model definitions. | | `model_data_ids` | `assets/minecraft/items/.json` | `custom_model_data.strings[0]` | Uses `minecraft:select` with string keys (`oraxen:`). Good for CMD-based workflows with stable identifiers. | | `model_data_float` | `assets/minecraft/items/.json` | `custom_model_data.floats[0]` | Uses `minecraft:range_dispatch` with numeric thresholds. Sets integer CMD on items. | | `generate_predicates` | `assets/minecraft/models/item/*.json` | — | Generates legacy predicate overrides. **Not needed on 1.21.4+.** | **Which systems should I enable?** * **`item_properties` only** — Best for new setups. Clean, modern, no collision with other plugins. * **`item_properties` + `model_data_ids`** — Hybrid setup. Items have both `item_model` component AND `custom_model_data.strings[0]` set. * **`model_data_float` + `generate_predicates`** — Full legacy compatibility with predicate overrides and integer CMD. ### Combining Systems[](https://docs.oraxen.com/creating-content/items/appearance#combining-systems) You can enable multiple systems to set multiple components on items: `appearance: item_properties: true # Sets item_model component model_data_ids: true # Also sets custom_model_data.strings[0]` This gives you the best of both worlds: native 1.21.4+ rendering via `item_model`, plus `custom_model_data` strings for plugins that read them. **Note:** `model_data_ids` and `model_data_float` cannot both be enabled—they write to the same pack file path (`assets/minecraft/items/*.json`). If both are enabled, `model_data_ids` takes priority for pack generation. ### Legacy Predicate Generation[](https://docs.oraxen.com/creating-content/items/appearance#legacy-predicate-generation) The `generate_predicates` option generates legacy predicate overrides (`assets/minecraft/models/item/*.json`): `appearance: model_data_float: true # Use float-based CMD generate_predicates: true # Also generate legacy predicates` **When do I need `generate_predicates`?** On 1.21.4+, Minecraft uses the new item definition system (`assets/minecraft/items/*.json`), so legacy predicate overrides are **not required** for the game client to display custom models. Only enable `generate_predicates` if: * External tools need to read legacy predicate JSON files * You’re using pack analysis tools that don’t support 1.21.4+ item definitions * You need backward compatibility with older resource pack formats ### Per-Item System Exclusions[](https://docs.oraxen.com/creating-content/items/appearance#per-item-system-exclusions) You can exclude specific items from either system: `my_item: Pack: generate_model: true textures: - my_texture exclude_from_predicates: false # Don't add to predicate file exclude_from_item_model: false # Don't generate item model definition` **Use cases:** * `exclude_from_predicates: true` - Item only uses item\_model (cleaner pack) * `exclude_from_item_model: true` - Item only uses CMD (for plugin compatibility) ### **Advanced**: How each system works **Item Model Definitions (1.21.4+)** Oraxen generates files in `assets/oraxen/items/` for each custom item. For example, an item with ID `my_sword` creates: `assets/oraxen/items/my_sword.json` This file defines which model to display. Items are then given an `item_model` component pointing to `oraxen:my_sword`. If you need a custom namespace or model path, you can override this using the Components section: `my_item: Components: item_model: "custom:weapons/legendary_sword"` This would reference `assets/custom/items/weapons/legendary_sword.json` in the resource pack. **Predicates (Custom Model Data)** Oraxen generates predicate overrides in the base item model files (e.g., `assets/minecraft/models/item/diamond_sword.json`). Each custom item gets a `custom_model_data` value that maps to its model. ### The pack folder[](https://docs.oraxen.com/creating-content/items/appearance#the-pack-folder) This folder (./plugins/Oraxen/pack) contains your pack. It works like a normal minecraft texture pack but simpler. You can drag your textures into the textures folder and your models into your models folder. You can also create sub-folders inside these folders to make it cleaner but it’s not necessary. When the plugin generates the resource pack it appears in this folder under the name pack.zip. ### Create a simple 2d item[](https://docs.oraxen.com/creating-content/items/appearance#create-a-simple-2d-item) Put the textures that you need in the textures directory of the pack folder. You can then ask Oraxen to generate the model by superposing the textures : `Pack: generate_model: true parent_model: "item/handheld" textures: - example_image1.png #png extension is not needed - example_image2.png` The `parent_model` field is required by Minecraft. It allows your item to inherit the rendering properties of an item template. Common values are `item/handheld` for weapons like swords, and `item/generated` for simple items or gems like amethysts. You can also use an alternative way of declaring textures, especially nice when using block parent-models. `Pack: generate_model: true parent_model: "block/cube" textures: top: example_image.png side: example_image2.png` ### Use a json model[](https://docs.oraxen.com/creating-content/items/appearance#use-a-json-model) Creating a json model can be time-consuming but it allows you to create really cool things (like 3d items). It is really easy to integrate a json model with Oraxen : put your textures in your textures directory and your model in your models directory (inside Oraxen/pack folder). Then you can ask Oraxen to put this model on one of your items: ALWAYS USE LOWER CASE FOR MODEL AND TEXTURE NAMES. Upper case is n longer supported by minecraft vanilla since 1.11 (even though it still works for users using optifine). `Pack: generate_model: false model: example_model.json #json extension is not mandatory` #### ⚠️ Pro tips when you use a json model![](https://docs.oraxen.com/creating-content/items/appearance#%EF%B8%8F-pro-tips-when-you-use-a-json-model) Usually the templates you get place the textures in a folder, to make sure, open the json file and look at the first few lines, you should find something similar: `{ "__comment": "Designed by HighBridRed for Oraxen", "textures": { "particle": "custom/bonesword_palette", "texture": "custom/bonesword_palette", "bonesword_palette": "custom/bonesword_palette" }, ...` As you can see, the path to the texture is **custom/bonesword\_palette**, that means minecraft will be looking for a texture called **bonesword\_palette.png** in the folder “custom”, so you need to create this folder inside “Oraxen/pack/textures”. You can also remove “custom/” and keep the texture name only, so you just have to drag and drop it inside the textures folder without creating a subfolder. ### Use a blocking json model (for shield)[](https://docs.oraxen.com/creating-content/items/appearance#use-a-blocking-json-model-for-shield) If you want to use a custom model for a shield, you need to specific the blocking model which will be used when a user right click using your shield, hopefully this is easy with Oraxen. Here is what it can look like: `Pack: generate_model: false model: example_shield.json #json extension is not mandatory blocking_model: example_shield_blocking.json #json extension is not mandatory` ### Use a pulling json model (for bows)[](https://docs.oraxen.com/creating-content/items/appearance#use-a-pulling-json-model-for-bows) If you want to use a custom model for a shield, you need to specific the pulling model which will be used when a user right click using your bow, hopefully this is easy with Oraxen. Here is what it can look like: `Pack: generate_model: false model: default/combat_bow pulling_models: - default/combat_bow_pulling_0 - default/combat_bow_pulling_1 - default/combat_bow_pulling_2` This also works with pulling\_textures if you only have texture files ### Use charged\_model json model (for Crossbows)[](https://docs.oraxen.com/creating-content/items/appearance#use-charged_model-json-model-for-crossbows) `Pack: generate_model: false model: default/custom_bow pulling_models: - default/custom_bow_pulling_0 - default/custom_bow_pulling_1 - default/custom_bow_pulling_2 charged_model: default/custom_bow_pulling_2 firework_model: default/custom_bow_charged #not so necessary` This also works with charged\_texture & firework\_texture if you only have texture files ### Use cast\_model json model (for fishing rods)[](https://docs.oraxen.com/creating-content/items/appearance#use-cast_model-json-model-for-fishing-rods) `Pack: generate_model: false model: default/fishing_rod cast_model: default/fishing_rod_cast` This also works with cast\_texture if you only have texture files ### Use damaged\_model json model (for different durability levels)[](https://docs.oraxen.com/creating-content/items/appearance#use-damaged_model-json-model-for-different-durability-levels) `Pack: generate_model: false model: default/diamond_sword damaged_models: - default/diamond_sword_damaged1 - default/diamond_sword_damaged2 - default/diamond_sword_damaged3` This also works with damaged\_textures if you only have texture files ### Use advanced model properties (Minecraft 1.21.4+)[](https://docs.oraxen.com/creating-content/items/appearance#use-advanced-model-properties-minecraft-1214) Since Minecraft 1.21.4, you can customize additional item model properties: **GUI-Only Models (1.21.2+)** Define a separate model that only appears in GUI/inventory contexts using the `gui_model` option. This uses Minecraft’s `display_context` selector to show different models when held/equipped versus displayed in inventories. `Pack: generate_model: false model: item/held_sword # Model when held or equipped gui_model: item/gui_sword # Model in inventories and GUIs` When a player holds or wears the item, the `model` is used. When viewing in inventories, crafting tables, or item frames, the `gui_model` is displayed instead. This is useful for: * Icons that look better in inventory than the 3D held model * Simplified GUI versions of complex 3D models * Different perspectives for items (e.g., top-down view in inventory, side view when held) **GUI Oversize** Allows items to extend beyond slot boundaries in GUI when scaled up `Pack: generate_model: false model: item/large_item oversized_in_gui: true` When combined with a scaled display model like this, it creates an item that stands out prominently in inventory slots. `{ "parent": "item/handheld", "textures": { "layer0": "default/welcome_disk" }, "display": { "gui": { "translation": [-2, -2, 0], "scale": [2, 2, 2] } } }` See how oversized rendering looks in practice. ![model-definitions-showcase.png](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fmodel-definitions-showcase.fae332d9.png&w=1920&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) Here is an example use case provided by Wollodriin. ![model-definitions-use-case.png](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fmodel-definitions-use-case.68d84fd2.png&w=828&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) **Hand Swap Animation** Controls whether hand animation plays when swapping items (only when switching from an item to another item) `Pack: generate_model: false model: item/example_item hand_animation_on_swap: false` **Hand Swap Animation Scale** Adjusts the scale of the swap animation `Pack: generate_model: false model: item/example_item swap_animation_scale: 1.5` ### Setting a specific Custom Model Data[](https://docs.oraxen.com/creating-content/items/appearance#setting-a-specific-custom-model-data) You can manually specify a custom model data value: `my_item: Pack: generate_model: true parent_model: "item/generated" textures: - my_texture custom_model_data: 452` On 1.21.4+, this value is used when `model_data_float` is enabled (see [Appearance Systems](https://docs.oraxen.com/creating-content/items/appearance#appearance-systems-1214) above). This lets you control which CMD value your item uses for compatibility with other plugins. Last updated on January 17, 2026 [Getting Started](https://docs.oraxen.com/creating-content/items "Getting Started") [Components](https://docs.oraxen.com/creating-content/items/components "Components") --- # Item Components | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/items/components#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Items](https://docs.oraxen.com/creating-content/items "Items") Components Copy page Item Components =============== Since Minecraft 1.20.5, items use data-driven components instead of NBT tags. Oraxen supports these components through the `Components` section in your item configuration. Components are version-specific. Make sure to check the sections below for the components available in your Minecraft version. * * * Basic Components[](https://docs.oraxen.com/creating-content/items/components#basic-components) ----------------------------------------------------------------------------------------------- These components are available in all versions supporting components (1.20.5+). ### durability[](https://docs.oraxen.com/creating-content/items/components#durability) Sets custom durability for an item. For non-tool materials (like PAPER), you can also configure when durability is consumed. SimpleAdvanced ### Simple `Components: durability: 100` ### Advanced `Components: durability: value: 100 damage_block_break: true # Consume durability when breaking blocks damage_entity_hit: true # Consume durability when hitting entities` ### fire\_resistant[](https://docs.oraxen.com/creating-content/items/components#fire_resistant) Makes the item immune to fire and lava damage. `Components: fire_resistant: true` ### hide\_tooltip[](https://docs.oraxen.com/creating-content/items/components#hide_tooltip) Hides all tooltips when hovering over the item. `Components: hide_tooltip: true` * * * Tool Component[](https://docs.oraxen.com/creating-content/items/components#tool-component) ------------------------------------------------------------------------------------------- Configure mining behavior for tool-like items. `Components: tool: damage_per_block: 1 # Durability consumed per block (default: 1) default_mining_speed: 1.0 # Base mining speed (default: 1.0) rules: - speed: 2.0 correct_for_drops: true # Whether blocks drop items material: DIAMOND_BLOCK # Single material # Or use a list: # materials: # - DIAMOND_BLOCK # - NETHERITE_BLOCK tag: minecraft:mineable/axe # Block tag # Or use a list: # tags: # - minecraft:mineable/axe # - minecraft:mineable/shovel` See [Minecraft Wiki - Block Tags](https://minecraft.wiki/w/Tag#Block_tags_2)   for all available block tags. * * * Food & Consumable Components[](https://docs.oraxen.com/creating-content/items/components#food--consumable-components) ---------------------------------------------------------------------------------------------------------------------- Make items edible or consumable with various effects. 1.21.2+1.20.5 - 1.21 ### 1.21.2+ In 1.21.2+, food and consumable behaviors are split into separate components for more flexibility. ### consumable[](https://docs.oraxen.com/creating-content/items/components#consumable) Makes the item consumable with detailed control over the consumption behavior. SimpleFull Example ### Simple `Components: consumable: true` ### Full Example `Components: consumable: consume_seconds: 1.6 # Time to consume (default: 1.6) animation: EAT # EAT, DRINK, BLOCK, BOW, SPEAR, CROSSBOW, SPYGLASS, TOOT_HORN, BRUSH sound: entity.generic.eat # Sound played when consuming has_consume_particles: true # Show particles while consuming on_consume_effects: # Effects applied when consumed - type: apply_effects effects: minecraft:haste: duration: 200 # Duration in seconds (converted to ticks internally) amplifier: 0 ambient: false show_particles: true show_icon: true probability: 1.0 # Chance to apply (0.0 - 1.0) - type: remove_effects effects: - minecraft:poison - minecraft:wither - type: clear_all_effects - type: teleport_randomly diameter: 16 # Teleport radius - type: play_sound sound: entity.enderman.teleport` #### Consume Effect Types[](https://docs.oraxen.com/creating-content/items/components#consume-effect-types) | Type | Description | Parameters | | --- | --- | --- | | `apply_effects` | Applies potion effects | `effects` (map), `probability` | | `remove_effects` | Removes specific effects | `effects` (list of effect IDs) | | `clear_all_effects` | Clears all potion effects | None | | `teleport_randomly` | Teleports player randomly | `diameter` (default: 16) | | `play_sound` | Plays a sound | `sound` | ### food[](https://docs.oraxen.com/creating-content/items/components#food) Adds nutrition and saturation to a consumable item. In 1.21.2+, this only handles hunger restoration - use `consumable` for consumption behavior. `Components: food: nutrition: 4 saturation: 2.5 can_always_eat: false # Optional, allows eating when not hungry` ### use\_remainder[](https://docs.oraxen.com/creating-content/items/components#use_remainder) Specifies an item to give back after consuming. `Components: use_remainder: oraxen_item: empty_bottle # Or use other item types: # minecraft_type: BOWL # crucible_item: crucibleid # mmoitems_id: id # mmoitems_type: type # ecoitem_id: ecoid amount: 1 # Number of items to return` ### use\_cooldown[](https://docs.oraxen.com/creating-content/items/components#use_cooldown) Applies a cooldown after using the item. `Components: use_cooldown: seconds: 2.5 # Cooldown duration (default: 1.0) group: oraxen:healing_items # Items in same group share cooldown # Set to "" to affect all items of the same material` ### 1.20.5 - 1.21 ### food[](https://docs.oraxen.com/creating-content/items/components#food-1) In versions 1.20.5 to 1.21, the food component handles all consumable properties in one place. `Components: food: nutrition: 4 # Hunger points restored saturation: 2.5 # Saturation modifier can_always_eat: false # Optional, allows eating when not hungry eat_seconds: 1.6 # Time to consume (default: 1.6) effects: # Potion effects when consumed haste: duration: 200 # Duration in ticks amplifier: 0 ambient: false show_particles: true show_icon: true probability: 1.0 # Chance to apply (0.0 - 1.0)` * * * Equipment Components[](https://docs.oraxen.com/creating-content/items/components#equipment-components) ------------------------------------------------------------------------------------------------------- These components are only available in **Minecraft 1.21.2+**. ### equippable[](https://docs.oraxen.com/creating-content/items/components#equippable) Makes an item equippable in armor slots. `Components: equippable: slot: HEAD # HEAD, CHEST, LEGS, FEET, BODY model: oraxen:custom_armor # Custom armor model (optional) camera_overlay: minecraft:pumpkin_blur # Overlay texture when equipped (optional) equip_sound: item.armor.equip_chain # Sound when equipping (Paper only) allowed_entity_types: # Entities that can equip (optional, defaults to all) - PLAYER - SKELETON - ZOMBIE dispensable: true # Can be equipped via dispenser (default: true) swappable: true # Can be swapped with equipped item (default: true) damage_on_hurt: true # Takes durability damage when hurt (default: true)` The `equip_sound` option requires **Paper** server. Entity type list: [Spigot EntityType](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/EntityType.html)   * * * Visual Components[](https://docs.oraxen.com/creating-content/items/components#visual-components) ------------------------------------------------------------------------------------------------- These components are only available in **Minecraft 1.21.2+**. ### item\_model[](https://docs.oraxen.com/creating-content/items/components#item_model) Sets a custom model for the item. This is the recommended way to set item appearance in 1.21.4+. `Components: item_model: oraxen:custom_sword` References model at: `assets/oraxen/items/custom_sword.json` See [Item Appearance](https://docs.oraxen.com/creating-content/items/appearance) for more details on how item models work with Oraxen’s resource pack generation. ### tooltip\_style[](https://docs.oraxen.com/creating-content/items/components#tooltip_style) Customizes the tooltip appearance with custom sprites. `Components: tooltip_style: oraxen:fancy` This requires custom textures: * `assets/oraxen/textures/gui/sprites/tooltip/fancy_background.png` * `assets/oraxen/textures/gui/sprites/tooltip/fancy_frame.png` Tooltip sprites can be animated using `.mcmeta` files. See the [Minecraft Wiki](https://minecraft.wiki/w/Resource_pack#Animation)   for details. * * * Audio Components[](https://docs.oraxen.com/creating-content/items/components#audio-components) ----------------------------------------------------------------------------------------------- ### jukebox\_playable[](https://docs.oraxen.com/creating-content/items/components#jukebox_playable) This component requires **Minecraft 1.21+** and a **Paper** server. Makes this item playable in a jukebox. `Components: jukebox_playable: show_in_tooltip: true song_key: minecraft:music_disc.cat # or custom: oraxen:custom_song` Custom songs require a datapack to register the song. Use Oraxen’s sound system to create custom music discs with automatic datapack generation. * * * Generic Component System (1.21.3+)[](https://docs.oraxen.com/creating-content/items/components#generic-component-system-1213) ------------------------------------------------------------------------------------------------------------------------------ Starting from **Minecraft 1.21.3**, Oraxen supports setting arbitrary data components through the generic component system. This allows you to use Minecraft data components that aren’t explicitly handled by Oraxen. Components that have object/section values (not primitives) can be passed directly to Minecraft’s data component system: `Components: # These work through the generic system custom_component: some_property: value another_property: 123` The generic system converts YAML sections to NBT and applies them to the corresponding Minecraft data component. * * * Complete Examples[](https://docs.oraxen.com/creating-content/items/components#complete-examples) ------------------------------------------------------------------------------------------------- ### Custom Armor (1.21.2+)[](https://docs.oraxen.com/creating-content/items/components#custom-armor-1212) `emerald_helmet: itemname: Emerald Helmet material: PAPER Components: durability: value: 437 damage_entity_hit: true equippable: slot: HEAD model: oraxen:emerald AttributeModifiers: - { attribute: MAX_HEALTH, amount: 2, operation: 0, slot: HEAD } - { attribute: ARMOR, amount: 3, operation: 0, slot: HEAD } - { attribute: ARMOR_TOUGHNESS, amount: 2, operation: 0, slot: HEAD } Pack: generate_model: true parent_model: item/generated textures: - default/armors/emerald_helmet` ### Custom Food with Effects (1.21.2+)[](https://docs.oraxen.com/creating-content/items/components#custom-food-with-effects-1212) `miner_sandwich: itemname: Miner's Sandwich material: PAPER Components: food: nutrition: 8 saturation: 12.8 can_always_eat: true consumable: consume_seconds: 5 animation: EAT sound: entity.generic.eat has_consume_particles: true on_consume_effects: - type: apply_effects effects: minecraft:haste: duration: 3600 amplifier: 0 ambient: true show_particles: true show_icon: true probability: 1.0 Pack: generate_model: true parent_model: item/generated textures: - default/sandwich.png` ### Custom Music Disc (1.21+)[](https://docs.oraxen.com/creating-content/items/components#custom-music-disc-121) `welcome_disk: itemname: Welcome Disk material: PAPER Components: jukebox_playable: show_in_tooltip: true song_key: oraxen:welcome Pack: generate_model: true parent_model: item/handheld textures: - default/welcome_disk.png` ### Custom Tool with Mining Rules[](https://docs.oraxen.com/creating-content/items/components#custom-tool-with-mining-rules) `super_pickaxe: itemname: Super Pickaxe material: DIAMOND_PICKAXE Components: durability: 2000 fire_resistant: true tool: damage_per_block: 1 default_mining_speed: 2.0 rules: - speed: 10.0 correct_for_drops: true tags: - minecraft:mineable/pickaxe - minecraft:needs_diamond_tool` Last updated on January 3, 2026 [Appearance & Models](https://docs.oraxen.com/creating-content/items/appearance "Appearance & Models") [Dyeable Items](https://docs.oraxen.com/creating-content/items/dyeable-items "Dyeable Items") --- # Dyeable Items | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/items/dyeable-items#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Items](https://docs.oraxen.com/creating-content/items "Items") Dyeable Items Copy page Dyeable Items ============= Introduction[](https://docs.oraxen.com/creating-content/items/dyeable-items#introduction) ------------------------------------------------------------------------------------------ Oraxen allows you to create paintable items and furtniture based on `POTION` and `LEATHER_HORSE_ARMOR`, so let’s first see how to do it in BlockBench! ### How do I do this?[](https://docs.oraxen.com/creating-content/items/dyeable-items#how-do-i-do-this) #### First step open your Blockbench model[](https://docs.oraxen.com/creating-content/items/dyeable-items#first-step-open-your-blockbench-model) ![](https://cdn.discordapp.com/attachments/896841738621177896/966749278615764992/IMG_20220421_121428.png) #### Select the face to be painted[](https://docs.oraxen.com/creating-content/items/dyeable-items#select-the-face-to-be-painted) ![](https://cdn.discordapp.com/attachments/896841738621177896/966749278850670592/IMG_20220421_121444.png) #### Activate the `tint` option[](https://docs.oraxen.com/creating-content/items/dyeable-items#activate-the-tint-option) Use white to paint better ![](https://cdn.discordapp.com/attachments/896841738621177896/966749279102308413/IMG_20220421_121505.png) ![](https://cdn.discordapp.com/attachments/896841738621177896/966749279349776424/IMG_20220421_121543.png) #### And select all the faces of your model with the option![](https://docs.oraxen.com/creating-content/items/dyeable-items#and-select-all-the-faces-of-your-model-with-the-option) `clock: displayname: "Clock" material: LEATHER_HORSE_ARMOR color: 255, 255, 255 #rgb Mechanics: furniture: barrier: false drop: # useless if you are not using a barrier silktouch: false loots: - { oraxen_item: clock, probability: 1.0 } Pack: generate_model: false model: custom/furniture/clock` Last updated on January 3, 2026 [Components](https://docs.oraxen.com/creating-content/items/components "Components") [Overview](https://docs.oraxen.com/creating-content/items/abilities "Overview") --- # All Mechanics | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/items/abilities#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Items](https://docs.oraxen.com/creating-content/items "Items") Item AbilitiesOverview Copy page All Mechanics ============= Oraxen provides a wide variety of mechanics that give special abilities to your items. These are organized into categories: [Miscellaneous](https://docs.oraxen.com/creating-content/items/abilities/misc) [](https://docs.oraxen.com/creating-content/items/abilities#miscellaneous) ---------------------------------------------------------------------------------------------------------------------------------------------------------- General-purpose mechanics for various item behaviors: * **Custom Food** - Custom hunger/saturation values and effects * **Backpack** - Turn items into portable storage * **Music Disc** - Custom music discs with custom sounds * **Durability** - Custom durability values * **Efficiency** - Mining speed boosts * **Consumable** - Make items consumable on right-click * **Repair** - Items that repair other items * **Commands** - Execute commands on item use * **Armor Effects** - Potion effects when armor is equipped * **Aura** - Particle effects when holding items * **Hat** - Make any item wearable as a hat * **Soulbound** - Keep items on death * **Skinnable/Skin** - Change item textures dynamically * **Toggle Light** - Toggle light when right clicking. [Combat](https://docs.oraxen.com/creating-content/items/abilities/combat) [](https://docs.oraxen.com/creating-content/items/abilities#combat) ---------------------------------------------------------------------------------------------------------------------------------------------- Weapon and spell mechanics for combat: * **Thor** - Throw lightning bolts * **Lifeleech** - Steal health from enemies * **Bleeding** - Apply bleed damage over time * **EnergyBlast** - Particle cone attack * **Witherskull** - Launch wither skulls * **Fireball** - Launch exploding fireballs [Farming](https://docs.oraxen.com/creating-content/items/abilities/farming) [](https://docs.oraxen.com/creating-content/items/abilities#farming) ------------------------------------------------------------------------------------------------------------------------------------------------- Tools for farming and mining: * **Harvesting** - Auto-harvest and replant crops * **BigMining** - Mine multiple blocks at once (3x3, 5x5, etc.) * **Smelting** - Auto-smelt ores when mined * **BottledExp** - Convert experience to bottles * **BedrockBreak** - Break bedrock blocks * **Watering** - Watering can system for farms Special Mechanics[](https://docs.oraxen.com/creating-content/items/abilities#special-mechanics) ------------------------------------------------------------------------------------------------ Some mechanics have their own dedicated pages: * [Custom Mechanic](https://docs.oraxen.com/creating-content/items/abilities/custom-ability) - Create custom event-based mechanics * [ClickAction](https://docs.oraxen.com/creating-content/items/abilities/clickaction) - Run actions when clicking blocks/furniture * [Furniture Mechanic](https://docs.oraxen.com/creating-content/furniture) - Custom furniture and decorations * [NoteBlock Mechanic](https://docs.oraxen.com/creating-content/blocks/noteblock) - Custom blocks using noteblocks * [StringBlock Mechanic](https://docs.oraxen.com/creating-content/blocks/stringblock) - Custom blocks using tripwire Last updated on January 3, 2026 [Dyeable Items](https://docs.oraxen.com/creating-content/items/dyeable-items "Dyeable Items") [Combat](https://docs.oraxen.com/creating-content/items/abilities/combat "Combat") --- # Combat Mechanics | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/items/abilities/combat#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Items](https://docs.oraxen.com/creating-content/items "Items") [Item Abilities](https://docs.oraxen.com/creating-content/items/abilities "Item Abilities") Combat Copy page Combat Mechanics ================ All spell-based combat mechanics (Thor, EnergyBlast, WitherSkull, Fireball) support a `charges` option that limits the number of uses before the item is consumed. Set to `-1` or omit for unlimited uses. ### Spear Lunge[](https://docs.oraxen.com/creating-content/items/abilities/combat#spear-lunge) Requires Minecraft 1.21.4+ for model swapping during charge animation. A charged attack mechanic that transforms your weapon into a devastating lunge. Hold right-click to charge, then release or left-click to thrust forward, dealing damage to enemies in your path. #### Features[](https://docs.oraxen.com/creating-content/items/abilities/combat#features) * **Model Animation**: The weapon model visually transitions during charging (requires 1.21.4+) * **Smooth Animation**: Optional intermediate frames for fluid charging animations * **Multi-Target**: Can hit multiple enemies along the lunge path with configurable piercing * **Movement Slowdown**: Configurable speed reduction while charging * **Full Customization**: Particles, sounds, damage, range, and knockback are all configurable #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/combat#per-item-configuration) `my_spear: material: IRON_SWORD displayname: "Battle Spear" Pack: generate_model: false model: default/spear_inactive # Base model (resting position) Mechanics: spear_lunge: active_model: default/spear_active # Model when fully charged (thrust position) intermediate_models: # Optional animation frames during charge - default/spear_frame0 - default/spear_frame1 smooth_frames: 2 # Number of intermediate frames to use charge_ticks: 20 # Ticks to fully charge (20 = 1 second) lunge_velocity: 0.8 # Forward velocity on lunge release max_range: 5.0 # Hit detection range in blocks damage: 10.0 # Damage at full charge min_damage: 2.0 # Minimum damage at lowest charge knockback: 0.8 # Knockback applied to targets hitbox_radius: 0.5 # Ray trace width for hit detection min_charge_percent: 0.25 # Minimum charge needed to attack (25%) charge_slowdown: 0.5 # Movement slowdown while charging (0.0-1.0) max_hold_ticks: 60 # Max hold time before auto-cancel (ticks) max_targets: 3 # Maximum enemies hit per lunge particles: enabled: true charge: CRIT # Particle during charging lunge: SWEEP_ATTACK # Particle on lunge hit: DAMAGE_INDICATOR # Particle on enemy hit sounds: enabled: true charge: ITEM_TRIDENT_RIPTIDE_1 lunge: ENTITY_PLAYER_ATTACK_SWEEP hit: ENTITY_PLAYER_ATTACK_STRONG` #### Configuration Options[](https://docs.oraxen.com/creating-content/items/abilities/combat#configuration-options) | Option | Default | Description | | --- | --- | --- | | `active_model` | \- | Model path when fully charged (required for animation) | | `intermediate_models` | \- | List of model paths for smooth charge animation | | `smooth_frames` | 0 | Number of animation frames to use during charge | | `charge_ticks` | 12 | Ticks to reach full charge (20 ticks = 1 second) | | `lunge_velocity` | 0.6 | Forward velocity multiplier on lunge | | `max_range` | 3.5 | Maximum hit detection range in blocks | | `damage` | 6.0 | Base damage at full charge | | `min_damage` | 0.0 | Minimum damage at lowest valid charge (scales to `damage` at full charge) | | `knockback` | 0.5 | Knockback strength applied to targets | | `hitbox_radius` | 0.5 | Ray trace width for hit detection (higher = easier to hit off-center targets, max 5.0) | | `min_charge_percent` | 0.3 | Minimum charge (0.0-1.0) needed to attack | | `charge_slowdown` | 0.4 | Movement speed reduction while charging (0.0 = none, 1.0 = frozen) | | `max_hold_ticks` | 60 | Maximum ticks to hold charge before auto-cancel | | `max_targets` | 1 | Maximum number of enemies hit per lunge | #### How It Works[](https://docs.oraxen.com/creating-content/items/abilities/combat#how-it-works) 1. **Start Charging**: Hold right-click with the spear to begin charging 2. **Visual Feedback**: The weapon model animates through frames, particles spawn, and your movement slows 3. **Attack**: Release right-click or left-click when charged to lunge forward 4. **Damage**: Enemies along the ray in front of you take damage scaled by charge percentage (from `min_damage` to `damage`) 5. **Cooldown**: After attacking, there’s a brief cooldown before you can charge again If you hold the charge too long (past `max_hold_ticks`), the attack will auto-cancel and revert to the inactive model without dealing damage. This prevents players from walking around indefinitely with a charged weapon. ### Thor[](https://docs.oraxen.com/creating-content/items/abilities/combat#thor) Have you ever dreamed of being able to throw lightning bolts? This is for you. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/combat#per-item-configuration-1) `Mechanics: thor: lightning_bolts_amount: 5 random_location_variation: 1.5 delay: 20000 # in milliseconds (20000ms = 20s) charges: -1 # optional: number of uses before item is consumed (-1 for infinite)` * **lightning\_bolts\_amount**: how many lightning bolts will be spawned? * **random\_location\_variation**: the random variation range between bolts (in blocks) * **delay**: delay between usage in milliseconds (1000ms = 1s) ### Lifeleech[](https://docs.oraxen.com/creating-content/items/abilities/combat#lifeleech) Want to steal hearts to your opponents when you hit them? #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/combat#per-item-configuration-2) `Mechanics: lifeleech: amount: 2 # the amount of 1/2 hearts that you'll steal to your opponents` ### Bleeding[](https://docs.oraxen.com/creating-content/items/abilities/combat#bleeding) Makes your enemies bleed for a specific amount of time. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/combat#per-item-configuration-3) `Mechanics: bleeding: chance: 0.3 # 30% chance to apply bleeding on hit duration: 100 # bleeding lasts for 100 ticks (5 seconds) damage_per_interval: 0.5 # deals 0.5 damage (1/4 heart) per interval interval: 20 # damage is applied every 20 ticks (1 second)` * **chance**: the chance of applying bleeding on hit * **duration**: the duration of bleeding in ticks (20 ticks = 1 second) * **damage\_per\_interval**: the damage dealt per interval * **interval**: the interval between damages in ticks (20 ticks = 1 second) ### EnergyBlast[](https://docs.oraxen.com/creating-content/items/abilities/combat#energyblast) EnergyBlast is a very cool mechanic that creates a cone of particles to attack entities. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/combat#per-item-configuration-4) `Mechanics: energyblast: delay: 20000 length: 5 damage: 10.0 charges: -1 # optional: number of uses before item is consumed (-1 for infinite) particle: type: REDSTONE # only REDSTONE particle can change size and color size: 1 color: red: 0 green: 255 blue: 255` ### Witherskull[](https://docs.oraxen.com/creating-content/items/abilities/combat#witherskull) Send wither skulls when right clicking! #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/combat#per-item-configuration-5) `Mechanics: witherskull: charged: false # a charged skull can break blocks delay: 3000 # in milliseconds (3000ms = 3s) charges: -1 # optional: number of uses before item is consumed (-1 for infinite)` ### Fireball[](https://docs.oraxen.com/creating-content/items/abilities/combat#fireball) Launch fireballs when right clicking! The fireball explodes on impact. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/combat#per-item-configuration-6) `Mechanics: fireball: delay: 3000 # in milliseconds (3000ms = 3s) yield: 2.0 # explosion power speed: 1.0 # projectile speed charges: 5 # optional: number of uses before item is consumed (-1 for infinite)` ### Knockback Strike[](https://docs.oraxen.com/creating-content/items/abilities/combat#knockback-strike) A combo-based knockback mechanic that triggers after landing a certain number of consecutive hits. Perfect for weapons that reward sustained combat engagement. #### Features[](https://docs.oraxen.com/creating-content/items/abilities/combat#features-1) * **Hit Tracking**: Counts consecutive hits and triggers knockback when threshold is reached * **Customizable Knockback**: Configure both horizontal and vertical knockback forces * **Particle Effects**: Display particles when knockback triggers * **Sound Effects**: Play sounds on knockback activation * **Auto-Reset**: Hit counter resets after a configurable timeout * **Thread-Safe**: Folia-compatible implementation for multi-threaded servers #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/combat#per-item-configuration-7) `legendary_hammer: displayname: "Legendary Hammer" material: DIAMOND_PICKAXE lore: - "<#ff455b>» <#D5D6D8>Strike your enemies with a devastating blow" - "<#ff455b>» <#D5D6D8>On the 15th hit, the player is launched forward" Mechanics: knockback_strike: required_hits: 15 # Hits needed to trigger knockback knockback_horizontal: 2.0 # Horizontal force (backward push) knockback_vertical: 1.2 # Vertical force (upward launch) reset_time: 80 # Ticks before hit counter resets (20 = 1 second) play_sound: true # Play sound on knockback trigger sound_type: ENTITY_ENDER_DRAGON_HURT # Sound to play sound_volume: 1.5 # Sound volume (0.0-2.0) sound_pitch: 0.8 # Sound pitch (0.5-2.0, lower = deeper) particle: type: DUST # Particle type to spawn count: 200 # Number of particles spread: 0.5 # Particle spread radius in blocks` #### Configuration Options[](https://docs.oraxen.com/creating-content/items/abilities/combat#configuration-options-1) | Option | Default | Description | | --- | --- | --- | | `required_hits` | 3 | Number of consecutive hits needed to trigger knockback (1-20) | | `knockback_horizontal` | 2.0 | Horizontal knockback force pushing the target backward (0.0-10.0) | | `knockback_vertical` | 0.5 | Vertical knockback force launching the target upward (0.0-5.0) | | `reset_time` | 60 | Ticks before hit counter resets if no hits land (20-200) | | `play_sound` | true | Whether to play a sound when knockback triggers | | `sound_type` | ENTITY\_PLAYER\_ATTACK\_KNOCKBACK | Sound to play on knockback | | `sound_volume` | 1.0 | Sound volume (0.0-2.0) | | `sound_pitch` | 1.0 | Sound pitch (0.5-2.0) | | `particle.type` | CRIT | Particle type to display | | `particle.count` | 20 | Number of particles to spawn (1-100) | | `particle.spread` | 0.5 | Particle spread radius in blocks (0.0-5.0) | #### Supported Particle Types[](https://docs.oraxen.com/creating-content/items/abilities/combat#supported-particle-types) Common particle types include: `CRIT`, `EXPLOSION_NORMAL`, `FLAME`, `SPELL_WITCH`, `DUST` (colored), `CLOUD`, `DRAGON_BREATH`, `SWEEP_ATTACK`, and more. The `DUST` particle type displays as red-colored dust. #### How It Works[](https://docs.oraxen.com/creating-content/items/abilities/combat#how-it-works-1) 1. **Hit Tracking**: Each time you hit an entity with the weapon, a counter increments 2. **Timeout Reset**: If you don’t land another hit within `reset_time` ticks, the counter resets to zero 3. **Knockback Trigger**: When hits reach `required_hits`, knockback is applied to the target 4. **Effects**: Particles spawn at the target’s location and sound plays (if enabled) 5. **Counter Reset**: After triggering, the counter resets and the cycle begins again This mechanic respects protection plugins through ProtectionLib. Knockback will not trigger in protected areas where PvP is disabled. Last updated on January 3, 2026 [Overview](https://docs.oraxen.com/creating-content/items/abilities "Overview") [Farming](https://docs.oraxen.com/creating-content/items/abilities/farming "Farming") --- # Unknown \# Oraxen Documentation # For AI Agents and LLMs # https://docs.oraxen.com > Oraxen is a Minecraft plugin which allows the creation of new items & blocks using custom textures and models. > It handles resourcepack generation, upload and storage, and is entirely open source with an extensible API. ## How to Access Documentation All docs are available as raw markdown: 1. \*\*Automatic\*\*: If your User-Agent is a known LLM (ChatGPT, GPTBot, PerplexityBot, ClaudeBot, etc.), you automatically get raw markdown 2. \*\*Add .md extension\*\*: \`/plugin-setup/plugin-settings.md\` returns raw markdown 3. \*\*Accept header\*\*: \`Accept: text/markdown\` 4. \*\*Query param\*\*: \`/plugin-setup/plugin-settings?format=md\` 5. \*\*API directly\*\*: \`/api/docs/plugin-setup/plugin-settings\` Known LLM User-Agents that get markdown automatically: ChatGPT-User, GPTBot, Claude-Web, ClaudeBot, PerplexityBot, Applebot, cohere-ai, anthropic-ai, Google-Extended, CCBot ## Documentation Index ### Getting Started - /index.md - Overview: what Oraxen is, installation guide, and getting started - /plugin-setup/understanding-the-basics.md - Understanding Oraxen basics - /plugin-setup/plugin-settings.md - Configure plugin settings, pack hosting, and more - /faq.md - Frequently asked questions ### Creating Content - /creating-content/index.md - Overview of creating custom content - /creating-content/items/index.md - Create custom items - /creating-content/items/appearance.md - Customize item appearance and models - /creating-content/items/components.md - Item components and properties - /creating-content/items/dyeable-items.md - Create dyeable custom items - /creating-content/blocks/index.md - Create custom blocks - /creating-content/blocks/noteblock.md - NoteBlock-based custom blocks - /creating-content/blocks/stringblock.md - StringBlock-based custom blocks - /creating-content/blocks/chorusblock.md - ChorusBlock-based custom blocks - /creating-content/blocks/farmblock.md - Farmable custom blocks - /creating-content/blocks/shapedblock.md - Shaped custom blocks - /creating-content/furniture/index.md - Create custom furniture - /creating-content/furniture/display-entities.md - Display entity furniture - /creating-content/furniture/farming.md - Farmable furniture - /creating-content/furniture/position.md - Furniture positioning - /creating-content/armors/index.md - Create custom armor - /creating-content/armors/components.md - Armor components - /creating-content/armors/shaders.md - Armor shaders - /creating-content/armors/trims.md - Armor trims - /creating-content/glyphs-hud/index.md - Custom glyphs and emojis - /creating-content/glyphs-hud/custom-gui.md - Custom GUI overlays - /creating-content/glyphs-hud/custom-hud.md - Custom HUD elements - /creating-content/text-effects/index.md - Text effects and shaders - /creating-content/text-effects/api.md - Text effects API - /creating-content/text-effects/glsl-customization.md - GLSL shader customization ### Item Abilities - /creating-content/items/abilities/index.md - Overview of item abilities - /creating-content/items/abilities/clickaction.md - Click action abilities - /creating-content/items/abilities/combat.md - Combat abilities - /creating-content/items/abilities/farming.md - Farming abilities - /creating-content/items/abilities/misc.md - Miscellaneous abilities - /creating-content/items/abilities/custom-ability.md - Create custom abilities - /creating-content/items/abilities/backpack-cosmetic.md - Backpack cosmetic abilities ### Plugin Configuration - /plugin-setup/plugin-settings.md - Various plugin settings and options - /plugin-setup/pack-hosting.md - Resource pack hosting configuration - /plugin-setup/pack-merging.md - Merge multiple resource packs - /usage/commands.md - Available commands - /usage/recipes.md - Create custom recipes - /usage/default-items.md - Default items included with Oraxen ### Compatibility - /compatibility/crucible.md - Crucible compatibility - /compatibility/mmoitems.md - MMOItems integration - /compatibility/mythicmobs-custom-mobs.md - MythicMobs custom mobs - /compatibility/modelengine-custom-mobs.md - ModelEngine custom mobs - /compatibility/mythichud.md - MythicHUD integration - /compatibility/skript.md - Skript integration - /compatibility/packlayer.md - PackLayer compatibility - /compatibility/world-generators/index.md - World generator compatibility overview - /compatibility/world-generators/iris-world-generator.md - Iris world generator - /compatibility/world-generators/terralith.md - Terralith world generator - /compatibility/world-generators/custom-ore-generator.md - Custom ore generator ### Developers - /developers/api.md - Complete API reference for developers - /developers/mechanics.md - Create custom mechanics - /developers/create-your-own-compatibility.md - Create compatibility integrations - /developers/custom-hosting-service.md - Custom resource pack hosting service ### Vendors - /vendors/vendor-guidelines.md - Guidelines for content creators and vendors ### Special Endpoints - /api/docs/\_index - JSON index of all documents - /api/docs/\_all - All documentation concatenated (for full context loading) ## Quick Reference ### Installation 1. Drop Oraxen .jar into /plugins/ folder 2. Restart server 3. Auto-downloaded dependencies: CommandAPI, PacketEvents 4. Optional: ProtocolLib (recommended) ### Supported Versions - Minecraft 1.18 → 1.21.6 - Server software: Paper (recommended), Spigot, or Folia - Paper 1.21.11+ fully supported ### Key Features - Custom items with textures and models - Custom blocks (NoteBlock, StringBlock, ChorusBlock) - Custom furniture using display entities - Custom armor with shaders and trims - Resource pack generation and hosting (Polymath) - Custom glyphs, emojis, and HUD elements - Text effects with GLSL shaders - Item abilities and mechanics - Custom recipes - Extensive plugin compatibility ### Configuration Structure \`\`\` plugins/Oraxen/ ├── items/ # Item configurations (.yml files) ├── glyphs/ # Custom font/glyph configurations ├── pack/ # Resource pack assets (textures, models) │ ├── textures/ # PNG texture files │ ├── models/ # JSON model files │ └── pack.zip # Generated resource pack └── settings.yml # Main plugin settings \`\`\` ### v1.207.0 New Features - GUI-only models (gui\_model) for 1.21.2+ - Resource pack layering (Pack.dispatch.layer) for BungeeCord/Velocity - Cross-version shader overlay compatibility (1.21.4/1.21.5 vs 1.21.6+) - Core shader reference updates for 1.21.4+ - Fixed invisible shields, conduits, and decorated pots - NoteBlock API improvements ## For AI Agents Working With Oraxen 1. Read /api/docs/\_all for complete documentation context 2. Or read specific sections like /plugin-setup/plugin-settings.md 3. Check /developers/api.md for API usage 4. Review /faq.md for common issues and solutions ## Source & Links - Repository: https://github.com/oraxen/oraxen - Documentation: https://docs.oraxen.com - Discord: https://discord.gg/oraxen - Polymath (pack hosting): https://github.com/Th0rgal/Polymath --- # Custom Mechanic | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Items](https://docs.oraxen.com/creating-content/items "Items") [Item Abilities](https://docs.oraxen.com/creating-content/items/abilities "Item Abilities") Custom Abilities Copy page Custom Mechanic =============== How does it work?[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#how-does-it-work) -------------------------------------------------------------------------------------------------------------- This mechanic is for items only and does not work with blocks/furniture. For that check the [clickAction mechanic](https://docs.oraxen.com/creating-content/items/abilities/clickaction) . The mechanics let you create subsections composed of 3 parts: * **Event**: when is this mechanic triggered? e.g. when you right-click on a block * **Conditions**: a set of conditions that must be satisfied. e.g. having a permission * **Actions**: a set of actions to perform. e.g. send a command or a message An optional settings called oneUsage allows you to imitate the use of an item at 1. A comprehensive example[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#a-comprehensive-example) --------------------------------------------------------------------------------------------------------------------------- `Mechanics: custom: test: one_usage: false event: "CLICK:right:all" conditions: - "HAS_PERMISSION:example.permission" actions: - "[console] give cooked_beef 1"` In this example, the subsection `test` defines a custom mechanic triggered when someone right click (on a block or in the air). If this player has the permission `example.permission`, the console will perform the give command and replace by the player name. The item won’t be consumed (oneUsage: false). Available events[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#available-events) ------------------------------------------------------------------------------------------------------------- ### CLICK:mouse\_click\_type:target\_type[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#clickmouse_click_typetarget_type) Called when you click with the item. **mouse\_click\_type**: `[ right, left, all ]` **target\_type**: `[ block, air, all ]` ### DROP[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#drop) Called when you drop the item. ### PICKUP[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#pickup) Called when you pick up the item. ### BREAK[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#break) Called when a player breaks an item. ### EQUIP[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#equip) Called when a player equips an item. ### UNEQUIP[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#unequip) Called when a player unequips an item. ### INV\_CLICK[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#inv_click) Called when a player clicks an item in an inventory. ### DEATH[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#death) Called when a player dies and would normally drop the given item. Available conditions[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#available-conditions) --------------------------------------------------------------------------------------------------------------------- ### HAS\_PERMISSION:the.permission[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#has_permissionthepermission) **the.permission**: `The permission required by the player using the item` Available actions[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#available-actions) --------------------------------------------------------------------------------------------------------------- ### COMMAND:sender:command[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#commandsendercommand) **sender**: `[ console, player ]` **command**: `The command to perform. The placeholder can be used.` ### MESSAGE:content[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#messagecontent) **content**: `Content of the message to send (it supports minimessage format)` ### ACTIONBAR:content[](https://docs.oraxen.com/creating-content/items/abilities/custom-ability#actionbarcontent) **content**: `Content of the message to send (it supports minimessage format)` Last updated on January 3, 2026 [Miscellaneous](https://docs.oraxen.com/creating-content/items/abilities/misc "Miscellaneous") [Click Actions](https://docs.oraxen.com/creating-content/items/abilities/clickaction "Click Actions") --- # Miscellaneous Mechanics | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/items/abilities/misc#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Items](https://docs.oraxen.com/creating-content/items "Items") [Item Abilities](https://docs.oraxen.com/creating-content/items/abilities "Item Abilities") Miscellaneous Copy page Miscellaneous Mechanics ======================= ### Custom Food[](https://docs.oraxen.com/creating-content/items/abilities/misc#custom-food) This mechanic allows you to set food-related properties for any food item. This means you can create foods which refill different amounts of hunger and saturation. It also lets you set a replacement item for when the food has been consumed. Below is a config example of the mechanic-part for a custom food: On 1.20.5+ use the new [Food-Component](https://docs.oraxen.com/creating-content/items/components) instead `Mechanics: food: hunger: 10 saturation: 10 replacement: oraxen_item: any_oraxen_itemid # Can also be minecraft_type or crucible_item effect_probability: 0.35 # The probability of the effect being applied, default is 1.0 / 100% effects: hunger: # Must be a valid potion effect, can find a list https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/potion/PotionEffectType.html amplifier: 1 # If not set, defaults to 0 duration: 20 # Duration in seconds. If not set, defaults to 1 second is_ambient: true # If not set, defaults to true has_particles: true # If not set, defaults to true has_icon: true # If not set, defaults to true night_vision: duration: 60` ### Backpack[](https://docs.oraxen.com/creating-content/items/abilities/misc#backpack) This allows you to turn any item into a backpack. This mechanic might cause duplication issues! If you find any please open a [bug-report](https://github.com/oraxen/oraxen/issues/new?assignees=&labels=bug&template=bug-report.yml&title=%5BBUG%5D+%3Cname+for+bug%3E)   and we will fix them as soon as possible! There is currently a known dupe, if your backpack is using a stackable material like paper. Make sure to specify that the item should be unstackable, like shown below. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/misc#per-item-configuration) `backpack: displayname: backpack material: PAPER unstackable: true #Recommend making it unstackable to avoid abovementioned dupe Mechanics: backpack: rows: 4 title: "Backpack" #Optional, Default: "Backpack" open_sound: "entity.shulker.open" #Optional, Default: "entity.shulker.open" close_sound: "entity.shulker.close" #Optional, Default: "entity.shulker.close"` ### Music Disc[](https://docs.oraxen.com/creating-content/items/abilities/misc#music-disc) This allows you to make custom music discs with custom sounds. To add a sound simply follow the default example by adding it into `Oraxen/sound.yml` Any stereo sounds will not play at a specific position or following an entity. If you want this you need to make sure your .ogg sound-file is in mono sound format. On 1.21+ use the new [JukeboxPlayable-Component](https://docs.oraxen.com/creating-content/items/components) instead `song` is the namespace:sound.name as you defined it in `sound.yml`. If your sound.yml entry looks like this: `sounds: my_music_disc_song.mysong: category: record sound: mysong.ogg` This means your .ogg file is in the path `Oraxen/sounds/mysong.ogg`, and your sound-ID is `my_music_disc_song.mysong` with the namespace minecraft. If you are importing sounds.json into another namespace, the namespace would naturally not be minecraft `Mechanics: music_disc: song: "minecraft:my_music_disc_song.mysong"` ### Durability[](https://docs.oraxen.com/creating-content/items/abilities/misc#durability) This allows you to change the durability of an item created with Oraxen. Minecraft vanilla wasn’t made to handle that kind of modifications, this is why this system is not perfect. You’ll not see the good durability on your item, it will just work as a percentage. What that means is that if for example you create a pickaxe based off the wooden pickaxe (which has 59 of durability by default) and you change it to 5900, you’ll still see 59 of durability on your item. But you’ll need to break 100 blocks in order to lose of one durability. The cool thing is that the displayed bar will be updated correctly. On 1.20.5+ use the new [Durability-Component](https://docs.oraxen.com/creating-content/items/components) instead #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/misc#per-item-configuration-1) There are two options available : ratio and fixed\_amount. You can put only one of these two options on the same item. Ratio allows you to repair a percentage of your item (0.15 will repair 15% of maximum durability while 1.0 will repair it to 100%). Fixe amount repairs a fixed amount of your item durability (put 10 if you want to add 10 durability points to your item for example). `Mechanics: durability: value: 5000 #diamond sword is 1561 by default` ### Efficiency[](https://docs.oraxen.com/creating-content/items/abilities/misc#efficiency) Gives the player a mining speed boost (Haste effect) while holding the item. Use negative values for mining fatigue instead. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/misc#per-item-configuration-2) `Mechanics: efficiency: amount: 2 # Haste level (use negative for mining fatigue)` ### Consumable[](https://docs.oraxen.com/creating-content/items/abilities/misc#consumable) Makes an item consumable on right-click. The item amount decreases by 1 when used. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/misc#per-item-configuration-3) `Mechanics: consumable: {}` ### Consumable Potion Effects[](https://docs.oraxen.com/creating-content/items/abilities/misc#consumable-potion-effects) Apply potion effects when an item is consumed or used. This is commonly combined with the consumable mechanic. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/misc#per-item-configuration-4) `Mechanics: consumable_potion_effects: speed: amplifier: 1 # effect level (0 = level 1) duration: 600 # in ticks (600 = 30 seconds) ambient: false particles: true icon: true regeneration: amplifier: 0 duration: 200` ### Misc Mechanic[](https://docs.oraxen.com/creating-content/items/abilities/misc#misc-mechanic) This mechanic has a bunch of small changes you can make to your item. What they each do should be pretty self-explanatory. On 1.20.5+ use the new [FireResistant-Component](https://docs.oraxen.com/creating-content/items/components) instead of burns\_in\_X below On 1.21.2+ use the new [DamageResistant-Component](https://docs.oraxen.com/creating-content/items/components) instead of burns\_in\_X/breaks\_from\_cactus below `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` ### Repair[](https://docs.oraxen.com/creating-content/items/abilities/misc#repair) This mechanic allows you to use an item to repair another one (which uses vanilla durability or oraxen custom). By default this mechanic is binded to iron, gold and diamond cogs. To use them you just need to click on the item you want to repair. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/misc#per-item-configuration-5) `Mechanics: repair: ratio: 0.10 # 10% fixed_amount: 10 # or 10 durability points` #### Global configuration[](https://docs.oraxen.com/creating-content/items/abilities/misc#global-configuration) If you enable oraxen\_durability\_only, this mechanic will only work with items using oraxen Durability mechanic. `repair: enabled: true oraxen_durability_only: false` ### Commands[](https://docs.oraxen.com/creating-content/items/abilities/misc#commands) This allows you to execute commands (as the console, a player or op player). If this option is not often the most elegant it has the merit of simplifying a lot of things. You can create a cooldown between usages, check if the player has a specific permission and use the item (understand decrease its amount by one when the command is performed). #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/misc#per-item-configuration-6) `Mechanics: commands: cooldown: 5 # example cooldown in seconds. This is optional permission: "my.awesome.perm" # required permission. This is optional one_usage: true # should the amount decrease when used? Default: false console: # e.g. to kill the player - "kill %p%" player: # e.g. the player performs /spawn - "spawn" opped_player: # e.g. the player gives himself a diamond sword - "give diamond_sword 1"` ### Armor Effects[](https://docs.oraxen.com/creating-content/items/abilities/misc#armor-effects) This allows you to bind a Potion Effect to an armor (or a hat) so that when you equip it you’ll get the effect. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/misc#per-item-configuration-7) [Here](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/potion/PotionEffectType.html)   is a list of all potion effect types available. `Mechanics: armor_effects: night_vision: # the potion effect type duration: 10 amplifier: 0 ambient: true # Makes potion effect produce more, translucent, particles. particles: true # whether this effect has particles or not icon: true # whether this effect has an icon or not` You can also make an effect only apply if the entire set it equipped. `Mechanics: armor_effects: night_vision: requires_full_set: true ...` ### Block and NoteBlock[](https://docs.oraxen.com/creating-content/items/abilities/misc#block-and-noteblock) These mechanic allows you to use an item as block. Since these are quite special mechanics, they have a [dedicated tutorial page](https://docs.oraxen.com/creating-content/blocks/noteblock) . ### clickAction[](https://docs.oraxen.com/creating-content/items/abilities/misc#clickaction) This mechanic allows you to run various events when a player clicks a block or furniture. It is very customizable, so it also has a [dedicated tutorial page](https://docs.oraxen.com/creating-content/items/abilities/clickaction) . ### Aura[](https://docs.oraxen.com/creating-content/items/abilities/misc#aura) Do you want to show a cool particle effect when a player holds your item? The Aura mechanic is your way to go. You can find a list of available particles here: [https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Particle.html](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Particle.html)   #### Per item configuration (easy)[](https://docs.oraxen.com/creating-content/items/abilities/misc#per-item-configuration-easy) `Mechanics: aura: type: simple # available types: [ simple, ring, helix ] particle: PORTAL` ### Hat[](https://docs.oraxen.com/creating-content/items/abilities/misc#hat) Do you want to create a hat? Use this mechanic so that you’ll be able to put any item on your head. #### Per item configuration (easy)[](https://docs.oraxen.com/creating-content/items/abilities/misc#per-item-configuration-easy-1) `Mechanics: hat: enabled: true` ### Skinnable[](https://docs.oraxen.com/creating-content/items/abilities/misc#skinnable) With this mechanic, you can change the texture of an item using an item with Skin mechanic. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/misc#per-item-configuration-8) `Mechanics: skinnable: {}` ### ItemType[](https://docs.oraxen.com/creating-content/items/abilities/misc#itemtype) With this mechanic, you can change the item type detected by OraxenBlocks. Make sure to use a type declared [inside the block mechanic](https://docs.oraxen.com/creating-content/blocks/noteblock#global-configuration) . #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/misc#per-item-configuration-9) `Mechanics: itemtype: value: SUPER_MATERIAL # your itemType` ### Soulbound[](https://docs.oraxen.com/creating-content/items/abilities/misc#soulbound) With this mechanic, you can avoid the players to lose their item when they die. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/misc#per-item-configuration-10) `Mechanics: soulbound: lose_chance: 0 # 0-1, chance to lose the item on death (0 = never lose, 1 = always lose)` ### Toggle-Light[](https://docs.oraxen.com/creating-content/items/abilities/misc#toggle-light) With this mechanic, you can create interactive lighting for furniture, noteblocks, and stringblocks. Players can right-click these items to toggle their light level between a base level and a toggle level, allowing them to turn lights on and off. * Interactive lighting control for custom items * Support for both static base lighting and toggleable lighting * State persistence across server restarts * Seamless integration with existing furniture mechanics (barriers, storage, seats, rotation) **Important notes** * For furniture with barriers: the light toggles across all barrier blocks in the furniture structure * Light state is automatically refreshed on server load/reload #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/misc#per-item-configuration-11) `Mechanics: toggle_light: light: 5 # Base light level (0-15), always active toggle_light: 15 # Toggle light level (0-15), activated on interaction` * `light`: The base light level (0-15) that is always active. This is the default state. * `toggle_light`: The toggle light level (0-15) that activates when players interact with the item. Set this to enable toggleable lighting. ### Custom mechanic[](https://docs.oraxen.com/creating-content/items/abilities/misc#custom-mechanic) This mechanic allows you to customize events, conditions and actions. Since it is a quite special mechanic, it has its [dedicated tutorial page](https://docs.oraxen.com/creating-content/items/abilities/custom-ability) . ### Skin[](https://docs.oraxen.com/creating-content/items/abilities/misc#skin) This mechanic will allow the item to be a skin for Skinnable mechanic, skin and Skinnable item must have the same material to apply the texture. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/misc#per-item-configuration-12) `Mechanics: skin: consume: true #consume 1 skin item` Last updated on January 3, 2026 [Farming](https://docs.oraxen.com/creating-content/items/abilities/farming "Farming") [Custom Abilities](https://docs.oraxen.com/creating-content/items/abilities/custom-ability "Custom Abilities") --- # Farming Mechanics | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/items/abilities/farming#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Items](https://docs.oraxen.com/creating-content/items "Items") [Item Abilities](https://docs.oraxen.com/creating-content/items/abilities "Item Abilities") Farming Copy page Farming Mechanics ================= ### Harvesting[](https://docs.oraxen.com/creating-content/items/abilities/farming#harvesting) Harvesting allows you to recolt and replant automatically wheat in a certain radius. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/farming#per-item-configuration) `Mechanics: harvesting: cooldown: 10000 # 10 seconds between usages radius: 5 # blocks surrounding the clicked block height: 3 # blocks above the clicked block lower_item_durability: true # whether harvesting reduces tool durability (default: true)` ### BigMining[](https://docs.oraxen.com/creating-content/items/abilities/farming#bigmining) Bigmining allows you to mine different blocks at the same time. By default this mechanic is used on the hammers and allows you to mine 3x3 square and more. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/farming#per-item-configuration-1) `Mechanics: bigmining: radius: 1 # blocks surrounding the broken block depth: 1` ### Smelting[](https://docs.oraxen.com/creating-content/items/abilities/farming#smelting) Smelting allows you to instantly melt iron and gold ores when you mine them. This supports fortune and silktouch. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/farming#per-item-configuration-2) `Mechanics: smelting: enabled: true play_sound: true` ### BottledExp[](https://docs.oraxen.com/creating-content/items/abilities/farming#bottledexp) This allows to transform your experience into bottles of experience with a right click. You can configure a loss percentage. #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/farming#per-item-configuration-3) The ratio corresponds to the quantity of exp transformed into a bottle for one exp. `Mechanics: bottledexp: ratio: 0.95 # So you'll lose 1/20 of your exp by converting it` #### Global configuration[](https://docs.oraxen.com/creating-content/items/abilities/farming#global-configuration) `bottledexp: enabled: true durability_cost: 1` ### BedrockBreak[](https://docs.oraxen.com/creating-content/items/abilities/farming#bedrockbreak) This mechanic depends on ProtocolLib, if you can’t use ProtocolLib, you need to disable it #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/farming#per-item-configuration-4) The hardness is the amount of ticks between breaking animation switch and probability is the percentage of chance to get the bedrock (0.10 for 10%, 0.5 for 50% or 1.0 for 100%). `Mechanics: bedrockbreak: hardness: 10 probability: 1` #### Global configuration[](https://docs.oraxen.com/creating-content/items/abilities/farming#global-configuration-1) If you set disable\_on\_first\_layer to true, your players will no longer be able to break the ground (layer 0), the durability\_cost is the amount of durability the item you’ve set bedrockbreak `bedrockbreak: enabled: true disable_on_first_layer: false durability_cost: 500` ### Watering[](https://docs.oraxen.com/creating-content/items/abilities/farming#watering) Create a watering can system for your farm. This mechanic requires two items: an empty can and a filled can. The empty can fills when right-clicking water or a water cauldron. The filled can waters farmland (vanilla or Oraxen farm blocks). #### Per item configuration[](https://docs.oraxen.com/creating-content/items/abilities/farming#per-item-configuration-5) You need to define both items and link them together: `empty_watering_can: displayname: "Empty Watering Can" material: PAPER Mechanics: watering: filledCanItem: filled_watering_can filled_watering_can: displayname: "Filled Watering Can" material: PAPER Mechanics: watering: emptyCanItem: empty_watering_can` The empty can turns into the filled can when filling with water, and vice versa when watering farmland. Last updated on January 17, 2026 [Combat](https://docs.oraxen.com/creating-content/items/abilities/combat "Combat") [Miscellaneous](https://docs.oraxen.com/creating-content/items/abilities/misc "Miscellaneous") --- # Shader Based Armors (1.18-1.19.4) | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/armors/shaders#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Armors](https://docs.oraxen.com/creating-content/armors "Armors") Shaders (1.18-1.19.4) Copy page Shader Based Armors (1.18-1.19.4) ================================= Oraxen alters this second texture by using colored leather armor and shaders. Armor has like every item a texture in the inventory and in the hand, but it also has a second texture when worn on the body This second appearance has some limitations and requires some practice. We will use a trick with leather armor and colors. If you are using shaders via either the Optifine or Iris mod, you will need some additional steps. For Optifine, everything is handled automatically. For Iris, you also need [CIT Resewn](https://modrinth.com/mod/cit-resewn)  , everything else is handled for you. ![A: item appearance B: body appearance](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fstuff.3848a711.png&w=1080&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) You must be careful when naming your armors to get the textures detected correctly. If you want to create an **amethyst** armor set, then your item sections must be: \- **amethyst**\_helmet \- **amethyst**\_chestplate \- **amethyst**\_leggings \- **amethyst**\_boots And in [step 2](https://docs.oraxen.com/creating-content/armors/#2-name-your-textures-correctly) you’ll be able to create the textures: \- **amethyst**\_armor\_layer\_1.png \- **amethyst**\_armor\_layer\_2.png #### How to configure your armor?[](https://docs.oraxen.com/creating-content/armors/shaders#how-to-configure-your-armor) For this we will be using the below config example for reference: `ruby_helmet: displayname: "Ruby Helmet" material: LEATHER_HELMET Pack: generate_model: true parent_model: "item/generated" textures: - default/armors/ruby_helmet - default/armors/ruby_helmet` Make sure that the items ID, or the first line in the above example, follows the pattern `armorname_armortype`. For the rest of the above set it would be `ruby_chestplate`, `ruby_leggings` and `ruby_boots`. This is also why LEATHER is the only material that works. Custom Armor can not be made with Diamond as the base material. To get custom armor amounts, simply add Attribute Modifiers. ### How to change the equipped appearance?[](https://docs.oraxen.com/creating-content/armors/shaders#how-to-change-the-equipped-appearance) Now the fun begins. We’re going to use a vanilla shader to associate an armor style with a specific color. Thanks to [Ancientkingg](https://twitter.com/ancientkingg)   for developing the shader used by Oraxen. ### 1) Create your textures[](https://docs.oraxen.com/creating-content/armors/shaders#1-create-your-textures) You’ll have to create two textures for your armor. You can download the ruby example here: [https://oraxen.com/resources/armor\_rest.png](https://media.discordapp.net/attachments/758785982005903431/1009559045893537802/ruby_armor_layer_1.png)   [https://oraxen.com/resources/armor\_leggings.png](https://media.discordapp.net/attachments/758785982005903431/1009559063815786626/ruby_armor_layer_2.png)   Make sure your armors resolution fits the value set in settings.yml. By default armor\_resolution is set to 16. This means that your textures must be 64x32 pixels. If you want to use a higher resolution, you’ll have to change the value in settings.yml. For example armor\_layer files with 128x64 pixels must have a resolution of 32 in settings.yml. You cannot have some at 64x32 and some at 128x64, it is either or. Also make sure that the bit-depth of your textures is 32 bits. Anything else means not fully transparent, and the pixels the shader uses will be black. This will not break Optifine/Iris versions but will break all vanilla versions. ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fleggings.ff7c1b9c.png&w=1920&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Farmor.4f283b39.png&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) You can make your texture **emissive** (no optifine required) by adding another file with the same name ending in **\_e.png**. For example `ruby_armor_layer_1_e.png` This texture will be treated as an emissivity map, where the alpha of the pixel will be treated as the amount of emissivity. ### 2) Name your textures correctly[](https://docs.oraxen.com/creating-content/armors/shaders#2-name-your-textures-correctly) To get your textures registered correctly, their name need to contain `armor_layer_X`. For example: `ruby_armor_layer_1.png` and`ruby_armor_layer_2.png` You can put them in any folder of the pack textures, `~/textures/default/armors` is suggested. Last updated on January 3, 2026 [Trims (1.20-1.21.1)](https://docs.oraxen.com/creating-content/armors/trims "Trims (1.20-1.21.1)") [Glyphs](https://docs.oraxen.com/creating-content/glyphs-hud "Glyphs") --- # Backpack Cosmetic | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Items](https://docs.oraxen.com/creating-content/items "Items") [Item Abilities](https://docs.oraxen.com/creating-content/items/abilities "Item Abilities") Backpack Cosmetic Copy page Backpack Cosmetic ================= The Backpack Cosmetic mechanic displays cosmetic backpacks on a player’s back when they equip an item in a specific slot. It uses packet-based invisible armor stands for efficient client-side rendering. ![Player with cosmetic backpack](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fbackpack_cosmetic.b8185e8b.webp&w=3840&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) This is a **cosmetic-only** mechanic. For functional storage backpacks, see the [Backpack mechanic](https://docs.oraxen.com/creating-content/items/abilities) (coming soon) or use the [Storage](https://docs.oraxen.com/creating-content/furniture#storage) feature on furniture. How It Works[](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic#how-it-works) -------------------------------------------------------------------------------------------------------- When a player equips an item with the `backpack_cosmetic` mechanic: 1. An invisible armor stand is spawned and mounted to the player 2. The backpack model is displayed as the armor stand’s equipment 3. The armor stand follows the player’s movement and rotation 4. Other players (and optionally the wearer) can see the backpack Basic Configuration[](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic#basic-configuration) ---------------------------------------------------------------------------------------------------------------------- `leather_backpack: displayname: "<#8B4513>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` Configuration Options[](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic#configuration-options) -------------------------------------------------------------------------------------------------------------------------- | Option | Type | Default | Description | | --- | --- | --- | --- | | `slot` | String | Required | Slot that triggers the cosmetic: `HEAD`, `CHEST`, `LEGS`, `FEET`, `HAND`, `OFF_HAND`, or `INVENTORY` | | `model` | String | Item model | Override the model displayed on the armor stand (optional) | | `offset` | Object | `{x:0, y:0.3, z:-0.3}` | Position offset relative to the player | | `scale` | Number | `1.0` | Size multiplier for the backpack model | | `view_distance` | Number | `48` | Maximum distance (in blocks) at which the backpack is visible | | `hide_in_spectator` | Boolean | `true` | Hide the backpack when the player is in spectator mode | | `small` | Boolean | `false` | Use a small armor stand for lower positioning | | `visible_to_self` | Boolean | `true` | Whether the wearer can see their own backpack | The `INVENTORY` slot triggers the backpack when the item is anywhere in the player’s inventory (excluding hands). This is useful for always-visible cosmetics. ### Offset Configuration[](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic#offset-configuration) The offset positions the backpack relative to the player: `offset: x: 0.5 # Positive = right, Negative = left y: 0.2 # Positive = up, Negative = down z: -0.2 # Positive = forward, Negative = backward (toward player's back)` When using the mounting system, offset values may have limited effect. The `small` option provides a significant vertical offset by using a smaller armor stand. Examples[](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic#examples) ------------------------------------------------------------------------------------------------ ### Standard Backpack[](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic#standard-backpack) A backpack centered on the player’s back: `adventurer_backpack: displayname: "<#2E8B57>Adventurer's Backpack" material: LEATHER_CHESTPLATE color: 46139 # Dark green tint Pack: generate_model: true parent_model: item/generated textures: - adventurer_backpack Mechanics: backpack_cosmetic: slot: CHEST offset: x: 0.0 y: 0.45 z: -0.35 scale: 0.9 view_distance: 64 hide_in_spectator: true small: true visible_to_self: true` ### Shoulder Pack[](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic#shoulder-pack) A smaller pack positioned to one side: `explorer_pack: displayname: "<#4169E1>Explorer's Pack" material: LEATHER_CHESTPLATE color: 4286945 # Blue tint Pack: generate_model: true parent_model: item/generated textures: - explorer_pack Mechanics: backpack_cosmetic: slot: CHEST offset: x: 0.5 # Offset to the right side y: 0.35 z: -0.25 scale: 0.75 view_distance: 48 hide_in_spectator: true small: false visible_to_self: true` ### Using Existing Models[](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic#using-existing-models) If you have a pre-made model, disable generation and reference it directly: `custom_bag: displayname: "<#8B4513>Custom Bag" material: LEATHER_CHESTPLATE Pack: generate_model: false model: items/bag # Path to existing model Mechanics: backpack_cosmetic: slot: CHEST offset: x: 0.0 y: 0.0 z: 0.0 scale: 1.0 view_distance: 48 hide_in_spectator: true small: true visible_to_self: true` Global Configuration[](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic#global-configuration) ------------------------------------------------------------------------------------------------------------------------ Enable or disable the mechanic globally in `mechanics.yml`: `backpack_cosmetic: enabled: true` Technical Details[](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic#technical-details) ------------------------------------------------------------------------------------------------------------------ ### Rendering Method[](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic#rendering-method) Backpacks are rendered using packet-based armor stands: * **No server-side entities** - Only packet data is sent to clients * **Efficient** - Minimal server overhead compared to real entities * **Mounted** - Armor stands are mounted to players for smooth position following * **Rotation sync** - Both head and body rotation are updated for proper orientation ### Performance Considerations[](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic#performance-considerations) * The `view_distance` option limits render distance to reduce packet overhead * Backpacks are automatically cleaned up when: * The player unequips the item * The player disconnects * The server shuts down or reloads ### Slot Behavior[](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic#slot-behavior) The backpack displays when the item is in the specified slot: * `CHEST` - Most common for backpacks (chestplate slot) * `HEAD` - Could be used for mounted items on the head * `LEGS` - Leggings slot * `FEET` - Boots slot * `HAND` - Main hand slot * `OFF_HAND` - Off-hand slot * `INVENTORY` - Anywhere in the player’s inventory (excluding hands) Tips[](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic#tips) ---------------------------------------------------------------------------------------- 1. **Use `small: true`** for backpacks to position them lower on the player’s back 2. **Adjust `scale`** between 0.5-1.0 for realistic sizing 3. **Set `visible_to_self: true`** so players can see their own cosmetics (especially in third-person view) 4. **Use `LEATHER_CHESTPLATE`** as the base material if you want dyeable backpacks (add a `color` property) 5. **Test in third-person** (F5) to verify positioning looks correct from other players’ perspectives Last updated on January 3, 2026 [Click Actions](https://docs.oraxen.com/creating-content/items/abilities/clickaction "Click Actions") [Overview](https://docs.oraxen.com/creating-content/blocks "Overview") --- # Custom Block Mechanics | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/blocks#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") BlocksOverview Copy page Custom Block Mechanics ====================== Oraxen provides several mechanics for creating custom blocks, each with different characteristics. This guide helps you choose the right one for your needs. Quick Comparison[](https://docs.oraxen.com/creating-content/blocks#quick-comparison) ------------------------------------------------------------------------------------- | Mechanic | Max Blocks | Base Block | Best For | | --- | --- | --- | --- | | [NoteBlock](https://docs.oraxen.com/creating-content/blocks/noteblock) | ~800 | Note Block | Most custom blocks (ores, stone, wood) | | [StringBlock](https://docs.oraxen.com/creating-content/blocks/stringblock) | 127 | Tripwire | Plants, flowers, decorations | | [ChorusBlock](https://docs.oraxen.com/creating-content/blocks/chorusblock) | 63 | Chorus Plant | Transparent blocks (leaves, glass-like) | | [ShapedBlock](https://docs.oraxen.com/creating-content/blocks/shapedblock) | 4 per type | Waxed Copper | Stairs, slabs, doors, trapdoors, grates | | [Furniture](https://docs.oraxen.com/creating-content/furniture) | Unlimited | Display Entity | Complex models, interactable objects | Choosing the Right Mechanic[](https://docs.oraxen.com/creating-content/blocks#choosing-the-right-mechanic) ----------------------------------------------------------------------------------------------------------- ### Use NoteBlock for:[](https://docs.oraxen.com/creating-content/blocks#use-noteblock-for) * **Solid blocks** like ores, stone variants, wood planks * When you need the **most block slots** (~800) * Blocks that should have **standard hitboxes** ### Use StringBlock for:[](https://docs.oraxen.com/creating-content/blocks#use-stringblock-for) * **Plants and flowers** that players walk through * **Small decorations** with passable hitboxes * Blocks that need to be **waterloggable** * **Tall plants** (2-block height) ### Use ChorusBlock for:[](https://docs.oraxen.com/creating-content/blocks#use-chorusblock-for) * **Transparent blocks** like custom leaves or glass variants * **Single-block furniture** that needs transparency (more performant than display entities) * Blocks where **see-through rendering** is important ### Use ShapedBlock for:[](https://docs.oraxen.com/creating-content/blocks#use-shapedblock-for) * **Custom stairs, slabs, doors, trapdoors, and grates** * Blocks that need **proper directional placement** (stairs facing, slab top/bottom) * **Functional doors and trapdoors** with open/close animations * Limited to **4 variations per type** (uses waxed copper as base) ### Use Furniture for:[](https://docs.oraxen.com/creating-content/blocks#use-furniture-for) * **Complex 3D models** (chairs, tables, machines) * **Interactable objects** (storage, jukebox) * **Unlimited variations** (no slot limit) * Objects with **custom hitboxes** or **seats** Paper Server Configuration[](https://docs.oraxen.com/creating-content/blocks#paper-server-configuration) --------------------------------------------------------------------------------------------------------- **Strongly Recommended for Paper Servers** For best performance and to prevent physics bugs, add these settings to `config/paper-global.yml`: `block-updates: disable-noteblock-updates: true disable-tripwire-updates: true disable-chorus-plant-updates: true` Without these settings, Oraxen must listen to expensive physics events which can cause lag. Feature Comparison[](https://docs.oraxen.com/creating-content/blocks#feature-comparison) ----------------------------------------------------------------------------------------- | Feature | NoteBlock | StringBlock | ChorusBlock | ShapedBlock | Furniture | | --- | --- | --- | --- | --- | --- | | Custom sounds | ✅ | ✅ | ✅ | ✅ | ✅ | | Light emission | ✅ | ✅ | ✅ | ✅ | ✅ | | Drops | ✅ | ✅ | ✅ | ✅ | ✅ | | Hardness | ✅ | ✅ | ✅ | ✅ | ✅ | | Blast resistant | ✅ | ✅ | ✅ | ❌ | ❌ | | Immovable | ✅ | ✅ | ✅ | ❌ | ❌ | | Falling blocks | ✅ | ✅ | ✅ | ❌ | ❌ | | Waterloggable | ❌ | ✅ | ❌ | ✅ | ❌ | | Storage | ✅ | ✅ | ✅ | ❌ | ✅ | | Directional | ✅ | ❌ | ❌ | ✅ | ✅ | | Tall plants | ❌ | ✅ | ❌ | ❌ | ❌ | | Evolution/Growth | ❌ | ✅ | ❌ | ❌ | ✅ | | Seats | ❌ | ❌ | ✅ | ❌ | ✅ | | Click actions | ✅ | ✅ | ✅ | ❌ | ✅ | | Stairs/Slabs | ❌ | ❌ | ❌ | ✅ | ❌ | | Doors/Trapdoors | ❌ | ❌ | ❌ | ✅ | ❌ | Legacy: Block Mechanic (Mushroom Stem)[](https://docs.oraxen.com/creating-content/blocks#legacy-block-mechanic-mushroom-stem) ------------------------------------------------------------------------------------------------------------------------------ The original `block` mechanic using mushroom stems still exists but is **disabled by default** and considered legacy. Use NoteBlock instead for new projects. If you have existing configurations using the mushroom stem mechanic, they will continue to work. To enable it, set `enabled: true` in `mechanics.yml`: `block: enabled: true # Default: false tool_types: - WOODEN - STONE - IRON - GOLDEN - DIAMOND - NETHERITE` The configuration is identical to NoteBlock, just using `block:` instead of `noteblock:` in your item configs. Next Steps[](https://docs.oraxen.com/creating-content/blocks#next-steps) ------------------------------------------------------------------------- * [NoteBlock Mechanic](https://docs.oraxen.com/creating-content/blocks/noteblock) - Best for most custom blocks * [StringBlock Mechanic](https://docs.oraxen.com/creating-content/blocks/stringblock) - Best for plants and decorations * [ChorusBlock Mechanic](https://docs.oraxen.com/creating-content/blocks/chorusblock) - Transparent blocks * [ShapedBlock Mechanic](https://docs.oraxen.com/creating-content/blocks/shapedblock) - Stairs, slabs, doors, trapdoors, grates * [Furniture Mechanic](https://docs.oraxen.com/creating-content/furniture) - Complex 3D models Last updated on January 17, 2026 [Backpack Cosmetic](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic "Backpack Cosmetic") [NoteBlock](https://docs.oraxen.com/creating-content/blocks/noteblock "NoteBlock") --- # ClickAction Mechanic | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/items/abilities/clickaction#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Items](https://docs.oraxen.com/creating-content/items "Items") [Item Abilities](https://docs.oraxen.com/creating-content/items/abilities "Item Abilities") Click Actions Copy page ClickAction Mechanic ==================== Information[](https://docs.oraxen.com/creating-content/items/abilities/clickaction#information) ------------------------------------------------------------------------------------------------ The `clickAction` mechanic allows you to run commands, play sounds, or send messages when a player clicks on a furniture or a block. ### Configuration[](https://docs.oraxen.com/creating-content/items/abilities/clickaction#configuration) To get started, create a basic [Block](https://docs.oraxen.com/creating-content/blocks/noteblock) or [Furniture](https://docs.oraxen.com/creating-content/furniture) . Next, under the mechanics section, you can add the default clickAction mechanic under any noteblock-mechanic, furniture-mechanic or stringblock-mechanic item. `Mechanics: noteblock/furniture/stringblock: clickActions: - conditions: - '#player.hasPermission("test.permission")' actions: - '[console] say hello !'` With this setup, players will only trigger the console command `say hello ` action if they have the permission `test.permission`. If you are not using conditions, you need to place brackets where they would be: `Mechanics: noteblock/furniture/stringblock: clickActions: - conditions: [] actions: - '[console] say hello !'` This mechanic does not support furniture with no hitbox. ### Conditions[](https://docs.oraxen.com/creating-content/items/abilities/clickaction#conditions) Conditions are VERY configurable. You can use any of the “get” methods for Player or Server. See the Spigot Javadocs for all methods. TIP! Click “CTRL + F” and search “get” to find valid methods. Additionally, the Spring Documentation is a good resource for understanding how to use condition expressions. #### Condition Examples[](https://docs.oraxen.com/creating-content/items/abilities/clickaction#condition-examples) `#server.getOnlinePlayers().size() > 10` `#server.getAllowEnd()` `#server.getDefaultGameMode()` `#player.world.name == 'world'` `#player.hasPermission("test.permission")` `#player.gamemode.name() == 'ADVENTURE'` ### Actions[](https://docs.oraxen.com/creating-content/items/abilities/clickaction#actions) `[console] ` `[player] ` `[message] ` `[actionbar] ` `{source=SOURCE volume=VOLUME pitch=PITCH} [sound] ` #### Action Examples[](https://docs.oraxen.com/creating-content/items/abilities/clickaction#action-examples) `[console] say hello` `[player] say hello` `[message] Hello!` `[actionbar] Hello from the actionbar!` `{source=AMBIENT volume=0.1 pitch=1} [sound] minecraft:block.shulker_box.close` Last updated on January 17, 2026 [Custom Abilities](https://docs.oraxen.com/creating-content/items/abilities/custom-ability "Custom Abilities") [Backpack Cosmetic](https://docs.oraxen.com/creating-content/items/abilities/backpack-cosmetic "Backpack Cosmetic") --- # NoteBlock | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/blocks/noteblock#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Blocks](https://docs.oraxen.com/creating-content/blocks "Blocks") NoteBlock Copy page NoteBlock ========= The NoteBlock mechanic allows you to create custom blocks using Minecraft’s note block states. This provides up to **~800 unique block variations**, making it the best choice for most custom blocks. Not sure which block mechanic to use? See the [Blocks Overview](https://docs.oraxen.com/creating-content/blocks) for a comparison. **Paper Server Recommended** For best performance, enable this setting in `config/paper-global.yml`: `block-updates: disable-noteblock-updates: true` Creating Your First Block[](https://docs.oraxen.com/creating-content/blocks/noteblock#creating-your-first-block) ----------------------------------------------------------------------------------------------------------------- ### Parent Models[](https://docs.oraxen.com/creating-content/blocks/noteblock#parent-models) The item configuration is the same as for any Oraxen item. To generate a block model, specify the `parent_model` your block should use. **Supported parent models:** | Model | Textures | Use Case | | --- | --- | --- | | `block/cube_all` | 1 | Same texture on all sides | | `block/cube_column` | 2 | Logs, pillars (top/bottom + sides) | | `block/cross` | 1 | Plants, flowers | | `block/orientable` | 3 | Furnaces, observers | | `block/orientable_vertical` | 2 | Vertical orientation | `my_block: displayname: "My block" material: DIAMOND Pack: generate_model: true parent_model: "block/cube_all" textures: - my_block_texture.png` ### Block Mechanic Configuration[](https://docs.oraxen.com/creating-content/blocks/noteblock#block-mechanic-configuration) To use this mechanic you need to tell Oraxen which model to use. You then need to use `custom_variation` which is not already used by another block. `Mechanics: noteblock: custom_variation: 2 model: my_block drop: silktouch: false minimal_type: STONE loots: - {oraxen_item: caveblock, probability: 1.0}` ### Breaking Speed & Tools[](https://docs.oraxen.com/creating-content/blocks/noteblock#breaking-speed--tools) You can customize the breaking speed and the most suitable tools with the hardness subsection. `Mechanics: noteblock: custom_variation: 2 model: my_block hardness: 20 # makes it really hard to mine drop: silktouch: false minimal_type: STONE best_tools: - PICKAXE # faster using a pickaxe loots: - {oraxen_item: caveblock, probability: 1.0}` Block Features[](https://docs.oraxen.com/creating-content/blocks/noteblock#block-features) ------------------------------------------------------------------------------------------- ### Light Emitting Blocks[](https://docs.oraxen.com/creating-content/blocks/noteblock#light-emitting-blocks) `Mechanics: noteblock: custom_variation: 2 model: my_block light: 5 # Light level 0-15` ### Falling Blocks[](https://docs.oraxen.com/creating-content/blocks/noteblock#falling-blocks) Mimics sand & gravel behavior: `Mechanics: noteblock: is_falling: true` ### Blast Resistant[](https://docs.oraxen.com/creating-content/blocks/noteblock#blast-resistant) Make blocks survive explosions: `Mechanics: noteblock: blast_resistant: true` ### Immovable[](https://docs.oraxen.com/creating-content/blocks/noteblock#immovable) Prevent pistons from pushing the block: `Mechanics: noteblock: immovable: true` ### Ignitable Blocks[](https://docs.oraxen.com/creating-content/blocks/noteblock#ignitable-blocks) Allow the block to be ignited by fire/flint and steel: `Mechanics: noteblock: can_ignite: true` ### Storage[](https://docs.oraxen.com/creating-content/blocks/noteblock#storage) Create custom storage containers: `Mechanics: noteblock: barrier: true storage: type: STORAGE # STORAGE, PERSONAL, ENDERCHEST, or DISPOSAL rows: 5 # Default: 6 title: "My Storage" open_sound: entity.shulker.open close_sound: entity.shulker.close` Storage types: * **STORAGE** - Normal chest, anyone can access * **PERSONAL** - Per-player inventory like enderchest * **ENDERCHEST** - Accesses the actual enderchest * **DISPOSAL** - Trashcan, items deleted on close ### Limited Placing[](https://docs.oraxen.com/creating-content/blocks/noteblock#limited-placing) Restrict where blocks can be placed: `Mechanics: noteblock: limited_placing: roof: true floor: true wall: true type: ALLOW # or DENY block_types: - GRASS_BLOCK - DIRT block_tags: - base_stone_nether oraxen_blocks: - ruby_ore` ### BlockLocker Protection[](https://docs.oraxen.com/creating-content/blocks/noteblock#blocklocker-protection) Enable [BlockLocker](https://www.spigotmc.org/resources/blocklocker.3268/)   protection: `Mechanics: noteblock: blocklocker: can_protect: true protection_type: CONTAINER # CONTAINER, DOOR, or ATTACHABLE` ### Click Actions[](https://docs.oraxen.com/creating-content/blocks/noteblock#click-actions) Run commands, play sounds, or send messages when a player clicks the block. See [Click Actions](https://docs.oraxen.com/creating-content/items/abilities/clickaction) for details. Complete Ore Example[](https://docs.oraxen.com/creating-content/blocks/noteblock#complete-ore-example) ------------------------------------------------------------------------------------------------------- `amethyst_ore: displayname: "Amethyst Ore" material: DIAMOND Pack: generate_model: true parent_model: "block/cube_all" textures: - amethyst_ore Mechanics: noteblock: block_sounds: place_sound: block.stone.place break_sound: block.stone.break hit_sound: block.stone.hit step_sound: block.stone.step fall_sound: block.stone.fall volume: 0.8 pitch: 0.8 custom_variation: 1 model: amethyst_ore hardness: 6 drop: silktouch: true fortune: true minimal_type: IRON best_tools: - PICKAXE loots: - oraxen_item: amethyst probability: 1.0` This does not spawn ores in your world. See [World Generators](https://docs.oraxen.com/compatibility/world-generators) for natural ore generation. * * * Directional Blocks[](https://docs.oraxen.com/creating-content/blocks/noteblock#directional-blocks) --------------------------------------------------------------------------------------------------- This sub-mechanic allows blocks to change texture based on placement direction, like logs. ### Directional Types[](https://docs.oraxen.com/creating-content/blocks/noteblock#directional-types) | Type | Variations Used | Directions | | --- | --- | --- | | `LOG` | 3 | Y, X, Z axes | | `FURNACE` | 4 | North, South, East, West | | `DROPPER` | 6 | All 6 directions | ### Parent Block Configuration[](https://docs.oraxen.com/creating-content/blocks/noteblock#parent-block-configuration) `custom_log: displayname: "Custom Log" material: PAPER Pack: generate_model: false model: custom_log_model Mechanics: noteblock: model: custom_log_model custom_variation: 1 directional: directional_type: LOG y_block: custom_log_y x_block: custom_log_x z_block: custom_log_z hardness: 1 drop: best_tools: - AXE loots: - {oraxen_item: custom_log, probability: 1.0}` ### Child Block Configuration[](https://docs.oraxen.com/creating-content/blocks/noteblock#child-block-configuration) `custom_log_y: excludeFromInventory: true material: PAPER Mechanics: noteblock: custom_variation: 1 directional: parent_block: custom_log custom_log_x: excludeFromInventory: true material: PAPER Mechanics: noteblock: custom_variation: 2 directional: parent_block: custom_log custom_log_z: excludeFromInventory: true material: PAPER Mechanics: noteblock: custom_variation: 3 directional: parent_block: custom_log` Models are automatically rotated based on placement direction. Use `excludeFromInventory: true` on child blocks so only the parent appears in the Oraxen inventory. * * * Stripped Log Mechanic[](https://docs.oraxen.com/creating-content/blocks/noteblock#stripped-log-mechanic) --------------------------------------------------------------------------------------------------------- _Requires Oraxen 1.134.0+_ Allows custom logs to be stripped with an axe, like vanilla logs. `Mechanics: noteblock: custom_variation: 2 logStrip: stripped_log: stripped_custom_log # Block to transform into drop: bark # Optional additional drop` Last updated on January 3, 2026 [Overview](https://docs.oraxen.com/creating-content/blocks "Overview") [StringBlock](https://docs.oraxen.com/creating-content/blocks/stringblock "StringBlock") --- # ChorusBlock Mechanic | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/blocks/chorusblock#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Blocks](https://docs.oraxen.com/creating-content/blocks "Blocks") ChorusBlock Copy page ChorusBlock Mechanic ==================== The ChorusBlock mechanic allows you to create custom blocks using Minecraft’s chorus plant block states. This provides up to **63 unique block variations**. **Best used for transparent blocks** like custom leaves, glass variants, or single-block furniture that needs see-through rendering. ChorusBlock is more performant than display entities for simple transparent blocks. Not sure which block mechanic to use? See the [Custom Blocks Overview](https://docs.oraxen.com/creating-content/blocks) for a comparison. **Paper Server Recommended** For best performance and stability, enable this setting in `config/paper-global.yml`: `block-updates: disable-chorus-plant-updates: true` Without this, Oraxen must listen to expensive physics events which may cause lag and minor bugs. Basic Configuration[](https://docs.oraxen.com/creating-content/blocks/chorusblock#basic-configuration) ------------------------------------------------------------------------------------------------------- `my_chorus_block: displayname: "Custom Block" material: PAPER Pack: generate_model: true parent_model: "block/cube_all" textures: - my_block_texture.png Mechanics: chorusblock: custom_variation: 1 # Must be unique, 1-63 model: my_chorus_block hardness: 5 drop: silktouch: false loots: - { oraxen_item: my_chorus_block, probability: 1.0 }` Configuration Options[](https://docs.oraxen.com/creating-content/blocks/chorusblock#configuration-options) ----------------------------------------------------------------------------------------------------------- | Option | Type | Description | | --- | --- | --- | | `custom_variation` | integer | **Required.** Unique ID from 1-63 | | `model` | string | Block model path | | `hardness` | integer | Break time multiplier (default: 1) | | `light` | integer | Light level 0-15 (default: 0) | | `is_falling` | boolean | Falls like sand/gravel (default: false) | | `blast_resistant` | boolean | Resists explosions (default: false) | | `immovable` | boolean | Cannot be moved by pistons (default: false) | | `drop` | object | Drop configuration | | `block_sounds` | object | Custom sounds | | `limited_placing` | object | Placement restrictions | | `blocklocker` | object | BlockLocker protection | | `clickActions` | list | Actions on click | | `storage` | object | Container configuration | | `seat` | object | Seating configuration | Custom Variation[](https://docs.oraxen.com/creating-content/blocks/chorusblock#custom-variation) ------------------------------------------------------------------------------------------------- Each ChorusBlock must have a unique `custom_variation` between 1 and 63. This ID determines which chorus plant state is used to represent your block. `# Block 1 ruby_ore: Mechanics: chorusblock: custom_variation: 1 # ... # Block 2 sapphire_ore: Mechanics: chorusblock: custom_variation: 2 # ...` Never reuse a `custom_variation` value. Each must be unique across all ChorusBlock items. Drop Configuration[](https://docs.oraxen.com/creating-content/blocks/chorusblock#drop-configuration) ----------------------------------------------------------------------------------------------------- Configure what drops when the block is broken: `Mechanics: chorusblock: custom_variation: 1 drop: silktouch: true # Only drop with silk touch loots: - oraxen_item: my_block probability: 1.0 - oraxen_item: bonus_item probability: 0.25 max_amount: 3` Custom Sounds[](https://docs.oraxen.com/creating-content/blocks/chorusblock#custom-sounds) ------------------------------------------------------------------------------------------- Add custom sounds for block interactions: `Mechanics: chorusblock: custom_variation: 1 block_sounds: place_sound: block.stone.place break_sound: block.stone.break hit_sound: block.stone.hit step_sound: block.stone.step fall_sound: block.stone.fall` You can also customize volume and pitch: `Mechanics: chorusblock: block_sounds: place: sound: block.amethyst_block.place volume: 1.0 pitch: 0.8 break_sound: block.amethyst_block.break` Light Emission[](https://docs.oraxen.com/creating-content/blocks/chorusblock#light-emission) --------------------------------------------------------------------------------------------- Make blocks emit light: `Mechanics: chorusblock: custom_variation: 1 light: 12 # Light level 0-15` Falling Blocks[](https://docs.oraxen.com/creating-content/blocks/chorusblock#falling-blocks) --------------------------------------------------------------------------------------------- Create blocks that fall like sand or gravel: `Mechanics: chorusblock: custom_variation: 1 is_falling: true` Blast Resistant[](https://docs.oraxen.com/creating-content/blocks/chorusblock#blast-resistant) ----------------------------------------------------------------------------------------------- Make blocks resist explosions: `Mechanics: chorusblock: custom_variation: 1 blast_resistant: true` Immovable[](https://docs.oraxen.com/creating-content/blocks/chorusblock#immovable) ----------------------------------------------------------------------------------- Prevent pistons from moving the block: `Mechanics: chorusblock: custom_variation: 1 immovable: true` Limited Placing[](https://docs.oraxen.com/creating-content/blocks/chorusblock#limited-placing) ----------------------------------------------------------------------------------------------- Restrict where blocks can be placed: `Mechanics: chorusblock: custom_variation: 1 limited_placing: roof: false floor: true wall: false type: ALLOW # or DENY block_types: - GRASS_BLOCK - DIRT block_tags: - base_stone_overworld oraxen_blocks: - custom_stone` BlockLocker Protection[](https://docs.oraxen.com/creating-content/blocks/chorusblock#blocklocker-protection) ------------------------------------------------------------------------------------------------------------- Enable [BlockLocker](https://www.spigotmc.org/resources/blocklocker.3268/)   protection: `Mechanics: chorusblock: custom_variation: 1 blocklocker: can_protect: true protection_type: CONTAINER # CONTAINER, DOOR, or ATTACHABLE` Click Actions[](https://docs.oraxen.com/creating-content/blocks/chorusblock#click-actions) ------------------------------------------------------------------------------------------- Run commands or play sounds when clicked. See [clickAction mechanic](https://docs.oraxen.com/creating-content/items/abilities/clickaction) for details. `Mechanics: chorusblock: custom_variation: 1 clickActions: - conditions: - "has_permission{perm=my.permission}" actions: - "[console] say %player% clicked the block!"` Storage[](https://docs.oraxen.com/creating-content/blocks/chorusblock#storage) ------------------------------------------------------------------------------- Turn your block into a container: `Mechanics: chorusblock: custom_variation: 1 storage: type: STORAGE # STORAGE, SHULKER, PERSONAL, DISPOSAL, or ENDERCHEST rows: 3 # Number of rows (1-6) title: "My Storage" # Container title open_sound: block.chest.open close_sound: block.chest.close` Storage types: * `STORAGE` - Standard shared container * `SHULKER` - Items stay in block when broken * `PERSONAL` - Per-player storage * `DISPOSAL` - Items are deleted when closed * `ENDERCHEST` - Opens player’s ender chest Seats[](https://docs.oraxen.com/creating-content/blocks/chorusblock#seats) --------------------------------------------------------------------------- Let players sit on your block (great for chairs and benches): `Mechanics: chorusblock: custom_variation: 1 seat: height: 0.5 # Height offset from block top yaw: 0 # Optional: fixed rotation when seated` When a player right-clicks a block with a seat, they will sit on it. The seat uses an invisible armor stand entity. Complete Example[](https://docs.oraxen.com/creating-content/blocks/chorusblock#complete-example) ------------------------------------------------------------------------------------------------- Here’s a full example of a custom ore block: `chorus_ruby_ore: displayname: "Ruby Ore" material: PAPER Pack: generate_model: true parent_model: "block/cube_all" textures: - ruby_ore.png Mechanics: chorusblock: custom_variation: 5 model: chorus_ruby_ore hardness: 8 light: 3 blast_resistant: true block_sounds: place_sound: block.deepslate.place break_sound: block.deepslate.break step_sound: block.deepslate.step drop: silktouch: true loots: - oraxen_item: ruby probability: 1.0 max_amount: 2 limited_placing: floor: true roof: true wall: true type: ALLOW block_tags: - base_stone_overworld - base_stone_nether` Comparison with Other Block Mechanics[](https://docs.oraxen.com/creating-content/blocks/chorusblock#comparison-with-other-block-mechanics) ------------------------------------------------------------------------------------------------------------------------------------------- | Feature | NoteBlock | StringBlock | ChorusBlock | | --- | --- | --- | --- | | Max variations | ~800 | 127 | 63 | | Base block | Note Block | Tripwire | Chorus Plant | | Custom sounds | Yes | Yes | Yes | | Light emission | Yes | Yes | Yes | | Falling blocks | Yes | Yes | Yes | | Blast resistant | Yes | Yes | Yes | | Immovable | Yes | Yes | Yes | | Storage | Yes | Yes | Yes | | Click actions | Yes | Yes | Yes | | Seats | No | No | Yes | | Directional | Yes | No | No | | Waterloggable | No | Yes | No | Choose ChorusBlock for **transparent blocks** where see-through rendering matters (leaves, glass-like blocks, simple transparent furniture), or when you need **seats** on blocks. For opaque blocks, prefer NoteBlock which has more available slots (~800 vs 63). Last updated on January 3, 2026 [StringBlock](https://docs.oraxen.com/creating-content/blocks/stringblock "StringBlock") [FarmBlock](https://docs.oraxen.com/creating-content/blocks/farmblock "FarmBlock") --- # StringBlock | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/blocks/stringblock#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Blocks](https://docs.oraxen.com/creating-content/blocks "Blocks") StringBlock Copy page StringBlock =========== The StringBlock mechanic allows you to create custom blocks using Minecraft’s tripwire states. This provides up to **127 unique block variations** and is ideal for plants, flowers, and other decorative elements. Not sure which block mechanic to use? See the [Blocks Overview](https://docs.oraxen.com/creating-content/blocks) for a comparison. **Paper Server Recommended** For best performance, enable this setting in `config/paper-global.yml`: `block-updates: disable-tripwire-updates: true` How Does It Work?[](https://docs.oraxen.com/creating-content/blocks/stringblock#how-does-it-work) -------------------------------------------------------------------------------------------------- StringBlocks use tripwire-based hitboxes, allowing you to make small decorative objects that players can walk through. They are more optimized than furniture for simple decorations. **Key features:** * Players can walk through StringBlocks * Waterloggable (can be placed underwater) * Variations 65-127 have smaller hitboxes than 1-64 ### Global Configuration[](https://docs.oraxen.com/creating-content/blocks/stringblock#global-configuration) `stringblock: tool_types: - WOODEN - STONE - IRON - GOLDEN - DIAMOND - NETHERITE enabled: true` Creating a Decoration[](https://docs.oraxen.com/creating-content/blocks/stringblock#creating-a-decoration) ----------------------------------------------------------------------------------------------------------- ### Basic Configuration[](https://docs.oraxen.com/creating-content/blocks/stringblock#basic-configuration) `jasmine_flower: displayname: "Jasmine Flower" material: PAPER Pack: generate_model: true parent_model: "block/cross" textures: - custom/flowers/jasmine_flower.png Mechanics: stringblock: custom_variation: 2 model: jasmine_flower hardness: 2 drop: silktouch: false loots: - { oraxen_item: jasmine_flower, probability: 1.0 }` Block Features[](https://docs.oraxen.com/creating-content/blocks/stringblock#block-features) --------------------------------------------------------------------------------------------- ### Tall Plants[](https://docs.oraxen.com/creating-content/blocks/stringblock#tall-plants) Create two-block-tall plants like vanilla tall grass or sunflowers: `Mechanics: stringblock: custom_variation: 5 is_tall: true # Creates a 2-block tall plant` ### Random Placement[](https://docs.oraxen.com/creating-content/blocks/stringblock#random-placement) Randomly choose from a list of blocks when placed (great for varied flower patches): `Mechanics: stringblock: custom_variation: 10 random_place: blocks: - red_flower - blue_flower - yellow_flower` ### Light Emission[](https://docs.oraxen.com/creating-content/blocks/stringblock#light-emission) `Mechanics: stringblock: custom_variation: 6 light: 10 # 0-15` ### Blast Resistant[](https://docs.oraxen.com/creating-content/blocks/stringblock#blast-resistant) `Mechanics: stringblock: blast_resistant: true` ### Immovable[](https://docs.oraxen.com/creating-content/blocks/stringblock#immovable) Prevent pistons from pushing: `Mechanics: stringblock: immovable: true` ### BlockLocker Protection[](https://docs.oraxen.com/creating-content/blocks/stringblock#blocklocker-protection) `Mechanics: stringblock: blocklocker: can_protect: true protection_type: CONTAINER # CONTAINER, DOOR, or ATTACHABLE` ### Falling Blocks[](https://docs.oraxen.com/creating-content/blocks/stringblock#falling-blocks) Create blocks that fall like sand or gravel: `Mechanics: stringblock: custom_variation: 8 is_falling: true` ### Storage[](https://docs.oraxen.com/creating-content/blocks/stringblock#storage) Turn your block into a container: `Mechanics: stringblock: custom_variation: 9 storage: type: STORAGE # STORAGE, SHULKER, PERSONAL, DISPOSAL, or ENDERCHEST rows: 3 # Number of rows (1-6) title: "My Storage" # Container title open_sound: block.chest.open close_sound: block.chest.close` Storage types: * `STORAGE` - Standard shared container * `SHULKER` - Items stay in block when broken * `PERSONAL` - Per-player storage * `DISPOSAL` - Items are deleted when closed * `ENDERCHEST` - Opens player’s ender chest ### Click Actions[](https://docs.oraxen.com/creating-content/blocks/stringblock#click-actions) Run commands or play sounds when clicked. See [clickAction mechanic](https://docs.oraxen.com/creating-content/items/abilities/clickaction) for details. `Mechanics: stringblock: custom_variation: 10 clickActions: - conditions: - "has_permission{perm=my.permission}" actions: - "[console] say %player% clicked the block!"` Custom Models[](https://docs.oraxen.com/creating-content/blocks/stringblock#custom-models) ------------------------------------------------------------------------------------------- Use your own 3D models: `oak_log_mini: displayname: "oak_log_mini" material: PAPER Pack: generate_model: false model: custom/furniture/oak_log_mini Mechanics: stringblock: custom_variation: 3 model: custom/furniture/oak_log_mini hardness: 2 drop: silktouch: false loots: - { oraxen_item: oak_log_mini, probability: 1.0 }` ![](https://cdn.discordapp.com/attachments/958524021035647046/961424759718047784/unknown.png) * * * Sapling Mechanic[](https://docs.oraxen.com/creating-content/blocks/stringblock#sapling-mechanic) ------------------------------------------------------------------------------------------------- _Requires Oraxen 1.136.0+_ Create custom saplings that can grow into structures (trees, plants, etc.). ### Global Configuration[](https://docs.oraxen.com/creating-content/blocks/stringblock#global-configuration-1) `stringblock: sapling_growth_check_delay: 4000 # Ticks between growth checks enabled: true` ### Sapling Configuration[](https://docs.oraxen.com/creating-content/blocks/stringblock#sapling-configuration) `custom_sapling: Mechanics: stringblock: custom_variation: 20 sapling: canGrowNaturally: true # Grows over time naturalGrowthTime: 6000 # Ticks until growth canGrowFromBoneMeal: true # Can be bone-mealed boneMealGrowChance: 50 # % chance per bone meal growSound: block.grass.break minLightLevel: 4 # Minimum light to grow requiresWaterSource: false # Needs nearby water schematicName: custom_tree # Structure to spawn` The `schematicName` refers to a schematic file that will be placed when the sapling grows. This allows you to create custom trees or any structure. Last updated on January 3, 2026 [NoteBlock](https://docs.oraxen.com/creating-content/blocks/noteblock "NoteBlock") [ChorusBlock](https://docs.oraxen.com/creating-content/blocks/chorusblock "ChorusBlock") --- # Furniture | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/furniture#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") FurnitureOverview Copy page Furniture ========= Oraxen lets you create custom 3D furniture like chairs, tables, lamps, and decorations. Furniture uses entity-based rendering for complex shapes that blocks can’t achieve. ![Example furniture](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fimage%20(3).11c4ac9f.png&w=1920&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) When to Use Furniture[](https://docs.oraxen.com/creating-content/furniture#when-to-use-furniture) -------------------------------------------------------------------------------------------------- | Use Case | Furniture | Blocks | | --- | --- | --- | | Complex 3D models | ✅ Best choice | ❌ Limited | | Sittable chairs | ✅ Built-in | ❌ Not possible | | Rotatable objects | ✅ Any angle | ⚠️ 4 directions | | Large decorations | ✅ Multi-block hitbox | ⚠️ Complex | | Mining/breaking | ⚠️ Instant | ✅ Natural | | Performance at scale | ⚠️ Entity-based | ✅ Better | Use furniture for decorative objects, chairs, tables, and anything requiring complex 3D models. Use [custom blocks](https://docs.oraxen.com/creating-content/blocks) for ores, building materials, and things players mine frequently. Key Features[](https://docs.oraxen.com/creating-content/furniture#key-features) -------------------------------------------------------------------------------- | Feature | Description | | --- | --- | | [Display Entities](https://docs.oraxen.com/creating-content/furniture/display-entities) | Modern rendering with transforms and animations | | [Barriers & Hitboxes](https://docs.oraxen.com/creating-content/furniture/display-entities#hitbox) | Collision and interaction areas | | [Seats](https://docs.oraxen.com/creating-content/furniture#seats) | Let players sit on furniture | | [Storage](https://docs.oraxen.com/creating-content/furniture#storage) | Custom containers and chests | | [Light Emission](https://docs.oraxen.com/creating-content/furniture#light) | Furniture that glows | | [Evolution](https://docs.oraxen.com/creating-content/furniture#evolution) | Crops and plants that grow over time | | [ModelEngine](https://docs.oraxen.com/compatibility/modelengine-custom-mobs) | Animated models with Blockbench | Basic Configuration[](https://docs.oraxen.com/creating-content/furniture#basic-configuration) ---------------------------------------------------------------------------------------------- `table: displayname: "Table" material: DIAMOND Pack: generate_model: false model: default/table Mechanics: furniture: type: DISPLAY_ENTITY barrier: true drop: silktouch: false loots: - { oraxen_item: table, probability: 1.0 }` Custom Sounds[](https://docs.oraxen.com/creating-content/furniture#custom-sounds) ---------------------------------------------------------------------------------- Furniture, like custom blocks, can have custom sounds. Currently the options are place/break/hit/step/fall. `Mechanics: furniture: block_sounds: place_sound: block.stone.place break_sound: block.stone.break hit_sound: my.custom.hitsound # Custom sound as defined in Oraxen/sound.yml step_sound: my.custom.stepsound # Requires a sound-file in the Oraxen/pack-folder aswell fall_sound: my.custom.fallsound` All the volume and pitch values are set to be what Minecraft uses for blocks normally. If you want to change the volume or pitch, you can do so by using the format below. Keep in mind these two formats are compatible with eachother. We recommend just use the default one, but the option is there if you want to change it. `Mechanics: furniture: block_sounds: place: sound: block.stone.place volume: 1.0 pitch: 0.2 break_sound: block.stone.break hit_sound: my.custom.hitsound # Custom sound as defined in Oraxen/sound.yml step_sound: my.custom.stepsound # Requires a sound-file in the Oraxen/pack-folder aswell fall_sound: my.custom.fallsound` Rotatable[](https://docs.oraxen.com/creating-content/furniture#rotatable) -------------------------------------------------------------------------- To make a furniture rotatable, simply add the following to your item’s config. `Mechanics: furniture: rotatable: true` ModelEngine Furniture[](https://docs.oraxen.com/creating-content/furniture#modelengine-furniture) -------------------------------------------------------------------------------------------------- To make use of a ModelEngine model as your furniture, simply add the following to your item’s config: `Mechanics: furniture: modelengine_id: name_of_your_bbmodel_file` Jukebox[](https://docs.oraxen.com/creating-content/furniture#jukebox) ---------------------------------------------------------------------- Lets this furniture accept music discs and custom music discs which will be played. You can tweak the `volume` and `pitch` of the music from the jukebox. There is also a `permission` field, which can be used if you only want certain players to be able to play music from the jukebox. By default permission is blank, which means anyone can play music from the jukebox. You can also specify an `active_model` to change the furniture’s appearance when a disc is playing: `turntable: Mechanics: furniture: jukebox: active_model: opened # References a key from Pack.models volume: 1.0 pitch: 1.0 permission: "oraxen.jukebox.play" Pack: model: default/turntable_closed models: opened: default/turntable_opened # Model shown when playing` The `active_model` references a key defined in `Pack.models`. See [Pack.models](https://docs.oraxen.com/creating-content/furniture#packmodels) for more details. Barriers[](https://docs.oraxen.com/creating-content/furniture#barriers) ------------------------------------------------------------------------ Barriers are invisible blocks placed with your furniture so that it has a realistic hitbox. You can place a single one or a list relative to the position of the player who places them. Note: For Display Entity furniture, you can use `hitbox` instead of barriers for a simpler configuration. Barriers are still useful for larger furniture or when you need collision. ### Single barrier:[](https://docs.oraxen.com/creating-content/furniture#single-barrier) `Mechanics: furniture: barrier: true` ### Multiple barriers:[](https://docs.oraxen.com/creating-content/furniture#multiple-barriers) `Mechanics: furniture: barriers: - origin # Shorthand for { x: 0, y: 0, z: 0 } - z: 1 # If not specified, coord is 0 -> { x: 0, y: 0, z: 1 } - z: 2 - x: 1 - { x: 1, z: 1 } - x: 1 z: 2` Seats ===== **Seats are only available when barriers are enabled.** Currently it will also spawn a seat for every barrier, if there is multiple ones. You can alter the height-offset of seats with the following configuration: `Mechanics: furniture: seat: { height: 0.5 }` You can also adjust the rotation if desired by adding a yaw section. Keep in mind it is recommended to leave this off `Mechanics: furniture: seat: { height: -0.5, yaw: 90 }` Restrict Rotation ================= You can restrict the amount of rotation-facings a furniture has with `restricted_rotation`. It can be set to STRICT or VERY\_STRICT, with 8 and 4 facings respectively. `chair: Mechanics: furniture: restricted_rotation: VERY_STRICT #STRICT is default if unspecified` Limited placing =============== You can customize what blocks a custom block/furniture can be placed on with `limited_placing` subsection. You can use the `roof`, `floor` and `wall` options to dictate where a block can be placed. By default, all are set to `true`. The `type` specifies if it should only be allowed on or denied on specific blocks. If type is `ALLOW` the block can only be placed on the given blocks. If the type is `DENY` can be placed on all blocks not matching the given blocks. There is also a `radius_limitation` option, which allows you to limit the amount of a certain furniture within a radius. `chair: Mechanics: furniture: limited_placing: radius_limitation: radius: 20 amount: 10 roof: false floor: true wall: false type: ALLOW block_types: - GRASS_BLOCK - DIRT block_tags: - base_stone_nether oraxen_blocks: - chair - ruby_ore` The `block_tags` can be found at [this page](https://minecraft.fandom.com/wiki/Tag#Block_tags)  . Useful if you want to allow/deny a group of blocks. The `block_types` are materials. Useful if you want to allow/deny a specific list block. The `oraxen_blocks` are blocks defined in the oraxen configuration. This allows all custom blocks and furniture in here, but furniture requires a barrier-hitbox. Storage ======= This is a sub-mechanic for furniture and noteblock mechanics, that let you make a custom storage container. Essentially a chest, closet or whatever you might want. There’s a few different types: _STORAGE, PERSONAL, ENDERCHEST & DISPOSAL_. **STORAGE** is similar to a normal chest. Anyone can open it and view the content of it. **PERSONAL** is essentially a custom enderchest, letting you edit the row-count and so on. **ENDERCHEST** is literally just the enderchest inventory, but letting you make a custom block/furniture to access it. **DISPOSAL** is a custom trashcan, letting you throw items in it, and they will be deleted when closed. `Mechanics: furniture: barrier: true storage: type: STORAGE rows: 5 # Default: 6 title: "My Storage" # Default: "Storage" open_sound: entity.shulker.open # Default: entity.chest.open close_sound: entity.shulker.close # Default: entity.chest.close` This mechanic requires a barrier(s) if used with furniture! Light[](https://docs.oraxen.com/creating-content/furniture#light) ------------------------------------------------------------------ You can configure your furniture so it emits light. This option corresponds to light intensity and must be between 1 and 15. `Mechanics: furniture: barrier: true light: 5 drop: silktouch: false loots: - { oraxen_item: table, probability: 1.0 }` BlockLocker[](https://docs.oraxen.com/creating-content/furniture#blocklocker) ------------------------------------------------------------------------------ You can use this to allow protection via [BlockLocker](https://www.spigotmc.org/resources/blocklocker.3268/)   Valid protectionTypes are CONTAINER, DOOR, ATTACHABLE `Mechanics: furniture: blocklocker: can_protect: true protection_type: CONTAINER` Hardness[](https://docs.oraxen.com/creating-content/furniture#hardness) ------------------------------------------------------------------------ You can set a custom hardness for your furniture, which affects how long it takes to break. `Mechanics: furniture: hardness: 5 # Default: 1` Alternative Display Item[](https://docs.oraxen.com/creating-content/furniture#alternative-display-item) -------------------------------------------------------------------------------------------------------- Use a different Oraxen item’s model when the furniture is placed. Useful for having a different inventory icon vs placed appearance. `Mechanics: furniture: item: different_item_id # The item model to display when placed` Placement Requirements[](https://docs.oraxen.com/creating-content/furniture#placement-requirements) ---------------------------------------------------------------------------------------------------- Require the furniture to be placed on farmland or a custom Oraxen farm block. `Mechanics: furniture: farmland_required: true # Requires vanilla farmland # OR farmblock_required: true # Requires Oraxen custom farm block` Evolution[](https://docs.oraxen.com/creating-content/furniture#evolution) -------------------------------------------------------------------------- Make furniture evolve over time into different stages, like crops growing. Useful for custom plants. `Mechanics: furniture: evolution: delay: 6000 # Ticks between evolution checks next_stage: my_plant_stage2 # The item ID to evolve into probability: 0.5 # Chance to evolve (0.0 to 1.0) light_boost: # Optional: speed up in light minimum_light_level: 9 boost_tick: 2000 # Ticks to add per check when light is sufficient rain_boost: # Optional: speed up in rain boost_tick: 1500 bone_meal: # Optional: allow bone meal to advance growth chance: 30 # Percentage chance to advance on bone meal use` Click Actions[](https://docs.oraxen.com/creating-content/furniture#click-actions) ---------------------------------------------------------------------------------- Run commands, play sounds, or send messages when a player clicks the furniture. See the [clickAction mechanic](https://docs.oraxen.com/creating-content/items/abilities/clickaction) for detailed configuration. Pack.models[](https://docs.oraxen.com/creating-content/furniture#packmodels) ----------------------------------------------------------------------------- Define multiple models for a single item using `Pack.models`. This eliminates the need for fake helper items when you need different visual states. `my_furniture: Pack: model: default/my_furniture # Base model models: active: default/my_furniture_active # Additional model broken: default/my_furniture_broken # Another model` These models are auto-registered as: * `oraxen:my_furniture` → base model * `oraxen:my_furniture/active` → active variant * `oraxen:my_furniture/broken` → broken variant ### Use Cases[](https://docs.oraxen.com/creating-content/furniture#use-cases) **Jukebox with playing state:** `turntable: Mechanics: furniture: jukebox: active_model: opened # Swap to this model when playing Pack: model: default/turntable_closed models: opened: default/turntable_opened` **Plant with growth stages:** `seed: Mechanics: furniture: stages: - model: stage0 evolution: { delay: 10000 } - model: stage1 # ... Pack: models: stage0: default/plant/stage0 stage1: default/plant/stage1` See [farming mechanic](https://docs.oraxen.com/creating-content/furniture/farming) for detailed plant/evolution configuration. Next Steps[](https://docs.oraxen.com/creating-content/furniture#next-steps) ---------------------------------------------------------------------------- * [Display Entities](https://docs.oraxen.com/creating-content/furniture/display-entities) - Modern furniture rendering and hitboxes * [Farming Mechanic](https://docs.oraxen.com/creating-content/furniture/farming) - Custom crops and plants * [Create Your First Item](https://docs.oraxen.com/creating-content/items) - Learn item basics first Last updated on January 17, 2026 [ShapedBlock](https://docs.oraxen.com/creating-content/blocks/shapedblock "ShapedBlock") [Display Entities](https://docs.oraxen.com/creating-content/furniture/display-entities "Display Entities") --- # Furniture Position | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/furniture/position#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Furniture](https://docs.oraxen.com/creating-content/furniture "Furniture") Position & Rotation Copy page Furniture Position ================== If your server is using 1.19.4 or above, there is a new entity-type called Display-Entities. These entities have some additional properties related to furniture-position, that you should set. The main one being `display_transform`, which dictates what Transform it should use to display your item. You can get a better explanation [here](https://docs.oraxen.com/creating-content/furniture/display-entities#display-entity-properties) . Below is an example of a furniture with the `type` set to `ITEM_FRAME` or `DISPLAY_ENTITY` with `display_transform` set to `FIXED`. To start using furniture without it looking bad you need to adjust its position, let’s say you used BlockBench to create the item then go to ![](https://hibiscuscreative.notion.site/image/https%3A%2F%2Fs3-us-west-2.amazonaws.com%2Fsecure.notion-static.com%2Fc051221b-af62-46a7-a988-c9fdaf3d9c47%2FUntitled.png?table=block&id=bb951dcd-f5c4-4a1d-a73b-a7cdb36d18f0&spaceId=d94d82a0-f00a-4f51-82f0-03722550c74d&width=1340&userId=&cache=v2) Most often, furniture is done using invisible item frames. So, you’ll need to modify the translation settings for “Frame”. ![](https://hibiscuscreative.notion.site/image/https%3A%2F%2Fs3-us-west-2.amazonaws.com%2Fsecure.notion-static.com%2F451c946e-fb1b-45c5-9738-be49b3fd4a5e%2FUntitled.png?table=block&id=07248014-959d-40c7-b9bd-74a038a3c361&spaceId=d94d82a0-f00a-4f51-82f0-03722550c74d&width=1440&userId=&cache=v2) And you got it! Last updated on January 3, 2026 [Display Entities](https://docs.oraxen.com/creating-content/furniture/display-entities "Display Entities") [Farming & Evolution](https://docs.oraxen.com/creating-content/furniture/farming "Farming & Evolution") --- # Commands | Oraxen Docs [Skip to Content](https://docs.oraxen.com/usage/commands#nextra-skip-nav) Commands & RecipesCommands Copy page Commands ======== General informations[](https://docs.oraxen.com/usage/commands#general-informations) ------------------------------------------------------------------------------------ All the oraxen commands start with the same label. This label, oraxen, has a few aliases so if you don’t want to type `/oraxen` every time you can also use `/oxn` and even `/o` . For this tutorial we will use /o because it is the shortest, but if this command is already used by another plugin or you can’t use it for any reason, just replace the label of the commands starting with a /o by /oxn or /oraxen. Get the items[](https://docs.oraxen.com/usage/commands#get-the-items) ---------------------------------------------------------------------- ### For testing[](https://docs.oraxen.com/usage/commands#for-testing) The main benefit of this method is that it allows you to see all the items at the same time and therefore to be more efficient (you just have to click on an item to make it appear in your inventory). But you can’t use it to automatically give an item to another player (for example from the shop). #### Usage: `/oraxen inventory`[](https://docs.oraxen.com/usage/commands#usage-oraxen-inventory) #### Permissions:[](https://docs.oraxen.com/usage/commands#permissions) `oraxen.command.inventory.view # Allows to view the inventory visualizer oraxen.command.inventory.give# Allows to get item from the inventory visualizer oraxen.command.inventory.* # Gives you the two previous permissions` ### In order to give them[](https://docs.oraxen.com/usage/commands#in-order-to-give-them) This command will be mainly useful if you want to give an item to another player or when you want to automate the give. If the target of this command has its inventory full, the stack will be looted on the ground. #### Usage:[](https://docs.oraxen.com/usage/commands#usage) `/oraxen give # Gives amount items to player` #### Permission:[](https://docs.oraxen.com/usage/commands#permission) `oraxen.command.give # Allows you to use /o give` Repair[](https://docs.oraxen.com/usage/commands#repair) -------------------------------------------------------- ### Repair only one item[](https://docs.oraxen.com/usage/commands#repair-only-one-item) This command can be used to repair an item you hold in your main hand. You can configure the plugin to repair only items using oraxen custom durability or also vanilla durability. #### Usage:[](https://docs.oraxen.com/usage/commands#usage-1) `/oraxen repair hand # Repair the item you hold` #### Permissions:[](https://docs.oraxen.com/usage/commands#permissions-1) `oraxen.command.repair # Allows to use the /o repair command` ### Repair all items in your inventory[](https://docs.oraxen.com/usage/commands#repair-all-items-in-your-inventory) This command can be used to repair every single item in your inventory (or in your armor slots). You can configure the plugin to repair only items using oraxen custom durability or also vanilla durability. #### Usage:[](https://docs.oraxen.com/usage/commands#usage-2) `/oraxen repair all # Repair all your item (inside your inventory)` #### Permissions:[](https://docs.oraxen.com/usage/commands#permissions-2) `oraxen.command.repair # so you are also able to use /o repair hand oraxen.command.repair.all # Allows to use the /o repair all command` Manage recipes[](https://docs.oraxen.com/usage/commands#manage-recipes) ------------------------------------------------------------------------ This command allows you to add new recipes to the configuration directly from the game using recipes builder. For more information on how to use it, see [Recipes](https://docs.oraxen.com/usage/recipes) . ![Recipe showcase using /o recipes show all](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Frecipe_showcase.a6de57c2.png&w=3840&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) #### Usage:[](https://docs.oraxen.com/usage/commands#usage-3) `/oraxen recipes builder # Creates a recipe builder of type and opens it /oraxen recipes save # Saves your recipe with name /oraxen recipes show all # Shows you the loaded recipes /oraxen recipes show # Shows you one recipe` #### Permission:[](https://docs.oraxen.com/usage/commands#permission-1) `oraxen.command.recipes # Allows you to create new recipes via /o recipes` Emojis[](https://docs.oraxen.com/usage/commands#emojis) -------------------------------------------------------- This command displays a list of available emojis/glyphs. The output depends on the `emoji_list_permission_only` setting (see [Glyphs Settings](https://docs.oraxen.com/plugin-setup/plugin-settings#glyphs) ). #### Usage:[](https://docs.oraxen.com/usage/commands#usage-4) `/oraxen emojis # Shows available emojis with permission status` #### Permission:[](https://docs.oraxen.com/usage/commands#permission-2) `oraxen.command.emojis # Allows you to use /o emojis` Pack[](https://docs.oraxen.com/usage/commands#pack) ---------------------------------------------------- This command allows you to interact with the Oraxen pack: send the configured message to download it from the internet or load it directly through the game. #### Usage:[](https://docs.oraxen.com/usage/commands#usage-5) `/oraxen pack send # Send to the pack directly through the game /oraxen pack msg # Send to the configured message` #### Permission:[](https://docs.oraxen.com/usage/commands#permission-3) `oraxen.command.pack # Allows you to use /o pack` Item info[](https://docs.oraxen.com/usage/commands#item-info) -------------------------------------------------------------- This command allows you to print item infos and custom-model-data-id #### Usage:[](https://docs.oraxen.com/usage/commands#usage-6) `/oraxen iteminfo # prints the requested item information` #### Permission:[](https://docs.oraxen.com/usage/commands#permission-4) `oraxen.command.iteminfo # Allows you to use /o iteminfo` Reload[](https://docs.oraxen.com/usage/commands#reload) -------------------------------------------------------- This command allows you to reload oraxen configurations quickly and without causing bugs (you cannot reload oraxen using plugman). However, it should be noted that for the time being, customs crafts created with oraxen cannot be reloaded. #### Usage[](https://docs.oraxen.com/usage/commands#usage-7) `/oraxen reload all # Reloads items configuration, Reloads recipes configuration, regenerates the pack and upload it /oraxen reload items # Reloads items configuration /oraxen reload pack # Regenerates resourcepack and upload it /oraxen reload recipes # Reloads recipes configuration` #### Permission:[](https://docs.oraxen.com/usage/commands#permission-5) `oraxen.command.reload # Allows you to use /o reload` Debug[](https://docs.oraxen.com/usage/commands#debug) ------------------------------------------------------ I wish you never have to use it but if you ever have a bug with Oraxen, I will probably ask you to execute this command to get more information about your installation. This will display advanced logs in the console. #### Usage:[](https://docs.oraxen.com/usage/commands#usage-8) It will depend on the situation and could change with the updates of oraxen, I will explain everything. #### Permissions:[](https://docs.oraxen.com/usage/commands#permissions-3) `oraxen.command.debug # Allows you to use /o debug` Last updated on January 3, 2026 [Pack Merging](https://docs.oraxen.com/plugin-setup/pack-merging "Pack Merging") [Default items](https://docs.oraxen.com/usage/default-items "Default items") --- # Default Items | Oraxen Docs [Skip to Content](https://docs.oraxen.com/usage/default-items#nextra-skip-nav) [Commands & Recipes](https://docs.oraxen.com/usage/commands "Commands & Recipes") Default items Copy page Default Items ============= Armors[](https://docs.oraxen.com/usage/default-items#armors) ------------------------------------------------------------- ### Emerald armor[](https://docs.oraxen.com/usage/default-items#emerald-armor) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fimage.1382683c.png&w=3840&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) The **emerald armor** gives you some extra hearts and a good protection (better than diamond). It doesn’t have a big durability though. ### Obsidian armor[](https://docs.oraxen.com/usage/default-items#obsidian-armor) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fobsidian_armor.b3786b2a.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) The **obsidian armor** is not as good as a diamond armor but has a ludicrous durability. Blocks[](https://docs.oraxen.com/usage/default-items#blocks) ------------------------------------------------------------- ### Ores[](https://docs.oraxen.com/usage/default-items#ores) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fores.91fba864.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) **Orax, ruby, onyx** and **amethyst** ores support fortune and silktouch enchantments. ### Caveblock[](https://docs.oraxen.com/usage/default-items#caveblock) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fcaveblock.0e717a4b.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) A **caveblock** is a block which allows you to see through the other blocks (like a kind of xray), players LOVE it in faction servers. Hats[](https://docs.oraxen.com/usage/default-items#hats) --------------------------------------------------------- ### Crown[](https://docs.oraxen.com/usage/default-items#crown) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fcrown.70dafc96.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) A nice **crown** to look like a king which gives you armor protection and armor toughness. ### Anubis head[](https://docs.oraxen.com/usage/default-items#anubis-head) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fanubis_helmet.e6e5ba61.jpg&w=3840&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) The **anubis** head gives you nightvision and some protection. ### Witch hat[](https://docs.oraxen.com/usage/default-items#witch-hat) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fwitch_hat.9ceb212f.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) A nice **witch hat** which gives you armor protection and armor toughness. ### Pharaoh head[](https://docs.oraxen.com/usage/default-items#pharaoh-head) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fpharaon.21824f56.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) The incredible legendary **pharaoh head**, which gives you some armor protection and armor toughness. Items[](https://docs.oraxen.com/usage/default-items#items) ----------------------------------------------------------- ### Cogs[](https://docs.oraxen.com/usage/default-items#cogs) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fcogs.808cd31f.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) A **cog** is an item that can be used to repair an item. You just have to take it in your hand and click on a repairable item using it inside your inventory. Mystical weapons[](https://docs.oraxen.com/usage/default-items#mystical-weapons) --------------------------------------------------------------------------------- ### Storm sword[](https://docs.oraxen.com/usage/default-items#storm-sword) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fstorm_sword.2132a343.png&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) A incredibly powerful **storm sword** which allows you to strike lightning. ### **Magical wand**[](https://docs.oraxen.com/usage/default-items#magical-wand) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fmagical_wand.30b66b56.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) This **magical wand** has a great animation and looks really cool, you can use it to make an Energy Blast to attack entities. ### Withooker[](https://docs.oraxen.com/usage/default-items#withooker) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fwithooker.2f0933a9.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) Like the magical wand, the **withooker** has a great animation and looks really cool but it currently doesn’t have any mechanic so it’s up to you to decide what you want to do with it. Other weapons[](https://docs.oraxen.com/usage/default-items#other-weapons) --------------------------------------------------------------------------- ### Dagger[](https://docs.oraxen.com/usage/default-items#dagger) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdagger.02056503.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) The **dagger** is a really nice weapon that can be used like a sword. By default you can use it faster than a sword. ### Energy crystal sword[](https://docs.oraxen.com/usage/default-items#energy-crystal-sword) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fenergy_crystal_sword.015a993c.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) The **energy crystal sword** is an incredibly looking sword, optimized for PvP and partially transparent. ### Blood sword[](https://docs.oraxen.com/usage/default-items#blood-sword) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fblood_sword.61ac85b8.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) You can use the **blood sword** to steal hearts from your enemies. ### Katana[](https://docs.oraxen.com/usage/default-items#katana) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fkatana.d89fba6f.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) The **katana** is another nice looking sword that you can customize. ### Octavia sword[](https://docs.oraxen.com/usage/default-items#octavia-sword) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Foctavia_sword.1c70619c.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) Like the dagger, the **Octavia sword** is small and nice looking. ### Obsidian sword[](https://docs.oraxen.com/usage/default-items#obsidian-sword) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fobsidian_sword.7f259d9b.jpg&w=3840&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) As powerful as an iron sword …but so much durable! The **obsidian sword** is really useful. ### Glass sword[](https://docs.oraxen.com/usage/default-items#glass-sword) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fglass_sword.b7a9fad6.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) The **glass sword** is a pretty powerful sword but with a low durability. Tools[](https://docs.oraxen.com/usage/default-items#tools) ----------------------------------------------------------- ### Axe of experience[](https://docs.oraxen.com/usage/default-items#axe-of-experience) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Faxe_of_experience.d5e97c6c.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) You can use the **axe of experience** to convert your experience into bottles of experience (you’ll have to lose a few percentage of experience though). ### Bedrock pickaxe[](https://docs.oraxen.com/usage/default-items#bedrock-pickaxe) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fbedrock_pickaxe.6d853ea0.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) You can use the **bedrock pickaxe** to break bedrock and go at the top of the nether for example. ### Iron serpe[](https://docs.oraxen.com/usage/default-items#iron-serpe) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Firon_serpe.2905bf6f.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) This tool allows you to harvest: it will automatically recolt and replant wheat! ### Obsidian pickaxe[](https://docs.oraxen.com/usage/default-items#obsidian-pickaxe) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fobsidian_pickaxe.a6fa7889.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) The **obsidian pickaxe** can be used to break a lot of blocks but is similar to an iron pickaxe. Hammers[](https://docs.oraxen.com/usage/default-items#hammers) --------------------------------------------------------------- Hammers are very special pickaxes capable of mining several blocks at the same time. Legend says that they were invented by Notch but he didn’t have time to add them so he only drew them into the anvil repair interface. ### **Emerald Hammer**[](https://docs.oraxen.com/usage/default-items#emerald-hammer) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Femerald_hammer.289f7847.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) The most basic hammer you can find is the **Emerald Hammer**, it mines a square of 3 blocks per 3 blocks, this is cool in order to start but definitively not the best you can get. ### Amethyst Hammer[](https://docs.oraxen.com/usage/default-items#amethyst-hammer) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Famethyst_hammer.aa11ea16.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) Unlike the Emerald Hammer, the **Amethyst Hammer** mines a square of 3 blocks per 3 blocks too but with a depth of two blocks. ### Onyx Hammer[](https://docs.oraxen.com/usage/default-items#onyx-hammer) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fonyx_hammer.355ec1e2.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) Take the Amethyst Hammer, improve it and you’ve got the **Onyx Hammer**. It can break more blocks than the Amethyst Hammer because it has a big durability. ### Orax Hammer[](https://docs.oraxen.com/usage/default-items#orax-hammer) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Forax_hammer.fd6c09e9.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) Compared to his brothers, the **Orax Hammer** is a god like hammer : it can mine a really big square with a depth of two blocks. ### Fire Hammer[](https://docs.oraxen.com/usage/default-items#fire-hammer) ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ffire_hammer.da0226de.jpg&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) The **Fire Hammer** mines like a basic hammer (3 blocks per 3 blocks, depth of 1) but it actually melts ores instantly! If you mine iron ore for example you’ll immediatly get rewarded with iron ingots …and it stacks with fortune! Last updated on January 17, 2026 [Commands](https://docs.oraxen.com/usage/commands "Commands") [Recipes](https://docs.oraxen.com/usage/recipes "Recipes") --- # Display Entity Furniture | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/furniture/display-entities#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Furniture](https://docs.oraxen.com/creating-content/furniture "Furniture") Display Entities Copy page Display Entity Furniture ======================== This page is only relevant to server-versions 1.19.4 and above. Display Entity Furniture will only show for players on 1.19.4 and above. ViaVersion will not fix this. Oraxen must also be version 1.154.0 or above Keep in mind that changing old furniture configs is not a good idea. Already placed furniture that use ItemFrames will not be updated automatically and might break if the config changes. If you want to change the config, you should remove the furniture and place it again. In the future, we might make a command, system or plugin-addon to migrate old furniture to DisplayEntities / new configs Display-Entities are a new entity type introduced in 1.19.4. It comes in a few different types: Item, Block and Interaction. Oraxen makes use of Item Display Entities and Interaction Entities for its furniture mechanic. With it, you can configure a bunch of stuff you previously could not. In addition to more options, it will also not cull, meaning it will not unrended at certain angles. This might lead to lower FPS for some players, but furniture will not vanish. Below is an example of such a config: `cart: displayname: "Cart" material: PAPER Mechanics: furniture: type: DISPLAY_ENTITY hitbox: width: 0.4 height: 0.3 display_entity_properties: display_transform: NONE brightness: block_light: 15 sky_light: 0 barrier: true Pack: generate_model: false model: default/cart` ### Furniture Type[](https://docs.oraxen.com/creating-content/furniture/display-entities#furniture-type) First off, `type` is a new property added in Oraxen 1.154.0. It allows you to specify if you want to use the old ItemFrame type, or new Display Entity type. If your server allows players on versions below 1.19.4, we suggest sticking with ItemFrame, as the other will not be visible. If this property is not specified, it defaults to `DISPLAY_ENTITY` on servers that support it (1.19.4+), otherwise `ITEM_FRAME`. The available options are: `ITEM_FRAME`, `GLOW_ITEM_FRAME` & `DISPLAY_ENTITY` ### Hitbox[](https://docs.oraxen.com/creating-content/furniture/display-entities#hitbox) Hitbox is also a new property as of Oraxen 1.154.0. This is regarding the new Interaction entity type. This entity is completely, has no collision and only functions as a hitbox. It can be used in addition to the old barrier mechanic. It has a `width` and a `height` property for defining the hitbox. ![](https://media.discordapp.net/attachments/743544047733440582/1085341928004005918/image.png?width=998&height=910) ### Display Entity Properties[](https://docs.oraxen.com/creating-content/furniture/display-entities#display-entity-properties) This section will detail the many options this new entity-type adds. Some are more useful than others, but I have added more or less all of them. Under `display_entity_properties` you can define these settings: `display_transform`, `tracking_rotation`, `brightness`, `view_range`, `shadow_radius`, `shadow_strength`, `scale` The `display_transform` dictates how the model will be displayed. By default it is set to `NONE`, which will show it as it looks when you open the model in BlockBench. As some other plugins might use ArmorStands and add the furniture to its head, you can set this option to `HEAD` for the same effect. There is also: `FIRSTPERSON_LEFTHAND`, `FIRSTPERSON_RIGHTHAND`, `FIXED`, `GROUND`, `GUI`, `THIRDPERSON_LEFTHAND`, `THIRDPERSON_RIGHTHAND`. All of these will be displayed ingame as shown in BlockBench’s Display Tab under the specified type. Look at [Furniture Position](https://docs.oraxen.com/creating-content/furniture/position) for an example on FIXED (ItemFrame Position) The `tracking_rotation`\-property defines whether you want the furniture to “track” the player. This is mainly for stuff like billboard and leaderboards you want the player to see, not normal furniture. Options are: `FIXED` - No rotation `VERTICAL` - Pivots around vertical axis `HORIZONTAL` - Pivots around horizontal axis `CENTER` - Pivots around center point The `brightness`\-property is a way to have your furniture emit light. It has a `block_light` and `sky_light` property for the different types of lighting Minecraft has. Config should look like this: `display_entity_properties: brightness: block_light: 15 sky_light: 0` The `scale`\-property is a way to scale the furniture. It has a `x`, `y` and `z` property for scaling on each axis. Config should look like this: `display_entity_properties: scale: x: 1 y: 1 z: 1` The `translation`\-property allows you to offset the furniture’s position relative to its placement block. This is useful for fine-tuning the exact position of your model without changing its placement coordinates. Values are specified in blocks (0.1 = 1/10th of a block). It has `x`, `y` and `z` properties for offsetting on each axis. Config should look like this: `display_entity_properties: translation: x: 0.0 y: 0.1 # Raise the furniture slightly off the ground z: 0.0` This is particularly useful when: * Centering models that are slightly off-center * Adjusting vertical placement without modifying the model in BlockBench * Fine-tuning furniture that sits on surfaces (tables, chairs, etc.) `view_range` controls from how far the furniture can be seen (in blocks). `shadow_radius` and `shadow_strength` control the shadow cast by the furniture. ### Animation Properties[](https://docs.oraxen.com/creating-content/furniture/display-entities#animation-properties) `interpolation_duration` sets how many ticks transformations (scale/rotation changes) take to complete. Useful for smooth animations. `interpolation_delay` sets a delay in ticks before transformations begin. `display_entity_properties: interpolation_duration: 10 # 10 ticks for smooth transitions interpolation_delay: 0` ### Display Dimensions[](https://docs.oraxen.com/creating-content/furniture/display-entities#display-dimensions) `displayWidth` and `displayHeight` control the bounding box dimensions used for culling (when the furniture is hidden if not in view). `display_entity_properties: displayWidth: 1.0 displayHeight: 1.0` Last updated on January 17, 2026 [Overview](https://docs.oraxen.com/creating-content/furniture "Overview") [Position & Rotation](https://docs.oraxen.com/creating-content/furniture/position "Position & Rotation") --- # FarmBlock Mechanic | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/blocks/farmblock#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Blocks](https://docs.oraxen.com/creating-content/blocks "Blocks") FarmBlock Copy page FarmBlock Mechanic ================== If you are looking to add customizable farming mechanics to your server, we heavily recommend looking into [CustomCrops](https://polymart.org/resource/customcrops.2625)  . It is a well-made plugin with full Oraxen compatibility. How does it work?[](https://docs.oraxen.com/creating-content/blocks/farmblock#how-does-it-work) ------------------------------------------------------------------------------------------------ This is a block system for custom plants and crops where you have your own watering system to make the plant grow. Global configuration[](https://docs.oraxen.com/creating-content/blocks/farmblock#global-configuration) ------------------------------------------------------------------------------------------------------- The global configuration has to be used to activate or deactivate this mechanism. `noteblock: tool_types: - WOODEN - STONE - IRON - GOLDEN - DIAMOND - NETHERITE farmblock_check_delay: 1000 # ticks between each check for dryout enabled: true harvesting: enabled: true watering: enabled: true` How to create a simple farmblock?[](https://docs.oraxen.com/creating-content/blocks/farmblock#how-to-create-a-simple-farmblock) -------------------------------------------------------------------------------------------------------------------------------- ### Oraxen item and Pack configuration[](https://docs.oraxen.com/creating-content/blocks/farmblock#oraxen-item-and-pack-configuration) In this case you cannot create blocks using this mechanics without having a pre-made model, and you have to create 2 models for each item, one with water and one without `epic_box_dry: displayname: "Epic Box" material: PAPER Pack: generate_model: false model: epic_box_dry Mechanics: noteblock: custom_variation: 49 model: epic_box_dry hardness: 5 farmblock: moistFarmBlockPath: epic_box_wet farmBlockDryOutTime: 30000 # in milliseconds (30000ms = 30s) epic_box_wet: displayname: "Epic Box Wet" excludeFromInventory: true # Makes inventory only contain base-block material: PAPER Pack: generate_model: false model: epic_box_wet Mechanics: noteblock: custom_variation: 48 hardness: 5 model: epic_box_wet farmblock: farmBlockPath: epic_box_dry farmBlockDryOutTime: 30000 # in milliseconds (30000ms = 30s)` In this example there are 2 blocks configured separately epic\_box\_dry is the Farmblock dry and epic\_box\_wet is the model with water. farmBlockPath is the Oraxen item to be transformed into if it has no water moistFarmBlockPath is the Oraxen item it will become if it has water. farmBlockDryOutTime the time in which the water will run out ### How do I water my blocks?[](https://docs.oraxen.com/creating-content/blocks/farmblock#how-do-i-water-my-blocks) Oraxen has a watering can system that allows with a custom item to water a Farmblock and this also requires 2 models, one with water and one without, this is an example. `epic_watering_vacuum: displayname: 'Epic Watering Vacuum' material: LEATHER_HORSE_ARMOR Mechanics: watering: filledCanItem: epic_watering_full #Item to replace when can is filled Pack: generate_model: false model: items/epic_watering_vacuum epic_watering_full: displayname: 'Epic Watering Full' material: LEATHER_HORSE_ARMOR Mechanics: watering: emptyCanItem: epic_watering_vacuum #Item to replace when can is empty Pack: generate_model: false model: custom/plants/epic_watering_full` ### Do you want to know how to make custom plants? [Click here](https://docs.oraxen.com/creating-content/furniture/farming) [](https://docs.oraxen.com/creating-content/blocks/farmblock#do-you-want-to-know-how-to-make-custom-plants-click-here) Last updated on January 3, 2026 [ChorusBlock](https://docs.oraxen.com/creating-content/blocks/chorusblock "ChorusBlock") [ShapedBlock](https://docs.oraxen.com/creating-content/blocks/shapedblock "ShapedBlock") --- # ShapedBlock | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/blocks/shapedblock#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Blocks](https://docs.oraxen.com/creating-content/blocks "Blocks") ShapedBlock Copy page ShapedBlock =========== The ShapedBlock mechanic allows you to create custom **stairs, slabs, doors, trapdoors, grates, and bulbs** using waxed copper blocks as the base material. Each block type supports up to **4 custom variations**. ![Custom stairs, door, trapdoor and leaves in-game](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fshaped_blocks.e2fff4fc.webp&w=3840&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) Not sure which block mechanic to use? See the [Blocks Overview](https://docs.oraxen.com/creating-content/blocks) for a comparison. How It Works[](https://docs.oraxen.com/creating-content/blocks/shapedblock#how-it-works) ----------------------------------------------------------------------------------------- ShapedBlock uses Minecraft’s waxed copper block variants (stairs, slabs, doors, trapdoors, grates) as the underlying material. Oraxen automatically: 1. Converts vanilla waxed copper blocks to non-waxed equivalents with an oxidation prevention marker 2. Reserves the waxed copper materials for custom blocks 3. Handles waxing/unwaxing with honeycomb and axes on vanilla copper 4. Converts waxed copper in world generation (Trial Chambers, etc.) This mechanic modifies how waxed copper behaves in your world. Vanilla waxed copper blocks will be converted to regular copper (with oxidation prevention) to reserve waxed variants for custom blocks. Block Types[](https://docs.oraxen.com/creating-content/blocks/shapedblock#block-types) --------------------------------------------------------------------------------------- | Type | Base Material | Variations | Features | | --- | --- | --- | --- | | `STAIR` | Waxed Copper Stairs | 4 | Directional placement, waterlogging | | `SLAB` | Waxed Copper Slab | 4 | Top/bottom/double placement, waterlogging | | `DOOR` | Waxed Copper Door | 4 | Two-block tall, openable, powered by redstone | | `TRAPDOOR` | Waxed Copper Trapdoor | 4 | Openable, powered by redstone, waterlogging | | `GRATE` | Waxed Copper Grate | 4 | Transparent (ideal for leaves), waterlogging | | `BULB` | Waxed Copper Bulb | 4 | Toggleable light source, redstone powered | Global Configuration[](https://docs.oraxen.com/creating-content/blocks/shapedblock#global-configuration) --------------------------------------------------------------------------------------------------------- In `mechanics.yml`, you can configure the ShapedBlock mechanic: `shaped_block: tool_types: - WOODEN - STONE - IRON - GOLDEN - DIAMOND - NETHERITE # Convert vanilla waxed copper to non-waxed with oxidation prevention convert_vanilla_waxed: true # Handle waxed copper in world generation (Trial Chambers, etc.) handle_world_generation: true enabled: true` If you disable this mechanic (`enabled: false`), vanilla waxed copper behavior will be fully restored. Players will be able to use waxed copper blocks normally without any conversion. Creating Shaped Blocks[](https://docs.oraxen.com/creating-content/blocks/shapedblock#creating-shaped-blocks) ------------------------------------------------------------------------------------------------------------- ### Custom Stairs[](https://docs.oraxen.com/creating-content/blocks/shapedblock#custom-stairs) `custom_oak_stairs: displayname: "<#8B4513>Custom Oak Stairs" material: PAPER Pack: generate_model: true parent_model: block/stairs textures: - custom_oak_planks Mechanics: shaped_block: type: STAIR custom_variation: 1 # 1-4 available hardness: 2 block_sounds: break_sound: block.wood.break place_sound: block.wood.place drop: silktouch: false loots: - oraxen_item: custom_oak_stairs probability: 1.0` ### Custom Slabs[](https://docs.oraxen.com/creating-content/blocks/shapedblock#custom-slabs) Slabs support top, bottom, and double-slab placement. Double slabs automatically drop 2 items when broken. `custom_stone_slab: displayname: "<#808080>Custom Stone Slab" material: PAPER Pack: generate_model: true parent_model: block/slab textures: - block/stone Mechanics: shaped_block: type: SLAB custom_variation: 1 hardness: 4 block_sounds: break_sound: block.stone.break place_sound: block.stone.place drop: silktouch: false loots: - oraxen_item: custom_stone_slab probability: 1.0` ### Custom Doors[](https://docs.oraxen.com/creating-content/blocks/shapedblock#custom-doors) Doors require special handling: use `item/generated` in the Pack section for the hand display icon, and specify block textures in the mechanic section for the placed door appearance. `custom_oak_door: displayname: "<#8B4513>Custom Oak Door" material: PAPER Pack: generate_model: true parent_model: item/generated textures: - custom_oak_door_icon # Flat icon for hand/inventory display Mechanics: shaped_block: type: DOOR custom_variation: 1 hardness: 2 # Block textures for the placed door (bottom and top halves) textures: bottom: block/oak_door_bottom top: block/oak_door_top block_sounds: break_sound: block.wood.break place_sound: block.wood.place drop: silktouch: false loots: - oraxen_item: custom_oak_door probability: 1.0` Doors are two blocks tall and automatically handle the top/bottom block placement. Breaking either half drops the door item. ### Custom Trapdoors[](https://docs.oraxen.com/creating-content/blocks/shapedblock#custom-trapdoors) `custom_oak_trapdoor: displayname: "<#8B4513>Custom Oak Trapdoor" material: PAPER Pack: generate_model: true parent_model: block/template_trapdoor_bottom textures: - block/oak_trapdoor Mechanics: shaped_block: type: TRAPDOOR custom_variation: 1 hardness: 2 block_sounds: break_sound: block.wood.break place_sound: block.wood.place drop: silktouch: false loots: - oraxen_item: custom_oak_trapdoor probability: 1.0` ### Custom Grates / Leaves[](https://docs.oraxen.com/creating-content/blocks/shapedblock#custom-grates--leaves) Grates are transparent blocks that use cutout rendering, making them ideal for custom leaves or other see-through blocks. `# Custom leaves using GRATE type for transparency crystalmush_leaves: displayname: "Crystal Mushroom Leaves" material: PAPER Pack: generate_model: true parent_model: block/leaves textures: - default/crystalmush/crystalmush_leaves_anim Mechanics: shaped_block: type: GRATE custom_variation: 2 light: 12 # Emits light hardness: 0.2 block_sounds: break_sound: block.grass.break place_sound: block.grass.place drop: silktouch: true # Only drops with silk touch loots: - oraxen_item: crystalmush_leaves probability: 1.0` Use `block/leaves` as the parent model for proper transparency rendering. The GRATE type renders with cutout rules, allowing texture alpha to show through like real leaves. ### Custom Bulbs[](https://docs.oraxen.com/creating-content/blocks/shapedblock#custom-bulbs) Bulbs are toggleable light sources that can be powered by redstone. `custom_light_bulb: displayname: "<#FFD700>Custom Light Bulb" material: PAPER Pack: generate_model: true parent_model: block/cube_all textures: - custom_bulb_texture Mechanics: shaped_block: type: BULB custom_variation: 1 hardness: 3 block_sounds: break_sound: block.copper.break place_sound: block.copper.place drop: silktouch: false loots: - oraxen_item: custom_light_bulb probability: 1.0` Configuration Options[](https://docs.oraxen.com/creating-content/blocks/shapedblock#configuration-options) ----------------------------------------------------------------------------------------------------------- ### Common Properties[](https://docs.oraxen.com/creating-content/blocks/shapedblock#common-properties) | Property | Description | Default | | --- | --- | --- | | `type` | Block type: `STAIR`, `SLAB`, `DOOR`, `TRAPDOOR`, `GRATE`, `BULB` | Required | | `custom_variation` | Variation number (1-4) | Required | | `hardness` | Mining hardness | `3` | | `light` | Light level emitted (0-15) | `0` | ### Block Sounds[](https://docs.oraxen.com/creating-content/blocks/shapedblock#block-sounds) `block_sounds: break_sound: block.wood.break place_sound: block.wood.place hit_sound: block.wood.hit step_sound: block.wood.step fall_sound: block.wood.fall volume: 1.0 pitch: 1.0` ### Drop Configuration[](https://docs.oraxen.com/creating-content/blocks/shapedblock#drop-configuration) `drop: silktouch: false # Require silk touch for drops fortune: false # Enable fortune enchantment bonus minimal_type: WOODEN # Minimum tool tier required best_tools: - PICKAXE loots: - oraxen_item: my_block probability: 1.0` Block Behaviors[](https://docs.oraxen.com/creating-content/blocks/shapedblock#block-behaviors) ----------------------------------------------------------------------------------------------- ### Stairs[](https://docs.oraxen.com/creating-content/blocks/shapedblock#stairs) * Automatically orient based on player facing direction * Support waterlogging * Place in correct half (top/bottom) based on click position ### Slabs[](https://docs.oraxen.com/creating-content/blocks/shapedblock#slabs) * Place as top, bottom, or double slab based on click position * Double slabs drop 2 items when broken * Support waterlogging ### Doors[](https://docs.oraxen.com/creating-content/blocks/shapedblock#doors) * Two blocks tall, automatically place both halves * Open/close on right-click * Powered by redstone * Breaking either half removes the entire door ### Trapdoors[](https://docs.oraxen.com/creating-content/blocks/shapedblock#trapdoors) * Open/close on right-click * Powered by redstone * Support waterlogging * Place on top or bottom of block based on click position ### Grates[](https://docs.oraxen.com/creating-content/blocks/shapedblock#grates) * Transparent (see-through) with cutout rendering * Support waterlogging * Light passes through * Ideal for custom leaves or glass-like blocks ### Bulbs[](https://docs.oraxen.com/creating-content/blocks/shapedblock#bulbs) * Toggleable light source * Powered by redstone * Click to toggle on/off state Parent Models Reference[](https://docs.oraxen.com/creating-content/blocks/shapedblock#parent-models-reference) --------------------------------------------------------------------------------------------------------------- | Block Type | Recommended Parent Model | | --- | --- | | Stairs | `block/stairs` | | Slabs | `block/slab` | | Doors | `item/generated` (for item), door textures in mechanic | | Trapdoors | `block/template_trapdoor_bottom` | | Grates | `block/cube_all` or `block/leaves` (for foliage) | | Bulbs | `block/cube_all` | Limitations[](https://docs.oraxen.com/creating-content/blocks/shapedblock#limitations) --------------------------------------------------------------------------------------- * Maximum of **4 custom variations per block type** (stairs, slabs, etc.) * Waxed copper blocks in your world will be converted to regular copper * Players cannot use waxed copper materials for vanilla purposes when this mechanic is enabled Last updated on January 3, 2026 [FarmBlock](https://docs.oraxen.com/creating-content/blocks/farmblock "FarmBlock") [Overview](https://docs.oraxen.com/creating-content/furniture "Overview") --- # Plant Evolution / Farming Mechanic | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/furniture/farming#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Furniture](https://docs.oraxen.com/creating-content/furniture "Furniture") Farming & Evolution Copy page Plant Evolution / Farming Mechanic ================================== Oraxen has a system for creating plants with various stages of growth. There are two ways to configure this: 1. **Inline Stages (Recommended)** - Define all stages in a single item 2. **Legacy Multi-Item** - Separate items for each stage **Inline Stages** is the recommended approach as it: * Reduces item count (1 item instead of 5+) * Improves performance (model swap vs entity recreation) * Keeps all configuration in one place Inline Stages (Recommended)[](https://docs.oraxen.com/creating-content/furniture/farming#inline-stages-recommended) -------------------------------------------------------------------------------------------------------------------- Define all growth stages within a single item using `stages` array and `Pack.models`: `rose_seed: displayname: "Rose Seed" material: PAPER Pack: generate_model: true parent_model: "item/generated" textures: - custom/plants/rose_seed # Define all growth stage models here models: stage0: custom/plants/rose_stage_0 stage1: custom/plants/rose_stage_1 stage2: custom/plants/rose_stage_2 stage3: custom/plants/rose_stage_3 Mechanics: furniture: barrier: false farmblock_required: true initial_stage: 0 # Start at stage0 when placed stages: - model: stage0 # References Pack.models key evolution: delay: 10000 probability: 0.5 light_boost: true bone_meal: chance: 50 drop: silktouch: true loots: - { oraxen_item: rose_seed, probability: 1.0 } - model: stage1 evolution: delay: 10000 probability: 0.5 light_boost: true bone_meal: chance: 50 drop: silktouch: true loots: - { oraxen_item: rose_seed, probability: 1.0 } - model: stage2 evolution: delay: 10000 probability: 0.5 light_boost: true bone_meal: chance: 50 drop: silktouch: true loots: - { oraxen_item: rose_seed, probability: 1.0 } - model: stage3 # Final stage - no evolution section drop: silktouch: true loots: - { oraxen_item: rose_seed, max_amount: 2, probability: 0.75 } - { oraxen_item: rose_plant, max_amount: 5, probability: 0.55 }` ### Stage Configuration Options[](https://docs.oraxen.com/creating-content/furniture/farming#stage-configuration-options) Each stage in the `stages` array can have: | Option | Description | | --- | --- | | `model` | **Required.** Reference to a key in `Pack.models` | | `light` | Optional light level for this stage (-1 = inherit from mechanic) | | `evolution` | Evolution settings. Omit for final stage | | `drop` | Stage-specific drops. Inherits from mechanic drop if omitted | ### Evolution Options[](https://docs.oraxen.com/creating-content/furniture/farming#evolution-options) `evolution: delay: 10000 # Ticks between evolution checks probability: 0.5 # Chance to evolve (0.0 to 1.0) light_boost: true # Enable light boost (shorthand) # OR detailed light boost: light_boost: minimum_light_level: 9 # Min light level for boost boost_tick: 500 # Extra ticks per check when lit rain_boost: true # Enable rain boost (shorthand) # OR detailed rain boost: rain_boost: boost_tick: 500 # Extra ticks per check when raining bone_meal: true # Enable bone meal (50% default) # OR detailed bone meal: bone_meal: chance: 50 # Success percentage (0-100)` * * * Legacy Multi-Item Pattern[](https://docs.oraxen.com/creating-content/furniture/farming#legacy-multi-item-pattern) ------------------------------------------------------------------------------------------------------------------ This pattern still works but is **deprecated**. You’ll see console warnings suggesting migration to inline stages. The legacy approach requires creating separate items for each growth stage: Seed ItemStage 1Stage 2Final Stage ### Seed Item `rose_seed: displayname: "Rose Seed" material: PAPER Mechanics: furniture: item: rose_plant_stage1 barrier: false farmblock_required: true evolution: delay: 10000 probability: 0.5 light_boost: true next_stage: rose_plant_stage1 # References another item drop: silktouch: true loots: - { oraxen_item: rose_seed, probability: 1.0 } Pack: generate_model: false model: custom/plants/rose_stage_1` ### Stage 1 `rose_plant_stage1: material: PAPER excludeFromInventory: true # Hide from inventory Mechanics: furniture: barrier: false farmblock_required: true evolution: delay: 10000 probability: 0.5 light_boost: true next_stage: rose_plant_stage2 drop: silktouch: true loots: - { oraxen_item: rose_seed, probability: 1.0 } Pack: generate_model: false model: custom/plants/rose_stage_1` ### Stage 2 `rose_plant_stage2: material: PAPER excludeFromInventory: true Mechanics: furniture: barrier: false farmblock_required: true evolution: delay: 10000 probability: 0.5 light_boost: true next_stage: rose_plant_stage3 drop: silktouch: true loots: - { oraxen_item: rose_seed, probability: 1.0 } Pack: generate_model: false model: custom/plants/rose_stage_2` ### Final Stage `rose_plant_stage3: material: PAPER excludeFromInventory: true Mechanics: furniture: barrier: false farmblock_required: true evolution: delay: 100000 probability: 0.25 light_boost: true # No next_stage = final stage drop: silktouch: true loots: - { oraxen_item: rose_seed, max_amount: 2, probability: 0.75 } - { oraxen_item: rose_plant, max_amount: 5, probability: 0.55 } Pack: generate_model: false model: custom/plants/rose_stage_3` * * * Configuration Reference[](https://docs.oraxen.com/creating-content/furniture/farming#configuration-reference) -------------------------------------------------------------------------------------------------------------- ### Placement Requirements[](https://docs.oraxen.com/creating-content/furniture/farming#placement-requirements) | Option | Description | | --- | --- | | `farmland_required` | Requires vanilla farmland block below | | `farmblock_required` | Requires custom Oraxen farm block below. See [farmblock mechanic](https://docs.oraxen.com/creating-content/blocks/noteblock#farmblock) | ### Evolution Options (Legacy)[](https://docs.oraxen.com/creating-content/furniture/farming#evolution-options-legacy) | Option | Description | | --- | --- | | `delay` | Time in ticks before evolution check | | `probability` | Chance to evolve when delay is reached (0.0-1.0) | | `light_boost` | Grow faster when light level is sufficient | | `rain_boost` | Grow faster when raining | | `bone_meal` | Allow bone meal to advance growth | | `next_stage` | The Oraxen item ID to evolve into (legacy only) | * * * Migration Guide[](https://docs.oraxen.com/creating-content/furniture/farming#migration-guide) ---------------------------------------------------------------------------------------------- To migrate from legacy multi-item to inline stages: 1. **Move models to `Pack.models`**: `Pack: models: stage0: path/to/stage0 stage1: path/to/stage1 # ...` 2. **Add `stages` array** with each stage’s config 3. **Delete the old stage items** (`*_stage1`, `*_stage2`, etc.) 4. **Remove `next_stage`** - stages advance automatically by array index See the [full migration guide](https://github.com/oraxen/oraxen/blob/master/MIGRATION_PACK_MODELS.md)   for detailed examples. Last updated on January 17, 2026 [Position & Rotation](https://docs.oraxen.com/creating-content/furniture/position "Position & Rotation") [Overview](https://docs.oraxen.com/creating-content/armors "Overview") --- # Custom Armors | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/armors#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") ArmorsOverview Copy page Custom Armors ============= Oraxen lets you create custom armor sets with unique textures when equipped. There are three methods available, each designed for different Minecraft versions. Quick Comparison[](https://docs.oraxen.com/creating-content/armors#quick-comparison) ------------------------------------------------------------------------------------- | Method | MC Version | Base Material | Shader Compatible | Recommended | | --- | --- | --- | --- | --- | | [Components](https://docs.oraxen.com/creating-content/armors/components) | 1.21.2+ | Any | ✅ Yes | ✅ Best choice | | [Trims](https://docs.oraxen.com/creating-content/armors/trims) | 1.20-1.21.1 | Chainmail | ✅ Yes | For 1.20-1.21.1 | | [Shaders](https://docs.oraxen.com/creating-content/armors/shaders) | 1.18-1.19.4 | Leather | ❌ Needs CIT | Legacy servers | Choosing the Right Method[](https://docs.oraxen.com/creating-content/armors#choosing-the-right-method) ------------------------------------------------------------------------------------------------------- ### Use Components for:[](https://docs.oraxen.com/creating-content/armors#use-components-for) * **All 1.21.2+ servers** - This is the optimal choice * **Any armor material** - Not restricted to leather or chainmail * **Full shader compatibility** - Works with Optifine, Iris, etc. ### Use Trims for:[](https://docs.oraxen.com/creating-content/armors#use-trims-for) * **1.20-1.21.1 servers** that don’t support Components * **Shader compatibility** without needing extra mods * **Non-leather materials** - Uses chainmail by default ### Use Shaders for:[](https://docs.oraxen.com/creating-content/armors#use-shaders-for) * **Pre-1.20 servers** or servers allowing older clients * **Legacy configurations** that already use this method **Shader Method Limitations** The shader method breaks with Optifine/Iris shaders. Oraxen generates CIT textures to fix this for Optifine, but Iris users need [CIT Resewn](https://modrinth.com/mod/cit-resewn)   installed. Feature Comparison[](https://docs.oraxen.com/creating-content/armors#feature-comparison) ----------------------------------------------------------------------------------------- | Feature | Components | Trims | Shaders | | --- | --- | --- | --- | | Any base material | ✅ | ❌ Chainmail | ❌ Leather | | Works with shaders | ✅ | ✅ | ⚠️ Needs CIT | | Animated textures | ✅ | ✅ | ✅ | | Trim patterns | ✅ | ✅ | ❌ | | Dyeable | ✅ | ❌ | ✅ | | Performance | ✅ Best | ✅ Good | ⚠️ Okay | Basic Configuration[](https://docs.oraxen.com/creating-content/armors#basic-configuration) ------------------------------------------------------------------------------------------- All armor methods share a similar base configuration: `my_helmet: displayname: "My Helmet" material: DIAMOND_HELMET # Or LEATHER_HELMET for shaders Pack: generate_model: true parent_model: "item/generated" textures: - my_helmet.png # Method-specific configuration below` Next Steps[](https://docs.oraxen.com/creating-content/armors#next-steps) ------------------------------------------------------------------------- * [Components (1.21.2+)](https://docs.oraxen.com/creating-content/armors/components) - Recommended for modern servers * [Trims (1.20-1.21.1)](https://docs.oraxen.com/creating-content/armors/trims) - For 1.20.x servers * [Shaders (1.18-1.19.4)](https://docs.oraxen.com/creating-content/armors/shaders) - For legacy servers Last updated on January 3, 2026 [Farming & Evolution](https://docs.oraxen.com/creating-content/furniture/farming "Farming & Evolution") [Components (1.21.2+)](https://docs.oraxen.com/creating-content/armors/components "Components (1.21.2+)") --- # Component Based Armors (1.21.2+) | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/armors/components#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Armors](https://docs.oraxen.com/creating-content/armors "Armors") Components (1.21.2+) Copy page Component Based Armors (1.21.2+) ================================ If using COMPONENTS as your custom-armor type, you are not limited in any way, unlike TRIMS & SHADER. Unlike SHADER this method does not break with shader-mods and is not restricted to LEATHER\_ARMOR items. It also has the benefit of not needing to be based on an armor-item at all, use PAPER if you want to. Every downside there has been to earlier methods is now gone, no restrictions. How to configure your armor?[](https://docs.oraxen.com/creating-content/armors/components#how-to-configure-your-armor) ----------------------------------------------------------------------------------------------------------------------- Make sure that the itemID of your OraxenItem follows the pattern `armorname_armortype`. For the rest of the above set it would be `ruby_chestplate`, `ruby_leggings` and `ruby_boots`. Make sure your armor-layer files follow the format of **armorname**\_armor\_layer\_1/2.png. In the example below, we would need a **ruby**\_armor\_layer\_1.png & **ruby**\_armor\_layer\_2.png Simply set the material you want, no need to specify the texture-icon twice: `ruby_helmet: displayname: "Ruby Helmet" material: PAPER Pack: generate_model: true parent_model: "item/generated" textures: - default/armors/ruby_helmet` An Equippable-Component is also necessary for the armor to display correctly. Oraxen will automatically assign it if it has not been manually specified. You can optionally manually assign the component if you want to. The value should be `oraxen:armorname`, so in our example; `ruby_helmet: Components: equippable: slot: HEAD model: oraxen:ruby` Last updated on January 3, 2026 [Overview](https://docs.oraxen.com/creating-content/armors "Overview") [Trims (1.20-1.21.1)](https://docs.oraxen.com/creating-content/armors/trims "Trims (1.20-1.21.1)") --- # Trims Based Armors (1.20-1.21.1) | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/armors/trims#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Armors](https://docs.oraxen.com/creating-content/armors "Armors") Trims (1.20-1.21.1) Copy page Trims Based Armors (1.20-1.21.1) ================================ If using trims as your custom-armor type, most things is handled automatically for you. Unlike with Core Shader method, trims aren’t limited to just using LEATHER-materials. By default, Oraxen is set to use CHAINMAIL, but this can be changed in `settings.yml`. Oraxen then generates a datapack based on your configured custom armors. Due to it requiring a datapack, the server needs to do a full restart any time you add/remove an armor-set. After changing `CustomArmor.armor_type` to `TRIMS` you need to: 1. Start your server to let datapack be generated 2. Stop your server 3. Start it again to enable the previously generated datapack ### How to configure your armor?[](https://docs.oraxen.com/creating-content/armors/trims#how-to-configure-your-armor) Make sure that the itemID of your OraxenItem follows the pattern `armorname_armortype`. For the rest of the above set it would be `ruby_chestplate`, `ruby_leggings` and `ruby_boots`. Make sure your armor-layer files follow the format of **armorname**\_armor\_layer\_1/2.png. In the example below, we would need a **ruby**\_armor\_layer\_1.png & **ruby**\_armor\_layer\_2.png Simply set the material and specify the texture-icon twice `ruby_helmet: displayname: "Ruby Helmet" material: CHAINMAIL_HELMET Pack: generate_model: true parent_model: "item/generated" textures: - default/armors/ruby_helmet - default/armors/ruby_helmet` A trim-pattern is also necessary for the armor to display correctly. Oraxen will automatically assign it if it has not been manually specified. You can optionally manually assign the `trim_pattern` if you want to. The value should be `oraxen:armorname`, so in our example; `ruby_helmet: trim_pattern: oraxen:ruby` Last updated on January 17, 2026 [Components (1.21.2+)](https://docs.oraxen.com/creating-content/armors/components "Components (1.21.2+)") [Shaders (1.18-1.19.4)](https://docs.oraxen.com/creating-content/armors/shaders "Shaders (1.18-1.19.4)") --- # World Generators | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/world-generators#nextra-skip-nav) [Compatibility](https://docs.oraxen.com/compatibility/packlayer "Compatibility") World GeneratorsWorld Generators Copy page World Generators ================ Oraxen doesn’t natively support ore generation. Instead, you can use world generators to spawn custom ores and blocks in your world. Recommended: Iris World Generator[](https://docs.oraxen.com/compatibility/world-generators#recommended-iris-world-generator) ----------------------------------------------------------------------------------------------------------------------------- [Iris World Generator](https://docs.oraxen.com/compatibility/world-generators/iris-world-generator) features **first-class Oraxen integration**. Oraxen automatically registers as an external data provider with Iris, allowing you to reference custom blocks using the `oraxen:block_id` syntax directly in your Iris configurations - no additional setup required. Alternative: Custom Ore Generator[](https://docs.oraxen.com/compatibility/world-generators#alternative-custom-ore-generator) ----------------------------------------------------------------------------------------------------------------------------- [Custom Ore Generator](https://docs.oraxen.com/compatibility/world-generators/custom-ore-generator) is a free alternative for adding custom ores to your world. For discontinued world generators (EpicWorldGenerator, RealisticWorldGenerator), see the [Archives](https://docs.oraxen.com/compatibility/archives) section. Find your ores’ custom block data[](https://docs.oraxen.com/compatibility/world-generators#find-your-ores-custom-block-data) ----------------------------------------------------------------------------------------------------------------------------- For most custom world generators you need to find your custom block data. This can be achieved using any minecraft version on a server running Oraxen. Just place your block (you can get it from the oraxen inventory of give it to yourself through a command) and press F3 while looking at the block you want to add. ### For note\_block based blocks (default)[](https://docs.oraxen.com/compatibility/world-generators#for-note_block-based-blocks-default) ![A noteblock based custom block](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fworld-generators-noteblock-based.00083c0d.png&w=3840&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) ### For mushroom based blocks[](https://docs.oraxen.com/compatibility/world-generators#for-mushroom-based-blocks) ![A mushroom based custom block](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Famethyst.da29634b.png&w=3840&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) Last updated on January 17, 2026 [Skript](https://docs.oraxen.com/compatibility/skript "Skript") [Iris World Generator](https://docs.oraxen.com/compatibility/world-generators/iris-world-generator "Iris World Generator") --- # Custom GUI | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/glyphs-hud/custom-gui#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Glyphs & HUD](https://docs.oraxen.com/creating-content/glyphs-hud "Glyphs & HUD") Custom GUI Copy page Custom GUI ========== With Oraxen glyph you can create custom textured GUI’s. Here is an example: `customshop: texture: custom/default/custom/gui_tienda.png ascent: 13 height: 256` The textures cannot be higher resolution than 256x256 and name of the texture must be all lowercase without spaces, as with all Resourcepack files. To adjust the horizontal position of your texture/glyph in the inventory, use the shift-tag. `` for moving 8 pixels back, and `` for moving 211 pixels forward. ![](https://images-ext-2.discordapp.net/external/lXJpPHHy3JFqjn9qU_JpNHjaP2edFMFvnQjuYvTghYE/https/mcmodels.net/wp-content/uploads/2022/01/image-1.png) ### How do I get the unicode for the glyph?[](https://docs.oraxen.com/creating-content/glyphs-hud/custom-gui#how-do-i-get-the-unicode-for-the-glyph) This really is not necessary as Oraxen will handle the `` tag in any inventory / title. So to add this glyph in any other plugin, just set the title to be ``. If you still want the raw unicode, you can find it in your glyphs config. ### How do I create an invisible item?[](https://docs.oraxen.com/creating-content/glyphs-hud/custom-gui#how-do-i-create-an-invisible-item) Invisible elements are ideal for making clickable buttons. To create invisible elements, you will need to make an element with a transparent texture. An example here `invisible_item: displayname: "" material: PAPER Pack: generate_model: true parent_model: "item/generated" textures: - required/particle` Last updated on January 17, 2026 [Glyphs](https://docs.oraxen.com/creating-content/glyphs-hud "Glyphs") [Custom HUD](https://docs.oraxen.com/creating-content/glyphs-hud/custom-hud "Custom HUD") --- # Glyphs & HUD Elements | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/glyphs-hud#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") Glyphs & HUDGlyphs Copy page Glyphs & HUD Elements ===================== Oraxen lets you create custom glyphs—textured unicode symbols that can appear in chat, item names, lore, scoreboards, and more. What You Can Create[](https://docs.oraxen.com/creating-content/glyphs-hud#what-you-can-create) ----------------------------------------------------------------------------------------------- | Type | Use Case | Example | | --- | --- | --- | | Emojis | Chat expressions | ❤️ :heart: in chat | | Icons | Item lore, ranks | Rank badges, rarity icons | | HUD Elements | Custom UI | Health bars, minimaps | | GUI Textures | Custom menus | Inventory backgrounds | | Large Images | Banners, logos | Server branding | Glyph Features[](https://docs.oraxen.com/creating-content/glyphs-hud#glyph-features) ------------------------------------------------------------------------------------- | Feature | Description | | --- | --- | | [Basic Glyphs](https://docs.oraxen.com/creating-content/glyphs-hud#how-to-add-a-glyph) | Simple emoji-style icons | | [Multi-Bitmap](https://docs.oraxen.com/creating-content/glyphs-hud#multi-bitmap-glyphs) | Multiple glyphs from one image | | [Grid Glyphs](https://docs.oraxen.com/creating-content/glyphs-hud#grid-based-glyphs) | Large images spanning multiple characters | | [Animated Glyphs](https://docs.oraxen.com/creating-content/glyphs-hud#animated-glyphs) | Moving/animated icons | | [Reference Glyphs](https://docs.oraxen.com/creating-content/glyphs-hud#reference-glyphs) | Aliases to existing glyphs | | [Shifts](https://docs.oraxen.com/creating-content/glyphs-hud#shifts-no-more-shiftsyml) | Pixel-perfect positioning | Glyphs work anywhere text is displayed: chat, item names, lore, scoreboards, boss bars, action bars, and more. * * * What is a glyph?[](https://docs.oraxen.com/creating-content/glyphs-hud#what-is-a-glyph) ---------------------------------------------------------------------------------------- A glyph is a textured unicode symbol. It can be used in any texts (chat, item name, lore and more). They can be used to do very, very powerful things (custom inventories, extra bars) but their simplest use is to be emoji. How to add a Glyph?[](https://docs.oraxen.com/creating-content/glyphs-hud#how-to-add-a-glyph) ---------------------------------------------------------------------------------------------- You first need to create a png texture. For example the heart.png file contained in `default/chat`. ![heart.png](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fheart%20(1).99e9fb96.png&w=32&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) You can then add your section to any yaml file from the glyphs directory. The code must be different for every glyph. This is the number that corresponds to the number of the unicode character that will be used. The texture is the path and name of the texture file. Height allows you to set the displayed character scale while ascent defines the vertical shift of the displayed result. `heart: texture: default/chat/heart ascent: 8 height: 8` My glyphs don’t work?[](https://docs.oraxen.com/creating-content/glyphs-hud#my-glyphs-dont-work) ------------------------------------------------------------------------------------------------- This is likely due to misconfiguration of the glyphs’ config. Please check your console for any errors, as it should tell you exactly which glyph is misconfigured and how it is. ![](https://user-images.githubusercontent.com/62521371/185404681-e0c1a881-e30b-446a-9f33-20dd88bae27c.png) Multi-Bitmap glyphs[](https://docs.oraxen.com/creating-content/glyphs-hud#multi-bitmap-glyphs) ----------------------------------------------------------------------------------------------- If you have a png consisting of several emotes, you can make it a multi-bitmap. This means you can, tie several glyphs to one image. This step requires some extra configuration to work however. In fonts.yml there is a section for `bitmaps`. Here you need to specify an `id`, which you will use in your glyph-configs. You also need to specify the path to the texture, as well as how many rows and columns the bitmap has. Below is an example of an entry in `fonts.yml`: `bitmaps: example_bitmap: texture: example/example_bitmap rows: 4 columns: 9 ascent: 8 height: 8` ![](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fexample_bitmap.44d5e59d.png&w=640&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) As you can see, the image shown above has 4 rows and 9 columns. The ascent and height property will be the one used for all glyphs tied to this bitmap. Now that you have your bitmap configured, you can link a glyphs to it. In your glyph config, you need to specify the bitmap id, as well as the row and column of the glyph you want to use. Below is an example of a glyph config using the bitmap above. `example_glyph: texture: default/chat/example_glyph bitmap: id: example_bitmap row: 1 column: 1 #ascent: 8 # Not needed as bitmap specifies it #height: 8 # Not needed as bitmap specifies it` This will link the glyph to the first emoji on the first row in the image above. Emoji List[](https://docs.oraxen.com/creating-content/glyphs-hud#emoji-list) ----------------------------------------------------------------------------- To make a glyph appear under `/oraxen emojis` you need to specify that it is one, like below. If not specified, this will default to `false` `heart: texture: default/chat/heart is_emoji: true` It will also, by default, only show emojis the player has the permission for. In `settings.yml` you can toggle the `only_show_emojis_with_permission` setting. This will show all emojis to every player, and adds a hover-message indicating if they have permission or not. ![img](https://cdn.discordapp.com/attachments/758785982005903431/1002564595099111474/unknown.png) How to use it in the chat?[](https://docs.oraxen.com/creating-content/glyphs-hud#how-to-use-it-in-the-chat) ------------------------------------------------------------------------------------------------------------ You need to add a chat subsection to your glyph section: `chat: placeholders: - "<3" permission: "oraxen.emoji.heart"` The placeholders can be used in chat by players with the required permission (if permission is specified, it is not mandatory). How to make glyphs tabcomplete?[](https://docs.oraxen.com/creating-content/glyphs-hud#how-to-make-glyphs-tabcomplete) ---------------------------------------------------------------------------------------------------------------------- Simply set `tabcomplete: true` in the chat-section. If not specified, this will default to `false` Tabcompletion is currently only available for servers on 1.19.3 and above. `chat: tabcomplete: true placeholders: - "<3" permission: "oraxen.emoji.heart"` Grid-Based Glyphs[](https://docs.oraxen.com/creating-content/glyphs-hud#grid-based-glyphs) ------------------------------------------------------------------------------------------- Grid-based glyphs allow you to use a single large texture that spans multiple unicode characters, perfect for large images, detailed icons, or sprite sheets. If you have a texture larger than 256x256 pixels, or want to display a large image in chat/lore, you can use the `grid` configuration to split it across multiple characters. `large_banner: texture: custom/large_banner ascent: 8 height: 128 grid: rows: 2 # Image spans 2 rows columns: 3 # Image spans 3 columns` The plugin will automatically allocate the required unicode characters (rows × columns) for the glyph. In the example above, 6 characters would be allocated to display the full image. When using a grid glyph in MiniMessage tags, you can select specific portions: * `` - Displays all characters with newlines between rows * `` - Displays only the 1st character * `` - Displays characters 1 through 4 Appearance Configuration[](https://docs.oraxen.com/creating-content/glyphs-hud#appearance-configuration) --------------------------------------------------------------------------------------------------------- Glyphs support an `appearance` section for advanced styling options: `custom_icon: texture: icons/custom ascent: 8 height: 8 appearance: font: "minecraft:default" # Custom font (default: minecraft:default) shadow_color: "#80000000" # Shadow color in ARGB hex format (1.21.4+)` ### Shadow Colors (1.21.4+)[](https://docs.oraxen.com/creating-content/glyphs-hud#shadow-colors-1214) On Minecraft 1.21.4 and above, you can customize the text shadow color for glyphs. The shadow color uses ARGB hex format: * `#AARRGGBB` - Full format with alpha, red, green, blue * `#RRGGBB` - RGB format (assumes FF alpha) * `#RGB` - Short format (expands to #FFRRGGBB) Example: `#80000000` creates a semi-transparent black shadow. If a glyph has `shadow_color` configured, the shadow is **automatically applied** when using the glyph tag - no extra flags needed. You only need the `:s:#color` syntax to override with a different color. Glyph Tag Options[](https://docs.oraxen.com/creating-content/glyphs-hud#glyph-tag-options) ------------------------------------------------------------------------------------------- When using glyphs in MiniMessage format, you can add modifiers: ` Basic usage (auto-applies configured shadow_color) Shorthand syntax Colorable - inherits surrounding text color Same as above (full name) Override shadow with custom color (red) Same as above (full name) Select specific character index (1-based) Select range of characters` Multiple options can be combined: ` Colorable with custom semi-transparent red shadow` ### Colorable Glyphs[](https://docs.oraxen.com/creating-content/glyphs-hud#colorable-glyphs) By default, glyphs render in white to display their original texture colors. Using the `:c` or `:colorable` modifier allows the glyph to inherit color from surrounding text: `I Oraxen // Heart will be red` Shifts (no more shifts.yml)[](https://docs.oraxen.com/creating-content/glyphs-hud#shifts-no-more-shiftsyml) ------------------------------------------------------------------------------------------------------------ Oraxen no longer relies on a generated `glyphs/shifts.yml` file. Shifts are now **built-in** using a space font provider that is automatically injected into the default font during pack generation. * If you still have a `plugins/Oraxen/glyphs/shifts.yml`, it is **deprecated** and can be safely deleted. * The shift tags still work (e.g. ``), but they are now backed by a **space provider** rather than “fake glyph textures”. If you previously customized `shifts.yml`, you should migrate that logic to normal glyphs or layout logic. Shifts are now considered infrastructure and are generated automatically. Reference Glyphs[](https://docs.oraxen.com/creating-content/glyphs-hud#reference-glyphs) ----------------------------------------------------------------------------------------- Reference glyphs let you **alias part of an existing glyph** (for example: a subset of a grid glyph), without generating a new provider/texture. This keeps packs smaller and makes large GUI glyphs easier to re-use. Example: `gui_header: reference: glyph: full_gui # Source glyph ID index: 1..3 # Characters to include (1-indexed) chat: placeholders: [":header:"] permission: "gui.header"` Animated Glyphs[](https://docs.oraxen.com/creating-content/glyphs-hud#animated-glyphs) --------------------------------------------------------------------------------------- Animated glyphs render frames from a **PNG sprite sheet** (frames stacked vertically). Animation is handled by shaders generated by Oraxen during pack generation. Example: `loading: texture: animations/loading # Path under plugins/Oraxen/pack/textures (png extension optional) animation: frames: 12 # Number of frames in the sprite sheet (max: 16) fps: 12 # 1-127 (default: 10) loop: true # default: true offset: 0 # optional horizontal offset, in pixels ascent: 8 height: 16 chat: placeholders: [":loading:"]` **Limits:** Animated glyphs support a maximum of **16 frames** per animation. Non-looping animations (`loop: false`) play synchronized to server time, meaning all instances of the same animation will be in sync. Animated glyphs require Oraxen’s pack generation to be enabled and may conflict with other packs that replace Minecraft’s text shaders. If you use multiple packs that edit shaders, use the pack merge system and ensure shader files are merged intentionally. Looking for text effects like rainbow, wave, shake, or pulse? See the [Text Effects](https://docs.oraxen.com/creating-content/text-effects) documentation. PlaceholderAPI[](https://docs.oraxen.com/creating-content/glyphs-hud#placeholderapi) ------------------------------------------------------------------------------------- ### What’s my glyph placeholder?[](https://docs.oraxen.com/creating-content/glyphs-hud#whats-my-glyph-placeholder) The section name is the glyph id. In this example the glyph id is `heart`, the placeholder is `%oraxen_glyphid%`, so in this example: `%oraxen_heart%` Glyph-ID is the first line in any glyphs config, it is not the texturename or the placeholder. ### Shift Placeholders[](https://docs.oraxen.com/creating-content/glyphs-hud#shift-placeholders) Oraxen provides PlaceholderAPI placeholders for pixel shifts, useful when you need to offset text or glyphs in compatible plugins: | Placeholder | Description | | --- | --- | | `%oraxen_shift_N%` | Shifts N pixels to the right (positive) | | `%oraxen_neg_shift_N%` | Shifts N pixels to the left (negative) | **Examples:** * `%oraxen_shift_8%` - Shift 8 pixels to the right * `%oraxen_shift_16%` - Shift 16 pixels to the right * `%oraxen_neg_shift_8%` - Shift 8 pixels to the left * `%oraxen_neg_shift_100%` - Shift 100 pixels to the left These are the PlaceholderAPI equivalent of the `` MiniMessage tags. ### How do I use this in Prefixes / Luckperms[](https://docs.oraxen.com/creating-content/glyphs-hud#how-do-i-use-this-in-prefixes--luckperms) To add a glyph to a luckperms prefix, commonly to display ranks, simply add `%oraxen_glyphid%` to your prefix solution of choice. For example, if using LuckPerms, you can use the command: `/lp group default meta setprefix %oraxen_glyphid%` and it will replace it with the glyph. Because most plugins only parse the placeholders one time, the %luckperms\_prefix% will not be parsed again. You will most likely need to get the Utils-Expansion for PlaceholderAPI aswell. To get this, go to [this link](https://api.extendedclip.com/media/Utils-Expansion-1.0.1.jar)  , and place it in your plugins/PlaceholderAPI/expansions folder. Then in your plugin of choice use `%utils_parse:2_luckperms_prefix%` to parse the prefix again. Keep in mind your chatplugin must support PlaceholderAPI for this to work. If this does not work for whatever reason, you can always use the raw unicode from your glyph-config’s `char`\-property ### How do I use a glyph in name/lore of an item?[](https://docs.oraxen.com/creating-content/glyphs-hud#how-do-i-use-a-glyph-in-namelore-of-an-item) Any glyph can be used in name and lore of your item configurations. `` Where heart is replaced by your glyph section name. Last updated on January 3, 2026 [Shaders (1.18-1.19.4)](https://docs.oraxen.com/creating-content/armors/shaders "Shaders (1.18-1.19.4)") [Custom GUI](https://docs.oraxen.com/creating-content/glyphs-hud/custom-gui "Custom GUI") --- # Custom HUD | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/glyphs-hud/custom-hud#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Glyphs & HUD](https://docs.oraxen.com/creating-content/glyphs-hud "Glyphs & HUD") Custom HUD Copy page Custom HUD ========== Configuration[](https://docs.oraxen.com/creating-content/glyphs-hud/custom-hud#configuration) ---------------------------------------------------------------------------------------------- Below is an example of a “balance” hud defined in `hud.yml`. Keep in mind, this implementation of `shift` is a bit different from the normal one Oraxen provides. `` moves your hud elements 10 pixels to the left, whilst `` moves it 10 pixels to the right. `font` is useful for adjusting the height of your text elements. Essentially this is the same as glyphs work, but will let you use normal text and placeholders. In the example below, we used a font that had its ascent set to -12. Below is an example of what a font-file should look like: `{ "providers": [ { "type": "bitmap", "file": "minecraft:required/ascii_offset.png", "ascent": -13, "height": 8, "chars": [ "\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000", "\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000", "\u0020\u0021\u0022\u0023\u0024\u0025\u0026\u0027\u0028\u0029\u002a\u002b\u002c\u002d\u002e\u002f", "\u0030\u0031\u0032\u0033\u0034\u0035\u0036\u0037\u0038\u0039\u003a\u003b\u003c\u003d\u003e\u003f", "\u0040\u0041\u0042\u0043\u0044\u0045\u0046\u0047\u0048\u0049\u004a\u004b\u004c\u004d\u004e\u004f", "\u0050\u0051\u0052\u0053\u0054\u0055\u0056\u0057\u0058\u0059\u005a\u005b\u005c\u005d\u005e\u005f", "\u0060\u0061\u0062\u0063\u0064\u0065\u0066\u0067\u0068\u0069\u006a\u006b\u006c\u006d\u006e\u006f", "\u0070\u0071\u0072\u0073\u0074\u0075\u0076\u0077\u0078\u0079\u007a\u007b\u007c\u007d\u007e\u0000", "\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000", "\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u00a3\u0000\u0000\u0192", "\u0000\u0000\u0000\u0000\u0000\u0000\u00aa\u00ba\u0000\u0000\u00ac\u0000\u0000\u0000\u00ab\u00bb", "\u2591\u2592\u2593\u2502\u2524\u2561\u2562\u2556\u2555\u2563\u2551\u2557\u255d\u255c\u255b\u2510", "\u2514\u2534\u252c\u251c\u2500\u253c\u255e\u255f\u255a\u2554\u2569\u2566\u2560\u2550\u256c\u2567", "\u2568\u2564\u2565\u2559\u2558\u2552\u2553\u256b\u256a\u2518\u250c\u2588\u2584\u258c\u2590\u2580", "\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u2205\u2208\u0000", "\u2261\u00b1\u2265\u2264\u2320\u2321\u00f7\u2248\u00b0\u2219\u0000\u221a\u207f\u00b2\u25a0\u0000" ] } ] }` Just like with Glyphs, editing the ascent property adjusts the y-position of the text. This will offset the text roughly to where the hud is in the image example below. To add in glyphs you can use both the normal placeholder via `%oraxen_glyphid%` or `` If you do not wish to use custom huds, you can easily disable it by setting `update_time_in_ticks` to 0. In case your HUD doesn’t display despite being properly configured, try toggling it with: `/oraxen hud toggle` followed by your HUD’s name (`/oraxen hud toggle balance`). \#### Example hud.yml: `update_time_in_ticks: 40 huds: balance: permission: "oraxen.hud.balance" display_text: "%vault_eco_balance%" disabled_whilst_in_water: true # Oxygen can be hidden if this is placed right above food enabled_by_default: true enable_for_spectator_mode: true # By default, this is set to false` ![](https://cdn.discordapp.com/attachments/758785982005903431/1002544517158801418/unknown.png) Last updated on January 3, 2026 [Custom GUI](https://docs.oraxen.com/creating-content/glyphs-hud/custom-gui "Custom GUI") [Overview](https://docs.oraxen.com/creating-content/text-effects "Overview") --- # Plugin API | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/text-effects/api#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Text Effects](https://docs.oraxen.com/creating-content/text-effects "Text Effects") Plugin API Copy page Plugin API ========== Oraxen provides a Java API for applying text effects programmatically in your plugins. Basic Usage[](https://docs.oraxen.com/creating-content/text-effects/api#basic-usage) ------------------------------------------------------------------------------------- `import io.th0rgal.oraxen.font.TextEffect; import net.kyori.adventure.text.Component; // Get a specific effect definition TextEffect.Definition rainbow = TextEffect.getEffect("rainbow"); // Apply effect to text Component text = TextEffect.apply("Hello World!", rainbow); // Apply by effect name Component wave = TextEffect.apply("Wavy text!", "wave"); // Convenience methods for built-in effects Component rainbowText = TextEffect.rainbow("Rainbow text!"); Component wavyText = TextEffect.wave("Wavy text!"); Component shakyText = TextEffect.shake("Shaky text!"); Component pulsingText = TextEffect.pulse("Pulsing text!"); // Check if effects are enabled boolean enabled = TextEffect.isEnabled(); boolean rainbowEnabled = TextEffect.isEffectEnabled(rainbow); boolean waveEnabled = TextEffect.isEffectEnabled("wave");` Available Methods[](https://docs.oraxen.com/creating-content/text-effects/api#available-methods) ------------------------------------------------------------------------------------------------- | Method | Description | | --- | --- | | `TextEffect.getEffect(name)` | Get effect definition by name | | `TextEffect.getEffect(id)` | Get effect definition by ID | | `TextEffect.getEffects()` | Get all available effect definitions | | `TextEffect.getEnabledEffects()` | Get all enabled effect definitions | | `TextEffect.apply(text, definition)` | Apply effect to text | | `TextEffect.apply(text, name)` | Apply effect by name | | `TextEffect.isEnabled()` | Check if text effects are enabled globally | | `TextEffect.isEffectEnabled(definition)` | Check if a specific effect is enabled | | `TextEffect.isEffectEnabled(name)` | Check if an effect is enabled by name | | `TextEffect.rainbow(text)` | Apply rainbow effect | | `TextEffect.wave(text)` | Apply wave effect | | `TextEffect.shake(text)` | Apply shake effect | | `TextEffect.pulse(text)` | Apply pulse effect | Effect Definitions[](https://docs.oraxen.com/creating-content/text-effects/api#effect-definitions) --------------------------------------------------------------------------------------------------- Each effect definition contains: `TextEffect.Definition effect = TextEffect.getEffect("rainbow"); String name = effect.getName(); // "rainbow" int id = effect.getId(); // 0 String desc = effect.getDescription(); // "Cycles through rainbow colors over time" boolean enabled = effect.isEnabled(); // true TextColor trigger = effect.getTriggerColor(); // The trigger color for this effect` MiniMessage Integration[](https://docs.oraxen.com/creating-content/text-effects/api#minimessage-integration) ------------------------------------------------------------------------------------------------------------- The simplest way to use text effects is through MiniMessage tags: `import io.th0rgal.oraxen.utils.AdventureUtils; // AdventureUtils.MINI_MESSAGE includes the text effect tag resolver Component text = AdventureUtils.MINI_MESSAGE.deserialize( "Rainbow text!" ); // Works with other MiniMessage tags Component mixed = AdventureUtils.MINI_MESSAGE.deserialize( "Bold wavy text!" );` ### Custom Tag Resolver[](https://docs.oraxen.com/creating-content/text-effects/api#custom-tag-resolver) If you need to add the text effect resolver to your own MiniMessage instance: `import io.th0rgal.oraxen.font.TextEffectTag; import net.kyori.adventure.text.minimessage.MiniMessage; import net.kyori.adventure.text.minimessage.tag.resolver.TagResolver; MiniMessage mm = MiniMessage.builder() .tags(TagResolver.resolver( TagResolver.standard(), TextEffectTag.RESOLVER )) .build(); Component text = mm.deserialize("Hello!");` How Effects Work[](https://docs.oraxen.com/creating-content/text-effects/api#how-effects-work) ----------------------------------------------------------------------------------------------- When you apply a text effect, Oraxen: 1. Sets each character to use an **effect-specific font** (e.g., `oraxen:effect/0` for rainbow) 2. Colors each character with the effect’s **trigger color** (e.g., `#FD0D00` for rainbow) 3. The shader matches this exact color and applies the visual effect `// The returned component has font and color set per-character Component rainbow = TextEffect.apply("Hi", TextEffect.getEffect("rainbow")); // Result: Each character has font=oraxen:effect/0, color=#FD0D00` PlaceholderAPI[](https://docs.oraxen.com/creating-content/text-effects/api#placeholderapi) ------------------------------------------------------------------------------------------- Text effects can be combined with PlaceholderAPI: `// Example: Apply effect to a placeholder result String placeholderResult = PlaceholderAPI.setPlaceholders(player, "%player_name%"); Component effectComponent = TextEffect.apply(placeholderResult, "rainbow");` Enabling/Disabling Effects[](https://docs.oraxen.com/creating-content/text-effects/api#enablingdisabling-effects) ------------------------------------------------------------------------------------------------------------------ You can programmatically toggle effects: `// Toggle global state TextEffect.setGlobalEnabled(false); // Toggle specific effects TextEffect.setEffectEnabled("rainbow", false); TextEffect.Definition wave = TextEffect.getEffect("wave"); TextEffect.setEffectEnabled(wave, true);` Changing effect state at runtime does not regenerate shaders. Effects can only be fully added/removed by editing `text_effects.yml` and reloading the resource pack. Performance Considerations[](https://docs.oraxen.com/creating-content/text-effects/api#performance-considerations) ------------------------------------------------------------------------------------------------------------------- * Text effects are rendered client-side via shaders, so there’s minimal server impact * Effect components are computed once when created * Cache `TextEffect.Definition` objects rather than calling `getEffect()` repeatedly * The MiniMessage tag resolver handles all encoding automatically Last updated on January 3, 2026 [GLSL Customization](https://docs.oraxen.com/creating-content/text-effects/glsl-customization "GLSL Customization") [sound.yml](https://docs.oraxen.com/configuration/sound-yml "sound.yml") --- # GLSL Customization | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/text-effects/glsl-customization#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") [Text Effects](https://docs.oraxen.com/creating-content/text-effects "Text Effects") GLSL Customization Copy page GLSL Customization ================== One of the most powerful features of Oraxen’s text effects system is the ability to customize or create new effects using GLSL (OpenGL Shading Language). The `text_effects.yml` file contains the GLSL snippets that define how each effect works. Interactive Shader Preview[](https://docs.oraxen.com/creating-content/text-effects/glsl-customization#interactive-shader-preview) ---------------------------------------------------------------------------------------------------------------------------------- Try out text effects directly in your browser! Select a template to start with, then modify the GLSL code to create your own effects. The preview uses the Minecraft font and simulates how effects will look in-game. ### ✨ Shader Preview Edit vertex & fragment shaders in real-time Hide Code⏸ Pause↺ Reset⤢ Fullscreen RainbowFWaveV+FShakeV+FPulseF **Rainbow**: Cycles through rainbow colors (fragment only) Text Size (32px) Text Color Background GLSL SHADERS Copy AllReset VERTEX SHADER (position)— // pos.x += ...; pos.y += ...; FRAGMENT SHADER (color)⏳ // Fragment shader - rainbow color cycling float hue = fract(charIndex \* 0.03 + timeSeconds \* 0.09); texColor.rgb = hsv2rgb(vec3(hue, 0.9, 1.0)); // Fragment shader - rainbow color cycling float hue = fract(charIndex \* 0.03 + timeSeconds \* 0.09); texColor.rgb = hsv2rgb(vec3(hue, 0.9, 1.0)); **Tip:** Edit shaders above - vertex controls position (pos.x/y), fragment controls color (texColor.rgb/a). All values are hardcoded in GLSL. GLSL Snippet Structure[](https://docs.oraxen.com/creating-content/text-effects/glsl-customization#glsl-snippet-structure) -------------------------------------------------------------------------------------------------------------------------- Each effect defines its complete visual behavior in GLSL snippets. All parameters (speed, amplitude, colors) are hardcoded in the snippets - no runtime variables needed: text\_effects.yml `effects: my_effect: # id: 0 # Optional - auto-assigned if omitted enabled: true # trigger_color: "#FD0D00" # Optional - defaults to #FDxD00 description: My custom effect snippets: - targets: # Optional: version constraints min_pack_format: 34 min_version: "1.21.4" vertex: | // Vertex shader code (position effects) pos.y += sin(timeSeconds * 6.0) * 2.0; fragment: | // Fragment shader code (color effects) texColor.rgb = vec3(1.0, 0.0, 0.0);` Available Variables[](https://docs.oraxen.com/creating-content/text-effects/glsl-customization#available-variables) -------------------------------------------------------------------------------------------------------------------- These variables are available in your GLSL snippets: | Variable | Type | Description | | --- | --- | --- | | `timeSeconds` | `float` | Game time in seconds (for animation) | | `charIndex` | `float` | Character index in the string (from `gl_VertexID`) | | `pos` | `vec3` | Vertex position (vertex shader only) | | `texColor` | `vec4` | Texture color RGBA (fragment shader only) | Unlike previous versions, `speed` and `param` variables are no longer available. All effect parameters should be hardcoded directly in your GLSL snippets for simplicity and to avoid false positives. Shared Code[](https://docs.oraxen.com/creating-content/text-effects/glsl-customization#shared-code) ---------------------------------------------------------------------------------------------------- The `shared` section defines reusable GLSL functions that are available to all effects: text\_effects.yml `shared: fragment_prelude: | // HSV to RGB conversion - useful for color effects vec3 hsv2rgb(vec3 c) { vec4 K = vec4(1.0, 2.0/3.0, 1.0/3.0, 3.0); vec3 p = abs(fract(c.xxx + K.xyz) * 6.0 - K.www); return c.z * mix(K.xxx, clamp(p - K.xxx, 0.0, 1.0), c.y); } vertex_prelude: | // Add any vertex shader helper functions here` Built-in Effect Examples[](https://docs.oraxen.com/creating-content/text-effects/glsl-customization#built-in-effect-examples) ------------------------------------------------------------------------------------------------------------------------------ These are the default effects from `text_effects.yml`: RainbowWaveShakePulse ### Rainbow **Rainbow Effect** - Cycles through hue colors over time `// Fragment shader float hue = fract(charIndex * 0.03 + timeSeconds * 0.09); texColor.rgb = hsv2rgb(vec3(hue, 0.9, 1.0));` **How it works:** * Uses `charIndex` to offset each character’s hue for a gradient effect * `timeSeconds * 0.09` animates the color cycling * `hsv2rgb()` converts the hue value to RGB colors * Saturation is 0.9, brightness is 1.0 ### Wave **Wave Effect** - Vertical sine wave motion `// Fragment shader - sets the wave color texColor.rgb = vec3(0.333, 0.804, 0.988); // Vertex shader - applies the wave motion float phase = charIndex * 0.6 + timeSeconds * 6.0; pos.y += sin(phase) * 2.0;` **How it works:** * Each character has a phase offset based on its index * `sin(phase)` creates the wave motion * Amplitude (`2.0`) and speed (`6.0`) are hardcoded * Color is set to a light blue ### Shake **Shake Effect** - Random jitter `// Fragment shader - sets the shake color texColor.rgb = vec3(1.0, 0.42, 0.42); // Vertex shader - applies random jitter float seed = charIndex + floor(timeSeconds * 32.0); pos.x += (fract(sin(seed * 12.9898) * 43758.5453) - 0.5) * 1.5; pos.y += (fract(sin(seed * 78.233) * 43758.5453) - 0.5) * 1.5;` **How it works:** * Uses a pseudo-random number generator based on `sin()` * `floor(timeSeconds * 32.0)` creates discrete shake “frames” * Random offset is applied to both X and Y positions * Intensity (`1.5`) is hardcoded ### Pulse **Pulse Effect** - Opacity fades in/out `// Fragment shader texColor.rgb = vec3(1.0, 0.85, 0.24); float pulse = (sin(timeSeconds * 1.5 + charIndex * 0.3) + 1.0) * 0.5; texColor.a *= 0.3 + pulse * 0.7;` **How it works:** * Uses `sin()` to oscillate between 0 and 1 * Adds `charIndex * 0.3` to offset each character’s phase * Multiplies the alpha channel to fade opacity * Minimum opacity is 0.3 (30%), color is golden yellow Creating Custom Effects[](https://docs.oraxen.com/creating-content/text-effects/glsl-customization#creating-custom-effects) ---------------------------------------------------------------------------------------------------------------------------- To create your own effect: 1. Add your effect to `text_effects.yml` (IDs are auto-assigned, or specify one explicitly): text\_effects.yml `effects: # Custom: Glowing text that pulses brighter and darker glow: enabled: true description: Glowing brightness pulse snippets: - fragment: | float glow = (sin(timeSeconds * 3.0) + 1.0) * 0.5; float brightness = 0.7 + glow * 0.6; // 0.7 to 1.3 texColor.rgb = vec3(0.9, 0.7, 0.2) * brightness;` 2. Reload Oraxen with `/oraxen reload all` 3. Test with `/oraxen texteffect glow Your glowing text!` 4. Or use in MiniMessage: `Glowing!` GLSL Reference[](https://docs.oraxen.com/creating-content/text-effects/glsl-customization#glsl-reference) ---------------------------------------------------------------------------------------------------------- ### Common Functions[](https://docs.oraxen.com/creating-content/text-effects/glsl-customization#common-functions) `sin(x), cos(x) // Smooth oscillation (-1 to 1) fract(x) // Fractional part (0 to 1) floor(x) // Round down (for discrete steps) step(edge, x) // 0.0 if x < edge, else 1.0 (binary threshold) clamp(x, min, max) // Constrain value to range mix(a, b, t) // Linear interpolation mod(x, y) // Remainder (for looping) abs(x) // Absolute value max(a, b), min(a, b) // Maximum/minimum of two values pow(x, y) // Power function sqrt(x) // Square root length(vec) // Vector length normalize(vec) // Unit vector dot(a, b) // Dot product` ### Useful Patterns[](https://docs.oraxen.com/creating-content/text-effects/glsl-customization#useful-patterns) `// Smooth oscillation between 0 and 1 float wave = (sin(timeSeconds * 2.0) + 1.0) * 0.5; // Discrete steps (for frame-like animation) float frame = floor(timeSeconds * 10.0); // 10 FPS // Per-character phase offset float phase = charIndex * 0.5 + timeSeconds * 3.0; // Pseudo-random based on seed float rand = fract(sin(seed * 12.9898) * 43758.5453); // Smooth step (ease in/out) float t = smoothstep(0.0, 1.0, x); // Ping-pong (oscillate 0 to 1 to 0) float pingpong = abs(mod(timeSeconds, 2.0) - 1.0); // Color from grayscale vec3 color = vec3(grayscale); // Darken color texColor.rgb *= 0.5; // Brighten color (may exceed 1.0) texColor.rgb *= 1.5; // Invert color texColor.rgb = 1.0 - texColor.rgb; // Desaturate (convert to grayscale) float gray = dot(texColor.rgb, vec3(0.299, 0.587, 0.114)); texColor.rgb = vec3(gray);` ### Custom Effect Ideas[](https://docs.oraxen.com/creating-content/text-effects/glsl-customization#custom-effect-ideas) Here are some ideas for custom effects you can create: **Breathing Effect** - Slow scale pulse `// Vertex shader float breath = (sin(timeSeconds * 1.5) + 1.0) * 0.1 + 0.9; pos *= breath;` **Color Shift** - Cycle through colors `// Fragment shader float shift = timeSeconds * 0.5; texColor.rgb = vec3( sin(shift) * 0.5 + 0.5, sin(shift + 2.094) * 0.5 + 0.5, sin(shift + 4.188) * 0.5 + 0.5 );` **Glitch Effect** - Random color/position jumps `// Fragment shader float glitch = step(0.95, fract(sin(floor(timeSeconds * 20.0) * charIndex) * 43758.5453)); texColor.rgb = mix(texColor.rgb, 1.0 - texColor.rgb, glitch);` **Fade In** - Characters fade in from transparent `// Fragment shader float fadeTime = 2.0; // seconds to fully appear float progress = clamp(timeSeconds / fadeTime, 0.0, 1.0); float alpha = smoothstep(charIndex / 20.0, charIndex / 20.0 + 0.1, progress); texColor.a *= alpha;` Version-Specific Snippets[](https://docs.oraxen.com/creating-content/text-effects/glsl-customization#version-specific-snippets) -------------------------------------------------------------------------------------------------------------------------------- You can define different GLSL code for different Minecraft versions: text\_effects.yml `effects: custom: enabled: true snippets: # Snippet for 1.21.6+ - targets: min_version: "1.21.6" fragment: | // Modern shader code texColor.rgb = vec3(1.0, 0.5, 0.0); # Fallback for older versions - targets: max_version: "1.21.5" fragment: | // Legacy shader code texColor.rgb = vec3(0.8, 0.4, 0.0);` The first matching snippet (based on `targets`) is used. Snippets without targets always match. ### Target Options[](https://docs.oraxen.com/creating-content/text-effects/glsl-customization#target-options) | Option | Description | | --- | --- | | `min_pack_format` | Minimum resource pack format | | `max_pack_format` | Maximum resource pack format | | `min_version` | Minimum Minecraft version (e.g., “1.21.4”) | | `max_version` | Maximum Minecraft version (e.g., “1.21.5”) | Debugging Tips[](https://docs.oraxen.com/creating-content/text-effects/glsl-customization#debugging-tips) ---------------------------------------------------------------------------------------------------------- When developing custom effects, you can quickly test changes by using `/oraxen reload all` after editing `text_effects.yml`. **Common issues:** 1. **Effect not showing**: Check that the effect name matches what you’re using in the tag 2. **Syntax errors**: GLSL is strict - ensure semicolons and proper types 3. **Nothing visible**: Check if `texColor.a` is being set to 0 4. **Flickering**: Use `floor()` for discrete animations, not continuous values 5. **Effect not triggering**: Make sure the effect is enabled in config **Test your GLSL locally:** Use the [Interactive Shader Preview](https://docs.oraxen.com/creating-content/text-effects/glsl-customization#interactive-shader-preview) at the top of this page to prototype effects before adding them to Oraxen. It uses the same Minecraft font and simulates the shader environment. Last updated on January 3, 2026 [Overview](https://docs.oraxen.com/creating-content/text-effects "Overview") [Plugin API](https://docs.oraxen.com/creating-content/text-effects/api "Plugin API") --- # Branding & Customization | Oraxen Docs [Skip to Content](https://docs.oraxen.com/configuration/branding-customization#nextra-skip-nav) [Configuration Reference](https://docs.oraxen.com/configuration/sound-yml "Configuration Reference") Branding & Customization Copy page Branding & Customization ======================== Learn how to customize Oraxen’s branding, change plugin messages, update prefixes, and modify language files to match your server’s identity. Changing the Plugin Prefix[](https://docs.oraxen.com/configuration/branding-customization#changing-the-plugin-prefix) ---------------------------------------------------------------------------------------------------------------------- The plugin prefix appears before all Oraxen messages in chat. To customize it: **Location:** `plugins/Oraxen/languages/.yml` For English, edit `plugins/Oraxen/languages/english.yml`: `general: prefix: "Oraxen | "` ### Examples[](https://docs.oraxen.com/configuration/branding-customization#examples) **Simple colored prefix:** `prefix: "[MyServer] "` **Gradient with custom colors:** `prefix: "MyServer » "` **Multiple color stops:** `prefix: "✦ MyPlugin | "` After changing the prefix, reload with `/oraxen reload all`. Customizing Plugin Messages[](https://docs.oraxen.com/configuration/branding-customization#customizing-plugin-messages) ------------------------------------------------------------------------------------------------------------------------ All plugin messages are stored in language files. Oraxen supports 9 languages: * `english.yml` (default) * `french.yml` * `german.yml` * `czech.yml` * `spanish.yml` * `korean.yml` * `japanese.yml` * `chinese-simplified.yml` (zh-CN) * `chinese-traditional.yml` (zh-TW) * `russian.yml` (ru-RU) * `portuguese-brazil.yml` (pt-BR) ### Changing the Language[](https://docs.oraxen.com/configuration/branding-customization#changing-the-language) In `settings.yml`: `Plugin: language: "english" # Change to: french, german, czech, korean, jpn_JP, ru-RU, zh-CN, zh-TW, pt-BR` ### Editing Messages[](https://docs.oraxen.com/configuration/branding-customization#editing-messages) **Location:** `plugins/Oraxen/languages/.yml` Example customizations in `english.yml`: `general: prefix: "Oraxen | " no_permission: "<#fa4943>You're lacking the permission to do this!" reload: "<#55ffa4>Successfully reloaded" # Customize to your server's style: reload: "✓ Configuration reloaded!" no_permission: "⚠ Missing permission: "` ### Message Formatting[](https://docs.oraxen.com/configuration/branding-customization#message-formatting) Oraxen uses [MiniMessage](https://docs.advntr.dev/minimessage/format.html)   formatting: **Colors:** * ``, ``, ``, etc. * `<#HEX>` for custom colors: `<#FF5733>` * `text` **Formatting:** * ``, ``, `` * ``, `` **Placeholders:** * `` - The plugin prefix * `` - Required permission * `` - Player name * `` - Item name * `` - Numerical amount Example: `updated_items: "✓ Updated items for !"` Customizing Welcome Messages[](https://docs.oraxen.com/configuration/branding-customization#customizing-welcome-messages) -------------------------------------------------------------------------------------------------------------------------- ### Join Message (Text)[](https://docs.oraxen.com/configuration/branding-customization#join-message-text) The text message sent when players join (separate from the welcome sound): **Location:** `settings.yml` `Pack: dispatch: join_message: enabled: false # Set to true to enable delay: -1 # Delay in ticks (-1 = instant, 20 = 1 second)` The message content is defined in `languages/.yml`: `command: join: |- {Resource Pack} To see the new items you need to use a special resourcepack (but don't worry, this doesn't prevent you from using yours at the same time). » To try to load it directly from the game, ! loading the resourcepack from the game can cause lags">CLICK HERE` ### Welcome Sound[](https://docs.oraxen.com/configuration/branding-customization#welcome-sound) **Location:** `settings.yml` `Pack: receive: loaded: actions: sound: enabled: true # Set to false to disable type: minecraft:welcome # Change to your custom sound volume: 1.0 pitch: 1.0` To use a custom sound, you must first register it in `sound.yml`. See the [sound.yml documentation](https://docs.oraxen.com/configuration/sound-yml) for details. Customizing Resource Pack Prompt[](https://docs.oraxen.com/configuration/branding-customization#customizing-resource-pack-prompt) ---------------------------------------------------------------------------------------------------------------------------------- When players join, they see a prompt to accept the resource pack: **Location:** `settings.yml` `Pack: dispatch: prompt: "<#fa4943>Accept the pack to enjoy a full Oraxen<#fa4943> experience"` ### Examples[](https://docs.oraxen.com/configuration/branding-customization#examples-1) **Simple prompt:** `prompt: "Please accept the resource pack to see custom items!"` **Branded prompt:** `prompt: "MyServer requires this pack for the full experience!"` **With emojis:** `prompt: "✨ Accept our custom pack for awesome items! ✨"` Customizing Pack Comments (Watermark)[](https://docs.oraxen.com/configuration/branding-customization#customizing-pack-comments-watermark) ------------------------------------------------------------------------------------------------------------------------------------------ Add a custom watermark inside the resource pack ZIP file: **Location:** `settings.yml` `Pack: generation: comment: "The content of this texture pack \nbelongs to the owner of the Oraxen \nplugin and any complete or partial \nuse must comply with the terms and \nconditions of Oraxen."` Change this to your server’s copyright notice or branding. Creating Custom Language Files[](https://docs.oraxen.com/configuration/branding-customization#creating-custom-language-files) ------------------------------------------------------------------------------------------------------------------------------ To create a custom language file (e.g., for a language not yet supported): 1. Copy `plugins/Oraxen/languages/english.yml` to your desired language name 2. Translate all messages while keeping the same structure 3. Update `settings.yml`: `Plugin: language: "custom" # Name of your new language file (without .yml)` Common Customization Examples[](https://docs.oraxen.com/configuration/branding-customization#common-customization-examples) ---------------------------------------------------------------------------------------------------------------------------- ### Minimal/Clean Style[](https://docs.oraxen.com/configuration/branding-customization#minimalclean-style) `general: prefix: "[O] " reload: "Reloaded." no_permission: "No permission."` ### Luxury/Premium Style[](https://docs.oraxen.com/configuration/branding-customization#luxurypremium-style) `general: prefix: "⚜ ORAXEN » " reload: "✓ Successfully reloaded all configurations!" no_permission: "⚠ Access Denied | Missing: "` ### Roleplay/Fantasy Style[](https://docs.oraxen.com/configuration/branding-customization#roleplayfantasy-style) `general: prefix: "⚔ Oraxen Magic ~ " reload: "<#90EE90>The ancient scrolls have been refreshed!" no_permission: "<#FF6347>The arcane forces deny you access! ()"` Troubleshooting[](https://docs.oraxen.com/configuration/branding-customization#troubleshooting) ------------------------------------------------------------------------------------------------ ### Messages Show Without Colors[](https://docs.oraxen.com/configuration/branding-customization#messages-show-without-colors) Ensure MiniMessage formatting is enabled in `settings.yml`: `Plugin: formatting: chat: true` ### Prefix Doesn’t Change[](https://docs.oraxen.com/configuration/branding-customization#prefix-doesnt-change) 1. Make sure you edited the correct language file (check `Plugin.language` in settings.yml) 2. Use `/oraxen reload all` to apply changes 3. Verify you’re using MiniMessage format, not legacy color codes (`&c`, `§c` won’t work) ### Custom Language File Not Loading[](https://docs.oraxen.com/configuration/branding-customization#custom-language-file-not-loading) 1. Ensure the filename matches exactly (case-sensitive) 2. Check for YAML syntax errors with an online validator 3. Verify the file is in `plugins/Oraxen/languages/` 4. Restart the server (some language changes require restart) See Also[](https://docs.oraxen.com/configuration/branding-customization#see-also) ---------------------------------------------------------------------------------- * [sound.yml Configuration](https://docs.oraxen.com/configuration/sound-yml) - Customize sounds * [Plugin Settings](https://docs.oraxen.com/plugin-setup/plugin-settings) - General plugin configuration * [MiniMessage Documentation](https://docs.advntr.dev/minimessage/format.html)   - Full formatting guide Last updated on January 3, 2026 [sound.yml](https://docs.oraxen.com/configuration/sound-yml "sound.yml") [Understanding the Basics](https://docs.oraxen.com/plugin-setup/understanding-the-basics "Understanding the Basics") --- # Text Effects | Oraxen Docs [Skip to Content](https://docs.oraxen.com/creating-content/text-effects#nextra-skip-nav) [Creating Content](https://docs.oraxen.com/creating-content "Creating Content") Text EffectsOverview Copy page Text Effects ============ Text effects are shader-based visual effects that can be applied to any text in Minecraft. Unlike animated glyphs which swap between sprite frames, text effects modify how existing characters render (color, position, opacity) using GLSL shaders. Text effects require Minecraft 1.21.4+ and Oraxen’s resource pack with shaders enabled. Quick Start[](https://docs.oraxen.com/creating-content/text-effects#quick-start) --------------------------------------------------------------------------------- Apply text effects using MiniMessage tags: `This text is rainbow! Wavy text here Shaking text!` These tags work anywhere MiniMessage is supported - item names, lore, chat, signs, etc. Configuration[](https://docs.oraxen.com/creating-content/text-effects#configuration) ------------------------------------------------------------------------------------- Text effects are configured in two files: * **`settings.yml`** - Master toggle and shader settings * **`text_effects.yml`** - Effect definitions and GLSL snippets ### settings.yml[](https://docs.oraxen.com/creating-content/text-effects#settingsyml) settings.yml `TextEffects: enabled: true # Master toggle for all text effects shader: template: auto # auto, effects_only, animated_only effects: # Optional: override enabled state per effect rainbow: enabled: true wave: enabled: false # Disable specific effects` ### text\_effects.yml[](https://docs.oraxen.com/creating-content/text-effects#text_effectsyml) Effects are defined with their visual behavior baked directly into the GLSL snippets: text\_effects.yml `version: 1 # Shared GLSL code available to all effects shared: fragment_prelude: | vec3 hsv2rgb(vec3 c) { vec4 K = vec4(1.0, 2.0/3.0, 1.0/3.0, 3.0); vec3 p = abs(fract(c.xxx + K.xyz) * 6.0 - K.www); return c.z * mix(K.xxx, clamp(p - K.xxx, 0.0, 1.0), c.y); } effects: rainbow: # id: 0 # Optional - auto-assigned if omitted enabled: true # trigger_color: "#FD0D00" # Optional - defaults to #FDxD00 description: Cycles through rainbow colors over time snippets: - fragment: | float hue = fract(charIndex * 0.03 + timeSeconds * 0.09); texColor.rgb = hsv2rgb(vec3(hue, 0.9, 1.0));` ### Configuration Options[](https://docs.oraxen.com/creating-content/text-effects#configuration-options) | Option | Description | Values | | --- | --- | --- | | `enabled` | Master toggle for all text effects | `true` / `false` | | `shader.template` | Which shaders to generate | `auto`, `effects_only`, `animated_only` | ### Effect Options[](https://docs.oraxen.com/creating-content/text-effects#effect-options) | Option | Description | Default | | --- | --- | --- | | `id` | Numeric effect ID (0-7) | Auto-assigned in order | | `enabled` | Whether the effect is available | `true` | | `trigger_color` | Hex color the shader matches | `#FDxD00` (x = id) | | `description` | Shown in `/oraxen texteffects` | — | | `snippets` | GLSL code for the effect | — | ### Shader Templates[](https://docs.oraxen.com/creating-content/text-effects#shader-templates) * **`auto`**: Generates shaders for both text effects and animated glyphs (recommended) * **`effects_only`**: Only generates text effect shaders * **`animated_only`**: Only generates animated glyph shaders Built-in Effects[](https://docs.oraxen.com/creating-content/text-effects#built-in-effects) ------------------------------------------------------------------------------------------- | Effect | Description | | --- | --- | | `rainbow` | Cycles through hue colors over time | | `wave` | Vertical sine wave motion | | `shake` | Random jitter/shake | | `pulse` | Opacity fades in and out | All effect parameters (speed, amplitude, colors) are defined in `text_effects.yml` and baked into the shader at resource pack generation time. Commands[](https://docs.oraxen.com/creating-content/text-effects#commands) --------------------------------------------------------------------------- Test effects in-game with these commands: `/oraxen texteffects # List all available effects /oraxen texteffect # Apply effect to text` ### Examples[](https://docs.oraxen.com/creating-content/text-effects#examples) `/oraxen texteffect rainbow Hello World! /oraxen texteffect wave Wavy Text /oraxen texteffect shake Very Shaky!` Permission required: `oraxen.command.texteffect` How It Works[](https://docs.oraxen.com/creating-content/text-effects#how-it-works) ----------------------------------------------------------------------------------- Text effects use a trigger color system to avoid false positives from gradient colors: 1. Each effect has a unique **trigger color** (e.g., `#FD0D00` for rainbow) 2. Text is rendered with a dedicated **effect font** (e.g., `oraxen:effect/0`) 3. The shader matches the exact trigger color and applies the effect This ensures only intentionally styled text triggers effects - normal colored text is never affected. ### Trigger Colors[](https://docs.oraxen.com/creating-content/text-effects#trigger-colors) Default trigger colors follow the pattern `#FDxD00` where `x` is the effect ID: | Effect | ID | Default Trigger Color | | --- | --- | --- | | rainbow | 0 | `#FD0D00` | | wave | 1 | `#FD1D00` | | shake | 2 | `#FD2D00` | | pulse | 3 | `#FD3D00` | You can customize trigger colors in `text_effects.yml` if needed. Compatibility Notes[](https://docs.oraxen.com/creating-content/text-effects#compatibility-notes) ------------------------------------------------------------------------------------------------- Text effects may conflict with other resource packs that modify Minecraft’s text shaders (`rendertype_text.vsh`, `rendertype_text.fsh`). If you use multiple packs that edit shaders, use the pack merge system and ensure shader files are merged correctly. ### Known Limitations[](https://docs.oraxen.com/creating-content/text-effects#known-limitations) * Effects are rendered client-side via shaders * Shadows are hidden for text with effects to avoid visual artifacts * 8 effect slots available (IDs 0-7) * Character index derived from `gl_VertexID` in shader ### Minecraft Version Support[](https://docs.oraxen.com/creating-content/text-effects#minecraft-version-support) | Version | Support | | --- | --- | | 1.21.4+ | Full support | | Below 1.21.4 | Not supported | Last updated on January 3, 2026 [Custom HUD](https://docs.oraxen.com/creating-content/glyphs-hud/custom-hud "Custom HUD") [GLSL Customization](https://docs.oraxen.com/creating-content/text-effects/glsl-customization "GLSL Customization") --- # Resource Pack Hosting | Oraxen Docs [Skip to Content](https://docs.oraxen.com/plugin-setup/pack-hosting#nextra-skip-nav) [Plugin Setup](https://docs.oraxen.com/plugin-setup/understanding-the-basics "Plugin Setup") Pack Hosting Copy page Resource Pack Hosting ===================== Oraxen allows multiple ways of hosting your resource pack. The resource pack has to be hosted, so it can be sent to other players. Overview[](https://docs.oraxen.com/plugin-setup/pack-hosting#overview) ----------------------------------------------------------------------- After Oraxen generates the resource pack, it automatically uploads it to a server, which then hosts the resource pack and allows other players to download it. The resource pack can either be hosted on a remote server (atlas), or locally using the built-in webserver. Oraxen Atlas (Polymath)[](https://docs.oraxen.com/plugin-setup/pack-hosting#oraxen-atlas-polymath) --------------------------------------------------------------------------------------------------- ### An external server hosted by Oraxen that allows the resource pack to be distributed easily without open ports or any setup.[](https://docs.oraxen.com/plugin-setup/pack-hosting#an-external-server-hosted-by-oraxen-that-allows-the-resource-pack-to-be-distributed-easily-without-open-ports-or-any-setup) The Oraxen Atlas is an external server (Polymath instance) hosted by Oraxen itself. It’s free, easy to use, and is the default option when first setting up Oraxen. We recommend this method for most users as it’s simple and mostly reliable. It also requires no additional server ports, making it the best choice for free minecraft server hosts. ### Configuration[](https://docs.oraxen.com/plugin-setup/pack-hosting#configuration) The Oraxen Atlas is setup by default with the following configuration. `upload: enabled: true type: polymath #transfer.sh, polymath, or self-host 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` ### Limitations & Advantages[](https://docs.oraxen.com/plugin-setup/pack-hosting#limitations--advantages) ✓ Free to use ✓ Easy to set up ✓ Requires no additional ports or setup ✗ May not work in some countries (Russia, China) ✗ May experience occasional downtime Self-Hosted Polymath Instance[](https://docs.oraxen.com/plugin-setup/pack-hosting#self-hosted-polymath-instance) ----------------------------------------------------------------------------------------------------------------- ### A server that has to be hosted by yourself.[](https://docs.oraxen.com/plugin-setup/pack-hosting#a-server-that-has-to-be-hosted-by-yourself) Oraxen allows you to host your own Polymath instance and connect it to Oraxen. It makes you independent from Oraxen’s atlas and fixes most country related issues. ### Configuration[](https://docs.oraxen.com/plugin-setup/pack-hosting#configuration-1) You can host your own Polymath instance by following [this](https://github.com/oraxen/polymath)   guide. Polymath is open source and it’s mostly easy to set up. After successfully running your own Polymath instance, you have to configure Oraxen to point at it instead of the default one. `upload: enabled: true type: polymath #transfer.sh, polymath, or self-host polymath: server: atlas.oraxen.com # this is the domain your polymath instance runs on secret: "oraxen" # this is the secret key used to authenticate requests, so other people cannot upload resource packs to your polymath` ### Limitations & Advantages[](https://docs.oraxen.com/plugin-setup/pack-hosting#limitations--advantages-1) ✓ Independent from the Oraxen Atlas ✓ Works in all countries (including Russia, China) ✗ Requires a webserver ✗ Requires additional setup ✗ Requires a port & must be accessible from outside network Self-Hosted Minecraft Server (with an open Port)[](https://docs.oraxen.com/plugin-setup/pack-hosting#self-hosted-minecraft-server-with-an-open-port) ----------------------------------------------------------------------------------------------------------------------------------------------------- ### Runs on your Minecraft server using Java’s built-in `com.sun.net.httpserver`.[](https://docs.oraxen.com/plugin-setup/pack-hosting#runs-on-your-minecraft-server-using-javas-built-in-comsunnethttpserver) Oraxen allows you to host your own resource pack server directly on your Minecraft server with an open port. ### Configuration[](https://docs.oraxen.com/plugin-setup/pack-hosting#configuration-2) `upload: enabled: true type: self-host 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")` ### Limitations & Advantages[](https://docs.oraxen.com/plugin-setup/pack-hosting#limitations--advantages-2) ✓ Independent from the Oraxen Atlas ✓ Works in all countries (including Russia, China) ✗ Requires a port & must be accessible from outside network ✗ May use more of server resources (CPU/RAM, but usually not noticeable) Default Setup[](https://docs.oraxen.com/plugin-setup/pack-hosting#default-setup) --------------------------------------------------------------------------------- `Pack: upload: enabled: true type: polymath #transfer.sh, polymath, or self-host 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 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")` Last updated on January 17, 2026 [Plugin Settings](https://docs.oraxen.com/plugin-setup/plugin-settings "Plugin Settings") [Pack Merging](https://docs.oraxen.com/plugin-setup/pack-merging "Pack Merging") --- # Understanding the Basics | Oraxen Docs [Skip to Content](https://docs.oraxen.com/plugin-setup/understanding-the-basics#nextra-skip-nav) Plugin SetupUnderstanding the Basics Copy page Understanding the Basics ======================== As seen previously, Oraxen is able to generate custom items including the texture pack that goes with them. It also makes it possible to associate these items with special powers or capabilities known as mechanics. Color and other minecraft formatting[](https://docs.oraxen.com/plugin-setup/understanding-the-basics#color-and-other-minecraft-formatting) ------------------------------------------------------------------------------------------------------------------------------------------- Minecraft only supported 16 colors in the past and most plugins used a special format with the & character. However, 1.16 added hex coloring for text and given the amount of formatting possible (clickable messages for example). Since PaperMC supports the [MiniMessage format](https://docs.adventure.kyori.net/minimessage.html#format)  . You are able to use hex coloring for items as well as some other additional tricks. If you’d like to try out minimessage formatting, [click here](https://webui.advntr.dev/)  ! Examples: * Hex Colors - `<#FF5555>I start out red <#55FF55>and now im green!` * Simple Colors - `I'm green now I'm golden now I'm green again!` * Auto Gradient - `This example automatically applies a gradient to whatever is between the start and end of the gradient` ![image](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fminimessage_example.70840c16.png&w=1920&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) Content of the Oraxen folder[](https://docs.oraxen.com/plugin-setup/understanding-the-basics#content-of-the-oraxen-folder) --------------------------------------------------------------------------------------------------------------------------- Oraxen ### Global configurations[](https://docs.oraxen.com/plugin-setup/understanding-the-basics#global-configurations) At root of this configuration folder you’ll find two files: `settings.yml` which contains various settings for Oraxen and `mechanics.yml` which contains global mechanics settings. ### Items configurations[](https://docs.oraxen.com/plugin-setup/understanding-the-basics#items-configurations) The subfolder `Oraxen/items` contains all created/purchased item configurations. You may make a new file for any item(s) you’d like or remove existing ones. While everything can be in a single file, storing them in folders with explicit names should help keep things organized. ### Resourcepack[](https://docs.oraxen.com/plugin-setup/understanding-the-basics#resourcepack) The resource pack is a crucial element of Oraxen and even if it is able to generate most of the files you will need, you will still have to provide the textures of the custom items yourself, all this is managed inside the `Oraxen/pack` folder. You can use the `Oraxen/pack/textures` subfolder for adding textures and the `Oraxen/pack/models` subfolder for adding models (if you want to use 3D items for example). You can also change the basic files of the pack (pack.mcmeta, pack icon, etc.) from the `Oraxen/pack` folder itself. If you need to override a specific file from Oraxen, you can create the `Oraxen/pack/assets` folder and insert for example `assets/minecraft/sounds.json` to override that file if generated by Oraxen. ### Recipes[](https://docs.oraxen.com/plugin-setup/understanding-the-basics#recipes) This folder contains the different recipe configurations you have added which are sorted by recipe type. For example, `Oraxen/recipes/shaped.yml` will contain all shaped recipes while `Oraxen/recipes/campfire.yml` will have any campfire recipes. _This folder is rarely touched because it is easier/faster to generate recipe configs directly from the game via the [oraxen recipe command](https://docs.oraxen.com/usage/commands#manage-recipes) ._ Last updated on January 17, 2026 [Branding & Customization](https://docs.oraxen.com/configuration/branding-customization "Branding & Customization") [Plugin Settings](https://docs.oraxen.com/plugin-setup/plugin-settings "Plugin Settings") --- # Plugin Settings | Oraxen Docs [Skip to Content](https://docs.oraxen.com/plugin-setup/plugin-settings#nextra-skip-nav) [Plugin Setup](https://docs.oraxen.com/plugin-setup/understanding-the-basics "Plugin Setup") Plugin Settings Copy page Plugin Settings =============== Plugin[](https://docs.oraxen.com/plugin-setup/plugin-settings#plugin) ---------------------------------------------------------------------- `Plugin: commands: repair: oraxen_durability_only: false # will not repair vanilla items if set to true` The plugin related options. Here you can configure how some things work. Should the repair only repair Oraxen items with an oraxen durability? Plugin Options[](https://docs.oraxen.com/plugin-setup/plugin-settings#plugin-options) -------------------------------------------------------------------------------------- `Plugin: language: english # Language file to use debug: false # Enable verbose logging (NMS detection, pack generation, HUD loading, etc.) auto_update_paper_config: true # Automatically update paper-global.yml for custom blocks generation: default_assets: true # Generate default textures/models on first run default_configs: true # Generate default item configs on first run formatting: # Enable MiniMessage formatting in various contexts inventory_titles: true titles: true subtitles: true action_bar: true anvil: false signs: false chat: false books: false` ### Debug Mode[](https://docs.oraxen.com/plugin-setup/plugin-settings#debug-mode) When `debug: true` is enabled, Oraxen outputs additional informational messages to the console, including: * NMS version detection * Packet adapter selection * Resource pack generation progress * HUD loading details * Shift font generation messages These messages are hidden by default to keep console output clean. ### Auto Update Paper Config[](https://docs.oraxen.com/plugin-setup/plugin-settings#auto-update-paper-config) When `auto_update_paper_config: true` (default), Oraxen automatically updates your `paper-global.yml` to disable block updates that interfere with custom blocks: * `disable-noteblock-updates: true` * `disable-tripwire-updates: true` * `disable-chorus-plant-updates: true` Set to `false` if you prefer to manage these settings manually. You can also override this with the JVM flag `-Doraxen.autoUpdatePaperConfig=false`. Item configurations[](https://docs.oraxen.com/plugin-setup/plugin-settings#item-configurations) ------------------------------------------------------------------------------------------------ ### How do the Oraxen configurations work?[](https://docs.oraxen.com/plugin-setup/plugin-settings#how-do-the-oraxen-configurations-work) First, Oraxen has several folders and 3 of these are to configure things, the first one is `Oraxen/glyphs/` and is to configure the Custom Font or Glyph, then `Oraxen/items/` and is to configure and create your own configuration yaml and lastly `Oraxen/pack/` the target place where all the files like textures and models will be created, Pack[](https://docs.oraxen.com/plugin-setup/plugin-settings#pack) ------------------------------------------------------------------ ### Generation[](https://docs.oraxen.com/plugin-setup/plugin-settings#generation) `generation: generate: true compression: BEST_COMPRESSION # see Deflater.class # protection will use several methods to make your pack impossible to extract # with usual tools (native windows unzip, 7zip, winrar, etc) without altering # its integrity. Be careful if you activate this option to not try to extract # the pack or you might fill your disk. protection: true comment: "The content of this texture pack \nbelongs to the owner of the Oraxen \nplugin and any complete or partial \nuse must comply with the terms and \nconditions of Oraxen." appearance: item_properties: true # Use item_model component model_data_ids: false # Use custom_model_data.strings with select model_data_float: false # Use custom_model_data.floats with range_dispatch generate_predicates: false # Generate legacy predicates (not needed on 1.21.4+)` This section allows you to configure the **generation** of the pack. The **compression** is configured to make the smallest zip possible by default. You can change the **comment** which is basically a watermark inside your zip. #### Appearance Systems (1.21.4+)[](https://docs.oraxen.com/plugin-setup/plugin-settings#appearance-systems-1214) The `appearance` section controls how item textures are applied. **Multiple systems can be enabled simultaneously** for maximum compatibility: | Setting | Pack Output | Item Component | Description | | --- | --- | --- | --- | | `item_properties` | `assets/oraxen/items/.json` | `item_model` component | **Default.** Uses item model definitions with Oraxen ids (`oraxen:`). | | `model_data_ids` | `assets/minecraft/items/.json` | `custom_model_data.strings[0]` | Uses `minecraft:select` dispatcher with string ids (`oraxen:`). | | `model_data_float` | `assets/minecraft/items/.json` | `custom_model_data.floats[0]` | Uses `minecraft:range_dispatch` with numeric thresholds. | | `generate_predicates` | `assets/minecraft/models/item/.json` | — | Generates legacy predicate overrides. **Not needed on 1.21.4+.** | **Version behavior:** * **Pre-1.21.4**: Always uses legacy predicate overrides (regardless of settings) * **1.21.4+**: Uses the enabled system(s) **Common configurations:** * `item_properties: true` only — Modern 1.21.4+ setup (default) * `item_properties: true` + `model_data_ids: true` — Hybrid for plugins that read CMD strings * `model_data_float: true` + `generate_predicates: true` — Full legacy compatibility `model_data_ids` and `model_data_float` cannot both be enabled—they write to the same pack file path. If both are enabled, `model_data_ids` takes priority. **generate\_predicates** is only needed if external tools read legacy predicate JSON files. On 1.21.4+, Minecraft uses the new item definition system, so predicates are not required for the game client. See [Item Appearance](https://docs.oraxen.com/creating-content/items/appearance#appearance-systems-1214) for detailed documentation and per-item options. #### Protection[](https://docs.oraxen.com/plugin-setup/plugin-settings#protection) Protection will allow you to prevent players from stealing your textures easily. This won’t make your pack heavier but if you enabled it. You **shall not** try to extract the generated zip, this could damage your disk. ![1 Exabyte (EB) = 1000000000 Gigabyte (GB)](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fsize.1afb5539.png&w=1920&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) ![Your operating system should prevent you from extracting in order to preserve your disk integrity](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fextraction.e5369511.png&w=2048&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) ### Import[](https://docs.oraxen.com/plugin-setup/plugin-settings#import) The `import` section controls how Oraxen merges external resource packs and handles duplicate assets. `Pack: import: merge_duplicate_fonts: true # Merge duplicate font files (e.g., default.json) merge_duplicates: true # Enable general duplicate handling retain_custom_model_data: true # Preserve CustomModelData from imported packs merge_item_base_models: false # Merge base model JSONs (paper.json, etc.)` #### Import Settings Explained[](https://docs.oraxen.com/plugin-setup/plugin-settings#import-settings-explained) | Setting | Default | Description | | --- | --- | --- | | `merge_duplicate_fonts` | `true` | Merges duplicate font files (most commonly `default.json`) into a single file. Original files are excluded from the final pack in favor of the merged version. | | `merge_duplicates` | `true` | Enables Oraxen’s duplicate asset handler. When multiple packs contain the same asset, Oraxen merges them intelligently. | | `retain_custom_model_data` | `true` | When importing external packs, preserves their original `custom_model_data` values. **Warning:** May override your OraxenItems if they use the same CMD values. Set to `false` to let Oraxen reassign values automatically. | | `merge_item_base_models` | `false` | Attempts to merge base model JSON files (e.g., `paper.json`, `diamond_sword.json`) from imported packs. Less reliable than font merging but useful for complex pack combinations. CustomModelData conflicts may still occur regardless of this setting. | #### When to Use These Settings[](https://docs.oraxen.com/plugin-setup/plugin-settings#when-to-use-these-settings) **`retain_custom_model_data: true`** - Use when: * You need imported items to keep their exact CMD values for compatibility with another plugin * You’re importing a vendor pack that requires specific CMD mappings **`retain_custom_model_data: false`** - Use when: * You want Oraxen to automatically handle all CMD assignments * You’re experiencing CMD conflicts between imported and Oraxen items **`merge_item_base_models: true`** - Use when: * Importing multiple packs that modify the same vanilla items * You need predicates from external packs to coexist with Oraxen’s ### Upload[](https://docs.oraxen.com/plugin-setup/plugin-settings#upload) `enabled: true type: polymath #transfer.sh or polymath polymath: server: atlas.oraxen.com # you can also host your own polymath instance` Oraxen integrates with Polymath (a custom web server written in Python especially to be compatible). You can download the source code [here](https://github.com/Th0rgal/Polymath/)   and host it yourself or use the provided instance (atlas). You can also integrate with [your own custom hosting service](https://docs.oraxen.com/developers/custom-hosting-service) . ### Dispatch[](https://docs.oraxen.com/plugin-setup/plugin-settings#dispatch) This section allows you to easily perform actions depending on the resource pack status of your players. You can send message (through a KICK, the chat, an actionbar or a title) and specify a delay and a period (between the different messages if you are using an actionbar or a title). #### Resource Pack Layering (1.20.3+)[](https://docs.oraxen.com/plugin-setup/plugin-settings#resource-pack-layering-1203) `Pack: dispatch: layer: "" # Set to any value (e.g., "bungee") for layering, or empty for replacement` The `layer` option controls resource pack layering on Minecraft 1.20.3+ servers: **Empty string `""` (default):** Traditional behavior * Uses `setResourcePack()` which **replaces** any existing packs * Best for standalone servers * Players only see Oraxen’s pack **Non-empty value (e.g., `"bungee"`, `"proxy"`, `"layer"`):** Layering mode * Uses `addResourcePack()` which **layers** packs together * Preserves resource packs sent by BungeeCord/Velocity proxies * Old Oraxen packs are automatically removed before adding new ones * Multiple packs can coexist * Requires Minecraft 1.20.3+ clients **Use layering when:** * Running on a BungeeCord/Velocity network with proxy-distributed packs * Need Oraxen to coexist with other pack-sending plugins * Want players to use multiple resource packs simultaneously **Use replacement (empty string) when:** * Running a standalone server * Oraxen is the only pack source * Need maximum compatibility with older clients #### Player Protection During Loading[](https://docs.oraxen.com/plugin-setup/plugin-settings#player-protection-during-loading) Oraxen can protect players while they’re downloading and loading the resource pack. This prevents them from being killed or moving into danger while their screen may be frozen or they can’t see properly. `Pack: dispatch: disable_movement_on_load: true # Freeze players during pack loading disable_damage_on_load: true # Make players invulnerable during pack loading` | Setting | Default | Description | | --- | --- | --- | | `disable_movement_on_load` | `true` | Prevents player movement from when they accept the pack until it finishes loading | | `disable_damage_on_load` | `true` | Prevents players from taking any damage while the pack is loading | Both protections are automatically removed once the pack successfully loads, is declined, or fails to download. Players are also removed from the protected state if they disconnect. #### Status Actions[](https://docs.oraxen.com/plugin-setup/plugin-settings#status-actions) Oraxen allows you to trigger actions based on the resource pack status reported by each player’s client. **Available Statuses:** | Status | Minecraft Version | Description | | --- | --- | --- | | `loaded` | All versions | Pack successfully loaded and applied | | `accepted` | All versions | Player clicked “Yes” on the pack prompt | | `denied` | All versions | Player clicked “No” on the pack prompt | | `failed_download` | All versions | Download failed (network error, timeout, etc.) | | `downloaded` | 1.20.3+ only | Pack downloaded but not yet applied | | `failed_reload` | 1.20.3+ only | Reloading the pack failed | | `invalid_url` | 1.20.3+ only | Pack URL was invalid or unreachable | | `discarded` | 1.20.3+ only | Pack was discarded by the client | `receive: enabled: true loaded: actions: message: enabled: true # KICK / CHAT / ACTION_BAR / TITLE type: ACTION_BAR # Delay before the first message to appear, this is in seconds delay: 0 # You only need a period if you send multiple messages of type ACTION_BAR or TITLE period: -1 # Click and Hover elements are only available by using the CHAT type messages: - "ResourcePack successfully loaded!" # If you need to send commands commands: console: [] player: [] opped_player: [] accepted: actions: message: enabled: true # KICK / CHAT / ACTION_BAR / TITLE type: TITLE # Delay before the first message to appear, this is in seconds delay: 0 # You only need a period if you send multiple messages of type ACTION_BAR or TITLE period: 3 # Click and Hover elements are only available by using the CHAT type messages: - "ResourcePack accepted!" - "Thank you" # If you need to send commands commands: console: [] player: [] opped_player: [] denied: actions: message: enabled: true # KICK / CHAT / ACTION_BAR / TITLE type: CHAT # Delay before the first message to appear, this is in seconds delay: 0 # You can put any value here because this is a CHAT message period: -1 # Click and Hover elements are only available by using the CHAT type messages: - "You refused the ResourcePack, but you need it in order to see the new items. Please Display more informations\">CLICK HERE or type /o pack" # If you need to send commands commands: console: [] player: [] opped_player: [] failed_download: actions: message: enabled: true # KICK / CHAT / ACTION_BAR / TITLE type: CHAT # Delay before the first message to appear, this is in seconds delay: 0 # You can put any value here because this is a CHAT message period: -1 # Click and Hover elements are only available by using the CHAT type messages: - "You failed to download the ResourcePack, but you need it in order to see the new items. Please /!\\ loading the resourcepack from the game can cause lags\">CLICK HERE to retry or type /o pack and download it from the internet" # If you need to send commands commands: console: [] player: [] opped_player: [] # Minecraft 1.20.3+ Additional Statuses # These statuses are only available on Minecraft 1.20.3 and above downloaded: # 1.20.3+ only - Pack was downloaded but not yet applied actions: commands: console: [] player: [] opped_player: [] failed_reload: # 1.20.3+ only - Pack reload failed (when changing packs) actions: commands: console: [] player: [] opped_player: [] invalid_url: # 1.20.3+ only - The pack URL was invalid or unreachable actions: commands: console: [] player: [] opped_player: [] discarded: # 1.20.3+ only - Pack was discarded by the client actions: commands: console: [] player: [] opped_player: []` ConfigTools[](https://docs.oraxen.com/plugin-setup/plugin-settings#configtools) -------------------------------------------------------------------------------- `ConfigsTools: enable_configs_updater: true disable_automatic_model_data: false disable_automatic_glyph_code: false error_item: material: PODZOL excludeFromInventory: false # set to true if you don't want to display it inside inventory injectID: false` | Setting | Description | | --- | --- | | `enable_configs_updater` | Automatically update config files when new options are added | | `disable_automatic_model_data` | Prevent Oraxen from auto-assigning `custom_model_data` values | | `disable_automatic_glyph_code` | Prevent Oraxen from auto-assigning unicode characters to glyphs | **Grid Glyphs Warning:** If you enable `disable_automatic_glyph_code`, you **must** manually define the `chars` list for any [grid-based glyphs](https://docs.oraxen.com/creating-content/glyphs-hud#grid-based-glyphs) . Without manual character assignment, grid glyphs will receive new unicode characters on every server restart, breaking saved references. Single-character glyphs will reuse their existing `char` value, but grid glyphs have no such fallback. CustomArmor[](https://docs.oraxen.com/plugin-setup/plugin-settings#customarmor) -------------------------------------------------------------------------------- `CustomArmor: disable_leather_repair: true` This option lets you disable leather being able to repair custom armors. This means the only way to repair a custom armor set is other copies of said armor set. Misc[](https://docs.oraxen.com/plugin-setup/plugin-settings#misc) ------------------------------------------------------------------ ### hide\_scoreboard\_numbers[](https://docs.oraxen.com/plugin-setup/plugin-settings#hide_scoreboard_numbers) This option lets you hide the red scoreboard numbers. `hide_scoreboard_numbers: true` **Before:** ![](https://media.discordapp.net/attachments/758785982005903431/1043486669371887616/image.png) **After:** ![](https://media.discordapp.net/attachments/758785982005903431/1043486615655432193/image.png) ### hide\_scoreboard\_background[](https://docs.oraxen.com/plugin-setup/plugin-settings#hide_scoreboard_background) This option lets you hide the scoreboard background. `hide_scoreboard_background: true` ### hide\_tablist\_background[](https://docs.oraxen.com/plugin-setup/plugin-settings#hide_tablist_background) `hide_tablist_background: true` This option lets you hide the tablist background (1.21+ only). ### reset\_recipes[](https://docs.oraxen.com/plugin-setup/plugin-settings#reset_recipes) `reset_recipes: true` This option can cause bugs with other recipe plugins. If you notice bugs with a recipe plugin when reloading Oraxen, you can disable this option. If you do that, you will have to restart the server to refresh Oraxen recipes. Glyphs[](https://docs.oraxen.com/plugin-setup/plugin-settings#glyphs) ---------------------------------------------------------------------- `Glyphs: glyph_handler: vanilla # or nms - vanilla is recommended emoji_list_permission_only: false # Filter emoji list by permissions unicode_completions: true # Enable tab-completion for unicode characters chat_hover_text: true # Show glyph name on hover in chat` | Setting | Default | Description | | --- | --- | --- | | `glyph_handler` | `vanilla` | Handler for glyph rendering (`vanilla` recommended, `nms` available) | | `emoji_list_permission_only` | `false` | Controls `/oraxen emojis` output (see below) | | `unicode_completions` | `true` | Enable tab-completion for unicode characters in chat | | `chat_hover_text` | `true` | Show glyph name when hovering over emojis in chat | ### Emoji List Permissions[](https://docs.oraxen.com/plugin-setup/plugin-settings#emoji-list-permissions) The `emoji_list_permission_only` setting controls how the `/oraxen emojis` command displays emojis: * **`false` (default)**: Shows all emojis. Hover text indicates permission status with colors: * Green = Player has permission * Red = No permission * **`true`**: Only shows emojis the player has permission to use Chat[](https://docs.oraxen.com/plugin-setup/plugin-settings#chat) ------------------------------------------------------------------ `Chat: chat_handler: vanilla # or nms` WorldEdit[](https://docs.oraxen.com/plugin-setup/plugin-settings#worldedit) ---------------------------------------------------------------------------- Enable/disable WorldEdit integration for custom blocks. `WorldEdit: noteblock_mechanic: true stringblock_mechanic: true furniture_mechanic: true` ItemUpdater[](https://docs.oraxen.com/plugin-setup/plugin-settings#itemupdater) -------------------------------------------------------------------------------- Control how Oraxen updates existing items when configs change. `ItemUpdater: update_items: true # Auto-update items in inventories update_items_on_reload: true # Update on /o reload override_renamed_items: false # Update even if player renamed the item override_item_lore: true # Override lore changes` FurnitureUpdater[](https://docs.oraxen.com/plugin-setup/plugin-settings#furnitureupdater) ------------------------------------------------------------------------------------------ Control how Oraxen updates placed furniture. `FurnitureUpdater: update_furniture: true update_on_reload: true update_on_load: true experimental_furniture_type_update: false # Update furniture entity type on config change experimental_fix_broken_furniture: false # Attempt to fix broken furniture` CustomBlocks[](https://docs.oraxen.com/plugin-setup/plugin-settings#customblocks) ---------------------------------------------------------------------------------- `CustomBlocks: block_correction: true # Auto-correct block states use_legacy_noteblocks: false # Use old noteblock system (not recommended)` Oraxen Inventory[](https://docs.oraxen.com/plugin-setup/plugin-settings#oraxen-inventory) ------------------------------------------------------------------------------------------ `oraxen_inventory: main_menu_title: "" menu_rows: 6 menu_layout: armors: slot: 1 icon: emerald_chestplate title: "<#362753>" blocks: slot: 2 icon: orax_ore title: "<#EDCDEB>" furniture: slot: 3 icon: chair title: "<#F2F2F2>" flowers: slot: 4 icon: dailily title: "<#bf332c>" hats: slot: 5 icon: crown title: "<#81B125>" items: slot: 6 icon: ruby title: "<#DA2E45>" mystical: slot: 7 icon: legendary_hammer title: "<#9AB2E4>" plants: slot: 8 icon: weed_leaf title: "<#44C886>" skins: slot: 9 icon: wood_sword title: "<#C48E40>" tools: slot: 10 icon: iron_serpe title: "<#FFFFFF>" weapons: slot: 11 icon: energy_crystal_sword title: "<#2FB6FF>"` This allows you to configure an icon for every section of the Oraxen inventory. You can use Oraxen ids or Minecraft materials. Last updated on January 3, 2026 [Understanding the Basics](https://docs.oraxen.com/plugin-setup/understanding-the-basics "Understanding the Basics") [Pack Hosting](https://docs.oraxen.com/plugin-setup/pack-hosting "Pack Hosting") --- # Resource Pack Merging Guide | Oraxen Docs [Skip to Content](https://docs.oraxen.com/plugin-setup/pack-merging#nextra-skip-nav) [Plugin Setup](https://docs.oraxen.com/plugin-setup/understanding-the-basics "Plugin Setup") Pack Merging Copy page Resource Pack Merging Guide =========================== Oraxen provides a powerful system to merge multiple resource packs into a single cohesive pack. You can merge packs using two methods. **ZIP file uploads** or **direct folder structure**. Both methods are processed automatically during pack generation. Overview[](https://docs.oraxen.com/plugin-setup/pack-merging#overview) ----------------------------------------------------------------------- When Oraxen generates the resource pack, it merges files from multiple sources in a specific order. 1. **Default Oraxen assets** (built-in textures, models, fonts, etc.) 2. **Direct folder structure** (`Oraxen/pack/assets/`, `Oraxen/pack/textures/`, etc.) 3. **Uploaded ZIP packs** (`Oraxen/pack/uploads/`) This allows you to. * Add custom textures and models * Override default behavior * Combine multiple community packs * Manage priorities easily ZIP Upload System[](https://docs.oraxen.com/plugin-setup/pack-merging#zip-upload-system) ----------------------------------------------------------------------------------------- ### Quick Start[](https://docs.oraxen.com/plugin-setup/pack-merging#quick-start) 1. Place your resource pack ZIP files in **`Oraxen/pack/uploads/`** 2. Reload or restart the server 3. Files are automatically merged into the final pack ### Directory Structure[](https://docs.oraxen.com/plugin-setup/pack-merging#directory-structure) `plugins/Oraxen/ ├── pack/ │ ├── uploads/ │ │ ├── 01_base_textures.zip ← Processed first │ │ ├── 02_custom_models.zip ← Processed second │ │ └── 99_overlay_pack.zip ← Processed last (highest priority) │ ├── assets/ │ ├── textures/ │ ├── models/ │ ├── sounds/ │ └── pack.zip ← Final merged pack` ### Priority System[](https://docs.oraxen.com/plugin-setup/pack-merging#priority-system) ZIP files are processed **alphabetically by filename**. The last file processed wins in case of conflicts. **Example** `uploads/ ├── 0_base_pack.zip (contains: texture.png, model.json) ├── 1_custom_pack.zip (contains: texture.png, new_item.json) └── 2_override_pack.zip (contains: texture.png)` **Processing Order & Result** 1. `0_base_pack.zip` → texture.png added 2. `1_custom_pack.zip` → texture.png **overrides** v1, new\_item.json added 3. `2_override_pack.zip` → texture.png **overrides** v2 **Final Pack Contains** * `texture.png` from `2_override_pack.zip` * `model.json` from `0_base_pack.zip` * `new_item.json` from `1_custom_pack.zip` ### Console Outputs[](https://docs.oraxen.com/plugin-setup/pack-merging#console-outputs) #### Normal Merge (No Conflicts)[](https://docs.oraxen.com/plugin-setup/pack-merging#normal-merge-no-conflicts) `[14:32:35 INFO] Oraxen | Processing pack | base_textures.zip [14:32:35 INFO] Oraxen | Added 45 files from base_textures.zip` #### With File Overrides[](https://docs.oraxen.com/plugin-setup/pack-merging#with-file-overrides) `[14:32:36 INFO] Oraxen | Processing pack | custom_overlay.zip [14:32:36 WARN] Oraxen | custom_overlay.zip will override existing file assets/minecraft/textures/gui/window.png from base_textures.zip [14:32:36 INFO] Oraxen | Added 12 new files, 8 overrides from custom_overlay.zip` #### Final Summary[](https://docs.oraxen.com/plugin-setup/pack-merging#final-summary) `[14:32:37 INFO] Oraxen | Merged 156 files from 3 uploaded pack(s)` Direct Folder Structure[](https://docs.oraxen.com/plugin-setup/pack-merging#direct-folder-structure) ----------------------------------------------------------------------------------------------------- ### Quick Start[](https://docs.oraxen.com/plugin-setup/pack-merging#quick-start-1) 1. Place your resource pack files directly in **`Oraxen/pack/assets/`** or **`Oraxen/pack/`** folders 2. Reload or restart the server 3. Files are automatically merged into the final pack ### Benefits (compared to ZIP Uploads)[](https://docs.oraxen.com/plugin-setup/pack-merging#benefits-compared-to-zip-uploads) * Persistent customizations * Development and iteration * Avoiding repeated uploads ### Directory Structure[](https://docs.oraxen.com/plugin-setup/pack-merging#directory-structure-1) `plugins/Oraxen/ └── pack/ ├── assets/ ← Direct resource pack files │ ├── minecraft/ │ │ ├── textures/ │ │ ├── models/ │ │ ├── lang/ │ │ └── sounds/ │ └── [custom_namespace]/ ├── textures/ ← Alternative: flat structure ├── models/ ├── sounds/ ├── lang/ ├── pack.mcmeta ├── pack.png └── uploads/ ← ZIP files go here` ### Priority System[](https://docs.oraxen.com/plugin-setup/pack-merging#priority-system-1) Direct folder files override defaults, but can be overridden by uploaded ZIPs. Files in the same source are processed in folder structure order. **Example** `Defaults (Minecraft) ├── assets/minecraft/textures/block/dirt.png ├── assets/minecraft/models/block/stone.json └── assets/minecraft/textures/item/sword.png Direct Folders (pack/) ├── assets/minecraft/textures/block/dirt.png ← Different version └── assets/minecraft/textures/item/axe.png ← New file Uploaded ZIPs (pack/uploads/) ├── 01_base_pack.zip (contains: sword.png) └── 02_override_pack.zip (contains: dirt.png)` **Processing Order & Result** 1. Oraxen defaults → dirt.png, stone.json, sword.png loaded 2. Direct folders → dirt.png **overrides** default, axe.png added 3. `01_base_pack.zip` → sword.png **overrides** default version 4. `02_override_pack.zip` → dirt.png **overrides** direct folder version **Final Pack Contains** * `dirt.png` from `02_override_pack.zip` * `stone.json` from Oraxen defaults * `sword.png` from `01_base_pack.zip` * `axe.png` from direct folder Priority[](https://docs.oraxen.com/plugin-setup/pack-merging#priority) ----------------------------------------------------------------------- `1. Oraxen Default Assets ↓ (can be overridden by) 2. pack/assets/ (direct folder) pack/textures/ (alternative structure) pack/models/ pack/sounds/ etc. ↓ (can be overridden by) 3. pack/uploads/01_*.zip (alphabetically first) pack/uploads/02_*.zip ... pack/uploads/99_*.zip (alphabetically last = highest priority)` ### How Conflicts Are Resolved[](https://docs.oraxen.com/plugin-setup/pack-merging#how-conflicts-are-resolved) When the same file path appears in multiple sources. * **Direct folders override defaults** * **ZIP packs override direct folders** * **Later ZIP files (alphabetically) override earlier ones** **Example** * `Oraxen/pack/assets/minecraft/textures/block/dirt.png` (direct) * `Oraxen/pack/uploads/custom_pack.zip` (contains `assets/minecraft/textures/block/dirt.png`) **Result |** File from `custom_pack.zip` is used (ZIP has higher priority) Last updated on January 3, 2026 [Pack Hosting](https://docs.oraxen.com/plugin-setup/pack-hosting "Pack Hosting") [Commands](https://docs.oraxen.com/usage/commands "Commands") --- # sound.yml Configuration | Oraxen Docs [Skip to Content](https://docs.oraxen.com/configuration/sound-yml#nextra-skip-nav) Configuration Referencesound.yml Copy page sound.yml Configuration ======================= Learn how to register custom sounds, configure jukebox songs, and override vanilla sounds in Oraxen. Overview[](https://docs.oraxen.com/configuration/sound-yml#overview) --------------------------------------------------------------------- The `sound.yml` file allows you to: * Register custom sound files (.ogg format) * Configure jukebox songs with metadata * Replace vanilla Minecraft sounds * Define sound categories and subtitles * Add custom block break/place sounds **Location:** `plugins/Oraxen/sound.yml` File Structure[](https://docs.oraxen.com/configuration/sound-yml#file-structure) --------------------------------------------------------------------------------- `settings: automatically_generate: true # Auto-generates sounds.json for the resource pack sounds: sound_id: category: records # Sound category sound: filename.ogg # Sound file (extension optional) stream: true # Whether to stream (recommended for music) subtitle: "Subtitle Text" # Subtitle shown in game replace: false # Whether to replace vanilla sound jukebox_song: # (Optional) Jukebox song metadata description: "Song description" length_in_seconds: 120 comparator_output: 15` Basic Sound Registration[](https://docs.oraxen.com/configuration/sound-yml#basic-sound-registration) ----------------------------------------------------------------------------------------------------- ### Adding a Custom Sound[](https://docs.oraxen.com/configuration/sound-yml#adding-a-custom-sound) 1. **Place your .ogg file** in `plugins/Oraxen/pack/sounds/` (create subdirectories if needed) 2. **Register in sound.yml:** `sounds: my_custom_sound: category: block sound: custom/my_sound.ogg subtitle: "Custom Sound Effect"` 3. **Reload Oraxen:** `/oraxen reload all` 4. **Use in game:** Play with `/playsound oraxen:my_custom_sound` ### Sound Categories[](https://docs.oraxen.com/configuration/sound-yml#sound-categories) Valid categories: * `master` - Master volume slider * `music` - Music & Jukebox volume * `record` - Alias for music (use for jukebox songs) * `weather` - Weather sounds * `block` - Block break/place sounds * `hostile` - Hostile mob sounds * `neutral` - Neutral mob sounds * `player` - Player sounds (footsteps, hurt, etc.) * `ambient` - Ambient/environment sounds * `voice` - Voice/speech sounds Jukebox Songs[](https://docs.oraxen.com/configuration/sound-yml#jukebox-songs) ------------------------------------------------------------------------------- Create music discs that play custom songs in jukeboxes. ### Configuration[](https://docs.oraxen.com/configuration/sound-yml#configuration) `sounds: welcome: category: records sound: welcome.ogg stream: true # Always use streaming for music subtitle: "Welcome Song" jukebox_song: description: - text: "Oraxen - Welcome" color: "gray" italic: false length_in_seconds: 180 comparator_output: 15` ### Jukebox Song Properties[](https://docs.oraxen.com/configuration/sound-yml#jukebox-song-properties) **`description`** - Song title shown in item tooltip: `jukebox_song: description: - text: "Artist - Song Name" color: "aqua" italic: true - text: "Album Name" color: "gray"` **`length_in_seconds`** - Duration of the song (for stopping playback) **`comparator_output`** - Redstone comparator strength (1-15) when playing ### Creating the Music Disc Item[](https://docs.oraxen.com/configuration/sound-yml#creating-the-music-disc-item) In your item configuration (e.g., `items/items.yml`): `welcome_disk: displayname: "Welcome Disk" material: MUSIC_DISC_13 # Or any music disc material ItemFlags: - HIDE_ADDITIONAL_TOOLTIP Components: jukebox_playable: show_in_tooltip: true song_key: "oraxen:welcome" # Must match sound ID Pack: generate_model: true parent_model: "item/handheld" textures: - default/welcome_disk.png` Replacing Vanilla Sounds[](https://docs.oraxen.com/configuration/sound-yml#replacing-vanilla-sounds) ----------------------------------------------------------------------------------------------------- Override Minecraft’s default sounds with custom ones. ### Example: Custom Block Break Sound[](https://docs.oraxen.com/configuration/sound-yml#example-custom-block-break-sound) `sounds: custom_stone_break: category: block sound: blocks/custom_stone.ogg replace: true subtitle: "Block breaks"` To apply this to a custom block, reference it in the block’s configuration. ### Common Vanilla Sound Replacements[](https://docs.oraxen.com/configuration/sound-yml#common-vanilla-sound-replacements) `sounds: # Custom wood sounds wood_break: category: block sound: blocks/wood/break.ogg replace: true subtitle: "Block breaks" wood_step: category: block sound: blocks/wood/step.ogg replace: true wood_place: category: block sound: blocks/wood/place.ogg replace: true subtitle: "Block placed" # Custom stone sounds stone_break: category: block sound: blocks/stone/break.ogg replace: true subtitle: "Block breaks" stone_step: category: block sound: blocks/stone/step.ogg replace: true` Block Sound Integration[](https://docs.oraxen.com/configuration/sound-yml#block-sound-integration) --------------------------------------------------------------------------------------------------- ### Applying Sounds to Custom Blocks[](https://docs.oraxen.com/configuration/sound-yml#applying-sounds-to-custom-blocks) In your block configuration: `my_custom_block: # ... other block properties ... sounds: break: oraxen:custom_stone_break place: oraxen:wood_place step: oraxen:wood_step hit: oraxen:custom_stone_break fall: oraxen:wood_step` ### Required Sounds Pattern[](https://docs.oraxen.com/configuration/sound-yml#required-sounds-pattern) For blocks that should use vanilla sound groups (wood, stone, etc.): `sounds: required.wood.break: category: block sound: block/wood/break.ogg replace: true required.wood.step: category: block sound: block/wood/step.ogg replace: true required.wood.place: category: block sound: block/wood/place.ogg replace: true` The `required.` prefix tells Oraxen these are essential sound mappings. Streaming vs Non-Streaming[](https://docs.oraxen.com/configuration/sound-yml#streaming-vs-non-streaming) --------------------------------------------------------------------------------------------------------- ### When to Use Streaming[](https://docs.oraxen.com/configuration/sound-yml#when-to-use-streaming) **Use `stream: true` for:** * Music discs (jukebox songs) * Long ambient sounds (>10 seconds) * Background music * Narration/dialogue **Use `stream: false` (or omit) for:** * Short sound effects (<5 seconds) * Block break/place sounds * UI sounds * Frequently played sounds ### Why It Matters[](https://docs.oraxen.com/configuration/sound-yml#why-it-matters) * **Non-streaming:** Loads entire sound into memory (fast playback, higher memory usage) * **Streaming:** Loads sound in chunks (lower memory, slight delay on playback start) Sound File Requirements[](https://docs.oraxen.com/configuration/sound-yml#sound-file-requirements) --------------------------------------------------------------------------------------------------- ### Format Requirements[](https://docs.oraxen.com/configuration/sound-yml#format-requirements) * **Format:** OGG Vorbis (`.ogg`) * **Channels:** Mono (stereo is converted automatically but wastes space) * **Sample Rate:** 44.1kHz or 48kHz recommended * **Bit Rate:** 128-192 kbps for music, 64-96 kbps for effects ### File Placement[](https://docs.oraxen.com/configuration/sound-yml#file-placement) Place sound files in `plugins/Oraxen/pack/sounds/`: `pack/ └── sounds/ ├── music/ │ ├── welcome.ogg │ └── boss_theme.ogg ├── blocks/ │ ├── wood/ │ │ ├── break.ogg │ │ ├── step.ogg │ │ └── place.ogg │ └── stone/ │ └── break.ogg └── custom/ └── my_sound.ogg` ### Converting Audio Files[](https://docs.oraxen.com/configuration/sound-yml#converting-audio-files) Use FFmpeg to convert audio to OGG: `# Convert MP3 to OGG (mono, 128kbps) ffmpeg -i input.mp3 -ac 1 -b:a 128k output.ogg # Convert WAV to OGG (mono, 96kbps for sound effects) ffmpeg -i input.wav -ac 1 -b:a 96k output.ogg` Complete Example[](https://docs.oraxen.com/configuration/sound-yml#complete-example) ------------------------------------------------------------------------------------- Here’s a full sound.yml with various sound types: `settings: automatically_generate: true sounds: # Music disc epic_theme: category: records sound: music/epic_theme.ogg stream: true subtitle: "Epic Theme Playing" jukebox_song: description: - text: "Epic Theme" color: "gold" italic: false - text: "By Composer Name" color: "gray" length_in_seconds: 240 comparator_output: 15 # Block sounds crystal_break: category: block sound: blocks/crystal/break.ogg subtitle: "Crystal shatters" crystal_step: category: block sound: blocks/crystal/step.ogg # Ambient sound magical_hum: category: ambient sound: ambient/magical_hum.ogg stream: true subtitle: "Magical humming" # UI sound menu_click: category: master sound: ui/menu_click.ogg # Weapon sound sword_swing: category: player sound: weapons/sword_swing.ogg subtitle: "Swoosh"` Using Sounds in Items[](https://docs.oraxen.com/configuration/sound-yml#using-sounds-in-items) ----------------------------------------------------------------------------------------------- ### Play Sound on Item Use[](https://docs.oraxen.com/configuration/sound-yml#play-sound-on-item-use) In item configuration: `magic_wand: # ... item properties ... Mechanics: custom: one_usage: event: CLICK:right:all actions: sound: name: oraxen:magical_hum volume: 1.0 pitch: 1.0` ### Play Sound on Block Break[](https://docs.oraxen.com/configuration/sound-yml#play-sound-on-block-break) `my_custom_block: # ... block properties ... break_sounds: - oraxen:crystal_break` Troubleshooting[](https://docs.oraxen.com/configuration/sound-yml#troubleshooting) ----------------------------------------------------------------------------------- ### Sound Not Playing[](https://docs.oraxen.com/configuration/sound-yml#sound-not-playing) 1. **Check file format:** Must be `.ogg` (OGG Vorbis) 2. **Verify file path:** Check `plugins/Oraxen/pack/sounds/` 3. **Reload Oraxen:** `/oraxen reload all` 4. **Resend pack:** `/oraxen pack send @a` 5. **Check client logs:** F3 + T to reload resource pack ### Sound Plays But No Subtitle[](https://docs.oraxen.com/configuration/sound-yml#sound-plays-but-no-subtitle) Ensure subtitle is defined and in-game subtitles are enabled (Options > Accessibility > Subtitles) ### Jukebox Song Not Playing[](https://docs.oraxen.com/configuration/sound-yml#jukebox-song-not-playing) 1. Verify `song_key` matches sound ID: `oraxen:` 2. Ensure `stream: true` is set 3. Check `length_in_seconds` is accurate 4. Confirm item has `jukebox_playable` component ### Sound File Too Large[](https://docs.oraxen.com/configuration/sound-yml#sound-file-too-large) **For music:** * Reduce bitrate: 128kbps is usually sufficient * Convert stereo to mono (halves file size) * Use streaming (`stream: true`) **For effects:** * Use 64-96kbps for short sounds * Ensure mono channel * Trim silence from start/end ### Sound Plays at Wrong Volume[](https://docs.oraxen.com/configuration/sound-yml#sound-plays-at-wrong-volume) Adjust in-game sound sliders: * Check the sound’s `category` matches intended slider * `master` - Master Volume * `music` - Music/Jukebox Volume * `block` - Blocks Volume * `ambient` - Ambient/Environment Volume Advanced: Sound Events[](https://docs.oraxen.com/configuration/sound-yml#advanced-sound-events) ------------------------------------------------------------------------------------------------ ### Custom Sound Events[](https://docs.oraxen.com/configuration/sound-yml#custom-sound-events) You can trigger sounds via plugin events: `Mechanics: custom: on_kill: event: KILL:player actions: sound: name: oraxen:victory_fanfare volume: 0.8 pitch: 1.2` ### Multiple Sounds[](https://docs.oraxen.com/configuration/sound-yml#multiple-sounds) Play random sounds from a pool: `sounds: footstep_1: category: player sound: footsteps/step1.ogg footstep_2: category: player sound: footsteps/step2.ogg footstep_3: category: player sound: footsteps/step3.ogg` Then reference randomly in mechanics or via plugin code. See Also[](https://docs.oraxen.com/configuration/sound-yml#see-also) --------------------------------------------------------------------- * [Item Abilities](https://docs.oraxen.com/creating-content/items/abilities/) - Use sounds in item mechanics * [Custom Blocks](https://docs.oraxen.com/creating-content/blocks/) - Add sounds to blocks * [Branding Customization](https://docs.oraxen.com/configuration/branding-customization) - Customize the welcome sound * [MiniMessage Format](https://docs.advntr.dev/minimessage/)   - Jukebox song description formatting Last updated on January 3, 2026 [Plugin API](https://docs.oraxen.com/creating-content/text-effects/api "Plugin API") [Branding & Customization](https://docs.oraxen.com/configuration/branding-customization "Branding & Customization") --- # Crucible | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/crucible#nextra-skip-nav) [Compatibility](https://docs.oraxen.com/compatibility/packlayer "Compatibility") MythicCrucible Copy page Crucible ======== The compatibility with Crucible allows you to import items created with MythicMobs & Crucible and use them as a base for your Oraxen items (you will keep everything configured with Crucible and add your own mechanics, textures, 3d models, etc). To do this, simply add a crucible section and specify the itemID in Oraxen `example_crucible: displayname: "Test" crucible: id: my_crucible_itemid` Last updated on January 3, 2026 [PackLayer - Proxy Optimization](https://docs.oraxen.com/compatibility/packlayer "PackLayer - Proxy Optimization") [MythicHUD](https://docs.oraxen.com/compatibility/mythichud "MythicHUD") --- # Recipes | Oraxen Docs [Skip to Content](https://docs.oraxen.com/usage/recipes#nextra-skip-nav) [Commands & Recipes](https://docs.oraxen.com/usage/commands "Commands & Recipes") Recipes Copy page Recipes ======= Recipes are ways that already exist in minecraft that allow players to create items from others. The craft table allows you to craft swords, armors and more, the crafts of these items are called ShapedRecipes because they are recipes with a particular shape. There are also ShapelessRecipes (you just have to put the ingredients in any order to get your result) or FurnaceRecipes (to obtain the item by burning the ingredient in a furnace). The objective of oraxen is to be able to support them all but for the moment only shaped recipes are supported. How to create a recipe?[](https://docs.oraxen.com/usage/recipes#how-to-create-a-recipe) ---------------------------------------------------------------------------------------- You can see the list of commands and permissions required in the [wiki page](https://docs.oraxen.com/usage/commands#create-recipes) . ### First step: open a builder inventory[](https://docs.oraxen.com/usage/recipes#first-step-open-a-builder-inventory) Start by typing **/o recipe builder SHAPED**, it will open you a crafting table: Then place the ingredients in the order you want in the left part. Place the wanted result in the slot on the right. ### Damn, I’m missing an ingredient, can I close the inventory?[](https://docs.oraxen.com/usage/recipes#damn-im-missing-an-ingredient-can-i-close-the-inventory) Absolutely, you can close the inventory at any time, to reopen it simply type **/o recipes open** (you will find the items you left in it). ### I finished my craft, how to load it?[](https://docs.oraxen.com/usage/recipes#i-finished-my-craft-how-to-load-it) You must register your craft. To do this, you must choose a name, then type the command **/o recipes save your\_name**. Unfortunately Oraxen does not yet know how to load these crafts in game, it will be necessary to wait for the server to restart before using them. You can also use **/o recipes save ** so that crafting your item with the name requires the permission How to edit my recipe?[](https://docs.oraxen.com/usage/recipes#how-to-edit-my-recipe) -------------------------------------------------------------------------------------- You can simply edit the configuration with the name of your craft type (shaped.yml for example), then find your craft and change the ingredients, result or permission. How to disable vanilla or existing recipes?[](https://docs.oraxen.com/usage/recipes#how-to-disable-vanilla-or-existing-recipes) -------------------------------------------------------------------------------------------------------------------------------- You can disable any vanilla Minecraft recipe or existing recipe by adding its namespaced key to the `disabled.yml` file in your recipes folder. This file is automatically created when Oraxen first loads. Simply add the recipe keys you want to disable: `disabled: - minecraft:diamond_sword # Same namespcaed key that shows up in e.g. the /recipes command - minecraft:iron_pickaxe - oraxen:custom_recipe` The server will need to restart for changes to take effect. Invalid recipe keys or recipes that don’t exist will show a warning in the console. Last updated on January 3, 2026 [Default items](https://docs.oraxen.com/usage/default-items "Default items") [PackLayer - Proxy Optimization](https://docs.oraxen.com/compatibility/packlayer "PackLayer - Proxy Optimization") --- # ModelEngine | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/modelengine-custom-mobs#nextra-skip-nav) [Compatibility](https://docs.oraxen.com/compatibility/packlayer "Compatibility") ModelEngine - custom mobs Copy page ModelEngine =========== Using ModelEngine with Oraxen is very simple as long as you use different types of items. As far as I know, ModelEngine uses leather horse armor. If you don’t, compatibility should be simple. How to merge?[](https://docs.oraxen.com/compatibility/modelengine-custom-mobs#how-to-merge) -------------------------------------------------------------------------------------------- Go to the ModelEngine folder. It should look like that: ![content of ModelEngine folder by @Thew](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fimage%20(7).517f4ab8.png&w=3840&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) Open the `resource pack` folder: ![content of resource pack folder by @Thew](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fimage%20(4).5290afd9.png&w=3840&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) Copy the assets folder (the folder, not its content) inside `Oraxen/pack`, this should look like this: ![Oraxen/pack folder by @Thew](https://docs.oraxen.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fimage%20(6).f80f5ce6.png&w=3840&q=75&dpl=dpl_7PAZg9DYpvBH7uBe5EGzyf8bGAs7) Last updated on January 3, 2026 [MMoItems](https://docs.oraxen.com/compatibility/mmoitems "MMoItems") [MythicMobs - custom mobs](https://docs.oraxen.com/compatibility/mythicmobs-custom-mobs "MythicMobs - custom mobs") --- # MythicHUD | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/mythichud#nextra-skip-nav) [Compatibility](https://docs.oraxen.com/compatibility/packlayer "Compatibility") MythicHUD Copy page MythicHUD ========= HappyHUD has been rebranded to **MythicHUD** and is now part of the MythicCraft ecosystem. If you’re migrating from HappyHUD, MythicHUD includes automatic migration support. This will detail how to properly make MythicHUD compatible with Oraxen. Setup Steps[](https://docs.oraxen.com/compatibility/mythichud#setup-steps) --------------------------------------------------------------------------- 1. Set `hide_scoreboard_numbers: false` in settings.yml 2. Delete `Oraxen/pack/shaders/core/render_text.vsh` and `render_text.json` if they exist 3. In MythicHUD’s config, enable `copy-resource-pack` and set `path: "Oraxen/pack/assets"` Hiding Scoreboard Numbers[](https://docs.oraxen.com/compatibility/mythichud#hiding-scoreboard-numbers) ------------------------------------------------------------------------------------------------------- If you really want to also hide scoreboard numbers, you can manually merge Oraxen’s shader file into MythicHUD’s in `MythicHUD/pack/minecraft/shaders/core/`. Resources[](https://docs.oraxen.com/compatibility/mythichud#resources) ----------------------------------------------------------------------- * [MythicHUD Documentation](https://mythiccraft.io/)   * [MythicHUD GitLab](https://git.mythiccraft.io/mythiccraft/mythichud)   Last updated on January 17, 2026 [MythicCrucible](https://docs.oraxen.com/compatibility/crucible "MythicCrucible") [MMoItems](https://docs.oraxen.com/compatibility/mmoitems "MMoItems") --- # MMOItems | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/mmoitems#nextra-skip-nav) [Compatibility](https://docs.oraxen.com/compatibility/packlayer "Compatibility") MMoItems Copy page MMOItems ======== The compatibility with MMOItems allows you to import items created with this plugin and use them as a base for your Oraxen items (you will keep everything configured with MmoItems and add your own mechanics, textures, 3d models, etc). To do this, simply add an mmoitem section to your item section in Oraxen `example_mmoitem: displayname: "Test" mmoitem: type: SWORD id: FALCON_BLADE level: 10 # Optional tier: RARE # Optional match_level: true # Optional` Last updated on January 17, 2026 [MythicHUD](https://docs.oraxen.com/compatibility/mythichud "MythicHUD") [ModelEngine - custom mobs](https://docs.oraxen.com/compatibility/modelengine-custom-mobs "ModelEngine - custom mobs") --- # PackLayer - Proxy Resource Pack Optimization | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/packlayer#nextra-skip-nav) CompatibilityPackLayer - Proxy Optimization Copy page PackLayer - Proxy Resource Pack Optimization ============================================ PackLayer is a **Velocity and BungeeCord proxy plugin** that optimizes resource pack distribution on multi-server networks. The Problem[](https://docs.oraxen.com/compatibility/packlayer#the-problem) --------------------------------------------------------------------------- When players switch between backend servers on a proxy network, each server typically sends its own resource pack request. If multiple servers use the **same pack** (like Oraxen’s pack), the client is forced to re-download and re-apply it on every switch — causing: * **Unnecessary delays** when switching servers * **Wasted bandwidth** for both players and servers * **Poor player experience** with loading screens The Solution[](https://docs.oraxen.com/compatibility/packlayer#the-solution) ----------------------------------------------------------------------------- PackLayer intercepts outgoing `ResourcePackSend` packets at the proxy level and **cancels duplicates**. If a player already has a pack with a matching hash, the packet is dropped, making server switching instant. Installation[](https://docs.oraxen.com/compatibility/packlayer#installation) ----------------------------------------------------------------------------- 1. Download the latest `bungee-pack-layer-X.X.X.jar` from [GitHub Releases](https://github.com/oraxen/bungee-pack-layer/releases)   2. Place it in your **proxy’s plugins folder** (Velocity or BungeeCord) 3. Restart your proxy 4. (Optional) Edit the generated `config.yml` to customize behavior **Note:** This is a **proxy plugin**, not a backend server plugin. It goes on Velocity/BungeeCord, not on Paper/Spigot. Configuration[](https://docs.oraxen.com/compatibility/packlayer#configuration) ------------------------------------------------------------------------------- PackLayer generates a `config.yml` in its data folder with sensible defaults: `# 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` Skip Modes Explained[](https://docs.oraxen.com/compatibility/packlayer#skip-modes-explained) --------------------------------------------------------------------------------------------- | Mode | When to Use | | --- | --- | | `HASH_ONLY` | **Default.** Best for most setups. Skips packs with identical SHA-1 hash. | | `URL_ONLY` | Use when different pack versions share the same URL (e.g., self-hosted with static URL). | | `HASH_OR_URL` | Most aggressive. Skips if either hash or URL matches. | | `HASH_AND_URL` | Most conservative. Only skips if both match exactly. | | `ALWAYS_SKIP` | Testing/debugging only. Skips all pack sends. | | `NEVER_SKIP` | Effectively disables PackLayer. | Server Filtering[](https://docs.oraxen.com/compatibility/packlayer#server-filtering) ------------------------------------------------------------------------------------- You can limit PackLayer to specific backend servers: `server-filter: mode: WHITELIST servers: - survival - creative - minigames` Or exclude specific servers: `server-filter: mode: BLACKLIST servers: - auth # Don't apply to auth server` Trusted Domains[](https://docs.oraxen.com/compatibility/packlayer#trusted-domains) ----------------------------------------------------------------------------------- Skip all packs from specific domains without checking hashes: `trusted-domains: - atlas.oraxen.com # Oraxen's default pack host - cdn.myserver.com # Your CDN - "*.example.com" # Wildcard matching` This is useful when you trust the pack source and want to minimize overhead. Commands[](https://docs.oraxen.com/compatibility/packlayer#commands) --------------------------------------------------------------------- All commands require the `packlayer.admin` permission. | Command | Description | | --- | --- | | `/packlayer reload` | Reload configuration | | `/packlayer stats` | Show skip statistics | | `/packlayer clear ` | Clear pack cache for player(s) | | `/packlayer info ` | Show cached pack info for a player | | `/packlayer debug` | Show debug mode status | Best Practices for Oraxen Networks[](https://docs.oraxen.com/compatibility/packlayer#best-practices-for-oraxen-networks) ------------------------------------------------------------------------------------------------------------------------- ### Single Pack Across All Servers[](https://docs.oraxen.com/compatibility/packlayer#single-pack-across-all-servers) If all your backend servers use the same Oraxen resource pack: 1. Install PackLayer on your proxy 2. Use default settings (`skip-mode: HASH_ONLY`) 3. Done! Players will only download the pack once. ### Different Packs Per Server[](https://docs.oraxen.com/compatibility/packlayer#different-packs-per-server) If some servers have different packs: `server-filter: mode: WHITELIST servers: - survival # These servers share the same pack - creative - lobby` Servers not in the list will always send their packs. ### Using Polymath (atlas.oraxen.com)[](https://docs.oraxen.com/compatibility/packlayer#using-polymath-atlasoraxencom) Add Oraxen’s pack host to trusted domains for optimal performance: `trusted-domains: - atlas.oraxen.com` Developer API[](https://docs.oraxen.com/compatibility/packlayer#developer-api) ------------------------------------------------------------------------------- PackLayer provides an event API for other plugins: `// Get the service (Velocity example) PackLayerVelocityPlugin plugin = /* get plugin instance */; PackLayerService service = plugin.getService(); // Register an event handler service.registerEventHandler(event -> { // Called when a pack skip is about to occur if (shouldForceResend(event.getPlayerId())) { event.setCancelled(true); // Force pack to be sent } }); // Manual pack cache control service.clearPlayer(playerId);` Troubleshooting[](https://docs.oraxen.com/compatibility/packlayer#troubleshooting) ----------------------------------------------------------------------------------- ### Pack still being re-sent[](https://docs.oraxen.com/compatibility/packlayer#pack-still-being-re-sent) 1. Check `debug: true` in config to see what’s happening 2. Verify all backend servers use the exact same pack (check SHA-1 hashes) 3. Make sure PackLayer is on the **proxy**, not backend servers ### Players seeing old pack version[](https://docs.oraxen.com/compatibility/packlayer#players-seeing-old-pack-version) Clear their pack cache: `/packlayer clear PlayerName` ### Need to force re-download[](https://docs.oraxen.com/compatibility/packlayer#need-to-force-re-download) Temporarily disable for a player: `/packlayer clear PlayerName` They’ll receive the pack on next server switch. Performance[](https://docs.oraxen.com/compatibility/packlayer#performance) --------------------------------------------------------------------------- PackLayer is designed to be lightweight: * **Zero disk I/O** during normal operation * **Minimal memory** footprint (only stores pack hashes per player) * **No network overhead** (only intercepts packets, doesn’t modify them) Typical impact: **< 1ms latency** per pack check. Compatibility[](https://docs.oraxen.com/compatibility/packlayer#compatibility) ------------------------------------------------------------------------------- * **Velocity:** 3.0.0+ * **BungeeCord:** 1.20+ * **Minecraft:** 1.8 - 1.21.x (all versions supported) PackLayer uses [PacketEvents](https://github.com/retrooper/packetevents)   for packet interception, which provides broad version compatibility. Last updated on January 17, 2026 [Recipes](https://docs.oraxen.com/usage/recipes "Recipes") [MythicCrucible](https://docs.oraxen.com/compatibility/crucible "MythicCrucible") --- # MythicMobs | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/mythicmobs-custom-mobs#nextra-skip-nav) [Compatibility](https://docs.oraxen.com/compatibility/packlayer "Compatibility") MythicMobs - custom mobs Copy page MythicMobs ========== If the plugin does not work with MythicMobs, use version 5.0.2. This feature is provided to you by [yzl210](https://github.com/yzl210)  , don’t hesitate to thank him! How to use an oraxen item for the drops?[](https://docs.oraxen.com/compatibility/mythicmobs-custom-mobs#how-to-use-an-oraxen-item-for-the-drops) ------------------------------------------------------------------------------------------------------------------------------------------------- ### Usage[](https://docs.oraxen.com/compatibility/mythicmobs-custom-mobs#usage) `oraxen [oraxen item name] [amount to drop(number or region)] [chance to drop(0-1)]` ### Example[](https://docs.oraxen.com/compatibility/mythicmobs-custom-mobs#example) `oraxen custom_material 3-4 0.75` This means that it has **75** percent chance to drop **3 to 4 custom\_material** items. How to equip your mob with an oraxen item?[](https://docs.oraxen.com/compatibility/mythicmobs-custom-mobs#how-to-equip-your-mob-with-an-oraxen-item) ----------------------------------------------------------------------------------------------------------------------------------------------------- ### Usage[](https://docs.oraxen.com/compatibility/mythicmobs-custom-mobs#usage-1) `oraxen [slot] [oraxen item(equipment) name]` #### Slots[](https://docs.oraxen.com/compatibility/mythicmobs-custom-mobs#slots) * 0, mainhand, weapon * 1, boots, shoes * 2, leggings, pants * 3, chestpiece, chestplate, body * 4, helmet, helm * 5, shield _5 is OffHand, but you can’t put **offhand**, because MythicMobs’s Author didn’t put the alias._ ### Example[](https://docs.oraxen.com/compatibility/mythicmobs-custom-mobs#example-1) `oraxen mainhand custom_sword` It means that you put a **custom\_sword** item in **MainHand**. `oraxen 3 custom_chestplate` It means that you put a **custom\_chestplate** item in **ChestPlate** slot (as an armor) Last updated on January 17, 2026 [ModelEngine - custom mobs](https://docs.oraxen.com/compatibility/modelengine-custom-mobs "ModelEngine - custom mobs") [Skript](https://docs.oraxen.com/compatibility/skript "Skript") --- # Iris World Generator | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/world-generators/iris-world-generator#nextra-skip-nav) [Compatibility](https://docs.oraxen.com/compatibility/packlayer "Compatibility") [World Generators](https://docs.oraxen.com/compatibility/world-generators "World Generators") Iris World Generator Copy page Iris World Generator ==================== Iris World Generator allows you to easily generate beautiful worlds with custom terrain, biomes, and structures. It features **first-class Oraxen integration**, allowing you to use custom blocks and items from Oraxen directly in your world generation configurations. Oraxen automatically registers as an external data provider with Iris. Just install both plugins and the integration works out of the box - no additional setup required. **Spigot Link:** [Iris World Generator](https://www.spigotmc.org/resources/iris-world-gen-the-dimension-engine.84586/)   Using Oraxen blocks in Iris[](https://docs.oraxen.com/compatibility/world-generators/iris-world-generator#using-oraxen-blocks-in-iris) --------------------------------------------------------------------------------------------------------------------------------------- You can reference any Oraxen custom block using the `oraxen:` prefix followed by your block’s ID. Iris will automatically resolve these references through Oraxen’s data provider. `oraxen:your_block_id` How to create custom ores[](https://docs.oraxen.com/compatibility/world-generators/iris-world-generator#how-to-create-custom-ores) ----------------------------------------------------------------------------------------------------------------------------------- In this example we assume that you have added a block (an amethyst ore for example) following [this example](https://docs.oraxen.com/creating-content/blocks/noteblock#ores) to your oraxen configuration. ### 1) Locate your dimension configuration[](https://docs.oraxen.com/compatibility/world-generators/iris-world-generator#1-locate-your-dimension-configuration) Go to `Iris/pack/YOUR_PACK_NAME/dimensions/YOUR_DIMENSION_NAME.json`, by default this should be: `Iris/packs/overworld/dimensions/overworld.json` Then, open the file (or the vscode workspace to enjoy the cool vscode integration). ### 2) Add your ore![](https://docs.oraxen.com/compatibility/world-generators/iris-world-generator#2-add-your-ore) Locate this part of the config: `"ORES": "All settings in regards to deposits. Contains the ores spawning in your world.", "deposits": [ { "minHeight": 19, "maxPerChunk": 4, "maxHeight": 150, "minPerChunk": 1, "minSize": 25, "maxSize": 25, "palette": [{"block": "granite"}], "varience": 2 },`\ \ Add your own config using the custom ore properties found at step one. For example:\ \ `{ "minHeight": 2, "maxPerChunk": 2, "maxHeight": 30, "minPerChunk": 0, "minSize": 3, "maxSize": 6, "palette": [{ "block": "oraxen:amethyst_ore" }], "varience": 5 },`\ \ You can now save the file, reset your world and restart!\ \ Last updated on January 17, 2026\ \ [World Generators](https://docs.oraxen.com/compatibility/world-generators "World Generators")\ [Custom Ore Generator](https://docs.oraxen.com/compatibility/world-generators/custom-ore-generator "Custom Ore Generator") --- # Skript Integration | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/skript#nextra-skip-nav) [Compatibility](https://docs.oraxen.com/compatibility/packlayer "Compatibility") Skript Copy page Skript Integration ================== Oraxen includes built-in Skript compatibility that loads automatically when [Skript](https://github.com/SkriptLang/Skript)   is present on the server. This allows you to use Oraxen items, custom blocks, and furniture directly in your scripts. Skript 2.9+ is recommended for full compatibility. Getting Started[](https://docs.oraxen.com/compatibility/skript#getting-started) -------------------------------------------------------------------------------- No configuration needed! Simply have both Oraxen and Skript installed on your server. Oraxen will automatically detect Skript and register all syntax elements. You’ll see this message in console when it loads: `[Oraxen] Skript compatibility enabled - Oraxen syntax registered` Available Syntax[](https://docs.oraxen.com/compatibility/skript#available-syntax) ---------------------------------------------------------------------------------- ### Expressions[](https://docs.oraxen.com/compatibility/skript#expressions) #### Get Oraxen Item[](https://docs.oraxen.com/compatibility/skript#get-oraxen-item) Get an ItemStack from an Oraxen item ID. `oraxen item %string% oraxen item from id %string%` **Examples:** `give player oraxen item "ruby_sword" set {_item} to oraxen item "emerald_pickaxe" drop oraxen item "custom_helmet" at player's location` #### Get Oraxen ID[](https://docs.oraxen.com/compatibility/skript#get-oraxen-id) Get the Oraxen ID from an ItemStack, Block, Entity, or Location. `oraxen id of %itemstack/block/entity/location% %itemstack/block/entity/location%'s oraxen id` **Examples:** `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` #### Get Oraxen Block[](https://docs.oraxen.com/compatibility/skript#get-oraxen-block) Get the Oraxen block ID at a location or block. `oraxen block at %location/block% %location/block%'s oraxen block` **Examples:** `set {_blockId} to oraxen block at player's location if oraxen block at clicked block exists: broadcast "This is an Oraxen block!"` #### Get Oraxen Furniture[](https://docs.oraxen.com/compatibility/skript#get-oraxen-furniture) Get the Oraxen furniture ID at a location, block, or from an entity. `oraxen furniture at %location/block/entity% %location/block/entity%'s oraxen furniture` **Examples:** `set {_furnitureId} to oraxen furniture at target entity if oraxen furniture at clicked entity is "wooden_chair": make player sit` * * * ### Conditions[](https://docs.oraxen.com/compatibility/skript#conditions) #### Is Oraxen Item[](https://docs.oraxen.com/compatibility/skript#is-oraxen-item) Check if an item is an Oraxen item. `%itemstack% is [an] oraxen item %itemstack% is oraxen item %string% %itemstack% is not [an] oraxen item` **Examples:** `if player's tool is an oraxen item: broadcast "You're holding a custom item!" if player's tool is oraxen item "ruby_sword": broadcast "You have the Ruby Sword!"` #### Is Oraxen Block[](https://docs.oraxen.com/compatibility/skript#is-oraxen-block) Check if a block is an Oraxen custom block. `%block/location% is [an] oraxen block %block/location% is oraxen block %string% %block/location% is not [an] oraxen block` **Examples:** `if clicked block is an oraxen block: cancel event if block at player's location is oraxen block "ruby_ore": broadcast "You found ruby ore!"` #### Is Oraxen Furniture[](https://docs.oraxen.com/compatibility/skript#is-oraxen-furniture) Check if an entity, block, or location is Oraxen furniture. `%entity/block/location% is [an] oraxen furniture %entity/block/location% is oraxen furniture %string% %entity/block/location% is not [an] oraxen furniture` **Examples:** `if target entity is oraxen furniture: broadcast "You're looking at furniture!" if clicked entity is oraxen furniture "wooden_chair": # handle chair interaction` * * * ### Events[](https://docs.oraxen.com/compatibility/skript#events) All events support filtering by a specific Oraxen item ID using `of "item_id"`. #### Oraxen Block Break[](https://docs.oraxen.com/compatibility/skript#oraxen-block-break) Called when a player breaks an Oraxen custom block (NoteBlock or StringBlock). `on oraxen block break [of %string%]` **Event values:** `event-player`, `event-block`, `event-string` (the Oraxen ID) **Examples:** `on oraxen block break: broadcast "%player% broke an Oraxen block: %event-string%" on oraxen block break of "ruby_ore": cancel event send "You need a special pickaxe to mine this!" to player` #### Oraxen Block Place[](https://docs.oraxen.com/compatibility/skript#oraxen-block-place) Called when a player places an Oraxen custom block. `on oraxen block place [of %string%]` **Event values:** `event-player`, `event-block`, `event-item`, `event-string` **Examples:** `on oraxen block place: broadcast "%player% placed an Oraxen block!" on oraxen block place of "tnt_block": cancel event send "TNT blocks are disabled!" to player` #### Oraxen Block Interact[](https://docs.oraxen.com/compatibility/skript#oraxen-block-interact) Called when a player interacts with an Oraxen custom block. `on oraxen block interact [of %string%]` **Event values:** `event-player`, `event-block`, `event-item`, `event-string` **Examples:** `on oraxen block interact of "magic_chest": open virtual chest inventory to player` #### Oraxen Furniture Break[](https://docs.oraxen.com/compatibility/skript#oraxen-furniture-break) Called when a player breaks Oraxen furniture. `on oraxen furniture break [of %string%]` **Event values:** `event-player`, `event-block`, `event-entity`, `event-string` **Examples:** `on oraxen furniture break: broadcast "%player% broke furniture: %event-string%" on oraxen furniture break of "expensive_chair": cancel event send "You can't break this!" to player` #### Oraxen Furniture Place[](https://docs.oraxen.com/compatibility/skript#oraxen-furniture-place) Called when a player places Oraxen furniture. `on oraxen furniture place [of %string%]` **Event values:** `event-player`, `event-block`, `event-entity`, `event-item`, `event-string` **Examples:** `on oraxen furniture place of "lamp": broadcast "A lamp was placed!"` #### Oraxen Furniture Interact[](https://docs.oraxen.com/compatibility/skript#oraxen-furniture-interact) Called when a player interacts with Oraxen furniture. `on oraxen furniture interact [of %string%]` **Event values:** `event-player`, `event-block`, `event-entity`, `event-item`, `event-string` **Examples:** `on oraxen furniture interact: broadcast "%player% interacted with furniture!" on oraxen furniture interact of "treasure_chest": give player diamond send "You found treasure!" to player` * * * ### Effects[](https://docs.oraxen.com/compatibility/skript#effects) #### Place Oraxen Block[](https://docs.oraxen.com/compatibility/skript#place-oraxen-block) Place an Oraxen custom block at a location. `place oraxen block %string% at %locations% set oraxen block at %locations% to %string%` **Examples:** `place oraxen block "ruby_ore" at player's location place oraxen block "custom_stone" at {_locations::*}` #### Place Oraxen Furniture[](https://docs.oraxen.com/compatibility/skript#place-oraxen-furniture) Place Oraxen furniture at a location. `place oraxen furniture %string% at %locations% spawn oraxen furniture %string% at %locations%` **Examples:** `place oraxen furniture "wooden_chair" at player's location spawn oraxen furniture "lamp" at {_location}` #### Remove Oraxen Block[](https://docs.oraxen.com/compatibility/skript#remove-oraxen-block) Remove an Oraxen block at a location (without drops). `remove oraxen block at %locations/blocks% delete oraxen block at %locations/blocks%` **Examples:** `remove oraxen block at player's location remove oraxen block at clicked block` #### Remove Oraxen Furniture[](https://docs.oraxen.com/compatibility/skript#remove-oraxen-furniture) Remove Oraxen furniture at a location or entity (without drops). `remove oraxen furniture at %locations/entities% delete oraxen furniture at %locations/entities%` **Examples:** `remove oraxen furniture at target entity remove oraxen furniture at player's location` * * * Complete Example Script[](https://docs.oraxen.com/compatibility/skript#complete-example-script) ------------------------------------------------------------------------------------------------ Here’s a complete example script demonstrating various Oraxen features: `# 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 : permission: oraxen.placefurniture trigger: place oraxen furniture arg-1 at player's target block send "&aPlaced %arg-1%!" to player` Troubleshooting[](https://docs.oraxen.com/compatibility/skript#troubleshooting) -------------------------------------------------------------------------------- If Skript syntax doesn’t work, ensure: * Skript is properly installed and enabled * You see the “Skript compatibility enabled” message in console * You’re using Skript 2.9 or newer ### Common Issues[](https://docs.oraxen.com/compatibility/skript#common-issues) **Syntax not recognized:** * Reload Skript with `/skript reload all` * Check console for parsing errors * Verify Oraxen loaded successfully **Item ID not found:** * Ensure the Oraxen item exists in your configuration * Check for typos in the item ID * Item IDs are case-sensitive **Events not triggering:** * Verify the specific event exists (not all vanilla events trigger Oraxen events) * Check if the block/furniture is actually from Oraxen Last updated on January 3, 2026 [MythicMobs - custom mobs](https://docs.oraxen.com/compatibility/mythicmobs-custom-mobs "MythicMobs - custom mobs") [World Generators](https://docs.oraxen.com/compatibility/world-generators "World Generators") --- # Custom Ore Generator | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/world-generators/custom-ore-generator#nextra-skip-nav) [Compatibility](https://docs.oraxen.com/compatibility/packlayer "Compatibility") [World Generators](https://docs.oraxen.com/compatibility/world-generators "World Generators") Custom Ore Generator Copy page Custom Ore Generator ==================== [Custom Ore Generator](https://www.spigotmc.org/resources/custom-ore-generator-%E3%80%8E1-8-1-18-2%E3%80%8F.64339/)   is a plugin for natural generation of blocks and decorations compatible with Oraxen and the Noteblock. Last updated on January 3, 2026 [Iris World Generator](https://docs.oraxen.com/compatibility/world-generators/iris-world-generator "Iris World Generator") [Terralith Datapack Integration](https://docs.oraxen.com/compatibility/world-generators/terralith "Terralith Datapack Integration") --- # BossShopPro | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/archives/bossshoppro#nextra-skip-nav) [Compatibility](https://docs.oraxen.com/compatibility/packlayer "Compatibility") [Archives](https://docs.oraxen.com/compatibility/archives "Archives") BossShopPro Copy page BossShopPro =========== **Archived**: The original BossShopPro plugin is no longer actively maintained and does not support Minecraft 1.17+. Status[](https://docs.oraxen.com/compatibility/archives/bossshoppro#status) ---------------------------------------------------------------------------- The original BossShopPro by Blackixx is no longer being updated. The developer stated that due to time constraints, they are not actively updating the plugin anymore. Alternative[](https://docs.oraxen.com/compatibility/archives/bossshoppro#alternative) -------------------------------------------------------------------------------------- If you need shop functionality, consider using [BossShopPro Continued](https://www.spigotmc.org/resources/bossshoppro-continued-now-free.104824/)  , which is a community-maintained fork that supports modern Minecraft versions. Legacy Information[](https://docs.oraxen.com/compatibility/archives/bossshoppro#legacy-information) ---------------------------------------------------------------------------------------------------- BossShopPro was a powerful chest GUI shop/menu plugin. If you’re still running an older server version (1.16 and below), Oraxen items could be used with BossShopPro through standard item configuration. Last updated on January 17, 2026 [Archives](https://docs.oraxen.com/compatibility/archives "Archives") [CrateReloaded](https://docs.oraxen.com/compatibility/archives/cratereloaded "CrateReloaded") --- # Terralith Datapack Integration | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/world-generators/terralith#nextra-skip-nav) [Compatibility](https://docs.oraxen.com/compatibility/packlayer "Compatibility") [World Generators](https://docs.oraxen.com/compatibility/world-generators "World Generators") Terralith Datapack Integration Copy page Terralith Datapack Integration ============================== Terralith is a popular datapack that overhauls world generation with new biomes and terrain features. You can integrate your Oraxen custom blocks into Terralith’s world generation by modifying the datapack files to include your custom ores and blocks. This method requires manual datapack modification and should be done before world generation. Make sure to backup your datapack files before making changes. **Download Terralith -** [Terralith on PlanetMinecraft](https://www.planetminecraft.com/data-pack/terralith-overworld-evolved-100-biomes-caves-and-more/)   Prerequisites[](https://docs.oraxen.com/compatibility/world-generators/terralith#prerequisites) ------------------------------------------------------------------------------------------------ * Terralith datapack downloaded and extracted * Oraxen custom blocks configured (particularly ores) * Basic understanding of JSON file editing * Text editor (VS Code recommended for bulk editing) Step 1 - Get Your Block Information[](https://docs.oraxen.com/compatibility/world-generators/terralith#step-1---get-your-block-information) -------------------------------------------------------------------------------------------------------------------------------------------- First, you need to obtain the note block data for your custom Oraxen block using the `/oraxen blockinfo` command. `/oraxen blockinfo [your_block_id]` For example, if you have a custom ore called `deepslate_valorite_ore`: `/oraxen blockinfo deepslate_valorite_ore` This will return information like: * **Note** 6 * **Instrument** bassdrum Write down these values as you’ll need them for the configuration files. Step 2 - Create the Configured Feature[](https://docs.oraxen.com/compatibility/world-generators/terralith#step-2---create-the-configured-feature) -------------------------------------------------------------------------------------------------------------------------------------------------- Navigate to `Terralith.zip\data\terralith\worldgen\configured_feature` and create a new JSON file for your ore (e.g., `valorite_ore.json`). `{ "type": "minecraft:ore", "config": { "discard_chance_on_air_exposure": 0.0, "size": 8, "targets": [ { "state": { "Name": "minecraft:note_block", "Properties": { "instrument": "basedrum", "note": "6", "powered": "false" } }, "target": { "predicate_type": "minecraft:tag_match", "tag": "minecraft:deepslate_ore_replaceables" } } ] } }` **Configuration Options** * `size` - Controls the size of ore veins (8 is a medium size) * `instrument` and `note` - Use the values from your `/oraxen blockinfo` command * `tag` - Choose appropriate replacement target (`minecraft:stone_ore_replaceables` for stone, `minecraft:deepslate_ore_replaceables` for deepslate) Step 3 - Create the Placed Feature[](https://docs.oraxen.com/compatibility/world-generators/terralith#step-3---create-the-placed-feature) ------------------------------------------------------------------------------------------------------------------------------------------ Navigate to `Terralith.zip\data\terralith\worldgen\placed_feature` and create another JSON file with the same name (e.g., `valorite_ore.json`). `{ "feature": "terralith:valorite_ore", "placement": [ { "type": "minecraft:count", "count": 4 }, { "type": "minecraft:in_square" }, { "type": "minecraft:height_range", "height": { "type": "minecraft:uniform", "min_inclusive": { "absolute": -64 }, "max_inclusive": { "absolute": -5 } } }, { "type": "minecraft:biome" } ] }` **Configuration Options** * `feature` - Must match your configured feature name (`terralith:your_ore_name`) * `count` - Number of ore veins per chunk (4 is moderate) * `min_inclusive`/`max_inclusive` - Y-level range for ore generation (-64 to -5 for deep underground) Step 4 - Add to Biome Files[](https://docs.oraxen.com/compatibility/world-generators/terralith#step-4---add-to-biome-files) ---------------------------------------------------------------------------------------------------------------------------- Navigate to `Terralith.zip\data\terralith\worldgen\biome` and select the biome files where you want your ore to spawn. **Pro Tip -** Use VS Code’s “Find and Replace in Files” feature to add your ore to multiple biomes at once. This saves significant time when adding ores to many biomes. In each biome file, locate the `features` section and find the **seventh array** (index 6). Add your ore reference: `{ "features": [ [...], [...], [...], [...], [...], [...], [ "existing_features...", "terralith:valorite_ore" ] ] }` Step 5 - Package and Deploy[](https://docs.oraxen.com/compatibility/world-generators/terralith#step-5---package-and-deploy) ---------------------------------------------------------------------------------------------------------------------------- 1. **Archive the datapack** - Compress the modified Terralith folder back into a ZIP file 2. **Deploy to server** - Place the datapack in your `world/datapacks` folder 3. **Generate new world** - The datapack must be present **before** world generation Datapacks only affect newly generated chunks. Existing world chunks will not contain your custom ores. Advanced Usage[](https://docs.oraxen.com/compatibility/world-generators/terralith#advanced-usage) -------------------------------------------------------------------------------------------------- ### Adding Non-Ore Blocks[](https://docs.oraxen.com/compatibility/world-generators/terralith#adding-non-ore-blocks) This method isn’t limited to ores. You can add any Oraxen custom block to world generation by: 1. Using appropriate feature types (e.g., `minecraft:simple_block` for single blocks) 2. Adjusting placement rules for your specific use case 3. Modifying the appropriate biome feature arrays ### Multiple Block Variants[](https://docs.oraxen.com/compatibility/world-generators/terralith#multiple-block-variants) For blocks with multiple variants, create separate configured and placed features for each variant, ensuring each has unique note/instrument combinations. Troubleshooting[](https://docs.oraxen.com/compatibility/world-generators/terralith#troubleshooting) ---------------------------------------------------------------------------------------------------- * **Ore not spawning** - Verify the note/instrument values match your `/oraxen blockinfo` output * **Wrong biomes** - Check that you added the feature to the correct array index (7th array) * **Datapack errors** - Validate your JSON syntax using a JSON validator While this process may seem complex initially, it provides full control over how your Oraxen blocks integrate with Terralith’s enhanced world generation. Last updated on January 3, 2026 [Custom Ore Generator](https://docs.oraxen.com/compatibility/world-generators/custom-ore-generator "Custom Ore Generator") [Archives](https://docs.oraxen.com/compatibility/archives "Archives") --- # Archived Compatibilities | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/archives#nextra-skip-nav) [Compatibility](https://docs.oraxen.com/compatibility/packlayer "Compatibility") ArchivesArchives Copy page Archived Compatibilities ======================== This section contains documentation for plugins that are no longer actively maintained or have been discontinued. These pages are kept for historical reference and for users who may still be running older server versions. If you’re starting a new server, we recommend using the actively maintained alternatives mentioned in each archived page. Last updated on January 17, 2026 [Terralith Datapack Integration](https://docs.oraxen.com/compatibility/world-generators/terralith "Terralith Datapack Integration") [BossShopPro](https://docs.oraxen.com/compatibility/archives/bossshoppro "BossShopPro") --- # CrateReloaded | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/archives/cratereloaded#nextra-skip-nav) [Compatibility](https://docs.oraxen.com/compatibility/packlayer "Compatibility") [Archives](https://docs.oraxen.com/compatibility/archives "Archives") CrateReloaded Copy page CrateReloaded ============= **Note**: CrateReloaded is still maintained but this documentation page was never completed. The plugin works with Oraxen items through standard item ID configuration. Using Oraxen Items with CrateReloaded[](https://docs.oraxen.com/compatibility/archives/cratereloaded#using-oraxen-items-with-cratereloaded) -------------------------------------------------------------------------------------------------------------------------------------------- CrateReloaded supports custom items through its reward configuration. You can use Oraxen items by referencing them with the `oraxen:` prefix or by using the item’s custom model data. Refer to the [CrateReloaded documentation](https://www.spigotmc.org/resources/free-crate-reloaded-mystery-crate-1-8-1-20-x.861/)   for the latest configuration syntax. Last updated on January 3, 2026 [BossShopPro](https://docs.oraxen.com/compatibility/archives/bossshoppro "BossShopPro") [TrMenu](https://docs.oraxen.com/compatibility/archives/trmenu "TrMenu") --- # TrMenu | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/archives/trmenu#nextra-skip-nav) [Compatibility](https://docs.oraxen.com/compatibility/packlayer "Compatibility") [Archives](https://docs.oraxen.com/compatibility/archives "Archives") TrMenu Copy page TrMenu ====== **Archived**: TrMenu was archived by its developers in September 2024 and is no longer actively maintained. Status[](https://docs.oraxen.com/compatibility/archives/trmenu#status) ----------------------------------------------------------------------- The original TrMenu repository was [archived on GitHub](https://github.com/TrPlugins/TrMenu)   in September 2024. The plugin is read-only and will not receive further updates. Alternatives[](https://docs.oraxen.com/compatibility/archives/trmenu#alternatives) ----------------------------------------------------------------------------------- Several community forks continue TrMenu development: * [TrMenu Continued](https://polymart.org/resource/trmenu-continued-menu-plugin.1337)   - Community-maintained fork with bug fixes * [TrMenu-Rebirth](https://github.com/shuiqing2046/TrMenu-Rebirth)   - Active fork attempting to maintain the resource Legacy Information[](https://docs.oraxen.com/compatibility/archives/trmenu#legacy-information) ----------------------------------------------------------------------------------------------- TrMenu was a modern and advanced menu plugin for Minecraft servers. Oraxen items could be displayed in TrMenu menus using item configuration with custom model data or Oraxen item IDs. Last updated on January 17, 2026 [CrateReloaded](https://docs.oraxen.com/compatibility/archives/cratereloaded "CrateReloaded") [EpicWorldGenerator](https://docs.oraxen.com/compatibility/archives/epicworldgenerator "EpicWorldGenerator") --- # EpicWorldGenerator | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/archives/epicworldgenerator#nextra-skip-nav) [Compatibility](https://docs.oraxen.com/compatibility/packlayer "Compatibility") [Archives](https://docs.oraxen.com/compatibility/archives "Archives") EpicWorldGenerator Copy page EpicWorldGenerator ================== **Archived**: EpicWorldGenerator only supports Minecraft 1.15 - 1.17.1 and has not been updated for modern versions. Status[](https://docs.oraxen.com/compatibility/archives/epicworldgenerator#status) ----------------------------------------------------------------------------------- EpicWorldGenerator’s last supported version is Minecraft 1.17.1. The plugin does not work on Minecraft 1.18 and above due to significant changes in world generation APIs. Alternative[](https://docs.oraxen.com/compatibility/archives/epicworldgenerator#alternative) --------------------------------------------------------------------------------------------- For modern Minecraft versions, we recommend using [Iris World Generator](https://www.spigotmc.org/resources/iris-world-gen-the-dimension-engine.84586/)   which actively supports the latest Minecraft versions and has native Oraxen block support. See our [Iris World Generator documentation](https://docs.oraxen.com/compatibility/world-generators/iris-world-generator) for integration details. Legacy Information[](https://docs.oraxen.com/compatibility/archives/epicworldgenerator#legacy-information) ----------------------------------------------------------------------------------------------------------- EpicWorldGenerator allowed custom ore generation with Oraxen blocks on servers running Minecraft 1.17.1 and below. If you’re still running an older server, the integration worked through custom BlockData configuration similar to other world generators. Last updated on January 17, 2026 [TrMenu](https://docs.oraxen.com/compatibility/archives/trmenu "TrMenu") [RealisticWorldGenerator](https://docs.oraxen.com/compatibility/archives/realisticworldgenerator "RealisticWorldGenerator") --- # Custom Hosting Service | Oraxen Docs [Skip to Content](https://docs.oraxen.com/developers/custom-hosting-service#nextra-skip-nav) [Developers](https://docs.oraxen.com/developers/mechanics "Developers") Custom hosting service Copy page Custom Hosting Service ====================== First step[](https://docs.oraxen.com/developers/custom-hosting-service#first-step) ----------------------------------------------------------------------------------- Create a new class which implements HostingProvider. Second step[](https://docs.oraxen.com/developers/custom-hosting-service#second-step) ------------------------------------------------------------------------------------- Insert an empty section into settings.xml/Pack.upload.options. Third step[](https://docs.oraxen.com/developers/custom-hosting-service#third-step) ----------------------------------------------------------------------------------- Set settings.xml/Pack.upload.options.class to external hosting provider class path Last step[](https://docs.oraxen.com/developers/custom-hosting-service#last-step) --------------------------------------------------------------------------------- Set settings.xml/Pack.upload.type to “external” (must.) Last updated on January 17, 2026 [Add Compatibility with a plugin](https://docs.oraxen.com/developers/create-your-own-compatibility "Add Compatibility with a plugin") [API](https://docs.oraxen.com/developers/api "API") --- # Create Your Own Compatibility | Oraxen Docs [Skip to Content](https://docs.oraxen.com/developers/create-your-own-compatibility#nextra-skip-nav) [Developers](https://docs.oraxen.com/developers/mechanics "Developers") Add Compatibility with a plugin Copy page Create Your Own Compatibility ============================= How does it work?[](https://docs.oraxen.com/developers/create-your-own-compatibility#how-does-it-work) ------------------------------------------------------------------------------------------------------- ### First Step: create a compatibility class[](https://docs.oraxen.com/developers/create-your-own-compatibility#first-step-create-a-compatibility-class) You need to create a class that extends `CompatibilityProvider
` and put the codes which add support for the plugin in the class you created. ### Second Step: add the compatibility class to Oraxen[](https://docs.oraxen.com/developers/create-your-own-compatibility#second-step-add-the-compatibility-class-to-oraxen) Use `CompatibilitiesManager.addCompatibility(name of the plugin you want to add support, class you created in first step)` to add the class to Oraxen. Example[](https://docs.oraxen.com/developers/create-your-own-compatibility#example) ------------------------------------------------------------------------------------ I’ll use MythicMobs for this example. ### First Step: create a compatibility class[](https://docs.oraxen.com/developers/create-your-own-compatibility#first-step-create-a-compatibility-class-1) `import io.lumine.xikage.mythicmobs.MythicMobs; import io.lumine.xikage.mythicmobs.api.bukkit.events.MythicDropLoadEvent; import io.th0rgal.oraxen.compatibilities.CompatibilityProvider; public class MythicMobsCompatibility extends CompatibilityProvider{ @EventHandler public void onMythicDropLoadEvent(MythicDropLoadEvent event) { } }` ### Second Step: add the compatibility class to Oraxen[](https://docs.oraxen.com/developers/create-your-own-compatibility#second-step-add-the-compatibility-class-to-oraxen-1) `import io.th0rgal.oraxen.compatibilities.CompatibilitiesManager; import org.bukkit.plugin.java.JavaPlugin; public class OraxenMythicMobsCompatibilityPlugin extends JavaPlugin { public void onEnable() { CompatibilitiesManager.addCompatibility("MythicMobs", MythicMobsCompatibility.class) } }` Last updated on January 17, 2026 [Create your own Mechanic](https://docs.oraxen.com/developers/mechanics "Create your own Mechanic") [Custom hosting service](https://docs.oraxen.com/developers/custom-hosting-service "Custom hosting service") --- # RealisticWorldGenerator | Oraxen Docs [Skip to Content](https://docs.oraxen.com/compatibility/archives/realisticworldgenerator#nextra-skip-nav) [Compatibility](https://docs.oraxen.com/compatibility/packlayer "Compatibility") [Archives](https://docs.oraxen.com/compatibility/archives "Archives") RealisticWorldGenerator Copy page RealisticWorldGenerator ======================= **Archived**: RealisticWorldGenerator only supports Minecraft 1.8.8 - 1.17.1 and does not work on Minecraft 1.18+. Status[](https://docs.oraxen.com/compatibility/archives/realisticworldgenerator#status) ---------------------------------------------------------------------------------------- RealisticWorldGenerator does not work on Minecraft 1.18 and above. The developers have announced a rewrite to support modern versions, but it is not yet available. If you need to use RealisticWorldGenerator worlds on 1.18+, you can generate the world on a 1.17.1 server first and then transfer it to your newer server. Alternative[](https://docs.oraxen.com/compatibility/archives/realisticworldgenerator#alternative) -------------------------------------------------------------------------------------------------- For modern Minecraft versions, we recommend using [Iris World Generator](https://www.spigotmc.org/resources/iris-world-gen-the-dimension-engine.84586/)   which actively supports the latest Minecraft versions and has native Oraxen block support. See our [Iris World Generator documentation](https://docs.oraxen.com/compatibility/world-generators/iris-world-generator) for integration details. Legacy Information[](https://docs.oraxen.com/compatibility/archives/realisticworldgenerator#legacy-information) ---------------------------------------------------------------------------------------------------------------- RealisticWorldGenerator allowed custom ore generation with Oraxen blocks on servers running Minecraft 1.17.1 and below. The integration worked through custom BlockData configuration. Last updated on January 3, 2026 [EpicWorldGenerator](https://docs.oraxen.com/compatibility/archives/epicworldgenerator "EpicWorldGenerator") [Create your own Mechanic](https://docs.oraxen.com/developers/mechanics "Create your own Mechanic") --- # API | Oraxen Docs [Skip to Content](https://docs.oraxen.com/developers/api#nextra-skip-nav) [Developers](https://docs.oraxen.com/developers/mechanics "Developers") API Copy page API === Add Oraxen to your plugin[](https://docs.oraxen.com/developers/api#add-oraxen-to-your-plugin) ---------------------------------------------------------------------------------------------- ### Repository & Dependency Info[](https://docs.oraxen.com/developers/api#repository--dependency-info) You can find the repository and dependency notice [here](https://github.com/oraxen/oraxen#api)  . All methods and better explanations of their functionality and parameters can be found in the actual Classes. Simply open them in your IDE to get a full list of them. Examples of use[](https://docs.oraxen.com/developers/api#examples-of-use) -------------------------------------------------------------------------- Oraxen is built around an ItemsBuilder class that allows you to create items easily. When the plugin starts it parses the configurations to generate builders for each type of items. Each builder can be used to generate itemstacks. ### [OraxenItems](https://github.com/Th0rgal/Oraxen/blob/master/core/src/main/java/io/th0rgal/oraxen/api/OraxenItems.java)   class:[](https://docs.oraxen.com/developers/api#oraxenitems-class-) #### Get an ItemBuilder from an OraxenID[](https://docs.oraxen.com/developers/api#get-an-itembuilder-from-an-oraxenid) `OraxenItems.getItemById(itemID); // where itemID is a section in items configurations` #### Check if an OraxenID exists[](https://docs.oraxen.com/developers/api#check-if-an-oraxenid-exists) `OraxenItems.isAnItem(itemID);` #### Extract an OraxenID from an ItemStack[](https://docs.oraxen.com/developers/api#extract-an-oraxenid-from-an-itemstack) You can use to check if an ItemStack is an OraxenItem (it will return null if OraxenID doesn’t exist) `OraxenItems.getIdByItem(itemstack);` ### Custom Blocks & Furniture[](https://docs.oraxen.com/developers/api#custom-blocks--furniture) #### Place an OraxenBlock[](https://docs.oraxen.com/developers/api#place-an-oraxenblock) Place an OraxenBlock at a given location `OraxenBlocks.place(itemID, location)` Place an OraxenFurniture at a given location, optionally setting a player for rotation purposes `OraxenFurniture.place(itemID, location, @Nullable player)` ### Add resources to the pack[](https://docs.oraxen.com/developers/api#add-resources-to-the-pack) #### Get access to the assets/ folder[](https://docs.oraxen.com/developers/api#get-access-to-the-assets-folder-) `ResourcePack.getAssetsFolder();` ### Mechanics:[](https://docs.oraxen.com/developers/api#mechanics) Oraxen allows you to add your own mechanics to the plugin, it is a little bit more complex than the rest, that’s why there is a [dedicated tutorial](https://docs.oraxen.com/developers/mechanics#how-does-the-mechanic-system-work) . Last updated on January 3, 2026 [Custom hosting service](https://docs.oraxen.com/developers/custom-hosting-service "Custom hosting service") [Vendor Guidelines](https://docs.oraxen.com/vendors/vendor-guidelines "Vendor Guidelines") --- # Custom Mechanics | Oraxen Docs [Skip to Content](https://docs.oraxen.com/developers/mechanics#nextra-skip-nav) DevelopersCreate your own Mechanic Copy page Custom Mechanics ================ How does the Mechanic system work?[](https://docs.oraxen.com/developers/mechanics#how-does-the-mechanic-system-work) --------------------------------------------------------------------------------------------------------------------- ### What’s a mechanic?[](https://docs.oraxen.com/developers/mechanics#whats-a-mechanic) A mechanic is a custom item property. There can be different variations of the same property on different items. For example, the durability property allows you to define a custom durability for an item, but not all items that have a durability mechanic have the same durability. The durability mechanic works by storing the item’s durability in its metadatas and uses the vanilla durability bar to display its custom durability and not its vanilla durability ### So if a Mechanic is different for every Item, should I rewrite a different Durability everytime?[](https://docs.oraxen.com/developers/mechanics#so-if-a-mechanic-is-different-for-every-item-should-i-rewrite-a-different-durability-everytime) No, it would be far too long. Instead, Oraxen offers a MechanicFactory system. Basically you will have to create a Mechanics class that is configurable, and a MechanicsFactory class that will configure all the different versions of your Mechanic class. It will also manage the common code of all these versions. ### Okay, but I want to modify the items which implement my Mechanic to store data in it, is it possible?[](https://docs.oraxen.com/developers/mechanics#okay-but-i-want-to-modify-the-items-which-implement-my-mechanic-to-store-data-in-it-is-it-possible) Of course, for this purpose Oraxen allows you to associate a list of ItemModifier to each mechanic. An ItemModifier is `Function` which is basically a small piece of code that contains changes to be made to an item when it is generated by the server via its configuration. For example for durability mechanics I use an itemModifier that stores the durability chosen by the user in the item’s metadatas. `item -> item.setCustomTag(NAMESPACED_KEY, PersistentDataType.INTEGER, section.getInt("value"))` Let’s create our first mechanic[](https://docs.oraxen.com/developers/mechanics#lets-create-our-first-mechanic) --------------------------------------------------------------------------------------------------------------- For this tutorial I will take as an example the durability mechanic (because it is very simple to understand) but you can follow this tutorial to create the one you want. ### First step: create our mechanic class[](https://docs.oraxen.com/developers/mechanics#first-step-create-our-mechanic-class) Start by creating a class inheriting from Mechanic, if you use [intelliJ](https://www.jetbrains.com/idea/)   you should get something like this: `class DurabilityMechanic extends Mechanic { public DurabilityMechanic(MechanicFactory mechanicFactory, ConfigurationSection section, Function... modifiers) { super(mechanicFactory, section, modifiers); } }` The Mechanic constructor takes three arguments: `- An instance of the Factory which created the Mechanic - The section used to configure the Mechanic - The item modifier(s)` I want each variation of my mechanics to have a different durability, so I will read the configuration of the mechanics and store the value of the field value. #### How the Mechanic configuration section will look like:[](https://docs.oraxen.com/developers/mechanics#how-the-mechanic-configuration-section-will-look-like) `class DurabilityMechanic extends Mechanic { private int itemDurability; public DurabilityMechanic(MechanicFactory mechanicFactory, ConfigurationSection section) { /* We give: - an instance of the Factory which created the mechanic - the section used to configure the mechanic - the item modifier(s) */ super(mechanicFactory, section, item -> item.setCustomTag(NAMESPACED_KEY, PersistentDataType.INTEGER, section.getInt("value"))); this.itemDurability = section.getInt("value"); } public int getItemMaxDurability() { return itemDurability; } }` So now we have a DurabilityMechanic class that is able to adapt to any item and that will call our DurabilityModifier class to tell to Oraxen which modifications to do before creating them (here we just add a data in the item which contains the wanted new durability). ### Second step: create our mechanic factory class[](https://docs.oraxen.com/developers/mechanics#second-step-create-our-mechanic-factory-class) As before, use your ide features to automatically create a class that extends MechanicFactory: `class DurabilityMechanicFactory extends MechanicFactory { public DurabilityMechanicFactory(ConfigurationSection section) { super(section); } @Override public Mechanic parse(ConfigurationSection itemMechanicConfiguration) { return null; } }` We rewrite the parse method to create a new Mechanic (via the DurabilityMechanic class created previously). We also want to tell to Oraxen that this mechanic is successfully implemented and can be loaded using `addToImplemented` method. So our class now looks like that: `public class DurabilityMechanicFactory extends MechanicFactory { public DurabilityMechanicFactory(ConfigurationSection section) { super(section); } @Override public Mechanic parse(ConfigurationSection itemMechanicConfiguration) { Mechanic mechanic = new DurabilityMechanic(this, itemMechanicConfiguration); addToImplemented(mechanic); return mechanic; } }` ### Third step: add our features (events)[](https://docs.oraxen.com/developers/mechanics#third-step-add-our-features-events) In my case I need to use only one event to play with durability and I will create a DurabilityMechanicsManager class that implements Listener to have a clean and tidy code but I could have done it directly in DurabilityMechanicFactory. I tell to Bukkit which class manages the events when the factory is built: `public class DurabilityMechanicFactory extends MechanicFactory { public DurabilityMechanicFactory(String mechanicId) { super(mechanicId); MechanicsManager.registerListeners(OraxenPlugin.get(), new DurabilityMechanicsManager(this)); } @Override public Mechanic parse(ConfigurationSection itemMechanicConfiguration) { Mechanic mechanic = new DurabilityMechanic(this, itemMechanicConfiguration); addToImplemented(mechanic); return mechanic; } }` In order to calculate the durability to display on the item according to the real durability managed by the plugin I use some simple maths: bukkitDamage\=bukkitMaxDurability−realDurability∗bukkitMaxDurabilityrealMaxDurabilitybukkitDamage = bukkitMaxDurability - \\frac{realDurability\*bukkitMaxDurability}{realMaxDurability}bukkitDamage\=bukkitMaxDurability−realMaxDurabilityrealDurability∗bukkitMaxDurability​ So this is my DurabilityMechanicsManager class: `class DurabilityMechanicsManager implements Listener { private DurabilityMechanicFactory factory; public DurabilityMechanicsManager(DurabilityMechanicFactory factory) { this.factory = factory; } @EventHandler(priority = EventPriority.HIGH, ignoreCancelled = true) private void onItemDamaged(PlayerItemDamageEvent event) { ItemStack item = event.getItem(); String itemID = OraxenItems.getIdByItem(item); if (factory.isNotImplementedIn(itemID)) return; DurabilityMechanic durabilityMechanic = (DurabilityMechanic) factory.getMechanic(itemID); ItemMeta itemMeta = item.getItemMeta(); PersistentDataContainer persistentDataContainer = itemMeta.getPersistentDataContainer(); int realDurabilityLeft = persistentDataContainer .get(DurabilityMechanic.NAMESPACED_KEY, PersistentDataType.INTEGER) - event.getDamage(); if (realDurabilityLeft > 0) { double realMaxDurability = //because int rounded values suck durabilityMechanic.getItemMaxDurability(); persistentDataContainer.set(DurabilityMechanic.NAMESPACED_KEY, PersistentDataType.INTEGER, realDurabilityLeft); ((Damageable) itemMeta).setDamage((int) (item.getType() .getMaxDurability() - realDurabilityLeft / realMaxDurability * item.getType().getMaxDurability())); item.setItemMeta(itemMeta); } else { item.setAmount(0); } } }` ### Last step: register our mechanic[](https://docs.oraxen.com/developers/mechanics#last-step-register-our-mechanic) To finish we need to register our MechanicFactory and reload the items to apply the new mechanic to them. It is recommended to register it in an EventListener for `OraxenNativeMechanicsRegisteredEvent`, due to `/oraxen reload all` clearing this registry. To do this we need to add these lines in the onEnable method of our plugin: `Bukkit.getPluginManager().registerEvents(new Listener() { @EventHandler public void onMechanicRegister(OraxenNativeMechanicsRegisteredEvent event) { MechanicsManager.registerMechanicFactory("durability", DurabilityMechanicFactory::new, true); OraxenItems.loadItems(); } }, this);` Conclusion[](https://docs.oraxen.com/developers/mechanics#conclusion) ---------------------------------------------------------------------- To properly create a new mechanic it is recommended to separate its code into three parts: * A factory which extends [MechanicFactory](https://github.com/Th0rgal/Oraxen/blob/master/src/main/java/io/th0rgal/oraxen/items/mechanics/MechanicFactory.java)   * A mechanic which extends [Mechanic](https://github.com/Th0rgal/Oraxen/blob/master/src/main/java/io/th0rgal/oraxen/items/mechanics/Mechanic.java)   * Your own features in a MechanicsManager class (optional too) While it is possible to modify items using your mechanic thanks to an ItemModifier: `item -> item.setCustomTag(NAMESPACED_KEY, PersistentDataType.INTEGER, section.getInt("value"))` You can also modify the texture pack in a similar way: `ResourcePack.addModifiers(packFolder -> {/* your modifications */});` Finally register your mechanic! To summarize the tutorial, [here is the complete source code of the durability mechanics](https://github.com/Th0rgal/Oraxen/blob/master/src/main/java/io/th0rgal/oraxen/items/mechanics/provided/durability/DurabilityMechanicFactory.java)  . Last updated on January 3, 2026 [RealisticWorldGenerator](https://docs.oraxen.com/compatibility/archives/realisticworldgenerator "RealisticWorldGenerator") [Add Compatibility with a plugin](https://docs.oraxen.com/developers/create-your-own-compatibility "Add Compatibility with a plugin") --- # Vendor Guidelines | Oraxen Docs [Skip to Content](https://docs.oraxen.com/vendors/vendor-guidelines#nextra-skip-nav) VendorsVendor Guidelines Copy page Vendor Guidelines ================= Introduction[](https://docs.oraxen.com/vendors/vendor-guidelines#introduction) ------------------------------------------------------------------------------- Oraxen has several ways to let you integrate your MCModels pack with it. This guide will cover the different ways you can do this. Depending on the type of pack, be that Furniture, Custom Blocks or Custom Items, you will need to use slightly different configs. In your downloadable pack it is recommended to have a dedicated folder for Oraxen configs and other files. This makes it easy for users to simply drag and drop files into their Oraxen folder. Common Pack-structure guidelines[](https://docs.oraxen.com/vendors/vendor-guidelines#common-pack-structure-guidelines) ----------------------------------------------------------------------------------------------------------------------- Both the `model` and `textures`\-properties are the relative path to `plugins/Oraxen/pack/models(or textures)/`. So the above model file would be located in `plugins/Oraxen/pack/models/packname_or_something/model_file.json`. If you want to use another namespace, you should put your files into `plugins/Oraxen/pack/assets/NAMESPACE/models(or textures)/`. Then in the config the format for `model` and `textures` are `NAMESPACE:filepath`. No model, texture or filepath should at any point contain Capital Letters or spaces. This is not formatting that resourcepacks past 1.13 support (though Optifine does). 1. `assets/namespace/models/SOMETHING/my model.json` X 2. `assets/namespace/models/something/my model.json` X 3. `assets/namespace/models/something/my_model.json` ✓ Textures should also be a maximum of 256x256 pixels. This is all basic resourcepack stuff, but it has happened enough that I feel a need to point it out. Whenever possible it is recommended to not import paper.json and other base-material files. These are the Nr.1 issue in support and can be avoided by making very basic OraxenItem configs. Essentially, Oraxen generates these into the final pack, if one or more OraxenItem configs uses that material. This will make it easier to properly handle CustomModelData and mitigate most support issues for this. Common config properties[](https://docs.oraxen.com/vendors/vendor-guidelines#common-config-properties) ------------------------------------------------------------------------------------------------------- CustomModelData is the most common pitfall of pack-conflicts. Several packs tend to use the same materials and same CustomModelData values. Oraxen has several methods it handles this. 1. If the config has no specified Pack.custom\_model\_data, Oraxen will assign the highest unused value based on the `material` and `model` 1. This value is always saved to the config unless `disable_automatic_model_data` is set to true 2. Vendors should have this setting set to `true` and not specify a value for the CustomModelData in the configs, to let Oraxen assign an unused one 2. For Glyphs, it is a similar situation. It has a `code`\-property, and Oraxen will assign the highest unused value 1. This value is always saved to the config unless `disable_automatic_glyph_code` is set to true 2. Vendors should have this setting set to `true` and not specify a value for the Glyph code in the configs, to let Oraxen assign an unused one 3. Due to ModelEngine using `LEATHER_HORSE_ARMOR` as it’s default property, it is adviced to not use this for configs. 1. Use another dyeable item like `TIPPED_ARROW`, `POTION` or `SPLASH_POTION` for optimal compatibility 4. If you are making Custom Armor, be aware that different resolutions cannot be combined 1. Meaning any pack that adds 128x64 armor will not work with 64x32 armor 2. The user should also be informed that they need to change the `armor_resolution` setting to match the pack they are using 3. This should be set to the height-pixel count of the armor\_layer files / 2. (128x64 = 32, 64x32 = 16 (default)) 4. Armor is very strict on formatting, and you are adviced to make sure you follow the guidelines in the [Armor](https://docs.oraxen.com/creating-content/armors) section. Custom Items[](https://docs.oraxen.com/vendors/vendor-guidelines#custom-items) ------------------------------------------------------------------------------- Custom Items are the most common type of pack, and the easiest to integrate with Oraxen. All you really need is a config file for your items, and a folder for all resourcepack files. The config file should be put in Oraxen/items and can be named whatever. For clarity, it is recommended to name it the same as your pack. The config file should look something like this: `my_example_item: displayname: "My Example Item" material: PAPER Pack: generate_model: false model: packname_or_something/model_file` This is the most basic of examples. If you are using 2D items, your `Pack`\-section should look like this instead: `Pack: generate_model: true parent_model: "item/generated" textures: - packname_or_something/texture_file` Optionally, the textures-property can take a specific base-name: `Pack: generate_model: true parent_model: "item/generated" textures: top: packname_or_something/top bottom: packname_or_something/bottom side: packname_or_something/side` Mostly used directional custom blocks, as you can specify the side, top, bottom textures more easily. Basically this relies on the `parent_model`, so if you have a custom entry there, you can also use this. `parent_model` follows the same structure as `model` and `textures`, so you can use `NAMESPACE:filepath` if you want to. Custom Blocks[](https://docs.oraxen.com/vendors/vendor-guidelines#custom-blocks) --------------------------------------------------------------------------------- Custom Blocks are essentially just Custom Items, with one of the Block Mechanics added. This means that you can use the same config as above, but with the addition of the `Mechanics`\-section. There are 2 types of Block-Mechanics, `noteblock` and `stringblock`. `noteblock` is essentially for anything that should be a normal block, like stone, wood, dirt, etc. `stringblock` is primarily aimed towards plants, flowers and other decorations as they have no collision. ### NoteBlock[](https://docs.oraxen.com/vendors/vendor-guidelines#noteblock) The `noteblock`\-mechanic is the most common one, and is used for most blocks. The config for this should look something like this: `my_example_block: displayname: "My Example Block" material: PAPER Pack: generate_model: true parent_model: "block/cube_all" textures: - something/texture_file Mechanics: noteblock: custom_variation: 1 model: something/model_file` The `custom_variation`\-property is used to distinguish between all the custom blocks and must be unique. Unlike `custom_model_data` this is not automatically assigned, and you must specify it yourself. The decision here is that since it is placed in the world, the user should have control over it. Perhaps in the future it will be assigned automatically. If you include a README, you should make note of this. The `model`\-property is the same as the one in the `Pack`\-section, and follows the same rules. If had `generate_model` enabled as you specified textures, the model would be your item-id, so `my_example_block`. There are also additional sub-mechanics, like custom sounds, hardness and more. You can read more about them in the [NoteBlock Mechanics](https://docs.oraxen.com/creating-content/blocks/noteblock) and its other pages. ### StringBlock[](https://docs.oraxen.com/vendors/vendor-guidelines#stringblock) The `stringblock`\-mechanic is used for blocks that should not have collision. This is primarily used for plants, flowers and other decorations. The config for this should look something like this: `my_example_block: displayname: "My Example Block" material: PAPER Pack: generate_model: true parent_model: "block/cross" textures: - something/texture_file Mechanics: stringblock: custom_variation: 1 model: something/model_file` As you can see it is very similar to the `noteblock`\-mechanic. The sub-mechanics can be found in the [StringBlock Mechanics](https://docs.oraxen.com/creating-content/blocks/stringblock) and its other pages. Custom Furniture[](https://docs.oraxen.com/vendors/vendor-guidelines#custom-furniture) --------------------------------------------------------------------------------------- Furniture is mostly used when wanting to make 3D modelled stuff like chairs, tables etc. The config for this should look something like this: `my_example_furniture: displayname: "My Example Furniture" material: PAPER Pack: generate_model: false model: packname_or_something/model_file Mechanics: furniture: type: DISPLAY_ENTITY hitbox: width: 1.0 height: 1.0 display_entity_properties: display_transform: FIXED barrier: true` There are a few more properties as you can see. The `type`\-property is used to specify what type of furniture it is. The options are `DISPLAY_ENTITY`, `ITEM_FRAME` and `GLOW_ITEM_FRAME`. `DISPLAY_ENTITY` is a new type as of 1.19.4, and will only work on 1.19.4 servers and above. It is recommended to set this to it either way, as it will be automatically converted to `ITEM_FRAME` on older versions. This type has more properties and allows for better hitboxes and performance. The `hitbox`\-property is used to specify the hitbox of the furniture. This is only useful on 1.19.4+ servers, and spawns what is called an Interaction Entity. Think of it like just a hitbox, used for detecting hitting and interacting with the furniture. This one does however not have collision, for that you need the `barrier`\-property. The `display_entity_properties`\-property is used to specify the properties of the `DISPLAY_ENTITY`. The `display_transform`\-property is used to specify the transform of the item. The options are `FIXED`, `HEAD`, `BODY`, `LEFT_ARM`, `RIGHT_ARM`, `LEFT_LEG`, `RIGHT_LEG` and `GROUND`. Essentially this is all the options in BlockBenches `Display`\-tab. If you want compatibility between ITEM\_FRAME and DISPLAY\_ENTITY, you should use `FIXED`. ItemsAdder would be the same as using `HEAD` due to ArmorStands being its preferred entity-type. You can find the rest of the [Display-Entity Properties](https://docs.oraxen.com/creating-content/furniture/display-entities) . The `barrier`\-property is used to specify if the furniture should have collision or not. This will place a normal barrier block at the furniture origin. You can place multiple barriers by following this format: `Mechanics: furniture: barriers: - { x: 0, y: 0, z: 0 } - { x: 0, y: 1, z: 0 }` Custom Sounds[](https://docs.oraxen.com/vendors/vendor-guidelines#custom-sounds) --------------------------------------------------------------------------------- Some packs might include custom sounds for ambience, mobs or other things. When possible it is recommended to use another namespace for this. This is because Oraxen creates a sounds.json based on the `sound.yml` file by default, and this can cause conflicts. If the usecase allows for custom namespaces, simply add your sounds.json to `Oraxen/pack/assets/namespace/` and add the sound-files to `Oraxen/pack/assets/namespace/sounds`\-folder. If the usecase needs to be in the normal minecraft namespace, you should not include a sounds.json. Instead add entries into Oraxens sound.yml file for optimal compatibility. Then simply add the sound-files into the `Oraxen/pack/assets/minecraft/sounds` folder. Last updated on January 3, 2026 [API](https://docs.oraxen.com/developers/api "API") ---