> 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/mo-zu-fu-shu-kai-fa/custom-elements.md).

# 自定义要素与注册契约

本文档面向 Core 附属模组作者。元素注册是启动期行为，运行时注册表冻结后不可修改。

## 元素定义

`ElementDefinition` 包含：

* `QualifiedTypeId id`：推荐使用 `yourmod:element_<name>`。
* `String translationKey`：小写翻译键，例如 `element.yourmod.crystal`。
* `CustomerAssetId iconAsset`：元素图标资源。
* `int tintColor`：可选的 `0xRRGGBB` 着色；无着色使用 `ElementDefinition.NO_TINT`。

示例声明：

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

上例最后一行只表示类型边界。实际注册器必须由项目提供的生命周期入口传入，不能通过静态猜测或反射获得。

## 资源与翻译

图标是客户端资源，但元素定义本身属于 Core 公共数据。资源应由附属模组随自己的资源包提供，并在 `en_us.json`、`zh_cn.json` 等语言文件中声明翻译键。

## 商品中的等级

元素定义不包含等级。Retail 商品使用 `CatalogElement` 为已注册元素分配 `1..9` 等级；创建 `CatalogElement` 时越界等级会被限制到有效范围。

## 注意事项

* ID 必须全局唯一。
* 注册窗口冻结后不要继续注册。
* 不要使用显示名称代替限定 ID。
* 不要把价格、库存或顾客权限写入元素定义。


---

# 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/mo-zu-fu-shu-kai-fa/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.