稀里糊涂的commands.json全解析 - 游戏技巧

土球球

本帖最后由 ustc_zzzz 于 2018-3-4 14:47 编辑

稀里糊涂的commands.json全解析

作为一个萌新第二次在游戏技巧版块发表主题。

原作者：@ustc_zzzz。本文基于Minecraft 1.13快照：Minecraft 18w09a。

引言

预备知识

我们应该怎么看待/tp zzzz_ustc 233 33 333这个命令呢？

先读入一个字符串，并发现它是"tp"，然后我们去找一找"tp"接下来应该让我们做什么。
"tp"告诉我们接下来先试着读进来一个实体，然后接着我们读取了一个实体，它是一个名为zzzz_ustc的玩家，然后我们看看接下来还应该读取什么。
接下来什么都不应该读取了——游戏告诉我们。哎呀那说明这个解析方式错了（但是对于诸如/tp zzzz_ustc这样的命令，这种解析方式是成功的），我们回退一步，到第2步还没开始的时候。
然后"tp"告诉我们如果失败了，可以再试试着连着读进来三个数字当作坐标，然后我们读进了"zzzz_ustc 233 33"。
游戏发现"zzzz_ustc 233 33"根本不是一个坐标——该死，又解析错了（但是对于诸如/tp 233 33 333这样的命令，这种解析方式是成功的），我们回退一步，到第4步还没开始的时候。
然后"tp"告诉我们如果失败了，可以再试试先读取一个或多个实体，然后我们接下来和第2步一样，读取了一个名为zzzz_ustc的玩家。
接下来游戏告诉我们，应该再读取一个实体，然后我们接下来读取了一个名为233的实体——似乎没这个实体，不过我们先不管他，再接着看游戏怎么让我们解析的。
游戏告诉我们不应该再有参数了——可是还剩着两个呢，所以又解析失败了（但是对于诸如/tp zzzz_ustc xuan_su这样的命令，这种解析方式是成功的）~~（玄素：这口锅我不背）~~，我们回退到第7步还没开始的时候。
现在已经解析的部分是"tp zzzz_ustc"，游戏告诉我们再连着读进来三个数字当作坐标，很好，我们读取进来了"2333 33 333"。
游戏又告诉我们可以停止解析了——正好，我们也没多余的参数，解析大成功，可以开始执行了。

刚刚在解析的过程中，我们轮流匹配了以下四条规则：

/tp 一个实体
/tp 一个由三个数字组成的坐标
/tp 一个或多个实体一个实体
/tp 一个或多个实体一个由三个数字组成的坐标

前三个规则都匹配失败了，而最后一个规则完成了匹配。

我们还用到了两个parser：

一个parser读取一个字符串当作实体。
一个parser读取连着的三个整数当作坐标。

整个1.13的命令解析机制，也就是如此。

开始理解commands.json

整个commands.json的获取方式请参阅本人在帖子开头处给出的链接。

以下所有...的形式代表内容太长且与本帖无关的内容，故本帖直接省略。

整个commands.json本身长这样：

{
"type": "root",
"children": {
"advancement": {...},
"ban": {...},
...
"xp": {...}
}
}

复制代码

type本身共有三种：

root只会出现在JSON的根节点处，代表从children中选一个命令开始解析。
literal代表匹配字符串本身。
argument代表匹配某种特定类型的参数，匹配方式由特定parser决定。

我们在匹配tp命令时使用的JSON子节点如下：

"tp": {
"type": "literal",
"redirect": [
"teleport"
]
}

复制代码

这里的redirect看起来代表这个命令本身是teleport的别名，但实际上redirect代表这个命令接下来的部分交由该命令解析，不总是代表一个命令是另一个的别名（很快我们就能看到反例）。也就是说/tp zzzz_ustc 233 33 333中"zzzz_ustc 233 33 333"这一部分被当作/teleport zzzz_ustc 233 33 333中的相应部分解析。

然后我们切换到了teleport命令：

"teleport": {
"type": "literal",
"children": {
"destination": {
"type": "argument",
"parser": "minecraft:entity",
"properties": {
"amount": "single",
"type": "entities"
},
"executable": true
},
"location": {
"type": "argument",
"parser": "minecraft:vec3",
"executable": true
},
"targets": {
"type": "argument",
"parser": "minecraft:entity",
"properties": {
"amount": "multiple",
"type": "entities"
},
"children": {
"destination": {
"type": "argument",
"parser": "minecraft:entity",
"properties": {
"amount": "single",
"type": "entities"
},
"executable": true
},
"location": {
"type": "argument",
"parser": "minecraft:vec3",
"children": {...},
"executable": true
}
}
}
}
}

