English

ComputerCraft Peripheral Lua API Documentation

For Mod Version: 1.0.6 Translated by Deepseek. This document describes the Lua function interfaces provided by the following peripherals:

• Integrated Pose Sensor (integrated_pose_sensor)
• Hologram Projector (hologram)
• Void Engine (void_engine)
• Glass Screen (extends the CC monitor monitor)
• Keyboard (keyboard)

---

1. Integrated Pose Sensor

Peripheral type: integrated_pose_sensor
Function: Read physical states such as centre of mass, mass, velocity, rotation matrix, etc. of a structure. All read methods require the structure to be in a simulated state, otherwise a LuaException is thrown.
Feature: Automatically computes combined physical structures (e.g., bearings and connectors).

isSimulated(): boolean

• Description: Checks whether the structure containing this sensor is under physical simulation.
• Return: true if simulated, false otherwise (other read methods will fail).

getCenterOfMassPosition(): table

• Description: Gets the world coordinates of the structure's centre of mass.
• Return: A table with keys x, y, z, all number (double-precision floating point).

getMass(): number

• Description: Gets the total mass of the structure.
• Return: Mass value (double).

getSensorPosition(): table

• Description: Gets the position of the sensor block itself in world space.
• Return: A table with keys x, y, z.

getStructureLinerVelocity(): table

• Description: Gets the linear velocity of the structure's centre of mass (world coordinate system).
• Return: A table with keys x, y, z.

getStructureAngleVelocity(): table

• Description: Gets the angular velocity of the structure (world coordinate system, in radians/second).
• Return: A table with keys x, y, z.

getStructureRotationMatrix(): table

• Description: Gets the 3×3 rotation matrix of the structure's current orientation (row-major order).
• Return: A list of three sublists, each containing three numbers, e.g., {{m00, m01, m02}, {m10, m11, m12}, {m20, m21, m22}}.

getSensorFacesDirection(): table

• Description: Gets the direction vectors of each face of the sensor in world space.
• Return: A table with keys for directions (e.g., "up", "down", "north", etc.), values are {x, y, z} vectors.

getSensorEuler(): table

• Description: Gets the current Euler angles of the sensor (rotations about X, Y, Z axes, in radians).
• Return: A table with keys x, y, z.

getStructureInertia(): table

• Description: Gets the inertia tensor matrix of the structure (3×3).
• Return: A 3×3 list in the same format as getStructureRotationMatrix.

enablePhysicsTickEvent()

• Description: Enables physics update event pushing. Once enabled, the peripheral pushes the phy_tick event to the connected computer every physics tick.
• Default: Disabled.

disablePhysicsTickEvent()

• Description: Disables physics update event pushing.

addConnectionWhiteList(block_id: string): boolean

• Description: Adds a block ID to the whitelist for composite physical body connections (recommended for physical bearings).
• Return: Whether the addition succeeded.

removeConnectionWhiteList(block_id: string)

• Description: Removes a block ID from the composite physical body connection whitelist.

Related Events

phy_tick

• Description: Physics tick event, pushed every physics tick.
• Parameter format: event_name, physics_state_snapshot
• event_name: The event name, always "phy_tick" for this event.
• physics_state_snapshot: A snapshot of the physical state, detailed below.

Physics State Snapshot (LuaPhyStateSnapshot)

Returned by the phy_tick event, caching the physical state (position, velocity, etc.) of the structure at a given physics tick.

getCenterOfMassPosition(): table

• Description: Gets the world coordinates of the structure's centre of mass.
• Return: A table with keys x, y, z.

getSensorPosition(): table

• Description: Gets the position of the sensor (or snapshot reference point) in world space.
• Return: A table with keys x, y, z.

getStructureLinerVelocity(): table

• Description: Gets the linear velocity of the structure's centre of mass (world coordinate system).
• Return: A table with keys x, y, z.

getStructureAngleVelocity(): table

• Description: Gets the angular velocity of the structure (world coordinate system, radians/second).
• Return: A table with keys x, y, z.

getStructureRotationMatrix(): table

• Description: Gets the 3×3 rotation matrix of the structure's current orientation (row-major).
• Return: A list of three sublists, each with three numbers.

getSensorFacesDirection(): table

• Description: Gets the direction vectors of each face of the snapshot reference point (sensor) in world space.
• Return: A table with keys "right", "up", "front", each value being a {x, y, z} vector.

getSensorEuler(): table

• Description: Gets the Euler angles of the sensor (rotations about X, Y, Z axes, in radians).
• Return: A table with keys "yaw", "pitch", "roll".

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

