Skip to main content

⚙️ Settings

Overview​

Oraxen settings control how the plugin behaves on your server.

Configuration​

Settings are configured in the settings.yml file in the plugins/Oraxen folder.

  • 📁 plugins
    • 📁 Oraxen
      • 📄 settings.yml

Settings​

🚩 debug

Toggles debug mode, which will output detailed additional informational messages to the console.

debug: false # Enables verbose console logging for Oraxen diagnostics.
🔔 update-checker

Checks GitHub for a newer Oraxen release and notifies players with the oraxen.update.notify permission when they join.

update-checker:
  enabled: true # Enables update checks. Set it to "false" to disable checks and join notifications.
  interval: 24h # Time between checks. Use a whole number followed by "s" (seconds), "m" (minutes), "h" (hours), or "d" (days). The minimum interval is "10m"; the default is "24h".
🧩 Plugin

Controls global Oraxen behavior, including config updates, language selection, first-run messaging, Paper config changes, and generation of default files.

Plugin:
  keep_this_up_to_date: true # Updates the config when settings change between Oraxen versions.
  language: "english" # Selects the language file Oraxen uses for messages. Valid options include "czech", "english", "french", "german", "jpn_JP", "korean", "ru-RU", "zh-CN", and "zh-TW".
  introduction: # Internal flags, do not change this.
    enabled: true
    console_sent: false
  auto_update_paper_config: true # Updates "paper-global.yml" to disable block updates for custom blocks.
  generation:
    default_assets: true # Generates the default resource-pack assets that ship with Oraxen.
    default_configs: true # Generates the default config files that ship with Oraxen.
📝 Plugin.formatting

Chooses which text Oraxen formats with MiniMessage, including text created by other plugins.

Plugin:
  formatting:
    inventory_titles: true # Formats inventory titles.
    titles: true # Formats titles.
    subtitles: true # Formats subtitles.
    action_bar: true # Formats action-bar messages.
    anvil: true # Formats anvil result text.
    signs: true # Formats sign text when placed or edited.
    chat: true # Formats chat messages and glyphs. Disable this if a chat plugin conflicts with it.
    books: true # Formats glyphs shown in written books.
info

This section uses MiniMessage. Legacy color formats such as §c or &c are not supported.

🛠️ ConfigsTools

Controls model-data and glyph-code generation, plus the fallback item shown when a config entry cannot be resolved.

ConfigsTools:
  skipped_model_data_numbers: [] # Reserves specific CustomModelData values so Oraxen will not assign them automatically. This list accepts singular numbers and ranges such as "1-4".
  disable_automatic_model_data: false # Disables automatic model-data assignment.
  disable_automatic_glyph_code: false # Stops Oraxen from auto-generating glyph codes.
  error_item:
    material: PODZOL # Material used for the fallback item shown when a config entry fails.
    excludeFromInventory: false # Hides the fallback item from inventories when enabled.
    injectId: false # Injects the Oraxen item-ID tag into the fallback item so Oraxen recognizes it as an Oraxen item. Defaults to "true" in code. The legacy "injectID" casing shipped in the default "settings.yml" is not read and has no effect.
🛡️ CustomArmor

Controls which custom armor system Oraxen uses and how component- or trim-based armor is configured.

CustomArmor:
  type: COMPONENT # Selects the custom armor system Oraxen should use. Valid types are "COMPONENT", "TRIMS", and "NONE".
  auto_select_type: true # Lets Oraxen replace incompatible armor types with the best type for the detected server version.
  disable_leather_repair: true # Prevents custom armor from being repaired with leather. Custom armor can only be repaired with copies of the same custom armor.
  component_settings:
    auto_assign_component: true # Automatically adds the equippable-model component unless you set it manually.
  trims_settings:
    material_replacement: CHAINMAIL # Chooses the vanilla material used to represent trim-based armor. Valid materials are "CHAINMAIL", "IRON", "GOLD", "DIAMOND", "NETHERITE", and "LEATHER".
    auto_assign_settings: true # Automatically applies trim and item-flag settings for custom armor.
