CC: TweakedAPI 中文参考

查接口、参数和事件。按编程任务组织，遇到具体问题直接跳读。

非官方原创参考 · 官网事实快照 2026-11-12 · 单文件离线阅读

从搭建指南开始资料与编写说明
/ 搜索 · Esc 清除 · 多词同时匹配

先确定要查什么

本册按编程任务重新组织官方公开的接口事实，讲解与示例独立编写，不是官方译本，也不是官网镜像。已有的实战手册负责搭建与模组联动，这里用于核对接口、数据类型和事件。

读写文件 fs / io发现设备 peripheral 搬运物品 inventory海龟编程 turtle 绘制界面 term / window监听变化 events
如何读签名、类型与版本

[参数] 表示可以省略，不是实际 Lua 调用中的方括号。... 表示变长参数。多个参数形式是重载选项，不能把它们全部连在一起传入。

number 数值、string 字符串、boolean 布尔值、table 表、nil 无值、any 任意值。类型中的 | 是可能类型之一；返回分支中的逗号表示多个返回值，不是一个表。

类型名如 fs.ReadHandle 用于描述返回对象，不是要求照抄成全局变量。fs 句柄、外设和终端对象通常用点号，io 句柄与向量按各自接口用冒号。

资料核对日期为 2026-11-12，官网快照包含到 1.121.0 的条目。它不是某个整合包的兼容保证：先检查安装版本，再检查函数和外设能力。实验性接口单独标注；示例未做游戏内实测。

覆盖官网主目录的 95 个主题与 551 个显式接口、常量及类型成员，保留其签名和类型信息。未复制官网叙述、示例代码、图像或样式；未纳入独立 Java API、历史版本整站和站外 Lua 手册。

程序与运行环境

_G基础输入与输出

写小程序时不必先加载库：print、read、sleep 等名字已经在运行环境里。交互文字与按键事件是两层接口，输入一整行优先用 read。

使用边界：sleep 的秒数按 0.05 秒的节拍向上取整，实际等待还受服务器运行速度影响。read 的遮盖字符只改变显示，不是密码加密。

读入一行并回应

Lua · 自编示例
write("Station name: ")
local name = read()
if name == "" then
  printError("A name is required.")
else
  print("Connected to " .. name)
end

资料来源：_G

本节接口索引

sleep([time=0])

主动让出执行权并等待；不要用不让出的空循环计时。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
timenumber可选；默认 0
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

变更 1.63。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

printError(...)

输出醒目的错误提示；它不会代替 error 中断程序。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
...any变长；数量依接口
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

本节说明与使用边界 · 核对官方定义

os事件、时间与程序生命周期

把程序写成“收到事件，再更新状态”的循环。定时器、网络与外设都通过事件交付结果，不能把等待某一种事件当作完全无损的通用消息队列。

使用边界：pullEvent 收到终止请求会报错退出；pullEventRaw 把 terminate 交给程序处理，即使设了其他过滤器也要处理它。秒、游戏小时与 epoch 毫秒不可混用。

同时观察计时与退出按键

Lua · 自编示例
local token = os.startTimer(3)
while true do
  local event, value = os.pullEvent()
  if event == "timer" and value == token then
    print("Three seconds elapsed.")
    break
  elseif event == "key" and value == keys.q then
    os.cancelTimer(token)
    break
  end
end

资料来源：os

本节接口索引

os.loadAPI(path)

旧式加载器，把文件导出的名字放到全局表；新模块优先使用 require。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
pathstring必需
返回值（按顺序）
  • boolean

新增 1.2。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

os.unloadAPI(name)

移除旧式 API 的全局入口，不负责关闭该 API 创建的设备或文件。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
namestring必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.2。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

os.sleep([time=0])

与全局 sleep 相同；挂起期间不会执行当前协程的业务逻辑。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
timenumber可选；默认 0
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

本节说明与使用边界 · 核对官方定义

os.queueEvent(name, ...)

给本机事件队列追加自定义消息；不能用它直接给另一台电脑发消息。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
namestring必需
...any变长；数量依接口
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

本节说明与使用边界 · 核对官方定义

os.cancelTimer(token)

取消指定编号的定时器；不要误取消同一程序中的另一项计时。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
tokennumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.6。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

os.setAlarm(time)

按游戏一天中的时刻安排闹钟，返回用于匹配 alarm 的编号。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
timenumber必需
返回值（按顺序）
  • number

新增 1.2。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

os.cancelAlarm(token)

撤销指定闹钟，参数不是小时数而是闹钟编号。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
tokennumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.6。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

os.time([locale])

读取一天中的小时值；ingame、utc 与 local 使用不同时间基准。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
localestring | table可选
返回值（按顺序）
  • any

新增 1.2 · 变更 1.80pr1 · 变更 1.82.0 · 变更 1.83.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

os.day([locale])

读取所选时间基准的天数；不要把游戏日和现实日期编号相混。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
localestring可选
返回值（按顺序）
  • number

新增 1.48 · 变更 1.82.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

os.epoch([locale])

读取所选时间基准的毫秒时间戳；现实时间戳通常选 utc。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
localestring可选
返回值（按顺序）
  • number

新增 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

os.date([format [, time]])

按格式输出日期，*t 可得到字段表；传入时间值使用秒而不是 epoch 毫秒。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
formatstring可选
timenumber可选
返回值（按顺序）
  • any

新增 1.83.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

shell命令行与程序入口

shell 负责当前目录、程序查找、别名和补全。处理用户输入的路径时，先用 shell.resolve 得到路径，再交给 fs。

使用边界：execute 保留每个参数的边界，run 会按命令行重新解释参数。含空格的用户参数优先交给 execute；新程序的全局变量不会自动回写到调用者。

资料来源：shell

本节接口索引

shell.execute(command, ...)

按已经分开的参数启动程序，适合参数中含空格的调用。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
commandstring必需
...string变长；数量依接口
返回值（按顺序）
  • boolean

新增 1.88.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

shell.run(...)

按命令行语法启动程序；引号和空白会参与参数解析。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
...string变长；数量依接口
返回值（按顺序）
  • boolean

变更 1.80pr1 · 变更 1.83.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

shell.setPath(path)

替换程序搜索路径；不会移动或安装程序。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
pathstring必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.2。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

shell.setCompletionFunction(program, complete)

为某个程序路径注册参数补全回调。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
programstring必需
completefunction(shell: table , index: number , argument: string , previous: { string }):{ string } | nil必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.74。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

shell.setAlias(command, program)

注册一个短命令到实际程序的映射。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
commandstring必需
programstring必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.2。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

shell.openTab(...)

在支持 multishell 的环境中用新标签运行命令。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
...string变长；数量依接口
返回值（按顺序）
  • number

新增 1.6。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

shell.switchTab(id)

把指定 multishell 标签切到前台。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
idnumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.6。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

multishell多标签程序

高级电脑的多标签终端让多个程序协作运行。区分正在执行的程序和用户正在看的标签：前者用 getCurrent，后者用 getFocus。

使用边界：普通电脑或自建运行环境可能没有 multishell。启动前先检查该全局是否存在；新标签不会因为创建就自动成为焦点。

资料来源：multishell

本节接口索引

parallel协作式并发

需要同时处理键盘、计时和网络时，把互相独立的循环交给 parallel。它在协程之间调度，并不是多个 CPU 线程同时运行 Lua。

使用边界：传函数本身，而不是函数调用结果。某个函数长期不让出执行权会阻塞同组任务；其中一个报错也会使并发调用失败。

一个分支更新状态，另一个接受退出

Lua · 自编示例
parallel.waitForAny(
  function()
    while true do
      print("Uptime:", os.clock())
      sleep(2)
    end
  end,
  function()
    while true do
      local _, key = os.pullEvent("key")
      if key == keys.q then return end
    end
  end
)

资料来源：parallel

本节接口索引

parallel.waitForAny(...)

任一分支正常结束就返回其位置；适合一个退出按钮结束一组监听。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
...function变长；数量依接口
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

本节说明与使用边界 · 核对官方定义

parallel.waitForAll(...)

等待所有分支都完成；适合必须全部结束的有限任务。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
...function(spawn: function(fn: function , ...: any ))变长；数量依接口
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

变更 1.120.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

settings配置与持久化

先用 define 描述设置的类型和默认值，再通过 get、set 访问。运行中的值与磁盘上的配置是两回事，修改后需要显式保存。

使用边界：load 会将读入值并入当前设置，不等同于先清空。clear 清的是值，不是设置定义；程序应检查 load、save 的成功标志。

定义设置并显式保存

Lua · 自编示例
settings.define("station.interval", {
  description = "Polling interval in seconds",
  default = 5,
  type = "number",
})
local value = settings.get("station.interval")
print("Interval:", value)
settings.set("station.interval", value)
if not settings.save() then error("Could not save settings.", 0) end

资料来源：settings

本节接口索引

settings.define(name [, options])

登记设置的描述、类型与默认值。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
namestring必需
options{ description ? = string , default ? = any , type ? = string }可选
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.87.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

