OpenComputers · Explained · Intermediate
OpenComputers Component API and Event Logic Explained
In this guide, you will learn how to bridge the gap between your Lua scripts and physical hardware in OpenComputers by mastering the Component API and the event system. Understanding how component addresses, proxy tables, and event pulling work is essential for automating complex multi-device networks and interacting with other mods via the Adapter.
What you need
- A working OpenComputers setup (Computer Case, CPU, Memory, Graphics Card, Hard Disk Drive, Screen, and Keyboard)
- OpenOS installed on your Hard Disk Drive (booted from the OpenOS Floppy Disk)
- An Analyzer item (for inspecting component addresses manually)
- At least two external components or cards for testing (such as a Redstone Card, Redstone I/O block, Motion Sensor, or an Adapter placed next to a furnace or energy cell)
- Cables to connect external blocks to the Computer Case
Step by step
1List Connected Hardware in OpenOS
Boot up your computer into the OpenOS command shell and connect your external blocks (like a Motion Sensor or Adapter) using Cables. Type the command 'components' into the terminal and press Enter. This displays a list of every internal card and external block currently recognized by the computer, showing both their human-readable type name (such as 'redstone' or 'motion_sensor') and their unique UUID address.
Tip: If the list is too long to fit on your screen, type 'components | less' to scroll through the output using your arrow keys, and press 'q' to exit.
2Explore Methods Using the Interactive Lua Prompt
Instead of guessing how to control a block, use the built-in interactive interpreter to read its documentation directly. Type 'lua' in the shell and press Enter to enter the interactive prompt. To see all functions available on your primary redstone component, type '=component.redstone' and press Enter; the system will output a table of functions. To read the exact usage and parameters for a specific function, append it to the query like '=component.redstone.setOutput'.
Tip: Hold Left Control and press C (or type 'os.exit()') to leave the interactive Lua prompt and return to the standard OpenOS shell.
3Access the Primary Component in a Script
Exit the Lua prompt and create a new script by typing 'edit test.lua'. At the very top of your file, you must import the component library by writing 'local component = require("component")'. If you only have one device of a specific type connected (for example, a single Redstone Card), you can grab it directly as the primary component using 'local rs = component.redstone', and then call its methods directly, such as 'rs.setOutput(1, 15)'.
Tip: In OpenComputers, side numbers usually correspond to standard directional indices, or you can import the 'sides' API using 'local sides = require("sides")' to write readable code like 'sides.north' or 'sides.bottom'.
4Copy Specific UUID Addresses with the Analyzer
When you connect two or more components of the exact same type (like three separate Redstone I/O blocks or multiple Adapters reading different energy cells), 'component.redstone' will only ever control one of them. To control a specific block, craft and hold the Analyzer item in your hand. Sneak and right-click the specific block in the world; this prints its details in your chat and automatically copies its full UUID address to your clipboard.
Tip: You only need the first few characters of an address to identify it uniquely if you use the 'component.get("prefix")' helper function.
5Bind Specific Hardware with Component Proxies
Open your script again with 'edit test.lua' to bind that specific block. Type 'local myBlock = component.proxy("' and press your middle mouse button (or the Insert key) to paste the copied UUID address into your code, then close the quotes and parentheses. The variable 'myBlock' now acts as a dedicated remote control for that exact block in the world, completely independent of any other identical blocks on the same Cable network.
Tip: If you swap out a broken machine or move your setup, you only need to update the UUID string at the top of your script rather than rewriting your logic.
6Listen for Hardware Signals with Event.pull
Instead of running an infinite loop that constantly checks a sensor (which wastes CPU cycles and in-game energy), make your computer wait for the hardware to speak first. Import the event library with 'local event = require("event")'. Add the line 'local eventName, address, x, y, z, entityName = event.pull("motion")' to your script. When you save and run this program, the computer will pause quietly until a connected Motion Sensor detects movement, at which point it wakes up and populates those variables with the exact trigger data.
Tip: Call 'event.pull()' with no arguments inside the interactive 'lua' prompt and trigger a block (like clicking a Screen or walking past a Motion Sensor) to see the exact event name and parameters it broadcasts.
7Combine Events and Proxies in an Automation Loop
To build a complete automated controller, wrap your 'event.pull()' call inside a 'while true do' loop in your script. Use a timeout as the first argument, such as 'local name, addr = event.pull(5, "redstone_changed")', which waits up to 5 seconds for a redstone change before running periodic maintenance code. By checking which 'addr' triggered the event, your script can dynamically decide which component proxy to activate in response.
Tip: Always include a way to yield or pull events inside any 'while true' loop; a loop that runs without pausing will trigger the mod's 'too long without yielding' crash protection.
How it works
In OpenComputers, every physical part—whether it is an internal Graphics Card, an external Hologram Projector, or an Adapter reading a chest—is treated as a network node with a unique 36-character UUID address. At the lowest level of the machine architecture, the computer communicates with these parts by invoking raw calls via their address string. Because writing raw invocation calls for every action is tedious, OpenOS provides the 'component' library, which wraps those raw address calls into convenient Lua tables called proxies.
When you call 'component.proxy(address)', OpenOS queries the hardware at that address for a list of all methods it supports and builds a virtual table of functions for you. Meanwhile, the 'component.type_name' shortcut simply asks OpenOS to grab the proxy for whichever component of that type was connected first (the 'primary' component). This explains why single-device setups work out of the box with simple names, while multi-device networks require you to explicitly bind proxies using UUIDs.
The Event API represents the flip side of hardware communication: signals travelling from the world into your CPU. Because OpenComputers persists script execution across world saves and shares execution time with the Minecraft server tick, programs cannot hog the CPU with endless checking loops. Calling 'event.pull()' puts your Lua thread into a suspended state, consuming almost zero server performance or mod power until a component pushes a hardware signal into the computer's event queue.
Common mistakes
- Writing 'component.redstone' at the global top level without calling 'local component = require("component")' first. While the interactive 'lua' prompt pre-loads standard libraries for convenience, standalone '.lua' scripts executed from the shell must explicitly require every API they use.
- Connecting multiple identical machines via Adapters and assuming 'component.adapter' or the machine's type name will control all of them at once. You must use 'component.list("type_name")' to iterate over all matching addresses, or bind each individual address with 'component.proxy()'.
- Using 'while true do' loops to repeatedly check 'rs.getInput()' without calling 'os.sleep()' or 'event.pull()'. OpenComputers strictly enforces execution quotas per tick; failing to yield via sleep or event pulling will cause the computer to forcefully terminate your script with a 'too long without yielding' error.
- Hardcoding an address and then breaking and replacing the component block in the world. Every crafted or placed OpenComputers component generates a brand-new UUID when initialized or replaced in certain contexts, so always verify your addresses with the Analyzer if you remodel your cable network.
FAQ
How do I iterate through ten identical machines without pasting ten UUIDs by hand?
You can loop over 'for address, componentType in component.list("machine_type") do' in your script. Inside the loop, call 'component.proxy(address)' to interact with each connected machine one by one automatically.
Why does my Adapter not show any components when I place it next to a block from another mod?
Not every block in every mod exposes data, or the block may require you to place the Adapter against a specific side (like a controller port or energy input face). Check the OpenComputers in-game manual or run 'components' in the shell while testing different faces of the target block.
How do I stop a script that is stuck waiting on event.pull()?
Hold down Left Control and Left Alt, then press C. This sends a 'interrupted' signal that forces OpenOS to terminate the currently running foreground program and return you to the shell prompt.
Can I use component.proxy inside a Microcontroller or Drone?
No. Microcontrollers and Drones do not run OpenOS; they run straight from a flashed EEPROM with minimal memory. On those devices, you must use the low-level global 'component.invoke(address, "methodName", ...)' or build a tiny proxy wrapper inside your EEPROM script.
By combining component.proxy() for targeted hardware commands with event.pull() for efficient signal listening, you can automate complex, multi-device networks in OpenComputers with clean and server-friendly Lua code.