🔁 ItemUpdater

Keeps player inventories, loaded block inventories, and loaded entity-held items synced to the latest Oraxen item definitions.

ItemUpdater:
  update_items: true # Updates player inventories to the current item config when they join.
  update_tile_entity_contents: true # Updates items in loaded block inventories such as chests and furnaces.
  update_entity_contents: true # Updates items held by loaded entities such as item frames, mobs, and ender chests.
  override_renamed_items: false # Replaces items even if they were renamed by a player.
  override_item_lore: false # Forces item lore to match the Oraxen item definition.
  update_items_on_reload: true # Re-applies item updates to online players after "/oraxen reload items" or "/oraxen reload all".
🪑 FurnitureUpdater

Keeps placed furniture synced when players join, reload items, or load entities and chunks, and can try to repair broken furniture.

FurnitureUpdater:
  update_furniture: true # Keeps placed furniture synced with the current config.
  update_on_reload: false # Updates furniture after "/oraxen reload items" or "/oraxen reload all".
  update_on_load: false # Updates the furniture item whenever an entity is loaded.
  experimental_furniture_type_update: false # Enables experimental furniture type migration.
  experimental_fix_broken_furniture: false # Tries to repair furniture that is not placed or broken correctly.
📦 Pack.generation

Generates and prepares Oraxen resource-pack files.

Pack:
  generation:
    generate: true # Enables or disables all resource-pack generation.
    unprotected-location: "" # Writes an extra readable ZIP after pack generation events and before obfuscation. Oraxen does not upload or send this file. Leave it empty to disable the export. Relative paths use the server working folder, and parent directories are created automatically. Put the export outside "plugins/Oraxen/pack" so Oraxen does not import it on a later generation.
    disable_mcmeta_generation: false # Prevents Oraxen from creating or modifying "pack.mcmeta". The file at "plugins/Oraxen/pack/pack.mcmeta" is included exactly as provided, and automatic overlay entries are disabled.
    multi_version_packs: false # Generates separate packs for clients on 1.21.3 and below and clients on 1.21.4+. ViaVersion is used for client-version detection; without it, players receive the server-version pack. Multi-version packs require the "lobfile", "polymath", "s3", or "external" upload type. The "self-host" type serves only one file and cannot be used for multi-version packs.
    excluded_file_extensions: [] # Lists file extensions that should not be included in the final zipped resource pack.
    appearance:
      item_properties: true # Uses the "minecraft:item_model" component with Oraxen item IDs and generates "assets/oraxen/items/<item_id>.json" for Minecraft 1.21.4+.
      model_data_ids: false # Uses "custom_model_data.strings[0]" with stable string identifiers such as "oraxen:<item_id>" and generates "minecraft:select" item definitions. This only applies to items that explicitly set "pack.custom_model_data".
      model_data_float: false # Uses "custom_model_data.floats[0]" with "minecraft:range_dispatch" and also sets integer CustomModelData for plugin compatibility. This only applies to items that explicitly set "pack.custom_model_data".
      generate_predicates: false # Generates legacy predicate override files on 1.21.4+. This is not normally needed unless an external tool requires legacy JSON files. Pre-1.21.4 servers always generate predicates.
    verify_pack_files: true # Checks textures and models for valid resource-pack formatting.
    fix_force_unicode_glyphs: true # Fixes glyphs not showing when Force Unicode is enabled.
    atlas:
      exclude_malformed_from_atlas: true # Excludes malformed textures from the atlas instead of including invalid entries.
      generate: true # Generates atlas files for the resource pack.
      type: "SPRITE" # Chooses the atlas mode. Valid options are "SPRITE" and "folder".
    auto_generated_models_follow_texture_path: false # Makes auto-generated models follow the source texture path.
    compression: BEST_COMPRESSION # Chooses the ZIP compression level used for the generated pack. This follows Java's "Deflater" constants.
    obfuscation:
      type: NONE # Chooses the pack obfuscation mode. "NONE" keeps keys readable, "SIMPLE" renames pack-internal model, texture, and sound paths while preserving namespaces, and "FULL" also replaces namespaces used by renamed resources.
    protection: true # Applies protection methods intended to make the pack difficult to extract with common archive tools.
    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." # Adds a comment to the generated pack archive.