settings.undefine(name)

撤掉设置的定义；它和清除当前设置值不是同一个动作。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
namestring必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.87.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

settings.getDetails(name)

读取值、默认值、描述及类型等元信息。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
namestring必需
返回值（按顺序）
  • { description ? = string , default ? = any , type ? = string , value ? = any }

新增 1.87.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

help本机帮助文件

这是 CraftOS 内置帮助文件的索引，不是联网搜索。可以将自己的帮助目录加入路径，为自编程序提供离线说明。

使用边界：帮助搜索路径中的目录使用绝对路径；找不到主题时先检查文件位置，再检查搜索路径。

资料来源：help

本节接口索引

help.lookup(topic)

将主题名解析成帮助文件路径，未找到时为 nil。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
topicstring必需
返回值（按顺序）
  • string | nil

变更 1.80pr1 · 变更 1.97.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

文件与数据

fs文件系统与文件句柄

fs 适合明确控制打开、读取、写入和关闭的流程。路径相对电脑根目录解释，不跟随 shell 当前目录；磁盘、ROM 和本机硬盘是不同挂载。

使用边界：w 会截断原文件，a 才是追加。1.109.0 起支持 r+ / w+，文本模式也以原始字节处理；不等于任意 Unicode 文本都能正确显示。写后关闭，读取大文件时分块处理。

追加一条记录，而不是截断旧文件

Lua · 自编示例
local path = shell.resolve("station-log.txt")
local file, reason = fs.open(path, "a")
if not file then error(reason, 0) end
local ok, failure = pcall(function()
  file.writeLine(tostring(os.epoch("utc")) .. " station checked")
end)
file.close()
if not ok then error(failure, 0) end
print("Appended to " .. path)

资料来源：fs

本节接口索引

fs.complete(...)

根据当前位置和输入前缀给出文件名补全，可筛选文件、目录和隐藏项。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
pathstring必需
locationstring必需
include_filesboolean可选；默认 true
include_dirsboolean可选；默认 true
参数形式 2
参数名类型 / 字段结构约定
pathstring必需
locationstring必需
options{ include_dirs ? = boolean , include_files ? = boolean , include_hidden ? = boolean }可选
返回值（按顺序）
  • { string ... }

新增 1.74 · 变更 1.101.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

fs.find(path)

用通配路径查找文件；这是路径匹配，不是文件正文搜索。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
pathstring必需
返回值（按顺序）
  • { string ... }

新增 1.6 · 变更 1.106.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

fs.combine(path, ...)

拼接并规整路径，避免手工处理重复分隔符。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
pathstring必需
...string变长；数量依接口
返回值（按顺序）
  • string

变更 1.95.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

fs.move(path, dest)

将文件或目录移动到新路径；目标冲突等情况可能报错。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
pathstring必需
deststring必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

本节说明与使用边界 · 核对官方定义

fs.delete(path)

删除文件；传目录会连同其内容删除，调用前确认路径。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
pathstring必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

本节说明与使用边界 · 核对官方定义

fs.open(path, mode)

按模式取得句柄；r 只读、a 追加，w 会立即截断旧文件。失败可能返回 nil, 原因，非法模式则可能抛错。

参数、返回值与版本

path 从电脑根目录解释；若路径由用户按当前目录输入，先用 shell.resolve 解析。

模式选择：r 读取，w 写入并清空旧内容，a 从末尾追加；1.109.0 起的 r+ 可读写且保留旧内容，w+ 可读写但会清空旧内容。末尾加 b 是兼容旧程序的二进制模式，会改变单字节读取和数值写入行为，新代码通常不需要它。

参数
参数名类型 / 字段结构约定
pathstring必需
modestring必需
返回值（按顺序）
  • 分支 1：table
  • 分支 2：nil，string | nil

变更 1.109.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

fs.getFreeSpace(path)

查询挂载剩余字节数；某些挂载用字符串 unlimited 表示无限。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
pathstring必需
返回值（按顺序）
  • number | "unlimited"

新增 1.4。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

fs.attributes(path)

取得大小、目录标志、只读标志及创建/修改时间。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
pathstring必需
返回值（按顺序）
  • { size = number , isDir = boolean , isReadOnly = boolean , created = number , modified = number }

新增 1.87.0 · 变更 1.91.0 · 变更 1.95.2。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

fs.ReadWriteHandle.read([count])

从当前位置读取字节；到末尾为 nil。二进制模式省略数量时返回一个字节数值，给出数量时返回字符串。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
countnumber可选
返回值（按顺序）
  • 分支 1：nil
  • 分支 2：number
  • 分支 3：string

变更 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

fs.ReadWriteHandle.write(...)

在当前位置写入字符串；旧式二进制句柄也接受单字节数值。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
contentsstring必需
参数形式 2
参数名类型 / 字段结构约定
charcodenumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

变更 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

fs.WriteHandle.write(...)

在当前位置写入字符串；旧式二进制句柄也接受单字节数值。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
contentsstring必需
参数形式 2
参数名类型 / 字段结构约定
charcodenumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

变更 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

fs.WriteHandle.seek([whence [, offset]])

移动读写位置；set、cur、end 分别从开头、当前位置、末尾计算偏移。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
whencestring可选
offsetnumber可选
返回值（按顺序）
  • 分支 1：number
  • 分支 2：nil，string

新增 1.80pr1.9 · 变更 1.109.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

fs.ReadHandle.read([count])

从当前位置读取字节；到末尾为 nil。二进制模式省略数量时返回一个字节数值，给出数量时返回字符串。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
countnumber可选
返回值（按顺序）
  • 分支 1：nil
  • 分支 2：number
  • 分支 3：string

变更 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

fs.ReadHandle.seek([whence [, offset]])

移动读写位置；set、cur、end 分别从开头、当前位置、末尾计算偏移。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
whencestring可选
offsetnumber可选
返回值（按顺序）
  • 分支 1：number
  • 分支 2：nil，string

新增 1.80pr1.9 · 变更 1.109.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

ioLua 风格的文件流

io 提供标准流和迭代读取风格。逐行扫描优先考虑 io.lines；需要显式控制文件寿命时，保留 io.open 返回的句柄并关闭它。

使用边界：它模拟 Lua 的文件 API，不代表能启动操作系统进程。io.open 返回的句柄以冒号调用；与 fs.open 句柄的点号调用区分。

逐行检查已有文件

Lua · 自编示例
local path = shell.resolve("station-log.txt")
if not fs.exists(path) then error("Missing log: " .. path, 0) end
local count = 0
for line in io.lines(path) do
  count = count + 1
  print(count, line)
end

资料来源：io

本节接口索引

io.close([file])

关闭指定流；未传流时作用于当前输出流。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
fileHandle可选
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.55。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

io.flush()

刷新当前输出流的缓冲数据。

参数、返回值与版本
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.55。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

io.lines([filename, ...])

取得逐行或按指定格式读取的迭代器；使用文件名创建的迭代器在结束时关闭文件。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
filenamestring可选
...any变长；数量依接口
返回值（按顺序）
  • function(): string | nil

新增 1.55。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

io.open(filename [, mode])

打开指定文件并返回句柄；失败时为 nil 和原因。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
filenamestring必需
modestring可选
返回值（按顺序）
  • 分支 1：Handle
  • 分支 2：nil，string

变更 1.111.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

io.write(...)

将多项值写到当前默认输出流。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
...string变长；数量依接口
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

变更 1.81.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

io.Handle.lines(...)

创建基于此句柄的读取迭代器；调用者仍负责关闭句柄。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
...any变长；数量依接口
返回值（按顺序）
  • function(): string | nil

新增 1.3。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

io.Handle.write(...)

写入字符串或数值，适合以 file:write(...) 形式调用。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
...string | number变长；数量依接口
返回值（按顺序）
  • 分支 1：Handle
  • 分支 2：nil，string

变更 1.81.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

textutils序列化与文字整理

需要存档就选 Lua 序列化，需要与外部服务交换就选 JSON。格式化输出、分页显示和 Lua 表达式补全也集中在这里。

使用边界：Lua 表、JSON 对象与 JSON 数组不是完全等价的结构。空数组和 JSON null 有专用标记；解析失败必须检查结果，不要把失败当作空数据继续覆盖存档。

资料来源：textutils

本节接口索引

textutils.slowWrite(text [, rate])

按字符逐步输出文字，不自动换行；速率按每秒字符数计算。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
textstring必需
ratenumber可选
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.3。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

textutils.tabulate(...)

按列排列表格内容，可在参数间插入颜色值。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
...{ string ... } | number变长；数量依接口
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.3。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

textutils.pagedTabulate(...)

分屏显示表格，避免输出超过屏幕后无法阅读。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
...{ string ... } | number变长；数量依接口
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.3。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

textutils.serialize(t, opts)

把可表示的 Lua 数据转成文本，便于存盘或检查。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
tany必需
opts{ compact ? = boolean , allow_repetitions ? = boolean }可选
返回值（按顺序）
  • string

