English

ComputerCraft 外设 Lua API 文档

本文档介绍以下外设所提供的 Lua 函数接口：

• 集成式姿态传感器 (integrated_pose_sensor)
• 全息投影仪 (hologram)
• 虚空引擎 (void_engine)
• 玻璃屏幕（扩展自CC监视器monitor）
• 键盘 (keyboard)

---

1. 集成式姿态传感器 (Integrated Pose Sensor)

外设类型：integrated_pose_sensor
功能：读取物理结构中质心、质量、速度、旋转矩阵等物理状态。所有读取方法均要求结构处于模拟状态，否则抛出 LuaException。
特性：会自动计算组合物理结构（如轴承和对接器）。

isSimulated(): boolean

• 描述：检查该传感器所在的结构是否处于物理模拟状态。
• 返回值：true 表示已模拟，false 表示未模拟（此时其他读取方法将失败）。

getCenterOfMassPosition(): table

• 描述：获取结构质心的世界坐标。
• 返回值：包含 x, y, z 三个键的表，值均为 number（双精度浮点数）。

getMass(): number

• 描述：获取结构的总质量。
• 返回值：质量值（double）。

getSensorPosition(): table

• 描述：获取传感器方块自身在世界空间中的位置。
• 返回值：包含 x, y, z 的表。

getStructureLinerVelocity(): table

• 描述：获取结构质心的线速度（世界坐标系）。
• 返回值：包含 x, y, z 的表。

getStructureAngleVelocity(): table

• 描述：获取结构的角速度（世界坐标系，单位为弧度/秒）。
• 返回值：包含 x, y, z 的表。

getStructureRotationMatrix(): table

• 描述：获取结构当前姿态的旋转矩阵（3×3，行主序）。
• 返回值：包含三个子列表的列表，每个子列表含三个 number，例如 {{m00, m01, m02}, {m10, m11, m12}, {m20, m21, m22}}。

getSensorFacesDirection(): table

• 描述：获取传感器各面在世界空间中的方向向量。
• 返回值：一个表，键为方向名称（如 "up", "down", "north" 等），值为对应的 {x, y, z} 向量。

getSensorEuler(): table

• 描述：获取传感器当前的欧拉角（绕 X、Y、Z 轴旋转，单位弧度）。
• 返回值：包含 x, y, z 的表。

getStructureInertia(): table

• 描述：获取结构的惯性张量矩阵（3×3）。
• 返回值：与 getStructureRotationMatrix 格式相同的 3×3 列表。

enablePhysicsTickEvent()

• 描述：启用物理更新事件推送。启用后，每次物理刻外设向连接的电脑推送事件phy_tick。
• 默认：禁用。

disablePhysicsTickEvent()

• 描述：禁用物理更新事件推送。

addConnectionWhiteList(block_id: string): boolean

• 描述：添加组合物理体连接结构的白名单。（建议添加物理轴承）
• 返回值：是否添加成功。

removeConnectionWhiteList(block_id: string)

• 描述：移除组合物理体连接结构的白名单。

相关事件

phy_tick

• 描述：物理刻事件，每物理 tick 时推送一次。
• 参数形格式：event_name, physics_state_snapshot
• event_name：事件名称，在本事件中永远为"phy_tick"。
• physics_state_snapshot：物理状态快照，详细见下文。

物理状态快照 (LuaPhyStateSnapshot)

由phy_tick事件返回，缓存该结构某一物理刻的物理状态（位置，速度等运动信息）。

getCenterOfMassPosition(): table

• 描述：获取结构质心的世界坐标。
• 返回值：包含 x, y, z 的表。

getSensorPosition(): table

• 描述：获取传感器（或快照参考点）在世界空间中的位置。
• 返回值：包含 x, y, z 的表。

getStructureLinerVelocity(): table

• 描述：获取结构质心的线速度（世界坐标系）。
• 返回值：包含 x, y, z 的表。

getStructureAngleVelocity(): table

• 描述：获取结构的角速度（世界坐标系，弧度/秒）。
• 返回值：包含 x, y, z 的表。

getStructureRotationMatrix(): table

• 描述：获取结构当前姿态的 3×3 旋转矩阵（行主序）。
• 返回值：三个子列表的列表，每个含三个 number。

getSensorFacesDirection(): table

• 描述：获取快照参考点（传感器）各面在世界空间中的方向向量。
• 返回值：包含 "right", "up", "front" 三个键的表，每个值为 {x, y, z} 向量。

getSensorEuler(): table

• 描述：获取传感器的欧拉角（绕 X、Y、Z 轴旋转，单位弧度）。
• 返回值：包含 "yaw", "pitch", "roll" 三个键的表。

mulTorqueByInertia(x: number, y: number, z: number): table

• 描述：将给定的角速度（或角冲量）向量乘以惯性张量，得到对应的角动量（或惯性作用下的扭矩效果）。
• 参数：x, y, z – 输入向量分量。
• 返回值：包含 x, y, z 的结果向量（矩阵乘法 input * inertia）。