复制代码

我们解析/teleport zzzz_ustc 233 33 333的时候，首先看到了type为literal，所以我们先匹配一个teleport字符串。
然后我们轮流匹配children中的内容，首先选取destination，它的type为argument，匹配方式由parser，也就是minecraft:entity决定。executable为true代表试图匹配后面没有参数的情况。刚刚我们得知，匹配失败了。
接下来是location，它的type也为argument，匹配方式由minecraft:vec3这一parser决定，因此游戏试图读取三个连续的整数作为坐标。executable为true代表试图匹配后面没有参数的情况。刚刚我们也得知，匹配又失败了。
然后是targets，它的type也为argument，匹配方式由minecraft:entity这一parser决定，所以游戏首先匹配了一个名为zzzz_ustc的实体，然后游戏接着从它的children里匹配内容。
- 第一个试图匹配的是destination，情况和上面的类似，不作赘述。不过这次也是失败的。
- 第二个试图匹配的是location，这次成功了。由于它的executable为true，所以我们可以匹配后面没有参数的情况。如果它的后面还有参数，那就再接着匹配location的children，感兴趣的读者可以自己打开JSON查看分析。

我们再来看一个相对复杂的，execute的例子：

"execute": {
"type": "literal",
"children": {
"align": {...},
"anchored": {...},
"as": {
"type": "literal",
"children": {
"targets": {
"type": "argument",
"parser": "minecraft:entity",
"properties": {
"amount": "multiple",
"type": "entities"
},
"redirect": [
"execute"
]
}
}
},
...
"run": {
"type": "literal"
},
...
}
}

复制代码

我们以/execute as @a run tp xuan_su为例。

首先匹配字符串execute，略过不提。
然后我们从children里找到了as，它的type是literal，于是我们再匹配一个as。
然后我们从children里找到了targets，它的type是argument，其parser匹配一个或多个实体，于是我们又匹配到了一个实体选择器，这里是@a。
然后我们发现targets没有children了，但是它有一个redirect，按照之前对于redirect的解释，后续的run tp 233 33 333被当作/execute run tp 233 33 333的相应部分处理。
然后我们读取一个execute，又切换到了run。run是全commands.json中唯一一个既没有children和redirect，也没有executable的用于命令匹配的JSON节点。1.13看起来对其的处理是把后续的内容直接按照从头开始的命令解析，这也挺符合execute命令本身的。
然后命令解析完成并开始执行，一群不幸的玩家全都被传送到了玄素那里。

到此commands.json的内容就大概讲清楚了。最后再讲一点parser的属性相关的东西。

parser及其属性

后记

我们可以看到，基于这样的一个JSON，我们可以很容易地做出来一些命令检查系统或者类似的东西。比如说一个最简单的应用，本人编写了不到40行的JavaScript代码把JSON转换成了一个输入/help后出现的列表，该列表和游戏内的实际输出丝毫不差。这段代码是本人随便写的，理解起来应该也不难。

该代码基于Node v8.9.4。如欲使用，把该段代码复制保存，然后把commands.json放置于同目录下，执行完成后查看commands.output.txt这一输出文件即可。

// Licensed under WTFPL (https://en.wikipedia.org/wiki/WTFPL)
const fs = require('fs'), path = require('path')
const visitors = {
root: visitJSONRoot,
literal: visitJSONLiteral,
argument: visitJSONArgument
}
function* visitJSON(json, key, prefix) {
for (let line of visitors[json.type](json, key)) yield (prefix || '') + line
}
function* visitJSONRoot(json) {
for (let i in json.children) yield* visitJSON(json.children[i], i)
}
function* visitJSONLiteral(json, key) {
if (json.executable) yield key
else if (!json.children && !json.redirect) yield `${key} ...`
for (let i in json.redirect) yield `${key} -> ${json.redirect[i]}`
for (let i in json.children) yield* visitJSON(json.children[i], i, `${key} `)
}
function* visitJSONArgument(json, key) {
if (json.executable) yield `<${key}>`
else if (!json.children && !json.redirect) yield `<${key}> ...`
for (let i in json.redirect) yield `<${key}> -> ${json.redirect[i]}`
for (let i in json.children) yield* visitJSON(json.children[i], i, `<${key}> `)
}
let outputFileData = ''
let inputFileData = fs.readFileSync(path.join(__dirname, 'commands.json'), 'utf8')
for (let line of visitJSON(JSON.parse(inputFileData))) outputFileData += line + '\n'
fs.writeFileSync(path.join(__dirname, 'commands.output.txt'), outputFileData, 'utf8')