warning

Do not try to extract a pack after enabling generation.protection; protected archives can behave unexpectedly in normal archive tools.

info

generation.appearance.model_data_ids and generation.appearance.model_data_float cannot be combined because both write to the same item definition files.

📥 Pack.import

Controls how Oraxen combines files from imported resource packs.

Pack:
  import:
    merge_duplicate_fonts: true # Merges duplicate font files, most often "default.json", into the final pack. Original files are not deleted, but duplicates are excluded in favor of the merged file.
    merge_duplicates: true # Merges duplicate imported resources when possible.
    remove_core_shaders_from_imported_packs: false # Removes imported Minecraft core shader files from "pack/assets" and uploaded ZIP merges. This is useful when external packs override Oraxen-generated text or scoreboard shaders.
    retain_custom_model_data: true # Keeps CustomModelData values from imported files. Only enable this when another plugin requires those exact values, because it can conflict with other Oraxen items.
    merge_item_base_models: false # Attempts to merge item base model JSON files such as "paper.json" from imported packs instead of generating item configs from them.
☁️ Pack.upload

Chooses where Oraxen uploads the generated resource pack.

Pack:
  upload:
    enabled: true # Enables uploading the generated resource pack to the selected host.
    type: polymath # Chooses the upload backend. Valid options are "lobfile", "polymath", "s3", "self-host", and "external".
    polymath:
      server: atlas.oraxen.com # Sets the Polymath server used for resource-pack uploads. You can use the public Oraxen Atlas endpoint or your own Polymath instance.
      secret: "oraxen" # Sets the Polymath upload secret. Change this when hosting your own Polymath instance to limit upload access.
    lobfile:
      api-key: "" # Sets the Lobfile API key used for uploads.
      pack-name: Oraxen # Sets the Lobfile pack name. When multi-version packs are enabled, Oraxen uses "<pack-name>_<version>".
    self-host:
      host: "0.0.0.0" # Sets the IP address the self-hosted HTTP server binds to. "0.0.0.0" listens on all interfaces.
      port: 8080 # Sets the port the self-hosted HTTP server listens on.
      domain: "localhost:8080" # Sets the domain or IP and port players use to download the self-hosted pack.
    s3:
      endpoint: "https://s3.us-east-1.amazonaws.com" # Sets the S3 API endpoint, including "https://".
      access-key: "" # Sets the credentials used to upload the pack.
      secret-key: "" # Sets the credentials used to upload the pack.
      bucket: "" # Sets the bucket where Oraxen stores the pack.
      region: "us-east-1" # Sets the S3 region.
      prefix: "oraxen" # Sets an optional folder within the bucket. An empty value stores packs at the bucket root.
      path-style: true # Uses path-style requests for services such as MinIO and Cloudflare R2. Set to "false" to use bucket subdomains.
      public-url: "" # Sets an optional public or CDN URL for the bucket root. When empty, Oraxen creates a presigned download URL.
      presigned-url-expiry: 86400 # Sets the presigned URL lifetime in seconds. It must be between "1" and "604800" when "public-url" is empty. Reload the pack before the URL expires.

External upload type​

When upload.type is external, Pack.upload.options.class must name a fully qualified class implementing HostingProvider. The constructor may be no-arg or take a ConfigurationSection. The whole options section is passed to the provider. This section is not present in the default settings.yml and must be added manually.