getStructureInertia(): table

• 描述：获取结构的惯性张量矩阵（3×3）。
• 返回值：与 getStructureRotationMatrix 格式相同的 3×3 列表。

注意：此对象的所有方法均为只读，且不会抛出 LuaException（除非参数异常，但该对象方法均无参数或只接受数字）。它适合用于存储和传递某一时刻的物理状态，避免并发访问问题。

---

2. 全息投影仪 (Hologram)

外设类型：hologram
功能：管理多个帧缓冲区，绘制像素、线条、文本，并支持缓冲区之间的拷贝（blit）。所有绘图操作均在当前激活的帧缓冲区上进行。

特性说明

颜色：范围 0255（8 位），通道顺序（二进制）为RRGGBBAA，每个通道范围03，映射到[0, 120, 200, 255]。

基础控制

sync()

• 描述：将显示缓冲区立即同步，每tick仅生效一次。

setOffset(x: number, y: number, z: number)

• 描述：设置投影画面的偏移量（坐标偏移）。

setRotation(yaw: number, pitch: number, roll: number)

• 描述：设置投影画面的旋转角度（单位：度）。

setScale(scale: number)

• 描述：设置投影画面的缩放比例。

帧缓冲区管理

getMaxBufferSize(): number

• 描述：获取单个帧缓冲区允许的最大像素数量（宽×高上限）。
• 返回值：最大像素数（整数）。

getAllocatedFrameBuffers(): list

• 描述：获取当前已分配的所有帧缓冲区 ID 列表。
• 返回值：整数 ID 列表。

isFrameBufferAllocated(id: number): boolean

• 描述：检查指定 ID 的帧缓冲区是否已分配。
• 参数：id – 缓冲区 ID。
• 返回值：true 表示已分配。

allocateFrameBuffer(width: number, height: number): number

• 描述：分配一个新的帧缓冲区，并返回其 ID。
• 参数：width, height – 宽度和高度（正整数）。
• 异常：若宽高非正或超过最大尺寸限制，则抛出 LuaException。
• 返回值：新分配的缓冲区 ID。

releaseFrameBuffer(id: number)

• 描述：释放指定 ID 的帧缓冲区。
• 异常：若 ID 不存在则抛出异常。

releaseAllFrameBuffer()

• 描述：释放所有已分配的帧缓冲区。

activateFrameBuffer(id: number)

• 描述：激活指定 ID 的帧缓冲区，后续绘制操作将作用于该缓冲区。
• 异常：若 ID 不存在则抛出异常。

resize(width: number, height: number)

• 描述：调整当前激活帧缓冲区的大小。若调整成功且当前缓冲区为显示缓冲区，则自动同步。
• 异常：宽高非正或超过最大尺寸时抛出 LuaException。

绘制操作

dumpFrameBuffer(): table

• 描述：导出当前激活帧缓冲区的像素数据。
• 返回值：包含 w（宽度）、h（高度）、pixels（一维字节数组，每个元素为颜色值 0~255）的表。像素按行优先存储。

fill(args: ...)

• 描述：用指定颜色填充矩形区域。
• 参数（顺序）：
  1. ax – 起始 X 坐标（整数）
  2. ay – 起始 Y 坐标（整数）
  3. w – 矩形宽度（整数）
  4. h – 矩形高度（整数）
  5. color – 颜色值（0~255）
  6. mode – （可选）填充模式，当前仅支持 0（纯色覆盖）或 1（纯色），默认 0。其他模式暂未启用。
• 说明：坐标超出画布的部分会被自动裁剪。

blitFrameBuffer(args: ...)

• 描述：将另一个帧缓冲区的内容复制到当前激活缓冲区。
• 参数（顺序）：
  1. ax – 目标起始 X
  2. ay – 目标起始 Y
  3. bufferId – 源缓冲区 ID
  4. mode – （可选）复制模式：0 完全覆盖，1 裁剪（仅复制非透明像素），默认 0。
• 异常：若 bufferId 无效则抛出异常。

blitFrameBufferArea(args: ...)

• 描述：将另一个帧缓冲区的内容复制到当前激活缓冲区。
• 参数（顺序）：
  1. ax – 目标起始 X
  2. ay – 目标起始 Y
  3. bx – 源裁剪起始 X
  4. bx – 源裁剪起始 Y
  5. bw – 源裁剪宽
  6. bh – 源裁剪高
  7. bufferId – 源缓冲区 ID
  8. mode – （可选）复制模式：0 完全覆盖，1 裁剪（仅复制非透明像素），默认 0。
• 异常：若 bufferId 无效则抛出异常。

blit(args: ...)

