LuaMade API Overview

LuaMade lets you run sandboxed Lua scripts on Computer Blocks.

Use it to automate ship behavior, build status dashboards, and coordinate multiple computers through network messaging.

Setup

{
  "height": 260,
  "blocks": [
    { "block": "videogoose.luamade~Computer", "at": [1, 0, 1], "orient": 19 }
  ],
  "steps": [
    { "text": "Place a Computer Block. Your scripts run on it." },
    {
      "text": "Blocks touching the computer become peripherals. A Display Module shows text from scripts.",
      "blocks": [{ "block": "DISPLAY_MODULE", "at": [2, 0, 1] }]
    },
    {
      "text": "A Disk Drive holds a disk for moving files between computers.",
      "blocks": [{ "block": "videogoose.luamade~Disk Drive", "at": [1, 1, 1] }]
    },
    {
      "text": "A Network Module lets the computer message other computers and make web requests.",
      "blocks": [{ "block": "videogoose.luamade~Network Module", "at": [0, 0, 1], "orient": 3 }]
    }
  ]
}

Quick start

Place and activate a Computer Block.
Open terminal and create a script using either editor:

edit /home/hello.lua

Or use the in-game editor:

nano /home/hello.lua

-- /home/hello.lua
print("Hello from LuaMade")

block = console.getBlock()
info = block.getInfo()
print("Running on:", info.getName(), "id=", info.getId())

Save and run:

run /home/hello.lua

Core globals

console: output and context access (getBlock, print, getTime).
fs: virtual filesystem read/write/list APIs, including password-protected path scopes (protect, auth, unprotect).
term: terminal/session controls and command hooks.
net: direct, channel, local, and modem networking APIs.
peripheral: relative and absolute nearby block access helpers.
args: script argument array for run and direct script execution.
shell: compatibility shell helpers (shell.run(pathOrCommand, ...)).
util: utility helpers from bundled Lua library plus native now/sleep.
json: bundled JSON encode/decode helpers (encode, decode, null).
coroutine: standard Lua coroutine API (create, resume, yield, status, running, wrap).
package: sandboxed package table (loaded, preload, path, cpath).

Terminal web requests are available through httpget / term.httpGet(url) and httpput / term.httpPut(url, body[, contentType]) when enabled in server config. Web requests need a Network Module placed adjacent to the computer.

Trusted package distribution is available through the pkg terminal command when package_manager_enabled is enabled. This is controlled separately from generic web fetch settings.

When web_fetch_trusted_domains_only or web_put_trusted_domains_only is enabled, trusted domains are loaded from:

config/luamade/trusted_domains.txt

The file is created automatically with default entries on first startup.

Package manager registry base URL is loaded from:

config/luamade/package_manager_base_url.txt

Quick JSON example:

raw = json.encode({ status = "ok", count = 3, enabled = true })
obj = json.decode(raw)
print(obj.status, obj.count)

Sandbox module loading

Sandboxed loaders are available and constrained:

dofile(path, ...) executes a resolved script path inside the sandbox.
loadfile(path) loads a resolved script file as a function.
load(source) loads an in-memory Lua chunk.
require("module.name") loads modules using strict sandbox rules.

Path policy:

dofile and loadfile can load any .lua file path inside the computer sandbox (for example /home, /bin, /etc, /lib).
require is for reusable libraries and searches library roots only.

require rules:

Module names must be lowercase dot notation with [a-z0-9_] segments (for example myteam.math).
Resolution order is package.loaded, then package.preload, then filesystem search.
Filesystem search checks player library roots first: /lib/<module>.lua, /etc/lib/<module>.lua.
For allowlisted names, require can also load bundled libs from /scripts/lib/<module>.lua.
Loaded modules are cached in package.loaded; modules returning nil are cached as true.
Cyclic loads are blocked with a recursion guard (require("a") -> require("a")).

Allowlisted module names are loaded from:

config/luamade/allowed_lua_packages.txt

The file is created automatically with safe defaults (json, util, vector).

Bundled module compatibility:

json and util are exposed as globals and are also available through require("json") / require("util").
vector is exposed as a global and is also available through require("vector").

Shared library examples:

-- /lib/myteam/math.lua
local M = {}

function M.add(a, b)
    return a + b
end

return M

-- anywhere else
local mathlib = require("myteam.math")
print(mathlib.add(2, 3))

Typical workflow

Command batching:

The terminal accepts multiple commands in one submission.
Separate commands with newlines, ;, &&, or || (outside quotes).
; and newlines always continue to the next command.
&& only runs the next command if the previous command succeeded.
|| only runs the next command if the previous command failed.
Empty/whitespace-only segments are ignored.

Read current state from console.getBlock() and wrappers.
Perform logic in Lua.
Persist local state to files under /home or /etc.
Use net to coordinate with other computers.

Peripheral side lookups are orientation-aware: front/back/left/right follow the computer block’s facing.

Startup behavior

If /etc/startup.lua exists, it runs at terminal boot.

Use startup for:

custom boot banner
prompt template setup
registering custom terminal commands
opening network channels/modem listeners

Safety and limits

Scripts run in a sandboxed Lua environment.
Host filesystem and unsafe loaders are not exposed.
Execution is controlled by server-configured parallel limits and manual interruption/cancellation.
Coroutines are cooperative (single script thread) and do not create parallel workers.
Web fetch is server-gated and can be restricted to trusted domains only.
Protected filesystem paths require successful auth before gated operations are allowed.