Pack:
  upload:
    type: external
    options:
      class: "com.example.MyHostingProvider"
📤 Pack.dispatch

Controls when and how Oraxen sends the resource pack to players.

Pack:
  dispatch:
    send: true # Sends the pack to players when enabled.
    mode: "JOIN" # Chooses when the pack is sent. Valid options are "JOIN" and "PRE-JOIN". "PRE-JOIN" requires Paper 1.21.7+ and falls back to "JOIN" when unavailable.
    timeout: 30s # Time to wait for the client to respond in "PRE-JOIN" mode before continuing login. Supports values such as "30s", "500ms", "1m", or "20t".
    exclude: [] # Client versions that should not receive the pack. Quote every rule, for example "'< 1.12'", "'= 1.21.11'", or "'> 1.21.11'".
    delay: -1 # Delays pack sending by the configured number of seconds after join. Values at or below "0", including "-1", send immediately. This only applies to "JOIN" mode.
    mandatory: true # Makes the pack required instead of optional.
    disable:
      movement: true # Freezes player movement while the pack loads.
      damage: true # Prevents damage while the pack loads.
    prompt: "<#fa4943>Accept the pack to enjoy a full <b><gradient:#9055FF:#13E2DA>Oraxen</b><#fa4943> experience" # Sets the resource-pack prompt shown to players.
    layer: "" # Sets the resource-pack layer. Set a non-empty value to stop Oraxen from clearing resource packs sent by your proxy.
📬 Pack.receive

Controls messages and commands triggered by resource-pack status changes.

Pack:
  receive:
    enabled: true # Enables pack status feedback handling.
    loaded:
      actions:
        sound:
          enabled: true # Plays a sound after the pack is loaded when enabled.
          type: oraxen:welcome # Sets the sound played after the pack is loaded.
          volume: 1.0 # Sets the loaded sound volume.
          pitch: 1.0 # Sets the loaded sound pitch.
        delay: 5 # Delays loaded actions by the configured number of ticks.
        message:
          enabled: false # Sends a message for the given pack status when enabled.
          type: ACTION_BAR # Chooses how the message is delivered. Valid options are "KICK", "CHAT", "ACTION_BAR", and "TITLE".
          content: "<#55ffa4><bold>ResourcePack loaded" # Sets the message content. Click and hover elements are only available with "CHAT" messages.
        commands:
          console: [] # Runs commands as console for the given pack status.
          player: [] # Runs commands as the player for the given pack status.
          opped_player: [] # Runs commands as a temporarily opped player for the given pack status.
    accepted:
      actions:
        message:
          enabled: false # Sends a message for the given pack status when enabled.
          type: ACTION_BAR # Chooses how the message is delivered. Valid options are "KICK", "CHAT", "ACTION_BAR", and "TITLE".
          content: "<#55ffa4><bold>ResourcePack accepted" # Sets the message content. Click and hover elements are only available with "CHAT" messages.
        commands:
          console: [] # Runs commands as console for the given pack status.
          player: [] # Runs commands as the player for the given pack status.
          opped_player: [] # Runs commands as a temporarily opped player for the given pack status.
    denied:
      actions:
        message:
          enabled: false # Sends a message for the given pack status when enabled.
          type: CHAT # Chooses how the message is delivered. Valid options are "KICK", "CHAT", "ACTION_BAR", and "TITLE".
          content: "<red>You refused the ResourcePack, but you need it in order to see the new items. Please </red><click:run_command:'/oraxen pack send'><hover:show_text:'<green>Display more information'><green><bold>CLICK HERE</bold></hover></click> <red>or type <bold>/oraxen pack send</bold>" # Sets the message content. Click and hover elements are only available with "CHAT" messages.
        commands:
          console: [] # Runs commands as console for the given pack status.
          player: [] # Runs commands as the player for the given pack status.
          opped_player: [] # Runs commands as a temporarily opped player for the given pack status.
    failed_download:
      actions:
        message:
          enabled: false # Sends a message for the given pack status when enabled.
          type: CHAT # Chooses how the message is delivered. Valid options are "KICK", "CHAT", "ACTION_BAR", and "TITLE".
          content: "<red>You failed to download the ResourcePack, but you need it in order to see the new items. Please </red><click:run_command:'/oraxen pack send'><hover:show_text:'<red>Loading the resource pack in game can cause lag'><red><bold>CLICK HERE</bold></hover></click> <red>to retry or type <bold>/oraxen pack send</bold>" # Sets the message content. Click and hover elements are only available with "CHAT" messages.
        commands:
          console: [] # Runs commands as console for the given pack status.
          player: [] # Runs commands as the player for the given pack status.
          opped_player: [] # Runs commands as a temporarily opped player for the given pack status.
    failed_reload:
      actions:
        commands:
          console: [] # Runs commands as console for the given pack status.
          player: [] # Runs commands as the player for the given pack status.
          opped_player: [] # Runs commands as a temporarily opped player for the given pack status.
    downloaded:
      actions:
        commands:
          console: [] # Runs commands as console for the given pack status.
          player: [] # Runs commands as the player for the given pack status.
          opped_player: [] # Runs commands as a temporarily opped player for the given pack status.
    invalid_url:
      actions:
        commands:
          console: [] # Runs commands as console for the given pack status.
          player: [] # Runs commands as the player for the given pack status.
          opped_player: [] # Runs commands as a temporarily opped player for the given pack status.
    discarded:
      actions:
        commands:
          console: [] # Runs commands as console for the given pack status.
          player: [] # Runs commands as the player for the given pack status.
          opped_player: [] # Runs commands as a temporarily opped player for the given pack status.