新增 1.3 · 变更 1.97.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

textutils.serializeJSON(...)

把数据转换成 JSON；选项可控制非标准值和格式细节。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
tany必需
options{ nbt_style ? = boolean , unicode_strings ? = boolean , allow_repetitions ? = boolean }可选
参数形式 2
参数名类型 / 字段结构约定
tany必需
bNBTStyleboolean必需
返回值（按顺序）
  • string

新增 1.7 · 变更 1.106.0 · 变更 1.109.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

textutils.serialiseJSON(...)

serializeJSON 的英式拼写别名。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
tany必需
options{ nbt_style ? = boolean , unicode_strings ? = boolean , allow_repetitions ? = boolean }可选
参数形式 2
参数名类型 / 字段结构约定
tany必需
bNBTStyleboolean必需
返回值（按顺序）
  • string

新增 1.7 · 变更 1.106.0 · 变更 1.109.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

textutils.unserializeJSON(s [, options])

解析 JSON；按选项决定空数组、null 和 Unicode 的处理。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
sstring必需
options{ nbt_style ? = boolean , parse_null ? = boolean , parse_empty_array ? = boolean }可选
返回值（按顺序）
  • 分支 1：any
  • 分支 2：nil，string

新增 1.87.0 · 变更 1.100.6。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

textutils.unserialiseJSON(s [, options])

unserializeJSON 的英式拼写别名。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
sstring必需
options{ nbt_style ? = boolean , parse_null ? = boolean , parse_empty_array ? = boolean }可选
返回值（按顺序）
  • 分支 1：any
  • 分支 2：nil，string

新增 1.87.0 · 变更 1.100.6。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

vector三维向量

适合存储位置、位移和方向。用 vector.new 创建对象，再用冒号方法或运算符做计算。

使用边界：向量运算返回新向量；不要把归一化方向当作原始距离。零向量没有可用的单位方向，归一化前先检查长度。

资料来源：vector

本节接口索引

画面与输入

term终端绘制与重定向

终端以字符格为坐标单位，左上角为 (1, 1)。普通输出可用 print，布局控件则用光标定位、write 和 blit。

使用边界：term.write 不自动折行；clear 不把光标移回左上角。重定向前保存旧目标，结束或出错后恢复；native 是底层终端，不是“当前窗口”。

在窗口里绘制，然后恢复输出目标

Lua · 自编示例
local parent = term.current()
local width, height = parent.getSize()
local pane = window.create(parent, 1, 1, width, math.min(3, height), false)
term.redirect(pane)
local ok, reason = pcall(function()
  term.setBackgroundColor(colors.black)
  term.clear()
  term.setCursorPos(1, 1)
  print("Status: ready")
end)
term.redirect(parent)
if not ok then error(reason, 0) end
pane.setVisible(true)

资料来源：term

本节接口索引

term.nativePaletteColour(colour)

读取该颜色槽的出厂 RGB 值，不受当前调色板修改影响。 与美式拼写方法等价。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
colournumber必需
返回值（按顺序）
  • number，number，number

新增 1.81.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

term.write(text)

在光标处写文字并向右移动光标；超出行宽的部分不会自动换行。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
textstring必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

本节说明与使用边界 · 核对官方定义

term.scroll(y)

让画面滚动指定行数；正数向上，负数向下。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
ynumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

本节说明与使用边界 · 核对官方定义

term.setTextColour(colour)

指定后续普通文字的前景色。 与美式拼写方法等价。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
colournumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.45 · 变更 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

term.setTextColor(colour)

指定后续普通文字的前景色。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
colournumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.45 · 变更 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

term.setBackgroundColour(colour)

指定后续写字和清屏使用的背景色。 与美式拼写方法等价。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
colournumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.45 · 变更 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

term.setBackgroundColor(colour)

指定后续写字和清屏使用的背景色。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
colournumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.45 · 变更 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

term.blit(text, textColour, backgroundColour)

一次写入文字、逐字符前景与逐字符背景；三段字符串长度必须相同。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
textstring必需
textColourstring必需
backgroundColourstring必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.74 · 变更 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

term.setPaletteColour(...)

调整一个颜色槽对应的 RGB；可用三个通道或打包后的 RGB 值。 与美式拼写方法等价。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
indexnumber必需
colournumber必需
参数形式 2
参数名类型 / 字段结构约定
indexnumber必需
rnumber必需
gnumber必需
bnumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

term.setPaletteColor(...)

调整一个颜色槽对应的 RGB；可用三个通道或打包后的 RGB 值。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
indexnumber必需
colournumber必需
参数形式 2
参数名类型 / 字段结构约定
indexnumber必需
rnumber必需
gnumber必需
bnumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

term.redirect(target)

把 term 输出改送到另一个终端对象，并返回旧对象以便恢复。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
targetRedirect必需
返回值（按顺序）
  • Redirect

新增 1.31。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

term.Redirect.setTextColour(colour)

指定后续普通文字的前景色。 与美式拼写方法等价。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
colournumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.45 · 变更 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

term.Redirect.blit(text, textColour, backgroundColour)

一次写入文字、逐字符前景与逐字符背景；三段字符串长度必须相同。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
textstring必需
textColourstring必需
backgroundColourstring必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.74 · 变更 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

term.Redirect.setPaletteColour(...)

调整一个颜色槽对应的 RGB；可用三个通道或打包后的 RGB 值。 与美式拼写方法等价。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
indexnumber必需
colournumber必需
参数形式 2
参数名类型 / 字段结构约定
indexnumber必需
rnumber必需
gnumber必需
bnumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

term.Redirect.setPaletteColor(...)

调整一个颜色槽对应的 RGB；可用三个通道或打包后的 RGB 值。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
indexnumber必需
colournumber必需
参数形式 2
参数名类型 / 字段结构约定
indexnumber必需
rnumber必需
gnumber必需
bnumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

window窗口与离屏绘制

窗口是父终端中的一个矩形区域，使用与 term 相同的绘制方法。隐藏窗口可以先写入缓冲，再显示，适合减少界面闪烁。

使用边界：窗口不自动帮程序处理鼠标命中；父终端变大也不代表子窗口自动适应。重设位置或尺寸后，根据新的宽高重新排版。

资料来源：window

本节接口索引

window.Window.getLine(y)

读取缓冲中的一行，返回文字、前景 blit 字符串和背景 blit 字符串。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
ynumber必需
返回值（按顺序）
  • string，string，string

新增 1.84.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

window.Window.reposition(new_x, new_y [, new_width, new_height [, new_parent]])

更换位置，并可同时调整尺寸或父终端。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
new_xnumber必需
new_ynumber必需
new_widthnumber可选
new_heightnumber必需
new_parentterm.Redirect可选
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

变更 1.85.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

colors颜色与位掩码

同一个颜色常量可以代表终端调色板槽，也可代表束线信号中的一位。终端使用单色常量；束线集合则用 combine、subtract 和 test 操作。

使用边界：term.blit 使用单个十六进制字符 0 到 f，不是直接传颜色常量。RGB 通道采用 0 到 1；修改调色板不会改变颜色常量的数值。

资料来源：colors

本节接口索引

colors.rgb8(...)

兼容式双向转换：三个参数打包，一个参数拆包。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
rnumber必需
gnumber必需
bnumber必需
参数形式 2
参数名类型 / 字段结构约定
rgbnumber必需
返回值（按顺序）
  • 分支 1：number
  • 分支 2：number，number，number

新增 1.80pr1 · 变更 1.81.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

colours颜色的英式名字

colours 与 colors 对应同一组颜色操作，可在英式代码习惯中使用。

使用边界：除了 grey / lightGrey 的拼写差异，接口与 colors 对照使用。

资料来源：colours

本节接口索引

paintutils字符格图形

适合进度条、框线和简单像素图。这里的一个“像素”是一格字符背景，并非真实屏幕像素。

使用边界：绘制会改变终端状态。颜色参数省略时使用当前颜色；需要细密字符和多色文字图时再看 cc.image.nft。

资料来源：paintutils

本节接口索引

keys按键名称

快捷键用 keys.enter、keys.left 这样的符号判断；文本编辑用 char 事件。

使用边界：键码在 Minecraft 版本之间有过变化，不要把数值写死。主回车与小键盘回车可能是不同键。

资料来源：keys

本节接口索引

monitor监视器

将 peripheral.find("monitor") 的结果作为独立终端使用。需要把 print 也送上大屏时，再临时调用 term.redirect。

使用边界：字号为 0.5～5、步长 0.5；字号越大，可用字符格越少。拼接或缩放后收到 monitor_resize，应重新查询尺寸。触摸事件需要高级监视器。

资料来源：monitor

本节接口索引

monitor.write(text)

在光标处写文字并向右移动光标；超出行宽的部分不会自动换行。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
textstring必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

本节说明与使用边界 · 核对官方定义

monitor.setTextColour(colour)

指定后续普通文字的前景色。 与美式拼写方法等价。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
colournumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.45 · 变更 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

monitor.setTextColor(colour)

