> For the complete documentation index, see [llms.txt](https://docs.cheddah-development.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cheddah-development.net/plugin-documentaion/cozy-claims/administration/oraxen-compatibility.md).

# Oraxen Compatibility

CozyClaims can use an Oraxen item as the default icon shown for claims that do not have a player-selected icon. Oraxen is completely optional; CozyClaims continues working with a normal Minecraft item when Oraxen is absent or an item cannot be resolved.

### Requirements

* A supported Oraxen installation enabled on the server
* A valid Oraxen item ID
* A valid vanilla Bukkit material to use as the fallback

No additional CozyClaims addon is required. Oraxen is detected automatically during startup, when Oraxen becomes enabled, and when `/claimsadmin reload` is used.

### Configuration

Replace the normal `claim-icons.default-material` value with an Oraxen item definition:

```yaml
claim-icons:
  default-material:
    oraxen: cozy_claim_icon
    fallback-material: GRASS_BLOCK
```

Change `cozy_claim_icon` to the item ID configured in Oraxen. `fallback-material` must be a valid Bukkit material name such as `GRASS_BLOCK`, `EMERALD`, or `OAK_LOG`.

The older `material` key is also accepted as the fallback, but `fallback-material` is recommended because its purpose is clearer:

```yaml
claim-icons:
  default-material:
    oraxen: cozy_claim_icon
    material: GRASS_BLOCK
```

Run `/claimsadmin reload` after making changes.

### Where the Oraxen item appears

The configured Oraxen item is used as the default claim display icon in claim-list interfaces, including:

* The player's **My Claims** list
* Claim selection for member management
* Administrator player-claim lists

If a claim has a custom Bukkit material icon selected by its owner, that custom icon takes priority over the configured Oraxen default. Administrative claims may use their own fixed display material.

### Fallback behavior

CozyClaims uses `fallback-material` when:

* Oraxen is not installed
* Oraxen is installed but disabled
* The configured Oraxen API is unavailable or incompatible
* The item ID is blank, missing, or invalid
* Oraxen fails to build the requested item

An invalid Oraxen ID produces a console warning and safely falls back. It does not prevent CozyClaims from enabling.

{% hint style="info" %}
Always configure a recognizable vanilla fallback. Players will still see a useful claim icon during Oraxen maintenance, load failures, or plugin removal.
{% endhint %}

### Player-selected icons

Oraxen compatibility applies to the configured default display item only. Players cannot permanently assign an Oraxen item ID to an individual claim through the icon picker.

When a player selects an item from their inventory, CozyClaims stores only its underlying Bukkit material. It intentionally does not store or copy:

* Oraxen item IDs
* Custom model data or item models
* Custom names or lore
* Enchantments
* Other custom item metadata

This keeps saved claim icons safe if Oraxen items are renamed, removed, or changed later.

The `claim-icons.allowed-materials` and `claim-icons.blocked-materials` lists also accept Bukkit material names only—not Oraxen IDs.

### Returning to a vanilla icon

Replace the section with a single material value:

```yaml
claim-icons:
  default-material: GRASS_BLOCK
```

Then run `/claimsadmin reload`. Existing player-selected claim icons are unaffected.

### Troubleshooting

#### The fallback appears instead of the Oraxen item

1. Confirm Oraxen is enabled without startup errors.
2. Confirm the item ID exactly matches the ID in Oraxen.
3. Run `/claimsadmin reload`.
4. Check the console for `Oraxen display item id ... did not resolve to an item` or an API compatibility warning.
5. Confirm the claim does not already have a player-selected icon.

#### CozyClaims says it hooked into Oraxen, but one item fails

The integration is active, but the configured ID could not be resolved or built. Correct the item ID in `config.yml` and reload.

#### Oraxen is removed later

No data conversion is required. CozyClaims automatically displays the configured vanilla fallback, and all native claim data continues working normally.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cheddah-development.net/plugin-documentaion/cozy-claims/administration/oraxen-compatibility.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.