Supported receive statuses are loaded, accepted, denied, failed_download, failed_reload, downloaded, invalid_url, and discarded. The failed_reload, downloaded, invalid_url, and discarded statuses are available on Minecraft 1.20.3+.

✦ Glyphs

Controls emoji-list permissions and glyph tab completions.

Glyphs:
  emoji_list_permission_only: true # Shows only emojis the player has permission to use.
  unicode_completions: true # Makes glyph tab completion show Unicode values instead of glyph placeholders.
🗂️ inventory-menu

Configures the built-in browser GUI that players open with Oraxen commands. It controls the menu title, pagination, and the category buttons shown in the item browser.

inventory-menu:
  title: "<shift:-18><glyph:menu_items><shift:-193>" # Sets the title used for the main browser GUI.
  rows: 6 # Sets how many rows the GUI uses.
  slots: 45 # Sets how many item slots are shown per page.
  previous_page_icon: arrow_previous_icon # Sets the Oraxen item ID or vanilla material used for the previous-page button. Bundled icons are used by default and fall back to vanilla items if missing.
  next_page_icon: arrow_next_icon # Sets the Oraxen item ID or vanilla material used for the next-page button. Bundled icons are used by default and fall back to vanilla items if missing.
  exit_icon: exit_icon # Sets the Oraxen item ID or vanilla material used for the exit button. Bundled icons are used by default and fall back to vanilla items if missing.

  layout: # Defines the category buttons shown in the browser.
    armors:
      slot: 1 # Chooses the slot used for the category button.
      icon: emerald_chestplate # Chooses the Oraxen item icon shown for the category.
      name: "<green>Armors" # Sets the visible name of the category button.
      title: "<main_menu_title><#362753><glyph:menu_items_overlay:colorable>" # Sets the GUI title shown when opening the category.

Default categories include armors, blocks, furniture, flowers, hats, items, mystical, plants, skins, tools, and weapons.

info

Existing oraxen_inventory configurations are migrated automatically to the inventory-menu format.

🧪 Studio

Connects a server to Oraxen Studio and controls automatic synchronization.

