diff --git a/assets/tis3d/doc/zh_cn/block/casing.md b/assets/tis3d/doc/zh_cn/block/casing.md new file mode 100644 index 000000000000..1cba2885f7bb --- /dev/null +++ b/assets/tis3d/doc/zh_cn/block/casing.md @@ -0,0 +1,13 @@ +# 机箱 + +![In case of logic](item:tis3d:casing) + +机箱可以安装六个模块。有鉴于机箱必须要连接到[控制器](controller.md)才能发挥作用，所以通常只能连接五个；机箱与机箱之间，或机箱与[控制器](controller.md)之间的面不能连接模块，因为这些面需要用来进行内部通讯。在装有模块的面旁边放置机箱或[控制器](controller.md)将导致模块被强行弹出。 + +机箱可以为每个模块提供四个端口。这些端口可以用来在机箱的棱上传递数据。如果在端口方向有另一个机箱，那么数据就会从连接面中传输过去，发送至相邻模块的对应端口。如果该方向上没有另一个机箱，那么他就会在同一个机箱的相邻面之间传输数据。 + +这意味着每个端口都必然对应着一个模块插槽。但是，如果插槽上并没有安装模块，那么对这个端口进行的任何读写操作都不会产生效果。 + +机箱可以用[钥匙](../item/key.md)来锁定。当机箱被锁定时，模块就不能插入到插槽上，或者从插槽上移除。这可以用来阻止其他玩家的修改，同时也可以避免不小心点击时移除模块。 + +另外，当玩家潜行时，[钥匙](../item/key.md)可以用来开启/关闭任意面的任 意接收端口。当接收端口被关闭时，任何的写入操作都会被阻塞。这可以用来避免将多接口输出的信号输出到不想要的位置。这使得你可以进行非常紧凑的设计，而且还可以帮你省下一些[执行模块](../item/module_execution.md)。否则，你在类似的场景下可 能需要使用更多的[执行模块](../item/module_execution.md)来管理数据的流向（比如说 直接把[红外模块](../item/module_infrared.md)的数据输出到[红石模块](../item/module_redstone.md)）。 diff --git a/assets/tis3d/doc/zh_cn/block/controller.md b/assets/tis3d/doc/zh_cn/block/controller.md new file mode 100644 index 000000000000..578e11bed386 --- /dev/null +++ b/assets/tis3d/doc/zh_cn/block/controller.md @@ -0,0 +1,11 @@ +# 控制器 + +![我有控制权了!](item:tis3d:controller) + +控制器方块是所有TIS-3D计算机的核心。它给所有连接 的[机箱](casing.md)提供能源，并改变TIS-3D计算机的状态。控制器可 以使用普通的红石信号供电，更高的红石信号强度能提升运行速度。特别地，强度为一的红石信号将导致TIS-3D计 算机进入暂停状态，但不会因断电造成复位。 + +一个控制器方块最多可以支持八个[机箱](casing.md)方块。如果更多的机箱方块连接到控制器，控制器将会停止运行，直到其数量减少到八个以内。 + +控制器也不可以互相连接。如果有多个控制器直接或间接连接，控制器也将停止运行，直到将其和其他控制器断开连接。 + +机箱相邻控制器，以及机箱和相邻机箱之间都可以建立连接。 diff --git a/assets/tis3d/doc/zh_cn/block/index.md b/assets/tis3d/doc/zh_cn/block/index.md new file mode 100644 index 000000000000..e1990fe2aead --- /dev/null +++ b/assets/tis3d/doc/zh_cn/block/index.md @@ -0,0 +1,6 @@ +# 方块索引 + +本索引列出了TIS-3D的所有方块。 如果你是来寻找物品的，请前往[物品索引](../item/index.md)。 + +- [控制器](controller.md) +- [机箱](casing.md) diff --git a/assets/tis3d/doc/zh_cn/index.md b/assets/tis3d/doc/zh_cn/index.md new file mode 100644 index 000000000000..4ab856a86177 --- /dev/null +++ b/assets/tis3d/doc/zh_cn/index.md @@ -0,0 +1,18 @@ +# TIS-3D 参考手册 + +"Tessellated Intelligence System是一个大规模并行计算机 架构，由均匀/非均匀的互联的异质节点构成。Tessellated Intelligence System对于那些需要处理复杂数据流的应用 来说十分合适，如自动金融贸易、大数据收集、以及公民行为分析。" +———— *TIS-100参考手册* + +TIS-3D是个三维的TIS系统。它的目的是控制Minecraft世 界中的各种原本需要复杂红石操纵的机器和其它机制。或者说，这只是个有趣的挑战！ + +## 计算机详述 +借助TIS-3D可构建强大的模块化计算机。该计算机包括 一台[控制器](block/controller.md)和最多八个[机箱](block/casing.md)。[机箱](block/casing.md)需要与控制器连接在 一起。注意，与[控制器](block/controller.md)的连接是可以传递的：也就是说， 若[机箱](block/casing.md)`C1`连接到了一台[控制器](block/controller.md)上，[机箱](block/casing.md)`C2`连接到了[机箱](block/casing.md)`C1`上，那么`C2`也会自动与这个[控制器](block/controller.md)相连。 + +计算机有且只能有一台[控制器](block/controller.md)。如果有其它[控制器](block/controller.md)直接或间接地连接，计算机就无法启动。一台计算机如果有超过八个[机箱](block/casing.md)，计算机也无法启动。 + +给[控制器](block/controller.md)在任何面上提供红石信号以启动计算机。计算机的运行速度由红石信号强度决定。若同时为[控制器](block/controller.md)给予多个红石信号会导致未定义行为。请联系[控制器](block/controller.md)制造商以获取整套行为规范，因为提供多个红石信号的行为可能会导致保修失效。提供最小的红石信号将暂停计算机。关闭计算机将完全重置其状态。 + +## 模块详述 +[机箱](block/casing.md)可以安装六个[模块](item/index.md)，每一个都可以被放置在[机箱](block/casing.md)的侧面。每个[模块](item/index.md)有四个端口，分别为：`up`、`right`、`down`、`left`，即上右下左。这些端口可通过[模块](item/index.md)读取和 写入值来进行通信。 + +读写操作会阻塞程序运行。[模块](item/index.md)通常在执行读写操作时进入锁定状态，直到操作完成后才会解除锁定。*对于特定 的供应商，可能存在例外。*两个[模块](item/index.md)在同一共享端口上同时进行读取操作操作，即互相读取，会导致它们陷入死锁，进而无法工作。如果[模块](item/index.md)向一个端口写入数据，但是这个 端口上没有其他[模块](item/index.md)来接收，他也会把自己锁死。重启计算机可解决这个问题。热插拔[模块](item/index.md)在技术上是可行的，但 通常会导致不可预知的结果。 diff --git a/assets/tis3d/doc/zh_cn/item/book_code.md b/assets/tis3d/doc/zh_cn/item/book_code.md new file mode 100644 index 000000000000..a16c3cfae30e --- /dev/null +++ b/assets/tis3d/doc/zh_cn/item/book_code.md @@ -0,0 +1,9 @@ +# 编码书 + +![99个小BUG隐藏在代码里...](item:tis3d:book_code) + +这本编码书（或者它有时被称为**代码圣经**）是TIS-3D程序 员工作时最好的朋友。相比于简陋的书与笔，使用它可以更舒适地为代码打草稿，支持更正，并且更容易发现代码中的潜在错误。 + +要获取编码书，只需手持一本普通的书右键点击安装于[机箱](../block/casing.md)上的[执行模块](module_execution.md)。若要在[执行模块](module_execution.md)上安装程序，首先需在编码书中选中，并对执行模块使用编码书。若要从[执行模块](module_execution.md)复制现有的程序到代码书中，只需潜行对着[执行模块](module_execution.md)使用编码书即可。 + +默认情况下，编码书上的每一页都有单独的一个程序。在给[执行模块](module_execution.md)写入程序的时候，只有当前页的内容会被写入。但是当这一页的最后一行是预处理宏`#BWTM`时，程序内容将延续到下一页。这使得你可以使用多页编写同一个程序。在给[执行模块](module_execution.md)写入程序时，整个多页程序将被一次性写入模块中。 diff --git a/assets/tis3d/doc/zh_cn/item/book_manual.md b/assets/tis3d/doc/zh_cn/item/book_manual.md new file mode 100644 index 000000000000..e0e4b740b267 --- /dev/null +++ b/assets/tis3d/doc/zh_cn/item/book_manual.md @@ -0,0 +1,7 @@ +# TIS-3D 参考手册 + +![黑白色](item:tis3d:book_manual) + +你现在正在阅读的便是TIS-3D参考手册。本手册详细讲 述了TIS-3D计算机各个零件的信息、使用限制、以及将 它们组合在一起的方法。 + +所有基本规格都应在文档中给出，如有遗漏，一般是由于特别要求，以满足供应商的特定需求。 diff --git a/assets/tis3d/doc/zh_cn/item/index.md b/assets/tis3d/doc/zh_cn/item/index.md new file mode 100644 index 000000000000..c2b5336d17a1 --- /dev/null +++ b/assets/tis3d/doc/zh_cn/item/index.md @@ -0,0 +1,25 @@ +# 物品索引 + +本索引列出了TIS-3D的所有物品。 如果你是来找方块的，请前往[方块索引](../block/index.md)。 + +## 模块 +- [音频模块](module_audio.md) +- [捆绑红石模块](module_bundled_redstone.md) +- [显示模块](module_display.md) +- [执行模块](module_execution.md) +- [红外模块](module_infrared.md) +- [键盘模块](module_keypad.md) +- [队列模块](module_queue.md) +- [随机模块](module_random.md) +- [RAM模块](module_random_access_memory.md) +- [ROM模块](module_read_only_memory.md) +- [红石模块](module_redstone.md) +- [串口模块](module_serial_port.md) +- [栈模块](module_stack.md) +- [终端模块](module_terminal.md) +- [记时器模块](module_timer.md) + +## 实用工具 +- [钥匙](key.md) +- [TIS-3D 参考手册](book_manual.md) +- [编码书](book_code.md) diff --git a/assets/tis3d/doc/zh_cn/item/key.md b/assets/tis3d/doc/zh_cn/item/key.md new file mode 100644 index 000000000000..24699491ed0b --- /dev/null +++ b/assets/tis3d/doc/zh_cn/item/key.md @@ -0,0 +1,15 @@ +# 钥匙 + +![周围有骷髅吗?](item:tis3d:key) + +钥匙可以很方便地锁定[机箱](../block/casing.md)配置，以防止各种意外或恶意操作，诸如错误安装机箱或模块等。 + +本钥匙使用了一种先进的指纹验证技术，它可为每个方块产生一个唯一的签名。 + +用钥匙锁定[机箱](../block/casing.md)后，模块不能拆除或安装，大多数模块也不能更改配置。执行模块将不能被更改(内部还是可以工作)，然而，键盘模块依然允许用户输入。 + +务必保管好钥匙。一旦钥匙遗失，只有强行破坏方块并重构方可解锁。 + +在潜行时，钥匙还可以用来打开/关闭[机箱](../block/casing.md)任意面的任意端口。查看[机箱](../block/casing.md)的手册页面以获得更多信息。 + +*注：被骷髅钥匙锁定的机箱不能被普通钥匙解锁。* diff --git a/assets/tis3d/doc/zh_cn/item/module_audio.md b/assets/tis3d/doc/zh_cn/item/module_audio.md new file mode 100644 index 000000000000..1e222f5bab42 --- /dev/null +++ b/assets/tis3d/doc/zh_cn/item/module_audio.md @@ -0,0 +1,15 @@ +# 音频模块 + +![蜂鸣](item:tis3d:module_audio) + +音频模块基于数字信号，对声音进行合成。其所发出的声音由输入到模块的值决定，定义见下文。若音量定义为0，该信号将被丢弃。 + +音频模块连续地从四个端口中的任意一个读取出数值，并基于所读取的值发出声音。这种高效的编码模式使得这个模块可以更轻松地进行交互。 + +## 技术规范 +由音频模块接收的每个值被解释为一个组：乐器、音量和音高。详细数据如下： +- `0xFF00` 包含音调。 +- `0x00F0` 包含音量，支持[0，5]。 +- `0x000F` 包含乐器，支持{0，1，2，3，4}中的一个。 + +在将各个参数合成为一个参数时，[执行模块](module_execution.md)的位操作已经被证明十分有用。 diff --git a/assets/tis3d/doc/zh_cn/item/module_bundled_redstone.md b/assets/tis3d/doc/zh_cn/item/module_bundled_redstone.md new file mode 100644 index 000000000000..7eec35994994 --- /dev/null +++ b/assets/tis3d/doc/zh_cn/item/module_bundled_redstone.md @@ -0,0 +1,16 @@ +# 捆绑红石模块 + +![16合1](item:tis3d:module_bundled_redstone) + +捆绑红石模块用于实现TIS-3D与各厂商生产的捆绑红石 线缆的相互通信。它**仅能**与捆绑电缆连接。针对各种常规的绝缘红石线缆，请参阅常规[红石模块](module_redstone.md)获取更多信息。由于接口有多个频道，捆绑红石模块需要一个更高级的协议。就像普通的[红石模块](module_redstone.md)它允许读取和发送信号。注意，捆绑红石模块将不执行任何信号处理。非法值会导致未定义行为。请查阅您捆绑电缆供应商的技术规范以确定合法数值。 + +捆绑红石模块有一个活动频道的概念。这决定了模块从哪个频道读取数值。活动频道可以通过提供特定格式的数据来改变(请查阅**技术规范**)。该模块从他的四个输入端口读取参数，解码之后会将给定的信号强度输出到给定的频道(请查阅**技术规范**)。 + +## 技术规范 +捆绑红石模块从端口读取的值被解释为两个单独的值，一个在高位字节( `0xFF00`)另一个在低位字节( `0x00FF`)。高位字节通常代表着将写入的频道。作为唯一的例外，如果高位字节等于`0xFF`低字节包含的数据将用以设置活动频道。换句话说，设置活动频道，也就是读取数据的频道时，高位字节必须包含`0xFF`，而低位字节则是将被激活的 频道编号。 + +这个例子展示了如何设置执行模块左侧的捆绑红石模块，使其激活6频道： +`MOV 0XFF ACC` +`SHL 8 # HI = 0xFF` +`ADD 6 # LO = 6` +`MOV ACC LEFT` diff --git a/assets/tis3d/doc/zh_cn/item/module_display.md b/assets/tis3d/doc/zh_cn/item/module_display.md new file mode 100644 index 000000000000..582376e21f44 --- /dev/null +++ b/assets/tis3d/doc/zh_cn/item/module_display.md @@ -0,0 +1,40 @@ +# 显示模块 + +![按数字进行绘制](item:tis3d:module_display) + +显示模块提供了一套高度灵活的方法，可用于在二维有色网格中以可视化方法呈现任意数据(编者注：孩子们喜欢叫他们“像素”)。通过向显示模块的任意一个端口写入一个数字序列，你可以改变这些单元的颜色。这个数字序列包含了将要填充的矩形的颜色码，位置和大小。 + +显示模块将从它的4个端口中不断读取数据，每五个值组成一次绘制调用。一旦一个绘制调用所需的五个数字都被接收，所描述的矩形将会被绘制到到彩色网格中。 + +## 绘制技术规范 +显示模块收到5个值组成的序列，会被依次解释为这些绘制调用的参数：颜色、列、行、宽度和高度。网格是由28行和28列组成的正方形。颜色的值由固定的颜色表决定。 +确切的颜色值可能因供应商而异，但一般颜色名称遵循这个世界的规范： +- `0`: 白色 +- `1`: 橙色 +- `2`: 品红 +- `3`: 浅蓝 +- `4`: 黄色 +- `5`: 黄绿 +- `6`: 粉色 +- `7`: 灰色 +- `8`: 银白 +- `9`: 青色 +- `10`: 紫色 +- `11`: 蓝色 +- `12`: 棕色 +- `13`: 绿色 +- `14`: 红色 +- `15`: 黑色 + +提供非法的颜色和坐标会引起未定义的行为，但是由于供应商处理谨慎，总体上都会被妥善解决。 + +下面是一个简单的程序，可以绘制不同颜色的竖线： +`MOV 16 ACC` +`LOOP:` +`SUB 1` +`MOV ACC LEFT # COLOR` +`MOV ACC LEFT # X` +`MOV 0 LEFT # Y` +`MOV 1 LEFT # WIDTH` +`MOV 28 LEFT # HEIGHT` +`JNZ LOOP` diff --git a/assets/tis3d/doc/zh_cn/item/module_execution.md b/assets/tis3d/doc/zh_cn/item/module_execution.md new file mode 100644 index 000000000000..f0c6733dd100 --- /dev/null +++ b/assets/tis3d/doc/zh_cn/item/module_execution.md @@ -0,0 +1,129 @@ +# 执行模块 + +![执——行!](item:tis3d:module_execution) + +执行模块是编程TIS-3D计算机的主要手段。当它被安装 在[框架](../block/casing.md)上时，用一本写有代码的书对其使用就可以对它进行编程。为了更愉快的编程体验，你可以考虑投资一本[编码书](book_code.md)。这是任何一个职业码农都应当拥有的，广为使用而久经测试的编程工具。 + +## 架构 +执行模块允许用户以极大灵活性控制TIS-3D计算机的操 作。每个执行模块可使用原始汇编语言进行编程，当然还带有一些优化过的指令集。激活时，执行模块将会从第一个指令开始，逐一处理指令。所有跳转指令以外的指令都会使程序计数器增加一，这样当这条指令执行完时，程序就会自动运行下一条指令。如果程序计数器离开指令的有效范围内(最后一条)，程序会自动从第一条指令执行。**这直接意味着程序循环**。 + +指令可以对不同类型的目标进行操作。一个目标可以是有效的数据源，或者是可以写入数据的目标。这包括执行模块的四个端口，执行模块的寄存器和少量的虚拟寄存器和端口。 + +一台TIS-3D计算机，或者说一个执行模块，支持16位的值 范围，符号值范围为-32768至32767。*由于技术上的限制，一些模块，包括执行模块，也许会将数值显示为无符号十六进制*。 + + +## 执行目标 +`ACC` +寄存器。这是一个执行模块的首要寄存器。数学运算经常将它们的运算结果储存到这个寄存器中。 + +`BAK` +不可寻址寄存器。这是一个特殊的寄存器，只可以与ACC进行交互，而不可以被直接寻址。你可以通过`SAV`和`SWP`两个指令写入和读取BAK中的数值。 + +`NIL` +虚拟寄存器。这是一个假的目标。你可以通过把值写入到这个寄存器中来将其销毁。当你从`NIL`读取时，他会提 供零值。 + +`LEFT`, `RIGHT`, `UP`, `DOWN` +端口。这几个目标代表着执行模块的四个端口。总体而言，对外部端口的读写操作要慢于对寄存器的操作速度。 + +`ANY` +虚拟端口。这是一个虚拟的目标，他会对所有的端口同步地进行操作。不过他实质上只会对第一个有效端口进行操作。举个例子，`MOV 10 ANY`会尝试向所有端口写入数值10，但是当数值被任意一个端口接收后，其余端口均不会再次接收这个数值。任何一个端口上成功的写入操作都会取消后续的尝试。 +[前译者注：经本人实验，从ANY读入时，如果同时有多个接口输入，优先级是：左>右>上>下；向ANY输出时，如果同时有多个接口可以输出，优先级是上>左>右>下] + +`LAST` +虚拟端口。这是一个虚拟的目标，将会指代最近用ANY伪端口读入或写出的端口。 + +## 编程语言参考 +除去指令列表，提供给执行模块的汇编代码还有可能包含元数据：注释是在编译执行时会被完全忽略的文本。标签（Label）是可以给跳转指令提供定位的标记。注释，标签和空行对于一个已经完成编译的程序而言，在寻址时不会产生任何影响。这在使用'JRO'指令时可能会有参考作用。 + +### 注释（Comments） +注释由开头的井号（`#`）所标记。他们可以作为一个完整的行，也可以附加在指令或者标签代码后。 +例: +`# Single line comment` +`LOOP: # Start of loop` +`MOV 0, ACC # Reset` + +### 标签（Labels） +标签是一个由冒号（':'）结尾的字符串。标签永远指代着 尾随其后的代码。当被作为跳转指令的目标使用时，程序将会直接跳转到该标签的位置。值得注意的是，你可以用单独的一行作为标签，也可以将一些指令添加在标签后方。这对程序的执行不会有任何影响。 +例: +`START: MOV 8, ACC` +`LOOP:` +`SUB 1` +`JGZ LOOP` +`JMP START` +`# Never reached` + +### 指令（Instructions） +`NOP` +这是一条伪指令，他不会对执行模块的任何寄存器和端口产生影响。也就是说，完全不会影响执行模块的状态。编译时，他会被自动替换为`ADD NIL`。 + +#### 数据转移 +`MOV ` +将`SRC`中的数据转移到`DST`中。上文中已经给出了可用目标的列表。值得一题的是，对内部寄存器或者状态的操作会明显快于对端口的操作。具体的时间消耗并不会在该指南中提供，请参考制造商提供的文档。另外，将数据写入`NIL`相当于直接丢弃数据。 +例: +`MOV 8, ACC` 将8写入`ACC`寄存器。 +`MOV LEFT, RIGHT` 从左侧端口读入，写入右侧。 +`MOV DOWN, NIL` 从下部端口读入，写入`NIL`。 + +`SWP` +将`ACC`和`BAK`寄存器中的值互换。 + +`SAV` +将当前`ACC`中的值写入`BAK`。 + +#### 数学操作 +`ADD ` +从目标`SRC`中读取数据，和当前`ACC`的数据相加，再将结果 赋值给`ACC`。请注意这个操作中的溢出值会被削除。运算结果会被限制在有效值范围内。 +例: +`ADD 1` 把1加到`ACC`的当前值。 +`ADD LEFT` 从左侧端口读取值，加到`ACC`上。 + +`SUB ` +从目标`SRC`中读取数据，从当前`ACC`的数值中减去该值，再 将结果赋值给`ACC`。请注意这个操作中的溢出值会被削除。运算结果会被限制在有效范围以内。 +例: +`SUB 1` 将`ACC`的当前值减小1。 +`SUB LEFT` 从左侧端口读取值，从`ACC`中减去。 + +`NEG` +计算`ACC`中数字的相反数，再赋值给`ACC`。 + +### 位运算 +TODO + +### 流程控制 + +`JMP