• Description: Multiplies the given angular velocity (or angular impulse) vector by the inertia tensor, obtaining the corresponding angular momentum (or torque effect under inertia).
• Parameters: x, y, z – input vector components.
• Return: A table with keys x, y, z – the resulting vector (matrix multiplication input * inertia).

getStructureInertia(): table

• Description: Gets the inertia tensor matrix of the structure (3×3).
• Return: A 3×3 list in the same format as getStructureRotationMatrix.

Note: All methods of this object are read‑only and do not throw LuaException (except for parameter errors, but all methods take no arguments or only numbers). It is suitable for storing and passing a physical state at a given moment, avoiding concurrency issues.

---

2. Hologram Projector

Peripheral type: hologram
Function: Manages multiple framebuffers, drawing pixels, lines, text, and supports copying (blitting) between buffers. All drawing operations are performed on the currently active framebuffer.

Feature Notes

Colour: Range 0–255 (8‑bit), channel order (binary) is RRGGBBAA, each channel ranges 0–3, mapped to [0, 120, 200, 255].

Basic Control

sync()

• Description: Immediately synchronises the display buffer; takes effect only once per tick.

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

• Description: Sets the offset of the projection (coordinate shift).

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

• Description: Sets the rotation angles of the projection (in degrees).

setScale(scale: number)

• Description: Sets the scaling factor of the projection.

Framebuffer Management

getMaxBufferSize(): number

• Description: Gets the maximum number of pixels allowed for a single framebuffer (width × height upper limit).
• Return: Maximum pixel count (integer).

getAllocatedFrameBuffers(): list

• Description: Gets the list of IDs of all currently allocated framebuffers.
• Return: A list of integer IDs.

isFrameBufferAllocated(id: number): boolean

• Description: Checks whether the framebuffer with the given ID is allocated.
• Parameters: id – buffer ID.
• Return: true if allocated.

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

• Description: Allocates a new framebuffer and returns its ID.
• Parameters: width, height – positive integers.
• Exception: Throws LuaException if width/height are non‑positive or exceed the maximum size.
• Return: The newly allocated buffer ID.

releaseFrameBuffer(id: number)

• Description: Releases the framebuffer with the given ID.
• Exception: Throws if the ID does not exist.

releaseAllFrameBuffer()

• Description: Releases all allocated framebuffers.

activateFrameBuffer(id: number)

• Description: Activates the framebuffer with the given ID; subsequent drawing operations will affect this buffer.
• Exception: Throws if the ID does not exist.

resize(width: number, height: number)

• Description: Resizes the currently active framebuffer. If the resize succeeds and the current buffer is the display buffer, it is automatically synchronised.
• Exception: Throws LuaException if width/height are non‑positive or exceed the maximum size.

Drawing Operations

dumpFrameBuffer(): table

• Description: Exports the pixel data of the currently active framebuffer.
• Return: A table containing w (width), h (height), and pixels (a 1‑D byte array, each element a colour value 0–255). Pixels are stored in row‑major order.

fill(args: ...)

• Description: Fills a rectangular area with a specified colour.
• Parameters (in order):
  1. ax – starting X coordinate (integer)
  2. ay – starting Y coordinate (integer)
  3. w – rectangle width (integer)
  4. h – rectangle height (integer)
  5. color – colour value (0–255)
  6. mode – (optional) fill mode, currently only 0 (solid overwrite) or 1 (solid) are supported; default 0. Other modes are not yet enabled.
• Note: Coordinates outside the canvas are automatically clipped.

blitFrameBuffer(args: ...)

• Description: Copies the content of another framebuffer into the currently active buffer.
• Parameters (in order):
  1. ax – target starting X
  2. ay – target starting Y
  3. bufferId – source buffer ID
  4. mode – (optional) copy mode: 0 full overwrite, 1 clipped (copy only non‑transparent pixels); default 0.
• Exception: Throws if bufferId is invalid.

blitFrameBufferArea(args: ...)

• Description: Copies a rectangular area from another framebuffer into the currently active buffer.
• Parameters (in order):
  1. ax – target starting X
  2. ay – target starting Y
  3. bx – source crop starting X
  4. by – source crop starting Y
  5. bw – source crop width
  6. bh – source crop height
  7. bufferId – source buffer ID
  8. mode – (optional) copy mode: 0 full overwrite, 1 clipped (copy only non‑transparent pixels); default 0.
• Exception: Throws if bufferId is invalid.

blit(args: ...)

• Description: Copies pixels from a Lua table (pixel map) into the current buffer.
• Parameters (in order):
  1. ax – target starting X
  2. ay – target starting Y
  3. w – source image width
  4. h – source image height
  5. src – a table where keys are pixel indices (linear index starting from 0, type number) and values are colour values (0–255).
  6. mode – (optional) mode, same as blitFrameBuffer.
