diff --git a/docs/.vitepress/zh_cn.ts b/docs/.vitepress/zh_cn.ts index 5f18c2c..9779465 100644 --- a/docs/.vitepress/zh_cn.ts +++ b/docs/.vitepress/zh_cn.ts @@ -3,18 +3,18 @@ import { defineConfig } from 'vitepress' export const zh_cn = defineConfig({ lang: "zh-CN", title: "命令官", - description: "An extension of the data pack system.", + description: "对原版数据包系统的补充模组。", themeConfig: { sidebar: [ { items: [ - { text: 'Welcome!', link: '/zh-cn/' }, - { text: 'Events', link: '/zh-cn/Events' }, - { text: 'Commands', link: '/zh-cn/Commands' }, - { text: 'Arithmetica', link: '/zh-cn/Arithmetica' } + { text: '欢迎', link: '/zh-cn/' }, + { text: '事件', link: '/zh-cn/Events' }, + { text: '命令', link: '/zh-cn/Commands' }, + { text: '算术', link: '/zh-cn/Arithmetica' } ] } ] } -}) \ No newline at end of file +}) diff --git a/docs/zh-cn/Arithmetica.md b/docs/zh-cn/Arithmetica.md new file mode 100644 index 0000000..2b6a820 --- /dev/null +++ b/docs/zh-cn/Arithmetica.md @@ -0,0 +1,57 @@ +# 算术 + +命令官模组凭借动态实体数据,实现了运算表达式的功能。 + +算术使用 [exp4j](https://www.objecthunter.net/exp4j/index.html) 来实现运算功能。掌握它并非必要,但多有好处。 + +## 额外功能 + +本模组在 exp4j 的基础上,添加了一些额外功能。 + +- `round` 能够四舍五入一个值。接受 1 个值。 +- `random` 能在指定范围内生成随机数。接受 2 个值(最小,最大)。 +- `clamp` 将其他两个值约束在范围内。接受 3 个值(值,最小,最大)。 +- `min` 返回两数中的最小数。接受 2 个值(a,b)。 +- `max` 返回两数中的最大数。接受 2 个值(a,b)。 +- `lerp` 平滑地将初值过渡到末值。`初值 + 平滑系数 * (末值 - 初值)`。接受 3 个值(平滑系数,初值,末值)。 + +## 读取源数据 + +因为算术以游戏的战利品功能为情境,你可以通过一种叫"提取"的特殊句法来读取源数据。 +``` +标识符[字段] +标识符[字段$动态数据] +``` +字段对准确度要求极高,在错误的情境下使用会直接使游戏崩溃。 + +示例: +``` +minecraft:this_entity[x] +minecraft:this_entity[living/attribute$generic.max_health] +minecraft:this_entity[rot/x] +minecraft:origin[world/day_time] +``` + +前景:说明所有可用字段。 + +## 使用算术 + +通过使用 `cmd:arithmetica` 命令,你可以快速上手。记得用 `"` 括住表达式来满足格式要求。 + +其他使用情境见 [命令宏](Commands#command-macros) 和 `commander:arithmetica` 的战利品数字提供器。 + +提供 condition(条件)的例子如下,非常简单: + +```json +{ + "condition": "minecraft:value_check", + "value": { + "type": "commander:arithmetica", + "arithmetica": "round(random(5, 15))" + }, + "range": { + "min": 12.3, + "max": 32 + } +} +``` diff --git a/docs/zh-cn/Commands.md b/docs/zh-cn/Commands.md new file mode 100644 index 0000000..ee3e51d --- /dev/null +++ b/docs/zh-cn/Commands.md @@ -0,0 +1,146 @@ +# 命令 + +命令官模组中的命令是你的订阅文件中的主角。 + +命令相当于 JSON 文件中的对象。事件被触发时,`type` 字段将决定哪些命令被执行。 + +`condition` 字段可以应用于所有类型的命令,它能够在当下事件的情境中执行。这一字段使用了原版的条件系统,这个工具 [misode.github.io](https://misode.github.io/predicate/) 可以帮你快速创建条件。 + +部分种类的命令有额外参数。 + +尽管本模组尽量避免在事件外使用命令,其他的项目还是可能把命令整合到其他情境中。这就不在支持范围内了。 + +[[toc]] + +## 内置命令 +本模组内置了少量命令,因为游戏内交互应该交给 `/` 样式的命令,或者函数。 + +### `commander:commands` +这是你在订阅文件中,主要会用到的命令类型。 + +这一种类需要有一个 selector(选择器),以及一系列命令(或函数)。推荐使用函数,因为游戏的函数加载器会在重载时校验它们。 + +::: details 示例 +```json +{ + "type": "commander:commands", + "selector": "commander:random_player", + "commands": [ + "/cmd:explode ~ ~1 ~ 2" + ] +} +``` +::: + +#### 命令宏 + +对于想要在命令中插入一些东西的人,命令宏是不二之选。 + +命令宏就是 `${{}}`,一个能让你从选择器中,动态插入内容的代码块。目前有两种命令宏:字符串宏和算术宏。 + +正如其名,字符串宏能够在命令中插入字符串,比如: +``` +"/say 我的名字是${{origin[world/key]}}!" +``` +这段命令在主世界中执行,将输出 `我的名字是minecraft:overworld`。 + +相比之下,算术宏要有趣得多。算术宏由 [算术](Arithmetica) 支持,你可以在那个页面了解更多关于数学表达式的信息。 + +算术宏永远会返回一个浮点数(比如 `1.7480`),但你可以通过在表达式前加上 `(long)` 来给它截断,比如: +``` +$(long){{random(0, 34)}} +``` + +### `commander:cancel` +这种类型比较特别,只能在特定类型的事件里使用。 + +这一类型只要求具备有合适返回值的 `value` 字段。 + +::: details 示例 +```json +{ + "type": "commander:cancel", + "value": false +} +``` + +```json +{ + "type": "commander:cancel", + "value": "fail" +} +``` +::: + +### `commander:all_of`, `commander:any_of`, `commander:defaulted` +这三种类型的功能相似。如果 condition(条件)返回 true,就执行在可选的 `then` 代码块中的命令。 + +注意:就算条件在很前面就返回 true 了,还是会执行全部命令! + +::: details 示例 +```json +{ + "event": "commander:player_use/item", + "commands": [ + { + "type": "commander:all_of", + "condition": { + "condition": "minecraft:match_tool", + "predicate": { + "items": [ + "minecraft:diamond" + ] + } + }, + "commands": [ + { + "type": "commander:commands", + "selector": "this_entity", + "commands": [ + "/say mmm... diamond..." + ] + }, + { + "type": "commander:cancel", + "value": "success" + } + ] + } + ] +} +``` +::: + +### `commander:random` +这一类型将按权重随机执行其中的命令。默认执行一轮。你可以在非必要的 `rolls` 字段中指定轮次(支持 [算术](Arithmetica))。 + +::: details 示例 +```json +{ + "type": "commander:random", + "rolls": 2, + "commands": [ + { + "weight": 2, + "data": { + "type": "commander:commands", + "selector": "this_entity", + "commands": [ + "/say weight 2" + ] + } + }, + { + "weight": 6, + "data": { + "type": "commander:commands", + "selector": "this_entity", + "commands": [ + "/say weight 6" + ] + } + } + ] +} +``` +::: diff --git a/docs/zh-cn/Events.md b/docs/zh-cn/Events.md new file mode 100644 index 0000000..75c9d09 --- /dev/null +++ b/docs/zh-cn/Events.md @@ -0,0 +1,52 @@ +# 事件 + +事件是游戏内,触发 [命令](Commands) 的节点。 + +## 订阅文件的引入 + +当你订阅文件中声明一个事件时,实际上是在标识你想要订阅的事件。事件可以在 `parameters` 代码块中接受额外的参数,但(目前)内置事件并不要求具备它们。 + +::: details 示例 +```json +{ + "event": "commander:after_killed_by_other" +} +``` +
+ +```json +{ + "event": "modid:custom_event", + "parameters": { + } +} +``` +::: + +订阅文件可以订阅不同的(或者一样的)事件。 + +::: details 示例 +```json +{ + "events": [ + { + "event": "commander:after_killed_by_other" + }, + { + "event": "commander:allow_damage" + }, + { + "event": "commander:player_attack/block" + } + ] +} +``` +::: + +## 内置事件 + +在 `commander` 命名空间下,本模组涵盖了绝大部分兼容的 fabric 事件。这里的返回指 [取消类命令](Commands#commandercancel)。 + +当前可用的事件请见:[实体事件](https://github.com/constellation-mc/commander/blob/main/src/main/java/me/melontini/commander/impl/builtin/events/EntityEvents.java),[玩家事件](https://github.com/constellation-mc/commander/blob/main/src/main/java/me/melontini/commander/impl/builtin/events/PlayerEvents.java),[服务器生命周期](https://github.com/constellation-mc/commander/blob/main/src/main/java/me/melontini/commander/impl/builtin/events/ServerLifecycle.java),[服务器刻](https://github.com/constellation-mc/commander/blob/main/src/main/java/me/melontini/commander/impl/builtin/events/ServerTick.java)。 + +前景:自动生成事件列表。 diff --git a/docs/zh-cn/index.md b/docs/zh-cn/index.md new file mode 100644 index 0000000..36f2e17 --- /dev/null +++ b/docs/zh-cn/index.md @@ -0,0 +1,15 @@ +# 命令官 + +命令官模组是对原版数据包系统的补充。 + +它引入了全新的事件系统,灵活的 json 命令,新的 `/` 类命令,进阶的数学表达式支持,还有更多! + +本模组不会有客户端特性,一切都会在服务端执行。 + +::: danger 注意 +这个模组只能在 Modrinth,CurseForge 和 GitHub 的 Actions 上被下载到。如果你从*其他*任何地方下载这个模组,你的电脑很可能感染类似 [fractureiser](https://github.com/fractureiser-investigation/fractureiser) 的病毒。 + +这个页面 [拒绝模组再分发](https://stopmodreposts.org/)展示了更详细的信息。 + +可别怪我没提醒哦! +:::