复制代码

然后我只圈一个人： @pca006132 （催更）（噫，没蓝）。

最后我想对插件开发者说两句：

插件中仍然会大量出现自定义命令。如果你是Bukkit插件开发者，你可能已经适应了通过分析一个数组长度或者什么传统的方式解析命令。而这种基于parser的命令解析方式十分强大，可读性很好，也不容易出错。对于Sponge插件开发者来说，SpongeAPI目前已经内嵌了这种基于parser的命令解析方式。随着1.13的发布，你一定会在代码中看到，或自己尝试应用这种，强大、方便、又安全的基于parser的命令解析方式。毕竟，Minecraft 1.13，无疑是命令的一次革新。

3TUSK

插一句：
https://gist.github.com/Dinnerbo ... ee2d8fc64514fb76de8
还记得 Dinnerbone 发的那个奇怪的推吗？那个推提到了一个 gist（上面给的就是），其中出现的巨大的 JSON 文件，现在看来很可能就是这个。
我对这个 JSON 理解是“全部 Minecraft 命令的语法树（请允许我使用这个词来称呼它）合并在一个文件里”。换言之，这个 JSON 描述了所有原版 Minecraft 指令的正确使用方式（虽然，这个文件不是给人看的）。
zzzz 这个贴给出了这个文件的一个十分明显的用途。
事实上，如果我们把脑洞再开得大一点，我们可以做出一个“适用于 Minecraft 1.13 Release 及以上版本的，外置的，Minecraft 命令集成开发环境”。这样一个奇葩的集成开发环境有什么用呢？
1. CB 玩家可以用它在不开游戏的情况下写 mcfunction（自带语法高亮）并进行调试...
2. Mod/插件开发者可以用它来制作生成对应的命令的具体实现，加速命令的开发（搞不好可以做图形化）...

好了脑洞结束，撤了

leavessoft

对开发者很友好啊

pca006132

u.s.knowledge 发表于 2018-3-4 06:30
插一句：
https://gist.github.com/Dinnerbone/7370a2846953eee2d8fc64514fb76de8
还记得 Dinnerbone 发的 ...

对cb玩家来说，早就有了...
两个都是我写的(跑)

玄素

解析方式的变更还带来了一些比较有意思的东西。
一则，应该很明显能发现，现在的命令错误提示比以前的版本，友好度提高了非常多。这意味着对命令中出现的错误，查知起来的成本更低。同样，也更容易能让新玩家了解到如何去寻找自己命令中的差错，而不是和以前一样全凭经验来做查验。
二则，虽然大部分命令没有在1.13的命令变更中做调整，但依旧有一些变化悄然发生在了这场变革之中。比如由/entitydata来的/data entity命令选择器参数处仅接受一个实体，而服务器玩家操作命令系列（/ban，/kick之类）也开始接受选择器（虽然依旧要求三级op权限而不能被命令方块执行）。这些细微之处的变化不容易察觉，但使用时可能没准一不留神就栽进去了，万望谨慎。

pca006132

u.s.knowledge 发表于 2018-3-4 06:30
插一句：
https://gist.github.com/Dinnerbone/7370a2846953eee2d8fc64514fb76de8
还记得 Dinnerbone 发的 ...

实际上呢，调试是不可能的
你鬼知道里面实际游戏机制是咋样啊

3TUSK

pca006132 发表于 2018-3-4 11:29
实际上呢，调试是不可能的
你鬼知道里面实际游戏机制是咋样啊

你可以模拟一个。~~于是上来就有了各种各样的标准库...~~

langyo_v3

https://github.com/langyo/SyntaxBuilder/blob/master/Example/cpp.sb

为何Mojang的脑洞和我碰一起了？…
(这是本人最近在实验的SyntaxBuilder语言的配置文件，用于部分解析C++语言)(这语言简称什么？当然是SB了…别想歪了，我没骂人)

chyx

langyo_v3 发表于 2018-3-11 13:29
https://github.com/langyo/SyntaxBuilder/blob/master/Example/cpp.sb

为何Mojang的脑洞和我碰一起了？… ...

从来没听说过有任何不为你的人理解你的脑洞

qq2799660499

明白了呃zzzz

00ll00

executable为true代表试图匹配后面没有参数的情况。

这里好像有些问题。executable为true应该只是代表如果这之后没有参数的话这个命令是可以执行的，也就是如果后面还有参数的话也可以继续解析。
例如新版的kill

所以tp命令那里究竟是怎样解析的呢……