• Note: Only pixels present in the table are copied; others remain unchanged.

drawLine(args: ...)

• Description: Draws a line segment using Bresenham's algorithm.
• Parameters (in order):
  1. x0, y0 – start coordinates
  2. x1, y1 – end coordinates
  3. color – colour value
  4. mode – (optional) drawing mode, currently only 0 (overwrite) or 1 (overwrite) are supported; default 0. Mode 2 is not yet enabled.
• Note: The line is clipped to the canvas boundaries.

drawPixel(args: ...)

• Description: Draws a single pixel.
• Parameters (in order):
  1. x, y – coordinates
  2. color – colour value
  3. mode – (optional) mode, default 0.

setUnicodeMode(enable: boolean)

• Description: Enables or disables Unicode character conversion when drawing text.
• Parameters: enable – true to enable conversion, false to disable.

drawText(args: ...)

• Description: Draws text (using built‑in or custom font).
• Parameters (in order):
  1. x, y – starting coordinates (top‑left corner)
  2. text – string to draw (supports newline \n)
  3. color – colour value
  4. mode – (optional) drawing mode, 0 or 1 (clip transparent pixels), default 1.
  5. fontName – (optional) font name. If not provided, the built‑in font is used.
• Exception: Throws if the specified font does not exist.

getPixel(args: ...): number

• Description: Gets the colour value of the pixel at the given coordinates.
• Parameters: x, y.
• Return: Colour value (0–255).
• Exception: Throws if coordinates are out of bounds.

clear(args: ...)

• Description: Clears the current framebuffer.
• Parameters: (optional) color – fill colour; if omitted, uses 0 (transparent/black).

---

3. Void Engine

Peripheral type: void_engine
Function: Applies linear and angular impulses to a physical structure, and queries energy and fluid reserves. All impulse application methods require the engine's structure to be in a simulated state.

Status Queries

isSimulated(): boolean

• Description: Checks whether the engine is in a simulated structure.
• Return: true if simulated.

getEnergyCapacity(): number

• Description: Gets the energy storage capacity (FE).
• Return: Integer.

getEnergy(): number

• Description: Gets the current energy stored (FE).
• Return: Integer.

getFluidCapacity(): number

• Description: Gets the fluid storage capacity (mB).
• Return: Integer.

getFluidAmount(): number

• Description: Gets the current fluid amount (mB).
• Return: Integer.

getFEConsumeRate(): number

• Description: Gets the current energy consumption rate (FE/tick).
• Return: Floating point number.

getFluidConsumeRate(): number

• Description: Gets the current fluid consumption rate (mB/tick).
• Return: Floating point number.

Physical Interaction

addConnectionWhiteList(block_id: string): boolean

• Description: Adds a block ID to the whitelist for composite physical body connections (recommended for physical bearings).
• Return: Whether the addition succeeded.

removeConnectionWhiteList(block_id: string)

• Description: Removes a block ID from the composite physical body connection whitelist.

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

• Description: Applies a linear force for one physics tick (world coordinate system), acting at the centre of mass.
• Parameters: Force components in three directions (units defined by the physics engine).
• Exception: Throws if not simulated.

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

• Description: Applies a torque for one physics tick (about world coordinate axes).
• Parameters: Components for the three axes.
• Exception: Throws if not simulated.

Note: Impulses are queued and applied at the next physics tick, consuming corresponding energy and fluid resources.

---

4. Glass Screen

Peripheral type: Inherits from CC's monitor; the type name remains monitor, but it provides the following two additional functions.

setTransparentMode(mode: boolean)

• Description: Enables or disables the screen's transparent background mode.
• Parameters: mode – true for transparent, false for opaque.

setTransparentColor(color: number)

• Description: Sets the "transparent colour" mapping for the background in transparent mode. The actual colour is taken from the character at index color in the string "0123456789abcdef" (color should be 0–15).
• Parameters: color – integer 0–15.
• Exception: Throws LuaException if color is outside 0–15 (internally checked via parseColour).

This class also inherits all standard monitor drawing functions (e.g., write, setCursorPos, clear, etc. – please refer to the official CC:T documentation for details). They are not repeated here.

---

5. Keyboard

Peripheral type: keyboard.

getType(): string

• Description: Returns the peripheral type identifier, fixed to "keyboard".

Note: This class does not expose any other Lua functions. Its main function is event pushing (when keys are pressed, events are sent to the connected computer).

Event types include key, key_up, paste, char, identical to the keyboard events of the CC:T terminal. Refer to the official documentation on Events for details.