Machine
概述
Machine 把机器设计变成了配置。一个 Machine Definition 条目描述一种机器：它有多少个输入、输出、燃料和升级槽位，它处理什么，消耗多少燃料和能量，外观如何，全息图显示什么，以及一位玩家或一座岛屿可以放置多少台。扩展会读取该定义并运行每一台已放置的机器。熔炉、粉碎机、圆石生成器或刷怪机都是一个条目，而不是代码。
机器属于 BTC Sky 岛屿。机器只能放置在玩家自己的岛屿上，受每位玩家和每座岛屿的限制约束，其层级由岛屿的研究树解锁。能量和液体在岛屿的一个维度内共享：发电机和蓄电池构成一个池，该维度中每台已连接的机器都从中取用。
这是 TypeWriter 的 BTC 构建版（BTC Core，Paper 或 Folia）的私有扩展，此处的文档仅供参考。其运行时对 Folia 是安全的：槽位缓存在内存中，并异步保存。
功能
- 每台机器一个条目 — 槽位、配方、燃料、能量、外观、全息图、限制和自动化都位于同一个 Machine Definition 中。
- 27 种处理类型 — 配方机器（熔炼、粉碎、锯切、混合、酿造…）、存储、物流、区域机器、能源机器、刷怪笼、粉碎怪物机等。
- 多输入和随机配方 — 额外的输入和输出、基于概率的输出、液体的输入和输出、目录物品以及原版药水。
- 共享的能源网络和液体储罐 — 蓄电池、发电机和储罐按岛屿维度汇集；机器可以从网络中断开。
- 层级和升级模块 — 由 BTC Sky 研究解锁的永久层级，以及与之叠加的可拆卸模块（速度、产量、时运、范围、过滤、容量、液体燃料）。
- 岛屿保护和限制 — 仅限在自己的岛屿上放置、建造标志，以及每位玩家、每座岛屿和每个维度的上限。
- 红石和漏斗 — 红石模式、弹出、比较器输出和完成脉冲，以及漏斗传输。
- 全息图 — 每台机器上方带有进度条的状态文本，完全采用 MiniMessage 格式。
- 仪表盘菜单 — 列出该维度每台机器及其状态、能量和连接状态的菜单。
- 持久化 — 已放置的机器、物品栏、能量和进度保存在 Machine Data Artifact 中。
安装
- 安装带有 BTC 构建版（Paper 或 Folia 上的 BTC Core）的 TypeWriter。
- 安装 Machine 所依赖的扩展：Quest、RPGBundle（RPG Core）、BTC Sky、BTCMobs 和 GuiAndDialogs（共享的 GUI 层）。
- 可选：如果某个定义使用
FURNITURE或CUSTOM_BLOCK外观，请安装 CraftEngine；若要使用占位符，请安装 MiniPlaceholders。 - 将 Machine 的 JAR 放入
plugins/Typewriter/extensions/，然后重启服务器。 - 只有当 BTC Core 提供红石信号发射时，红石比较器输出和完成脉冲才会生效。
快速上手
创建一台把铁矿石熔炼成铁锭的熔炉：
- 在 TypeWriter 网页面板中，打开一个 static 页面，添加一个 Machine Data Artifact。它存储每一台已放置的机器。此后请不要更改它的
artifactId，否则已保存的机器会丢失。 - 在同一个页面上，添加一个 Machine Definition。为它设置
name，并保持processingType为SMELTING。 - 将
storageRef设为第 1 步中的 artifact。 - 在
recipes中添加一个配方：inputMaterial为IRON_ORE，outputMaterial为IRON_INGOT，outputAmount为1，cookTime为200（单位是 tick，即 10 秒）。如果机器必须燃烧燃料，请让fuelCost保持在1或更大。 - 在
fuelTypes中，添加COAL，并设置burnTime和fuelValue。 - 将
spawnItem设为玩家用来创建机器而放置的物品。定义需要有spawnItem或vanillaBlock，否则在发布时会被拒绝。 - 可选：设置
perIslandLimit来限制每座岛屿上的数量。 - 发布。把该物品放置在你自己的岛屿上：机器会连同它的全息图一起出现，右键点击会打开它的菜单。
vanillaBlock（例如 BREWING_STAND）会让定义接管该原版方块：放置它就会创建机器。原版方块的转换不受放置限制警告的约束，因为上限同样会限制原版方块本身。
工作原理
机器由一个定义（条目）加上若干实例（放置在世界中的副本）构成。定义在运行时永远不会改变；每个实例保留自己的物品栏、能量储备和进度。
定义模型
Machine Definition 的每个字段都属于以下分组之一：
| 分组 | 字段 | 控制的内容 |
|---|---|---|
| 类型 | processingType, behaviors | 机器做什么。behaviors 是可选的，为空时由类型推导。 |
| 槽位 | inputSlots, outputSlots, hasFuelSlot, upgradeSlots, essenceSlots, filterSlots, shearsSlots, maxPerSlot | 物品栏布局。机器布局最多 54 个槽位。 |
| 配方和燃料 | recipes, fuelTypes | 放入什么、产出什么、需要多长时间以及消耗什么。 |
| 能量和液体 | energyCapacity, energyGenerationPerTick, liquidTankCapacity, liquidFuelName | 对池的贡献和液体处理。 |
| 成长 | tiers, allowedUpgrades, upgradeSpecs | 永久层级和可拆卸模块。 |
| 外观 | spawnItem, visualType, furnitureId, customBlockId, alignWithPlayerYaw, hologram* | 物品、模型和全息图。 |
| 放置 | machineLimit, perIslandLimit, islandLimitUpgradeKey, dimensionScope, vanillaBlock | 谁可以放置、在哪里放置以及能放置多少。 |
| 自动化 | hopperInterval, hopperTransferAmount, redstoneMode, ejectWhenPowered, redstoneComparatorOutput, redstonePulseOnComplete, redstonePulseTicks | 漏斗和红石。 |
| 持久化 | storageRef, guiStorageRef | 实例和 STORAGE 内容的保存位置。 |
处理类型
| 类别 | 类型 |
|---|---|
由 recipes 驱动的配方机器 | SMELTING, LIQUID_SMELTING, MULTI_SMELTING, GRINDING, SAWING, MIXING, COMPACTING, ENRICHING, RECYCLING, BREWING, AUTO_CRAFTING, INDUSTRIAL, GENERIC |
| 生产 | GENERATOR（无输入：随时间产出配方的输出，可选择消耗能量） |
| 存储和物流 | STORAGE, SORTING（每个过滤槽位占用一侧）, CONVEYOR（有方向的传送带） |
| 区域机器 | VACUUM（vacuumRange）, SHEARING（shearRange, shearInterval, shearsSlots） |
| 能量 | ENERGY_CELL, ENERGY_GENERATOR, CHARGING（chargeables, chargeRatePerSecond） |
| 实体 | ASSEMBLER（assemblerMode 为 SPAWN 或 COLLECT, assemblerEntityType, assemblerMobId, assemblerIngredients, assemblerEnergyCost, assemblerInterval, assemblerRange, spawnerUpgrades）, MOB_GRINDING（grinder* 字段）, EXPERIENCE_TANK（experienceCapacity） |
| 特殊 | CONTROL_PANEL（运行 panelOpenCommand / panelAltCommand，无法被拾起）, TRANSMUTATION（将物品上最高的附魔转移到书上，以换取经验瓶） |
当没有声明任何配方时，SMELTING 和 AUTO_CRAFTING 会回退到原版配方。所有其他配方数为零的配方机器会接受物品并永远处于空闲状态；扩展会在发布时记录一条警告。
能量和液体
能量存储在 ENERGY_CELL 机器中。岛屿维度的池是其所有已连接蓄电池之和。ENERGY_GENERATOR 机器向其供能，消耗者则从中取用。机器一经放置就会加入其所在维度的网络；Machine Link 按钮（或仪表盘）可以把它从网络中断开并重新接入。主世界的蓄电池永远不会给下界的机器供能。
液体储罐的工作方式相同：已连接的机器可以访问其所在维度的每个储罐，未连接的则只能看到自己的储罐。配方通过 liquidInputName/liquidInputAmount 和 liquidOutputName/liquidOutputAmount 来消耗或产出液体。
层级和升级模块
- 层级（
tiers）是永久性的。每个层级指定了解锁它的 BTC Sky 研究节点（researchNode），并设置速度、产量和能量的倍率、时运概率以及额外的槽位。请按升序列出层级：已解锁的最高层级会作用于该岛屿上这种机器的每一台。researchNode为空白的层级会被拒绝。 - 升级模块（
upgradeSpecs）是放入升级槽位中的物品。itemId是 BTC 物品 id（推荐使用），material是备用方案。它的type（SPEED、YIELD、ENERGY_EFFICIENCY、FORTUNE、RANGE、FILTER、CAPACITY、LIQUID_FUEL）只有在列入allowedUpgrades时才会生效。 - 层级和模块的效果会相乘。
菜单
Machine Menu 是由共享 GUI 扩展的布局构建的 GUI（layoutPool、mainLayoutId、inventoryRows）。布局中 buttonType 为 Machine 按钮的物品会被填入实时数据：
| 按钮类型 | 效果 |
|---|---|
MACHINE_OPEN, MACHINE_SMELT, MACHINE_COLLECT, MACHINE_STATUS, MACHINE_FUEL | 标准的机器动作和状态显示。 |
MACHINE_LINK | 将机器连接到其维度的网络，或断开连接。 |
MACHINE_PICKUP | 移除已打开的机器，并将其作为物品归还。 |
NAV_BACK, NAV_CLOSE | 返回或关闭。 |
MACHINE_GRID_INFO | 该维度的摘要：机器数量、已存储的能量、容量、产出、消耗和收支平衡。 |
MACHINE_ENTRY | 每个带标签的槽位对应该维度中的一台机器。左键点击切换其全息图，右键点击切换其网络连接。 |
MACHINE_LIST_ARROW | 机器列表的滚动箭头，带有页码计数器。 |
还有另外两个条目补全了这一套。Open Machine GUI 将一个定义与菜单标题和大小关联起来，但按当前代码，触发它的动作不会做任何事：机器是在右键点击时打开其菜单的。Machine Position Variable 返回观看者自己在其维度中某个定义的机器的位置，因此同一个 NPC 条目可以跟随每座岛屿的机器。
仪表盘所显示的标签（状态、连接、全息图）来自 Machine Dashboard Wording。滚动和打开命令则来自 Machine Dashboard Command。
命令
| 命令 | 说明 |
|---|---|
/typewriter machine give | 列出每一种已注册的机器。 |
/typewriter machine give <machine> | 给自己一台机器的物品，可按 id 或其名称的一部分指定（忽略重音和大小写）。 |
/typewriter machine liquide | 显示你所注视的机器（6 格以内）所持有的液体。 |
/typewriter machine liquide <liquid> <millibuckets> | 向所注视的机器倒入液体。这是一个测试工具：玩家没有任何操作能向储罐灌注液体。 |
/machine 命令树注册在 TypeWriter 命令之下，因此输入的是 /typewriter machine …（别名 /tw machine …）。它全部需要 machine.admin。条目还可以注册更多命令，作为顶层命令：
| 命令 | 说明 |
|---|---|
/<commandName> scroll <delta>, reset | 滚动仪表盘列表，或将其回退。默认名称为 machines。 |
/<commandName> dashboard | 打开 dashboardMenuId 中指定的菜单。 |
/<commandName> link <instanceId>, hologram <instanceId> | 切换机器的网络连接或全息图。供仪表盘的槽位使用。 |
Machine Test Command 的 /<commandName> | 在 criteria 匹配时触发其 triggers。默认名称为 machine-test。 |
Machine Test Platform Command 的 /<commandName>、clear、bench | 在你所站的位置构建机器展示区，移除它，或配置 loadbench_* 世界。默认名称为 machine-test-platform。 |
权限
| 权限 | 授予 |
|---|---|
machine.admin | /typewriter machine 命令。 |
machine.protection.bypass | 在任何地方放置、破坏机器并与之交互，无视岛屿所有权、建造标志和限制。 |
占位符
machine expansion 的 MiniPlaceholders 标签，通过 TypeWriter 提供。<instance> 是已放置机器的 id，<slot> 是逻辑槽位索引（默认 0）。
| 占位符 | 返回值 |
|---|---|
<machine_input:instance:slot> | 输入槽位中有物品时为 true。 |
<machine_input_name:instance:slot> | 输入物品的材质名称。 |
<machine_input_amount:instance:slot> | 输入槽位中的数量。 |
<machine_output:instance:slot> | 输出槽位中有物品时为 true。 |
<machine_output_name:instance:slot> | 输出物品的材质名称。 |
<machine_output_amount:instance:slot> | 输出槽位中的数量。 |
<machine_tier:instance> | 当前层级的名称。 |
<machine_dimension> | 玩家所在维度的可读名称。 |
<machine_grid_count>, <machine_grid_active>, <machine_grid_stalled> | 该维度中的机器数量、运行中的数量以及停滞的数量。 |
<machine_energy_stored>, <machine_energy_capacity> | 该维度已存储的能量和总容量。 |
<machine_energy_produced>, <machine_energy_consumed>, <machine_energy_balance> | 每秒产出、消耗和净值的能量。 |
在没有玩家的情况下（控制台），与玩家相关的占位符会返回空值。
全息图消息支持 %machine%、%tier%、%energy%、%bar%、%percent% 和 %time_left%。
条目
10 个条目，由扩展源码生成。
动作2
- Machine MenuMachine Menu
- Open Machine GUIOpen Machine GUI
命令3
- Machine Dashboard CommandMachine dashboard commands
- Machine Test CommandRegister a Machine test command
- Machine Test Platform CommandProvision the Machine BTC test platform
变量1
- Machine Position VariablePosition of the viewer's machine of a given definition
构件1
- Machine Data ArtifactStores machine runtime state (placed instances, energy, progress) as JSON data
清单2
- Machine Dashboard ConfigMachine Dashboard Wording
- Machine Protection ConfigMachines : messages de protection
其他条目1
- Machine DefinitionMachine Definition
故障排查
定义在发布时被拒绝。 请检查服务器日志：no way to obtain this machine 表示既没有设置 spawnItem 也没有设置 vanillaBlock；tier[n].researchNode is blank 表示某个层级没有研究节点；the machine layout needs N slots, maximum is 54 表示槽位过多。
机器接受物品却始终不工作。 recipes 列表为空的配方机器（例如 MIXING、GRINDING、BREWING）没有原版回退。只有 SMELTING 和 AUTO_CRAFTING 会使用原版配方。
放置被拒绝。 消息来自 Machine Protection Config：机器必须位于你自己的 BTC Sky 岛屿上，你需要拥有建造标志，并且会应用玩家、岛屿和维度的限制以及 dimensionScope。CONTROL_PANEL 需要该维度中有稳定水晶。拥有 machine.protection.bypass 的管理员会跳过所有检查。
机器提示未连接或没有能量。 它需要同一维度中有 ENERGY_CELL 和 ENERGY_GENERATOR 机器，并且必须已连接（使用连接按钮）。能量池永远不会跨越维度。
升级模块没有任何作用。 它的 type 必须在 allowedUpgrades 中，并且 CAPACITY 只对 STORAGE、EXPERIENCE_TANK 和 ENERGY_CELL 有效。LIQUID_FUEL 需要 liquidFuelName。
某个层级始终没有生效。 researchNode 必须与 BTC Sky 的某个研究节点 id 匹配，并且岛屿必须已经解锁了它。
菜单打开后是空的，或打不开。 请对照 layoutPool 中的 id 检查 mainLayoutId；不匹配时，日志会列出池中的 id。
家具或自定义方块外观失败。 FURNITURE 和 CUSTOM_BLOCK 需要 CraftEngine 以及一个存在的 furnitureId 或 customBlockId。
相关扩展
- BTC Sky — 机器所依赖的岛屿、所有权、研究和维度。