> For the complete documentation index, see [llms.txt](https://hamsterbaron.gitbook.io/hamsterbaron/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hamsterbaron.gitbook.io/hamsterbaron/mechanic-guides/getting-started.md).
# 制作机制 / Getting Started
## 开始制作第一个机制
跟随以下文档教程，只需几步就能轻松学会新建与导入您的自定义枪械技能机制。请注意，开发版可能存在预期之外的功能漏斗，因此建议您在仅包含必要模组的客户端/服务端中新建一个测试世界以熟悉开发过程，避免误操作导致的潜在破坏性风险[^1]。
首先，创建一个空的 example.yaml 文件。您的机制 YAML 配置文件所处结构应如下所示:
```
/.minecraft/config/taczexpand/skills
```
> 只有开发版能够识别该路径下的文件，标准用户版只能读取config目录下已封装的机制文件。
一个完整的能够正常运行的机制配置需要拥有数个基础元素，在机制模块页面中已有讲解。此处是基本元素的缩进结构与示例:
```yaml
Name: "ExampleName" #程序内部的识别名，用于管理
Lore: "TestLore" #匹配的Lore物品词条，可为空
Attachments: #匹配的配件列表，可为空
- "someid:attachment"
Guns: #匹配的枪械列表，可为空
- "someid:gunid"
Trigger: "ON_TRIGGER_TYPE" #设定触发器的键值对
Flags: #该映射为属性组
TriggerProbability: 100
# ...
# 属性组中部分非必要的属性配置可省略，此处为演示故全部省略
# ...
ConditionExpression: "ALL_TRUE"
Conditions: [] #该映射为条件块，可为空，意为触发则无条件执行
Actions: [] #该映射为动作块部分，实际不可为空
ReverseActions: null #退出动作块，可为空(null,而非[])
```
有关各键值对的具体含义与配置方法，请参阅下一章节：[基础参数](/hamsterbaron/mechanic-guides/option.md)部分内容。
此处需要特别注意的是：**部分列表类型即便可以为空但仍须写出空数组的键值对**以保证结构稳定，如缺失相关字段将会导致该条技能配置加载出错。
***
## 在游戏内应用机制
当完成了一个技能的配置时，您就可以在游戏中测试它的实际效果了。Arcana 支持配置的热重载，在拥有四级管理员权限的情况下，输入以下指令:
```
/taczexpand reload
```
如果聊天栏出现Reloaded字段，则说明所有已导入的技能均被正常加载。此时，您可以开始进行游戏内的实际技能测试了。
{% hint style="info" %}
**小提示** : 当出现Failed to Reloaded字段时，加载异常的技能其详细错误信息会打印在客户端log中，因此建议使用本地服务端安装 Arcana 以便快捷的在服务端后台输出中查看错误报告。
{% endhint %}
Arcana 通过给 TacZ 枪械物品添加**物品描述**(Lore)以启用机制。选择你想要测试的枪械，在游戏内拿出对应物品，并**丢弃在附近**，确保无其他掉落物的情况下输入以下指令即可使得地面上掉落物形式的枪械获得测试用的物品描述语句。
```
/data merge entity @e[type=item,distance=..5,limit=1] {"Item":{"tag":{"display":{"Lore":["{\"text\":\"TestLore\"}"]}}}}
```
该指令将会为扔出的枪械添加一行内容为“TestLore”的NBT描述文本。所有设置为匹配该字段的机制都会被应用到枪械物品上（如实际制作中设定了其他 Lore 匹配语句，只需要将以下指令中"TestLore"字段换为您设定的字段即可）
{% hint style="info" %}
**小提示** : 每次输入指令太麻烦？尝试使用 NBTEdit 模组，服务端开发环境下可以使用 ILoreEdit 插件，通过可视化界面或简洁指令来快速的为测试枪械添加所需要的描述词条。
{% endhint %}
考虑到机制应用的灵活性，除了匹配描述文本的NBT绑定形式，对于拓展包制作者以及希望更贴合原版模组方式的开发者，Arcana 同样提供直接将机制绑定到配件或枪械上的方案，详细内容请阅读下一章节。
***
## 基础测试技能示范
此处提供了一个教学用的示范技能，在导入游戏并为某一 TacZ 枪械物品添加含有"TestLore"字段的描述后，手持枪械**并击杀任意僵尸**即可在聊天栏看见Hello,<您的游戏ID>字段输出。对于其中的条件块与动作块内容，我们将在后续的章节中详细讲解。
```yaml
Name: "SimpleExample"
Lore: "TestLore"
Attachments: []
Trigger: "ON_KILL_ENTITY"
Flags:
TriggerProbability: 100
Cooldown: 0
KeepCheckTimes: 0
Frequency: 0
RepeatTimes: 0
RepeatDelay: 0
ConditionExpression: "ALL_TRUE"
Conditions:
- !
entities:
- "minecraft:zombie"
Actions:
- !
command: "say Hello,$1"
selector: null
args:
- "SelfName"
delay: null
ReverseActions: null
```
[^1]: 事实上，目前并未出现过因误操作导致的数据损坏问题。但理论上存在此种风险，因此仍然建议您按教程操作。
---
# 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://hamsterbaron.gitbook.io/hamsterbaron/mechanic-guides/getting-started.md?ask=&goal=
```
`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.