指定后续普通文字的前景色。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
colournumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.45 · 变更 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

monitor.setBackgroundColour(colour)

指定后续写字和清屏使用的背景色。 与美式拼写方法等价。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
colournumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.45 · 变更 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

monitor.blit(text, textColour, backgroundColour)

一次写入文字、逐字符前景与逐字符背景；三段字符串长度必须相同。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
textstring必需
textColourstring必需
backgroundColourstring必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.74 · 变更 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

monitor.setPaletteColour(...)

调整一个颜色槽对应的 RGB；可用三个通道或打包后的 RGB 值。 与美式拼写方法等价。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
indexnumber必需
colournumber必需
参数形式 2
参数名类型 / 字段结构约定
indexnumber必需
rnumber必需
gnumber必需
bnumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

monitor.setPaletteColor(...)

调整一个颜色槽对应的 RGB；可用三个通道或打包后的 RGB 值。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
indexnumber必需
colournumber必需
参数形式 2
参数名类型 / 字段结构约定
indexnumber必需
rnumber必需
gnumber必需
bnumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.80pr1。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

网络与定位

httpHTTP 与 WebSocket

简单下载使用同步接口；需要主循环继续工作时，用异步请求配合事件。返回的 HTTP 响应仍是需要关闭的资源。

使用边界：URL 是否可访问受服务器配置、DNS、端口与请求配额共同影响。网络失败和 HTTP 错误状态都要处理；错误响应有时仍提供可读取的句柄。WebSocket 不是浏览器对象。

资料来源：http

本节接口索引

http.get(...)

发起 GET 并等待响应；成功返回响应句柄，失败返回原因并可能带错误响应。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
urlstring必需
headers{ [ string ] = string }可选
binaryboolean可选；默认 false
参数形式 2
参数名类型 / 字段结构约定
request{ url = string , headers ? = { [ string ] = string }, binary ? = boolean , method ? = string , redirect ? = boolean , timeout ? = number }可选
返回值（按顺序）
  • 分支 1：Response
  • 分支 2：nil，string，Response | nil

变更 1.63 · 变更 1.80pr1 · 变更 1.80pr1.6 · 变更 1.86.0 · 变更 1.105.0 · 变更 1.109.0 · 变更 1.121.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

http.post(...)

发送请求体并等待 POST 响应；表形式可指定更多请求选项。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
urlstring必需
bodystring必需
headers{ [ string ] = string }可选
binaryboolean可选；默认 false
参数形式 2
参数名类型 / 字段结构约定
request{ url = string , body ? = string , headers ? = { [ string ] = string }, binary ? = boolean , method ? = string , redirect ? = boolean , timeout ? = number }可选
返回值（按顺序）
  • 分支 1：Response
  • 分支 2：nil，string，Response | nil

新增 1.31 · 变更 1.63 · 变更 1.80pr1 · 变更 1.80pr1.6 · 变更 1.86.0 · 变更 1.105.0 · 变更 1.109.0 · 变更 1.121.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

http.request(...)

只提交异步请求，最终结果通过 http_success 或 http_failure 获取。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
urlstring必需
bodystring可选
headers{ [ string ] = string }可选
binaryboolean可选；默认 false
参数形式 2
参数名类型 / 字段结构约定
request{ url = string , body ? = string , headers ? = { [ string ] = string }, binary ? = boolean , method ? = string , redirect ? = boolean , timeout ? = number }可选
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

变更 1.63 · 变更 1.80pr1 · 变更 1.80pr1.6 · 变更 1.86.0 · 变更 1.105.0 · 变更 1.109.0 · 变更 1.121.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

http.websocketAsync(...)

发起 WebSocket 握手，不阻塞到连接完成。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
urlstring必需
headers{ [ string ] = string }可选
参数形式 2
参数名类型 / 字段结构约定
request{ url = string , headers ? = { [ string ] = string }, timeout ? = number }可选
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.80pr1.3 · 变更 1.95.3 · 变更 1.105.0 · 变更 1.109.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

http.websocket(...)

等待 WebSocket 握手，成功后得到连接对象。

参数、返回值与版本
参数形式 1
参数名类型 / 字段结构约定
urlstring必需
headers{ [ string ] = string }可选
参数形式 2
参数名类型 / 字段结构约定
request{ url = string , headers ? = { [ string ] = string }, timeout ? = number }可选
返回值（按顺序）
  • 分支 1：Websocket
  • 分支 2：false，string

新增 1.80pr1.1 · 变更 1.80pr1.3 · 变更 1.95.3 · 变更 1.105.0 · 变更 1.109.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

http.Websocket.receive([timeout])

等待一条消息；可设超时，并区分文本与二进制标记。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
timeoutnumber可选
返回值（按顺序）
  • 分支 1：string，boolean
  • 分支 2：nil，string

变更 1.80pr1.13 · 变更 1.87.0 · 变更 1.117.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

rednet电脑之间的消息

Rednet 在 modem 通道之上提供电脑编号、协议名与主机查询。先打开连接的 modem，再收发结构化消息。

使用边界：协议名用于分类，不提供身份认证或保密。发送成功不等于对方已执行业务；需要确认时自行设计请求编号和回执。

监听一种协议，并校验消息结构

Lua · 自编示例
local modem = peripheral.find("modem")
if not modem then error("Connect a modem first.", 0) end
local name = peripheral.getName(modem)
rednet.open(name)
local ok, reason = pcall(function()
  local sender, message = rednet.receive("station.status", 10)
  if sender == nil then
    print("No status report received.")
  elseif type(message) == "table" and type(message.state) == "string" then
    print(sender, message.state)
  else
    printError("Invalid status report.")
  end
end)
rednet.close(name)
if not ok then error(reason, 0) end

资料来源：rednet

本节接口索引

rednet.host(protocol, hostname)

登记协议与主机名，供同网设备查找。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
protocolstring必需
hostnamestring必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.6。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

rednet.unhost(protocol)

撤销某协议的主机登记。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
protocolstring必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.6。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

gps坐标定位

GPS 通过无线 modem 与已有坐标的主机计算位置，不会凭空读取世界坐标。用于导航时，定位失败必须停止依赖坐标的动作。

使用边界：主机必须处于加载状态，且布局不能全部共面。坐标使用主机电脑方块位置；末影 modem 的跨维通信不意味着可以跨维完成测距定位。

资料来源：gps

本节接口索引

modem原始通道与有线网络

原始 modem 消息使用通道号，而不是 Rednet 的电脑编号。远程外设枚举和调用属于有线 modem 的网络能力。

使用边界：通道范围 0～65535，同时最多打开 128 个。接收方须打开目标通道；发送时给出的回信通道也需要本机打开才能收回信。无线 modem 不能直接包装另一台电脑的远端外设。

资料来源：modem

本节接口索引

外设与自动化

peripheral发现与调用外设

先确认设备是否被电脑识别，再取得包装对象。相邻设备常用六向名字，有线网络设备使用网络名称。

使用边界：find 返回多个值，不是一个数组；收集全部设备可写 {peripheral.find("inventory")}。设备可能同时实现多个类型，优先使用 hasType 判断能力。

发现所有库存，不假定只有一台

Lua · 自编示例
local stores = { peripheral.find("inventory") }
for _, store in ipairs(stores) do
  print(peripheral.getName(store), store.size())
end
if #stores == 0 then printError("No inventory is connected.") end

资料来源：peripheral

本节接口索引

peripheral.find(ty [, filter])

按类型查找所有匹配设备，可增加 (name, wrapped) 过滤回调。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
tystring必需
filterfunction(name: string , wrapped: table ): boolean可选
返回值（按顺序）
  • table ...

新增 1.6。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

turtle海龟动作与背包

先读状态，再发出一步动作，再检查结果。移动、挖掘、放置都可能失败，导航程序不能在失败后照样更新内部坐标。

使用边界：槽位为 1～16。移动通常消耗燃料，转向不消耗；unlimited 是字符串而非数字。前、上、下是动作方向，某些方法中的 side 是选择左/右工具，不是任意行动方向。

只读探测，并处理没有方块的情况

Lua · 自编示例
if not turtle then error("Run this on a turtle.", 0) end
local found, block = turtle.inspect()
if found then
  print(block.name)
  print(textutils.serialize(block.state))
else
  printError(block)
end

资料来源：turtle

本节接口索引

turtle.craft([limit=64])

按背包中的合成网格制作；需要合成能力，无关槽位里的物品也可能使配方无效。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
limitnumber可选；默认 64
返回值（按顺序）
  • 分支 1：true
  • 分支 2：false，string

新增 1.4。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

turtle.dig([side])

尝试用工具破坏前方方块；检查成功标志与失败原因。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
sidestring可选
返回值（按顺序）
  • boolean，string | nil

变更 1.6。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

turtle.digUp([side])

尝试用工具破坏上方方块；检查成功标志与失败原因。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
sidestring可选
返回值（按顺序）
  • boolean，string | nil

变更 1.6。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

turtle.digDown([side])