• 描述：从 Lua 表（像素映射）复制像素到当前缓冲区。
• 参数（顺序）：
  1. ax – 目标起始 X
  2. ay – 目标起始 Y
  3. w – 源图像宽度
  4. h – 源图像高度
  5. src – 一个表，键为像素索引（从 0 开始的线性索引，类型为 number），值为颜色值（0~255）。
  6. mode – （可选）模式，同 blitFrameBuffer。
• 说明：只复制表中存在的像素，其余保持原样。

drawLine(args: ...)

• 描述：使用 Bresenham 算法绘制一条线段。
• 参数（顺序）：
  1. x0, y0 – 起点坐标
  2. x1, y1 – 终点坐标
  3. color – 颜色值
  4. mode – （可选）绘制模式，当前仅支持 0（覆盖）或 1（覆盖），默认 0。模式 2 暂未启用。
• 说明：线段会被裁剪到画布边界。

drawPixel(args: ...)

• 描述：绘制单个像素。
• 参数（顺序）：
  1. x, y – 坐标
  2. color – 颜色值
  3. mode – （可选）模式，默认 0。

drawText(args: ...)

• 描述：绘制文本（使用内置或自定义字体）。
• 参数（顺序）：
  1. x, y – 起始坐标（左上角）
  2. text – 要绘制的字符串（支持换行符 \n）
  3. color – 颜色值
  4. mode – （可选）绘制模式，0 或 1（裁剪透明像素），默认 1。
  5. fontName – （可选）字体名称。若未提供则使用内置字体。
• 异常：若指定的字体不存在则抛出异常。

getPixel(args: ...): number

• 描述：获取指定坐标处的像素颜色值。
• 参数：x, y。
• 返回值：颜色值（0~255）。
• 异常：若坐标越界则抛出异常。

clear(args: ...)

• 描述：清空当前帧缓冲区。
• 参数：（可选）color – 填充颜色，若省略则使用 0（透明/黑色）。

---

3. 虚空引擎 (Void Engine)

外设类型：void_engine
功能：向物理结构施加线性和角冲量，并查询能量与流体储量。所有冲量施加方法要求引擎所在结构处于模拟状态。

状态查询

isSimulated(): boolean

• 描述：检查引擎是否处于模拟结构中。
• 返回值：true 表示已模拟。

getEnergyCapacity(): number

• 描述：获取能量存储上限（FE）。
• 返回值：整数。

getEnergy(): number

• 描述：获取当前能量存储量（FE）。
• 返回值：整数。

getFluidCapacity(): number

• 描述：获取流体存储容量（mB）。
• 返回值：整数。

getFluidAmount(): number

• 描述：获取当前流体量（mB）。
• 返回值：整数。

getFEConsumeRate(): number

• 描述：获取当前能量消耗率（FE/tick）。
• 返回值：浮点数。

getFluidConsumeRate(): number

• 描述：获取当前流体消耗率（mB/tick）。
• 返回值：浮点数。

物理交互

addConnectionWhiteList(block_id: string): boolean

• 描述：添加组合物理体连接结构的白名单。（建议添加物理轴承）
• 返回值：是否添加成功。

removeConnectionWhiteList(block_id: string)

• 描述：移除组合物理体连接结构的白名单。

linearImpulse(x: number, y: number, z: number)

• 描述：施加1物理刻的线性力（世界坐标系），作用于质心。
• 参数：三个方向的力分量（单位由物理引擎定义）。
• 异常：若未模拟则抛出异常。

angularImpulse(x: number, y: number, z: number)

• 描述：施加1物理刻的扭矩（绕世界坐标轴）。
• 参数：三个轴的分量。
• 异常：若未模拟则抛出异常。

注意：冲量会被暂存并在下一次物理 tick 时应用，应用时会消耗对应的能量和流体资源。

---

4. 玻璃屏幕 (Glass Screen)

外设类型：继承自CC的 monitor，类型名仍为 monitor，但额外提供以下两个函数。

setTransparentMode(mode: boolean)

• 描述：启用或禁用屏幕的透明背景模式。
• 参数：mode – true 为透明，false 为不透明。

setTransparentColor(color: number)

• 描述：设置透明模式下背景的“透明色”映射。实际颜色取自 "0123456789abcdef" 中的第 color 个字符（color 应为 0~15）。
• 参数：color – 整数 0~15。
• 异常：若 color 不在 0~15 范围内则抛出 LuaException（内部通过 parseColour 检查）。

该类还继承了标准监视器的所有绘图函数（如 write, setCursorPos, clear 等，请自行查阅CC:T官方文档），此处不再赘述。

---

5. 键盘 (Keyboard)

外设类型：keyboard。

getType(): string

• 描述：返回外设类型标识，固定为 "keyboard"。

说明：该类并未暴露其他 Lua 函数，其主要功能是事件推送（当按键发生时，向连接的电脑发送事件）。

事件类型包含key、key_up、paste、char，与CC:T中终端的按键事件相同，详细参考官方文档Events。