> For the complete documentation index, see [llms.txt](https://eurekabusiness.caiziii.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://eurekabusiness.caiziii.com/eurekabusinesscommunity-en/addon-developers/custom-elements.md).

# Custom Elements & Registration

This document explains how addon authors can declare and register custom elements during the Core initialization window.

## Element Definition

An `ElementDefinition` declares:

* `QualifiedTypeId id`: Namespaced identifier, typically `yourmod:element_<name>`;
* `String translationKey`: Localization key, e.g. `element.yourmod.crystal`;
* `CustomerAssetId iconAsset`: Path to the element's icon asset;
* `int tintColor`: Optional `0xRRGGBB` tint color, or `ElementDefinition.NO_TINT`.

Example declaration:

```java
import com.eureka.eurekabusiness.core.api.business.QualifiedTypeId;
import com.eureka.eurekabusiness.core.api.element.ElementDefinition;
import com.eureka.eurekabusiness.core.api.element.ElementRegistrar;
import com.eureka.eurekabusiness.core.api.npc.customer.CustomerAssetId;

QualifiedTypeId id = QualifiedTypeId.parse("yourmod:element_crystal");
ElementDefinition definition = new ElementDefinition(
        id,
        "element.yourmod.crystal",
        CustomerAssetId.parse("yourmod:textures/gui/elements/crystal.png"),
        0x80FFFF
);

ElementRegistrar registrar = /* obtain during the Core bootstrap window */ null;
```

Registrars are provided through framework lifecycle callbacks. Never invoke registries via reflection or static state after freeze.

## Assets & Localization

Icons are client resources, while element metadata is shared across logical sides. Provide 16×16 texture assets in your mod resources alongside translations in `en_us.json` and `zh_cn.json`.

## Item Element Levels

Element definitions do not hardcode item levels. Retail assigns levels (`1..9`) to registered elements per catalog entry via `CatalogElement`.

## Design Rules

* Element IDs must be globally unique;
* Registration must complete before registry freeze;
* Use qualified type IDs, not localized display names, when referencing elements;
* Do not store prices, inventories, or customer permissions inside element definitions.


---

# 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://eurekabusiness.caiziii.com/eurekabusinesscommunity-en/addon-developers/custom-elements.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.