尝试用工具破坏下方方块；检查成功标志与失败原因。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
sidestring可选
返回值（按顺序）
  • boolean，string | nil

变更 1.6。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

turtle.place([text])

用当前槽物品向前方放置或执行可用交互；返回成功与否。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
textstring可选
返回值（按顺序）
  • boolean，string | nil

新增 1.4。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

turtle.placeUp([text])

用当前槽物品向上方放置或执行可用交互；返回成功与否。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
textstring可选
返回值（按顺序）
  • boolean，string | nil

新增 1.4。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

turtle.drop([count])

把当前槽物品送进前方库存；没有库存时会成为掉落物。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
countnumber可选
返回值（按顺序）
  • boolean，string | nil

新增 1.31。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

turtle.dropUp([count])

把当前槽物品送进上方库存；没有库存时会成为掉落物。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
countnumber可选
返回值（按顺序）
  • boolean，string | nil

新增 1.4。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

turtle.attack([side])

尝试攻击前方实体，可选左侧或右侧工具。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
sidestring可选
返回值（按顺序）
  • boolean，string | nil

新增 1.4 · 变更 1.6。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

turtle.suck([count])

从前方库存或世界掉落物吸入背包，可限制数量。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
countnumber可选
返回值（按顺序）
  • boolean，string | nil

新增 1.4 · 变更 1.6。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

turtle.suckUp([count])

从上方库存或世界掉落物吸入背包，可限制数量。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
countnumber可选
返回值（按顺序）
  • boolean，string | nil

新增 1.4 · 变更 1.6。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

turtle.suckDown([count])

从下方库存或世界掉落物吸入背包，可限制数量。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
countnumber可选
返回值（按顺序）
  • boolean，string | nil

新增 1.4 · 变更 1.6。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

turtle.refuel([count])

消耗当前槽的燃料补充储备；数量 0 可探测是否为燃料而不消耗。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
countnumber可选
返回值（按顺序）
  • 分支 1：true
  • 分支 2：false，string

新增 1.4。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

pocket口袋电脑升级

口袋电脑可以通过 API 更换背面升级，不是让程序直接修改玩家任意装备。

使用边界：可用升级必须存在于玩家物品栏，替换失败时检查返回原因。

资料来源：pocket

本节接口索引

redstone本机红石

将红石输入读取与输出控制分开：输入表示外部状态，输出表示程序设置。rs 是常用的兼容入口。

使用边界：六向名字相对电脑朝向。模拟信号范围为 0～15；束线能力需要相容的外部实现。收到 redstone 事件后重新读取感兴趣的侧面。

观察输入，不修改输出

Lua · 自编示例
local previous = redstone.getAnalogInput("back")
print("back:", previous)
while true do
  os.pullEvent("redstone")
  local current = redstone.getAnalogInput("back")
  if current ~= previous then
    print(previous, "->", current)
    previous = current
  end
end

资料来源：redstone

本节接口索引

redstone.setAnalogueOutput(side, value)

设置这一侧的输出强度，合法范围为 0～15。 与 Analog 拼写方法等价。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
sidestring必需
valuenumber必需
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.51。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

disk按名称访问磁盘机

disk 是针对磁盘机的便利入口，每次传入磁盘机名称。它与包装后的 drive 对象操作的是同一类设备。

使用边界：磁盘机内可以放数据盘、唱片或其他物品。存在物品、可挂载数据和可播放音频是三个不同条件。

资料来源：disk

本节接口索引

commands命令电脑

这是具有命令权限的电脑接口，不是普通生存电脑默认可用的功能。用它查询方块或实体时，也应控制查询范围和频率。

使用边界：普通电脑上先检查 commands 是否存在。异步调用返回任务编号，应匹配 task_complete，不能把任务已提交当作命令成功。

资料来源：commands

本节接口索引

commands.exec(command)

执行一条 Minecraft 命令，返回成功标志、输出行及可能的影响数量。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
commandstring必需
返回值（按顺序）
  • boolean，{ string ... }，number | nil

变更 1.71 · 变更 1.85.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

inventory通用物品库存

在有线网络中按设备名称搬运，来源槽与目标槽都从 1 开始。先 list 得到概况，再按需查询详细信息。

使用边界：list 是稀疏槽位表，用 pairs，不要靠 # 或 ipairs 统计全部槽。搬运返回实际件数，可能为 0；同名设备必须是本网络可访问的库存。

只读盘点：正确遍历稀疏槽位

Lua · 自编示例
local store = peripheral.find("inventory")
if not store then error("Connect an inventory first.", 0) end
local total = 0
for slot, stack in pairs(store.list()) do
  print(slot, stack.name, stack.count)
  total = total + stack.count
end
print("Items:", total, "Slots:", store.size())

资料来源：inventory

本节接口索引

fluid_storage通用流体库存

将多个可访问储罐看作网络端点，按流体注册名选择搬运对象。物品槽位参数不能直接套用到流体接口。

使用边界：返回实际转移量，而非请求量。容器是否暴露通用能力与模组、加载器有关；流体数量单位按当前平台实现核对，不能跨环境无条件当作 mB。

资料来源：fluid_storage

本节接口索引

energy_storage通用能量读数

这个通用接口用于监测，不提供直接的能量推拉方法。传能仍由管线、机器侧配置或对应模组完成。

使用边界：能量读数使用 FE 口径，但并不是每台储能方块都实现这个外设类型。先检查 peripheral.hasType。

资料来源：energy_storage

本节接口索引

computer另一台电脑的电源

通过相邻连接或有线网络取得其他电脑的外设对象，可管理电源并读取编号与标签。

使用边界：这个接口不是远程执行任意 Lua 的接口。需要交换业务数据时另用网络消息。

资料来源：computer

本节接口索引

drive磁盘机对象

包装磁盘机后，不再需要像 disk API 那样每次传入名字。用挂载路径操作文件，而不是猜测一定叫 disk。

使用边界：多台磁盘机会有不同挂载名。磁盘弹出后，原路径和句柄可能失效；处理 disk / disk_eject 重新检查。

资料来源：drive

本节接口索引

printer打印机

打印流程分三步：申请一页、写入内容、提交到输出槽。要分别处理纸张、墨水和输出空间不足。

使用边界：不是调用 write 就完成了实体打印；newPage 与 endPage 都返回是否成功。光标和页面尺寸以字符格计算。

资料来源：printer

本节接口索引

redstone_relay远端红石中继

中继让电脑通过外设连接控制另一个位置的红石。调用习惯与本机 redstone 接近，但侧面相对中继本身。

使用边界：中继输入变化也使用 redstone 事件，事件本身不列出哪个侧面改变。保存旧状态，再读取目标侧面比较。

资料来源：redstone_relay

本节接口索引

speaker扬声器

游戏音效、音符盒音符和 PCM 音频是三条不同入口。连续音频需要先解码成采样数组，再按缓冲可用情况送入。

使用边界：playAudio 接收 48 kHz、-128～127 的采样整数，一次最多 131072 个。返回 false 时等待本扬声器的 speaker_audio_empty，然后重试同一批，不要丢掉它。

资料来源：speaker

本节接口索引

turtle_storage海龟储物升级（实验性）

这是装备在海龟上的储物外设，例如可访问所装备容器的内容。其搬运目标固定为海龟背包，不接收另一外设名字。

使用边界：官网标为 1.121.0 新增且实验性，需要启用 computercraft/turtle_storage 数据包，方法仍可能变化。不要把它写成旧版本默认可用的箱子接口。

资料来源：turtle_storage

本节接口索引

command命令方块外设

对接命令方块的管理入口，与 commands 命令电脑 API 不同。只有相应服务器配置启用时才可用。

使用边界：能发现方块不等于拥有任意命令权限。先核对服务器配置，再处理 runCommand 的失败结果。

资料来源：command

本节接口索引

require 工具库

cc.audio.dfpwmDFPWM 音频编解码

先 require("cc.audio.dfpwm")。整段转换与连续流的用法不同：流式处理要在整个音轨期间复用同一个编码器或解码器。

使用边界：不要给每个分块重新 make_decoder，否则块间状态丢失。解码后仍须遵守扬声器的采样数上限与缓冲等待。

资料来源：cc.audio.dfpwm

本节接口索引

cc.base64Base64 数据包装

先 require("cc.base64")。把二进制装进 JSON 或其他文本通道时可用 Base64，但这不是加密。

使用边界：默认末两位字符为 +/，替代字符必须是长度 2 的字符串。解码遇到非法数据或缺失必要填充会返回失败，不应默默使用损坏内容。

本地往返转换

Lua · 自编示例
local base64 = require("cc.base64")
local packed = base64.encode("station:42")
local unpacked, reason = base64.decode(packed)
if not unpacked then error(reason, 0) end
print(packed)
print(unpacked)

资料来源：cc.base64

本节接口索引

cc.completion输入框补全

先加载 cc.completion，把它的结果交给 read 的补全回调。返回值是应追加的后缀，不是整段替换文本。