Studio:
  url: "https://studio.oraxen.com" # Sets the Oraxen Studio URL used by "/oraxen studio connect", "/oraxen studio pull", and "/oraxen studio push".
  secret: "" # Stores the scoped server token created by "/oraxen studio connect". Keep this token private.
  auto_sync: true # Listens for Studio WebSocket sync events and reloads items and the resource pack.
⚙️ Misc recipe settings

Controls recipe resets and whether unlocked Oraxen recipes appear in the recipe book.

Misc:
  reset_recipes: true # Resets Oraxen recipes on reload. This can conflict with other plugins, but makes recipe testing easier.
  add_recipes_to_book: true # Adds unlocked Oraxen recipes to the player recipe book.
📊 Misc scoreboard and tablist

Controls the number and background display for scoreboards and the tablist.

Misc:
  hide_scoreboard_numbers: false # Hides scoreboard numbers on the sidebar using Oraxen's native packet handling on supported Paper versions.
  hide_scoreboard_background: false # Hides the scoreboard background on Minecraft 1.21.6 through 1.21.7.
  hide_tablist_background: false # Hides the tablist background on Minecraft 1.21.6 through 1.21.7.
🛡️ Misc.armor_equip_event_bypass
Misc:
  armor_equip_event_bypass: # Lists blocks that should not trigger armor equip behavior when right-clicked.
    - FURNACE
    - CHEST
    - TRAPPED_CHEST
    - ...
🖼️ Misc item display transforms

Sets the vanilla display transforms Oraxen uses when it adds custom shields, bows, and crossbows.

Misc:
  shield_display: '{"thirdperson_righthand":{"rotation":[0,90,0],"translation":[10,6,-4],"scale":[1,1,1]},"thirdperson_lefthand":{"rotation":[0,90,0],"translation":[10,6,12],"scale":[1,1,1]},"firstperson_righthand":{"rotation":[0,180,5],"translation":[-10,2,-10],"scale":[1.25,1.25,1.25]},"firstperson_lefthand":{"rotation":[0,180,5],"translation":[10,0,-10],"scale":[1.25,1.25,1.25]},"gui":{"rotation":[15,-25,-5],"translation":[2,3,0],"scale":[0.65,0.65,0.65]},"fixed":{"rotation":[0,180,0],"translation":[-2,4,-5],"scale":[0.5,0.5,0.5]},"ground":{"rotation":[0,0,0],"translation":[4,4,2],"scale":[0.25,0.25,0.25]}}' # Sets the vanilla shield display transforms.
  bow_display: '{"thirdperson_righthand":{"rotation":[-80,260,-40],"translation":[-1,-2,2.5],"scale":[0.9,0.9,0.9]},"thirdperson_lefthand":{"rotation":[-80,-280,40],"translation":[-1,-2,2.5],"scale":[0.9,0.9,0.9]},"firstperson_righthand":{"rotation":[0,-90,25],"translation":[1.13,3.2,1.13],"scale":[0.68,0.68,0.68]},"firstperson_lefthand":{"rotation":[0,90,-25],"translation":[1.13,3.2,1.13],"scale":[0.68,0.68,0.68]}}' # Sets the vanilla bow display transforms.
  crossbow_display: '{"thirdperson_righthand":{"rotation":[-90,0,-60],"translation":[2,0.1,-3],"scale":[0.9,0.9,0.9]},"thirdperson_lefthand":{"rotation":[-90,0,30],"translation":[2,0.1,-3],"scale":[0.9,0.9,0.9]},"firstperson_righthand":{"rotation":[-90,0,-55],"translation":[1.13,3.2,1.13],"scale":[0.68,0.68,0.68]},"firstperson_lefthand":{"rotation":[-90,0,35],"translation":[1.13,3.2,1.13],"scale":[0.68,0.68,0.68]}}' # Sets the vanilla crossbow display transforms.