Peripheral API

peripheral provides convenient access to nearby blocks using relative sides, plus absolute lookups by position.

Typical usage

local topBlock = peripheral.getRelative("top")
if topBlock ~= nil then
  print("Top block id:", topBlock.getId())
end

local frontBlock = peripheral.getRelative("front")
if frontBlock ~= nil and frontBlock.isDisplayModule() then
  frontBlock.setDisplayText("Connected")
end

local wrappedDisplay = peripheral.wrap(frontBlock, "display")
if wrappedDisplay ~= nil then
  wrappedDisplay.setText("Wrapped display")
end

Side names

Accepted side names:

  • front

  • back

  • left

  • right

  • top (alias: up)

  • bottom (alias: down)

Reference

  • getCurrentBlock() Returns the current computer Block.

  • wrap(block<Block>, asType<String>) Returns a typed wrapper for block based on asType, or nil when incompatible.

  • wrapCurrent(asType<String>) Typed wrapper for the current computer block.

  • getAt(position<LuaVec3i>) Returns a Block at an absolute position, or nil.

  • getRelative(side<String>) Returns adjacent Block on that side, or nil.

  • wrapRelative(side<String>, asType<String>) Equivalent to wrap(getRelative(side), asType).

  • wrapAt(position<LuaVec3i>, asType<String>) Equivalent to wrap(getAt(position), asType).

  • hasRelative(side<String>) Returns true when a block exists on that side.

  • getSides() Returns supported side names.

Notes

  • Relative sides are resolved from the current computer block position.

  • front/back/left/right/top/bottom are resolved relative to the computer block’s facing/orientation.

  • If no block exists at a location/side, methods return nil (or false for hasRelative).

  • wrap(..., asType) supports: display, inventory, diskdrive, accesspoint, networkmodule, datastore, networkeddatastore, block/base, and auto. Other mods may register additional type names.

  • display exposes display helpers like setText()/getText().

  • inventory exposes helpers like getItems() and getInventoryName().

  • diskdrive exposes disk methods like saveProgram(), installProgram(), and listPrograms().

  • networkmodule exposes networking and FTP access — see Network Module wrapper below.

  • accesspoint exposes remote access methods described below.

Network Module wrapper

When a Network Module block is wrapped, it provides access to the networking and FTP APIs:

  • getNet() Returns a NetworkInterface handle for this module. See networking for the full API reference.

  • getFtp() Returns an FtpApi handle bound to this module’s hostname and the calling computer’s filesystem. See FTP for the full API reference.

local nm  = peripheral.wrapRelative("front", "networkmodule")
local net = nm.getNet()
local ftp = nm.getFtp()

net.setHostname("myserver")
net.send("target", "proto", "hello")

ftp.listen("secret")

Each Network Module block has its own identity (hostname) on the network. The hostname is persisted across server restarts.

Remote access point wrapper

When a remote access point block is wrapped from a computer script, it can be bound to that computer:

  • connect() Binds the access point to the current computer. Returns true on success.

  • disconnect() Removes the computer binding from the access point.

  • isConnected() Returns true when the access point is currently bound to a computer.

  • getLinkedComputerUUID() Returns the UUID of the linked computer, or nil when unbound.

  • getLinkedComputerName() Returns the linked computer display name, or nil when unavailable.

  • isSessionActive() Returns true when this access point currently has an active remote control session.

local access = peripheral.wrapRelative("front", "accesspoint")
if access ~= nil then
  access:connect()
end

local topBlock = peripheral.getRelative("top")

local display = peripheral.wrap(topBlock, "display")
if display ~= nil then
  display.setText("Status: OK")
end

local inv = peripheral.wrap(topBlock, "inventory")
if inv ~= nil then
  print("Inventory volume:", inv.getInventoryVolume())
end