使用边界：add_space 决定完成后是否附空格。自由输入和受限选项应分别校验，补全候选本身不是输入验证。

资料来源：cc.completion

本节接口索引

cc.expect参数检查

模块入口用 expect 检查位置参数，用 field 检查选项表，再用 range 限制数值。

使用边界：检查失败会抛错；它们不负责将字符串转成数字。先决定是否允许类型转换，再进行检查。

把错误挡在函数入口

Lua · 自编示例
local expect = require("cc.expect")
local function setInterval(seconds)
  expect.expect(1, seconds, "number")
  expect.range(seconds, 0.1, 60)
  return seconds
end
print(setInterval(2))

资料来源：cc.expect

本节接口索引

cc.image.nftNFT 字符图

这里的 NFT 是终端文字图像格式，与区块链无关。它能保存字符及前景背景色，而 paint 图片主要表达背景色。

使用边界：先解析或加载，再绘制到指定终端。目标坐标仍以字符格计，文件加载失败需要处理。

资料来源：cc.image.nft

本节接口索引

cc.pretty可换行的结构化输出

先构建文档对象，再按目标宽度渲染；适合调试复杂表和输出结构化报告。文档对象不是普通字符串。

使用边界：group 决定一组内容能否压成一行；长单词本身不会因为设置宽度就被截断。ribbon_frac 默认 0.6，表示用于内容的宽度比例。

资料来源：cc.pretty

本节接口索引

cc.pretty.pretty(obj [, options])

把任意对象转成便于阅读的文档，可显示函数参数或来源。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
objany必需
options{ function_args = boolean , function_source = boolean }可选
返回值（按顺序）
  • Doc

变更 1.88.0。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

cc.pretty.pretty_print(obj [, options [, ribbon_frac=0.6]])

将对象格式化后直接输出，适合快速查看表结构。

参数、返回值与版本
参数
参数名类型 / 字段结构约定
objany必需
options{ function_args = boolean , function_source = boolean }可选
ribbon_fracnumber可选；默认 0.6
返回值（按顺序）

官方条目未声明返回值；不要依赖未约定的结果。

新增 1.99。变更细节以对应版本原始定义为准。

本节说明与使用边界 · 核对官方定义

cc.require自建模块环境

普通程序直接使用 require；只有编写自己的程序运行器、包环境或隔离工具时才需要 cc.require.make。

使用边界：给定的环境表不是安全沙箱的自动保证。模块能访问什么，取决于环境里暴露了哪些功能。

资料来源：cc.require

本节接口索引

cc.shell.completion命令参数补全

用 build 按参数位置声明规则，再交给 shell.setCompletionFunction。文件路径补全会使用当前 shell 的工作目录。

使用边界：每个位置可放 nil、回调或带选项的表；末尾表可用 many=true 处理余下参数。回调收到 shell、当前文本和之前的参数。

资料来源：cc.shell.completion

本节接口索引

cc.strings字符串排版与分割

把固定列宽和折行逻辑放到工具库里，而不是在每个界面重写。先 require("cc.strings")。

使用边界：Lua 模式不是正则表达式；如果分隔符应该按字面匹配，显式设 plain=true。默认宽度取终端宽度。

将宽度约束集中处理

Lua · 自编示例
local strings = require("cc.strings")
local width = term.getSize()
local lines = strings.wrap("Inventory report for the north warehouse.", width)
for _, line in ipairs(lines) do print(line) end
print(strings.ensure_width("READY", width))

资料来源：cc.strings

本节接口索引

事件载荷

先收事件名，再按位置解包。需要保留末尾 nil 时用 table.pack(os.pullEvent())；过滤式等待可能丢弃其他事件，多个监听任务可交给 parallel。

alarm游戏时刻闹钟

到达 os.setAlarm 安排的时刻时产生。

使用边界：用返回编号区分多个闹钟，不按到达顺序猜测。

载荷顺序

"alarm" → alarmId:number

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：alarm

timer延时到期

os.startTimer 到期后送出一次通知。

使用边界：用编号匹配；服务器卡顿可能让实际等待时间更长。

载荷顺序

"timer" → timerId:number

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：timer

char输入字符

用于文字输入，得到实际产生的字符。

使用边界：Ctrl、方向键等不一定产生字符；快捷键改用 key。

载荷顺序

"char" → text:string

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：char

key按下按键

按键按下或持续按住时产生，isHeld 区分重复按键。

使用边界：使用 keys 常量比较，不写死数值。

载荷顺序

"key" → keyCode:number | isHeld:boolean

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：key

key_up释放按键

按键释放或终端关闭导致按住状态结束时产生。

载荷顺序

"key_up" → keyCode:number

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：key_up

paste粘贴文字

用户向终端粘贴文字时产生，内容不必是单个字符。

使用边界：自行处理换行和长度，不能把它当作可信命令直接执行。

载荷顺序

"paste" → text:string

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：paste

mouse_click鼠标按下

高级电脑终端里的鼠标按下事件。

使用边界：按钮 1/2/3 分别是左/右/中键，坐标从 1 开始。

载荷顺序

"mouse_click" → button:number | x:number | y:number

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：mouse_click

mouse_up鼠标释放

鼠标按钮松开，或按住时移出终端会结束按压。

载荷顺序

"mouse_up" → button:number | x:number | y:number

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：mouse_up

mouse_drag鼠标拖动

按住鼠标按钮移动时报告当前坐标。

载荷顺序

"mouse_drag" → button:number | x:number | y:number

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：mouse_drag

mouse_scroll鼠标滚轮

滚轮变化时报告方向与当时指针位置。

使用边界：向上是 -1，向下是 1；这不是鼠标按钮编号。

载荷顺序

"mouse_scroll" → direction:number | x:number | y:number

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：mouse_scroll

monitor_touch监视器触摸

玩家右击高级监视器时产生。

使用边界：名字可能是侧面，也可能是有线网络名称；坐标单位为字符格。

载荷顺序

"monitor_touch" → name:string | x:number | y:number

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：monitor_touch

monitor_resize监视器尺寸改变

监视器拼接或缩放等改变可用字符尺寸时产生。

使用边界：对该设备重新调用 getSize 并重绘。

载荷顺序

"monitor_resize" → name:string

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：monitor_resize

term_resize主终端尺寸改变

例如多标签栏出现或消失后，需要更新布局。

使用边界：重定向场景也可能收到该通知；按当前终端尺寸重画。

载荷顺序

"term_resize" → 无额外参数

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：term_resize

peripheral外设接入

相邻设备或有线网络新外设可访问时产生。

使用边界：再次读取类型和方法，不沿用旧设备的能力假设。

载荷顺序

"peripheral" → name:string

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：peripheral

peripheral_detach外设离开

设备被移除或网络断开后产生。

使用边界：撤销旧包装对象的业务使用，等待设备重新出现。

载荷顺序

"peripheral_detach" → name:string

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：peripheral_detach

disk介质插入

磁盘机插入介质时产生。

使用边界：重新检查是否有数据以及实际挂载路径。

载荷顺序

"disk" → name:string

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：disk

disk_eject介质移除

介质从磁盘机移除时产生。

载荷顺序

"disk_eject" → name:string

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：disk_eject

redstone红石输入变化

电脑或红石中继的输入发生变化时产生。

使用边界：事件不携带侧面和强度；读取设备状态与旧值比较。

载荷顺序

"redstone" → 无额外参数

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：redstone

turtle_inventory海龟背包变化

海龟物品栏发生变化时产生。

使用边界：重新读取相关槽位；不要假设只改变了选中槽。

载荷顺序

"turtle_inventory" → 无额外参数

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：turtle_inventory

modem_message原始 modem 消息

已打开的通道收到消息时报告通道、回信通道与载荷。

使用边界：跨维消息的距离可能为 nil；有线网络的值也不应当作无线测距。载荷不是可信身份。

载荷顺序

"modem_message" → side:string | channel:number | replyChannel:number | payload:any | distance:number/nil

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：modem_message

rednet_messageRednet 消息

由 CraftOS 将 modem 消息转换为 Rednet 消息。

使用边界：通常交给 rednet.receive；自己收事件时保留同样的类型和协议校验。

载荷顺序

"rednet_message" → senderId:number | message:any | protocol:string/nil

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：rednet_message

http_successHTTP 请求完成

异步 HTTP 请求成功后取得响应句柄。

使用边界：读完关闭句柄；并发请求同一 URL 时需自己管理对应关系。

载荷顺序

"http_success" → url:string | response:http.Response

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：http_success

http_failureHTTP 请求失败

连接失败、超时或 HTTP 错误状态通过这里报告。

使用边界：存在错误响应时可以读取错误正文，但仍必须关闭句柄。

载荷顺序

"http_failure" → url:string | reason:string | response:http.Response/nil

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：http_failure

http_checkURL 规则检查完成

http.checkURLAsync 的结果。

使用边界：这是配置允许性检查，不是服务健康检测。

载荷顺序

"http_check" → url:string | allowed:boolean | reason:string/nil

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：http_check

websocket_successWebSocket 已连接

异步握手成功后取得连接对象。

载荷顺序

"websocket_success" → url:string | socket:http.Websocket

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：websocket_success

websocket_failureWebSocket 连接失败

异步握手失败，连接对象未建立。

载荷顺序

"websocket_failure" → url:string | reason:string

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：websocket_failure

websocket_messageWebSocket 收到消息

已连接的 WebSocket 收到一条消息。

使用边界：按 binary 区分数据用途，不把不可信消息直接当 Lua 执行。

载荷顺序

"websocket_message" → url:string | message:string | binary:boolean

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：websocket_message

websocket_closedWebSocket 已断开

已打开的连接关闭时产生。

使用边界：异常断开可能没有关闭原因与状态码；重连要设置退避。

载荷顺序

"websocket_closed" → url:string | reason:string/nil | code:number/nil

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：websocket_closed

speaker_audio_empty音频缓冲可继续写入

对应扬声器能够继续接收采样时产生。

使用边界：不是整首音轨已经播放完；应重试之前未接收的采样块。

载荷顺序

"speaker_audio_empty" → name:string

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：speaker_audio_empty

setting_changed设置值变化

通过设置 API 修改值时报告新旧值。

使用边界：可能包含 nil，收集事件参数时注意 Lua 表长度不能表示末尾 nil。

载荷顺序

"setting_changed" → name:string | newValue:any | oldValue:any

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：setting_changed

task_complete异步任务完成

用于领取异步任务结果，例如命令电脑提交的任务。

使用边界：匹配 taskId，并按照 success 分支解释后续参数。

载荷顺序

"task_complete" → taskId:number | success:boolean | 失败原因（失败时） | 任务附加返回值…

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：task_complete

computer_command服务器命令消息

服务器的 /computercraft queue 向命令电脑传入参数。

使用边界：不要将玩家传入字符串未经校验拼接成高权限命令。

载荷顺序

"computer_command" → args:string…

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：computer_command

terminate用户终止请求

持续按住 Ctrl+T 时请求结束程序。

使用边界：pullEvent 将其转为错误；pullEventRaw 要自行退出，不能只忽略它。

载荷顺序

"terminate" → 无额外参数

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：terminate

file_transfer拖放导入文件

用户把本机文件拖到打开的电脑界面后，程序可以枚举待接收文件。

使用边界：每个文件是只读二进制句柄并提供 getName；保存前限制目标目录、确认覆盖，读完关闭。

载荷顺序

"file_transfer" → files:TransferredFiles

第一项始终是事件名；后面才是本行列出的载荷。这里的字段名用于解释位置，不代表返回的是字段表。

资料来源：file_transfer

本节接口索引

搭建与程序组织

建立可验证的 GPS 定位

定位程序依赖多个坐标已知、持续加载的主机。把建设和测试分成两步：先确认主机坐标，再让独立客户端请求定位。

布点

准备四台带无线 modem 的主机，使位置在三个坐标轴上展开，不全部落在同一平面。示意布点可为 (200,80,200)、(206,80,200)、(200,86,200)、(200,80,206)；这是示例，不是固定配方。

坐标与加载

记录每台电脑方块的实际坐标，不要抄玩家脚下坐标或 modem 方块坐标。主机应保持区块加载；末影 modem 可改善无线覆盖，但不免除加载与有效测距要求。

启动和验收

各主机运行 gps host x y z，三个数换成该主机坐标。客户端装无线 modem，用 gps locate 或 gps.locate 测试。失败依次检查主机运行、加载、范围、坐标填写和共面布局。

客户端校验定位结果

Lua · 自编示例
local x, y, z = gps.locate(4, false)
if x == nil then
  error("GPS unavailable: check hosts, loading and radio range.", 0)
end
print(string.format("Position %.2f / %.2f / %.2f", x, y, z))

资料来源：Setting up GPS

开发服务的 HTTP 访问

默认阻止私网访问是服务器的安全边界。需要连接局域网服务时，由服务器管理者为目标地址添加最小范围规则，而不是把所有私网限制全部删除。

先找对配置

MC 1.13+ 且 CC:T 1.87.0+ 通常在世界目录的 serverconfig/computercraft-server.toml 配置 http.rules；1.95.0+ 可见 $private 规则。更旧版本使用不同配置文件和字段，不能原样照搬。

排错顺序

确认服务监听地址、端口、DNS 与网络可达性，再看规则是否允许。http.checkURL 通过仅说明配置允许；连接超时仍可能是网络或服务问题。

最小授权

仅允许需要的主机、端口及流量额度，保留其余拒绝规则，按该版本要求重新加载或重启。多人服务器上的电脑代码可能由其他玩家编写，不应开放访问宿主的管理接口和凭据服务。

历史配置

CC:T 1.86.2 及更早的 MC 1.13+ 配置可在 config/computercraft-common.toml；MC 1.12.2 及以前使用 ComputerCraft.cfg。以安装版本的官方指南为准，修改前备份。

资料来源：Allowing access to local IPs

连续播放音频

采用“读取一块 → 解码 → 等待缓冲可用 → 提交”的流水线，不把整首音轨展开到一个 Lua 表里。

先看格式

扬声器需要 48000 个采样/秒，采样是 -128～127 的整数。MP3 文件不能直接传给 playAudio；先使用合适工具转成 DFPWM 等可解码格式。

把状态留在块之间

同一音轨只创建一次 DFPWM 解码器。16 KiB 的 DFPWM 数据可展开为 131072 个采样，正好达到单次上限；示例采用更小的 4096 字节块。

缓冲和结束

提交失败时保留同一批采样，等待对应扬声器的事件再试。文件读完可以关闭文件，但不要立刻 stop，否则尚未播放完的尾部会被截断。

音频加工

调整音量或混音可处理采样幅度，结果应限制在合法范围；延迟效果要跨块保存历史。简单跳过或重复采样会同时影响速度与音高，不能声称它是保真变调。

播放自己的 DFPWM 文件

Lua · 自编示例
local codec = require("cc.audio.dfpwm")
local speaker = peripheral.find("speaker")
if not speaker then error("Connect a speaker first.", 0) end
local file, reason = fs.open("announcement.dfpwm", "rb")
if not file then error(reason, 0) end
local decode = codec.make_decoder()
local name = peripheral.getName(speaker)
local ok, failure = pcall(function()
  while true do
    local bytes = file.read(4096)
    if not bytes then break end
    local samples = decode(bytes)
    while not speaker.playAudio(samples) do
      local _, available
      repeat
        _, available = os.pullEvent("speaker_audio_empty")
      until available == name
    end
  end
end)
file.close()
if not ok then error(failure, 0) end

资料来源：Playing audio with speakers

开机自动运行

给长期运行的服务单独写主程序，启动文件只负责加载配置与启动服务。这样可以直接在终端运行服务，便于排错。

单个入口

电脑根目录的 /startup.lua 可调用主程序。先手动运行主程序确认能启动，再重启电脑，不要把每次重启都当成唯一调试方式。

多个初始化步骤

/startup/ 中的程序按字典序执行。可用 10-config.lua、20-service.lua 显示表达先后关系；前一个永不返回的循环会挡住后面的启动步骤。

外部启动与恢复

可启动磁盘可能先于硬盘入口执行。排查“改了 startup 仍没生效”时，检查连接磁盘及 shell.allow_disk_startup、shell.allow_startup，不要只检查根目录文件。

启动入口只负责启动服务

Lua · 自编示例
-- Save as /startup.lua after creating /station.lua.
local program = "/station.lua"
if not fs.exists(program) then
  error("Missing service: " .. program, 0)
end
if not shell.execute(program) then
  error("Station service exited with an error.", 0)
end

资料来源：Running programs on computer startup

把程序拆成模块

先决定模块输出的能力，再决定文件名。主程序只依赖返回值，不依赖模块把名字偷偷放进全局环境。

文件与模块名

require("factory.stock") 查找 factory/stock.lua 或匹配搜索模板的入口；模块名不写 .lua，目录层次用点号。相对搜索以当前程序为基准，不是随意以终端当前目录为基准。

导出与缓存

模块末尾通常返回函数表，也可以返回函数或其他值。同一模块的加载结果会缓存；不要依赖重复 require 来重做初始化。需要可重复动作时导出一个显式函数。

查找失败时

先检查模块文件大小写、程序所在位置和 package.path，再检查模块本身是否报错。自建运行环境使用 cc.require.make；普通业务程序不必替换加载器。

两个文件：模块只导出明确能力

Lua · 自编示例
-- File: station_format.lua
local function quantity(name, amount)
  return string.format("%s: %d", name, amount)
end
return { quantity = quantity }

-- Save the following separately as report.lua:
-- local format = require("station_format")
-- print(format.quantity("Iron", 24))

资料来源：Reusing code with require

数据结构与兼容

方块资料字段

方块查询返回的是当时的资料快照，不是可写入的世界对象。常用入口为 turtle.inspect 与 commands.getBlockInfo。

必读字段

name:string 是命名空间 ID；state:table 表示方块状态。判断农作物成熟、活塞朝向等优先读状态字段，而不是依赖旧版 metadata 数字。

标签与颜色

tags 是标签名到 true 的映射，测试用 info.tags["某标签"]；mapColour / mapColor 是可选的 RGB 整数，不是 colors 的 16 色位常量。

版本与缺项

方块状态字段在 1.76 加入，地图颜色在 1.117.0 加入。不同提供者可能有附加字段，程序应先确认字段存在，而不是假定所有方块都长一样。

资料来源：Block details

旧程序迁移检查

迁移时先记录 Minecraft、CC:T 和外设附属版本，再按实际使用的能力核查。核心 API 稳定不代表所有模组外设也稳定。

CC:T 1.109.0～1.109.3

Lua 运行时迁移涉及 _ENV、函数环境和变长参数。函数内改用 ...，不要依赖旧式 arg；load 默认使用全局环境。string.dump 与二进制 chunk 不再可用，随机数算法也已变化。

字节与文字

这一时期文件、HTTP 与 WebSocket 统一使用原始字节。非 ASCII 内容不能继续假定旧版文本模式会自动做 UTF-8 转换。处理网络编码时明确约定格式。

Minecraft 1.13

键码随 LWJGL 变化，使用 keys 常量，并分别考虑主回车与小键盘回车。旧版物品 damage/方块 metadata 分类应改用物品 ID 和方块状态；自定义 ROM 改由数据包提供。

海龟与电脑状态

MC 1.13 后海龟可含水，不再把穿过水源等同于破坏水。CC:T 1.88.0 起，未命名电脑被破坏后也保留 ID，因此不能再依赖其像普通方块一样堆叠。

老 shell 行为

ComputerCraft 1.80pr1 后 shell.run 程序有独立环境；包含 / 的程序路径按当前目录解析，不再按所有搜索路径补全。

资料来源：Incompatibilities between versions

服务器管理员工具

/computercraft 用于观察和管理运行中的电脑，不是电脑 Lua 中的普通函数。执行前明确目标范围，尤其避免无参数的批量电源操作。

选择目标

电脑选择器为 @c[...]，支持 id、instance、family、label、distance；#编号 是按 ID 选择的简写。不要把它与实体选择器 @e 混用。

查看与电源

dump 列出已加载电脑，也可进一步查看单台；turn-on / shutdown 处理指定目标，省略目标可能作用于全部已加载电脑。tp 和 view 分别用于传送与远程打开终端。

性能定位

track start 开始统计，track stop 停止并查看，track dump 可在过程中读取。可选字段如 server_tasks_count、server_tasks、http_upload、http_download，分别用于任务和网络开销排查。

权限与玩家消息

多人服务器中管理子命令通常需要 OP；queue 可由普通玩家向命令电脑送事件。单人无作弊时可用部分诊断、电源、统计命令，tp/view 仍需作弊权限；权限模组可用 computercraft.command.NAME 细分授权。

资料来源：The /computercraft command

数据包与 ROM 扩展

数据包是服务器分发统一程序和扩展模组规则的途径。包格式依 Minecraft 版本变化，先选匹配版本，再制作内容。

ROM 路径

ROM 程序放在 data/computercraft/lua/rom 下。programs 提供命令，modules/main 提供 require 模块，autorun 提供开机初始化。数据包路径与文件名使用小写。

旧式 API 目录

rom/apis 会在启动时加载；其 http、turtle、pocket、command 子目录分别按相应能力启用。新模块优先放在 modules，而不是继续扩大全局 API。

行为标签

computercraft:turtle_can_place 是可被海龟使用的物品标签；turtle_can_use 指可交互方块。always_breakable 扩展所有工具都能破坏的方块；turtle_shovel_harvestable、turtle_sword_harvestable、turtle_hoe_harvestable 分别针对工具。

发布与刷新

本页不混写不同版本的升级 JSON 格式。1.20.x、1.21.x 和 26.3 的官方数据包参考为独立版本页面。修改后按环境执行 /reload 并重新启动相关电脑；在测试世界确认后再分发。

版本参考：1.20.x · 1.21.x · 26.3

资料来源：Data packs

实体资料字段

1.118.0 起的相关实体查询可用于命令电脑监测。先确认当前版本存在 commands.getEntities。

识别与名称

name 是实体类型 ID，不是某一个体的持久身份。displayName 是服务器语言下的显示文字，不能拿它替代稳定类型判断。

生命值和标签

适用实体提供 health、maxHealth；tags 是实体类型标签集合。不要假定所有实体都有生命值，也不要将类型标签与自定义命令标记混为一谈。

资料来源：Entity details

协程间保留错误上下文

一般业务代码让错误自然传出即可；只有编写协程调度器时，才需要考虑如何把原协程栈传给 CraftOS 的错误显示层。

错误对象

普通错误可能只是字符串；CraftOS 异常对象是带 message:string、thread:thread 的表，其元表用 __name="exception" 标识。捕获错误时不能只假定它是字符串。

跨协程转交

coroutine.resume 的失败结果若仅重新包装成普通字符串，会丢失来源协程信息。自建调度器需保存来源线程，并按协议转交，避免诊断只剩调度器的位置。

parallel 的兼容处理

parallel 为兼容会被用户捕获和检查的旧式错误，并非每次都包装异常。自建调度器可研究 debug.getregistry().try_barrier 的 context，其中 co 是父协程，can_wrap 控制是否允许包装；这是底层集成约定，不是普通业务的必需模板。

资料来源：CraftOS's exception protocol

Lua 兼容性边界

CC:T 使用 Cobalt，不能仅凭 _VERSION 假定等同于完整桌面 Lua。语言语法、标准库和兼容别名需要分别判断。

常用能力

支持 goto、_ENV、__len、__pairs、rawlen、table.pack/unpack、带参数的 xpcall、package.searchpath、bit32，并保留部分旧版兼容名字。

5.3 风格能力

支持 utf8、\u{...}、string.pack/unpack/packsize、table.move、coroutine.isyieldable。没有独立整数子类型、原生位运算符或整除运算符；不要直接移植含这些语法的代码。

保留而非删除

loadstring、全局 unpack、table.maxn、math.log10、math.frexp/ldexp/pow/cosh/sinh/tanh、bit32 等旧名字仍可见；不能按“新 Lua 删除了”反推这里不存在。

没有或不等同

collectgarbage、os.execute、os.exit、string.dump、二进制 chunk 不能照搬桌面实现。getfenv/setfenv 只对带 _ENV 的 Lua 闭包有相应意义；package.loaders 没有整体换成 package.searchers。

新加入与边缘功能

官网还列有 table.create 与 utf8.offset 返回结束位置等较新能力，旧整合包不一定支持。GC 由 Java 管理，调试钩子、弱表等细节应按具体兼容表核查。

资料来源：Lua 5.2/5.3 features in CC: Tweaked

物品资料字段

列表接口适合快速概览，详细查询适合确实需要附魔、标签或耐久的判断。不要为每次刷新都对所有空槽做详细查询。

基础身份

name:string 与 count:number 表示物品类型和数量。可选的 nbt:string 是数据摘要，不是可读取的 NBT 内容；用名称和摘要区分附魔、内容等不同的同名物品。

显示与容量

displayName 是显示名称，lore 是说明行，maxCount 是堆叠上限。显示语言由服务器环境决定，业务分类不要依赖英文或中文显示名。

标签与物品组

tags 按标签名映射到 true。itemGroups 中的元素包含 id 和 displayName；MC 1.19.3～1.20.3 这个字段存在但为空，不能据此断定物品没有分类。

耐久与不可破坏

damage 是已消耗耐久，maxDamage 是最大耐久；可选 durability 为耐久条剩余比例 0～1，unbreakable 表示不可破坏。非耐久物品不能照搬这些字段。

附魔与药水

enchantments 的元素可读 name、displayName、level。potionEffects 可读效果名、显示名及可选的 duration（秒）、potency；瞬时效果不一定有持续时间。

地图色与版本

mapColour / mapColor 是可选 RGB 整数。1.94.0 扩充 NBT 摘要、标签等详细数据；1.100.9 加入物品组，1.117.0 加入地图色与药水效果。

资料来源：Item details

启动顺序与启动设置

排查开机行为时，要区分 ROM 初始化、磁盘入口和本机入口。

实际优先级

先执行 /rom/autorun。允许磁盘启动时，检查已连接磁盘，找到可启动介质后执行该介质的 startup 或 startup.lua，再执行其 startup/ 内程序。只有没找到磁盘启动项且允许本机启动时，才检查硬盘根目录。

顺序的边界

目录内文件按 fs.list 的字典序执行；多个磁盘之间的查找顺序没有保证。只保留一个可启动磁盘，或禁用磁盘启动，避免依赖不稳定顺序。

与程序设计的关系

启动脚本中定义配置和补全后应返回。长期任务集中在明确的服务入口，不能让一个初始化脚本无限循环并期待后续脚本继续执行。

资料来源：Computer startup

回到顶部