# Table of Contents - [CC: Tweaked](#cc-tweaked) - [_G](#-g) - [colors](#colors) - [colours](#colours) - [commands](#commands) - [disk](#disk) - [gps](#gps) - [fs](#fs) - [help](#help) - [http](#http) - [io](#io) - [keys](#keys) - [multishell](#multishell) - [os](#os) - [paintutils](#paintutils) - [parallel](#parallel) - [peripheral](#peripheral) - [pocket](#pocket) - [rednet](#rednet) - [redstone](#redstone) - [settings](#settings) - [shell](#shell) - [textutils](#textutils) - [vector](#vector) - [turtle](#turtle) - [term](#term) - [window](#window) - [cc.audio.dfpwm](#cc-audio-dfpwm) - [cc.base64](#cc-base64) - [cc.completion](#cc-completion) - [cc.expect](#cc-expect) - [cc.image.nft](#cc-image-nft) - [cc.pretty](#cc-pretty) - [cc.require](#cc-require) - [cc.shell.completion](#cc-shell-completion) - [command](#command) - [computer](#computer) - [cc.strings](#cc-strings) - [drive](#drive) - [modem](#modem) - [energy_storage](#energy-storage) - [disk](#disk) - [alarm](#alarm) - [char](#char) - [computer_command](#computer-command) - [http_check](#http-check) - [file_transfer](#file-transfer) - [disk_eject](#disk-eject) - [http_failure](#http-failure) - [key_up](#key-up) - [http_success](#http-success) - [key](#key) - [monitor_resize](#monitor-resize) - [modem_message](#modem-message) - [monitor_touch](#monitor-touch) - [fluid_storage](#fluid-storage) - [printer](#printer) - [redstone_relay](#redstone-relay) - [monitor](#monitor) - [speaker](#speaker) - [inventory](#inventory) - [mouse_click](#mouse-click) - [mouse_drag](#mouse-drag) - [mouse_scroll](#mouse-scroll) - [mouse_up](#mouse-up) - [paste](#paste) - [peripheral](#peripheral) - [speaker_audio_empty](#speaker-audio-empty) - [setting_changed](#setting-changed) - [peripheral_detach](#peripheral-detach) - [redstone](#redstone) - [rednet_message](#rednet-message) - [task_complete](#task-complete) - [term_resize](#term-resize) - [terminate](#terminate) - [turtle_inventory](#turtle-inventory) - [timer](#timer) - [websocket_closed](#websocket-closed) - [websocket_failure](#websocket-failure) - [websocket_success](#websocket-success) - [websocket_message](#websocket-message) - [Setting up GPS](#setting-up-gps) - [Playing audio with speakers](#playing-audio-with-speakers) - [Reusing code with require](#reusing-code-with-require) - [Block details](#block-details) - [Incompatibilities between versions](#incompatibilities-between-versions) - [The /computercraft command](#the-computercraft-command) - [Entity details](#entity-details) - [CraftOS's exception protocol](#craftos-s-exception-protocol) - [Lua 5.2/5.3 features in CC: Tweaked](#lua-5-2-5-3-features-in-cc-tweaked) - [Item details](#item-details) - [Computer startup](#computer-startup) - [Running programs on computer startup](#running-programs-on-computer-startup) - [Allowing access to local IPs](#allowing-access-to-local-ips) - [Not Found | CC: Tweaked](#not-found-cc-tweaked) --- # CC: Tweaked ![CC: Tweaked](https://tweaked.cc/logo-42c40e20.png) ====================================================== CC: Tweaked is a mod for Minecraft which adds programmable computers, turtles and more to the game. A fork of the much-beloved [ComputerCraft](https://github.com/dan200/ComputerCraft "ComputerCraft on GitHub") , it continues its legacy with improved performance and stability, along with a wealth of new features. CC: Tweaked can be installed from [Modrinth](https://modrinth.com/mod/gu7yAYhd "Download CC: Tweaked from Modrinth") . It runs on both [Minecraft Forge](https://files.minecraftforge.net/ "Download Minecraft Forge.") and [Fabric](https://fabricmc.net/use/installer/ "Download Fabric.") . Features -------- Controlled using the [Lua programming language](https://www.lua.org/ "Lua's main website") , CC: Tweaked's computers provides all the tools you need to start writing code and automating your Minecraft world. ![A ComputerCraft terminal open and ready to be programmed.](https://tweaked.cc/basic-terminal-45a33440.png) While computers are incredibly powerful, they're rather limited by their inability to move about. _Turtles_ are the solution here. They can move about the world, placing and breaking blocks, swinging a sword to protect you from zombies, or whatever else you program them to! ![A turtle tunneling in Minecraft.](https://tweaked.cc/turtle-1b1e3370.png) Not all problems can be solved with a pickaxe though, and so CC: Tweaked also provides a bunch of additional peripherals for your computers. You can play a tune with speakers, display text or images on a monitor, connect all your computers together with modems, and much more. Computers can now also interact with inventories such as chests, allowing you to build complex inventory and item management systems. ![A chest's contents being read by a computer and displayed on a monitor.](https://tweaked.cc/peripherals-d5df11cc.png) Getting Started --------------- While ComputerCraft is lovely for both experienced programmers and for people who have never coded before, it can be a little daunting getting started. Thankfully, there's several fantastic tutorials out there: * [Direwolf20's ComputerCraft tutorials](https://www.youtube.com/watch?v=wrUHUhfCY5A "ComputerCraft Tutorial Episode 1 - HELP! and Hello World") * [Sethbling's ComputerCraft series](https://www.youtube.com/watch?v=DSsx4VSe-Uk "Programming Tutorial with Minecraft Turtles -- Ep. 1: Intro to Turtles and If-Then-Else_End") * [Lyqyd's Computer Basics 1](https://ccf.squiddev.cc/forums2/index.php?/topic/15033-computer-basics-i/ "Computer Basics I") Once you're a little more familiar with the mod, the sidebar and links below provide more detailed documentation on the various APIs and peripherals provided by the mod. Community --------- If you need help getting started with CC: Tweaked, want to show off your latest project, or just want to chat about ComputerCraft, do check out our [GitHub discussions page](https://github.com/cc-tweaked/CC-Tweaked/discussions) ! There's also a fairly populated, albeit quiet IRC channel on [EsperNet](https://www.esper.net/) , if that's more your cup of tea. You can join `#computercraft` through your desktop client, or online using [KiwiIRC](https://kiwiirc.com/nextclient/#irc://irc.esper.net:+6697/#computercraft "#computercraft on EsperNet") . Get Involved ------------ CC: Tweaked lives on [GitHub](https://github.com/cc-tweaked/CC-Tweaked/ "CC: Tweaked on GitHub") . If you've got any ideas, feedback or bugs please do [create an issue](https://github.com/cc-tweaked/CC-Tweaked/issues/new/choose) . Globals ------- | | | | --- | --- | | [\_G](https://tweaked.cc/module/_G.html) | Functions in the global environment, defined in `bios.lua`. | | [colors](https://tweaked.cc/module/colors.html) | Constants and functions for colour values, suitable for working with [`term`](https://tweaked.cc/module/term.html)
and [`redstone`](https://tweaked.cc/module/redstone.html)
. | | [colours](https://tweaked.cc/module/colours.html) | An alternative version of [`colors`](https://tweaked.cc/module/colors.html)
for lovers of British spelling. | | [commands](https://tweaked.cc/module/commands.html) | Execute Minecraft commands and gather data from the results from a command computer. | | [disk](https://tweaked.cc/module/disk.html) | Interact with disk drives. | | [fs](https://tweaked.cc/module/fs.html) | Interact with the computer's files and filesystem, allowing you to manipulate files, directories and paths. | | [gps](https://tweaked.cc/module/gps.html) | Use [modems](https://tweaked.cc/peripheral/modem.html)
to locate the position of the current turtle or computers. | | [help](https://tweaked.cc/module/help.html) | Find help files on the current computer. | | [http](https://tweaked.cc/module/http.html) | Make HTTP requests, sending and receiving data to a remote web server. | | [io](https://tweaked.cc/module/io.html) | Emulates Lua's standard io library. | | [keys](https://tweaked.cc/module/keys.html) | Constants for all keyboard "key codes", as queued by the [`key`](https://tweaked.cc/event/key.html)
event. | | [multishell](https://tweaked.cc/module/multishell.html) | Multishell allows multiple programs to be run at the same time. | | [os](https://tweaked.cc/module/os.html) | The [`os`](https://tweaked.cc/module/os.html)
API allows interacting with the current computer. | | [paintutils](https://tweaked.cc/module/paintutils.html) | Utilities for drawing more complex graphics, such as pixels, lines and images. | | [parallel](https://tweaked.cc/module/parallel.html) | A simple way to run several functions at once. | | [peripheral](https://tweaked.cc/module/peripheral.html) | Find and control peripherals attached to this computer. | | [pocket](https://tweaked.cc/module/pocket.html) | Control the current pocket computer, adding or removing upgrades. | | [rednet](https://tweaked.cc/module/rednet.html) | Communicate with other computers by using [modems](https://tweaked.cc/peripheral/modem.html)
. | | [redstone](https://tweaked.cc/module/redstone.html) | Get and set redstone signals adjacent to this computer. | | [settings](https://tweaked.cc/module/settings.html) | Read and write configuration options for CraftOS and your programs. | | [shell](https://tweaked.cc/module/shell.html) | The shell API provides access to CraftOS's command line interface. | | [term](https://tweaked.cc/module/term.html) | Interact with a computer's terminal or monitors, writing text and drawing ASCII graphics. | | [textutils](https://tweaked.cc/module/textutils.html) | Helpful utilities for formatting and manipulating strings. | | [turtle](https://tweaked.cc/module/turtle.html) | Turtles are a robotic device, which can break and place blocks, attack mobs, and move about the world. | | [vector](https://tweaked.cc/module/vector.html) | A basic 3D vector type and some common vector operations. | | [window](https://tweaked.cc/module/window.html) | A [terminal redirect](https://tweaked.cc/module/term.html#ty:Redirect)
occupying a smaller area of an existing terminal. | Modules ------- | | | | --- | --- | | [cc.audio.dfpwm](https://tweaked.cc/library/cc.audio.dfpwm.html) | Convert between streams of DFPWM audio data and a list of amplitudes. | | [cc.base64](https://tweaked.cc/library/cc.base64.html) | The [`cc.base64`](https://tweaked.cc/library/cc.base64.html)
module provides functions for converting binary data to and from [Base64](https://en.wikipedia.org/wiki/Base64)
. | | [cc.completion](https://tweaked.cc/library/cc.completion.html) | A collection of helper methods for working with input completion, such as that require by [`_G.read`](https://tweaked.cc/module/_G.html#v:read)
. | | [cc.expect](https://tweaked.cc/library/cc.expect.html) | The [`cc.expect`](https://tweaked.cc/library/cc.expect.html)
library provides helper functions for verifying that function arguments are well-formed and of the correct type. | | [cc.image.nft](https://tweaked.cc/library/cc.image.nft.html) | Read and draw nft ("Nitrogen Fingers Text") images. | | [cc.pretty](https://tweaked.cc/library/cc.pretty.html) | A pretty printer for rendering data structures in an aesthetically pleasing manner. | | [cc.require](https://tweaked.cc/library/cc.require.html) | A pure Lua implementation of the builtin [`require`](https://www.lua.org/manual/5.1/manual.html#pdf-require)
function and [`package`](https://www.lua.org/manual/5.1/manual.html#5.3)
library. | | [cc.shell.completion](https://tweaked.cc/library/cc.shell.completion.html) | A collection of helper methods for working with shell completion. | | [cc.strings](https://tweaked.cc/library/cc.strings.html) | Various utilities for working with strings and text. | Peripherals ----------- | | | | --- | --- | | [command](https://tweaked.cc/peripheral/command.html) | This peripheral allows you to interact with command blocks. | | [computer](https://tweaked.cc/peripheral/computer.html) | A computer or turtle wrapped as a peripheral. | | [drive](https://tweaked.cc/peripheral/drive.html) | Disk drives are a peripheral which allow you to read and write to floppy disks and other "mountable media" (such as computers or turtles). | | [modem](https://tweaked.cc/peripheral/modem.html) | Modems allow you to send messages between computers over long distances. | | [monitor](https://tweaked.cc/peripheral/monitor.html) | Monitors are a block which act as a terminal, displaying information on one side. | | [printer](https://tweaked.cc/peripheral/printer.html) | The printer peripheral allows printing text onto pages. | | [redstone\_relay](https://tweaked.cc/peripheral/redstone_relay.html) | The redstone relay is a peripheral that allows reading and outputting redstone signals. | | [speaker](https://tweaked.cc/peripheral/speaker.html) | The speaker peripheral allows your computer to play notes and other sounds. | Generic Peripherals ------------------- | | | | --- | --- | | [energy\_storage](https://tweaked.cc/generic_peripheral/energy_storage.html) | Methods for interacting with blocks which store energy. | | [fluid\_storage](https://tweaked.cc/generic_peripheral/fluid_storage.html) | Methods for interacting with tanks and other fluid storage blocks. | | [inventory](https://tweaked.cc/generic_peripheral/inventory.html) | Methods for interacting with inventories. | Events ------ | | | | --- | --- | | [alarm](https://tweaked.cc/event/alarm.html) | The [`alarm`](https://tweaked.cc/event/alarm.html)
event is fired when an alarm started with [`os.setAlarm`](https://tweaked.cc/module/os.html#v:setAlarm)
completes. | | [char](https://tweaked.cc/event/char.html) | The [`char`](https://tweaked.cc/event/char.html)
event is fired when a character is typed on the keyboard. | | [computer\_command](https://tweaked.cc/event/computer_command.html) | The [`computer_command`](https://tweaked.cc/event/computer_command.html)
event is fired when the [`/computercraft queue` command](https://tweaked.cc/reference/computercraft_command.html#queue)
is run for the current command computer. | | [disk](https://tweaked.cc/event/disk.html) | The [`disk`](https://tweaked.cc/module/disk.html)
event is fired when a disk is inserted into an adjacent or networked disk drive. | | [disk\_eject](https://tweaked.cc/event/disk_eject.html) | The [`disk_eject`](https://tweaked.cc/event/disk_eject.html)
event is fired when a disk is removed from an adjacent or networked disk drive. | | [file\_transfer](https://tweaked.cc/event/file_transfer.html) | The [`file_transfer`](https://tweaked.cc/event/file_transfer.html)
event is queued when a user drags-and-drops a file on an open computer. | | [http\_check](https://tweaked.cc/event/http_check.html) | The [`http_check`](https://tweaked.cc/event/http_check.html)
event is fired when a URL check finishes. | | [http\_failure](https://tweaked.cc/event/http_failure.html) | The [`http_failure`](https://tweaked.cc/event/http_failure.html)
event is fired when an HTTP request fails. | | [http\_success](https://tweaked.cc/event/http_success.html) | The [`http_success`](https://tweaked.cc/event/http_success.html)
event is fired when an HTTP request returns successfully. | | [key](https://tweaked.cc/event/key.html) | This event is fired when any key is pressed while the terminal is focused. | | [key\_up](https://tweaked.cc/event/key_up.html) | Fired whenever a key is released (or the terminal is closed while a key was being pressed). | | [modem\_message](https://tweaked.cc/event/modem_message.html) | The [`modem_message`](https://tweaked.cc/event/modem_message.html)
event is fired when a message is received on an open channel on any [`modem`](https://tweaked.cc/peripheral/modem.html)
. | | [monitor\_resize](https://tweaked.cc/event/monitor_resize.html) | The [`monitor_resize`](https://tweaked.cc/event/monitor_resize.html)
event is fired when an adjacent or networked [monitor's](https://tweaked.cc/peripheral/monitor.html)
size is changed. | | [monitor\_touch](https://tweaked.cc/event/monitor_touch.html) | The [`monitor_touch`](https://tweaked.cc/event/monitor_touch.html)
event is fired when an adjacent or networked [Advanced Monitor](https://tweaked.cc/peripheral/monitor.html)
is right-clicked. | | [mouse\_click](https://tweaked.cc/event/mouse_click.html) | This event is fired when the terminal is clicked with a mouse. | | [mouse\_drag](https://tweaked.cc/event/mouse_drag.html) | This event is fired every time the mouse is moved while a mouse button is being held. | | [mouse\_scroll](https://tweaked.cc/event/mouse_scroll.html) | This event is fired when a mouse wheel is scrolled in the terminal. | | [mouse\_up](https://tweaked.cc/event/mouse_up.html) | This event is fired when a mouse button is released or a held mouse leaves the computer's terminal. | | [paste](https://tweaked.cc/event/paste.html) | The [`paste`](https://tweaked.cc/event/paste.html)
event is fired when text is pasted into the computer through Ctrl-V (or ⌘V on Mac). | | [peripheral](https://tweaked.cc/event/peripheral.html) | The [`peripheral`](https://tweaked.cc/module/peripheral.html)
event is fired when a peripheral is attached on a side or to a modem. | | [peripheral\_detach](https://tweaked.cc/event/peripheral_detach.html) | The [`peripheral_detach`](https://tweaked.cc/event/peripheral_detach.html)
event is fired when a peripheral is detached from a side or from a modem. | | [rednet\_message](https://tweaked.cc/event/rednet_message.html) | The [`rednet_message`](https://tweaked.cc/event/rednet_message.html)
event is fired when a message is sent over Rednet. | | [redstone](https://tweaked.cc/event/redstone.html) | The [`redstone`](https://tweaked.cc/event/redstone.html)
event is fired whenever any redstone inputs on the computer or [relay](https://tweaked.cc/peripheral/redstone_relay.html)
change. | | [setting\_changed](https://tweaked.cc/event/setting_changed.html) | The [`setting_changed`](https://tweaked.cc/event/setting_changed.html)
event is fired when a setting is modified with the [`settings`](https://tweaked.cc/module/settings.html)
API. | | [speaker\_audio\_empty](https://tweaked.cc/event/speaker_audio_empty.html) | Return Values | | [task\_complete](https://tweaked.cc/event/task_complete.html) | The [`task_complete`](https://tweaked.cc/event/task_complete.html)
event is fired when an asynchronous task completes. | | [term\_resize](https://tweaked.cc/event/term_resize.html) | The [`term_resize`](https://tweaked.cc/event/term_resize.html)
event is fired when the main terminal is resized. | | [terminate](https://tweaked.cc/event/terminate.html) | The [`terminate`](https://tweaked.cc/event/terminate.html)
event is fired when Ctrl-T is held down. | | [timer](https://tweaked.cc/event/timer.html) | The [`timer`](https://tweaked.cc/event/timer.html)
event is fired when a timer started with [`os.startTimer`](https://tweaked.cc/module/os.html#v:startTimer)
completes. | | [turtle\_inventory](https://tweaked.cc/event/turtle_inventory.html) | The [`turtle_inventory`](https://tweaked.cc/event/turtle_inventory.html)
event is fired when a turtle's inventory is changed. | | [websocket\_closed](https://tweaked.cc/event/websocket_closed.html) | The [`websocket_closed`](https://tweaked.cc/event/websocket_closed.html)
event is fired when an open WebSocket connection is closed. | | [websocket\_failure](https://tweaked.cc/event/websocket_failure.html) | The [`websocket_failure`](https://tweaked.cc/event/websocket_failure.html)
event is fired when a WebSocket connection request fails. | | [websocket\_message](https://tweaked.cc/event/websocket_message.html) | The [`websocket_message`](https://tweaked.cc/event/websocket_message.html)
event is fired when a message is received on an open WebSocket connection. | | [websocket\_success](https://tweaked.cc/event/websocket_success.html) | The [`websocket_success`](https://tweaked.cc/event/websocket_success.html)
event is fired when a WebSocket connection request returns successfully. | Guides ------ | | | | --- | --- | | [Setting up GPS](https://tweaked.cc/guide/gps_setup.html) | The [`gps`](https://tweaked.cc/module/gps.html)
API allows a computer to find its current position using a [wireless modem](https://tweaked.cc/peripheral/modem.html)
. | | [Allowing access to local IPs](https://tweaked.cc/guide/local_ips.html) | By default, ComputerCraft blocks access to local IP addresses for security. | | [Playing audio with speakers](https://tweaked.cc/guide/speaker_audio.html) | CC: Tweaked's speaker peripheral provides a powerful way to play any audio you like with the [`speaker.playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio)
method. | | [Running programs on computer startup](https://tweaked.cc/guide/startup.html) | It's often useful to automatically start running a program when a computer is turned on, such as when running a [GPS host...](https://tweaked.cc/guide/gps_setup.html) | | [Reusing code with require](https://tweaked.cc/guide/using_require.html) | A library is a collection of useful functions and other definitions which is stored separately to your main program. | Reference --------- | | | | --- | --- | | [Block details](https://tweaked.cc/reference/block_details.html) | Several functions in CC: Tweaked, such as [`turtle.inspect`](https://tweaked.cc/module/turtle.html#v:inspect)
and [`commands.getBlockInfo`](https://tweaked.cc/module/commands.html#v:getBlockInfo)
provide a way to get information about a block in the world. | | [Incompatibilities between versions](https://tweaked.cc/reference/breaking_changes.html) | CC: Tweaked tries to remain as compatible between versions as possible, meaning most programs written for older versions... | | [The /computercraft command](https://tweaked.cc/reference/computercraft_command.html) | CC: Tweaked provides a `/computercraft` command for server owners to manage running computers on a server. | | [Entity details](https://tweaked.cc/reference/entity_details.html) | Some functions in CC: Tweaked (such as [`commands.getEntities`](https://tweaked.cc/module/commands.html#v:getEntities)
) provide a way to get information about an entity. | | [CraftOS's exception protocol](https://tweaked.cc/reference/exceptions.html) | By default, Lua represents errors are plain strings. | | [Lua 5.2/5.3 features in CC: Tweaked](https://tweaked.cc/reference/feature_compat.html) | CC: Tweaked is based off of the Cobalt Lua runtime, which uses Lua 5. | | [Item details](https://tweaked.cc/reference/item_details.html) | Several functions in CC: Tweaked, such as [`turtle.getItemDetail`](https://tweaked.cc/module/turtle.html#v:getItemDetail)
and [`inventory.getItemDetail`](https://tweaked.cc/generic_peripheral/inventory.html#v:getItemDetail)
provide a way to get information about an item stack. | | [Computer startup](https://tweaked.cc/reference/startup.html) | When a computer turns on, it searches for files to run as part of the startup process. | --- # _G \_G === Functions in the global environment, defined in `bios.lua`. This does not include standard Lua functions. | | | | --- | --- | | [sleep(\[time=0\])](https://tweaked.cc/module/_G.html#v:sleep) | Pauses execution for the specified number of seconds. | | [write(text)](https://tweaked.cc/module/_G.html#v:write) | Writes a line of text to the screen without a newline at the end, wrapping text if necessary. | | [print(...)](https://tweaked.cc/module/_G.html#v:print) | Prints the specified values to the screen separated by spaces, wrapping if necessary. | | [printError(...)](https://tweaked.cc/module/_G.html#v:printError) | Prints the specified values to the screen in red, separated by spaces, wrapping if necessary. | | [read(\[replaceChar \[, history \[, completeFn \[, default\]\]\]\])](https://tweaked.cc/module/_G.html#v:read) | Reads user input from the terminal. | | [\_HOST](https://tweaked.cc/module/_G.html#v:_HOST) | Stores the current ComputerCraft and Minecraft versions. | | [\_CC\_DEFAULT\_SETTINGS](https://tweaked.cc/module/_G.html#v:_CC_DEFAULT_SETTINGS) | The default computer settings as defined in the ComputerCraft configuration. | [](https://tweaked.cc/module/_G.html#v:sleep) sleep(\[time=0\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/doc/stub/global.lua#L43) Pauses execution for the specified number of seconds. As it waits for a fixed amount of world ticks, `time` will automatically be rounded up to the nearest multiple of 0.05 seconds. If you are using coroutines or the [parallel API](https://tweaked.cc/module/parallel.html) , it will only pause execution of the current thread, not the whole program. ##### tip Because sleep internally uses timers, it is a function that yields. This means that you can use it to prevent "Too long without yielding" errors. However, as the minimum sleep time is 0.05 seconds, it will slow your program down. ##### ⚠ warning Internally, this function queues and waits for a timer event (using [`os.startTimer`](https://tweaked.cc/module/os.html#v:startTimer) ), however it does not listen for any other events. This means that any event that occurs while sleeping will be entirely discarded. If you need to receive events while sleeping, consider using [timers](https://tweaked.cc/module/os.html#v:startTimer) , or the [parallel API](https://tweaked.cc/module/parallel.html) . ### Parameters 1. time? `number` = The number of seconds to sleep for, rounded up to the nearest multiple of 0.05. ### Usage * Sleep for three seconds. Run ᐅ print("Sleeping for three seconds") sleep(3) print("Done!") ### See also * **[`os.startTimer`](https://tweaked.cc/module/os.html#v:startTimer) ** ### Changes * **Changed in version 1.63:** The `time` parameter is now optional. [](https://tweaked.cc/module/_G.html#v:write) write(text)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/doc/stub/global.lua#L52) Writes a line of text to the screen without a newline at the end, wrapping text if necessary. ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The text to write to the string ### Returns 1. `number` The number of lines written ### Usage * Run ᐅ write("Hello, world") ### See also * **[`print`](https://tweaked.cc/module/_G.html#v:print) ** A wrapper around write that adds a newline and accepts multiple arguments [](https://tweaked.cc/module/_G.html#v:print) print(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/doc/stub/global.lua#L60) Prints the specified values to the screen separated by spaces, wrapping if necessary. After printing, the cursor is moved to the next line. ### Parameters 1. ... The values to print on the screen ### Returns 1. `number` The number of lines written ### Usage * Run ᐅ print("Hello, world!") [](https://tweaked.cc/module/_G.html#v:printError) printError(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/doc/stub/global.lua#L67) Prints the specified values to the screen in red, separated by spaces, wrapping if necessary. After printing, the cursor is moved to the next line. ### Parameters 1. ... The values to print on the screen ### Usage * Run ᐅ printError("Something went wrong!") [](https://tweaked.cc/module/_G.html#v:read) read(\[replaceChar \[, history \[, completeFn \[, default\]\]\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/doc/stub/global.lua#L115) Reads user input from the terminal. This automatically handles arrow keys, pasting, character replacement, history scrollback, auto-completion, and default values. ### Parameters 1. replaceChar? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) A character to replace each typed character with. This can be used for hiding passwords, for example. 2. history? [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) A table holding history items that can be scrolled back to with the up/down arrow keys. The oldest item is at index 1, while the newest item is at the highest index. 3. completeFn? function(partial: [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ):{ [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } | nil A function to be used for completion. This function should take the partial text typed so far, and returns a list of possible completion options. 4. default? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Default text which should already be entered into the prompt. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The text typed in. ### Usage * Read a string and echo it back to the user Run ᐅ write("> ") local msg \= read() print(msg) * Prompt a user for a password. Run ᐅ while true do write("Password> ") local pwd \= read("\*") if pwd \== "let me in" then break end print("Incorrect password, try again.") end print("Logged in!") * A complete example with completion, history and a default value. Run ᐅ local [completion](https://tweaked.cc/library/cc.completion.html "A collection of helper methods for working with input completion, such as that require by _G.read.") \= require "cc.completion" local history \= { "potato", "orange", "apple" } local choices \= { "apple", "orange", "banana", "strawberry" } write("> ") local msg \= read(nil, history, function(text) return [completion.choice](https://tweaked.cc/library/cc.completion.html#v:choice "Complete from a choice of one or more strings.") (text, choices) end, "app") print(msg) ### See also * **[`cc.completion`](https://tweaked.cc/library/cc.completion.html) ** For functions to help with completion. ### Changes * **Changed in version 1.74:** Added `completeFn` parameter. * **Changed in version 1.80pr1:** Added `default` parameter. [](https://tweaked.cc/module/_G.html#v:_HOST) \_HOST[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/doc/stub/global.lua#L131) Stores the current ComputerCraft and Minecraft versions. Outside of Minecraft (for instance, in an emulator) [`_HOST`](https://tweaked.cc/module/_G.html#v:_HOST) will contain the emulator's version instead. If you need to check for the presence of a feature, it is usually better to rely on feature detection, rather than comparing mod or Minecraft versions. For example, `ComputerCraft 1.93.0 (Minecraft 1.15.2)`. ### Usage * Print the current computer's environment. Run ᐅ print(\_HOST) ### See also * **[`os.version`](https://tweaked.cc/module/os.html#v:version) ** ### Changes * **New in version 1.76** [](https://tweaked.cc/module/_G.html#v:_CC_DEFAULT_SETTINGS) \_CC\_DEFAULT\_SETTINGS[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/doc/stub/global.lua#L146) The default computer settings as defined in the ComputerCraft configuration. This is a comma-separated list of settings pairs defined by the mod configuration or server owner. By default, it is empty. An example value to disable autocompletion: shell.autocomplete=false,lua.autocomplete=false,edit.autocomplete=false ### Usage * Run ᐅ \_CC\_DEFAULT\_SETTINGS ### Changes * **New in version 1.77** --- # colors colors ====== Constants and functions for colour values, suitable for working with [`term`](https://tweaked.cc/module/term.html) and [`redstone`](https://tweaked.cc/module/redstone.html) . This is useful in conjunction with [Bundled Cables](https://tweaked.cc/module/redstone.html#v:setBundledOutput) from mods like Project Red, and [colors on Advanced Computers and Advanced Monitors](https://tweaked.cc/module/term.html#v:setTextColour) . For the non-American English version just replace [`colors`](https://tweaked.cc/module/colors.html) with [`colours`](https://tweaked.cc/module/colours.html) . This alternative API is exactly the same, except the colours use British English (e.g. [`colors.gray`](https://tweaked.cc/module/colors.html#v:gray) is spelt [`colours.grey`](https://tweaked.cc/module/colours.html#v:grey) ). On basic terminals (such as the Computer and Monitor), all the colors are converted to grayscale. This means you can still use all 16 colors on the screen, but they will appear as the nearest tint of gray. You can check if a terminal supports color by using the function [`term.isColor`](https://tweaked.cc/module/term.html#v:isColor) . Grayscale colors are calculated by taking the average of the three components, i.e. `(red + green + blue) / 3`. | Default Colors | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | | Color | Value | | | Default Palette Color | | | | | --- | --- | --- | --- | --- | --- | --- | --- | | Dec | Hex | Paint/Blit | Preview | Hex | RGB | Grayscale | | --- | --- | --- | --- | --- | --- | --- | --- | | `colors.white` | 1 | 0x1 | 0 | | #F0F0F0 | 240, 240, 240 | | | `colors.orange` | 2 | 0x2 | 1 | | #F2B233 | 242, 178, 51 | | | `colors.magenta` | 4 | 0x4 | 2 | | #E57FD8 | 229, 127, 216 | | | `colors.lightBlue` | 8 | 0x8 | 3 | | #99B2F2 | 153, 178, 242 | | | `colors.yellow` | 16 | 0x10 | 4 | | #DEDE6C | 222, 222, 108 | | | `colors.lime` | 32 | 0x20 | 5 | | #7FCC19 | 127, 204, 25 | | | `colors.pink` | 64 | 0x40 | 6 | | #F2B2CC | 242, 178, 204 | | | `colors.gray` | 128 | 0x80 | 7 | | #4C4C4C | 76, 76, 76 | | | `colors.lightGray` | 256 | 0x100 | 8 | | #999999 | 153, 153, 153 | | | `colors.cyan` | 512 | 0x200 | 9 | | #4C99B2 | 76, 153, 178 | | | `colors.purple` | 1024 | 0x400 | a | | #B266E5 | 178, 102, 229 | | | `colors.blue` | 2048 | 0x800 | b | | #3366CC | 51, 102, 204 | | | `colors.brown` | 4096 | 0x1000 | c | | #7F664C | 127, 102, 76 | | | `colors.green` | 8192 | 0x2000 | d | | #57A64E | 87, 166, 78 | | | `colors.red` | 16384 | 0x4000 | e | | #CC4C4C | 204, 76, 76 | | | `colors.black` | 32768 | 0x8000 | f | | #111111 | 17, 17, 17 | | ### See also * **[`colours`](https://tweaked.cc/module/colours.html) ** | | | | --- | --- | | [white = 0x1](https://tweaked.cc/module/colors.html#v:white) | White: Written as `0` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit)
, has a default terminal colour of #F0F0F0. | | [orange = 0x2](https://tweaked.cc/module/colors.html#v:orange) | Orange: Written as `1` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit)
, has a default terminal colour of #F2B233. | | [magenta = 0x4](https://tweaked.cc/module/colors.html#v:magenta) | Magenta: Written as `2` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit)
, has a default terminal colour of #E57FD8. | | [lightBlue = 0x8](https://tweaked.cc/module/colors.html#v:lightBlue) | Light blue: Written as `3` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit)
, has a default terminal colour of #99B2F2. | | [yellow = 0x10](https://tweaked.cc/module/colors.html#v:yellow) | Yellow: Written as `4` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit)
, has a default terminal colour of #DEDE6C. | | [lime = 0x20](https://tweaked.cc/module/colors.html#v:lime) | Lime: Written as `5` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit)
, has a default terminal colour of #7FCC19. | | [pink = 0x40](https://tweaked.cc/module/colors.html#v:pink) | Pink: Written as `6` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit)
, has a default terminal colour of #F2B2CC. | | [gray = 0x80](https://tweaked.cc/module/colors.html#v:gray) | Gray: Written as `7` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit)
, has a default terminal colour of #4C4C4C. | | [lightGray = 0x100](https://tweaked.cc/module/colors.html#v:lightGray) | Light gray: Written as `8` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit)
, has a default terminal colour of #999999. | | [cyan = 0x200](https://tweaked.cc/module/colors.html#v:cyan) | Cyan: Written as `9` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit)
, has a default terminal colour of #4C99B2. | | [purple = 0x400](https://tweaked.cc/module/colors.html#v:purple) | Purple: Written as `a` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit)
, has a default terminal colour of #B266E5. | | [blue = 0x800](https://tweaked.cc/module/colors.html#v:blue) | Blue: Written as `b` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit)
, has a default terminal colour of #3366CC. | | [brown = 0x1000](https://tweaked.cc/module/colors.html#v:brown) | Brown: Written as `c` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit)
, has a default terminal colour of #7F664C. | | [green = 0x2000](https://tweaked.cc/module/colors.html#v:green) | Green: Written as `d` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit)
, has a default terminal colour of #57A64E. | | [red = 0x4000](https://tweaked.cc/module/colors.html#v:red) | Red: Written as `e` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit)
, has a default terminal colour of #CC4C4C. | | [black = 0x8000](https://tweaked.cc/module/colors.html#v:black) | Black: Written as `f` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit)
, has a default terminal colour of #111111. | | [combine(...)](https://tweaked.cc/module/colors.html#v:combine) | Combines a set of colors (or sets of colors) into a larger set. | | [subtract(colors, ...)](https://tweaked.cc/module/colors.html#v:subtract) | Removes one or more colors (or sets of colors) from an initial set. | | [test(colors, color)](https://tweaked.cc/module/colors.html#v:test) | Tests whether `color` is contained within `colors`. | | [packRGB(r, g, b)](https://tweaked.cc/module/colors.html#v:packRGB) | Combine a three-colour RGB value into one hexadecimal representation. | | [unpackRGB(rgb)](https://tweaked.cc/module/colors.html#v:unpackRGB) | Separate a hexadecimal RGB colour into its three constituent channels. | | [rgb8(...)](https://tweaked.cc/module/colors.html#v:rgb8) | Either calls [`colors.packRGB`](https://tweaked.cc/module/colors.html#v:packRGB)
or [`colors.unpackRGB`](https://tweaked.cc/module/colors.html#v:unpackRGB)
, depending on how many arguments it receives. | | [toBlit(color)](https://tweaked.cc/module/colors.html#v:toBlit) | Converts the given color to a paint/blit hex character (0-9a-f). | | [fromBlit(hex)](https://tweaked.cc/module/colors.html#v:fromBlit) | Converts the given paint/blit hex character (0-9a-f) to a color. | [](https://tweaked.cc/module/colors.html#v:white) white = 0x1[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L145) White: Written as `0` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #F0F0F0. [](https://tweaked.cc/module/colors.html#v:orange) orange = 0x2[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L149) Orange: Written as `1` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #F2B233. [](https://tweaked.cc/module/colors.html#v:magenta) magenta = 0x4[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L153) Magenta: Written as `2` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #E57FD8. [](https://tweaked.cc/module/colors.html#v:lightBlue) lightBlue = 0x8[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L157) Light blue: Written as `3` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #99B2F2. [](https://tweaked.cc/module/colors.html#v:yellow) yellow = 0x10[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L161) Yellow: Written as `4` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #DEDE6C. [](https://tweaked.cc/module/colors.html#v:lime) lime = 0x20[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L165) Lime: Written as `5` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #7FCC19. [](https://tweaked.cc/module/colors.html#v:pink) pink = 0x40[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L169) Pink: Written as `6` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #F2B2CC. [](https://tweaked.cc/module/colors.html#v:gray) gray = 0x80[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L173) Gray: Written as `7` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #4C4C4C. [](https://tweaked.cc/module/colors.html#v:lightGray) lightGray = 0x100[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L177) Light gray: Written as `8` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #999999. [](https://tweaked.cc/module/colors.html#v:cyan) cyan = 0x200[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L181) Cyan: Written as `9` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #4C99B2. [](https://tweaked.cc/module/colors.html#v:purple) purple = 0x400[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L185) Purple: Written as `a` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #B266E5. [](https://tweaked.cc/module/colors.html#v:blue) blue = 0x800[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L189) Blue: Written as `b` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #3366CC. [](https://tweaked.cc/module/colors.html#v:brown) brown = 0x1000[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L193) Brown: Written as `c` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #7F664C. [](https://tweaked.cc/module/colors.html#v:green) green = 0x2000[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L197) Green: Written as `d` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #57A64E. [](https://tweaked.cc/module/colors.html#v:red) red = 0x4000[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L201) Red: Written as `e` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #CC4C4C. [](https://tweaked.cc/module/colors.html#v:black) black = 0x8000[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L205) Black: Written as `f` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #111111. [](https://tweaked.cc/module/colors.html#v:combine) combine(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L218) Combines a set of colors (or sets of colors) into a larger set. Useful for Bundled Cables. ### Parameters 1. ... `number` The colors to combine. ### Returns 1. `number` The union of the color sets given in `...` ### Usage * Run ᐅ [colors.combine](https://tweaked.cc/module/colors.html#v:combine "Combines a set of colors (or sets of colors) into a larger set.") ([colors.white](https://tweaked.cc/module/colors.html#v:white "White: Written as 0 in paint files and term.blit, has a default terminal colour of #F0F0F0.") , [colors.magenta](https://tweaked.cc/module/colors.html#v:magenta "Magenta: Written as 2 in paint files and term.blit, has a default terminal colour of #E57FD8.") , [colours](https://tweaked.cc/module/colours.html "An alternative version of colors for lovers of British spelling.") .lightBlue) \-- => 13 ### Changes * **New in version 1.2** [](https://tweaked.cc/module/colors.html#v:subtract) subtract(colors, ...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L244) Removes one or more colors (or sets of colors) from an initial set. Useful for Bundled Cables. Each parameter beyond the first may be a single color or may be a set of colors (in the latter case, all colors in the set are removed from the original set). ### Parameters 1. colors `number` The color from which to subtract. 2. ... `number` The colors to subtract. ### Returns 1. `number` The resulting color. ### Usage * Run ᐅ [colours](https://tweaked.cc/module/colours.html "An alternative version of colors for lovers of British spelling.") .subtract([colours](https://tweaked.cc/module/colours.html "An alternative version of colors for lovers of British spelling.") .lime, [colours](https://tweaked.cc/module/colours.html "An alternative version of colors for lovers of British spelling.") .orange, [colours](https://tweaked.cc/module/colours.html "An alternative version of colors for lovers of British spelling.") .white) \-- => 32 ### Changes * **New in version 1.2** [](https://tweaked.cc/module/colors.html#v:test) test(colors, color)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L267) Tests whether `color` is contained within `colors`. Useful for Bundled Cables. ### Parameters 1. colors `number` A color, or color set 2. color `number` A color or set of colors that `colors` should contain. ### Returns 1. `boolean` If `colors` contains all colors within `color`. ### Usage * Run ᐅ [colors.test](https://tweaked.cc/module/colors.html#v:test "Tests whether color is contained within colors.") ([colors.combine](https://tweaked.cc/module/colors.html#v:combine "Combines a set of colors (or sets of colors) into a larger set.") ([colors.white](https://tweaked.cc/module/colors.html#v:white "White: Written as 0 in paint files and term.blit, has a default terminal colour of #F0F0F0.") , [colors.magenta](https://tweaked.cc/module/colors.html#v:magenta "Magenta: Written as 2 in paint files and term.blit, has a default terminal colour of #E57FD8.") , [colours](https://tweaked.cc/module/colours.html "An alternative version of colors for lovers of British spelling.") .lightBlue), [colors.lightBlue](https://tweaked.cc/module/colors.html#v:lightBlue "Light blue: Written as 3 in paint files and term.blit, has a default terminal colour of #99B2F2.") ) \-- => true ### Changes * **New in version 1.2** [](https://tweaked.cc/module/colors.html#v:packRGB) packRGB(r, g, b)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L285) Combine a three-colour RGB value into one hexadecimal representation. ### Parameters 1. r `number` The red channel, should be between 0 and 1. 2. g `number` The green channel, should be between 0 and 1. 3. b `number` The blue channel, should be between 0 and 1. ### Returns 1. `number` The combined hexadecimal colour. ### Usage * Run ᐅ [colors.packRGB](https://tweaked.cc/module/colors.html#v:packRGB "Combine a three-colour RGB value into one hexadecimal representation.") (0.7, 0.2, 0.6) \-- => 0xb23399 ### Changes * **New in version 1.81.0** [](https://tweaked.cc/module/colors.html#v:unpackRGB) unpackRGB(rgb)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L308) Separate a hexadecimal RGB colour into its three constituent channels. ### Parameters 1. rgb `number` The combined hexadecimal colour. ### Returns 1. `number` The red channel, will be between 0 and 1. 2. `number` The green channel, will be between 0 and 1. 3. `number` The blue channel, will be between 0 and 1. ### Usage * Run ᐅ [colors.unpackRGB](https://tweaked.cc/module/colors.html#v:unpackRGB "Separate a hexadecimal RGB colour into its three constituent channels.") (0xb23399) \-- => 0.7, 0.2, 0.6 ### See also * **[`colors.packRGB`](https://tweaked.cc/module/colors.html#v:packRGB) ** ### Changes * **New in version 1.81.0** [](https://tweaked.cc/module/colors.html#v:rgb8) rgb8(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L340) ##### 🛈 Deprecated Use [`packRGB`](https://tweaked.cc/module/colors.html#v:packRGB) or [`unpackRGB`](https://tweaked.cc/module/colors.html#v:unpackRGB) directly. Either calls [`colors.packRGB`](https://tweaked.cc/module/colors.html#v:packRGB) or [`colors.unpackRGB`](https://tweaked.cc/module/colors.html#v:unpackRGB) , depending on how many arguments it receives. ### Parameters 1. r `number` The red channel, as an argument to [`colors.packRGB`](https://tweaked.cc/module/colors.html#v:packRGB) . 2. g `number` The green channel, as an argument to [`colors.packRGB`](https://tweaked.cc/module/colors.html#v:packRGB) . 3. b `number` The blue channel, as an argument to [`colors.packRGB`](https://tweaked.cc/module/colors.html#v:packRGB) . #### Or 1. rgb `number` The combined hexadecimal color, as an argument to [`colors.unpackRGB`](https://tweaked.cc/module/colors.html#v:unpackRGB) . ### Returns 1. `number` The combined hexadecimal colour, as returned by [`colors.packRGB`](https://tweaked.cc/module/colors.html#v:packRGB) . #### Or 1. `number` The red channel, as returned by [`colors.unpackRGB`](https://tweaked.cc/module/colors.html#v:unpackRGB) 2. `number` The green channel, as returned by [`colors.unpackRGB`](https://tweaked.cc/module/colors.html#v:unpackRGB) 3. `number` The blue channel, as returned by [`colors.unpackRGB`](https://tweaked.cc/module/colors.html#v:unpackRGB) ### Usage * Run ᐅ [colors.rgb8](https://tweaked.cc/module/colors.html#v:rgb8 "Either calls colors.packRGB or colors.unpackRGB, depending on how many arguments it receives.") (0xb23399) \-- => 0.7, 0.2, 0.6 * Run ᐅ [colors.rgb8](https://tweaked.cc/module/colors.html#v:rgb8 "Either calls colors.packRGB or colors.unpackRGB, depending on how many arguments it receives.") (0.7, 0.2, 0.6) \-- => 0xb23399 ### Changes * **New in version 1.80pr1** * **Changed in version 1.81.0:** Deprecated in favor of colors.(un)packRGB. [](https://tweaked.cc/module/colors.html#v:toBlit) toBlit(color)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L369) Converts the given color to a paint/blit hex character (0-9a-f). This is equivalent to converting `floor(log_2(color))` to hexadecimal. Values outside the range of a valid colour will error. ### Parameters 1. color `number` The color to convert. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The blit hex code of the color. ### Usage * Run ᐅ [colors.toBlit](https://tweaked.cc/module/colors.html#v:toBlit "Converts the given color to a paint/blit hex character (0-9a-f).") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") ) \-- => "c" ### See also * **[`colors.fromBlit`](https://tweaked.cc/module/colors.html#v:fromBlit) ** ### Changes * **New in version 1.94.0** [](https://tweaked.cc/module/colors.html#v:fromBlit) fromBlit(hex)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua#L392) Converts the given paint/blit hex character (0-9a-f) to a color. This is equivalent to converting the hex character to a number and then 2 ^ decimal ### Parameters 1. hex [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The paint/blit hex character to convert ### Returns 1. `number` The color ### Usage * Run ᐅ [colors.fromBlit](https://tweaked.cc/module/colors.html#v:fromBlit "Converts the given paint/blit hex character (0-9a-f) to a color.") ("e") \-- => 16384 ### See also * **[`colors.toBlit`](https://tweaked.cc/module/colors.html#v:toBlit) ** ### Changes * **New in version 1.105.0** --- # colours colours ======= An alternative version of [`colors`](https://tweaked.cc/module/colors.html) for lovers of British spelling. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** ### Changes * **New in version 1.2** | | | | --- | --- | | [grey](https://tweaked.cc/module/colours.html#v:grey) | Grey. | | [lightGrey](https://tweaked.cc/module/colours.html#v:lightGrey) | Light grey. | [](https://tweaked.cc/module/colours.html#v:grey) grey[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colours.lua#L20) Grey. Written as `7` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #4C4C4C. ### See also * **[`colors.gray`](https://tweaked.cc/module/colors.html#v:gray) ** [](https://tweaked.cc/module/colours.html#v:lightGrey) lightGrey[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colours.lua#L27) Light grey. Written as `8` in paint files and [`term.blit`](https://tweaked.cc/module/term.html#v:blit) , has a default terminal colour of #999999. ### See also * **[`colors.lightGray`](https://tweaked.cc/module/colors.html#v:lightGray) ** --- # commands commands ======== Execute [Minecraft commands](https://minecraft.wiki/w/Commands) and gather data from the results from a command computer. ##### 🛈 note This API is only available on Command computers. It is not accessible to normal players. While one may use [`commands.exec`](https://tweaked.cc/module/commands.html#v:exec) directly to execute a command, the commands API also provides helper methods to execute every command. For instance, `commands.say("Hi!")` is equivalent to `commands.exec("say Hi!")`. [`commands.async`](https://tweaked.cc/module/commands.html#v:async) provides a similar interface to execute asynchronous commands. `commands.async.say("Hi!")` is equivalent to `commands.execAsync("say Hi!")`. ### Usage * Set the block above this computer to stone: Run ᐅ [commands](https://tweaked.cc/module/commands.html "Execute Minecraft commands and gather data from the results from a command computer.") .setblock("~", "~1", "~", "minecraft:stone") ### Changes * **New in version 1.7** | | | | --- | --- | | [exec(command)](https://tweaked.cc/module/commands.html#v:exec) | Execute a specific command. | | [execAsync(command)](https://tweaked.cc/module/commands.html#v:execAsync) | Asynchronously execute a command. | | [list(...)](https://tweaked.cc/module/commands.html#v:list) | List all available commands which the computer has permission to execute. | | [getDimension()](https://tweaked.cc/module/commands.html#v:getDimension) | Get the name of the dimension the current command computer is in, such as `minecraft:overworld`. | | [getBlockPosition()](https://tweaked.cc/module/commands.html#v:getBlockPosition) | Get the position of the current command computer. | | [getBlockInfos(minX, minY, minZ, maxX, maxY, maxZ \[, dimension\])](https://tweaked.cc/module/commands.html#v:getBlockInfos) | Get information about a range of blocks. | | [getBlockInfo(x, y, z \[, dimension\])](https://tweaked.cc/module/commands.html#v:getBlockInfo) | Get some basic information about a block. | | [getEntities(selector)](https://tweaked.cc/module/commands.html#v:getEntities) | Get all entities matching the given selector. | | [native](https://tweaked.cc/module/commands.html#v:native) | The builtin commands API, without any generated command helper functions | | [async](https://tweaked.cc/module/commands.html#v:async) | A table containing asynchronous wrappers for all commands. | [](https://tweaked.cc/module/commands.html#v:exec) exec(command)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java#L103) Execute a specific command. ### Parameters 1. command [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The command to execute. ### Returns 1. `boolean` Whether the command executed successfully. 2. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } The output of this command, as a list of lines. 3. `number` | nil The number of "affected" objects, or `nil` if the command failed. The definition of this varies from command to command. ### Usage * Set the block above the command computer to stone. Run ᐅ [commands.exec](https://tweaked.cc/module/commands.html#v:exec "Execute a specific command.") ("setblock ~ ~1 ~ minecraft:stone") ### Changes * **Changed in version 1.71:** Added return value with command output. * **Changed in version 1.85.0:** Added return value with the number of affected objects. [](https://tweaked.cc/module/commands.html#v:execAsync) execAsync(command)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java#L129) Asynchronously execute a command. Unlike [`exec`](https://tweaked.cc/module/commands.html#v:exec) , this will immediately return, instead of waiting for the command to execute. This allows you to run multiple commands at the same time. When this command has finished executing, it will queue a `task_complete` event containing the result of executing this command (what [`exec`](https://tweaked.cc/module/commands.html#v:exec) would return). ### Parameters 1. command [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The command to execute. ### Returns 1. `number` The "task id". When this command has been executed, it will queue a `task_complete` event with a matching id. ### Usage * Asynchronously sets the block above the computer to stone. Run ᐅ [commands.execAsync](https://tweaked.cc/module/commands.html#v:execAsync "Asynchronously execute a command.") ("setblock ~ ~1 ~ minecraft:stone") ### See also * **[`parallel`](https://tweaked.cc/module/parallel.html) ** One may also use the parallel API to run multiple commands at once. [](https://tweaked.cc/module/commands.html#v:list) list(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java#L142) List all available commands which the computer has permission to execute. ### Parameters 1. ... [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The sub-command to complete. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } A list of all available commands [](https://tweaked.cc/module/commands.html#v:getDimension) getDimension()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java#L167) Get the name of the dimension the current command computer is in, such as `minecraft:overworld`. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The dimension the computer is in. ### See also * **[`getBlockPosition`](https://tweaked.cc/module/commands.html#v:getBlockPosition) ** ### Changes * **New in version 1.119.0** [](https://tweaked.cc/module/commands.html#v:getBlockPosition) getBlockPosition()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java#L182) Get the position of the current command computer. ### Returns 1. `number` This computer's x position. 2. `number` This computer's y position. 3. `number` This computer's z position. ### See also * **[`gps.locate`](https://tweaked.cc/module/gps.html#v:locate) ** To get the position of a non-command computer. * **[`getDimension`](https://tweaked.cc/module/commands.html#v:getDimension) ** [](https://tweaked.cc/module/commands.html#v:getBlockInfos) getBlockInfos(minX, minY, minZ, maxX, maxY, maxZ \[, dimension\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java#L228) Get information about a range of blocks. This returns the same information as [`getBlockInfo`](https://tweaked.cc/module/commands.html#v:getBlockInfo) , just for multiple blocks at once. Blocks are traversed by ascending y level, followed by z and x - the returned table may be indexed using `x + z*width + y*width*depth + 1`. ### Parameters 1. minX `number` The start x coordinate of the range to query. 2. minY `number` The start y coordinate of the range to query. 3. minZ `number` The start z coordinate of the range to query. 4. maxX `number` The end x coordinate of the range to query. 5. maxY `number` The end y coordinate of the range to query. 6. maxZ `number` The end z coordinate of the range to query. 7. dimension? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The dimension to query (e.g. "minecraft:overworld"). Defaults to the current dimension. ### Returns 1. { [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) ... } A list of information about each block. ### Throws * If the coordinates are not within the world. * If trying to get information about more than 4096 blocks. ### Usage * Print out all blocks in a cube around the computer. Run ᐅ \-- Get a 3x3x3 cube around the computer local x, y, z \= [commands.getBlockPosition](https://tweaked.cc/module/commands.html#v:getBlockPosition "Get the position of the current command computer.") () local min\_x, min\_y, min\_z, max\_x, max\_y, max\_z \= x \- 1, y \- 1, z \- 1, x + 1, y + 1, z + 1 local blocks \= [commands.getBlockInfos](https://tweaked.cc/module/commands.html#v:getBlockInfos "Get information about a range of blocks.") (min\_x, min\_y, min\_z, max\_x, max\_y, max\_z) \-- Then loop over all blocks and print them out. local width, height, depth \= max\_x \- min\_x + 1, max\_y \- min\_y + 1, max\_z \- min\_z + 1 for x \= min\_x, max\_x do for y \= min\_y, max\_y do for z \= min\_z, max\_z do print(("%d, %d %d => %s"):format(x, y, z, blocks\[(x \- min\_x) + (z \- min\_z) \* width + (y \- min\_y) \* width \* depth + 1\].name)) end end end ### Changes * **New in version 1.76** * **Changed in version 1.99:** Added `dimension` argument. [](https://tweaked.cc/module/commands.html#v:getBlockInfo) getBlockInfo(x, y, z \[, dimension\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java#L277) Get some basic information about a block. The returned table contains the the same information as listed in [Block details](https://tweaked.cc/reference/block_details.html) . If there is a block entity for that block, its NBT will also be returned. ### Parameters 1. x `number` The x position of the block to query. 2. y `number` The y position of the block to query. 3. z `number` The z position of the block to query. 4. dimension? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The dimension to query (e.g. "minecraft:overworld"). Defaults to the current dimension. ### Returns 1. [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The given block's information. ### Throws * If the coordinates are not within the world, or are not currently loaded. ### Changes * **Changed in version 1.76:** Added block state info to return value * **Changed in version 1.99:** Added `dimension` argument. [](https://tweaked.cc/module/commands.html#v:getEntities) getEntities(selector)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java#L301) Get all entities matching the given selector. ### Parameters 1. selector [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) An [entity selector](https://minecraft.wiki/w/Target_selectors) , such as `@p` or `@a`. ### Returns 1. { [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) ... } A list of information about all matching entities. ### Throws * If the entity selector canont be parsed. ### Usage * Print the name of all entities within 10 blocks of the command computer. Run ᐅ for \_, entity in ipairs([commands.getEntities](https://tweaked.cc/module/commands.html#v:getEntities "Get all entities matching the given selector.") ("@e\[distance=..10\]")) do print(entity.displayName) end ### See also * **[`Entity details`](https://tweaked.cc/reference/entity_details.html) ** ### Changes * **New in version 1.118.0** [](https://tweaked.cc/module/commands.html#v:native) native[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/command/commands.lua#L35) The builtin commands API, without any generated command helper functions This may be useful if a built-in function (such as [`commands.list`](https://tweaked.cc/module/commands.html#v:list) ) has been overwritten by a command. [](https://tweaked.cc/module/commands.html#v:async) async[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/command/commands.lua#L61) A table containing asynchronous wrappers for all commands. As with [`commands.execAsync`](https://tweaked.cc/module/commands.html#v:execAsync) , this returns the "task id" of the enqueued command. ### Usage * Asynchronously sets the block above the computer to stone. Run ᐅ [commands.async](https://tweaked.cc/module/commands.html#v:async "A table containing asynchronous wrappers for all commands.") .setblock("~", "~1", "~", "minecraft:stone") ### See also * **[`execAsync`](https://tweaked.cc/module/commands.html#v:execAsync) ** --- # disk disk ==== Interact with disk drives. These functions can operate on locally attached or remote disk drives. To use a locally attached drive, specify “side” as one of the six sides (e.g. `left`); to use a remote disk drive, specify its name as printed when enabling its modem (e.g. `drive_0`). ##### tip All computers (except command computers), turtles and pocket computers can be placed within a disk drive to access it's internal storage like a disk. ### Changes * **New in version 1.2** | | | | --- | --- | | [isPresent(name)](https://tweaked.cc/module/disk.html#v:isPresent) | Checks whether any item at all is in the disk drive | | [getLabel(name)](https://tweaked.cc/module/disk.html#v:getLabel) | Get the label of the floppy disk, record, or other media within the given disk drive. | | [setLabel(name, label)](https://tweaked.cc/module/disk.html#v:setLabel) | Set the label of the floppy disk or other media | | [hasData(name)](https://tweaked.cc/module/disk.html#v:hasData) | Check whether the current disk provides a mount. | | [getMountPath(name)](https://tweaked.cc/module/disk.html#v:getMountPath) | Find the directory name on the local computer where the contents of the current floppy disk (or other mount) can be found. | | [hasAudio(name)](https://tweaked.cc/module/disk.html#v:hasAudio) | Whether the current disk is a music disk as opposed to a floppy disk or other item. | | [getAudioTitle(name)](https://tweaked.cc/module/disk.html#v:getAudioTitle) | Get the title of the audio track from the music record in the drive. | | [playAudio(name)](https://tweaked.cc/module/disk.html#v:playAudio) | Starts playing the music record in the drive. | | [stopAudio(name)](https://tweaked.cc/module/disk.html#v:stopAudio) | Stops the music record in the drive from playing, if it was started with [`disk.playAudio`](https://tweaked.cc/module/disk.html#v:playAudio)
. | | [eject(name)](https://tweaked.cc/module/disk.html#v:eject) | Ejects any item currently in the drive, spilling it into the world as a loose item. | | [getID(name)](https://tweaked.cc/module/disk.html#v:getID) | Returns a number which uniquely identifies the disk in the drive. | [](https://tweaked.cc/module/disk.html#v:isPresent) isPresent(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua#L32) Checks whether any item at all is in the disk drive ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the disk drive. ### Returns 1. `boolean` If something is in the disk drive. ### Usage * Run ᐅ [disk.isPresent](https://tweaked.cc/module/disk.html#v:isPresent "Checks whether any item at all is in the disk drive") ("top") [](https://tweaked.cc/module/disk.html#v:getLabel) getLabel(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua#L49) Get the label of the floppy disk, record, or other media within the given disk drive. If there is a computer or turtle within the drive, this will set the label as read by `os.getComputerLabel`. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the disk drive. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The name of the current media, or `nil` if the drive is not present or empty. ### See also * **[`disk.setLabel`](https://tweaked.cc/module/disk.html#v:setLabel) ** [](https://tweaked.cc/module/disk.html#v:setLabel) setLabel(name, label)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua#L60) Set the label of the floppy disk or other media ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the disk drive. 2. label [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The new label of the disk [](https://tweaked.cc/module/disk.html#v:hasData) hasData(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua#L73) Check whether the current disk provides a mount. This will return true for disks and computers, but not records. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the disk drive. ### Returns 1. `boolean` If the disk is present and provides a mount. ### See also * **[`disk.getMountPath`](https://tweaked.cc/module/disk.html#v:getMountPath) ** [](https://tweaked.cc/module/disk.html#v:getMountPath) getMountPath(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua#L87) Find the directory name on the local computer where the contents of the current floppy disk (or other mount) can be found. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the disk drive. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The mount's directory, or `nil` if the drive does not contain a floppy or computer. ### See also * **[`disk.hasData`](https://tweaked.cc/module/disk.html#v:hasData) ** [](https://tweaked.cc/module/disk.html#v:hasAudio) hasAudio(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua#L103) Whether the current disk is a [music disk](https://minecraft.wiki/w/Music_Disc) as opposed to a floppy disk or other item. If this returns true, you will can [play](https://tweaked.cc/module/disk.html#v:playAudio) the record. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the disk drive. ### Returns 1. `boolean` If the disk is present and has audio saved on it. [](https://tweaked.cc/module/disk.html#v:getAudioTitle) getAudioTitle(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua#L117) Get the title of the audio track from the music record in the drive. This generally returns the same as [`disk.getLabel`](https://tweaked.cc/module/disk.html#v:getLabel) for records. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the disk drive. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | false | nil The track title, `false` if there is not a music record in the drive or `nil` if no drive is present. [](https://tweaked.cc/module/disk.html#v:playAudio) playAudio(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua#L133) Starts playing the music record in the drive. If any record is already playing on any disk drive, it stops before the target drive starts playing. The record stops when it reaches the end of the track, when it is removed from the drive, when [`disk.stopAudio`](https://tweaked.cc/module/disk.html#v:stopAudio) is called, or when another record is started. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the disk drive. ### Usage * Run ᐅ [disk.playAudio](https://tweaked.cc/module/disk.html#v:playAudio "Starts playing the music record in the drive.") ("bottom") [](https://tweaked.cc/module/disk.html#v:stopAudio) stopAudio(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua#L143) Stops the music record in the drive from playing, if it was started with [`disk.playAudio`](https://tweaked.cc/module/disk.html#v:playAudio) . ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name o the disk drive. [](https://tweaked.cc/module/disk.html#v:eject) eject(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua#L159) Ejects any item currently in the drive, spilling it into the world as a loose item. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the disk drive. ### Usage * Run ᐅ [disk.eject](https://tweaked.cc/module/disk.html#v:eject "Ejects any item currently in the drive, spilling it into the world as a loose item.") ("bottom") [](https://tweaked.cc/module/disk.html#v:getID) getID(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua#L173) Returns a number which uniquely identifies the disk in the drive. Note, unlike [`disk.getLabel`](https://tweaked.cc/module/disk.html#v:getLabel) , this does not return anything for other media, such as computers or turtles. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the disk drive. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The disk ID, or `nil` if the drive does not contain a floppy disk. ### Changes * **New in version 1.4** --- # gps gps === Use [modems](https://tweaked.cc/peripheral/modem.html) to locate the position of the current turtle or computers. This works by communicating with other computers (called GPS hosts) that already know their position, finding the distance to those computers (with [`modem_message`](https://tweaked.cc/event/modem_message.html) ), and using that to derive its position from theirs (with a process known as [trilateration](https://en.wikipedia.org/wiki/Trilateration) . ### See also * **[`Setting up GPS`](https://tweaked.cc/guide/gps_setup.html) ** ### Changes * **New in version 1.31** | | | | --- | --- | | [CHANNEL\_GPS = 65534](https://tweaked.cc/module/gps.html#v:CHANNEL_GPS) | The channel which GPS requests and responses are broadcast on. | | [locate(\[timeout=2 \[, debug=false\]\])](https://tweaked.cc/module/gps.html#v:locate) | Tries to retrieve the computer or turtles own location. | [](https://tweaked.cc/module/gps.html#v:CHANNEL_GPS) CHANNEL\_GPS = 65534[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/gps.lua#L21) The channel which GPS requests and responses are broadcast on. [](https://tweaked.cc/module/gps.html#v:locate) locate(\[timeout=2 \[, debug=false\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/gps.lua#L86) Tries to retrieve the computer or turtles own location. ### Parameters 1. timeout? `number` = The maximum time in seconds taken to establish our position. 2. debug? `boolean` = Print debugging messages ### Returns 1. `number` This computer's `x` position. 2. `number` This computer's `y` position. 3. `number` This computer's `z` position. #### Or 1. nil If the position could not be established. --- # fs fs == Interact with the computer's files and filesystem, allowing you to manipulate files, directories and paths. This includes: * **Reading and writing files:** Call [`open`](https://tweaked.cc/module/fs.html#v:open) to obtain a file "handle", which can be used to read from or write to a file. * **Path manipulation:** [`combine`](https://tweaked.cc/module/fs.html#v:combine) , [`getName`](https://tweaked.cc/module/fs.html#v:getName) and [`getDir`](https://tweaked.cc/module/fs.html#v:getDir) allow you to manipulate file paths, joining them together or extracting components. * **Querying paths:** For instance, checking if a file exists, or whether it's a directory. See [`getSize`](https://tweaked.cc/module/fs.html#v:getSize) , [`exists`](https://tweaked.cc/module/fs.html#v:exists) , [`isDir`](https://tweaked.cc/module/fs.html#v:isDir) , [`isReadOnly`](https://tweaked.cc/module/fs.html#v:isReadOnly) and [`attributes`](https://tweaked.cc/module/fs.html#v:attributes) . * **File and directory manipulation:** For instance, moving or copying files. See [`makeDir`](https://tweaked.cc/module/fs.html#v:makeDir) , [`move`](https://tweaked.cc/module/fs.html#v:move) , [`copy`](https://tweaked.cc/module/fs.html#v:copy) and [`delete`](https://tweaked.cc/module/fs.html#v:delete) . ##### 🛈 note All functions in the API work on absolute paths, and do not take the [current directory](https://tweaked.cc/module/shell.html#v:dir) into account. You can use [`shell.resolve`](https://tweaked.cc/module/shell.html#v:resolve) to convert a relative path into an absolute one. Mounts ------ While a computer can only have one hard drive and filesystem, other filesystems may be "mounted" inside it. For instance, the [drive peripheral](https://tweaked.cc/peripheral/drive.html) mounts its disk's contents at `"disk/"`, `"disk1/"`, etc... You can see which mount a path belongs to with the [`getDrive`](https://tweaked.cc/module/fs.html#v:getDrive) function. This returns `"hdd"` for the computer's main filesystem (`"/"`), `"rom"` for the rom (`"rom/"`). Most filesystems have a limited capacity, operations which would cause that capacity to be reached (such as writing an incredibly large file) will fail. You can see a mount's capacity with [`getCapacity`](https://tweaked.cc/module/fs.html#v:getCapacity) and the remaining space with [`getFreeSpace`](https://tweaked.cc/module/fs.html#v:getFreeSpace) . | | | | --- | --- | | [complete(...)](https://tweaked.cc/module/fs.html#v:complete) | Provides completion for a file or directory name, suitable for use with [`_G.read`](https://tweaked.cc/module/_G.html#v:read)
. | | [find(path)](https://tweaked.cc/module/fs.html#v:find) | Searches for files matching a string with wildcards. | | [isDriveRoot(path)](https://tweaked.cc/module/fs.html#v:isDriveRoot) | Returns true if a path is mounted to the parent filesystem. | | [list(path)](https://tweaked.cc/module/fs.html#v:list) | Returns a list of files in a directory. | | [combine(path, ...)](https://tweaked.cc/module/fs.html#v:combine) | Combines several parts of a path into one full path, adding separators as needed. | | [getName(path)](https://tweaked.cc/module/fs.html#v:getName) | Returns the file name portion of a path. | | [getDir(path)](https://tweaked.cc/module/fs.html#v:getDir) | Returns the parent directory portion of a path. | | [getSize(path)](https://tweaked.cc/module/fs.html#v:getSize) | Returns the size of the specified file. | | [exists(path)](https://tweaked.cc/module/fs.html#v:exists) | Returns whether the specified path exists. | | [isDir(path)](https://tweaked.cc/module/fs.html#v:isDir) | Returns whether the specified path is a directory. | | [isReadOnly(path)](https://tweaked.cc/module/fs.html#v:isReadOnly) | Returns whether a path is read-only. | | [makeDir(path)](https://tweaked.cc/module/fs.html#v:makeDir) | Creates a directory, and any missing parents, at the specified path. | | [move(path, dest)](https://tweaked.cc/module/fs.html#v:move) | Moves a file or directory from one path to another. | | [copy(path, dest)](https://tweaked.cc/module/fs.html#v:copy) | Copies a file or directory to a new path. | | [delete(path)](https://tweaked.cc/module/fs.html#v:delete) | Deletes a file or directory. | | [open(path, mode)](https://tweaked.cc/module/fs.html#v:open) | Opens a file for reading or writing at a path. | | [getDrive(path)](https://tweaked.cc/module/fs.html#v:getDrive) | Returns the name of the mount that the specified path is located on. | | [getFreeSpace(path)](https://tweaked.cc/module/fs.html#v:getFreeSpace) | Returns the amount of free space available on the drive the path is located on. | | [getCapacity(path)](https://tweaked.cc/module/fs.html#v:getCapacity) | Returns the capacity of the drive the path is located on. | | [attributes(path)](https://tweaked.cc/module/fs.html#v:attributes) | Get attributes about a specific file or folder. | [](https://tweaked.cc/module/fs.html#v:complete) complete(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/fs.lua#L63) Provides completion for a file or directory name, suitable for use with [`_G.read`](https://tweaked.cc/module/_G.html#v:read) . When a directory is a possible candidate for completion, two entries are included - one with a trailing slash (indicating that entries within this directory exist) and one without it (meaning this entry is an immediate completion candidate). `include_dirs` can be set to `false` to only include those with a trailing slash. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to complete. 2. location [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The location where paths are resolved from. 3. include\_files? `boolean` = When `false`, only directories will be included in the returned list. 4. include\_dirs? `boolean` = When `false`, "raw" directories will not be included in the returned list. #### Or 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to complete. 2. location [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The location where paths are resolved from. 3. options { include\_dirs? = `boolean`, include\_files? = `boolean`, include\_hidden? = `boolean` } This table form is an expanded version of the previous syntax. The `include_files` and `include_dirs` arguments from above are passed in as fields. This table also accepts the following options: * `include_hidden`: Whether to include hidden files (those starting with `.`) by default. They will still be shown when typing a `.`. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } A list of possible completion candidates. ### Usage * Complete files in the root directory. Run ᐅ read(nil, nil, function(str) return [fs.complete](https://tweaked.cc/module/fs.html#v:complete "Provides completion for a file or directory name, suitable for use with _G.read.") (str, "", true, false) end) * Complete files in the root directory, hiding hidden files by default. Run ᐅ read(nil, nil, function(str) return [fs.complete](https://tweaked.cc/module/fs.html#v:complete "Provides completion for a file or directory name, suitable for use with _G.read.") (str, "", { include\_files \= true, include\_dirs \= false, include\_hidden \= false, }) end) ### Changes * **New in version 1.74** * **Changed in version 1.101.0** [](https://tweaked.cc/module/fs.html#v:find) find(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/fs.lua#L190) Searches for files matching a string with wildcards. This string looks like a normal path string, but can include wildcards, which can match multiple paths: * "?" matches any single character in a file name. * "\*" matches any number of characters. For example, `rom/*/command*` will look for any path starting with `command` inside any subdirectory of `/rom`. Note that these wildcards match a single segment of the path. For instance `rom/*.lua` will include `rom/startup.lua` but _not_ include `rom/programs/list.lua`. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The wildcard-qualified path to search for. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } A list of paths that match the search string. ### Throws * If the supplied path was invalid. ### Usage * List all Markdown files in the help folder Run ᐅ [fs.find](https://tweaked.cc/module/fs.html#v:find "Searches for files matching a string with wildcards.") ("rom/help/\*.md") ### Changes * **New in version 1.6** * **Changed in version 1.106.0:** Added support for the `?` wildcard. [](https://tweaked.cc/module/fs.html#v:isDriveRoot) isDriveRoot(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/fs.lua#L233) Returns true if a path is mounted to the parent filesystem. The root filesystem "/" is considered a mount, along with disk folders and the rom folder. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to check. ### Returns 1. `boolean` If the path is mounted, rather than a normal file/folder. ### Throws * If the path does not exist. ### See also * **[`getDrive`](https://tweaked.cc/module/fs.html#v:getDrive) ** ### Changes * **New in version 1.87.0** [](https://tweaked.cc/module/fs.html#v:list) list(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L103) Returns a list of files in a directory. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to list. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } A table with a list of files in the directory. ### Throws * If the path doesn't exist. ### Usage * List all files under `/rom/` Run ᐅ local files \= [fs.list](https://tweaked.cc/module/fs.html#v:list "Returns a list of files in a directory.") ("/rom/") for i \= 1, #files do print(files\[i\]) end [](https://tweaked.cc/module/fs.html#v:combine) combine(path, ...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L128) Combines several parts of a path into one full path, adding separators as needed. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The first part of the path. For example, a parent directory path. 2. ... [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Additional parts of the path to combine. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The new path, with separators added between parts as needed. ### Throws * On argument errors. ### Usage * Combine several file paths together Run ᐅ [fs.combine](https://tweaked.cc/module/fs.html#v:combine "Combines several parts of a path into one full path, adding separators as needed.") ("/rom/programs", "../apis", "parallel.lua") \-- => rom/apis/parallel.lua ### Changes * **Changed in version 1.95.0:** Now supports multiple arguments. [](https://tweaked.cc/module/fs.html#v:getName) getName(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L154) Returns the file name portion of a path. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to get the name from. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The final part of the path (the file name). ### Usage * Get the file name of `rom/startup.lua` Run ᐅ [fs.getName](https://tweaked.cc/module/fs.html#v:getName "Returns the file name portion of a path.") ("rom/startup.lua") \-- => startup.lua ### Changes * **New in version 1.2** [](https://tweaked.cc/module/fs.html#v:getDir) getDir(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L171) Returns the parent directory portion of a path. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to get the directory from. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path with the final part removed (the parent directory). ### Usage * Get the directory name of `rom/startup.lua` Run ᐅ [fs.getDir](https://tweaked.cc/module/fs.html#v:getDir "Returns the parent directory portion of a path.") ("rom/startup.lua") \-- => rom ### Changes * **New in version 1.63** [](https://tweaked.cc/module/fs.html#v:getSize) getSize(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L184) Returns the size of the specified file. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The file to get the file size of. ### Returns 1. `number` The size of the file, in bytes. ### Throws * If the path doesn't exist. ### Changes * **New in version 1.3** [](https://tweaked.cc/module/fs.html#v:exists) exists(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L199) Returns whether the specified path exists. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to check the existence of. ### Returns 1. `boolean` Whether the path exists. [](https://tweaked.cc/module/fs.html#v:isDir) isDir(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L214) Returns whether the specified path is a directory. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to check. ### Returns 1. `boolean` Whether the path is a directory. [](https://tweaked.cc/module/fs.html#v:isReadOnly) isReadOnly(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L229) Returns whether a path is read-only. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to check. ### Returns 1. `boolean` Whether the path cannot be written to. [](https://tweaked.cc/module/fs.html#v:makeDir) makeDir(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L244) Creates a directory, and any missing parents, at the specified path. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to the directory to create. ### Throws * If the directory couldn't be created. [](https://tweaked.cc/module/fs.html#v:move) move(path, dest)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L262) Moves a file or directory from one path to another. Any parent directories are created as needed. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The current file or directory to move from. 2. dest [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The destination path for the file or directory. ### Throws * If the file or directory couldn't be moved. [](https://tweaked.cc/module/fs.html#v:copy) copy(path, dest)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L280) Copies a file or directory to a new path. Any parent directories are created as needed. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The file or directory to copy. 2. dest [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to the destination file or directory. ### Throws * If the file or directory couldn't be copied. [](https://tweaked.cc/module/fs.html#v:delete) delete(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L298) Deletes a file or directory. If the path points to a directory, all of the enclosed files and subdirectories are also deleted. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to the file or directory to delete. ### Throws * If the file or directory couldn't be deleted. [](https://tweaked.cc/module/fs.html#v:open) open(path, mode)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L365) Opens a file for reading or writing at a path. The `mode` string can be any of the following: * **"r"**: Read mode. * **"w"**: Write mode. * **"a"**: Append mode. * **"r+"**: Update mode (allows reading and writing), all data is preserved. * **"w+"**: Update mode, all data is erased. The mode may also have a "b" at the end, which opens the file in "binary mode". This changes [`fs.ReadHandle.read`](https://tweaked.cc/module/fs.html#ty:ReadHandle:read) and [`fs.WriteHandle.write`](https://tweaked.cc/module/fs.html#ty:WriteHandle:write) to read/write single bytes as numbers rather than strings. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to the file to open. 2. mode [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The mode to open the file with. ### Returns 1. [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) A file handle object for the file. #### Or 1. nil If the file does not exist, or cannot be opened. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil A message explaining why the file cannot be opened. ### Throws * If an invalid mode was specified. ### Usage * Read the contents of a file. Run ᐅ local file \= [fs.open](https://tweaked.cc/module/fs.html#v:open "Opens a file for reading or writing at a path.") ("/rom/help/intro.txt", "r") local contents \= file.readAll() file.close() print(contents) * Open a file and read all lines into a table. [`io.lines`](https://tweaked.cc/module/io.html#v:lines) offers an alternative way to do this. Run ᐅ local file \= [fs.open](https://tweaked.cc/module/fs.html#v:open "Opens a file for reading or writing at a path.") ("/rom/motd.txt", "r") local lines \= {} while true do local line \= file.readLine() \-- If line is nil then we've reached the end of the file and should stop if not line then break end lines\[#lines + 1\] \= line end file.close() print(lines\[math.random(#lines)\]) \-- Pick a random line and print it. * Open a file and write some text to it. You can run `edit out.txt` to see the written text. Run ᐅ local file \= [fs.open](https://tweaked.cc/module/fs.html#v:open "Opens a file for reading or writing at a path.") ("out.txt", "w") file.write("Just testing some code") file.close() \-- Remember to call close, otherwise changes may not be written! ### Changes * **Changed in version 1.109.0:** Add support for update modes (`r+` and `w+`). * **Changed in version 1.109.0:** Opening a file in non-binary mode now uses the raw bytes of the file rather than encoding to UTF-8. [](https://tweaked.cc/module/fs.html#v:getDrive) getDrive(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L413) Returns the name of the mount that the specified path is located on. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to get the drive of. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The name of the drive that the file is on; e.g. `hdd` for local files, or `rom` for ROM files. ### Throws * If the path doesn't exist. ### Usage * Print the drives of a couple of mounts: Run ᐅ print("/: " .. [fs.getDrive](https://tweaked.cc/module/fs.html#v:getDrive "Returns the name of the mount that the specified path is located on.") ("/")) print("/rom/: " .. [fs.getDrive](https://tweaked.cc/module/fs.html#v:getDrive "Returns the name of the mount that the specified path is located on.") ("rom")) [](https://tweaked.cc/module/fs.html#v:getFreeSpace) getFreeSpace(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L433) Returns the amount of free space available on the drive the path is located on. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to check the free space for. ### Returns 1. `number` | "unlimited" The amount of free space available, in bytes, or "unlimited". ### Throws * If the path doesn't exist. ### See also * **[`getCapacity`](https://tweaked.cc/module/fs.html#v:getCapacity) ** To get the capacity of this drive. ### Changes * **New in version 1.4** [](https://tweaked.cc/module/fs.html#v:getCapacity) getCapacity(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L454) Returns the capacity of the drive the path is located on. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path of the drive to get. ### Returns 1. `number` | nil This drive's capacity. This will be nil for "read-only" drives, such as the ROM or treasure disks. ### Throws * If the capacity cannot be determined. ### See also * **[`getFreeSpace`](https://tweaked.cc/module/fs.html#v:getFreeSpace) ** To get the free space available on this drive. ### Changes * **New in version 1.87.0** [](https://tweaked.cc/module/fs.html#v:attributes) attributes(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java#L484) Get attributes about a specific file or folder. The returned attributes table contains information about the size of the file, whether it is a directory, when it was created and last modified, and whether it is read only. The creation and modification times are given as the number of milliseconds since the UNIX epoch. This may be given to [`os.date`](https://tweaked.cc/module/os.html#v:date) in order to convert it to more usable form. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to get attributes for. ### Returns 1. { size = `number`, isDir = `boolean`, isReadOnly = `boolean`, created = `number`, modified = `number` } The resulting attributes. ### Throws * If the path does not exist. ### See also * **[`getSize`](https://tweaked.cc/module/fs.html#v:getSize) ** If you only care about the file's size. * **[`isDir`](https://tweaked.cc/module/fs.html#v:isDir) ** If you only care whether a path is a directory or not. ### Changes * **New in version 1.87.0** * **Changed in version 1.91.0:** Renamed `modification` field to `modified`. * **Changed in version 1.95.2:** Added `isReadOnly` to attributes. ### Types ### [](https://tweaked.cc/module/fs.html#ty:ReadWriteHandle) ReadWriteHandle A file handle opened for reading and writing with [`fs.open`](https://tweaked.cc/module/fs.html#v:open) . [](https://tweaked.cc/module/fs.html#ty:ReadWriteHandle:read) ReadWriteHandle.read(\[count\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/ReadWriteHandle.java#L31) Read a number of bytes from this file. ### Parameters 1. count? `number` The number of bytes to read. This may be 0 to determine we are at the end of the file. When absent, a single byte will be read. ### Returns 1. nil If we are at the end of the file. #### Or 1. `number` The value of the byte read. This is returned if the file is opened in binary mode and `count` is absent #### Or 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The bytes read as a string. This is returned when the `count` is given. ### Throws * When trying to read a negative number of bytes. * If the file has been closed. ### Changes * **Changed in version 1.80pr1:** Now accepts an integer argument to read multiple bytes, returning a string instead of a number. [](https://tweaked.cc/module/fs.html#ty:ReadWriteHandle:readAll) ReadWriteHandle.readAll()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/ReadWriteHandle.java#L40) Read the remainder of the file. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The remaining contents of the file, or `nil` in the event of an error. ### Throws * If the file has been closed. ### Changes * **New in version 1.80pr1** * **Changed in version 1.109.0:** Binary-mode handles are now consistent with non-binary files, and return an empty string at the end of the file, rather than `nil`. [](https://tweaked.cc/module/fs.html#ty:ReadWriteHandle:readLine) ReadWriteHandle.readLine(\[withTrailing\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/ReadWriteHandle.java#L49) Read a line from the file. ### Parameters 1. withTrailing? `boolean` Whether to include the newline characters with the returned string. Defaults to `false`. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The read line or `nil` if at the end of the file. ### Throws * If the file has been closed. ### Changes * **New in version 1.80pr1.9** * **Changed in version 1.81.0:** `\r` is now stripped. [](https://tweaked.cc/module/fs.html#ty:ReadWriteHandle:seek) ReadWriteHandle.seek(\[whence \[, offset\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/ReadWriteHandle.java#L58) Seek to a new position within the file, changing where bytes are written to. The new position is an offset given by `offset`, relative to a start position determined by `whence`: * `"set"`: `offset` is relative to the beginning of the file. * `"cur"`: Relative to the current position. This is the default. * `"end"`: Relative to the end of the file. In case of success, `seek` returns the new file position from the beginning of the file. ### Parameters 1. whence? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Where the offset is relative to. 2. offset? `number` The offset to seek to. ### Returns 1. `number` The new position. #### Or 1. nil If seeking failed. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The reason seeking failed. ### Throws * If the file has been closed. ### Changes * **New in version 1.80pr1.9** * **Changed in version 1.109.0:** Now available on all file handles, not just binary-mode handles. [](https://tweaked.cc/module/fs.html#ty:ReadWriteHandle:write) ReadWriteHandle.write(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/ReadWriteHandle.java#L67) Write a string or byte to the file. ### Parameters 1. contents [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The string to write. #### Or 1. charcode `number` The byte to write, if the file was opened in binary mode. ### Throws * If the file has been closed. ### Changes * **Changed in version 1.80pr1:** Now accepts a string to write multiple bytes. [](https://tweaked.cc/module/fs.html#ty:ReadWriteHandle:writeLine) ReadWriteHandle.writeLine(text)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/ReadWriteHandle.java#L76) Write a string of characters to the file, following them with a new line character. ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The text to write to the file. ### Throws * If the file has been closed. [](https://tweaked.cc/module/fs.html#ty:ReadWriteHandle:flush) ReadWriteHandle.flush()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/ReadWriteHandle.java#L85) Save the current file without closing it. ### Throws * If the file has been closed. [](https://tweaked.cc/module/fs.html#ty:ReadWriteHandle:close) ReadWriteHandle.close()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/AbstractHandle.java#L54) Close this file, freeing any resources it uses. Once a file is closed it may no longer be read or written to. ### Throws * If the file has already been closed. ### [](https://tweaked.cc/module/fs.html#ty:WriteHandle) WriteHandle A file handle opened for writing by [`fs.open`](https://tweaked.cc/module/fs.html#v:open) . [](https://tweaked.cc/module/fs.html#ty:WriteHandle:write) WriteHandle.write(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/WriteHandle.java#L35) Write a string or byte to the file. ### Parameters 1. contents [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The string to write. #### Or 1. charcode `number` The byte to write, if the file was opened in binary mode. ### Throws * If the file has been closed. ### Changes * **Changed in version 1.80pr1:** Now accepts a string to write multiple bytes. [](https://tweaked.cc/module/fs.html#ty:WriteHandle:writeLine) WriteHandle.writeLine(text)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/WriteHandle.java#L44) Write a string of characters to the file, following them with a new line character. ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The text to write to the file. ### Throws * If the file has been closed. [](https://tweaked.cc/module/fs.html#ty:WriteHandle:flush) WriteHandle.flush()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/WriteHandle.java#L53) Save the current file without closing it. ### Throws * If the file has been closed. [](https://tweaked.cc/module/fs.html#ty:WriteHandle:seek) WriteHandle.seek(\[whence \[, offset\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/WriteHandle.java#L67) Seek to a new position within the file, changing where bytes are written to. The new position is an offset given by `offset`, relative to a start position determined by `whence`: * `"set"`: `offset` is relative to the beginning of the file. * `"cur"`: Relative to the current position. This is the default. * `"end"`: Relative to the end of the file. In case of success, `seek` returns the new file position from the beginning of the file. ### Parameters 1. whence? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Where the offset is relative to. 2. offset? `number` The offset to seek to. ### Returns 1. `number` The new position. #### Or 1. nil If seeking failed. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The reason seeking failed. ### Throws * If the file has been closed. ### Changes * **New in version 1.80pr1.9** * **Changed in version 1.109.0:** Now available on all file handles, not just binary-mode handles. [](https://tweaked.cc/module/fs.html#ty:WriteHandle:close) WriteHandle.close()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/AbstractHandle.java#L54) Close this file, freeing any resources it uses. Once a file is closed it may no longer be read or written to. ### Throws * If the file has already been closed. ### [](https://tweaked.cc/module/fs.html#ty:ReadHandle) ReadHandle A file handle opened for reading with [`fs.open`](https://tweaked.cc/module/fs.html#v:open) . [](https://tweaked.cc/module/fs.html#ty:ReadHandle:read) ReadHandle.read(\[count\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/ReadHandle.java#L32) Read a number of bytes from this file. ### Parameters 1. count? `number` The number of bytes to read. This may be 0 to determine we are at the end of the file. When absent, a single byte will be read. ### Returns 1. nil If we are at the end of the file. #### Or 1. `number` The value of the byte read. This is returned if the file is opened in binary mode and `count` is absent #### Or 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The bytes read as a string. This is returned when the `count` is given. ### Throws * When trying to read a negative number of bytes. * If the file has been closed. ### Changes * **Changed in version 1.80pr1:** Now accepts an integer argument to read multiple bytes, returning a string instead of a number. [](https://tweaked.cc/module/fs.html#ty:ReadHandle:readAll) ReadHandle.readAll()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/ReadHandle.java#L41) Read the remainder of the file. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The remaining contents of the file, or `nil` in the event of an error. ### Throws * If the file has been closed. ### Changes * **New in version 1.80pr1** * **Changed in version 1.109.0:** Binary-mode handles are now consistent with non-binary files, and return an empty string at the end of the file, rather than `nil`. [](https://tweaked.cc/module/fs.html#ty:ReadHandle:readLine) ReadHandle.readLine(\[withTrailing\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/ReadHandle.java#L50) Read a line from the file. ### Parameters 1. withTrailing? `boolean` Whether to include the newline characters with the returned string. Defaults to `false`. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The read line or `nil` if at the end of the file. ### Throws * If the file has been closed. ### Changes * **New in version 1.80pr1.9** * **Changed in version 1.81.0:** `\r` is now stripped. [](https://tweaked.cc/module/fs.html#ty:ReadHandle:seek) ReadHandle.seek(\[whence \[, offset\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/ReadHandle.java#L59) Seek to a new position within the file, changing where bytes are written to. The new position is an offset given by `offset`, relative to a start position determined by `whence`: * `"set"`: `offset` is relative to the beginning of the file. * `"cur"`: Relative to the current position. This is the default. * `"end"`: Relative to the end of the file. In case of success, `seek` returns the new file position from the beginning of the file. ### Parameters 1. whence? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Where the offset is relative to. 2. offset? `number` The offset to seek to. ### Returns 1. `number` The new position. #### Or 1. nil If seeking failed. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The reason seeking failed. ### Throws * If the file has been closed. ### Changes * **New in version 1.80pr1.9** * **Changed in version 1.109.0:** Now available on all file handles, not just binary-mode handles. [](https://tweaked.cc/module/fs.html#ty:ReadHandle:close) ReadHandle.close()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/handles/AbstractHandle.java#L54) Close this file, freeing any resources it uses. Once a file is closed it may no longer be read or written to. ### Throws * If the file has already been closed. --- # help help ==== Find help files on the current computer. ### Changes * **New in version 1.2** | | | | --- | --- | | [path()](https://tweaked.cc/module/help.html#v:path) | Returns a colon-separated list of directories where help files are searched for. | | [setPath(newPath)](https://tweaked.cc/module/help.html#v:setPath) | Sets the colon-separated list of directories where help files are searched for to `newPath` | | [lookup(topic)](https://tweaked.cc/module/help.html#v:lookup) | Returns the location of the help file for the given topic. | | [topics()](https://tweaked.cc/module/help.html#v:topics) | Returns a list of topics that can be looked up and/or displayed. | | [completeTopic(prefix)](https://tweaked.cc/module/help.html#v:completeTopic) | Returns a list of topic endings that match the prefix. | [](https://tweaked.cc/module/help.html#v:path) path()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/help.lua#L19) Returns a colon-separated list of directories where help files are searched for. All directories are absolute. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The current help search path, separated by colons. ### See also * **[`help.setPath`](https://tweaked.cc/module/help.html#v:setPath) ** [](https://tweaked.cc/module/help.html#v:setPath) setPath(newPath)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/help.lua#L30) Sets the colon-separated list of directories where help files are searched for to `newPath` ### Parameters 1. newPath [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The new path to use. ### Usage * Run ᐅ [help.setPath](https://tweaked.cc/module/help.html#v:setPath "Sets the colon-separated list of directories where help files are searched for to newPath") ( "/disk/help/" ) * Run ᐅ [help.setPath](https://tweaked.cc/module/help.html#v:setPath "Sets the colon-separated list of directories where help files are searched for to newPath") ( [help.path](https://tweaked.cc/module/help.html#v:path "Returns a colon-separated list of directories where help files are searched for.") () .. ":/myfolder/help/" ) ### See also * **[`help.path`](https://tweaked.cc/module/help.html#v:path) ** [](https://tweaked.cc/module/help.html#v:lookup) lookup(topic)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/help.lua#L45) Returns the location of the help file for the given topic. ### Parameters 1. topic [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The topic to find ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The path to the given topic's help file, or `nil` if it cannot be found. ### Usage * Run ᐅ [help.lookup](https://tweaked.cc/module/help.html#v:lookup "Returns the location of the help file for the given topic.") ("disk") ### Changes * **Changed in version 1.80pr1:** Now supports finding .txt files. * **Changed in version 1.97.0:** Now supports finding Markdown files. [](https://tweaked.cc/module/help.html#v:topics) topics()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/help.lua#L66) Returns a list of topics that can be looked up and/or displayed. ### Returns 1. [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) A list of topics in alphabetical order. ### Usage * Run ᐅ [help.topics](https://tweaked.cc/module/help.html#v:topics "Returns a list of topics that can be looked up and/or displayed.") () [](https://tweaked.cc/module/help.html#v:completeTopic) completeTopic(prefix)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/help.lua#L107) Returns a list of topic endings that match the prefix. Can be used with `read` to allow input of a help topic. ### Parameters 1. prefix [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The prefix to match ### Returns 1. [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) A list of matching topics. ### Changes * **New in version 1.74** --- # http http ==== Make HTTP requests, sending and receiving data to a remote web server. ### See also * **[`Allowing access to local IPs`](https://tweaked.cc/guide/local_ips.html) ** To allow accessing servers running on your local network. ### Changes * **New in version 1.1** | | | | --- | --- | | [get(...)](https://tweaked.cc/module/http.html#v:get) | Make a HTTP GET request to the given url. | | [post(...)](https://tweaked.cc/module/http.html#v:post) | Make a HTTP POST request to the given url. | | [request(...)](https://tweaked.cc/module/http.html#v:request) | Asynchronously make a HTTP request to the given url. | | [checkURLAsync(url)](https://tweaked.cc/module/http.html#v:checkURLAsync) | Asynchronously determine whether a URL can be requested. | | [checkURL(url)](https://tweaked.cc/module/http.html#v:checkURL) | Determine whether a URL can be requested. | | [websocketAsync(...)](https://tweaked.cc/module/http.html#v:websocketAsync) | Asynchronously open a websocket. | | [websocket(...)](https://tweaked.cc/module/http.html#v:websocket) | Open a websocket. | [](https://tweaked.cc/module/http.html#v:get) get(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/http/http.lua#L104) Make a HTTP GET request to the given url. ### Parameters 1. url [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The url to request 2. headers? { \[[`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ \] = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) } Additional headers to send as part of this request. 3. binary? `boolean` = Whether the [response handle](https://tweaked.cc/module/fs.html#ty:ReadHandle) should be opened in binary mode. #### Or 1. request { url = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) , headers? = { \[[`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ \] = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) }, binary? = `boolean`, method? = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) , redirect? = `boolean`, timeout? = `number` } Options for the request. See [`http.request`](https://tweaked.cc/module/http.html#v:request) for details on how these options behave. ### Returns 1. [`Response`](https://tweaked.cc/module/http.html#ty:Response) The resulting http response, which can be read from. #### Or 1. nil When the http request failed, such as in the event of a 404 error or connection timeout. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) A message detailing why the request failed. 3. [`Response`](https://tweaked.cc/module/http.html#ty:Response) | nil The failing http response, if available. ### Usage * Make a request to [example.tweaked.cc](https://example.tweaked.cc/) , and print the returned page. Run ᐅ local request \= [http.get](https://tweaked.cc/module/http.html#v:get "Make a HTTP GET request to the given url.") ("https://example.tweaked.cc") print(request.readAll()) \-- => HTTP is working! request.close() ### Changes * **Changed in version 1.63:** Added argument for headers. * **Changed in version 1.80pr1:** Response handles are now returned on error if available. * **Changed in version 1.80pr1:** Added argument for binary handles. * **Changed in version 1.80pr1.6:** Added support for table argument. * **Changed in version 1.86.0:** Added PATCH and TRACE methods. * **Changed in version 1.105.0:** Added support for custom timeouts. * **Changed in version 1.109.0:** The returned response now reads the body as raw bytes, rather than decoding from UTF-8. [](https://tweaked.cc/module/http.html#v:post) post(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/http/http.lua#L148) Make a HTTP POST request to the given url. ### Parameters 1. url [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The url to request 2. body [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The body of the POST request. 3. headers? { \[[`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ \] = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) } Additional headers to send as part of this request. 4. binary? `boolean` = Whether the [response handle](https://tweaked.cc/module/fs.html#ty:ReadHandle) should be opened in binary mode. #### Or 1. request { url = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) , body? = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) , headers? = { \[[`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ \] = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) }, binary? = `boolean`, method? = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) , redirect? = `boolean`, timeout? = `number` } Options for the request. See [`http.request`](https://tweaked.cc/module/http.html#v:request) for details on how these options behave. ### Returns 1. [`Response`](https://tweaked.cc/module/http.html#ty:Response) The resulting http response, which can be read from. #### Or 1. nil When the http request failed, such as in the event of a 404 error or connection timeout. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) A message detailing why the request failed. 3. [`Response`](https://tweaked.cc/module/http.html#ty:Response) | nil The failing http response, if available. ### Changes * **New in version 1.31** * **Changed in version 1.63:** Added argument for headers. * **Changed in version 1.80pr1:** Response handles are now returned on error if available. * **Changed in version 1.80pr1:** Added argument for binary handles. * **Changed in version 1.80pr1.6:** Added support for table argument. * **Changed in version 1.86.0:** Added PATCH and TRACE methods. * **Changed in version 1.105.0:** Added support for custom timeouts. * **Changed in version 1.109.0:** The returned response now reads the body as raw bytes, rather than decoding from UTF-8. [](https://tweaked.cc/module/http.html#v:request) request(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/http/http.lua#L201) Asynchronously make a HTTP request to the given url. This returns immediately, a [`http_success`](https://tweaked.cc/event/http_success.html) or [`http_failure`](https://tweaked.cc/event/http_failure.html) will be queued once the request has completed. ### Parameters 1. url [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The url to request 2. body? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) An optional string containing the body of the request. If specified, a `POST` request will be made instead. 3. headers? { \[[`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ \] = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) } Additional headers to send as part of this request. 4. binary? `boolean` = Whether the [response handle](https://tweaked.cc/module/fs.html#ty:ReadHandle) should be opened in binary mode. #### Or 1. request { url = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) , body? = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) , headers? = { \[[`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ \] = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) }, binary? = `boolean`, method? = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) , redirect? = `boolean`, timeout? = `number` } Options for the request. This table form is an expanded version of the previous syntax. All arguments from above are passed in as fields instead (for instance, `http.request("https://example.com")` becomes `http.request { url = "https://example.com" }`). This table also accepts several additional options: * `method`: Which HTTP method to use, for instance `"PATCH"` or `"DELETE"`. * `redirect`: Whether to follow HTTP redirects. Defaults to true. * `timeout`: The connection timeout, in seconds. ### See also * **[`http.get`](https://tweaked.cc/module/http.html#v:get) ** For a synchronous way to make GET requests. * **[`http.post`](https://tweaked.cc/module/http.html#v:post) ** For a synchronous way to make POST requests. ### Changes * **Changed in version 1.63:** Added argument for headers. * **Changed in version 1.80pr1:** Added argument for binary handles. * **Changed in version 1.80pr1.6:** Added support for table argument. * **Changed in version 1.86.0:** Added PATCH and TRACE methods. * **Changed in version 1.105.0:** Added support for custom timeouts. * **Changed in version 1.109.0:** The returned response now reads the body as raw bytes, rather than decoding from UTF-8. [](https://tweaked.cc/module/http.html#v:checkURLAsync) checkURLAsync(url)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/http/http.lua#L223) Asynchronously determine whether a URL can be requested. If this returns `true`, one should also listen for [`http_check`](https://tweaked.cc/event/http_check.html) which will container further information about whether the URL is allowed or not. ### Parameters 1. url [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The URL to check. ### Returns 1. true When this url is not invalid. This does not imply that it is allowed - see the comment above. #### Or 1. false When this url is invalid. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) A reason why this URL is not valid (for instance, if it is malformed, or blocked). ### See also * **[`http.checkURL`](https://tweaked.cc/module/http.html#v:checkURL) ** For a synchronous version. [](https://tweaked.cc/module/http.html#v:checkURL) checkURL(url)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/http/http.lua#L264) Determine whether a URL can be requested. If this returns `true`, one should also listen for [`http_check`](https://tweaked.cc/event/http_check.html) which will container further information about whether the URL is allowed or not. ### Parameters 1. url [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The URL to check. ### Returns 1. true When this url is valid and can be requested via [`http.request`](https://tweaked.cc/module/http.html#v:request) . #### Or 1. false When this url is invalid. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) A reason why this URL is not valid (for instance, if it is malformed, or blocked). ### Usage * Run ᐅ print([http.checkURL](https://tweaked.cc/module/http.html#v:checkURL "Determine whether a URL can be requested.") ("https://example.tweaked.cc/")) \-- => true print([http.checkURL](https://tweaked.cc/module/http.html#v:checkURL "Determine whether a URL can be requested.") ("http://localhost/")) \-- => false Domain not permitted print([http.checkURL](https://tweaked.cc/module/http.html#v:checkURL "Determine whether a URL can be requested.") ("not a url")) \-- => false URL malformed ### See also * **[`http.checkURLAsync`](https://tweaked.cc/module/http.html#v:checkURLAsync) ** For an asynchronous version. [](https://tweaked.cc/module/http.html#v:websocketAsync) websocketAsync(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/http/http.lua#L307) Asynchronously open a websocket. This returns immediately, a [`websocket_success`](https://tweaked.cc/event/websocket_success.html) or [`websocket_failure`](https://tweaked.cc/event/websocket_failure.html) will be queued once the request has completed. ### Parameters 1. url [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The websocket url to connect to. This should have the `ws://` or `wss://` protocol. 2. headers? { \[[`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ \] = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) } Additional headers to send as part of the initial websocket connection. #### Or 1. request { url = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) , headers? = { \[[`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ \] = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) }, timeout? = `number` } Options for the websocket. See [`http.websocket`](https://tweaked.cc/module/http.html#v:websocket) for details on how these options behave. ### See also * **[`websocket_success`](https://tweaked.cc/event/websocket_success.html) ** * **[`websocket_failure`](https://tweaked.cc/event/websocket_failure.html) ** ### Changes * **New in version 1.80pr1.3** * **Changed in version 1.95.3:** Added User-Agent to default headers. * **Changed in version 1.105.0:** Added support for table argument and custom timeout. * **Changed in version 1.109.0:** Non-binary websocket messages now use the raw bytes rather than using UTF-8. [](https://tweaked.cc/module/http.html#v:websocket) websocket(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/http/http.lua#L365) Open a websocket. ### Parameters 1. url [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The websocket url to connect to. This should have the `ws://` or `wss://` protocol. 2. headers? { \[[`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ \] = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) } Additional headers to send as part of the initial websocket connection. #### Or 1. request { url = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) , headers? = { \[[`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ \] = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) }, timeout? = `number` } Options for the websocket. This table form is an expanded version of the previous syntax. All arguments from above are passed in as fields instead (for instance, `http.websocket("https://example.com")` becomes `http.websocket { url = "https://example.com" }`). This table also accepts the following additional options: * `timeout`: The connection timeout, in seconds. ### Returns 1. [`Websocket`](https://tweaked.cc/module/http.html#ty:Websocket) The websocket connection. #### Or 1. false If the websocket connection failed. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) An error message describing why the connection failed. ### Usage * Connect to an echo websocket and send a message. Run ᐅ local ws \= assert([http.websocket](https://tweaked.cc/module/http.html#v:websocket "Open a websocket.") ("wss://example.tweaked.cc/echo")) ws.send("Hello!") \-- Send a message print(ws.receive()) \-- And receive the reply ws.close() ### Changes * **New in version 1.80pr1.1** * **Changed in version 1.80pr1.3:** No longer asynchronous. * **Changed in version 1.95.3:** Added User-Agent to default headers. * **Changed in version 1.105.0:** Added support for table argument and custom timeout. * **Changed in version 1.109.0:** Non-binary websocket messages now use the raw bytes rather than using UTF-8. ### Types ### [](https://tweaked.cc/module/http.html#ty:Response) Response A http response. This provides the same methods as a [file](https://tweaked.cc/module/fs.html#ty:ReadHandle) , though provides several request specific methods. ### See also * **[`http.request`](https://tweaked.cc/module/http.html#v:request) ** On how to make a http request. [](https://tweaked.cc/module/http.html#ty:Response:getResponseCode) Response.getResponseCode()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/http/request/HttpResponseHandle.java#L45) Returns the response code and response message returned by the server. ### Returns 1. `number` The response code (i.e. 200) 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The response message (i.e. "OK") ### Changes * **Changed in version 1.80pr1.13:** Added response message return value. [](https://tweaked.cc/module/http.html#ty:Response:getResponseHeaders) Response.getResponseHeaders()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/http/request/HttpResponseHandle.java#L68) Get a table containing the response's headers, in a format similar to that required by [`http.request`](https://tweaked.cc/module/http.html#v:request) . If multiple headers are sent with the same name, they will be combined with a comma. ### Returns 1. { \[[`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ \] = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) } The response's headers. ### Usage * Make a request to [example.tweaked.cc](https://example.tweaked.cc/) , and print the returned headers. Run ᐅ local request \= [http.get](https://tweaked.cc/module/http.html#v:get "Make a HTTP GET request to the given url.") ("https://example.tweaked.cc") print([textutils.serialize](https://tweaked.cc/module/textutils.html#v:serialize "Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing.") (request.getResponseHeaders())) \-- => { \-- \[ "Content-Type" \] = "text/plain; charset=utf8", \-- \[ "content-length" \] = 17, \-- ... \-- } request.close() ### [](https://tweaked.cc/module/http.html#ty:Websocket) Websocket A websocket, which can be used to send and receive messages with a web server. ### See also * **[`http.websocket`](https://tweaked.cc/module/http.html#v:websocket) ** On how to open a websocket. [](https://tweaked.cc/module/http.html#ty:Websocket:receive) Websocket.receive(\[timeout\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/http/websocket/WebsocketHandle.java#L66) Wait for a message from the server. ### Parameters 1. timeout? `number` The number of seconds to wait if no message is received. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The received message. 2. `boolean` If this was a binary message. #### Or 1. nil If the websocket was closed while waiting, or if we timed out. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The reason we failed to receive a message. Either the reason the websocket was closed (as returned by [`websocket_closed`](https://tweaked.cc/event/websocket_closed.html) , or the string `"Timed out"`. ### Throws * If the websocket has been closed. ### Changes * **Changed in version 1.80pr1.13:** Added return value indicating whether the message was binary. * **Changed in version 1.87.0:** Added timeout argument. * **Changed in version 1.117.0:** Added return value indicating why receiving the message failed. [](https://tweaked.cc/module/http.html#ty:Websocket:send) Websocket.send(message \[, binary\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/http/websocket/WebsocketHandle.java#L85) Send a websocket message to the connected server. ### Parameters 1. message [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The message to send. 2. binary? `boolean` Whether this message should be treated as a binary message. ### Throws * If the message is too large. * If the websocket has been closed. ### Changes * **Changed in version 1.81.0:** Added argument for binary mode. [](https://tweaked.cc/module/http.html#ty:Websocket:close) Websocket.close()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/http/websocket/WebsocketHandle.java#L110) Close this websocket. This will terminate the connection, meaning messages can no longer be sent or received along it. [](https://tweaked.cc/module/http.html#ty:Websocket:getResponseHeaders) Websocket.getResponseHeaders()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/http/websocket/WebsocketHandle.java#L134) Get a table containing the headers from the handshake response, in a format similar to that required by [`http.request`](https://tweaked.cc/module/http.html#v:request) . If multiple headers are sent with the same name, they will be combined with a comma. ### Returns 1. { \[[`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ \] = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) } The response's headers. ### Usage * Make a websocket connection to [example.tweaked.cc](https://example.tweaked.cc/) , and print the returned headers. Run ᐅ local ws \= [http.websocket](https://tweaked.cc/module/http.html#v:websocket "Open a websocket.") ("wss://example.tweaked.cc/echo") print([textutils.serialize](https://tweaked.cc/module/textutils.html#v:serialize "Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing.") (ws.getResponseHeaders())) \-- => { \-- Connection = "Upgrade", \-- Upgrade = "websocket", \-- ... \-- } ws.close() ### Changes * **New in version 1.117.0** --- # io io == Emulates Lua's standard [io library](https://www.lua.org/manual/5.1/manual.html#5.7) . | | | | --- | --- | | [stdin](https://tweaked.cc/module/io.html#v:stdin) | A file handle representing the "standard input". | | [stdout](https://tweaked.cc/module/io.html#v:stdout) | A file handle representing the "standard output". | | [stderr](https://tweaked.cc/module/io.html#v:stderr) | A file handle representing the "standard error" stream. | | [close(\[file\])](https://tweaked.cc/module/io.html#v:close) | Closes the provided file handle. | | [flush()](https://tweaked.cc/module/io.html#v:flush) | Flushes the current output file. | | [input(\[file\])](https://tweaked.cc/module/io.html#v:input) | Get or set the current input file. | | [lines(\[filename, ...\])](https://tweaked.cc/module/io.html#v:lines) | Opens the given file name in read mode and returns an iterator that, each time it is called, returns a new line from the file. | | [open(filename \[, mode\])](https://tweaked.cc/module/io.html#v:open) | Open a file with the given mode, either returning a new file handle or `nil`, plus an error message. | | [output(\[file\])](https://tweaked.cc/module/io.html#v:output) | Get or set the current output file. | | [read(...)](https://tweaked.cc/module/io.html#v:read) | Read from the currently opened input file. | | [type(obj)](https://tweaked.cc/module/io.html#v:type) | Checks whether `handle` is a given file handle, and determine if it is open or not. | | [write(...)](https://tweaked.cc/module/io.html#v:write) | Write to the currently opened output file. | [](https://tweaked.cc/module/io.html#v:stdin) stdin[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L243) A file handle representing the "standard input". Reading from this file will prompt the user for input. [](https://tweaked.cc/module/io.html#v:stdout) stdout[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L245) A file handle representing the "standard output". Writing to this file will display the written text to the screen. [](https://tweaked.cc/module/io.html#v:stderr) stderr[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L247) A file handle representing the "standard error" stream. One may use this to display error messages, writing to it will display them on the terminal. [](https://tweaked.cc/module/io.html#v:close) close(\[file\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L284) Closes the provided file handle. ### Parameters 1. file? [`Handle`](https://tweaked.cc/module/io.html#ty:Handle) The file handle to close, defaults to the current output file. ### See also * **[`Handle:close`](https://tweaked.cc/module/io.html#ty:Handle:close) ** * **[`io.output`](https://tweaked.cc/module/io.html#v:output) ** ### Changes * **New in version 1.55** [](https://tweaked.cc/module/io.html#v:flush) flush()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L298) Flushes the current output file. ### See also * **[`Handle:flush`](https://tweaked.cc/module/io.html#ty:Handle:flush) ** * **[`io.output`](https://tweaked.cc/module/io.html#v:output) ** ### Changes * **New in version 1.55** [](https://tweaked.cc/module/io.html#v:input) input(\[file\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L308) Get or set the current input file. ### Parameters 1. file? [`Handle`](https://tweaked.cc/module/io.html#ty:Handle) | [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The new input file, either as a file path or pre-existing handle. ### Returns 1. [`Handle`](https://tweaked.cc/module/io.html#ty:Handle) The current input file. ### Throws * If the provided filename cannot be opened for reading. ### Changes * **New in version 1.55** [](https://tweaked.cc/module/io.html#v:lines) lines(\[filename, ...\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L349) Opens the given file name in read mode and returns an iterator that, each time it is called, returns a new line from the file. This can be used in a for loop to iterate over all lines of a file Once the end of the file has been reached, `nil` will be returned. The file is automatically closed. If no file name is given, the [current input](https://tweaked.cc/module/io.html#v:input) will be used instead. In this case, the handle is not used. ### Parameters 1. filename? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the file to extract lines from 2. ... The argument to pass to [`Handle:read`](https://tweaked.cc/module/io.html#ty:Handle:read) for each line. ### Returns 1. function():[`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The line iterator. ### Throws * If the file cannot be opened for reading ### Usage * Iterate over every line in a file and print it out. Run ᐅ for line in [io.lines](https://tweaked.cc/module/io.html#v:lines "Opens the given file name in read mode and returns an iterator that, each time it is called, returns a new line from the file.") ("/rom/help/intro.txt") do print(line) end ### See also * **[`Handle:lines`](https://tweaked.cc/module/io.html#ty:Handle:lines) ** * **[`io.input`](https://tweaked.cc/module/io.html#v:input) ** ### Changes * **New in version 1.55** [](https://tweaked.cc/module/io.html#v:open) open(filename \[, mode\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L383) Open a file with the given mode, either returning a new file handle or `nil`, plus an error message. The `mode` string can be any of the following: * **"r"**: Read mode. * **"w"**: Write mode. * **"a"**: Append mode. * **"r+"**: Update mode (allows reading and writing), all data is preserved. * **"w+"**: Update mode, all data is erased. The mode may also have a `b` at the end, which opens the file in "binary mode". This has no impact on functionality. ### Parameters 1. filename [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the file to open. 2. mode? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The mode to open the file with. This defaults to `r`. ### Returns 1. [`Handle`](https://tweaked.cc/module/io.html#ty:Handle) The opened file. #### Or 1. nil In case of an error. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The reason the file could not be opened. ### Changes * **Changed in version 1.111.0:** Add support for `r+` and `w+`. [](https://tweaked.cc/module/io.html#v:output) output(\[file\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L399) Get or set the current output file. ### Parameters 1. file? [`Handle`](https://tweaked.cc/module/io.html#ty:Handle) | [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The new output file, either as a file path or pre-existing handle. ### Returns 1. [`Handle`](https://tweaked.cc/module/io.html#ty:Handle) The current output file. ### Throws * If the provided filename cannot be opened for writing. ### Changes * **New in version 1.55** [](https://tweaked.cc/module/io.html#v:read) read(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L420) Read from the currently opened input file. This is equivalent to `io.input():read(...)`. See [the documentation](https://tweaked.cc/module/io.html#ty:Handle:read) there for full details. ### Parameters 1. ... [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The formats to read, defaulting to a whole line. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil... The data read, or `nil` if nothing can be read. [](https://tweaked.cc/module/io.html#v:type) type(obj)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L430) Checks whether `handle` is a given file handle, and determine if it is open or not. ### Parameters 1. obj The value to check ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil `"file"` if this is an open file, `"closed file"` if it is a closed file handle, or `nil` if not a file handle. [](https://tweaked.cc/module/io.html#v:write) write(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L448) Write to the currently opened output file. This is equivalent to `io.output():write(...)`. See [the documentation](https://tweaked.cc/module/io.html#ty:Handle:write) there for full details. ### Parameters 1. ... [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The strings to write ### Changes * **Changed in version 1.81.0:** Multiple arguments are now allowed. ### Types ### [](https://tweaked.cc/module/io.html#ty:Handle) Handle A file handle which can be read or written to. [](https://tweaked.cc/module/io.html#ty:Handle:close) Handle.close()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L42) Close this file handle, freeing any resources it uses. ### Returns 1. true If this handle was successfully closed. #### Or 1. nil If this file handle could not be closed. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The reason it could not be closed. ### Throws * If this handle was already closed. [](https://tweaked.cc/module/io.html#ty:Handle:flush) Handle.flush()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L61) Flush any buffered output, forcing it to be written to the file ### Throws * If the handle has been closed [](https://tweaked.cc/module/io.html#ty:Handle:lines) Handle.lines(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L96) Returns an iterator that, each time it is called, returns a new line from the file. This can be used in a for loop to iterate over all lines of a file Once the end of the file has been reached, `nil` will be returned. The file is _not_ automatically closed. ### Parameters 1. ... The argument to pass to [`Handle:read`](https://tweaked.cc/module/io.html#ty:Handle:read) for each line. ### Returns 1. function():[`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The line iterator. ### Throws * If the file cannot be opened for reading ### Usage * Iterate over every line in a file and print it out. Run ᐅ local file \= [io.open](https://tweaked.cc/module/io.html#v:open "Open a file with the given mode, either returning a new file handle or nil, plus an error message.") ("/rom/help/intro.txt") for line in file:lines() do print(line) end file:close() ### See also * **[`io.lines`](https://tweaked.cc/module/io.html#v:lines) ** ### Changes * **New in version 1.3** [](https://tweaked.cc/module/io.html#ty:Handle:read) Handle.read(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L129) Reads data from the file, using the specified formats. For each format provided, the function returns either the data read, or `nil` if no data could be read. The following formats are available: * `l`: Returns the next line (without a newline on the end). * `L`: Returns the next line (with a newline on the end). * `a`: Returns the entire rest of the file. * ~`n`: Returns a number~ (not implemented in CC). These formats can be preceded by a `*` to make it compatible with Lua 5.1. If no format is provided, `l` is assumed. ### Parameters 1. ... The formats to use. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil... The data read from the file. [](https://tweaked.cc/module/io.html#ty:Handle:seek) Handle.seek(\[whence \[, offset\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L189) Seeks the file cursor to the specified position, and returns the new position. `whence` controls where the seek operation starts, and is a string that may be one of these three values: * `set`: base position is 0 (beginning of the file) * `cur`: base is current position * `end`: base is end of file The default value of `whence` is `cur`, and the default value of `offset` is 0. This means that `file:seek()` without arguments returns the current position without moving. ### Parameters 1. whence? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The place to set the cursor from. 2. offset? `number` The offset from the start to move to. ### Returns 1. `number` The new location of the file cursor. [](https://tweaked.cc/module/io.html#ty:Handle:setvbuf) Handle.setvbuf(mode \[, size\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L211) ##### 🛈 Deprecated This has no effect in CC. Sets the buffering mode for an output file. This has no effect under ComputerCraft, and exists with compatility with base Lua. ### Parameters 1. mode [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The buffering mode. 2. size? `number` The size of the buffer. ### See also * **[`file:setvbuf`](https://www.lua.org/manual/5.1/manual.html#pdf-file:setvbuf) ** Lua's documentation for `setvbuf`. [](https://tweaked.cc/module/io.html#ty:Handle:write) Handle.write(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua#L220) Write one or more values to the file ### Parameters 1. ... [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | `number` The values to write. ### Returns 1. [`Handle`](https://tweaked.cc/module/io.html#ty:Handle) The current file, allowing chained calls. #### Or 1. nil If the file could not be written to. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The error message which occurred while writing. ### Changes * **Changed in version 1.81.0:** Multiple arguments are now allowed. --- # keys keys ==== Constants for all keyboard "key codes", as queued by the [`key`](https://tweaked.cc/event/key.html) event. These values are not guaranteed to remain the same between versions. It is recommended that you use the constants provided by this file, rather than the underlying numerical values. ### Changes * **New in version 1.4** | | | | --- | --- | | [getName(code)](https://tweaked.cc/module/keys.html#v:getName) | Translates a numerical key code to a human-readable name. | [](https://tweaked.cc/module/keys.html#v:getName) getName(code)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/keys.lua#L153) Translates a numerical key code to a human-readable name. The human-readable name is one of the constants in the keys API. ### Parameters 1. code `number` The key code to look up. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The name of the key, or `nil` if not a valid key code. ### Usage * Run ᐅ [keys.getName](https://tweaked.cc/module/keys.html#v:getName "Translates a numerical key code to a human-readable name.") ([keys](https://tweaked.cc/module/keys.html "Constants for all keyboard "key codes", as queued by the key event.") .enter) --- # multishell multishell ========== Multishell allows multiple programs to be run at the same time. When multiple programs are running, it displays a tab bar at the top of the screen, which allows you to switch between programs. New programs can be launched using the `fg` or `bg` programs, or using the [`shell.openTab`](https://tweaked.cc/module/shell.html#v:openTab) and [`multishell.launch`](https://tweaked.cc/module/multishell.html#v:launch) functions. Each process is identified by its ID, which corresponds to its position in the tab list. As tabs may be opened and closed, this ID is _not_ constant over a program's run. As such, be careful not to use stale IDs. As with [`shell`](https://tweaked.cc/module/shell.html) , [`multishell`](https://tweaked.cc/module/multishell.html) is not a "true" API. Instead, it is a standard program, which launches a shell and injects its API into the shell's environment. This API is not available in the global environment, and so is not available to [APIs](https://tweaked.cc/module/os.html#v:loadAPI) . ### Changes * **New in version 1.6** | | | | --- | --- | | [getFocus()](https://tweaked.cc/module/multishell.html#v:getFocus) | Get the currently visible process. | | [setFocus(n)](https://tweaked.cc/module/multishell.html#v:setFocus) | Change the currently visible process. | | [getTitle(n)](https://tweaked.cc/module/multishell.html#v:getTitle) | Get the title of the given tab. | | [setTitle(n, title)](https://tweaked.cc/module/multishell.html#v:setTitle) | Set the title of the given process. | | [getCurrent()](https://tweaked.cc/module/multishell.html#v:getCurrent) | Get the index of the currently running process. | | [launch(tProgramEnv, sProgramPath, ...)](https://tweaked.cc/module/multishell.html#v:launch) | Start a new process, with the given environment, program and arguments. | | [getCount()](https://tweaked.cc/module/multishell.html#v:getCount) | Get the number of processes within this multishell. | [](https://tweaked.cc/module/multishell.html#v:getFocus) getFocus()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/advanced/multishell.lua#L241) Get the currently visible process. This will be the one selected on the tab bar. Note, this is different to [`getCurrent`](https://tweaked.cc/module/multishell.html#v:getCurrent) , which returns the process which is currently executing. ### Returns 1. `number` The currently visible process's index. ### See also * **[`setFocus`](https://tweaked.cc/module/multishell.html#v:setFocus) ** [](https://tweaked.cc/module/multishell.html#v:setFocus) setFocus(n)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/advanced/multishell.lua#L251) Change the currently visible process. ### Parameters 1. n `number` The process index to switch to. ### Returns 1. `boolean` If the process was changed successfully. This will return `false` if there is no process with this id. ### See also * **[`getFocus`](https://tweaked.cc/module/multishell.html#v:getFocus) ** [](https://tweaked.cc/module/multishell.html#v:getTitle) getTitle(n)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/advanced/multishell.lua#L268) Get the title of the given tab. This starts as the name of the program, but may be changed using [`multishell.setTitle`](https://tweaked.cc/module/multishell.html#v:setTitle) . ### Parameters 1. n `number` The process index. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The current process title, or `nil` if the process doesn't exist. [](https://tweaked.cc/module/multishell.html#v:setTitle) setTitle(n, title)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/advanced/multishell.lua#L284) Set the title of the given process. ### Parameters 1. n `number` The process index. 2. title [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The new process title. ### Usage * Change the title of the current process Run ᐅ [multishell.setTitle](https://tweaked.cc/module/multishell.html#v:setTitle "Set the title of the given process.") ([multishell.getCurrent](https://tweaked.cc/module/multishell.html#v:getCurrent "Get the index of the currently running process.") (), "Hello") ### See also * **[`getTitle`](https://tweaked.cc/module/multishell.html#v:getTitle) ** [](https://tweaked.cc/module/multishell.html#v:getCurrent) getCurrent()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/advanced/multishell.lua#L296) Get the index of the currently running process. ### Returns 1. `number` The currently running process. [](https://tweaked.cc/module/multishell.html#v:launch) launch(tProgramEnv, sProgramPath, ...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/advanced/multishell.lua#L316) Start a new process, with the given environment, program and arguments. The returned process index is not constant over the program's run. It can be safely used immediately after launching (for instance, to update the title or switch to that tab). However, after your program has yielded, it may no longer be correct. ### Parameters 1. tProgramEnv [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The environment to load the path under. 2. sProgramPath [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to the program to run. 3. ... Additional arguments to pass to the program. ### Returns 1. `number` The index of the created process. ### Usage * Run the "hello" program, and set its title to "Hello!" Run ᐅ local id \= [multishell.launch](https://tweaked.cc/module/multishell.html#v:launch "Start a new process, with the given environment, program and arguments.") ({}, "/rom/programs/fun/hello.lua") [multishell.setTitle](https://tweaked.cc/module/multishell.html#v:setTitle "Set the title of the given process.") (id, "Hello!") ### See also * **[`os.run`](https://tweaked.cc/module/os.html#v:run) ** [](https://tweaked.cc/module/multishell.html#v:getCount) getCount()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/advanced/multishell.lua#L330) Get the number of processes within this multishell. ### Returns 1. `number` The number of processes. --- # os os == The [`os`](https://tweaked.cc/module/os.html) API allows interacting with the current computer. | | | | --- | --- | | [loadAPI(path)](https://tweaked.cc/module/os.html#v:loadAPI) | Loads the given API into the global environment. | | [unloadAPI(name)](https://tweaked.cc/module/os.html#v:unloadAPI) | Unloads an API which was loaded by [`os.loadAPI`](https://tweaked.cc/module/os.html#v:loadAPI)
. | | [pullEvent(\[filter\])](https://tweaked.cc/module/os.html#v:pullEvent) | Pause execution of the current thread and waits for any events matching `filter`. | | [pullEventRaw(\[filter\])](https://tweaked.cc/module/os.html#v:pullEventRaw) | Pause execution of the current thread and waits for events, including the `terminate` event. | | [sleep(\[time=0\])](https://tweaked.cc/module/os.html#v:sleep) | Pauses execution for the specified number of seconds, alias of [`_G.sleep`](https://tweaked.cc/module/_G.html#v:sleep)
. | | [version()](https://tweaked.cc/module/os.html#v:version) | Get the current CraftOS version (for example, `CraftOS 1.9`). | | [run(env, path, ...)](https://tweaked.cc/module/os.html#v:run) | Run the program at the given path with the specified environment and arguments. | | [queueEvent(name, ...)](https://tweaked.cc/module/os.html#v:queueEvent) | Adds an event to the event queue. | | [startTimer(time)](https://tweaked.cc/module/os.html#v:startTimer) | Starts a timer that will run for the specified number of seconds. | | [cancelTimer(token)](https://tweaked.cc/module/os.html#v:cancelTimer) | Cancels a timer previously started with [`startTimer`](https://tweaked.cc/module/os.html#v:startTimer)
. | | [setAlarm(time)](https://tweaked.cc/module/os.html#v:setAlarm) | Sets an alarm that will fire at the specified [in-game time](https://tweaked.cc/module/os.html#v:time)
. | | [cancelAlarm(token)](https://tweaked.cc/module/os.html#v:cancelAlarm) | Cancels an alarm previously started with setAlarm. | | [shutdown()](https://tweaked.cc/module/os.html#v:shutdown) | Shuts down the computer immediately. | | [reboot()](https://tweaked.cc/module/os.html#v:reboot) | Reboots the computer immediately. | | [getComputerID()](https://tweaked.cc/module/os.html#v:getComputerID) | Returns the ID of the computer. | | [computerID()](https://tweaked.cc/module/os.html#v:computerID) | Returns the ID of the computer. | | [getComputerLabel()](https://tweaked.cc/module/os.html#v:getComputerLabel) | Returns the label of the computer, or `nil` if none is set. | | [computerLabel()](https://tweaked.cc/module/os.html#v:computerLabel) | Returns the label of the computer, or `nil` if none is set. | | [setComputerLabel(\[label\])](https://tweaked.cc/module/os.html#v:setComputerLabel) | Set the label of this computer. | | [clock()](https://tweaked.cc/module/os.html#v:clock) | Returns the number of seconds that the computer has been running. | | [time(\[locale\])](https://tweaked.cc/module/os.html#v:time) | Returns the current time depending on the string passed in. | | [day(\[locale\])](https://tweaked.cc/module/os.html#v:day) | Returns the day depending on the locale specified. | | [epoch(\[locale\])](https://tweaked.cc/module/os.html#v:epoch) | Returns the number of milliseconds since an epoch depending on the locale. | | [date(\[format \[, time\]\])](https://tweaked.cc/module/os.html#v:date) | Returns a date string (or table) using a specified format string and optional time to format. | [](https://tweaked.cc/module/os.html#v:loadAPI) loadAPI(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/doc/stub/os.lua#L20) ##### 🛈 Deprecated When possible it's best to avoid using this function. It pollutes the global table and can mask errors. [`require`](https://www.lua.org/manual/5.1/manual.html#pdf-require) should be used to load libraries instead. Loads the given API into the global environment. This function loads and executes the file at the given path, and all global variables and functions exported by it will by available through the use of `myAPI.`, where `myAPI` is the base name of the API file. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path of the API to load. ### Returns 1. `boolean` Whether or not the API was successfully loaded. ### Changes * **New in version 1.2** [](https://tweaked.cc/module/os.html#v:unloadAPI) unloadAPI(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/doc/stub/os.lua#L29) ##### 🛈 Deprecated See [`os.loadAPI`](https://tweaked.cc/module/os.html#v:loadAPI) for why. Unloads an API which was loaded by [`os.loadAPI`](https://tweaked.cc/module/os.html#v:loadAPI) . This effectively removes the specified table from `_G`. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the API to unload. ### Changes * **New in version 1.2** [](https://tweaked.cc/module/os.html#v:pullEvent) pullEvent(\[filter\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/doc/stub/os.lua#L67) Pause execution of the current thread and waits for any events matching `filter`. This function [yields](https://www.lua.org/manual/5.1/manual.html#pdf-coroutine.yield) the current process and waits for it to be resumed with a vararg list where the first element matches `filter`. If no `filter` is supplied, this will match all events. Unlike [`os.pullEventRaw`](https://tweaked.cc/module/os.html#v:pullEventRaw) , it will stop the application upon a "terminate" event, printing the error "Terminated". ### Parameters 1. filter? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Event to filter for. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) event The name of the event that fired. 2. `any` param... Optional additional parameters of the event. ### Usage * Listen for `mouse_click` events. Run ᐅ while true do local event, button, x, y \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("mouse\_click") print("Button", button, "was clicked at", x, ",", y) end * Listen for multiple events. Run ᐅ while true do local eventData \= {[os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ()} local event \= eventData\[1\] if event \== "mouse\_click" then print("Button", eventData\[2\], "was clicked at", eventData\[3\], ",", eventData\[4\]) elseif event \== "key" then print("Key code", eventData\[2\], "was pressed") end end ### See also * **[`os.pullEventRaw`](https://tweaked.cc/module/os.html#v:pullEventRaw) ** To pull the terminate event. ### Changes * **Changed in version 1.3:** Added filter argument. [](https://tweaked.cc/module/os.html#v:pullEventRaw) pullEventRaw(\[filter\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/doc/stub/os.lua#L90) Pause execution of the current thread and waits for events, including the `terminate` event. This behaves almost the same as [`os.pullEvent`](https://tweaked.cc/module/os.html#v:pullEvent) , except it allows you to handle the `terminate` event yourself - the program will not stop execution when Ctrl+T is pressed. ### Parameters 1. filter? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Event to filter for. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) event The name of the event that fired. 2. `any` param... Optional additional parameters of the event. ### Usage * Listen for `terminate` events. Run ᐅ while true do local event \= [os.pullEventRaw](https://tweaked.cc/module/os.html#v:pullEventRaw "Pause execution of the current thread and waits for events, including the terminate event.") () if event \== "terminate" then print("Caught terminate event!") end end ### See also * **[`os.pullEvent`](https://tweaked.cc/module/os.html#v:pullEvent) ** To pull events normally. [](https://tweaked.cc/module/os.html#v:sleep) sleep(\[time=0\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/doc/stub/os.lua#L96) Pauses execution for the specified number of seconds, alias of [`_G.sleep`](https://tweaked.cc/module/_G.html#v:sleep) . ### Parameters 1. time? `number` = The number of seconds to sleep for, rounded up to the nearest multiple of 0.05. [](https://tweaked.cc/module/os.html#v:version) version()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/doc/stub/os.lua#L109) Get the current CraftOS version (for example, `CraftOS 1.9`). This is defined by `bios.lua`. For the current version of CC:Tweaked, this should return `CraftOS 1.9`. If you need to check for the presence of a feature, it is usually better to rely on feature detection, rather than comparing CraftOS versions. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The current CraftOS version. ### Usage * Run ᐅ [os.version](https://tweaked.cc/module/os.html#v:version "Get the current CraftOS version (for example, CraftOS 1.9).") () ### See also * **[`_G._HOST`](https://tweaked.cc/module/_G.html#v:_HOST) ** [](https://tweaked.cc/module/os.html#v:run) run(env, path, ...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/doc/stub/os.lua#L134) Run the program at the given path with the specified environment and arguments. This function does not resolve program names like the shell does. This means that, for example, `os.run("edit")` will not work. As well as this, it does not provide access to the [`shell`](https://tweaked.cc/module/shell.html) API in the environment. For this behaviour, use [`shell.run`](https://tweaked.cc/module/shell.html#v:run) instead. If the program cannot be found, or failed to run, it will print the error and return `false`. If you want to handle this more gracefully, use an alternative such as [`loadfile`](https://www.lua.org/manual/5.1/manual.html#pdf-loadfile) . ### Parameters 1. env [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The environment to run the program with. 2. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The exact path of the program to run. 3. ... The arguments to pass to the program. ### Returns 1. `boolean` Whether or not the program ran successfully. ### Usage * Run the default shell from within your program: Run ᐅ [os.run](https://tweaked.cc/module/os.html#v:run "Run the program at the given path with the specified environment and arguments.") ({}, "/rom/programs/shell.lua") ### See also * **[`shell.run`](https://tweaked.cc/module/shell.html#v:run) ** * **[`loadfile`](https://www.lua.org/manual/5.1/manual.html#pdf-loadfile) ** [](https://tweaked.cc/module/os.html#v:queueEvent) queueEvent(name, ...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L139) Adds an event to the event queue. This event can later be pulled with os.pullEvent. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the event to queue. 2. ... The parameters of the event. These can be any primitive type (boolean, number, string) as well as tables. Other types (like functions), as well as metatables, will not be preserved. ### See also * **[`os.pullEvent`](https://tweaked.cc/module/os.html#v:pullEvent) ** To pull the event queued [](https://tweaked.cc/module/os.html#v:startTimer) startTimer(time)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L159) Starts a timer that will run for the specified number of seconds. Once the timer fires, a [`timer`](https://tweaked.cc/event/timer.html) event will be added to the queue with the ID returned from this function as the first parameter. As with [sleep](https://tweaked.cc/module/os.html#v:sleep) , the time will automatically be rounded up to the nearest multiple of 0.05 seconds, as it waits for a fixed amount of world ticks. ### Parameters 1. time `number` The number of seconds until the timer fires. ### Returns 1. `number` The ID of the new timer. This can be used to filter the [`timer`](https://tweaked.cc/event/timer.html) event, or [cancel the timer](https://tweaked.cc/module/os.html#v:cancelTimer) . ### Throws * If the time is below zero. ### See also * **[`cancelTimer`](https://tweaked.cc/module/os.html#v:cancelTimer) ** To cancel a timer. [](https://tweaked.cc/module/os.html#v:cancelTimer) cancelTimer(token)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L172) Cancels a timer previously started with [`startTimer`](https://tweaked.cc/module/os.html#v:startTimer) . This will stop the timer from firing. ### Parameters 1. token `number` The ID of the timer to cancel. ### See also * **[`startTimer`](https://tweaked.cc/module/os.html#v:startTimer) ** To start a timer. ### Changes * **New in version 1.6** [](https://tweaked.cc/module/os.html#v:setAlarm) setAlarm(time)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L189) Sets an alarm that will fire at the specified [in-game time](https://tweaked.cc/module/os.html#v:time) . When it fires, an `alarm` event will be added to the event queue with the ID returned from this function as the first parameter. ### Parameters 1. time `number` The time at which to fire the alarm, in the range \[0.0, 24.0).\ \ ### Returns\ \ 1. `number` The ID of the new alarm. This can be used to filter the `alarm` event, or [cancel the alarm](https://tweaked.cc/module/os.html#v:cancelAlarm)\ .\ \ ### Throws\ \ * If the time is out of range.\ \ \ ### See also\ \ * **[`cancelAlarm`](https://tweaked.cc/module/os.html#v:cancelAlarm)\ ** To cancel an alarm.\ \ ### Changes\ \ * **New in version 1.2**\ \ [](https://tweaked.cc/module/os.html#v:cancelAlarm)\ cancelAlarm(token)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L208)\ \ Cancels an alarm previously started with setAlarm. This will stop the alarm from firing.\ \ ### Parameters\ \ 1. token `number` The ID of the alarm to cancel.\ \ ### See also\ \ * **[`setAlarm`](https://tweaked.cc/module/os.html#v:setAlarm)\ ** To set an alarm.\ \ ### Changes\ \ * **New in version 1.6**\ \ [](https://tweaked.cc/module/os.html#v:shutdown)\ shutdown()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L218)\ \ Shuts down the computer immediately.\ \ [](https://tweaked.cc/module/os.html#v:reboot)\ reboot()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L226)\ \ Reboots the computer immediately.\ \ [](https://tweaked.cc/module/os.html#v:getComputerID)\ getComputerID()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L236)\ \ Returns the ID of the computer.\ \ ### Returns\ \ 1. `number` The ID of the computer.\ \ [](https://tweaked.cc/module/os.html#v:computerID)\ computerID()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L236)\ \ Returns the ID of the computer.\ \ ### Returns\ \ 1. `number` The ID of the computer.\ \ [](https://tweaked.cc/module/os.html#v:getComputerLabel)\ getComputerLabel()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L248)\ \ Returns the label of the computer, or `nil` if none is set.\ \ ### Returns\ \ 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ | nil The label of the computer.\ \ ### Changes\ \ * **New in version 1.3**\ \ [](https://tweaked.cc/module/os.html#v:computerLabel)\ computerLabel()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L248)\ \ Returns the label of the computer, or `nil` if none is set.\ \ ### Returns\ \ 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ | nil The label of the computer.\ \ ### Changes\ \ * **New in version 1.3**\ \ [](https://tweaked.cc/module/os.html#v:setComputerLabel)\ setComputerLabel(\[label\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L260)\ \ Set the label of this computer.\ \ ### Parameters\ \ 1. label? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ The new label. May be `nil` in order to clear it.\ \ ### Changes\ \ * **New in version 1.3**\ \ [](https://tweaked.cc/module/os.html#v:clock)\ clock()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L271)\ \ Returns the number of seconds that the computer has been running.\ \ ### Returns\ \ 1. `number` The computer's uptime.\ \ ### Changes\ \ * **New in version 1.2**\ \ [](https://tweaked.cc/module/os.html#v:time)\ time(\[locale\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L305)\ \ Returns the current time depending on the string passed in. This will always be in the range \[0.0, 24.0).\ \ * If called with `ingame`, the current world time will be returned. This is the default if nothing is passed.\ * If called with `utc`, returns the hour of the day in UTC time.\ * If called with `local`, returns the hour of the day in the timezone the server is located in.\ \ This function can also be called with a table returned from [`date`](https://tweaked.cc/module/os.html#v:date)\ , which will convert the date fields into a UNIX timestamp (number of seconds since 1 January 1970).\ \ ### Parameters\ \ 1. locale? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ | [`table`](https://www.lua.org/manual/5.1/manual.html#5.5)\ The locale of the time, or a table filled by `os.date("*t")` to decode. Defaults to `ingame` locale if not specified.\ \ ### Returns\ \ 1. `any` The hour of the selected locale, or a UNIX timestamp from the table, depending on the argument passed in.\ \ ### Throws\ \ * If an invalid locale is passed.\ \ \ ### Usage\ \ * Print the current in-game time.\ \ Run ᐅ\ \ [textutils.formatTime](https://tweaked.cc/module/textutils.html#v:formatTime "Takes input time and formats it in a more readable format such as 6:30 PM.")\ ([os.time](https://tweaked.cc/module/os.html#v:time "Returns the current time depending on the string passed in.")\ ())\ \ \ ### See also\ \ * **[`textutils.formatTime`](https://tweaked.cc/module/textutils.html#v:formatTime)\ ** To convert times into a user-readable string.\ * **[`date`](https://tweaked.cc/module/os.html#v:date)\ ** To get a date table that can be converted with this function.\ \ ### Changes\ \ * **New in version 1.2**\ * **Changed in version 1.80pr1:** Add support for getting the local and UTC time.\ * **Changed in version 1.82.0:** Arguments are now case insensitive.\ * **Changed in version 1.83.0:** [`time`](https://tweaked.cc/module/os.html#v:time)\ now accepts table arguments and converts them to UNIX timestamps.\ \ [](https://tweaked.cc/module/os.html#v:day)\ day(\[locale\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L335)\ \ Returns the day depending on the locale specified.\ \ * If called with `ingame`, returns the number of days since the world was created. This is the default.\ * If called with `utc`, returns the number of days since 1 January 1970 in the UTC timezone.\ * If called with `local`, returns the number of days since 1 January 1970 in the server's local timezone.\ \ ### Parameters\ \ 1. locale? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ The locale to get the day for. Defaults to `ingame` if not set.\ \ ### Returns\ \ 1. `number` The day depending on the selected locale.\ \ ### Throws\ \ * If an invalid locale is passed.\ \ \ ### Changes\ \ * **New in version 1.48**\ * **Changed in version 1.82.0:** Arguments are now case insensitive.\ \ [](https://tweaked.cc/module/os.html#v:epoch)\ epoch(\[locale\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L374)\ \ Returns the number of milliseconds since an epoch depending on the locale.\ \ * If called with `ingame`, returns the number of _in-game_ milliseconds since the world was created. This is the default.\ * If called with `utc`, returns the number of milliseconds since 1 January 1970 in the UTC timezone.\ * If called with `local`, returns the number of milliseconds since 1 January 1970 in the server's local timezone.\ \ ##### 🛈 info\ \ The `ingame` time zone assumes that one Minecraft day consists of 86,400,000 milliseconds. Since one in-game day is much faster than a real day (20 minutes), this will change quicker than real time - one real second is equal to 72000 in-game milliseconds. If you wish to convert this value to real time, divide by 72000; to convert to ticks (where a day is 24000 ticks), divide by 3600.\ \ ### Parameters\ \ 1. locale? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ The locale to get the milliseconds for. Defaults to `ingame` if not set.\ \ ### Returns\ \ 1. `number` The milliseconds since the epoch depending on the selected locale.\ \ ### Throws\ \ * If an invalid locale is passed.\ \ \ ### Usage\ \ * Get the current time and use [`date`](https://tweaked.cc/module/os.html#v:date)\ to convert it to a table.\ \ Run ᐅ\ \ \-- Dividing by 1000 converts it from milliseconds to seconds.\ local time \= [os.epoch](https://tweaked.cc/module/os.html#v:epoch "Returns the number of milliseconds since an epoch depending on the locale.")\ ("local") / 1000\ local time\_table \= [os.date](https://tweaked.cc/module/os.html#v:date "Returns a date string (or table) using a specified format string and optional time to format.")\ ("\*t", time)\ print([textutils.serialize](https://tweaked.cc/module/textutils.html#v:serialize "Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing.")\ (time\_table))\ \ \ ### Changes\ \ * **New in version 1.80pr1**\ \ [](https://tweaked.cc/module/os.html#v:date)\ date(\[format \[, time\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java#L426)\ \ Returns a date string (or table) using a specified format string and optional time to format.\ \ The format string takes the same formats as C's [strftime](http://www.cplusplus.com/reference/ctime/strftime/)\ function. The format string can also be prefixed with an exclamation mark (`!`) to use UTC time instead of the server's local timezone.\ \ If the format is exactly `"*t"` (or `"!*t"` ), a table representation of the timestamp will be returned instead. This table has fields for the year, month, day, hour, minute, second, day of the week, day of the year, and whether Daylight Savings Time is in effect. This table can be converted back to a timestamp with [`time`](https://tweaked.cc/module/os.html#v:time)\ .\ \ ### Parameters\ \ 1. format? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ The format of the string to return. This defaults to `%c`, which expands to a string similar to "Sat Dec 24 16:58:00 2011".\ 2. time? `number` The timestamp to convert to a string. This defaults to the current time.\ \ ### Returns\ \ 1. `any` The resulting formated string, or table.\ \ ### Throws\ \ * If an invalid format is passed.\ \ \ ### Usage\ \ * Print the current date in a user-friendly string.\ \ Run ᐅ\ \ [os.date](https://tweaked.cc/module/os.html#v:date "Returns a date string (or table) using a specified format string and optional time to format.")\ ("%A %d %B %Y") \-- See the reference above!\ \ * Convert a timestamp to a table.\ \ Run ᐅ\ \ [os.date](https://tweaked.cc/module/os.html#v:date "Returns a date string (or table) using a specified format string and optional time to format.")\ ("!\*t", 1242534247)\ \--\[=\[ {\ -- Date\ year = 2009,\ month = 5,\ day = 17,\ yday = 137,\ wday = 1,\ -- Time\ hour = 4,\ min = 24,\ sec = 7,\ isdst = false,\ } \]=\]\ \ \ ### Changes\ \ * **New in version 1.83.0** --- # paintutils paintutils ========== Utilities for drawing more complex graphics, such as pixels, lines and images. ### Changes * **New in version 1.45** | | | | --- | --- | | [parseImage(image)](https://tweaked.cc/module/paintutils.html#v:parseImage) | Parses an image from a multi-line string | | [loadImage(path)](https://tweaked.cc/module/paintutils.html#v:loadImage) | Loads an image from a file. | | [drawPixel(xPos, yPos \[, colour\])](https://tweaked.cc/module/paintutils.html#v:drawPixel) | Draws a single pixel to the current term at the specified position. | | [drawLine(startX, startY, endX, endY \[, colour\])](https://tweaked.cc/module/paintutils.html#v:drawLine) | Draws a straight line from the start to end position. | | [drawBox(startX, startY, endX, endY \[, colour\])](https://tweaked.cc/module/paintutils.html#v:drawBox) | Draws the outline of a box on the current term from the specified start position to the specified end position. | | [drawFilledBox(startX, startY, endX, endY \[, colour\])](https://tweaked.cc/module/paintutils.html#v:drawFilledBox) | Draws a filled box on the current term from the specified start position to the specified end position. | | [drawImage(image, xPos, yPos)](https://tweaked.cc/module/paintutils.html#v:drawImage) | Draw an image loaded by [`paintutils.parseImage`](https://tweaked.cc/module/paintutils.html#v:parseImage)
or [`paintutils.loadImage`](https://tweaked.cc/module/paintutils.html#v:loadImage)
. | [](https://tweaked.cc/module/paintutils.html#v:parseImage) parseImage(image)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/paintutils.lua#L66) Parses an image from a multi-line string ### Parameters 1. image [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The string containing the raw-image data. ### Returns 1. [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The parsed image data, suitable for use with [`paintutils.drawImage`](https://tweaked.cc/module/paintutils.html#v:drawImage) . ### Usage * Parse an image from a string, and draw it. Run ᐅ local image \= [paintutils.parseImage](https://tweaked.cc/module/paintutils.html#v:parseImage "Parses an image from a multi-line string") (\[\[\ e e\ \ e e\ eeee\ \]\]) [paintutils.drawImage](https://tweaked.cc/module/paintutils.html#v:drawImage "Draw an image loaded by paintutils.parseImage or paintutils.loadImage.") (image, [term.getCursorPos](https://tweaked.cc/module/term.html#v:getCursorPos "Get the position of the cursor.") ()) ### Changes * **New in version 1.80pr1** [](https://tweaked.cc/module/paintutils.html#v:loadImage) loadImage(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/paintutils.lua#L89) Loads an image from a file. You can create a file suitable for being loaded using the `paint` program. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The file to load. ### Returns 1. [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) | nil The parsed image data, suitable for use with [`paintutils.drawImage`](https://tweaked.cc/module/paintutils.html#v:drawImage) , or `nil` if the file does not exist. ### Usage * Load an image and draw it. Run ᐅ local image \= [paintutils.loadImage](https://tweaked.cc/module/paintutils.html#v:loadImage "Loads an image from a file.") ("data/example.nfp") [paintutils.drawImage](https://tweaked.cc/module/paintutils.html#v:drawImage "Draw an image loaded by paintutils.parseImage or paintutils.loadImage.") (image, [term.getCursorPos](https://tweaked.cc/module/term.html#v:getCursorPos "Get the position of the cursor.") ()) [](https://tweaked.cc/module/paintutils.html#v:drawPixel) drawPixel(xPos, yPos \[, colour\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/paintutils.lua#L112) Draws a single pixel to the current term at the specified position. ##### ⚠ warning This function may change the position of the cursor and the current background colour. You should not expect either to be preserved. ### Parameters 1. xPos `number` The x position to draw at, where 1 is the far left. 2. yPos `number` The y position to draw at, where 1 is the very top. 3. colour? `number` The [color](https://tweaked.cc/module/colors.html) of this pixel. This will be the current background colour if not specified. [](https://tweaked.cc/module/paintutils.html#v:drawLine) drawLine(startX, startY, endX, endY \[, colour\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/paintutils.lua#L138) Draws a straight line from the start to end position. ##### ⚠ warning This function may change the position of the cursor and the current background colour. You should not expect either to be preserved. ### Parameters 1. startX `number` The starting x position of the line. 2. startY `number` The starting y position of the line. 3. endX `number` The end x position of the line. 4. endY `number` The end y position of the line. 5. colour? `number` The [color](https://tweaked.cc/module/colors.html) of this pixel. This will be the current background colour if not specified. ### Usage * Run ᐅ [paintutils.drawLine](https://tweaked.cc/module/paintutils.html#v:drawLine "Draws a straight line from the start to end position.") (2, 3, 30, 7, [colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") ) [](https://tweaked.cc/module/paintutils.html#v:drawBox) drawBox(startX, startY, endX, endY \[, colour\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/paintutils.lua#L215) Draws the outline of a box on the current term from the specified start position to the specified end position. ##### ⚠ warning This function may change the position of the cursor and the current background colour. You should not expect either to be preserved. ### Parameters 1. startX `number` The starting x position of the line. 2. startY `number` The starting y position of the line. 3. endX `number` The end x position of the line. 4. endY `number` The end y position of the line. 5. colour? `number` The [color](https://tweaked.cc/module/colors.html) of this pixel. This will be the current background colour if not specified. ### Usage * Run ᐅ [paintutils.drawBox](https://tweaked.cc/module/paintutils.html#v:drawBox "Draws the outline of a box on the current term from the specified start position to the specified end position.") (2, 3, 30, 7, [colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") ) [](https://tweaked.cc/module/paintutils.html#v:drawFilledBox) drawFilledBox(startX, startY, endX, endY \[, colour\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/paintutils.lua#L271) Draws a filled box on the current term from the specified start position to the specified end position. ##### ⚠ warning This function may change the position of the cursor and the current background colour. You should not expect either to be preserved. ### Parameters 1. startX `number` The starting x position of the line. 2. startY `number` The starting y position of the line. 3. endX `number` The end x position of the line. 4. endY `number` The end y position of the line. 5. colour? `number` The [color](https://tweaked.cc/module/colors.html) of this pixel. This will be the current background colour if not specified. ### Usage * Run ᐅ [paintutils.drawFilledBox](https://tweaked.cc/module/paintutils.html#v:drawFilledBox "Draws a filled box on the current term from the specified start position to the specified end position.") (2, 3, 30, 7, [colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") ) [](https://tweaked.cc/module/paintutils.html#v:drawImage) drawImage(image, xPos, yPos)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/paintutils.lua#L319) Draw an image loaded by [`paintutils.parseImage`](https://tweaked.cc/module/paintutils.html#v:parseImage) or [`paintutils.loadImage`](https://tweaked.cc/module/paintutils.html#v:loadImage) . ##### ⚠ warning This function may change the position of the cursor and the current background colour. You should not expect either to be preserved. ### Parameters 1. image [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The parsed image data. 2. xPos `number` The x position to start drawing at. 3. yPos `number` The y position to start drawing at. ### Usage * Load an image and draw it. Run ᐅ local image \= [paintutils.loadImage](https://tweaked.cc/module/paintutils.html#v:loadImage "Loads an image from a file.") ("data/example.nfp") [paintutils.drawImage](https://tweaked.cc/module/paintutils.html#v:drawImage "Draw an image loaded by paintutils.parseImage or paintutils.loadImage.") (image, [term.getCursorPos](https://tweaked.cc/module/term.html#v:getCursorPos "Get the position of the cursor.") ()) --- # parallel parallel ======== A simple way to run several functions at once. Functions are not actually executed simultaneously, but rather this API will automatically switch between them whenever they yield (e.g. whenever they call [`coroutine.yield`](https://www.lua.org/manual/5.1/manual.html#pdf-coroutine.yield) , or functions that call that - such as [`os.pullEvent`](https://tweaked.cc/module/os.html#v:pullEvent) - or functions that call that, etc - basically, anything that causes the function to "pause"). Each function executed in "parallel" gets its own copy of the event queue, and so "event consuming" functions (again, mostly anything that causes the script to pause - eg [`os.sleep`](https://tweaked.cc/module/os.html#v:sleep) , [`rednet.receive`](https://tweaked.cc/module/rednet.html#v:receive) , most of the [`turtle`](https://tweaked.cc/module/turtle.html) API, etc) can safely be used in one without affecting the event queue accessed by the other. ##### ⚠ warning When using this API, be careful to pass the functions you want to run in parallel, and _not_ the result of calling those functions. For instance, the following is correct: Run ᐅ local function do\_sleep() sleep(1) end [parallel.waitForAny](https://tweaked.cc/module/parallel.html#v:waitForAny "Switches between execution of the functions, until any of them finishes.") (do\_sleep, [rednet.receive](https://tweaked.cc/module/rednet.html#v:receive "Wait for a rednet message to be received, or until timeout seconds have elapsed.") ) but the following is **NOT**: Run ᐅ local function do\_sleep() sleep(1) end [parallel.waitForAny](https://tweaked.cc/module/parallel.html#v:waitForAny "Switches between execution of the functions, until any of them finishes.") (do\_sleep(), [rednet.receive](https://tweaked.cc/module/rednet.html#v:receive "Wait for a rednet message to be received, or until timeout seconds have elapsed.") ) ### Changes * **New in version 1.2** | | | | --- | --- | | [waitForAny(...)](https://tweaked.cc/module/parallel.html#v:waitForAny) | Switches between execution of the functions, until any of them finishes. | | [waitForAll(...)](https://tweaked.cc/module/parallel.html#v:waitForAll) | Runs several functions in parallel, until all of them are finished. | [](https://tweaked.cc/module/parallel.html#v:waitForAny) waitForAny(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/parallel.lua#L69) Switches between execution of the functions, until any of them finishes. If any of the functions errors, the message is propagated upwards from the [`parallel.waitForAny`](https://tweaked.cc/module/parallel.html#v:waitForAny) call. ### Parameters 1. ... `function` The functions to run in parallel. ### Usage * Print a message every second until the `q` key is pressed. Run ᐅ local function tick() while true do [os.sleep](https://tweaked.cc/module/os.html#v:sleep "Pauses execution for the specified number of seconds, alias of _G.sleep.") (1) print("Tick") end end local function wait\_for\_q() repeat local \_, key \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("key") until key \== [keys](https://tweaked.cc/module/keys.html "Constants for all keyboard "key codes", as queued by the key event.") .q print("Q was pressed!") end [parallel.waitForAny](https://tweaked.cc/module/parallel.html#v:waitForAny "Switches between execution of the functions, until any of them finishes.") (tick, wait\_for\_q) print("Everything done!") [](https://tweaked.cc/module/parallel.html#v:waitForAll) waitForAll(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/parallel.lua#L182) Runs several functions in parallel, until all of them are finished. If any of the functions errors, the other functions are not resumed, and the error is propagated upwards. ##### ⚠ warning While any number of functions can be run in parallel, running too many things in parallel can sometimes cause issues: * Computers only buffer 256 events at a time. Trying to run several hundred functions in parallel (particularly when calling peripheral methods) can cause the event queue to fill up, resulting in events being dropped, and programs getting stuck. * Computers only run 16 HTTP requests at a time. Trying to run more than that in parallel will have no effect. ### Spawning new parallel functions In some cases, you may want to start running additional functions in parallel from an existing [`parallel.waitForAll`](https://tweaked.cc/module/parallel.html#v:waitForAll) call. Every function passed to [`waitForAll`](https://tweaked.cc/module/parallel.html#v:waitForAll) can accept a `spawn` argument, which can be called to spawn new parallel functions. Run ᐅ [parallel.waitForAll](https://tweaked.cc/module/parallel.html#v:waitForAll "Runs several functions in parallel, until all of them are finished.") (function(spawn) spawn(function() sleep(1); print("Finished 1") end) spawn(function() sleep(2); print("Finished 2") end) end) ### Parameters 1. ... function(spawn: function(fn: `function`, ...: `any`)) The functions to run in parallel. ### Usage * Start off two timers and wait for them both to run. Run ᐅ local function a() [os.sleep](https://tweaked.cc/module/os.html#v:sleep "Pauses execution for the specified number of seconds, alias of _G.sleep.") (1) print("A is done") end local function b() [os.sleep](https://tweaked.cc/module/os.html#v:sleep "Pauses execution for the specified number of seconds, alias of _G.sleep.") (3) print("B is done") end [parallel.waitForAll](https://tweaked.cc/module/parallel.html#v:waitForAll "Runs several functions in parallel, until all of them are finished.") (a, b) print("Everything done!") * Generate a list of functions to run in parallel. Run ᐅ local funcs \= {} for i \= 1, 5 do table.insert(funcs, function() sleep(math.random()) print("Finished " .. i) end) end [parallel.waitForAll](https://tweaked.cc/module/parallel.html#v:waitForAll "Runs several functions in parallel, until all of them are finished.") (table.unpack(funcs)) print("Everything done!") * Run new functions in parallel from within `waitForAll`. Run ᐅ [parallel.waitForAll](https://tweaked.cc/module/parallel.html#v:waitForAll "Runs several functions in parallel, until all of them are finished.") (function(spawn) for i \= 1, 5 do spawn(function() sleep(math.random()) print("Finished " .. i) end) end end) print("Everything done!") ### Changes * **Changed in version 1.120.0:** Added ability to spawn new parallel functions. --- # peripheral peripheral ========== Find and control peripherals attached to this computer. Peripherals are blocks (or turtle and pocket computer upgrades) which can be controlled by a computer. For instance, the [`speaker`](https://tweaked.cc/peripheral/speaker.html) peripheral allows a computer to play music and the [`monitor`](https://tweaked.cc/peripheral/monitor.html) peripheral allows you to display text in the world. Referencing peripherals ----------------------- Computers can interact with adjacent peripherals. Each peripheral is given a name based on which direction it is in. For instance, a disk drive below your computer will be called `"bottom"` in your Lua code, one to the left called `"left"` , and so on for all 6 directions (`"bottom"`, `"top"`, `"left"`, `"right"`, `"front"`, `"back"`). You can list the names of all peripherals with the `peripherals` program, or the [`peripheral.getNames`](https://tweaked.cc/module/peripheral.html#v:getNames) function. It's also possible to use peripherals which are further away from your computer through the use of [Wired Modems](https://tweaked.cc/peripheral/modem.html) . Place one modem against your computer (you may need to sneak and right click), run Networking Cable to your peripheral, and then place another modem against that block. You can then right click the modem to use (or _attach_) the peripheral. This will print a peripheral name to chat, which can then be used just like a direction name to access the peripheral. You can click on the message to copy the name to your clipboard. Using peripherals ----------------- Once you have the name of a peripheral, you can call functions on it using the [`peripheral.call`](https://tweaked.cc/module/peripheral.html#v:call) function. This takes the name of our peripheral, the name of the function we want to call, and then its arguments. ##### 🛈 info Some bits of the peripheral API call peripheral functions _methods_ instead (for example, the [`peripheral.getMethods`](https://tweaked.cc/module/peripheral.html#v:getMethods) function). Don't worry, they're the same thing! Let's say we have a monitor above our computer (and so "top") and want to [write some text to it](https://tweaked.cc/peripheral/monitor.html#v:write) . We'd write the following: Run ᐅ [peripheral.call](https://tweaked.cc/module/peripheral.html#v:call "Call a method on the peripheral with the given name.") ("top", "write", "This is displayed on a monitor!") Once you start calling making a couple of peripheral calls this can get very repetitive, and so we can [wrap](https://tweaked.cc/module/peripheral.html#v:wrap) a peripheral. This builds a table of all the peripheral's functions so you can use it like an API or module. For instance, we could have written the above example as follows: Run ᐅ local my\_monitor \= [peripheral.wrap](https://tweaked.cc/module/peripheral.html#v:wrap "Get a table containing all functions available on a peripheral.") ("top") my\_monitor.write("This is displayed on a monitor!") Finding peripherals ------------------- Sometimes when you're writing a program you don't care what a peripheral is called, you just need to know it's there. For instance, if you're writing a music player, you just need a speaker - it doesn't matter if it's above or below the computer. Thankfully there's a quick way to do this: [`peripheral.find`](https://tweaked.cc/module/peripheral.html#v:find) . This takes a _peripheral type_ and returns all the attached peripherals which are of this type. What is a peripheral type though? This is a string which describes what a peripheral is, and so what functions are available on it. For instance, speakers are just called `"speaker"`, and monitors `"monitor"`. Some peripherals might have more than one type - a Minecraft chest is both a `"minecraft:chest"` and `"inventory"`. You can get all the types a peripheral has with [`peripheral.getType`](https://tweaked.cc/module/peripheral.html#v:getType) , and check a peripheral is a specific type with [`peripheral.hasType`](https://tweaked.cc/module/peripheral.html#v:hasType) . To return to our original example, let's use [`peripheral.find`](https://tweaked.cc/module/peripheral.html#v:find) to find an attached speaker: Run ᐅ local speaker \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("speaker") speaker.playNote("harp") ### See also * **[`peripheral`](https://tweaked.cc/event/peripheral.html) ** This event is fired whenever a new peripheral is attached. * **[`peripheral_detach`](https://tweaked.cc/event/peripheral_detach.html) ** This event is fired whenever a peripheral is detached. ### Changes * **New in version 1.3** * **Changed in version 1.51:** Add support for wired modems. * **Changed in version 1.99:** Peripherals can have multiple types. | | | | --- | --- | | [getNames()](https://tweaked.cc/module/peripheral.html#v:getNames) | Provides a list of all peripherals available. | | [isPresent(name)](https://tweaked.cc/module/peripheral.html#v:isPresent) | Determines if a peripheral is present with the given name. | | [getType(peripheral)](https://tweaked.cc/module/peripheral.html#v:getType) | Get the types of a named or wrapped peripheral. | | [hasType(peripheral, peripheral\_type)](https://tweaked.cc/module/peripheral.html#v:hasType) | Check if a peripheral is of a particular type. | | [getMethods(name)](https://tweaked.cc/module/peripheral.html#v:getMethods) | Get all available methods for the peripheral with the given name. | | [getName(peripheral)](https://tweaked.cc/module/peripheral.html#v:getName) | Get the name of a peripheral wrapped with [`peripheral.wrap`](https://tweaked.cc/module/peripheral.html#v:wrap)
. | | [call(name, method, ...)](https://tweaked.cc/module/peripheral.html#v:call) | Call a method on the peripheral with the given name. | | [wrap(name)](https://tweaked.cc/module/peripheral.html#v:wrap) | Get a table containing all functions available on a peripheral. | | [find(ty \[, filter\])](https://tweaked.cc/module/peripheral.html#v:find) | Find all peripherals of a specific type, and return the [wrapped](https://tweaked.cc/module/peripheral.html#v:wrap)
peripherals. | [](https://tweaked.cc/module/peripheral.html#v:getNames) getNames()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua#L110) Provides a list of all peripherals available. If a device is located directly next to the system, then its name will be listed as the side it is attached to. If a device is attached via a Wired Modem, then it'll be reported according to its name on the wired network. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } A list of the names of all attached peripherals. ### Changes * **New in version 1.51** [](https://tweaked.cc/module/peripheral.html#v:isPresent) isPresent(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua#L133) Determines if a peripheral is present with the given name. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side or network name that you want to check. ### Returns 1. `boolean` If a peripheral is present with the given name. ### Usage * Run ᐅ [peripheral.isPresent](https://tweaked.cc/module/peripheral.html#v:isPresent "Determines if a peripheral is present with the given name.") ("top") * Run ᐅ [peripheral.isPresent](https://tweaked.cc/module/peripheral.html#v:isPresent "Determines if a peripheral is present with the given name.") ("monitor\_0") [](https://tweaked.cc/module/peripheral.html#v:getType) getType(peripheral)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua#L159) Get the types of a named or wrapped peripheral. ### Parameters 1. peripheral [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The name of the peripheral to find, or a wrapped peripheral instance. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... The peripheral's types, or `nil` if it is not present. ### Usage * Get the type of a peripheral above this computer. Run ᐅ [peripheral.getType](https://tweaked.cc/module/peripheral.html#v:getType "Get the types of a named or wrapped peripheral.") ("top") ### Changes * **Changed in version 1.88.0:** Accepts a wrapped peripheral as an argument. * **Changed in version 1.99:** Now returns multiple types. [](https://tweaked.cc/module/peripheral.html#v:hasType) hasType(peripheral, peripheral\_type)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua#L189) Check if a peripheral is of a particular type. ### Parameters 1. peripheral [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The name of the peripheral or a wrapped peripheral instance. 2. peripheral\_type [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The type to check. ### Returns 1. `boolean` | nil If a peripheral has a particular type, or `nil` if it is not present. ### Changes * **New in version 1.99** [](https://tweaked.cc/module/peripheral.html#v:getMethods) getMethods(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua#L217) Get all available methods for the peripheral with the given name. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the peripheral to find. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } | nil A list of methods provided by this peripheral, or `nil` if it is not present. [](https://tweaked.cc/module/peripheral.html#v:getName) getName(peripheral)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua#L236) Get the name of a peripheral wrapped with [`peripheral.wrap`](https://tweaked.cc/module/peripheral.html#v:wrap) . ### Parameters 1. peripheral [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The peripheral to get the name of. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the given peripheral. ### Changes * **New in version 1.88.0** [](https://tweaked.cc/module/peripheral.html#v:call) call(name, method, ...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua#L255) Call a method on the peripheral with the given name. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the peripheral to invoke the method on. 2. method [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the method 3. ... Additional arguments to pass to the method ### Returns 1. The return values of the peripheral method. ### Usage * Open the modem on the top of this computer. Run ᐅ [peripheral.call](https://tweaked.cc/module/peripheral.html#v:call "Call a method on the peripheral with the given name.") ("top", "open", 1) [](https://tweaked.cc/module/peripheral.html#v:wrap) wrap(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua#L281) Get a table containing all functions available on a peripheral. These can then be called instead of using [`peripheral.call`](https://tweaked.cc/module/peripheral.html#v:call) every time. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the peripheral to wrap. ### Returns 1. [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) | nil The table containing the peripheral's methods, or `nil` if there is no peripheral present with the given name. ### Usage * Open the modem on the top of this computer. Run ᐅ local modem \= [peripheral.wrap](https://tweaked.cc/module/peripheral.html#v:wrap "Get a table containing all functions available on a peripheral.") ("top") modem.open(1) [](https://tweaked.cc/module/peripheral.html#v:find) find(ty \[, filter\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua#L332) Find all peripherals of a specific type, and return the [wrapped](https://tweaked.cc/module/peripheral.html#v:wrap) peripherals. ### Parameters 1. ty [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The type of peripheral to look for. 2. filter? function(name: [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) , wrapped: [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) ):`boolean` A filter function, which takes the peripheral's name and wrapped table and returns if it should be included in the result. ### Returns 1. [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) ... 0 or more wrapped peripherals matching the given filters. ### Usage * Find all monitors and store them in a table, writing "Hello" on each one. Run ᐅ local monitors \= { [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("monitor") } for \_, monitor in pairs(monitors) do monitor.write("Hello") end * Find all wireless modems connected to this computer. Run ᐅ local modems \= { [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("modem", function(name, modem) return modem.isWireless() \-- Check this modem is wireless. end) } * This abuses the `filter` argument to call [`rednet.open`](https://tweaked.cc/module/rednet.html#v:open) on every modem. Run ᐅ [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("modem", [rednet.open](https://tweaked.cc/module/rednet.html#v:open "Opens a modem with the given peripheral name, allowing it to send and receive messages over rednet.") ) ### Changes * **New in version 1.6** --- # pocket pocket ====== Control the current pocket computer, adding or removing upgrades. This API is only available on pocket computers. As such, you may use its presence to determine what kind of computer you are using: Run ᐅ if [pocket](https://tweaked.cc/module/pocket.html "Control the current pocket computer, adding or removing upgrades.") then print("On a pocket computer") else print("On something else") end Recipes ------- **Pocket Computer** ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Golden Apple](https://tweaked.cc/images/items/minecraft/golden_apple.png "Golden Apple") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Glass Pane](https://tweaked.cc/images/items/minecraft/glass_pane.png "Glass Pane") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Pocket Computer](https://tweaked.cc/images/items/computercraft/pocket_computer_normal.png "Pocket Computer") **Advanced Pocket Computer** ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Golden Apple](https://tweaked.cc/images/items/minecraft/golden_apple.png "Golden Apple") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Glass Pane](https://tweaked.cc/images/items/minecraft/glass_pane.png "Glass Pane") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Advanced Pocket Computer](https://tweaked.cc/images/items/computercraft/pocket_computer_advanced.png "Advanced Pocket Computer") | | | | --- | --- | | [equipBack()](https://tweaked.cc/module/pocket.html#v:equipBack) | Search the player's inventory for another upgrade, replacing the existing one with that item if found. | | [unequipBack()](https://tweaked.cc/module/pocket.html#v:unequipBack) | Remove the pocket computer's current upgrade. | [](https://tweaked.cc/module/pocket.html#v:equipBack) equipBack()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/pocket/apis/PocketAPI.java#L63) Search the player's inventory for another upgrade, replacing the existing one with that item if found. This inventory search starts from the player's currently selected slot, allowing you to prioritise upgrades. ### Returns 1. `boolean` If an item was equipped. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason an item was not equipped. [](https://tweaked.cc/module/pocket.html#v:unequipBack) unequipBack()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/pocket/apis/PocketAPI.java#L94) Remove the pocket computer's current upgrade. ### Returns 1. `boolean` If the upgrade was unequipped. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason an upgrade was not unequipped. --- # rednet rednet ====== Communicate with other computers by using [modems](https://tweaked.cc/peripheral/modem.html) . [`rednet`](https://tweaked.cc/module/rednet.html) provides a layer of abstraction on top of the main [`modem`](https://tweaked.cc/peripheral/modem.html) peripheral, making it slightly easier to use. Basic usage ----------- In order to send a message between two computers, each computer must have a modem on one of its sides (or in the case of pocket computers and turtles, the modem must be equipped as an upgrade). The two computers should then call [`rednet.open`](https://tweaked.cc/module/rednet.html#v:open) , which sets up the modems ready to send and receive messages. Once rednet is opened, you can send messages using [`rednet.send`](https://tweaked.cc/module/rednet.html#v:send) and receive them using [`rednet.receive`](https://tweaked.cc/module/rednet.html#v:receive) . It's also possible to send a message to _every_ rednet-using computer using [`rednet.broadcast`](https://tweaked.cc/module/rednet.html#v:broadcast) . ##### ⚠ Network security While rednet provides a friendly way to send messages to specific computers, it doesn't provide any guarantees about security. Other computers could be listening in to your messages, or even pretending to send messages from other computers! If you're playing on a multi-player server (or at least one where you don't trust other players), it's worth encrypting or signing your rednet messages. Protocols and hostnames ----------------------- Several rednet messages accept "protocol"s - simple string names describing what a message is about. When sending messages using [`rednet.send`](https://tweaked.cc/module/rednet.html#v:send) and [`rednet.broadcast`](https://tweaked.cc/module/rednet.html#v:broadcast) , you can optionally specify a protocol for the message. This same protocol can then be given to [`rednet.receive`](https://tweaked.cc/module/rednet.html#v:receive) , to ignore all messages not using this protocol. It's also possible to look-up computers based on protocols, providing a basic system for service discovery and [DNS](https://en.wikipedia.org/wiki/Domain_Name_System "Domain Name System") . A computer can advertise that it supports a particular protocol with [`rednet.host`](https://tweaked.cc/module/rednet.html#v:host) , also providing a friendly "hostname". Other computers may then find all computers which support this protocol using [`rednet.lookup`](https://tweaked.cc/module/rednet.html#v:lookup) . ### See also * **[`rednet_message`](https://tweaked.cc/event/rednet_message.html) ** Queued when a rednet message is received. * **[`modem`](https://tweaked.cc/peripheral/modem.html) ** Rednet is built on top of the modem peripheral. Modems provide a more bare-bones but flexible interface. ### Changes * **New in version 1.2** | | | | --- | --- | | [CHANNEL\_BROADCAST = 65535](https://tweaked.cc/module/rednet.html#v:CHANNEL_BROADCAST) | The channel used by the Rednet API to [`broadcast`](https://tweaked.cc/module/rednet.html#v:broadcast)
messages. | | [CHANNEL\_REPEAT = 65533](https://tweaked.cc/module/rednet.html#v:CHANNEL_REPEAT) | The channel used by the Rednet API to repeat messages. | | [MAX\_ID\_CHANNELS = 65500](https://tweaked.cc/module/rednet.html#v:MAX_ID_CHANNELS) | The number of channels rednet reserves for computer IDs. | | [open(modem)](https://tweaked.cc/module/rednet.html#v:open) | Opens a modem with the given [`peripheral`](https://tweaked.cc/module/peripheral.html)
name, allowing it to send and receive messages over rednet. | | [close(\[modem\])](https://tweaked.cc/module/rednet.html#v:close) | Close a modem with the given [`peripheral`](https://tweaked.cc/module/peripheral.html)
name, meaning it can no longer send and receive rednet messages. | | [isOpen(\[modem\])](https://tweaked.cc/module/rednet.html#v:isOpen) | Determine if rednet is currently open. | | [send(recipient, message \[, protocol\])](https://tweaked.cc/module/rednet.html#v:send) | Allows a computer or turtle with an attached modem to send a message intended for a computer with a specific ID. | | [broadcast(message \[, protocol\])](https://tweaked.cc/module/rednet.html#v:broadcast) | Broadcasts a string message over the predefined [`CHANNEL_BROADCAST`](https://tweaked.cc/module/rednet.html#v:CHANNEL_BROADCAST)
channel. | | [receive(\[protocol\_filter \[, timeout\]\])](https://tweaked.cc/module/rednet.html#v:receive) | Wait for a rednet message to be received, or until `timeout` seconds have elapsed. | | [host(protocol, hostname)](https://tweaked.cc/module/rednet.html#v:host) | Register the system as "hosting" the desired protocol under the specified name. | | [unhost(protocol)](https://tweaked.cc/module/rednet.html#v:unhost) | Stop [hosting](https://tweaked.cc/module/rednet.html#v:host)
a specific protocol, meaning it will no longer respond to [`rednet.lookup`](https://tweaked.cc/module/rednet.html#v:lookup)
requests. | | [lookup(protocol \[, hostname \[, timeout=2\]\])](https://tweaked.cc/module/rednet.html#v:lookup) | Search the local rednet network for systems [hosting](https://tweaked.cc/module/rednet.html#v:host)
the desired protocol and returns any computer IDs that respond as "r... | | [run()](https://tweaked.cc/module/rednet.html#v:run) | Listen for modem messages and converts them into rednet messages, which may then be [received](https://tweaked.cc/module/rednet.html#v:receive)
. | [](https://tweaked.cc/module/rednet.html#v:CHANNEL_BROADCAST) CHANNEL\_BROADCAST = 65535[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua#L53) The channel used by the Rednet API to [`broadcast`](https://tweaked.cc/module/rednet.html#v:broadcast) messages. [](https://tweaked.cc/module/rednet.html#v:CHANNEL_REPEAT) CHANNEL\_REPEAT = 65533[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua#L56) The channel used by the Rednet API to repeat messages. [](https://tweaked.cc/module/rednet.html#v:MAX_ID_CHANNELS) MAX\_ID\_CHANNELS = 65500[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua#L60) The number of channels rednet reserves for computer IDs. Computers with IDs greater or equal to this limit wrap around to 0. [](https://tweaked.cc/module/rednet.html#v:open) open(modem)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua#L91) Opens a modem with the given [`peripheral`](https://tweaked.cc/module/peripheral.html) name, allowing it to send and receive messages over rednet. This will open the modem on two channels: one which has the same [ID](https://tweaked.cc/module/os.html#v:getComputerID) as the computer, and another on [the broadcast channel](https://tweaked.cc/module/rednet.html#v:CHANNEL_BROADCAST) . ### Parameters 1. modem [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the modem to open. ### Throws * If there is no such modem with the given name ### Usage * Open rednet on the back of the computer, allowing you to send and receive rednet messages using it. Run ᐅ [rednet.open](https://tweaked.cc/module/rednet.html#v:open "Opens a modem with the given peripheral name, allowing it to send and receive messages over rednet.") ("back") * Open rednet on all attached modems. This abuses the "filter" argument to [`peripheral.find`](https://tweaked.cc/module/peripheral.html#v:find) . Run ᐅ [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("modem", [rednet.open](https://tweaked.cc/module/rednet.html#v:open "Opens a modem with the given peripheral name, allowing it to send and receive messages over rednet.") ) ### See also * **[`rednet.close`](https://tweaked.cc/module/rednet.html#v:close) ** * **[`rednet.isOpen`](https://tweaked.cc/module/rednet.html#v:isOpen) ** [](https://tweaked.cc/module/rednet.html#v:close) close(\[modem\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua#L107) Close a modem with the given [`peripheral`](https://tweaked.cc/module/peripheral.html) name, meaning it can no longer send and receive rednet messages. ### Parameters 1. modem? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side the modem exists on. If not given, all open modems will be closed. ### Throws * If there is no such modem with the given name ### See also * **[`rednet.open`](https://tweaked.cc/module/rednet.html#v:open) ** [](https://tweaked.cc/module/rednet.html#v:isOpen) isOpen(\[modem\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua#L133) Determine if rednet is currently open. ### Parameters 1. modem? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Which modem to check. If not given, all connected modems will be checked. ### Returns 1. `boolean` If the given modem is open. ### See also * **[`rednet.open`](https://tweaked.cc/module/rednet.html#v:open) ** ### Changes * **New in version 1.31** [](https://tweaked.cc/module/rednet.html#v:send) send(recipient, message \[, protocol\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua#L176) Allows a computer or turtle with an attached modem to send a message intended for a computer with a specific ID. At least one such modem must first be [opened](https://tweaked.cc/module/rednet.html#v:open) before sending is possible. Assuming the target was in range and also had a correctly opened modem, the target computer may then use [`rednet.receive`](https://tweaked.cc/module/rednet.html#v:receive) to collect the message. ### Parameters 1. recipient `number` The ID of the receiving computer. 2. message The message to send. Like with [`modem.transmit`](https://tweaked.cc/peripheral/modem.html#v:transmit) , this can contain any primitive type (numbers, booleans and strings) as well as tables. Other types (like functions), as well as metatables, will not be transmitted. 3. protocol? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The "protocol" to send this message under. When using [`rednet.receive`](https://tweaked.cc/module/rednet.html#v:receive) one can filter to only receive messages sent under a particular protocol. ### Returns 1. `boolean` If this message was successfully sent (i.e. if rednet is currently [open](https://tweaked.cc/module/rednet.html#v:open) ). Note, this does not guarantee the message was actually _received_. ### Usage * Send a message to computer #2. Run ᐅ [rednet.send](https://tweaked.cc/module/rednet.html#v:send "Allows a computer or turtle with an attached modem to send a message intended for a computer with a specific ID.") (2, "Hello from rednet!") ### See also * **[`rednet.receive`](https://tweaked.cc/module/rednet.html#v:receive) ** ### Changes * **Changed in version 1.6:** Added protocol parameter. * **Changed in version 1.82.0:** Now returns whether the message was successfully sent. [](https://tweaked.cc/module/rednet.html#v:broadcast) broadcast(message \[, protocol\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua#L233) Broadcasts a string message over the predefined [`CHANNEL_BROADCAST`](https://tweaked.cc/module/rednet.html#v:CHANNEL_BROADCAST) channel. The message will be received by every device listening to rednet. ### Parameters 1. message The message to send. This should not contain coroutines or functions, as they will be converted to `nil`. 2. protocol? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The "protocol" to send this message under. When using [`rednet.receive`](https://tweaked.cc/module/rednet.html#v:receive) one can filter to only receive messages sent under a particular protocol. ### Usage * Broadcast the words "Hello, world!" to every computer using rednet. Run ᐅ [rednet.broadcast](https://tweaked.cc/module/rednet.html#v:broadcast "Broadcasts a string message over the predefined CHANNEL_BROADCAST channel.") ("Hello, world!") ### See also * **[`rednet.receive`](https://tweaked.cc/module/rednet.html#v:receive) ** ### Changes * **Changed in version 1.6:** Added protocol parameter. [](https://tweaked.cc/module/rednet.html#v:receive) receive(\[protocol\_filter \[, timeout\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua#L276) Wait for a rednet message to be received, or until `timeout` seconds have elapsed. ### Parameters 1. protocol\_filter? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The protocol the received message must be sent with. If specified, any messages not sent under this protocol will be discarded. 2. timeout? `number` The number of seconds to wait if no message is received. ### Returns 1. `number` The computer which sent this message 2. The received message 3. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The protocol this message was sent under. #### Or 1. nil If the timeout elapsed and no message was received. ### Usage * Receive a rednet message. Run ᐅ local id, message \= [rednet.receive](https://tweaked.cc/module/rednet.html#v:receive "Wait for a rednet message to be received, or until timeout seconds have elapsed.") () print(("Computer %d sent message %s"):format(id, message)) * Receive a message, stopping after 5 seconds if no message was received. Run ᐅ local id, message \= [rednet.receive](https://tweaked.cc/module/rednet.html#v:receive "Wait for a rednet message to be received, or until timeout seconds have elapsed.") (nil, 5) if not id then printError("No message received") else print(("Computer %d sent message %s"):format(id, message)) end * Receive a message from computer #2. Run ᐅ local id, message repeat id, message \= [rednet.receive](https://tweaked.cc/module/rednet.html#v:receive "Wait for a rednet message to be received, or until timeout seconds have elapsed.") () until id \== 2 print(message) ### See also * **[`rednet.broadcast`](https://tweaked.cc/module/rednet.html#v:broadcast) ** * **[`rednet.send`](https://tweaked.cc/module/rednet.html#v:send) ** ### Changes * **Changed in version 1.6:** Added protocol filter parameter. [](https://tweaked.cc/module/rednet.html#v:host) host(protocol, hostname)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua#L332) Register the system as "hosting" the desired protocol under the specified name. If a rednet [lookup](https://tweaked.cc/module/rednet.html#v:lookup) is performed for that protocol (and maybe name) on the same network, the registered system will automatically respond via a background process, hence providing the system performing the lookup with its ID number. Multiple computers may not register themselves on the same network as having the same names against the same protocols, and the title `localhost` is specifically reserved. They may, however, share names as long as their hosted protocols are different, or if they only join a given network after "registering" themselves before doing so (eg while offline or part of a different network). ### Parameters 1. protocol [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The protocol this computer provides. 2. hostname [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name this computer exposes for the given protocol. ### Throws * If trying to register a hostname which is reserved, or currently in use. ### See also * **[`rednet.unhost`](https://tweaked.cc/module/rednet.html#v:unhost) ** * **[`rednet.lookup`](https://tweaked.cc/module/rednet.html#v:lookup) ** ### Changes * **New in version 1.6** [](https://tweaked.cc/module/rednet.html#v:unhost) unhost(protocol)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua#L351) Stop [hosting](https://tweaked.cc/module/rednet.html#v:host) a specific protocol, meaning it will no longer respond to [`rednet.lookup`](https://tweaked.cc/module/rednet.html#v:lookup) requests. ### Parameters 1. protocol [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The protocol to unregister your self from. ### Changes * **New in version 1.6** [](https://tweaked.cc/module/rednet.html#v:lookup) lookup(protocol \[, hostname \[, timeout=2\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua#L391) Search the local rednet network for systems [hosting](https://tweaked.cc/module/rednet.html#v:host) the desired protocol and returns any computer IDs that respond as "registered" against it. If a hostname is specified, only one ID will be returned (assuming an exact match is found). ### Parameters 1. protocol [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The protocol to search for. 2. hostname? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The hostname to search for. 3. timeout? `number` = The number of seconds to wait for a lookup response. ### Returns 1. `number`... A list of computer IDs hosting the given protocol. #### Or 1. `number` | nil The computer ID with the provided hostname and protocol, or `nil` if none exists. ### Usage * Find all computers which are hosting the `"chat"` protocol. Run ᐅ local computers \= {[rednet.lookup](https://tweaked.cc/module/rednet.html#v:lookup "Search the local rednet network for systems hosting the desired protocol and returns any computer IDs that respond as "r...") ("chat")} print(#computers .. " computers available to chat") for \_, computer in pairs(computers) do print("Computer #" .. computer) end * Find a computer hosting the `"chat"` protocol with a hostname of `"my_host"`. Run ᐅ local id \= [rednet.lookup](https://tweaked.cc/module/rednet.html#v:lookup "Search the local rednet network for systems hosting the desired protocol and returns any computer IDs that respond as "r...") ("chat", "my\_host") if id then print("Found my\_host at computer #" .. id) else printError("Cannot find my\_host") end ### Changes * **New in version 1.6** * **Changed in version 1.118.0:** Added `timeout` parameter. [](https://tweaked.cc/module/rednet.html#v:run) run()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua#L465) Listen for modem messages and converts them into rednet messages, which may then be [received](https://tweaked.cc/module/rednet.html#v:receive) . This is automatically started in the background on computer startup, and should not be called manually. --- # redstone redstone ======== Get and set redstone signals adjacent to this computer. The [`redstone`](https://tweaked.cc/module/redstone.html) library exposes three "types" of redstone control: * Binary input/output ([`setOutput`](https://tweaked.cc/module/redstone.html#v:setOutput) /[`getInput`](https://tweaked.cc/module/redstone.html#v:getInput) ): These simply check if a redstone wire has any input or output. A signal strength of 1 and 15 are treated the same. * Analogue input/output ([`setAnalogOutput`](https://tweaked.cc/module/redstone.html#v:setAnalogOutput) /[`getAnalogInput`](https://tweaked.cc/module/redstone.html#v:getAnalogInput) ): These work with the actual signal strength of the redstone wired, from 0 to 15. * Bundled cables ([`setBundledOutput`](https://tweaked.cc/module/redstone.html#v:setBundledOutput) /[`getBundledInput`](https://tweaked.cc/module/redstone.html#v:getBundledInput) ): These interact with "bundled" cables, such as those from Project:Red. These allow you to send 16 separate on/off signals. Each channel corresponds to a colour, with the first being [`colors.white`](https://tweaked.cc/module/colors.html#v:white) and the last [`colors.black`](https://tweaked.cc/module/colors.html#v:black) . Whenever a redstone input changes, a [`redstone`](https://tweaked.cc/event/redstone.html) event will be fired. This may be used instead of repeativly polling. This module may also be referred to as `rs`. For example, one may call `rs.getSides()` instead of [`getSides`](https://tweaked.cc/module/redstone.html#v:getSides) . ### Usage * Toggle the redstone signal above the computer every 0.5 seconds. Run ᐅ while true do [redstone.setOutput](https://tweaked.cc/module/redstone.html#v:setOutput "Turn the redstone signal of a specific side on or off.") ("top", not [redstone.getOutput](https://tweaked.cc/module/redstone.html#v:getOutput "Get the current redstone output of a specific side.") ("top")) sleep(0.5) end * Mimic a redstone comparator in [subtraction mode](https://minecraft.wiki/w/Redstone_Comparator#Subtract_signal_strength "Redstone Comparator on the Minecraft wiki.") . Run ᐅ while true do local rear \= rs.getAnalogueInput("back") local sides \= math.max(rs.getAnalogueInput("left"), rs.getAnalogueInput("right")) rs.setAnalogueOutput("front", math.max(rear \- sides, 0)) [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("redstone") \-- Wait for a change to inputs. end | | | | --- | --- | | [getSides()](https://tweaked.cc/module/redstone.html#v:getSides) | Returns a table containing the six sides of the computer. | | [setOutput(side, on)](https://tweaked.cc/module/redstone.html#v:setOutput) | Turn the redstone signal of a specific side on or off. | | [getOutput(side)](https://tweaked.cc/module/redstone.html#v:getOutput) | Get the current redstone output of a specific side. | | [getInput(side)](https://tweaked.cc/module/redstone.html#v:getInput) | Get the current redstone input of a specific side. | | [setAnalogOutput(side, value)](https://tweaked.cc/module/redstone.html#v:setAnalogOutput) | Set the redstone signal strength for a specific side. | | [setAnalogueOutput(side, value)](https://tweaked.cc/module/redstone.html#v:setAnalogueOutput) | Set the redstone signal strength for a specific side. | | [getAnalogOutput(side)](https://tweaked.cc/module/redstone.html#v:getAnalogOutput) | Get the redstone output signal strength for a specific side. | | [getAnalogueOutput(side)](https://tweaked.cc/module/redstone.html#v:getAnalogueOutput) | Get the redstone output signal strength for a specific side. | | [getAnalogInput(side)](https://tweaked.cc/module/redstone.html#v:getAnalogInput) | Get the redstone input signal strength for a specific side. | | [getAnalogueInput(side)](https://tweaked.cc/module/redstone.html#v:getAnalogueInput) | Get the redstone input signal strength for a specific side. | | [setBundledOutput(side, output)](https://tweaked.cc/module/redstone.html#v:setBundledOutput) | Set the bundled cable output for a specific side. | | [getBundledOutput(side)](https://tweaked.cc/module/redstone.html#v:getBundledOutput) | Get the bundled cable output for a specific side. | | [getBundledInput(side)](https://tweaked.cc/module/redstone.html#v:getBundledInput) | Get the bundled cable input for a specific side. | | [testBundledInput(side, mask)](https://tweaked.cc/module/redstone.html#v:testBundledInput) | Determine if a specific combination of colours are on for the given side. | [](https://tweaked.cc/module/redstone.html#v:getSides) getSides()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneAPI.java#L73) Returns a table containing the six sides of the computer. Namely, "top", "bottom", "left", "right", "front" and "back". ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } A table of valid sides. ### Changes * **New in version 1.2** [](https://tweaked.cc/module/redstone.html#v:setOutput) setOutput(side, on)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L27) Turn the redstone signal of a specific side on or off. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to set. 2. on `boolean` Whether the redstone signal should be on or off. When on, a signal strength of 15 is emitted. [](https://tweaked.cc/module/redstone.html#v:getOutput) getOutput(side)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L39) Get the current redstone output of a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to get. ### Returns 1. `boolean` Whether the redstone output is on or off. ### See also * **[`setOutput`](https://tweaked.cc/module/redstone.html#v:setOutput) ** [](https://tweaked.cc/module/redstone.html#v:getInput) getInput(side)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L50) Get the current redstone input of a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to get. ### Returns 1. `boolean` Whether the redstone input is on or off. [](https://tweaked.cc/module/redstone.html#v:setAnalogOutput) setAnalogOutput(side, value)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L63) Set the redstone signal strength for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to set. 2. value `number` The signal strength between 0 and 15. ### Throws * If `value` is not between 0 and 15. ### Changes * **New in version 1.51** [](https://tweaked.cc/module/redstone.html#v:setAnalogueOutput) setAnalogueOutput(side, value)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L63) Set the redstone signal strength for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to set. 2. value `number` The signal strength between 0 and 15. ### Throws * If `value` is not between 0 and 15. ### Changes * **New in version 1.51** [](https://tweaked.cc/module/redstone.html#v:getAnalogOutput) getAnalogOutput(side)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L77) Get the redstone output signal strength for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to get. ### Returns 1. `number` The output signal strength, between 0 and 15. ### See also * **[`setAnalogOutput`](https://tweaked.cc/module/redstone.html#v:setAnalogOutput) ** ### Changes * **New in version 1.51** [](https://tweaked.cc/module/redstone.html#v:getAnalogueOutput) getAnalogueOutput(side)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L77) Get the redstone output signal strength for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to get. ### Returns 1. `number` The output signal strength, between 0 and 15. ### See also * **[`setAnalogOutput`](https://tweaked.cc/module/redstone.html#v:setAnalogOutput) ** ### Changes * **New in version 1.51** [](https://tweaked.cc/module/redstone.html#v:getAnalogInput) getAnalogInput(side)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L89) Get the redstone input signal strength for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to get. ### Returns 1. `number` The input signal strength, between 0 and 15. ### Changes * **New in version 1.51** [](https://tweaked.cc/module/redstone.html#v:getAnalogueInput) getAnalogueInput(side)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L89) Get the redstone input signal strength for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to get. ### Returns 1. `number` The input signal strength, between 0 and 15. ### Changes * **New in version 1.51** [](https://tweaked.cc/module/redstone.html#v:setBundledOutput) setBundledOutput(side, output)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L102) Set the bundled cable output for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to set. 2. output `number` The colour bitmask to set. ### See also * **[`colors.subtract`](https://tweaked.cc/module/colors.html#v:subtract) ** For removing a colour from the bitmask. * **[`colors.combine`](https://tweaked.cc/module/colors.html#v:combine) ** For adding a color to the bitmask. [](https://tweaked.cc/module/redstone.html#v:getBundledOutput) getBundledOutput(side)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L113) Get the bundled cable output for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to get. ### Returns 1. `number` The bundle cable's output. [](https://tweaked.cc/module/redstone.html#v:getBundledInput) getBundledInput(side)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L125) Get the bundled cable input for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to get. ### Returns 1. `number` The bundle cable's input. ### See also * **[`testBundledInput`](https://tweaked.cc/module/redstone.html#v:testBundledInput) ** To determine if a specific colour is set. [](https://tweaked.cc/module/redstone.html#v:testBundledInput) testBundledInput(side, mask)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L142) Determine if a specific combination of colours are on for the given side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to test. 2. mask `number` The mask to test. ### Returns 1. `boolean` If the colours are on. ### Usage * Check if [`colors.white`](https://tweaked.cc/module/colors.html#v:white) and [`colors.black`](https://tweaked.cc/module/colors.html#v:black) are on above this block. Run ᐅ print([redstone.testBundledInput](https://tweaked.cc/module/redstone.html#v:testBundledInput "Determine if a specific combination of colours are on for the given side.") ("top", [colors.combine](https://tweaked.cc/module/colors.html#v:combine "Combines a set of colors (or sets of colors) into a larger set.") ([colors.white](https://tweaked.cc/module/colors.html#v:white "White: Written as 0 in paint files and term.blit, has a default terminal colour of #F0F0F0.") , [colors.black](https://tweaked.cc/module/colors.html#v:black "Black: Written as f in paint files and term.blit, has a default terminal colour of #111111.") ))) ### See also * **[`getBundledInput`](https://tweaked.cc/module/redstone.html#v:getBundledInput) ** --- # settings settings ======== Read and write configuration options for CraftOS and your programs. When a computer starts, it reads the current value of settings from the `/.settings` file. These values then may be [read](https://tweaked.cc/module/settings.html#v:get) or [modified](https://tweaked.cc/module/settings.html#v:set) . Any modifications to a settings, either from loading a file ([`settings.load`](https://tweaked.cc/module/settings.html#v:load) ) or directly setting it ([`settings.set`](https://tweaked.cc/module/settings.html#v:set) , [`settings.unset`](https://tweaked.cc/module/settings.html#v:unset) ) will queue a [`setting_changed`](https://tweaked.cc/event/setting_changed.html) event. This may be listened to by programs to reload settings while running. ##### ⚠ warning Calling [`settings.set`](https://tweaked.cc/module/settings.html#v:set) does _not_ update the settings file by default. You _must_ call [`settings.save`](https://tweaked.cc/module/settings.html#v:save) to persist values. ### Usage * Define an basic setting `123` and read its value. Run ᐅ [settings.define](https://tweaked.cc/module/settings.html#v:define "Define a new setting, optional specifying various properties about it.") ("my.setting", { description \= "An example setting", default \= 123, type \= "number", }) print("my.setting = " .. [settings.get](https://tweaked.cc/module/settings.html#v:get "Get the value of a setting.") ("my.setting")) \-- 123 You can then use the `set` program to change its value (e.g. `set my.setting 456`), and then re-run the `example` program to check it has changed. ### See also * **[`setting_changed`](https://tweaked.cc/event/setting_changed.html) ** ### Changes * **New in version 1.78** * **Changed in version 1.87.0:** [`setting_changed`](https://tweaked.cc/event/setting_changed.html) event is now queued when settings are changed. | | | | --- | --- | | [define(name \[, options\])](https://tweaked.cc/module/settings.html#v:define) | Define a new setting, optional specifying various properties about it. | | [undefine(name)](https://tweaked.cc/module/settings.html#v:undefine) | Remove a [definition](https://tweaked.cc/module/settings.html#v:define)
of a setting. | | [set(name, value)](https://tweaked.cc/module/settings.html#v:set) | Set the value of a setting. | | [get(name \[, default\])](https://tweaked.cc/module/settings.html#v:get) | Get the value of a setting. | | [getDetails(name)](https://tweaked.cc/module/settings.html#v:getDetails) | Get details about a specific setting. | | [unset(name)](https://tweaked.cc/module/settings.html#v:unset) | Remove the value of a setting, setting it to the default. | | [clear()](https://tweaked.cc/module/settings.html#v:clear) | Resets the value of all settings. | | [getNames()](https://tweaked.cc/module/settings.html#v:getNames) | Get the names of all currently defined settings. | | [load(\[path=".settings"\])](https://tweaked.cc/module/settings.html#v:load) | Load settings from the given file. | | [save(\[path=".settings"\])](https://tweaked.cc/module/settings.html#v:save) | Save settings to the given file. | [](https://tweaked.cc/module/settings.html#v:define) define(name \[, options\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua#L74) Define a new setting, optional specifying various properties about it. While settings do not have to be added before being used, doing so allows you to provide defaults and additional metadata. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of this option 2. options? { description? = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) , default? = `any`, type? = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) } Options for this setting. This table accepts the following fields: * `description`: A description which may be printed when running the `set` program. * `default`: A default value, which is returned by [`settings.get`](https://tweaked.cc/module/settings.html#v:get) if the setting has not been changed. * `type`: Require values to be of this type. [Setting](https://tweaked.cc/module/settings.html#v:set) the value to another type will error. Must be one of: `"number"`, `"string"`, `"boolean"`, or `"table"`. ### Changes * **New in version 1.87.0** [](https://tweaked.cc/module/settings.html#v:undefine) undefine(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua#L102) Remove a [definition](https://tweaked.cc/module/settings.html#v:define) of a setting. If a setting has been changed, this does not remove its value. Use [`settings.unset`](https://tweaked.cc/module/settings.html#v:unset) for that. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of this option ### Changes * **New in version 1.87.0** [](https://tweaked.cc/module/settings.html#v:set) set(name, value)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua#L133) Set the value of a setting. ##### ⚠ warning Calling [`settings.set`](https://tweaked.cc/module/settings.html#v:set) does _not_ update the settings file by default. You _must_ call [`settings.save`](https://tweaked.cc/module/settings.html#v:save) to persist values. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the setting to set 2. value The setting's value. This cannot be `nil`, and must be serialisable by [`textutils.serialize`](https://tweaked.cc/module/textutils.html#v:serialize) . ### Throws * If this value cannot be serialised ### See also * **[`settings.unset`](https://tweaked.cc/module/settings.html#v:unset) ** [](https://tweaked.cc/module/settings.html#v:get) get(name \[, default\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua#L151) Get the value of a setting. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the setting to get. 2. default? The value to use should there be pre-existing value for this setting. If not given, it will use the setting's default value if given, or `nil` otherwise. ### Returns 1. The setting's, or the default if the setting has not been changed. ### Changes * **Changed in version 1.87.0:** Now respects default value if pre-defined and `default` is unset. [](https://tweaked.cc/module/settings.html#v:getDetails) getDetails(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua#L171) Get details about a specific setting. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the setting to get. ### Returns 1. { description? = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) , default? = `any`, type? = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) , value? = `any` } Information about this setting. This includes all information from [`settings.define`](https://tweaked.cc/module/settings.html#v:define) , as well as this setting's value. ### Changes * **New in version 1.87.0** [](https://tweaked.cc/module/settings.html#v:unset) unset(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua#L188) Remove the value of a setting, setting it to the default. [`settings.get`](https://tweaked.cc/module/settings.html#v:get) will return the default value until the setting's value is [set](https://tweaked.cc/module/settings.html#v:set) , or the computer is rebooted. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the setting to unset. ### See also * **[`settings.set`](https://tweaked.cc/module/settings.html#v:set) ** * **[`settings.clear`](https://tweaked.cc/module/settings.html#v:clear) ** [](https://tweaked.cc/module/settings.html#v:clear) clear()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua#L197) Resets the value of all settings. Equivalent to calling [`settings.unset`](https://tweaked.cc/module/settings.html#v:unset) on every setting. ### See also * **[`settings.unset`](https://tweaked.cc/module/settings.html#v:unset) ** [](https://tweaked.cc/module/settings.html#v:getNames) getNames()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua#L207) Get the names of all currently defined settings. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) } An alphabetically sorted list of all currently-defined settings. [](https://tweaked.cc/module/settings.html#v:load) load(\[path=".settings"\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua#L231) Load settings from the given file. Existing settings will be merged with any pre-existing ones. Conflicting entries will be overwritten, but any others will be preserved. ### Parameters 1. path? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) = The file to load from. ### Returns 1. `boolean` Whether settings were successfully read from this file. Reasons for failure may include the file not existing or being corrupted. ### See also * **[`settings.save`](https://tweaked.cc/module/settings.html#v:save) ** ### Changes * **Changed in version 1.87.0:** `path` is now optional. [](https://tweaked.cc/module/settings.html#v:save) save(\[path=".settings"\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua#L271) Save settings to the given file. This will entirely overwrite the pre-existing file. Settings defined in the file, but not currently loaded will be removed. ### Parameters 1. path? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) = The path to save settings to. ### Returns 1. `boolean` If the settings were successfully saved. ### See also * **[`settings.load`](https://tweaked.cc/module/settings.html#v:load) ** ### Changes * **Changed in version 1.87.0:** `path` is now optional. --- # shell shell ===== The shell API provides access to CraftOS's command line interface. It allows you to [start programs](https://tweaked.cc/module/shell.html#v:run) , [add completion for a program](https://tweaked.cc/module/shell.html#v:setCompletionFunction) , and much more. [`shell`](https://tweaked.cc/module/shell.html) is not a "true" API. Instead, it is a standard program, which injects its API into the programs that it launches. This allows for multiple shells to run at the same time, but means that the API is not available in the global environment, and so is unavailable to other [APIs](https://tweaked.cc/module/os.html#v:loadAPI) . Programs and the program path ----------------------------- When you run a command with the shell, either from the prompt or [from Lua code](https://tweaked.cc/module/shell.html#v:run) , the shell API performs several steps to work out which program to run: 1. Firstly, the shell attempts to resolve [aliases](https://tweaked.cc/module/shell.html#v:aliases) . This allows us to use multiple names for a single command. For example, the `list` program has two aliases: `ls` and `dir`. When you write `ls /rom`, that's expanded to `list /rom`. 2. Next, the shell attempts to find where the program actually is. For this, it uses the [program path](https://tweaked.cc/module/shell.html#v:path) . This is a colon separated list of directories, each of which is checked to see if it contains the program. `list` or `list.lua` doesn't exist in `.` (the current directory), so the shell now looks in `/rom/programs`, where `list.lua` can be found! 3. Finally, the shell reads the file and checks if the file starts with a `#!`. This is a [hashbang](https://en.wikipedia.org/wiki/Shebang_(Unix)) , which says that this file shouldn't be treated as Lua, but instead passed to _another_ program, the name of which should follow the `#!`. ### Changes * **Changed in version 1.103.0:** Added support for hashbangs. | | | | --- | --- | | [execute(command, ...)](https://tweaked.cc/module/shell.html#v:execute) | Run a program with the supplied arguments. | | [run(...)](https://tweaked.cc/module/shell.html#v:run) | Run a program with the supplied arguments. | | [exit()](https://tweaked.cc/module/shell.html#v:exit) | Exit the current shell. | | [dir()](https://tweaked.cc/module/shell.html#v:dir) | Return the current working directory. | | [setDir(dir)](https://tweaked.cc/module/shell.html#v:setDir) | Set the current working directory. | | [path()](https://tweaked.cc/module/shell.html#v:path) | Get the path where programs are located. | | [setPath(path)](https://tweaked.cc/module/shell.html#v:setPath) | Set the [current program path](https://tweaked.cc/module/shell.html#v:path)
. | | [resolve(path)](https://tweaked.cc/module/shell.html#v:resolve) | Resolve a relative path to an absolute path. | | [resolveProgram(command)](https://tweaked.cc/module/shell.html#v:resolveProgram) | Resolve a program, using the [program path](https://tweaked.cc/module/shell.html#v:path)
and list of [aliases](https://tweaked.cc/module/shell.html#v:aliases)
. | | [programs(\[include\_hidden\])](https://tweaked.cc/module/shell.html#v:programs) | Return a list of all programs on the [path](https://tweaked.cc/module/shell.html#v:path)
. | | [complete(sLine)](https://tweaked.cc/module/shell.html#v:complete) | Complete a shell command line. | | [completeProgram(program)](https://tweaked.cc/module/shell.html#v:completeProgram) | Complete the name of a program. | | [setCompletionFunction(program, complete)](https://tweaked.cc/module/shell.html#v:setCompletionFunction) | Set the completion function for a program. | | [getCompletionInfo()](https://tweaked.cc/module/shell.html#v:getCompletionInfo) | Get a table containing all completion functions. | | [getRunningProgram()](https://tweaked.cc/module/shell.html#v:getRunningProgram) | Returns the path to the currently running program. | | [setAlias(command, program)](https://tweaked.cc/module/shell.html#v:setAlias) | Add an alias for a program. | | [clearAlias(command)](https://tweaked.cc/module/shell.html#v:clearAlias) | Remove an alias. | | [aliases()](https://tweaked.cc/module/shell.html#v:aliases) | Get the current aliases for this shell. | | [openTab(...)](https://tweaked.cc/module/shell.html#v:openTab) | Open a new [`multishell`](https://tweaked.cc/module/multishell.html)
tab running a command. | | [switchTab(id)](https://tweaked.cc/module/shell.html#v:switchTab) | Switch to the [`multishell`](https://tweaked.cc/module/multishell.html)
tab with the given index. | [](https://tweaked.cc/module/shell.html#v:execute) execute(command, ...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L209) Run a program with the supplied arguments. Unlike [`shell.run`](https://tweaked.cc/module/shell.html#v:run) , each argument is passed to the program verbatim. While `shell.run("echo", "b c")` runs `echo` with `b` and `c`, `shell.execute("echo", "b c")` runs `echo` with a single argument `b c`. ### Parameters 1. command [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The program to execute. 2. ... [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Arguments to this program. ### Returns 1. `boolean` Whether the program exited successfully. ### Usage * Run `paint my-image` from within your program: Run ᐅ [shell.execute](https://tweaked.cc/module/shell.html#v:execute "Run a program with the supplied arguments.") ("paint", "my-image") ### Changes * **New in version 1.88.0** [](https://tweaked.cc/module/shell.html#v:run) run(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L263) Run a program with the supplied arguments. All arguments are concatenated together and then parsed as a command line. As a result, `shell.run("program a b")` is the same as `shell.run("program", "a", "b")`. ### Parameters 1. ... [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The program to run and its arguments. ### Returns 1. `boolean` Whether the program exited successfully. ### Usage * Run `paint my-image` from within your program: Run ᐅ [shell.run](https://tweaked.cc/module/shell.html#v:run "Run a program with the supplied arguments.") ("paint", "my-image") ### See also * **[`shell.execute`](https://tweaked.cc/module/shell.html#v:execute) ** Run a program directly without parsing the arguments. ### Changes * **Changed in version 1.80pr1:** Programs now get their own environment instead of sharing the same one. * **Changed in version 1.83.0:** `arg` is now added to the environment. [](https://tweaked.cc/module/shell.html#v:exit) exit()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L277) Exit the current shell. This does _not_ terminate your program, it simply makes the shell terminate after your program has finished. If this is the toplevel shell, then the computer will be shutdown. [](https://tweaked.cc/module/shell.html#v:dir) dir()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L287) Return the current working directory. This is what is displayed before the `>` of the shell prompt, and is used by [`shell.resolve`](https://tweaked.cc/module/shell.html#v:resolve) to handle relative paths. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The current working directory. ### See also * **[`setDir`](https://tweaked.cc/module/shell.html#v:setDir) ** To change the working directory. [](https://tweaked.cc/module/shell.html#v:setDir) setDir(dir)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L298) Set the current working directory. ### Parameters 1. dir [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The new working directory. ### Throws * If the path does not exist or is not a directory. ### Usage * Set the working directory to "rom" Run ᐅ [shell.setDir](https://tweaked.cc/module/shell.html#v:setDir "Set the current working directory.") ("rom") [](https://tweaked.cc/module/shell.html#v:path) path()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L315) Get the path where programs are located. The path is composed of a list of directory names in a string, each separated by a colon (`:`). On normal turtles will look in the current directory (`.`), `/rom/programs` and `/rom/programs/turtle` folder, making the path `.:/rom/programs:/rom/programs/turtle`. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The current shell's path. ### See also * **[`setPath`](https://tweaked.cc/module/shell.html#v:setPath) ** To change the current path. [](https://tweaked.cc/module/shell.html#v:setPath) setPath(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L326) Set the [current program path](https://tweaked.cc/module/shell.html#v:path) . Be careful to prefix directories with a `/`. Otherwise they will be searched for from the [current directory](https://tweaked.cc/module/shell.html#v:dir) , rather than the computer's root. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The new program path. ### Changes * **New in version 1.2** [](https://tweaked.cc/module/shell.html#v:resolve) resolve(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L343) Resolve a relative path to an absolute path. The [`fs`](https://tweaked.cc/module/fs.html) and [`io`](https://tweaked.cc/module/io.html) APIs work using absolute paths, and so we must convert any paths relative to the [current directory](https://tweaked.cc/module/shell.html#v:dir) to absolute ones. This does nothing when the path starts with `/`. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to resolve. ### Usage * Resolve `startup.lua` when in the `rom` folder. Run ᐅ [shell.setDir](https://tweaked.cc/module/shell.html#v:setDir "Set the current working directory.") ("rom") print([shell.resolve](https://tweaked.cc/module/shell.html#v:resolve "Resolve a relative path to an absolute path.") ("startup.lua")) \-- => rom/startup.lua [](https://tweaked.cc/module/shell.html#v:resolveProgram) resolveProgram(command)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L364) Resolve a program, using the [program path](https://tweaked.cc/module/shell.html#v:path) and list of [aliases](https://tweaked.cc/module/shell.html#v:aliases) . ### Parameters 1. command [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the program ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The absolute path to the program, or `nil` if it could not be found. ### Usage * Locate the `hello` program. Run ᐅ [shell.resolveProgram](https://tweaked.cc/module/shell.html#v:resolveProgram "Resolve a program, using the program path and list of aliases.") ("hello") \-- => rom/programs/fun/hello.lua ### Changes * **New in version 1.2** * **Changed in version 1.80pr1:** Now searches for files with and without the `.lua` extension. [](https://tweaked.cc/module/shell.html#v:programs) programs(\[include\_hidden\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L409) Return a list of all programs on the [path](https://tweaked.cc/module/shell.html#v:path) . ### Parameters 1. include\_hidden? `boolean` Include hidden files. Namely, any which start with `.`. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) } A list of available programs. ### Usage * Run ᐅ [textutils.tabulate](https://tweaked.cc/module/textutils.html#v:tabulate "Prints tables in a structured form.") ([shell.programs](https://tweaked.cc/module/shell.html#v:programs "Return a list of all programs on the path.") ()) ### Changes * **New in version 1.2** [](https://tweaked.cc/module/shell.html#v:complete) complete(sLine)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L523) Complete a shell command line. This accepts an incomplete command, and completes the program name or arguments. For instance, `l` will be completed to `ls`, and `ls ro` will be completed to `ls rom/`. Completion handlers for your program may be registered with [`shell.setCompletionFunction`](https://tweaked.cc/module/shell.html#v:setCompletionFunction) . ### Parameters 1. sLine [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The input to complete. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) } | nil The list of possible completions. ### See also * **[`_G.read`](https://tweaked.cc/module/_G.html#v:read) ** For more information about completion. * **[`shell.completeProgram`](https://tweaked.cc/module/shell.html#v:completeProgram) ** * **[`shell.setCompletionFunction`](https://tweaked.cc/module/shell.html#v:setCompletionFunction) ** * **[`shell.getCompletionInfo`](https://tweaked.cc/module/shell.html#v:getCompletionInfo) ** ### Changes * **New in version 1.74** [](https://tweaked.cc/module/shell.html#v:completeProgram) completeProgram(program)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L565) Complete the name of a program. ### Parameters 1. program [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of a program to complete. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) } A list of possible completions. ### See also * **[`cc.shell.completion.program`](https://tweaked.cc/library/cc.shell.completion.html#v:program) ** [](https://tweaked.cc/module/shell.html#v:setCompletionFunction) setCompletionFunction(program, complete)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L599) Set the completion function for a program. When the program is entered on the command line, this program will be called to provide auto-complete information. The completion function accepts four arguments: 1. The current shell. As completion functions are inherited, this is not guaranteed to be the shell you registered this function in. 2. The index of the argument currently being completed. 3. The current argument. This may be the empty string. 4. A list of the previous arguments. For instance, when completing `pastebin put rom/st` our pastebin completion function will receive the shell API, an index of 2, `rom/st` as the current argument, and a "previous" table of `{ "put" }`. This function may then wish to return a table containing `artup.lua`, indicating the entire command should be completed to `pastebin put rom/startup.lua`. You completion entries may also be followed by a space, if you wish to indicate another argument is expected. ### Parameters 1. program [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The path to the program. This should be an absolute path _without_ the leading `/`. 2. complete function(shell: [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) , index: `number`, argument: [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) , previous: { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) }):{ [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) } | nil The completion function. ### See also * **[`cc.shell.completion`](https://tweaked.cc/library/cc.shell.completion.html) ** Various utilities to help with writing completion functions. * **[`shell.complete`](https://tweaked.cc/module/shell.html#v:complete) ** * **[`_G.read`](https://tweaked.cc/module/_G.html#v:read) ** For more information about completion. ### Changes * **New in version 1.74** [](https://tweaked.cc/module/shell.html#v:getCompletionInfo) getCompletionInfo()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L614) Get a table containing all completion functions. This should only be needed when building custom shells. Use [`setCompletionFunction`](https://tweaked.cc/module/shell.html#v:setCompletionFunction) to add a completion function. ### Returns 1. { \[[`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ \] = { fnComplete = `function` } } A table mapping the absolute path of programs, to their completion functions. [](https://tweaked.cc/module/shell.html#v:getRunningProgram) getRunningProgram()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L622) Returns the path to the currently running program. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The absolute path to the running program. ### Changes * **New in version 1.3** [](https://tweaked.cc/module/shell.html#v:setAlias) setAlias(command, program)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L637) Add an alias for a program. ### Parameters 1. command [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the alias to add. 2. program [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name or path to the program. ### Usage * Alias `vim` to the `edit` program Run ᐅ [shell.setAlias](https://tweaked.cc/module/shell.html#v:setAlias "Add an alias for a program.") ("vim", "edit") ### Changes * **New in version 1.2** [](https://tweaked.cc/module/shell.html#v:clearAlias) clearAlias(command)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L646) Remove an alias. ### Parameters 1. command [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The alias name to remove. [](https://tweaked.cc/module/shell.html#v:aliases) aliases()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L662) Get the current aliases for this shell. Aliases are used to allow multiple commands to refer to a single program. For instance, the `list` program is aliased to `dir` or `ls`. Running `ls`, `dir` or `list` in the shell will all run the `list` program. ### Returns 1. { \[[`string`](https://www.lua.org/manual/5.1/manual.html#5.4)\ \] = [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) } A table, where the keys are the names of aliases, and the values are the path to the program. ### See also * **[`shell.setAlias`](https://tweaked.cc/module/shell.html#v:setAlias) ** * **[`shell.resolveProgram`](https://tweaked.cc/module/shell.html#v:resolveProgram) ** This uses aliases when resolving a program name to an absolute path. [](https://tweaked.cc/module/shell.html#v:openTab) openTab(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L688) Open a new [`multishell`](https://tweaked.cc/module/multishell.html) tab running a command. This behaves similarly to [`shell.run`](https://tweaked.cc/module/shell.html#v:run) , but instead returns the process index. This function is only available if the [`multishell`](https://tweaked.cc/module/multishell.html) API is. ### Parameters 1. ... [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The command line to run. ### Returns 1. `number` The ID of the new tab that was opened. ### Usage * Launch the Lua interpreter and switch to it. Run ᐅ local id \= [shell.openTab](https://tweaked.cc/module/shell.html#v:openTab "Open a new multishell tab running a command.") ("lua") [shell.switchTab](https://tweaked.cc/module/shell.html#v:switchTab "Switch to the multishell tab with the given index.") (id) ### See also * **[`shell.run`](https://tweaked.cc/module/shell.html#v:run) ** * **[`multishell.launch`](https://tweaked.cc/module/multishell.html#v:launch) ** ### Changes * **New in version 1.6** [](https://tweaked.cc/module/shell.html#v:switchTab) switchTab(id)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua#L708) Switch to the [`multishell`](https://tweaked.cc/module/multishell.html) tab with the given index. ### Parameters 1. id `number` The tab to switch to. ### See also * **[`multishell.setFocus`](https://tweaked.cc/module/multishell.html#v:setFocus) ** ### Changes * **New in version 1.6** --- # textutils textutils ========= Helpful utilities for formatting and manipulating strings. ### Changes * **New in version 1.2** | | | | --- | --- | | [slowWrite(text \[, rate\])](https://tweaked.cc/module/textutils.html#v:slowWrite) | Slowly writes string text at current cursor position, character-by-character. | | [slowPrint(sText \[, nRate\])](https://tweaked.cc/module/textutils.html#v:slowPrint) | Slowly prints string text at current cursor position, character-by-character. | | [formatTime(nTime \[, bTwentyFourHour\])](https://tweaked.cc/module/textutils.html#v:formatTime) | Takes input time and formats it in a more readable format such as `6:30 PM`. | | [pagedPrint(text \[, free\_lines\])](https://tweaked.cc/module/textutils.html#v:pagedPrint) | Prints a given string to the display. | | [tabulate(...)](https://tweaked.cc/module/textutils.html#v:tabulate) | Prints tables in a structured form. | | [pagedTabulate(...)](https://tweaked.cc/module/textutils.html#v:pagedTabulate) | Prints tables in a structured form, stopping and prompting for input should the result not fit on the terminal. | | [empty\_json\_array](https://tweaked.cc/module/textutils.html#v:empty_json_array) | A table representing an empty JSON array, in order to distinguish it from an empty JSON object. | | [json\_null](https://tweaked.cc/module/textutils.html#v:json_null) | A table representing the JSON null value. | | [serialize(t, opts)](https://tweaked.cc/module/textutils.html#v:serialize) | Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing. | | [serialise(t, opts)](https://tweaked.cc/module/textutils.html#v:serialise) | Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing. | | [unserialize(s)](https://tweaked.cc/module/textutils.html#v:unserialize) | Converts a serialised string back into a reassembled Lua object. | | [unserialise(s)](https://tweaked.cc/module/textutils.html#v:unserialise) | Converts a serialised string back into a reassembled Lua object. | | [serializeJSON(...)](https://tweaked.cc/module/textutils.html#v:serializeJSON) | Returns a JSON representation of the given data. | | [serialiseJSON(...)](https://tweaked.cc/module/textutils.html#v:serialiseJSON) | Returns a JSON representation of the given data. | | [unserializeJSON(s \[, options\])](https://tweaked.cc/module/textutils.html#v:unserializeJSON) | Converts a serialised JSON string back into a reassembled Lua object. | | [unserialiseJSON(s \[, options\])](https://tweaked.cc/module/textutils.html#v:unserialiseJSON) | Converts a serialised JSON string back into a reassembled Lua object. | | [urlEncode(str)](https://tweaked.cc/module/textutils.html#v:urlEncode) | Replaces certain characters in a string to make it safe for use in URLs or POST data. | | [complete(sSearchText \[, tSearchTable\])](https://tweaked.cc/module/textutils.html#v:complete) | Provides a list of possible completions for a partial Lua expression. | [](https://tweaked.cc/module/textutils.html#v:slowWrite) slowWrite(text \[, rate\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L27) Slowly writes string text at current cursor position, character-by-character. Like [`_G.write`](https://tweaked.cc/module/_G.html#v:write) , this does not insert a newline at the end. ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The the text to write to the screen 2. rate? `number` The number of characters to write each second, Defaults to 20. ### Usage * Run ᐅ [textutils.slowWrite](https://tweaked.cc/module/textutils.html#v:slowWrite "Slowly writes string text at current cursor position, character-by-character.") ("Hello, world!") * Run ᐅ [textutils.slowWrite](https://tweaked.cc/module/textutils.html#v:slowWrite "Slowly writes string text at current cursor position, character-by-character.") ("Hello, world!", 5) ### Changes * **New in version 1.3** [](https://tweaked.cc/module/textutils.html#v:slowPrint) slowPrint(sText \[, nRate\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L54) Slowly prints string text at current cursor position, character-by-character. Like [`print`](https://www.lua.org/manual/5.1/manual.html#pdf-print) , this inserts a newline after printing. ### Parameters 1. sText [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The the text to write to the screen 2. nRate? `number` The number of characters to write each second, Defaults to 20. ### Usage * Run ᐅ [textutils.slowPrint](https://tweaked.cc/module/textutils.html#v:slowPrint "Slowly prints string text at current cursor position, character-by-character.") ("Hello, world!") * Run ᐅ [textutils.slowPrint](https://tweaked.cc/module/textutils.html#v:slowPrint "Slowly prints string text at current cursor position, character-by-character.") ("Hello, world!", 5) [](https://tweaked.cc/module/textutils.html#v:formatTime) formatTime(nTime \[, bTwentyFourHour\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L71) Takes input time and formats it in a more readable format such as `6:30 PM`. ### Parameters 1. nTime `number` The time to format, as provided by [`os.time`](https://tweaked.cc/module/os.html#v:time) . 2. bTwentyFourHour? `boolean` Whether to format this as a 24-hour clock (`18:30`) rather than a 12-hour one (`6:30 AM`) ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The formatted time ### Usage * Print the current in-game time as a 12-hour clock. Run ᐅ [textutils.formatTime](https://tweaked.cc/module/textutils.html#v:formatTime "Takes input time and formats it in a more readable format such as 6:30 PM.") ([os.time](https://tweaked.cc/module/os.html#v:time "Returns the current time depending on the string passed in.") ()) * Print the local time as a 24-hour clock. Run ᐅ [textutils.formatTime](https://tweaked.cc/module/textutils.html#v:formatTime "Takes input time and formats it in a more readable format such as 6:30 PM.") ([os.time](https://tweaked.cc/module/os.html#v:time "Returns the current time depending on the string passed in.") ("local"), true) [](https://tweaked.cc/module/textutils.html#v:pagedPrint) pagedPrint(text \[, free\_lines\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L141) Prints a given string to the display. If the action can be completed without scrolling, it acts much the same as [`print`](https://www.lua.org/manual/5.1/manual.html#pdf-print) ; otherwise, it will throw up a "Press any key to continue" prompt at the bottom of the display. Each press will cause it to scroll down and write a single line more before prompting again, if need be. ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The text to print to the screen. 2. free\_lines? `number` The number of lines which will be automatically scrolled before the first prompt appears (meaning free\_lines + 1 lines will be printed). This can be set to the cursor's y position - 2 to always try to fill the screen. Defaults to 0, meaning only one line is displayed before prompting. ### Returns 1. `number` The number of lines printed. ### Usage * Generates several lines of text and then prints it, paging once the bottom of the terminal is reached. Run ᐅ local lines \= {} for i \= 1, 30 do lines\[i\] \= ("This is line #%d"):format(i) end local message \= table.concat(lines, "\\n") local width, height \= [term.getCursorPos](https://tweaked.cc/module/term.html#v:getCursorPos "Get the position of the cursor.") () [textutils.pagedPrint](https://tweaked.cc/module/textutils.html#v:pagedPrint "Prints a given string to the display.") (message, height \- 2) [](https://tweaked.cc/module/textutils.html#v:tabulate) tabulate(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L251) Prints tables in a structured form. This accepts multiple arguments, either a table or a number. When encountering a table, this will be treated as a table row, with each column width being auto-adjusted. When encountering a number, this sets the text color of the subsequent rows to it. ### Parameters 1. ... { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } | `number` The rows and text colors to display. ### Usage * Run ᐅ [textutils.tabulate](https://tweaked.cc/module/textutils.html#v:tabulate "Prints tables in a structured form.") ( [colors.orange](https://tweaked.cc/module/colors.html#v:orange "Orange: Written as 1 in paint files and term.blit, has a default terminal colour of #F2B233.") , { "1", "2", "3" }, [colors.lightBlue](https://tweaked.cc/module/colors.html#v:lightBlue "Light blue: Written as 3 in paint files and term.blit, has a default terminal colour of #99B2F2.") , { "A", "B", "C" } ) ### Changes * **New in version 1.3** [](https://tweaked.cc/module/textutils.html#v:pagedTabulate) pagedTabulate(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L273) Prints tables in a structured form, stopping and prompting for input should the result not fit on the terminal. This functions identically to [`textutils.tabulate`](https://tweaked.cc/module/textutils.html#v:tabulate) , but will prompt for user input should the whole output not fit on the display. ### Parameters 1. ... { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } | `number` The rows and text colors to display. ### Usage * Generates a long table, tabulates it, and prints it to the screen. Run ᐅ local rows \= {} for i \= 1, 30 do rows\[i\] \= {("Row #%d"):format(i), math.random(1, 400)} end [textutils.pagedTabulate](https://tweaked.cc/module/textutils.html#v:pagedTabulate "Prints tables in a structured form, stopping and prompting for input should the result not fit on the terminal.") ([colors.orange](https://tweaked.cc/module/colors.html#v:orange "Orange: Written as 1 in paint files and term.blit, has a default terminal colour of #F2B233.") , {"Column", "Value"}, [colors.lightBlue](https://tweaked.cc/module/colors.html#v:lightBlue "Light blue: Written as 3 in paint files and term.blit, has a default terminal colour of #99B2F2.") , table.unpack(rows)) ### See also * **[`textutils.tabulate`](https://tweaked.cc/module/textutils.html#v:tabulate) ** * **[`textutils.pagedPrint`](https://tweaked.cc/module/textutils.html#v:pagedPrint) ** ### Changes * **New in version 1.3** [](https://tweaked.cc/module/textutils.html#v:empty_json_array) empty\_json\_array[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L398) A table representing an empty JSON array, in order to distinguish it from an empty JSON object. The contents of this table should not be modified. ### Usage * Run ᐅ [textutils.serialiseJSON](https://tweaked.cc/module/textutils.html#v:serialiseJSON "Returns a JSON representation of the given data.") ([textutils.empty\_json\_array](https://tweaked.cc/module/textutils.html#v:empty_json_array "A table representing an empty JSON array, in order to distinguish it from an empty JSON object.") ) ### See also * **[`textutils.serialiseJSON`](https://tweaked.cc/module/textutils.html#v:serialiseJSON) ** * **[`textutils.unserialiseJSON`](https://tweaked.cc/module/textutils.html#v:unserialiseJSON) ** [](https://tweaked.cc/module/textutils.html#v:json_null) json\_null[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L407) A table representing the JSON null value. The contents of this table should not be modified. ### Usage * Run ᐅ [textutils.serialiseJSON](https://tweaked.cc/module/textutils.html#v:serialiseJSON "Returns a JSON representation of the given data.") ([textutils.json\_null](https://tweaked.cc/module/textutils.html#v:json_null "A table representing the JSON null value.") ) ### See also * **[`textutils.serialiseJSON`](https://tweaked.cc/module/textutils.html#v:serialiseJSON) ** * **[`textutils.unserialiseJSON`](https://tweaked.cc/module/textutils.html#v:unserialiseJSON) ** [](https://tweaked.cc/module/textutils.html#v:serialize) serialize(t, opts)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L814) Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing. ### Parameters 1. t The object to serialise 2. opts { compact? = `boolean`, allow\_repetitions? = `boolean` } Options for serialisation. * `compact`: Do not emit indentation and other whitespace between terms. * `allow_repetitions`: Relax the check for recursive tables, allowing them to appear multiple times (as long as tables do not appear inside themselves). ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The serialised representation ### Throws * If the object contains a value which cannot be serialised. This includes functions and tables which appear multiple times. ### Usage * Serialise a basic table. Run ᐅ [textutils.serialise](https://tweaked.cc/module/textutils.html#v:serialise "Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing.") ({ 1, 2, 3, a \= 1, \["another key"\] \= { true } }) * Demonstrates some of the other options Run ᐅ local tbl \= { 1, 2, 3 } print([textutils.serialise](https://tweaked.cc/module/textutils.html#v:serialise "Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing.") ({ tbl, tbl }, { allow\_repetitions \= true })) print([textutils.serialise](https://tweaked.cc/module/textutils.html#v:serialise "Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing.") (tbl, { compact \= true })) ### See also * **[`cc.pretty.pretty_print`](https://tweaked.cc/library/cc.pretty.html#v:pretty_print) ** An alternative way to display a table, often more suitable for pretty printing. ### Changes * **New in version 1.3** * **Changed in version 1.97.0:** Added `opts` argument. [](https://tweaked.cc/module/textutils.html#v:serialise) serialise(t, opts)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L814) Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing. ### Parameters 1. t The object to serialise 2. opts { compact? = `boolean`, allow\_repetitions? = `boolean` } Options for serialisation. * `compact`: Do not emit indentation and other whitespace between terms. * `allow_repetitions`: Relax the check for recursive tables, allowing them to appear multiple times (as long as tables do not appear inside themselves). ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The serialised representation ### Throws * If the object contains a value which cannot be serialised. This includes functions and tables which appear multiple times. ### Usage * Serialise a basic table. Run ᐅ [textutils.serialise](https://tweaked.cc/module/textutils.html#v:serialise "Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing.") ({ 1, 2, 3, a \= 1, \["another key"\] \= { true } }) * Demonstrates some of the other options Run ᐅ local tbl \= { 1, 2, 3 } print([textutils.serialise](https://tweaked.cc/module/textutils.html#v:serialise "Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing.") ({ tbl, tbl }, { allow\_repetitions \= true })) print([textutils.serialise](https://tweaked.cc/module/textutils.html#v:serialise "Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing.") (tbl, { compact \= true })) ### See also * **[`cc.pretty.pretty_print`](https://tweaked.cc/library/cc.pretty.html#v:pretty_print) ** An alternative way to display a table, often more suitable for pretty printing. ### Changes * **New in version 1.3** * **Changed in version 1.97.0:** Added `opts` argument. [](https://tweaked.cc/module/textutils.html#v:unserialize) unserialize(s)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L837) Converts a serialised string back into a reassembled Lua object. This is mainly used together with [`textutils.serialise`](https://tweaked.cc/module/textutils.html#v:serialise) . ### Parameters 1. s [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The serialised string to deserialise. ### Returns 1. The deserialised object #### Or 1. nil If the object could not be deserialised. ### Changes * **New in version 1.3** [](https://tweaked.cc/module/textutils.html#v:unserialise) unserialise(s)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L837) Converts a serialised string back into a reassembled Lua object. This is mainly used together with [`textutils.serialise`](https://tweaked.cc/module/textutils.html#v:serialise) . ### Parameters 1. s [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The serialised string to deserialise. ### Returns 1. The deserialised object #### Or 1. nil If the object could not be deserialised. ### Changes * **New in version 1.3** [](https://tweaked.cc/module/textutils.html#v:serializeJSON) serializeJSON(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L916) Returns a JSON representation of the given data. This is largely intended for interacting with various functions from the [`commands`](https://tweaked.cc/module/commands.html) API, though may also be used in making [`http`](https://tweaked.cc/module/http.html) requests. Lua has a rather different data model to Javascript/JSON. As a result, some Lua values do not serialise cleanly into JSON. * Lua tables can contain arbitrary key-value pairs, but JSON only accepts arrays, and objects (which require a string key). When serialising a table, if it only has numeric keys, then it will be treated as an array. Otherwise, the table will be serialised to an object using the string keys. Non-string keys (such as numbers or tables) will be dropped. A consequence of this is that an empty table will always be serialised to an object, not an array. [`textutils.empty_json_array`](https://tweaked.cc/module/textutils.html#v:empty_json_array) may be used to express an empty array. * Lua strings are a sequence of raw bytes, and do not have any specific encoding. However, JSON strings must be valid unicode. By default, non-ASCII characters in a string are serialised to their unicode code point (for instance, `"\xfe"` is converted to `"\u00fe"`). The `unicode_strings` option may be set to treat all input strings as UTF-8. * Lua does not distinguish between missing keys (`undefined` in JS) and ones explicitly set to `null`. As a result `{ x = nil }` is serialised to `{}`. [`textutils.json_null`](https://tweaked.cc/module/textutils.html#v:json_null) may be used to get an explicit null value (`{ x = textutils.json_null }` will serialise to `{"x": null}`). ### Parameters 1. t The value to serialise. Like [`textutils.serialise`](https://tweaked.cc/module/textutils.html#v:serialise) , this should not contain recursive tables or functions. 2. options? { nbt\_style? = `boolean`, unicode\_strings? = `boolean`, allow\_repetitions? = `boolean` } Options for serialisation. * `nbt_style`: Whether to produce NBT-style JSON (non-quoted keys) instead of standard JSON. * `unicode_strings`: Whether to treat strings as containing UTF-8 characters instead of using the default 8-bit character set. * `allow_repetitions`: Relax the check for recursive tables, allowing them to appear multiple times (as long as tables do not appear inside themselves). #### Or 1. t The value to serialise. Like [`textutils.serialise`](https://tweaked.cc/module/textutils.html#v:serialise) , this should not contain recursive tables or functions. 2. bNBTStyle `boolean` Whether to produce NBT-style JSON (non-quoted keys) instead of standard JSON. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The JSON representation of the input. ### Throws * If the object contains a value which cannot be serialised. This includes functions and tables which appear multiple times. ### Usage * Serialise a simple object Run ᐅ [textutils.serialiseJSON](https://tweaked.cc/module/textutils.html#v:serialiseJSON "Returns a JSON representation of the given data.") ({ values \= { 1, "2", true } }) * Serialise an object to a NBT-style string Run ᐅ [textutils.serialiseJSON](https://tweaked.cc/module/textutils.html#v:serialiseJSON "Returns a JSON representation of the given data.") ({ values \= { 1, "2", true } }, { nbt\_style \= true }) ### See also * **[`textutils.json_null`](https://tweaked.cc/module/textutils.html#v:json_null) ** Use to serialise a JSON `null` value. * **[`textutils.empty_json_array`](https://tweaked.cc/module/textutils.html#v:empty_json_array) ** Use to serialise a JSON empty array. ### Changes * **New in version 1.7** * **Changed in version 1.106.0:** Added `options` overload and `unicode_strings` option. * **Changed in version 1.109.0:** Added `allow_repetitions` option. [](https://tweaked.cc/module/textutils.html#v:serialiseJSON) serialiseJSON(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L916) Returns a JSON representation of the given data. This is largely intended for interacting with various functions from the [`commands`](https://tweaked.cc/module/commands.html) API, though may also be used in making [`http`](https://tweaked.cc/module/http.html) requests. Lua has a rather different data model to Javascript/JSON. As a result, some Lua values do not serialise cleanly into JSON. * Lua tables can contain arbitrary key-value pairs, but JSON only accepts arrays, and objects (which require a string key). When serialising a table, if it only has numeric keys, then it will be treated as an array. Otherwise, the table will be serialised to an object using the string keys. Non-string keys (such as numbers or tables) will be dropped. A consequence of this is that an empty table will always be serialised to an object, not an array. [`textutils.empty_json_array`](https://tweaked.cc/module/textutils.html#v:empty_json_array) may be used to express an empty array. * Lua strings are a sequence of raw bytes, and do not have any specific encoding. However, JSON strings must be valid unicode. By default, non-ASCII characters in a string are serialised to their unicode code point (for instance, `"\xfe"` is converted to `"\u00fe"`). The `unicode_strings` option may be set to treat all input strings as UTF-8. * Lua does not distinguish between missing keys (`undefined` in JS) and ones explicitly set to `null`. As a result `{ x = nil }` is serialised to `{}`. [`textutils.json_null`](https://tweaked.cc/module/textutils.html#v:json_null) may be used to get an explicit null value (`{ x = textutils.json_null }` will serialise to `{"x": null}`). ### Parameters 1. t The value to serialise. Like [`textutils.serialise`](https://tweaked.cc/module/textutils.html#v:serialise) , this should not contain recursive tables or functions. 2. options? { nbt\_style? = `boolean`, unicode\_strings? = `boolean`, allow\_repetitions? = `boolean` } Options for serialisation. * `nbt_style`: Whether to produce NBT-style JSON (non-quoted keys) instead of standard JSON. * `unicode_strings`: Whether to treat strings as containing UTF-8 characters instead of using the default 8-bit character set. * `allow_repetitions`: Relax the check for recursive tables, allowing them to appear multiple times (as long as tables do not appear inside themselves). #### Or 1. t The value to serialise. Like [`textutils.serialise`](https://tweaked.cc/module/textutils.html#v:serialise) , this should not contain recursive tables or functions. 2. bNBTStyle `boolean` Whether to produce NBT-style JSON (non-quoted keys) instead of standard JSON. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The JSON representation of the input. ### Throws * If the object contains a value which cannot be serialised. This includes functions and tables which appear multiple times. ### Usage * Serialise a simple object Run ᐅ [textutils.serialiseJSON](https://tweaked.cc/module/textutils.html#v:serialiseJSON "Returns a JSON representation of the given data.") ({ values \= { 1, "2", true } }) * Serialise an object to a NBT-style string Run ᐅ [textutils.serialiseJSON](https://tweaked.cc/module/textutils.html#v:serialiseJSON "Returns a JSON representation of the given data.") ({ values \= { 1, "2", true } }, { nbt\_style \= true }) ### See also * **[`textutils.json_null`](https://tweaked.cc/module/textutils.html#v:json_null) ** Use to serialise a JSON `null` value. * **[`textutils.empty_json_array`](https://tweaked.cc/module/textutils.html#v:empty_json_array) ** Use to serialise a JSON empty array. ### Changes * **New in version 1.7** * **Changed in version 1.106.0:** Added `options` overload and `unicode_strings` option. * **Changed in version 1.109.0:** Added `allow_repetitions` option. [](https://tweaked.cc/module/textutils.html#v:unserializeJSON) unserializeJSON(s \[, options\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L540) Converts a serialised JSON string back into a reassembled Lua object. This may be used with [`textutils.serializeJSON`](https://tweaked.cc/module/textutils.html#v:serializeJSON) , or when communicating with command blocks or web APIs. If a `null` value is encountered, it is converted into `nil`. It can be converted into [`textutils.json_null`](https://tweaked.cc/module/textutils.html#v:json_null) with the `parse_null` option. If an empty array is encountered, it is converted into [`textutils.empty_json_array`](https://tweaked.cc/module/textutils.html#v:empty_json_array) . It can be converted into a new empty table with the `parse_empty_array` option. ### Parameters 1. s [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The serialised string to deserialise. 2. options? { nbt\_style? = `boolean`, parse\_null? = `boolean`, parse\_empty\_array? = `boolean` } Options which control how this JSON object is parsed. * `nbt_style`: When true, this will accept [stringified NBT](https://minecraft.wiki/w/NBT_format) strings, as produced by many commands. * `parse_null`: When true, `null` will be parsed as [`json_null`](https://tweaked.cc/module/textutils.html#v:json_null) , rather than `nil`. * `parse_empty_array`: When false, empty arrays will be parsed as a new table. By default (or when this value is true), they are parsed as [`empty_json_array`](https://tweaked.cc/module/textutils.html#v:empty_json_array) . ### Returns 1. The deserialised object #### Or 1. nil If the object could not be deserialised. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) A message describing why the JSON string is invalid. ### Usage * Unserialise a basic JSON object Run ᐅ [textutils.unserialiseJSON](https://tweaked.cc/module/textutils.html#v:unserialiseJSON "Converts a serialised JSON string back into a reassembled Lua object.") ('{"name": "Steve", "age": null}') * Unserialise a basic JSON object, returning null values as [`json_null`](https://tweaked.cc/module/textutils.html#v:json_null) . Run ᐅ [textutils.unserialiseJSON](https://tweaked.cc/module/textutils.html#v:unserialiseJSON "Converts a serialised JSON string back into a reassembled Lua object.") ('{"name": "Steve", "age": null}', { parse\_null \= true }) ### See also * **[`textutils.json_null`](https://tweaked.cc/module/textutils.html#v:json_null) ** Use to serialize a JSON `null` value. * **[`textutils.empty_json_array`](https://tweaked.cc/module/textutils.html#v:empty_json_array) ** Use to serialize a JSON empty array. ### Changes * **New in version 1.87.0** * **Changed in version 1.100.6:** Added `parse_empty_array` option [](https://tweaked.cc/module/textutils.html#v:unserialiseJSON) unserialiseJSON(s \[, options\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L540) Converts a serialised JSON string back into a reassembled Lua object. This may be used with [`textutils.serializeJSON`](https://tweaked.cc/module/textutils.html#v:serializeJSON) , or when communicating with command blocks or web APIs. If a `null` value is encountered, it is converted into `nil`. It can be converted into [`textutils.json_null`](https://tweaked.cc/module/textutils.html#v:json_null) with the `parse_null` option. If an empty array is encountered, it is converted into [`textutils.empty_json_array`](https://tweaked.cc/module/textutils.html#v:empty_json_array) . It can be converted into a new empty table with the `parse_empty_array` option. ### Parameters 1. s [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The serialised string to deserialise. 2. options? { nbt\_style? = `boolean`, parse\_null? = `boolean`, parse\_empty\_array? = `boolean` } Options which control how this JSON object is parsed. * `nbt_style`: When true, this will accept [stringified NBT](https://minecraft.wiki/w/NBT_format) strings, as produced by many commands. * `parse_null`: When true, `null` will be parsed as [`json_null`](https://tweaked.cc/module/textutils.html#v:json_null) , rather than `nil`. * `parse_empty_array`: When false, empty arrays will be parsed as a new table. By default (or when this value is true), they are parsed as [`empty_json_array`](https://tweaked.cc/module/textutils.html#v:empty_json_array) . ### Returns 1. The deserialised object #### Or 1. nil If the object could not be deserialised. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) A message describing why the JSON string is invalid. ### Usage * Unserialise a basic JSON object Run ᐅ [textutils.unserialiseJSON](https://tweaked.cc/module/textutils.html#v:unserialiseJSON "Converts a serialised JSON string back into a reassembled Lua object.") ('{"name": "Steve", "age": null}') * Unserialise a basic JSON object, returning null values as [`json_null`](https://tweaked.cc/module/textutils.html#v:json_null) . Run ᐅ [textutils.unserialiseJSON](https://tweaked.cc/module/textutils.html#v:unserialiseJSON "Converts a serialised JSON string back into a reassembled Lua object.") ('{"name": "Steve", "age": null}', { parse\_null \= true }) ### See also * **[`textutils.json_null`](https://tweaked.cc/module/textutils.html#v:json_null) ** Use to serialize a JSON `null` value. * **[`textutils.empty_json_array`](https://tweaked.cc/module/textutils.html#v:empty_json_array) ** Use to serialize a JSON empty array. ### Changes * **New in version 1.87.0** * **Changed in version 1.100.6:** Added `parse_empty_array` option [](https://tweaked.cc/module/textutils.html#v:urlEncode) urlEncode(str)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L944) Replaces certain characters in a string to make it safe for use in URLs or POST data. ### Parameters 1. str [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The string to encode ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The encoded string. ### Usage * Run ᐅ print("https://example.com/?view=" .. [textutils.urlEncode](https://tweaked.cc/module/textutils.html#v:urlEncode "Replaces certain characters in a string to make it safe for use in URLs or POST data.") ("some text&things")) ### Changes * **New in version 1.31** [](https://tweaked.cc/module/textutils.html#v:complete) complete(sSearchText \[, tSearchTable\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua#L983) Provides a list of possible completions for a partial Lua expression. If the completed element is a table, suggestions will have `.` appended to them. Similarly, functions have `(` appended to them. ### Parameters 1. sSearchText [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The partial expression to complete, such as a variable name or table index. 2. tSearchTable? [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The table to find variables in, defaulting to the global environment ([`_G`](https://tweaked.cc/module/_G.html) ). The function also searches the "parent" environment via the `__index` metatable field. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } The (possibly empty) list of completions. ### Usage * Run ᐅ [textutils.complete](https://tweaked.cc/module/textutils.html#v:complete "Provides a list of possible completions for a partial Lua expression.") ( "pa", \_ENV ) ### See also * **[`shell.setCompletionFunction`](https://tweaked.cc/module/shell.html#v:setCompletionFunction) ** * **[`_G.read`](https://tweaked.cc/module/_G.html#v:read) ** ### Changes * **New in version 1.74** --- # vector vector ====== A basic 3D vector type and some common vector operations. This may be useful when working with coordinates in Minecraft's world (such as those from the [`gps`](https://tweaked.cc/module/gps.html) API). An introduction to vectors can be found on [Wikipedia](http://en.wikipedia.org/wiki/Euclidean_vector) . ### Changes * **New in version 1.31** | | | | --- | --- | | [new(x, y, z)](https://tweaked.cc/module/vector.html#v:new) | Construct a new [`Vector`](https://tweaked.cc/module/vector.html#ty:Vector)
with the given coordinates. | [](https://tweaked.cc/module/vector.html#v:new) new(x, y, z)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua#L223) Construct a new [`Vector`](https://tweaked.cc/module/vector.html#ty:Vector) with the given coordinates. ### Parameters 1. x `number` The X coordinate or direction of the vector. 2. y `number` The Y coordinate or direction of the vector. 3. z `number` The Z coordinate or direction of the vector. ### Returns 1. [`Vector`](https://tweaked.cc/module/vector.html#ty:Vector) The constructed vector. ### Types ### [](https://tweaked.cc/module/vector.html#ty:Vector) Vector A 3-dimensional vector, with `x`, `y`, and `z` values. This is suitable for representing both position and directional vectors. [](https://tweaked.cc/module/vector.html#ty:Vector:add) Vector:add(o)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua#L34) Adds two vectors together. ### Parameters 1. o [`Vector`](https://tweaked.cc/module/vector.html#ty:Vector) The second vector to add. ### Returns 1. [`Vector`](https://tweaked.cc/module/vector.html#ty:Vector) The resulting vector ### Usage * Run ᐅ v1:add(v2) * Run ᐅ v1 + v2 [](https://tweaked.cc/module/vector.html#ty:Vector:sub) Vector:sub(o)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua#L52) Subtracts one vector from another. ### Parameters 1. o [`Vector`](https://tweaked.cc/module/vector.html#ty:Vector) The vector to subtract. ### Returns 1. [`Vector`](https://tweaked.cc/module/vector.html#ty:Vector) The resulting vector ### Usage * Run ᐅ v1:sub(v2) * Run ᐅ v1 \- v2 [](https://tweaked.cc/module/vector.html#ty:Vector:mul) Vector:mul(factor)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua#L70) Multiplies a vector by a scalar value. ### Parameters 1. factor `number` The scalar value to multiply with. ### Returns 1. [`Vector`](https://tweaked.cc/module/vector.html#ty:Vector) A vector with value `(x * m, y * m, z * m)`. ### Usage * Run ᐅ [vector.new](https://tweaked.cc/module/vector.html#v:new "Construct a new Vector with the given coordinates.") (1, 2, 3):mul(3) * Run ᐅ [vector.new](https://tweaked.cc/module/vector.html#v:new "Construct a new Vector with the given coordinates.") (1, 2, 3) \* 3 [](https://tweaked.cc/module/vector.html#ty:Vector:div) Vector:div(factor)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua#L88) Divides a vector by a scalar value. ### Parameters 1. factor `number` The scalar value to divide by. ### Returns 1. [`Vector`](https://tweaked.cc/module/vector.html#ty:Vector) A vector with value `(x / m, y / m, z / m)`. ### Usage * Run ᐅ [vector.new](https://tweaked.cc/module/vector.html#v:new "Construct a new Vector with the given coordinates.") (1, 2, 3):div(3) * Run ᐅ [vector.new](https://tweaked.cc/module/vector.html#v:new "Construct a new Vector with the given coordinates.") (1, 2, 3) / 3 [](https://tweaked.cc/module/vector.html#ty:Vector:unm) Vector:unm()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua#L104) Negate a vector ### Returns 1. [`Vector`](https://tweaked.cc/module/vector.html#ty:Vector) The negated vector. ### Usage * Run ᐅ \-[vector.new](https://tweaked.cc/module/vector.html#v:new "Construct a new Vector with the given coordinates.") (1, 2, 3) [](https://tweaked.cc/module/vector.html#ty:Vector:dot) Vector:dot(o)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua#L119) Compute the dot product of two vectors ### Parameters 1. o [`Vector`](https://tweaked.cc/module/vector.html#ty:Vector) The second vector to compute the dot product of. ### Returns 1. `number` The dot product of `self` and `o`. ### Usage * Run ᐅ v1:dot(v2) [](https://tweaked.cc/module/vector.html#ty:Vector:cross) Vector:cross(o)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua#L132) Compute the cross product of two vectors ### Parameters 1. o [`Vector`](https://tweaked.cc/module/vector.html#ty:Vector) The second vector to compute the cross product of. ### Returns 1. [`Vector`](https://tweaked.cc/module/vector.html#ty:Vector) The cross product of `self` and `o`. ### Usage * Run ᐅ v1:cross(v2) [](https://tweaked.cc/module/vector.html#ty:Vector:length) Vector:length()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua#L146) Get the length (also referred to as magnitude) of this vector. ### Returns 1. `number` The length of this vector. [](https://tweaked.cc/module/vector.html#ty:Vector:normalize) Vector:normalize()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua#L157) Divide this vector by its length, producing with the same direction, but of length 1. ### Returns 1. [`Vector`](https://tweaked.cc/module/vector.html#ty:Vector) The normalised vector ### Usage * Run ᐅ v:normalize() [](https://tweaked.cc/module/vector.html#ty:Vector:round) Vector:round(\[tolerance\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua#L168) Construct a vector with each dimension rounded to the nearest value. ### Parameters 1. tolerance? `number` The tolerance that we should round to, defaulting to 1. For instance, a tolerance of 0.5 will round to the nearest 0.5. ### Returns 1. [`Vector`](https://tweaked.cc/module/vector.html#ty:Vector) The rounded vector. [](https://tweaked.cc/module/vector.html#ty:Vector:tostring) Vector:tostring()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua#L186) Convert this vector into a string, for pretty printing. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) This vector's string representation. ### Usage * Run ᐅ v:tostring() * Run ᐅ tostring(v) [](https://tweaked.cc/module/vector.html#ty:Vector:equals) Vector:equals(other)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua#L197) Check for equality between two vectors. ### Parameters 1. other [`Vector`](https://tweaked.cc/module/vector.html#ty:Vector) The second vector to compare to. ### Returns 1. `boolean` Whether or not the vectors are equal. --- # turtle turtle ====== Turtles are a robotic device, which can break and place blocks, attack mobs, and move about the world. They have an internal inventory of 16 slots, allowing them to store blocks they have broken or would like to place. Movement -------- Turtles are capable of moving through the world. As turtles are blocks themselves, they are confined to Minecraft's grid, moving a single block at a time. [`turtle.forward`](https://tweaked.cc/module/turtle.html#v:forward) and [`turtle.back`](https://tweaked.cc/module/turtle.html#v:back) move the turtle in the direction it is facing, while [`turtle.up`](https://tweaked.cc/module/turtle.html#v:up) and [`turtle.down`](https://tweaked.cc/module/turtle.html#v:down) move it up and down (as one might expect!). In order to move left or right, you first need to turn the turtle using [`turtle.turnLeft`](https://tweaked.cc/module/turtle.html#v:turnLeft) /[`turtle.turnRight`](https://tweaked.cc/module/turtle.html#v:turnRight) and then move forward or backwards. ##### 🛈 info The name "turtle" comes from [Turtle graphics](https://en.wikipedia.org/wiki/Turtle_graphics "Turtle graphics") , which originated from the Logo programming language. Here you'd move a turtle with various commands like "move 10" and "turn left", much like ComputerCraft's turtles! Moving a turtle (though not turning it) consumes _fuel_. If a turtle does not have any [fuel](https://tweaked.cc/module/turtle.html#v:refuel) , it won't move, and the movement functions will return `false`. If your turtle isn't going anywhere, the first thing to check is if you've fuelled your turtle. ##### Handling errors Many turtle functions can fail in various ways. For instance, a turtle cannot move forward if there's already a block there. Instead of erroring, functions which can fail either return `true` if they succeed, or `false` and some error message if they fail. Unexpected failures can often lead to strange behaviour. It's often a good idea to check the return values of these functions, or wrap them in [`assert`](https://www.lua.org/manual/5.1/manual.html#pdf-assert) (for instance, use `assert(turtle.forward())` rather than `turtle.forward()`), so the program doesn't misbehave. Turtle upgrades --------------- While a normal turtle can move about the world and place blocks, its functionality is limited. Thankfully, turtles can be upgraded with upgrades. Turtles have two upgrade slots, one on the left and right sides. Upgrades can be equipped by crafting a turtle with the upgrade, or calling the [`turtle.equipLeft`](https://tweaked.cc/module/turtle.html#v:equipLeft) /[`turtle.equipRight`](https://tweaked.cc/module/turtle.html#v:equipRight) functions. By default, any diamond tool may be used as an upgrade (though more may be added with [datapacks](https://datapacks.madefor.cc/) ). The diamond pickaxe may be used to break blocks (with [`turtle.dig`](https://tweaked.cc/module/turtle.html#v:dig) ), while the sword can attack entities ([`turtle.attack`](https://tweaked.cc/module/turtle.html#v:attack) ). Other tools have more niche use-cases, for instance hoes can til dirt. Some peripherals (namely [speakers](https://tweaked.cc/peripheral/speaker.html) and Ender and Wireless [modems](https://tweaked.cc/peripheral/modem.html) ) can also be equipped as upgrades. These are then accessible by accessing the `"left"` or `"right"` peripheral. Recipes ------- **Turtle** ![Iron Ingot](https://tweaked.cc/images/items/minecraft/iron_ingot.png "Iron Ingot") ![Iron Ingot](https://tweaked.cc/images/items/minecraft/iron_ingot.png "Iron Ingot") ![Iron Ingot](https://tweaked.cc/images/items/minecraft/iron_ingot.png "Iron Ingot") ![Iron Ingot](https://tweaked.cc/images/items/minecraft/iron_ingot.png "Iron Ingot") ![Computer](https://tweaked.cc/images/items/computercraft/computer_normal.png "Computer") ![Iron Ingot](https://tweaked.cc/images/items/minecraft/iron_ingot.png "Iron Ingot") ![Iron Ingot](https://tweaked.cc/images/items/minecraft/iron_ingot.png "Iron Ingot") ![Chest](https://tweaked.cc/images/items/minecraft/chest.png "Chest") ![Iron Ingot](https://tweaked.cc/images/items/minecraft/iron_ingot.png "Iron Ingot") ![Turtle](https://tweaked.cc/images/items/computercraft/turtle_normal.png "Turtle") **Advanced Turtle** ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Advanced Computer](https://tweaked.cc/images/items/computercraft/computer_advanced.png "Advanced Computer") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Chest](https://tweaked.cc/images/items/minecraft/chest.png "Chest") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Advanced Turtle](https://tweaked.cc/images/items/computercraft/turtle_advanced.png "Advanced Turtle") ### Changes * **New in version 1.3** | | | | --- | --- | | [craft(\[limit=64\])](https://tweaked.cc/module/turtle.html#v:craft) | Craft a recipe based on the turtle's inventory. | | [native](https://tweaked.cc/module/turtle.html#v:native) | The builtin turtle API, without any generated helper functions. | | [forward()](https://tweaked.cc/module/turtle.html#v:forward) | Move the turtle forward one block. | | [back()](https://tweaked.cc/module/turtle.html#v:back) | Move the turtle backwards one block. | | [up()](https://tweaked.cc/module/turtle.html#v:up) | Move the turtle up one block. | | [down()](https://tweaked.cc/module/turtle.html#v:down) | Move the turtle down one block. | | [turnLeft()](https://tweaked.cc/module/turtle.html#v:turnLeft) | Rotate the turtle 90 degrees to the left. | | [turnRight()](https://tweaked.cc/module/turtle.html#v:turnRight) | Rotate the turtle 90 degrees to the right. | | [dig(\[side\])](https://tweaked.cc/module/turtle.html#v:dig) | Attempt to break the block in front of the turtle. | | [digUp(\[side\])](https://tweaked.cc/module/turtle.html#v:digUp) | Attempt to break the block above the turtle. | | [digDown(\[side\])](https://tweaked.cc/module/turtle.html#v:digDown) | Attempt to break the block below the turtle. | | [place(\[text\])](https://tweaked.cc/module/turtle.html#v:place) | Place a block or item into the world in front of the turtle. | | [placeUp(\[text\])](https://tweaked.cc/module/turtle.html#v:placeUp) | Place a block or item into the world above the turtle. | | [placeDown(\[text\])](https://tweaked.cc/module/turtle.html#v:placeDown) | Place a block or item into the world below the turtle. | | [drop(\[count\])](https://tweaked.cc/module/turtle.html#v:drop) | Drop the currently selected stack into the inventory in front of the turtle, or as an item into the world if there is no inventory. | | [dropUp(\[count\])](https://tweaked.cc/module/turtle.html#v:dropUp) | Drop the currently selected stack into the inventory above the turtle, or as an item into the world if there is no inventory. | | [dropDown(\[count\])](https://tweaked.cc/module/turtle.html#v:dropDown) | Drop the currently selected stack into the inventory below the turtle, or as an item into the world if there is no inventory. | | [select(slot)](https://tweaked.cc/module/turtle.html#v:select) | Change the currently selected slot. | | [getItemCount(\[slot\])](https://tweaked.cc/module/turtle.html#v:getItemCount) | Get the number of items in the given slot. | | [getItemSpace(\[slot\])](https://tweaked.cc/module/turtle.html#v:getItemSpace) | Get the remaining number of items which may be stored in this stack. | | [detect()](https://tweaked.cc/module/turtle.html#v:detect) | Check if there is a solid block in front of the turtle. | | [detectUp()](https://tweaked.cc/module/turtle.html#v:detectUp) | Check if there is a solid block above the turtle. | | [detectDown()](https://tweaked.cc/module/turtle.html#v:detectDown) | Check if there is a solid block below the turtle. | | [compare()](https://tweaked.cc/module/turtle.html#v:compare) | Check if the block in front of the turtle is equal to the item in the currently selected slot. | | [compareUp()](https://tweaked.cc/module/turtle.html#v:compareUp) | Check if the block above the turtle is equal to the item in the currently selected slot. | | [compareDown()](https://tweaked.cc/module/turtle.html#v:compareDown) | Check if the block below the turtle is equal to the item in the currently selected slot. | | [attack(\[side\])](https://tweaked.cc/module/turtle.html#v:attack) | Attack the entity in front of the turtle. | | [attackUp(\[side\])](https://tweaked.cc/module/turtle.html#v:attackUp) | Attack the entity above the turtle. | | [attackDown(\[side\])](https://tweaked.cc/module/turtle.html#v:attackDown) | Attack the entity below the turtle. | | [suck(\[count\])](https://tweaked.cc/module/turtle.html#v:suck) | Suck an item from the inventory in front of the turtle, or from an item floating in the world. | | [suckUp(\[count\])](https://tweaked.cc/module/turtle.html#v:suckUp) | Suck an item from the inventory above the turtle, or from an item floating in the world. | | [suckDown(\[count\])](https://tweaked.cc/module/turtle.html#v:suckDown) | Suck an item from the inventory below the turtle, or from an item floating in the world. | | [getFuelLevel()](https://tweaked.cc/module/turtle.html#v:getFuelLevel) | Get the maximum amount of fuel this turtle currently holds. | | [refuel(\[count\])](https://tweaked.cc/module/turtle.html#v:refuel) | Refuel this turtle. | | [compareTo(slot)](https://tweaked.cc/module/turtle.html#v:compareTo) | Compare the item in the currently selected slot to the item in another slot. | | [transferTo(slot \[, count\])](https://tweaked.cc/module/turtle.html#v:transferTo) | Move an item from the selected slot to another one. | | [getSelectedSlot()](https://tweaked.cc/module/turtle.html#v:getSelectedSlot) | Get the currently selected slot. | | [getFuelLimit()](https://tweaked.cc/module/turtle.html#v:getFuelLimit) | Get the maximum amount of fuel this turtle can hold. | | [equipLeft()](https://tweaked.cc/module/turtle.html#v:equipLeft) | Equip (or unequip) an item on the left side of this turtle. | | [equipRight()](https://tweaked.cc/module/turtle.html#v:equipRight) | Equip (or unequip) an item on the right side of this turtle. | | [getEquippedLeft()](https://tweaked.cc/module/turtle.html#v:getEquippedLeft) | Get the upgrade currently equipped on the left of the turtle. | | [getEquippedRight()](https://tweaked.cc/module/turtle.html#v:getEquippedRight) | Get the upgrade currently equipped on the right of the turtle. | | [inspect()](https://tweaked.cc/module/turtle.html#v:inspect) | Get [information about the block](https://tweaked.cc/reference/block_details.html)
in front of the turtle. | | [inspectUp()](https://tweaked.cc/module/turtle.html#v:inspectUp) | Get [information about the block](https://tweaked.cc/reference/block_details.html)
above the turtle. | | [inspectDown()](https://tweaked.cc/module/turtle.html#v:inspectDown) | Get [information about the block](https://tweaked.cc/reference/block_details.html)
below the turtle. | | [getItemDetail(\[slot \[, detailed\]\])](https://tweaked.cc/module/turtle.html#v:getItemDetail) | Get [information about the items](https://tweaked.cc/reference/item_details.html)
in the given slot. | [](https://tweaked.cc/module/turtle.html#v:craft) craft(\[limit=64\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/doc/stub/turtle.lua#L20) Craft a recipe based on the turtle's inventory. The turtle's inventory should set up like a crafting grid. For instance, to craft sticks, slots 1 and 5 should contain planks. _All_ other slots should be empty, including those outside the crafting "grid". `turtle.craft(0)` can be used to check whether the turtle contains a valid recipe, without actually crafting it. ### Parameters 1. limit? `number` = The maximum number of crafting steps to run. ### Returns 1. true If crafting succeeds. #### Or 1. false If crafting fails. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) A string describing why crafting failed. ### Throws * When limit is less than 0 or greater than 64. ### Changes * **New in version 1.4** [](https://tweaked.cc/module/turtle.html#v:native) native[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/turtle/turtle.lua#L15) ##### 🛈 Deprecated Historically this table behaved differently to the main turtle API, but this is no longer the case. You should not need to use it. The builtin turtle API, without any generated helper functions. [](https://tweaked.cc/module/turtle.html#v:forward) forward()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L99) Move the turtle forward one block. ### Returns 1. `boolean` Whether the turtle could successfully move. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason the turtle could not move. [](https://tweaked.cc/module/turtle.html#v:back) back()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L111) Move the turtle backwards one block. ### Returns 1. `boolean` Whether the turtle could successfully move. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason the turtle could not move. [](https://tweaked.cc/module/turtle.html#v:up) up()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L123) Move the turtle up one block. ### Returns 1. `boolean` Whether the turtle could successfully move. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason the turtle could not move. [](https://tweaked.cc/module/turtle.html#v:down) down()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L135) Move the turtle down one block. ### Returns 1. `boolean` Whether the turtle could successfully move. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason the turtle could not move. [](https://tweaked.cc/module/turtle.html#v:turnLeft) turnLeft()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L147) Rotate the turtle 90 degrees to the left. ### Returns 1. `boolean` Whether the turtle could successfully turn. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason the turtle could not turn. [](https://tweaked.cc/module/turtle.html#v:turnRight) turnRight()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L159) Rotate the turtle 90 degrees to the right. ### Returns 1. `boolean` Whether the turtle could successfully turn. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason the turtle could not turn. [](https://tweaked.cc/module/turtle.html#v:dig) dig(\[side\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L177) Attempt to break the block in front of the turtle. This requires a turtle tool capable of breaking the block. Diamond pickaxes (mining turtles) can break any vanilla block breakable in survival mode, but other tools (such as axes) are more limited. ### Parameters 1. side? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The specific tool to use. Should be "left" or "right". ### Returns 1. `boolean` Whether a block was broken. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason no block was broken. ### Changes * **Changed in version 1.6:** Added optional side argument. [](https://tweaked.cc/module/turtle.html#v:digUp) digUp(\[side\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L192) Attempt to break the block above the turtle. See [`dig`](https://tweaked.cc/module/turtle.html#v:dig) for full details. ### Parameters 1. side? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The specific tool to use. ### Returns 1. `boolean` Whether a block was broken. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason no block was broken. ### Changes * **Changed in version 1.6:** Added optional side argument. [](https://tweaked.cc/module/turtle.html#v:digDown) digDown(\[side\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L207) Attempt to break the block below the turtle. See [`dig`](https://tweaked.cc/module/turtle.html#v:dig) for full details. ### Parameters 1. side? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The specific tool to use. ### Returns 1. `boolean` Whether a block was broken. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason no block was broken. ### Changes * **Changed in version 1.6:** Added optional side argument. [](https://tweaked.cc/module/turtle.html#v:place) place(\[text\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L227) Place a block or item into the world in front of the turtle. "Placing" an item allows it to interact with blocks and entities in front of the turtle. For instance, buckets can pick up and place down fluids, and wheat can be used to breed cows. However, you cannot use [`place`](https://tweaked.cc/module/turtle.html#v:place) to perform arbitrary block interactions, such as clicking buttons or flipping levers. ### Parameters 1. text? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) When placing a sign, set its contents to this text. ### Returns 1. `boolean` Whether the block could be placed. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason the block was not placed. ### Changes * **New in version 1.4** [](https://tweaked.cc/module/turtle.html#v:placeUp) placeUp(\[text\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L243) Place a block or item into the world above the turtle. ### Parameters 1. text? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) When placing a sign, set its contents to this text. ### Returns 1. `boolean` Whether the block could be placed. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason the block was not placed. ### See also * **[`place`](https://tweaked.cc/module/turtle.html#v:place) ** For more information about placing items. ### Changes * **New in version 1.4** [](https://tweaked.cc/module/turtle.html#v:placeDown) placeDown(\[text\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L259) Place a block or item into the world below the turtle. ### Parameters 1. text? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) When placing a sign, set its contents to this text. ### Returns 1. `boolean` Whether the block could be placed. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason the block was not placed. ### See also * **[`place`](https://tweaked.cc/module/turtle.html#v:place) ** For more information about placing items. ### Changes * **New in version 1.4** [](https://tweaked.cc/module/turtle.html#v:drop) drop(\[count\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L276) Drop the currently selected stack into the inventory in front of the turtle, or as an item into the world if there is no inventory. ### Parameters 1. count? `number` The number of items to drop. If not given, the entire stack will be dropped. ### Returns 1. `boolean` Whether items were dropped. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason the no items were dropped. ### Throws * If dropping an invalid number of items. ### See also * **[`select`](https://tweaked.cc/module/turtle.html#v:select) ** ### Changes * **New in version 1.31** [](https://tweaked.cc/module/turtle.html#v:dropUp) dropUp(\[count\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L293) Drop the currently selected stack into the inventory above the turtle, or as an item into the world if there is no inventory. ### Parameters 1. count? `number` The number of items to drop. If not given, the entire stack will be dropped. ### Returns 1. `boolean` Whether items were dropped. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason the no items were dropped. ### Throws * If dropping an invalid number of items. ### See also * **[`select`](https://tweaked.cc/module/turtle.html#v:select) ** ### Changes * **New in version 1.4** [](https://tweaked.cc/module/turtle.html#v:dropDown) dropDown(\[count\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L310) Drop the currently selected stack into the inventory below the turtle, or as an item into the world if there is no inventory. ### Parameters 1. count? `number` The number of items to drop. If not given, the entire stack will be dropped. ### Returns 1. `boolean` Whether items were dropped. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason the no items were dropped. ### Throws * If dropping an invalid number of items. ### See also * **[`select`](https://tweaked.cc/module/turtle.html#v:select) ** ### Changes * **New in version 1.4** [](https://tweaked.cc/module/turtle.html#v:select) select(slot)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L327) Change the currently selected slot. The selected slot is determines what slot actions like [`drop`](https://tweaked.cc/module/turtle.html#v:drop) or [`getItemCount`](https://tweaked.cc/module/turtle.html#v:getItemCount) act on. ### Parameters 1. slot `number` The slot to select. ### Returns 1. true When the slot has been selected. ### Throws * If the slot is out of range. ### See also * **[`getSelectedSlot`](https://tweaked.cc/module/turtle.html#v:getSelectedSlot) ** [](https://tweaked.cc/module/turtle.html#v:getItemCount) getItemCount(\[slot\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L343) Get the number of items in the given slot. ### Parameters 1. slot? `number` The slot we wish to check. Defaults to the [selected slot](https://tweaked.cc/module/turtle.html#v:select) . ### Returns 1. `number` The number of items in this slot. ### Throws * If the slot is out of range. [](https://tweaked.cc/module/turtle.html#v:getItemSpace) getItemSpace(\[slot\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L358) Get the remaining number of items which may be stored in this stack. For instance, if a slot contains 13 blocks of dirt, it has room for another 51. ### Parameters 1. slot? `number` The slot we wish to check. Defaults to the [selected slot](https://tweaked.cc/module/turtle.html#v:select) . ### Returns 1. `number` The space left in this slot. ### Throws * If the slot is out of range. [](https://tweaked.cc/module/turtle.html#v:detect) detect()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L372) Check if there is a solid block in front of the turtle. In this case, solid refers to any non-air or liquid block. ### Returns 1. `boolean` If there is a solid block in front. [](https://tweaked.cc/module/turtle.html#v:detectUp) detectUp()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L383) Check if there is a solid block above the turtle. In this case, solid refers to any non-air or liquid block. ### Returns 1. `boolean` If there is a solid block above. [](https://tweaked.cc/module/turtle.html#v:detectDown) detectDown()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L394) Check if there is a solid block below the turtle. In this case, solid refers to any non-air or liquid block. ### Returns 1. `boolean` If there is a solid block below. [](https://tweaked.cc/module/turtle.html#v:compare) compare()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L406) Check if the block in front of the turtle is equal to the item in the currently selected slot. ### Returns 1. `boolean` If the block and item are equal. ### Changes * **New in version 1.31** [](https://tweaked.cc/module/turtle.html#v:compareUp) compareUp()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L418) Check if the block above the turtle is equal to the item in the currently selected slot. ### Returns 1. `boolean` If the block and item are equal. ### Changes * **New in version 1.31** [](https://tweaked.cc/module/turtle.html#v:compareDown) compareDown()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L430) Check if the block below the turtle is equal to the item in the currently selected slot. ### Returns 1. `boolean` If the block and item are equal. ### Changes * **New in version 1.31** [](https://tweaked.cc/module/turtle.html#v:attack) attack(\[side\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L445) Attack the entity in front of the turtle. ### Parameters 1. side? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The specific tool to use. ### Returns 1. `boolean` Whether an entity was attacked. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason nothing was attacked. ### Changes * **New in version 1.4** * **Changed in version 1.6:** Added optional side argument. [](https://tweaked.cc/module/turtle.html#v:attackUp) attackUp(\[side\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L460) Attack the entity above the turtle. ### Parameters 1. side? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The specific tool to use. ### Returns 1. `boolean` Whether an entity was attacked. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason nothing was attacked. ### Changes * **New in version 1.4** * **Changed in version 1.6:** Added optional side argument. [](https://tweaked.cc/module/turtle.html#v:attackDown) attackDown(\[side\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L475) Attack the entity below the turtle. ### Parameters 1. side? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The specific tool to use. ### Returns 1. `boolean` Whether an entity was attacked. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason nothing was attacked. ### Changes * **New in version 1.4** * **Changed in version 1.6:** Added optional side argument. [](https://tweaked.cc/module/turtle.html#v:suck) suck(\[count\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L493) Suck an item from the inventory in front of the turtle, or from an item floating in the world. This will pull items into the first acceptable slot, starting at the [currently selected](https://tweaked.cc/module/turtle.html#v:select) one. ### Parameters 1. count? `number` The number of items to suck. If not given, up to a stack of items will be picked up. ### Returns 1. `boolean` Whether items were picked up. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason the no items were picked up. ### Throws * If given an invalid number of items. ### Changes * **New in version 1.4** * **Changed in version 1.6:** Added an optional limit argument. [](https://tweaked.cc/module/turtle.html#v:suckUp) suckUp(\[count\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L509) Suck an item from the inventory above the turtle, or from an item floating in the world. ### Parameters 1. count? `number` The number of items to suck. If not given, up to a stack of items will be picked up. ### Returns 1. `boolean` Whether items were picked up. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason the no items were picked up. ### Throws * If given an invalid number of items. ### Changes * **New in version 1.4** * **Changed in version 1.6:** Added an optional limit argument. [](https://tweaked.cc/module/turtle.html#v:suckDown) suckDown(\[count\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L525) Suck an item from the inventory below the turtle, or from an item floating in the world. ### Parameters 1. count? `number` The number of items to suck. If not given, up to a stack of items will be picked up. ### Returns 1. `boolean` Whether items were picked up. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The reason the no items were picked up. ### Throws * If given an invalid number of items. ### Changes * **New in version 1.4** * **Changed in version 1.6:** Added an optional limit argument. [](https://tweaked.cc/module/turtle.html#v:getFuelLevel) getFuelLevel()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L540) Get the maximum amount of fuel this turtle currently holds. ### Returns 1. `number` The current amount of fuel a turtle this turtle has. #### Or 1. "unlimited" If turtles do not consume fuel when moving. ### See also * **[`getFuelLimit`](https://tweaked.cc/module/turtle.html#v:getFuelLimit) ** * **[`refuel`](https://tweaked.cc/module/turtle.html#v:refuel) ** ### Changes * **New in version 1.4** [](https://tweaked.cc/module/turtle.html#v:refuel) refuel(\[count\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L582) Refuel this turtle. While most actions a turtle can perform (such as digging or placing blocks) are free, moving consumes fuel from the turtle's internal buffer. If a turtle has no fuel, it will not move. [`refuel`](https://tweaked.cc/module/turtle.html#v:refuel) refuels the turtle, consuming fuel items (such as coal or lava buckets) from the currently selected slot and converting them into energy. This finishes once the turtle is fully refuelled or all items have been consumed. ### Parameters 1. count? `number` The maximum number of items to consume. One can pass `0` to check if an item is combustable or not. ### Returns 1. true If the turtle was refuelled. #### Or 1. false If the turtle was not refuelled. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The reason the turtle was not refuelled. ### Throws * If the refuel count is out of range. ### Usage * Refuel a turtle from the currently selected slot. Run ᐅ local level \= [turtle.getFuelLevel](https://tweaked.cc/module/turtle.html#v:getFuelLevel "Get the maximum amount of fuel this turtle currently holds.") () if level \== "unlimited" then error("Turtle does not need fuel", 0) end local ok, err \= [turtle.refuel](https://tweaked.cc/module/turtle.html#v:refuel "Refuel this turtle.") () if ok then local new\_level \= [turtle.getFuelLevel](https://tweaked.cc/module/turtle.html#v:getFuelLevel "Get the maximum amount of fuel this turtle currently holds.") () print(("Refuelled %d, current level is %d"):format(new\_level \- level, new\_level)) else printError(err) end * Check if the current item is a valid fuel source. Run ᐅ local is\_fuel, reason \= [turtle.refuel](https://tweaked.cc/module/turtle.html#v:refuel "Refuel this turtle.") (0) if not is\_fuel then printError(reason) end ### See also * **[`getFuelLevel`](https://tweaked.cc/module/turtle.html#v:getFuelLevel) ** * **[`getFuelLimit`](https://tweaked.cc/module/turtle.html#v:getFuelLimit) ** ### Changes * **New in version 1.4** [](https://tweaked.cc/module/turtle.html#v:compareTo) compareTo(slot)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L598) Compare the item in the currently selected slot to the item in another slot. ### Parameters 1. slot `number` The slot to compare to. ### Returns 1. `boolean` If the two items are equal. ### Throws * If the slot is out of range. ### Changes * **New in version 1.4** [](https://tweaked.cc/module/turtle.html#v:transferTo) transferTo(slot \[, count\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L614) Move an item from the selected slot to another one. ### Parameters 1. slot `number` The slot to move this item to. 2. count? `number` The maximum number of items to move. ### Returns 1. `boolean` If some items were successfully moved. ### Throws * If the slot is out of range. * If the number of items is out of range. ### Changes * **New in version 1.45** [](https://tweaked.cc/module/turtle.html#v:getSelectedSlot) getSelectedSlot()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L628) Get the currently selected slot. ### Returns 1. `number` The current slot. ### See also * **[`select`](https://tweaked.cc/module/turtle.html#v:select) ** ### Changes * **New in version 1.6** [](https://tweaked.cc/module/turtle.html#v:getFuelLimit) getFuelLimit()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L645) Get the maximum amount of fuel this turtle can hold. By default, normal turtles have a limit of 20,000 and advanced turtles of 100,000. ### Returns 1. `number` The maximum amount of fuel a turtle can hold. #### Or 1. "unlimited" If turtles do not consume fuel when moving. ### See also * **[`getFuelLevel`](https://tweaked.cc/module/turtle.html#v:getFuelLevel) ** * **[`refuel`](https://tweaked.cc/module/turtle.html#v:refuel) ** ### Changes * **New in version 1.6** [](https://tweaked.cc/module/turtle.html#v:equipLeft) equipLeft()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L665) Equip (or unequip) an item on the left side of this turtle. This finds the item in the currently selected slot and attempts to equip it to the left side of the turtle. The previous upgrade is removed and placed into the turtle's inventory. If there is no item in the slot, the previous upgrade is removed, but no new one is equipped. ### Returns 1. true If the item was equipped. #### Or 1. false If we could not equip the item. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The reason equipping this item failed. ### See also * **[`equipRight`](https://tweaked.cc/module/turtle.html#v:equipRight) ** * **[`getEquippedLeft`](https://tweaked.cc/module/turtle.html#v:getEquippedLeft) ** ### Changes * **New in version 1.6** [](https://tweaked.cc/module/turtle.html#v:equipRight) equipRight()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L685) Equip (or unequip) an item on the right side of this turtle. This finds the item in the currently selected slot and attempts to equip it to the right side of the turtle. The previous upgrade is removed and placed into the turtle's inventory. If there is no item in the slot, the previous upgrade is removed, but no new one is equipped. ### Returns 1. true If the item was equipped. #### Or 1. false If we could not equip the item. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The reason equipping this item failed. ### See also * **[`equipLeft`](https://tweaked.cc/module/turtle.html#v:equipLeft) ** * **[`getEquippedRight`](https://tweaked.cc/module/turtle.html#v:getEquippedRight) ** ### Changes * **New in version 1.6** [](https://tweaked.cc/module/turtle.html#v:getEquippedLeft) getEquippedLeft()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L700) Get the upgrade currently equipped on the left of the turtle. This returns [information about the currently equipped item](https://tweaked.cc/reference/item_details.html) . ### Returns 1. [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) | nil Information about the currently equipped item, or `nil` if no upgrade is equipped. ### See also * **[`equipLeft`](https://tweaked.cc/module/turtle.html#v:equipLeft) ** * **[`Item details`](https://tweaked.cc/reference/item_details.html) ** ### Changes * **New in version 1.116.0** [](https://tweaked.cc/module/turtle.html#v:getEquippedRight) getEquippedRight()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L716) Get the upgrade currently equipped on the right of the turtle. This returns [information about the currently equipped item](https://tweaked.cc/reference/item_details.html) . ### Returns 1. [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) | nil Information about the currently equipped item, or `nil` if no upgrade is equipped. ### See also * **[`equipRight`](https://tweaked.cc/module/turtle.html#v:equipRight) ** * **[`Item details`](https://tweaked.cc/reference/item_details.html) ** ### Changes * **New in version 1.116.0** [](https://tweaked.cc/module/turtle.html#v:inspect) inspect()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L744) Get [information about the block](https://tweaked.cc/reference/block_details.html) in front of the turtle. ### Returns 1. `boolean` Whether there is a block in front of the turtle. 2. [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) | [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Information about the block in front, or a message explaining that there is no block. ### Usage * Run ᐅ local has\_block, data \= [turtle.inspect](https://tweaked.cc/module/turtle.html#v:inspect "Get information about the block in front of the turtle.") () if has\_block then print([textutils.serialise](https://tweaked.cc/module/textutils.html#v:serialise "Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing.") (data)) \-- { \-- name = "minecraft:oak\_log", \-- state = { axis = "x" }, \-- tags = { \["minecraft:logs"\] = true, ... }, \-- } else print("No block in front of the turtle") end ### See also * **[`Block details`](https://tweaked.cc/reference/block_details.html) ** ### Changes * **New in version 1.64** * **Changed in version 1.76:** Added block state to return value. [](https://tweaked.cc/module/turtle.html#v:inspectUp) inspectUp()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L758) Get [information about the block](https://tweaked.cc/reference/block_details.html) above the turtle. ### Returns 1. `boolean` Whether there is a block above the turtle. 2. [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) | [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Information about the block above, or a message explaining that there is no block. ### See also * **[`Block details`](https://tweaked.cc/reference/block_details.html) ** ### Changes * **New in version 1.64** [](https://tweaked.cc/module/turtle.html#v:inspectDown) inspectDown()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L772) Get [information about the block](https://tweaked.cc/reference/block_details.html) below the turtle. ### Returns 1. `boolean` Whether there is a block below the turtle. 2. [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) | [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Information about the block below, or a message explaining that there is no block. ### See also * **[`Block details`](https://tweaked.cc/reference/block_details.html) ** ### Changes * **New in version 1.64** [](https://tweaked.cc/module/turtle.html#v:getItemDetail) getItemDetail(\[slot \[, detailed\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java#L800) Get [information about the items](https://tweaked.cc/reference/item_details.html) in the given slot. ### Parameters 1. slot? `number` The slot to get information about. Defaults to the [selected slot](https://tweaked.cc/module/turtle.html#v:select) . 2. detailed? `boolean` Whether to include "detailed" information. When `true` the method will contain much more information about the item at the cost of taking longer to run. ### Returns 1. nil | [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) Information about the item in this slot, or `nil` if it is empty. ### Throws * If the slot is out of range. ### Usage * Print the current slot, assuming it contains 13 dirt. Run ᐅ print([textutils.serialise](https://tweaked.cc/module/textutils.html#v:serialise "Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing.") ([turtle.getItemDetail](https://tweaked.cc/module/turtle.html#v:getItemDetail "Get information about the items in the given slot.") ())) \-- => { \-- name = "minecraft:dirt", \-- count = 13, \-- } ### See also * **[`Item details`](https://tweaked.cc/reference/item_details.html) ** ### Changes * **New in version 1.64** * **Changed in version 1.90.0:** Added detailed parameter. --- # term term ==== Interact with a computer's terminal or monitors, writing text and drawing ASCII graphics. Writing to the terminal ----------------------- The simplest operation one can perform on a terminal is displaying (or writing) some text. This can be performed with the [`term.write`](https://tweaked.cc/module/term.html#v:write) method. Run ᐅ [term.write](https://tweaked.cc/module/term.html#v:write "Write text at the current cursor position, moving the cursor to the end of the text.") ("Hello, world!") When you write text, this advances the cursor, so the next call to [`term.write`](https://tweaked.cc/module/term.html#v:write) will write text immediately after the previous one. Run ᐅ [term.write](https://tweaked.cc/module/term.html#v:write "Write text at the current cursor position, moving the cursor to the end of the text.") ("Hello, world!") [term.write](https://tweaked.cc/module/term.html#v:write "Write text at the current cursor position, moving the cursor to the end of the text.") ("Some more text") [`term.getCursorPos`](https://tweaked.cc/module/term.html#v:getCursorPos) and [`term.setCursorPos`](https://tweaked.cc/module/term.html#v:setCursorPos) can be used to manually change the cursor's position. Run ᐅ [term.clear](https://tweaked.cc/module/term.html#v:clear "Clears the terminal, filling it with the current background colour.") () [term.setCursorPos](https://tweaked.cc/module/term.html#v:setCursorPos "Set the position of the cursor.") (1, 1) \-- The first column of line 1 [term.write](https://tweaked.cc/module/term.html#v:write "Write text at the current cursor position, moving the cursor to the end of the text.") ("First line") [term.setCursorPos](https://tweaked.cc/module/term.html#v:setCursorPos "Set the position of the cursor.") (20, 2) \-- The 20th column of line 2 [term.write](https://tweaked.cc/module/term.html#v:write "Write text at the current cursor position, moving the cursor to the end of the text.") ("Second line") [`term.write`](https://tweaked.cc/module/term.html#v:write) is a relatively basic and low-level function, and does not handle more advanced features such as line breaks or word wrapping. If you just want to display text to the screen, you probably want to use [`print`](https://www.lua.org/manual/5.1/manual.html#pdf-print) or [`write`](https://tweaked.cc/module/term.html#v:write) instead. Colours ------- So far we've been writing text in black and white. However, advanced computers are also capable of displaying text in a variety of colours, with the [`term.setTextColour`](https://tweaked.cc/module/term.html#v:setTextColour) and [`term.setBackgroundColour`](https://tweaked.cc/module/term.html#v:setBackgroundColour) functions. Run ᐅ print("This text is white") [term.setTextColour](https://tweaked.cc/module/term.html#v:setTextColour "Set the colour that new text will be written as.") ([colours](https://tweaked.cc/module/colours.html "An alternative version of colors for lovers of British spelling.") .green) print("This text is green") These functions accept any of the constants from the [`colors`](https://tweaked.cc/module/colors.html) API. [Combinations of colours](https://tweaked.cc/module/colors.html#v:combine) may be accepted, but will only display a single colour (typically following the behaviour of [`colors.toBlit`](https://tweaked.cc/module/colors.html#v:toBlit) ). The [`paintutils`](https://tweaked.cc/module/paintutils.html) API provides several helpful functions for displaying graphics using [`term.setBackgroundColour`](https://tweaked.cc/module/term.html#v:setBackgroundColour) . | | | | --- | --- | | [nativePaletteColour(colour)](https://tweaked.cc/module/term.html#v:nativePaletteColour) | Get the default palette value for a colour. | | [nativePaletteColor(colour)](https://tweaked.cc/module/term.html#v:nativePaletteColor) | Get the default palette value for a colour. | | [write(text)](https://tweaked.cc/module/term.html#v:write) | Write `text` at the current cursor position, moving the cursor to the end of the text. | | [scroll(y)](https://tweaked.cc/module/term.html#v:scroll) | Move all positions up (or down) by `y` pixels. | | [getCursorPos()](https://tweaked.cc/module/term.html#v:getCursorPos) | Get the position of the cursor. | | [setCursorPos(x, y)](https://tweaked.cc/module/term.html#v:setCursorPos) | Set the position of the cursor. | | [getCursorBlink()](https://tweaked.cc/module/term.html#v:getCursorBlink) | Checks if the cursor is currently blinking. | | [setCursorBlink(blink)](https://tweaked.cc/module/term.html#v:setCursorBlink) | Sets whether the cursor should be visible (and blinking) at the current [cursor position](https://tweaked.cc/module/term.html#v:getCursorPos)
. | | [getSize()](https://tweaked.cc/module/term.html#v:getSize) | Get the size of the terminal. | | [clear()](https://tweaked.cc/module/term.html#v:clear) | Clears the terminal, filling it with the [current background colour](https://tweaked.cc/module/term.html#v:getBackgroundColour)
. | | [clearLine()](https://tweaked.cc/module/term.html#v:clearLine) | Clears the line the cursor is currently on, filling it with the [current background colour](https://tweaked.cc/module/term.html#v:getBackgroundColour)
. | | [getTextColour()](https://tweaked.cc/module/term.html#v:getTextColour) | Return the colour that new text will be written as. | | [getTextColor()](https://tweaked.cc/module/term.html#v:getTextColor) | Return the colour that new text will be written as. | | [setTextColour(colour)](https://tweaked.cc/module/term.html#v:setTextColour) | Set the colour that new text will be written as. | | [setTextColor(colour)](https://tweaked.cc/module/term.html#v:setTextColor) | Set the colour that new text will be written as. | | [getBackgroundColour()](https://tweaked.cc/module/term.html#v:getBackgroundColour) | Return the current background colour. | | [getBackgroundColor()](https://tweaked.cc/module/term.html#v:getBackgroundColor) | Return the current background colour. | | [setBackgroundColour(colour)](https://tweaked.cc/module/term.html#v:setBackgroundColour) | Set the current background colour. | | [setBackgroundColor(colour)](https://tweaked.cc/module/term.html#v:setBackgroundColor) | Set the current background colour. | | [isColour()](https://tweaked.cc/module/term.html#v:isColour) | Determine if this terminal supports colour. | | [isColor()](https://tweaked.cc/module/term.html#v:isColor) | Determine if this terminal supports colour. | | [blit(text, textColour, backgroundColour)](https://tweaked.cc/module/term.html#v:blit) | Writes `text` to the terminal with the specific foreground and background colours. | | [setPaletteColour(...)](https://tweaked.cc/module/term.html#v:setPaletteColour) | Set the palette for a specific colour. | | [setPaletteColor(...)](https://tweaked.cc/module/term.html#v:setPaletteColor) | Set the palette for a specific colour. | | [getPaletteColour(colour)](https://tweaked.cc/module/term.html#v:getPaletteColour) | Get the current palette for a specific colour. | | [getPaletteColor(colour)](https://tweaked.cc/module/term.html#v:getPaletteColor) | Get the current palette for a specific colour. | | [redirect(target)](https://tweaked.cc/module/term.html#v:redirect) | Redirects terminal output to a monitor, a [`window`](https://tweaked.cc/module/window.html)
, or any other custom terminal object. | | [current()](https://tweaked.cc/module/term.html#v:current) | Returns the current terminal object of the computer. | | [native()](https://tweaked.cc/module/term.html#v:native) | Get the native terminal object of the current computer. | [](https://tweaked.cc/module/term.html#v:nativePaletteColour) nativePaletteColour(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermAPI.java#L91) Get the default palette value for a colour. ### Parameters 1. colour `number` The colour whose palette should be fetched. ### Returns 1. `number` The red channel, will be between 0 and 1. 2. `number` The green channel, will be between 0 and 1. 3. `number` The blue channel, will be between 0 and 1. ### Throws * When given an invalid colour. ### See also * **[`term.Redirect.setPaletteColour`](https://tweaked.cc/module/term.html#ty:Redirect:setPaletteColour) ** To change the palette colour. ### Changes * **New in version 1.81.0** [](https://tweaked.cc/module/term.html#v:nativePaletteColor) nativePaletteColor(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermAPI.java#L91) Get the default palette value for a colour. ### Parameters 1. colour `number` The colour whose palette should be fetched. ### Returns 1. `number` The red channel, will be between 0 and 1. 2. `number` The green channel, will be between 0 and 1. 3. `number` The blue channel, will be between 0 and 1. ### Throws * When given an invalid colour. ### See also * **[`term.Redirect.setPaletteColour`](https://tweaked.cc/module/term.html#ty:Redirect:setPaletteColour) ** To change the palette colour. ### Changes * **New in version 1.81.0** [](https://tweaked.cc/module/term.html#v:write) write(text)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L38) Write `text` at the current cursor position, moving the cursor to the end of the text. Unlike functions like [`_G.write`](https://tweaked.cc/module/_G.html#v:write) and [`print`](https://www.lua.org/manual/5.1/manual.html#pdf-print) , this does not wrap the text - it simply copies the text to the current terminal line. ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The text to write. [](https://tweaked.cc/module/term.html#v:scroll) scroll(y)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L57) Move all positions up (or down) by `y` pixels. Every pixel in the terminal will be replaced by the line `y` pixels below it. If `y` is negative, it will copy pixels from above instead. ### Parameters 1. y `number` The number of lines to move up by. This may be a negative number. [](https://tweaked.cc/module/term.html#v:getCursorPos) getCursorPos()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L70) Get the position of the cursor. ### Returns 1. `number` The x position of the cursor. 2. `number` The y position of the cursor. [](https://tweaked.cc/module/term.html#v:setCursorPos) setCursorPos(x, y)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L83) Set the position of the cursor. [Terminal writes](https://tweaked.cc/module/term.html#v:write) will begin from this position. ### Parameters 1. x `number` The new x position of the cursor. 2. y `number` The new y position of the cursor. [](https://tweaked.cc/module/term.html#v:getCursorBlink) getCursorBlink()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L98) Checks if the cursor is currently blinking. ### Returns 1. `boolean` If the cursor is blinking. ### Changes * **New in version 1.80pr1.9** [](https://tweaked.cc/module/term.html#v:setCursorBlink) setCursorBlink(blink)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L109) Sets whether the cursor should be visible (and blinking) at the current [cursor position](https://tweaked.cc/module/term.html#v:getCursorPos) . ### Parameters 1. blink `boolean` Whether the cursor should blink. [](https://tweaked.cc/module/term.html#v:getSize) getSize()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L125) Get the size of the terminal. ### Returns 1. `number` The terminal's width. 2. `number` The terminal's height. [](https://tweaked.cc/module/term.html#v:clear) clear()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L136) Clears the terminal, filling it with the [current background colour](https://tweaked.cc/module/term.html#v:getBackgroundColour) . [](https://tweaked.cc/module/term.html#v:clearLine) clearLine()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L147) Clears the line the cursor is currently on, filling it with the [current background colour](https://tweaked.cc/module/term.html#v:getBackgroundColour) . [](https://tweaked.cc/module/term.html#v:getTextColour) getTextColour()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L160) Return the colour that new text will be written as. ### Returns 1. `number` The current text colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants, returned by this function. ### Changes * **New in version 1.74** [](https://tweaked.cc/module/term.html#v:getTextColor) getTextColor()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L160) Return the colour that new text will be written as. ### Returns 1. `number` The current text colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants, returned by this function. ### Changes * **New in version 1.74** [](https://tweaked.cc/module/term.html#v:setTextColour) setTextColour(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L174) Set the colour that new text will be written as. ### Parameters 1. colour `number` The new text colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants. ### Changes * **New in version 1.45** * **Changed in version 1.80pr1:** Standard computers can now use all 16 colors, being changed to grayscale on screen. [](https://tweaked.cc/module/term.html#v:setTextColor) setTextColor(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L174) Set the colour that new text will be written as. ### Parameters 1. colour `number` The new text colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants. ### Changes * **New in version 1.45** * **Changed in version 1.80pr1:** Standard computers can now use all 16 colors, being changed to grayscale on screen. [](https://tweaked.cc/module/term.html#v:getBackgroundColour) getBackgroundColour()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L192) Return the current background colour. This is used when [writing text](https://tweaked.cc/module/term.html#v:write) and [clearing](https://tweaked.cc/module/term.html#v:clear) the terminal. ### Returns 1. `number` The current background colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants, returned by this function. ### Changes * **New in version 1.74** [](https://tweaked.cc/module/term.html#v:getBackgroundColor) getBackgroundColor()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L192) Return the current background colour. This is used when [writing text](https://tweaked.cc/module/term.html#v:write) and [clearing](https://tweaked.cc/module/term.html#v:clear) the terminal. ### Returns 1. `number` The current background colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants, returned by this function. ### Changes * **New in version 1.74** [](https://tweaked.cc/module/term.html#v:setBackgroundColour) setBackgroundColour(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L207) Set the current background colour. This is used when [writing text](https://tweaked.cc/module/term.html#v:write) and [clearing](https://tweaked.cc/module/term.html#v:clear) the terminal. ### Parameters 1. colour `number` The new background colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants. ### Changes * **New in version 1.45** * **Changed in version 1.80pr1:** Standard computers can now use all 16 colors, being changed to grayscale on screen. [](https://tweaked.cc/module/term.html#v:setBackgroundColor) setBackgroundColor(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L207) Set the current background colour. This is used when [writing text](https://tweaked.cc/module/term.html#v:write) and [clearing](https://tweaked.cc/module/term.html#v:clear) the terminal. ### Parameters 1. colour `number` The new background colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants. ### Changes * **New in version 1.45** * **Changed in version 1.80pr1:** Standard computers can now use all 16 colors, being changed to grayscale on screen. [](https://tweaked.cc/module/term.html#v:isColour) isColour()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L226) Determine if this terminal supports colour. Terminals which do not support colour will still allow writing coloured text/backgrounds, but it will be displayed in greyscale. ### Returns 1. `boolean` Whether this terminal supports colour. ### Changes * **New in version 1.45** [](https://tweaked.cc/module/term.html#v:isColor) isColor()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L226) Determine if this terminal supports colour. Terminals which do not support colour will still allow writing coloured text/backgrounds, but it will be displayed in greyscale. ### Returns 1. `boolean` Whether this terminal supports colour. ### Changes * **New in version 1.45** [](https://tweaked.cc/module/term.html#v:blit) blit(text, textColour, backgroundColour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L253) Writes `text` to the terminal with the specific foreground and background colours. As with [`write`](https://tweaked.cc/module/term.html#v:write) , the text will be written at the current cursor location, with the cursor moving to the end of the text. `textColour` and `backgroundColour` must both be strings the same length as `text`. All characters represent a single hexadecimal digit, which is converted to one of CC's colours. For instance, `"a"` corresponds to purple. ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The text to write. 2. textColour [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The corresponding text colours. 3. backgroundColour [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The corresponding background colours. ### Throws * If the three inputs are not the same length. ### Usage * Prints "Hello, world!" in rainbow text. Run ᐅ [term.blit](https://tweaked.cc/module/term.html#v:blit "Writes text to the terminal with the specific foreground and background colours.") ("Hello, world!","01234456789ab","0000000000000") ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants, and their hexadecimal values. ### Changes * **New in version 1.74** * **Changed in version 1.80pr1:** Standard computers can now use all 16 colors, being changed to grayscale on screen. [](https://tweaked.cc/module/term.html#v:setPaletteColour) setPaletteColour(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L299) Set the palette for a specific colour. ComputerCraft's palette system allows you to change how a specific colour should be displayed. For instance, you can make [`colors.red`](https://tweaked.cc/module/colors.html#v:red) _more red_ by setting its palette to #FF0000. This does now allow you to draw more colours - you are still limited to 16 on the screen at one time - but you can change _which_ colours are used. ### Parameters 1. index `number` The colour whose palette should be changed. 2. colour `number` A 24-bit integer representing the RGB value of the colour. For instance the integer `0xFF0000` corresponds to the colour #FF0000. #### Or 1. index `number` The colour whose palette should be changed. 2. r `number` The intensity of the red channel, between 0 and 1. 3. g `number` The intensity of the green channel, between 0 and 1. 4. b `number` The intensity of the blue channel, between 0 and 1. ### Usage * Change the [red colour](https://tweaked.cc/module/colors.html#v:red) from the default #CC4C4C to #FF0000. Run ᐅ [term.setPaletteColour](https://tweaked.cc/module/term.html#v:setPaletteColour "Set the palette for a specific colour.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") , 0xFF0000) [term.setTextColour](https://tweaked.cc/module/term.html#v:setTextColour "Set the colour that new text will be written as.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") ) print("Hello, world!") * As above, but specifying each colour channel separately. Run ᐅ [term.setPaletteColour](https://tweaked.cc/module/term.html#v:setPaletteColour "Set the palette for a specific colour.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") , 1, 0, 0) [term.setTextColour](https://tweaked.cc/module/term.html#v:setTextColour "Set the colour that new text will be written as.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") ) print("Hello, world!") ### See also * **[`colors.unpackRGB`](https://tweaked.cc/module/colors.html#v:unpackRGB) ** To convert from the 24-bit format to three separate channels. * **[`colors.packRGB`](https://tweaked.cc/module/colors.html#v:packRGB) ** To convert from three separate channels to the 24-bit format. ### Changes * **New in version 1.80pr1** [](https://tweaked.cc/module/term.html#v:setPaletteColor) setPaletteColor(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L299) Set the palette for a specific colour. ComputerCraft's palette system allows you to change how a specific colour should be displayed. For instance, you can make [`colors.red`](https://tweaked.cc/module/colors.html#v:red) _more red_ by setting its palette to #FF0000. This does now allow you to draw more colours - you are still limited to 16 on the screen at one time - but you can change _which_ colours are used. ### Parameters 1. index `number` The colour whose palette should be changed. 2. colour `number` A 24-bit integer representing the RGB value of the colour. For instance the integer `0xFF0000` corresponds to the colour #FF0000. #### Or 1. index `number` The colour whose palette should be changed. 2. r `number` The intensity of the red channel, between 0 and 1. 3. g `number` The intensity of the green channel, between 0 and 1. 4. b `number` The intensity of the blue channel, between 0 and 1. ### Usage * Change the [red colour](https://tweaked.cc/module/colors.html#v:red) from the default #CC4C4C to #FF0000. Run ᐅ [term.setPaletteColour](https://tweaked.cc/module/term.html#v:setPaletteColour "Set the palette for a specific colour.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") , 0xFF0000) [term.setTextColour](https://tweaked.cc/module/term.html#v:setTextColour "Set the colour that new text will be written as.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") ) print("Hello, world!") * As above, but specifying each colour channel separately. Run ᐅ [term.setPaletteColour](https://tweaked.cc/module/term.html#v:setPaletteColour "Set the palette for a specific colour.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") , 1, 0, 0) [term.setTextColour](https://tweaked.cc/module/term.html#v:setTextColour "Set the colour that new text will be written as.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") ) print("Hello, world!") ### See also * **[`colors.unpackRGB`](https://tweaked.cc/module/colors.html#v:unpackRGB) ** To convert from the 24-bit format to three separate channels. * **[`colors.packRGB`](https://tweaked.cc/module/colors.html#v:packRGB) ** To convert from three separate channels to the 24-bit format. ### Changes * **New in version 1.80pr1** [](https://tweaked.cc/module/term.html#v:getPaletteColour) getPaletteColour(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L325) Get the current palette for a specific colour. ### Parameters 1. colour `number` The colour whose palette should be fetched. ### Returns 1. `number` The red channel, will be between 0 and 1. 2. `number` The green channel, will be between 0 and 1. 3. `number` The blue channel, will be between 0 and 1. ### Changes * **New in version 1.80pr1** [](https://tweaked.cc/module/term.html#v:getPaletteColor) getPaletteColor(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L325) Get the current palette for a specific colour. ### Parameters 1. colour `number` The colour whose palette should be fetched. ### Returns 1. `number` The red channel, will be between 0 and 1. 2. `number` The green channel, will be between 0 and 1. 3. `number` The blue channel, will be between 0 and 1. ### Changes * **New in version 1.80pr1** [](https://tweaked.cc/module/term.html#v:redirect) redirect(target)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/term.lua#L40) Redirects terminal output to a monitor, a [`window`](https://tweaked.cc/module/window.html) , or any other custom terminal object. Once the redirect is performed, any calls to a "term" function - or to a function that makes use of a term function, as [`print`](https://www.lua.org/manual/5.1/manual.html#pdf-print) - will instead operate with the new terminal object. A "terminal object" is simply a table that contains functions with the same names - and general features - as those found in the term table. For example, a wrapped monitor is suitable. The redirect can be undone by pointing back to the previous terminal object (which this function returns whenever you switch). ### Parameters 1. target [`Redirect`](https://tweaked.cc/module/term.html#ty:Redirect) The terminal redirect the [`term`](https://tweaked.cc/module/term.html) API will draw to. ### Returns 1. [`Redirect`](https://tweaked.cc/module/term.html#ty:Redirect) The previous redirect object, as returned by [`term.current`](https://tweaked.cc/module/term.html#v:current) . ### Usage * Redirect to a monitor on the right of the computer. Run ᐅ [term.redirect](https://tweaked.cc/module/term.html#v:redirect "Redirects terminal output to a monitor, a window, or any other custom terminal object.") ([peripheral.wrap](https://tweaked.cc/module/peripheral.html#v:wrap "Get a table containing all functions available on a peripheral.") ("right")) ### Changes * **New in version 1.31** [](https://tweaked.cc/module/term.html#v:current) current()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/term.lua#L67) Returns the current terminal object of the computer. ### Returns 1. [`Redirect`](https://tweaked.cc/module/term.html#ty:Redirect) The current terminal redirect ### Usage * Create a new [`window`](https://tweaked.cc/module/window.html) which draws to the current redirect target. Run ᐅ [window.create](https://tweaked.cc/module/window.html#v:create "Returns a terminal object that is a space within the specified parent terminal object.") ([term.current](https://tweaked.cc/module/term.html#v:current "Returns the current terminal object of the computer.") (), 1, 1, 10, 10) ### Changes * **New in version 1.6** [](https://tweaked.cc/module/term.html#v:native) native()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/term.lua#L79) Get the native terminal object of the current computer. It is recommended you do not use this function unless you absolutely have to. In a multitasked environment, [`term.native`](https://tweaked.cc/module/term.html#v:native) will _not_ be the current terminal object, and so drawing may interfere with other programs. ### Returns 1. [`Redirect`](https://tweaked.cc/module/term.html#ty:Redirect) The native terminal redirect. ### Changes * **New in version 1.6** ### Types ### [](https://tweaked.cc/module/term.html#ty:Redirect) Redirect A base class for all objects which interact with a terminal. Namely the [`term`](https://tweaked.cc/module/term.html) and monitors. [](https://tweaked.cc/module/term.html#ty:Redirect:write) Redirect.write(text)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L38) Write `text` at the current cursor position, moving the cursor to the end of the text. Unlike functions like [`_G.write`](https://tweaked.cc/module/_G.html#v:write) and [`print`](https://www.lua.org/manual/5.1/manual.html#pdf-print) , this does not wrap the text - it simply copies the text to the current terminal line. ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The text to write. [](https://tweaked.cc/module/term.html#ty:Redirect:scroll) Redirect.scroll(y)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L57) Move all positions up (or down) by `y` pixels. Every pixel in the terminal will be replaced by the line `y` pixels below it. If `y` is negative, it will copy pixels from above instead. ### Parameters 1. y `number` The number of lines to move up by. This may be a negative number. [](https://tweaked.cc/module/term.html#ty:Redirect:getCursorPos) Redirect.getCursorPos()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L70) Get the position of the cursor. ### Returns 1. `number` The x position of the cursor. 2. `number` The y position of the cursor. [](https://tweaked.cc/module/term.html#ty:Redirect:setCursorPos) Redirect.setCursorPos(x, y)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L83) Set the position of the cursor. [Terminal writes](https://tweaked.cc/module/term.html#v:write) will begin from this position. ### Parameters 1. x `number` The new x position of the cursor. 2. y `number` The new y position of the cursor. [](https://tweaked.cc/module/term.html#ty:Redirect:getCursorBlink) Redirect.getCursorBlink()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L98) Checks if the cursor is currently blinking. ### Returns 1. `boolean` If the cursor is blinking. ### Changes * **New in version 1.80pr1.9** [](https://tweaked.cc/module/term.html#ty:Redirect:setCursorBlink) Redirect.setCursorBlink(blink)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L109) Sets whether the cursor should be visible (and blinking) at the current [cursor position](https://tweaked.cc/module/term.html#v:getCursorPos) . ### Parameters 1. blink `boolean` Whether the cursor should blink. [](https://tweaked.cc/module/term.html#ty:Redirect:getSize) Redirect.getSize()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L125) Get the size of the terminal. ### Returns 1. `number` The terminal's width. 2. `number` The terminal's height. [](https://tweaked.cc/module/term.html#ty:Redirect:clear) Redirect.clear()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L136) Clears the terminal, filling it with the [current background colour](https://tweaked.cc/module/term.html#v:getBackgroundColour) . [](https://tweaked.cc/module/term.html#ty:Redirect:clearLine) Redirect.clearLine()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L147) Clears the line the cursor is currently on, filling it with the [current background colour](https://tweaked.cc/module/term.html#v:getBackgroundColour) . [](https://tweaked.cc/module/term.html#ty:Redirect:getTextColour) Redirect.getTextColour()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L160) Return the colour that new text will be written as. ### Returns 1. `number` The current text colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants, returned by this function. ### Changes * **New in version 1.74** [](https://tweaked.cc/module/term.html#ty:Redirect:getTextColor) Redirect.getTextColor()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L160) Return the colour that new text will be written as. ### Returns 1. `number` The current text colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants, returned by this function. ### Changes * **New in version 1.74** [](https://tweaked.cc/module/term.html#ty:Redirect:setTextColour) Redirect.setTextColour(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L174) Set the colour that new text will be written as. ### Parameters 1. colour `number` The new text colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants. ### Changes * **New in version 1.45** * **Changed in version 1.80pr1:** Standard computers can now use all 16 colors, being changed to grayscale on screen. [](https://tweaked.cc/module/term.html#ty:Redirect:setTextColor) Redirect.setTextColor(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L174) Set the colour that new text will be written as. ### Parameters 1. colour `number` The new text colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants. ### Changes * **New in version 1.45** * **Changed in version 1.80pr1:** Standard computers can now use all 16 colors, being changed to grayscale on screen. [](https://tweaked.cc/module/term.html#ty:Redirect:getBackgroundColour) Redirect.getBackgroundColour()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L192) Return the current background colour. This is used when [writing text](https://tweaked.cc/module/term.html#v:write) and [clearing](https://tweaked.cc/module/term.html#v:clear) the terminal. ### Returns 1. `number` The current background colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants, returned by this function. ### Changes * **New in version 1.74** [](https://tweaked.cc/module/term.html#ty:Redirect:getBackgroundColor) Redirect.getBackgroundColor()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L192) Return the current background colour. This is used when [writing text](https://tweaked.cc/module/term.html#v:write) and [clearing](https://tweaked.cc/module/term.html#v:clear) the terminal. ### Returns 1. `number` The current background colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants, returned by this function. ### Changes * **New in version 1.74** [](https://tweaked.cc/module/term.html#ty:Redirect:setBackgroundColour) Redirect.setBackgroundColour(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L207) Set the current background colour. This is used when [writing text](https://tweaked.cc/module/term.html#v:write) and [clearing](https://tweaked.cc/module/term.html#v:clear) the terminal. ### Parameters 1. colour `number` The new background colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants. ### Changes * **New in version 1.45** * **Changed in version 1.80pr1:** Standard computers can now use all 16 colors, being changed to grayscale on screen. [](https://tweaked.cc/module/term.html#ty:Redirect:setBackgroundColor) Redirect.setBackgroundColor(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L207) Set the current background colour. This is used when [writing text](https://tweaked.cc/module/term.html#v:write) and [clearing](https://tweaked.cc/module/term.html#v:clear) the terminal. ### Parameters 1. colour `number` The new background colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants. ### Changes * **New in version 1.45** * **Changed in version 1.80pr1:** Standard computers can now use all 16 colors, being changed to grayscale on screen. [](https://tweaked.cc/module/term.html#ty:Redirect:isColour) Redirect.isColour()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L226) Determine if this terminal supports colour. Terminals which do not support colour will still allow writing coloured text/backgrounds, but it will be displayed in greyscale. ### Returns 1. `boolean` Whether this terminal supports colour. ### Changes * **New in version 1.45** [](https://tweaked.cc/module/term.html#ty:Redirect:isColor) Redirect.isColor()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L226) Determine if this terminal supports colour. Terminals which do not support colour will still allow writing coloured text/backgrounds, but it will be displayed in greyscale. ### Returns 1. `boolean` Whether this terminal supports colour. ### Changes * **New in version 1.45** [](https://tweaked.cc/module/term.html#ty:Redirect:blit) Redirect.blit(text, textColour, backgroundColour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L253) Writes `text` to the terminal with the specific foreground and background colours. As with [`write`](https://tweaked.cc/module/term.html#v:write) , the text will be written at the current cursor location, with the cursor moving to the end of the text. `textColour` and `backgroundColour` must both be strings the same length as `text`. All characters represent a single hexadecimal digit, which is converted to one of CC's colours. For instance, `"a"` corresponds to purple. ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The text to write. 2. textColour [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The corresponding text colours. 3. backgroundColour [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The corresponding background colours. ### Throws * If the three inputs are not the same length. ### Usage * Prints "Hello, world!" in rainbow text. Run ᐅ [term.blit](https://tweaked.cc/module/term.html#v:blit "Writes text to the terminal with the specific foreground and background colours.") ("Hello, world!","01234456789ab","0000000000000") ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants, and their hexadecimal values. ### Changes * **New in version 1.74** * **Changed in version 1.80pr1:** Standard computers can now use all 16 colors, being changed to grayscale on screen. [](https://tweaked.cc/module/term.html#ty:Redirect:setPaletteColour) Redirect.setPaletteColour(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L299) Set the palette for a specific colour. ComputerCraft's palette system allows you to change how a specific colour should be displayed. For instance, you can make [`colors.red`](https://tweaked.cc/module/colors.html#v:red) _more red_ by setting its palette to #FF0000. This does now allow you to draw more colours - you are still limited to 16 on the screen at one time - but you can change _which_ colours are used. ### Parameters 1. index `number` The colour whose palette should be changed. 2. colour `number` A 24-bit integer representing the RGB value of the colour. For instance the integer `0xFF0000` corresponds to the colour #FF0000. #### Or 1. index `number` The colour whose palette should be changed. 2. r `number` The intensity of the red channel, between 0 and 1. 3. g `number` The intensity of the green channel, between 0 and 1. 4. b `number` The intensity of the blue channel, between 0 and 1. ### Usage * Change the [red colour](https://tweaked.cc/module/colors.html#v:red) from the default #CC4C4C to #FF0000. Run ᐅ [term.setPaletteColour](https://tweaked.cc/module/term.html#v:setPaletteColour "Set the palette for a specific colour.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") , 0xFF0000) [term.setTextColour](https://tweaked.cc/module/term.html#v:setTextColour "Set the colour that new text will be written as.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") ) print("Hello, world!") * As above, but specifying each colour channel separately. Run ᐅ [term.setPaletteColour](https://tweaked.cc/module/term.html#v:setPaletteColour "Set the palette for a specific colour.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") , 1, 0, 0) [term.setTextColour](https://tweaked.cc/module/term.html#v:setTextColour "Set the colour that new text will be written as.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") ) print("Hello, world!") ### See also * **[`colors.unpackRGB`](https://tweaked.cc/module/colors.html#v:unpackRGB) ** To convert from the 24-bit format to three separate channels. * **[`colors.packRGB`](https://tweaked.cc/module/colors.html#v:packRGB) ** To convert from three separate channels to the 24-bit format. ### Changes * **New in version 1.80pr1** [](https://tweaked.cc/module/term.html#ty:Redirect:setPaletteColor) Redirect.setPaletteColor(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L299) Set the palette for a specific colour. ComputerCraft's palette system allows you to change how a specific colour should be displayed. For instance, you can make [`colors.red`](https://tweaked.cc/module/colors.html#v:red) _more red_ by setting its palette to #FF0000. This does now allow you to draw more colours - you are still limited to 16 on the screen at one time - but you can change _which_ colours are used. ### Parameters 1. index `number` The colour whose palette should be changed. 2. colour `number` A 24-bit integer representing the RGB value of the colour. For instance the integer `0xFF0000` corresponds to the colour #FF0000. #### Or 1. index `number` The colour whose palette should be changed. 2. r `number` The intensity of the red channel, between 0 and 1. 3. g `number` The intensity of the green channel, between 0 and 1. 4. b `number` The intensity of the blue channel, between 0 and 1. ### Usage * Change the [red colour](https://tweaked.cc/module/colors.html#v:red) from the default #CC4C4C to #FF0000. Run ᐅ [term.setPaletteColour](https://tweaked.cc/module/term.html#v:setPaletteColour "Set the palette for a specific colour.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") , 0xFF0000) [term.setTextColour](https://tweaked.cc/module/term.html#v:setTextColour "Set the colour that new text will be written as.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") ) print("Hello, world!") * As above, but specifying each colour channel separately. Run ᐅ [term.setPaletteColour](https://tweaked.cc/module/term.html#v:setPaletteColour "Set the palette for a specific colour.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") , 1, 0, 0) [term.setTextColour](https://tweaked.cc/module/term.html#v:setTextColour "Set the colour that new text will be written as.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") ) print("Hello, world!") ### See also * **[`colors.unpackRGB`](https://tweaked.cc/module/colors.html#v:unpackRGB) ** To convert from the 24-bit format to three separate channels. * **[`colors.packRGB`](https://tweaked.cc/module/colors.html#v:packRGB) ** To convert from three separate channels to the 24-bit format. ### Changes * **New in version 1.80pr1** [](https://tweaked.cc/module/term.html#ty:Redirect:getPaletteColour) Redirect.getPaletteColour(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L325) Get the current palette for a specific colour. ### Parameters 1. colour `number` The colour whose palette should be fetched. ### Returns 1. `number` The red channel, will be between 0 and 1. 2. `number` The green channel, will be between 0 and 1. 3. `number` The blue channel, will be between 0 and 1. ### Changes * **New in version 1.80pr1** [](https://tweaked.cc/module/term.html#ty:Redirect:getPaletteColor) Redirect.getPaletteColor(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L325) Get the current palette for a specific colour. ### Parameters 1. colour `number` The colour whose palette should be fetched. ### Returns 1. `number` The red channel, will be between 0 and 1. 2. `number` The green channel, will be between 0 and 1. 3. `number` The blue channel, will be between 0 and 1. ### Changes * **New in version 1.80pr1** --- # window window ====== A [terminal redirect](https://tweaked.cc/module/term.html#ty:Redirect) occupying a smaller area of an existing terminal. This allows for easy definition of spaces within the display that can be written/drawn to, then later redrawn/repositioned/etc as need be. The API itself contains only one function, [`window.create`](https://tweaked.cc/module/window.html#v:create) , which returns the windows themselves. Windows are considered terminal objects - as such, they have access to nearly all the commands in the term API (plus a few extras of their own, listed within said API) and are valid targets to redirect to. Each window has a "parent" terminal object, which can be the computer's own display, a monitor, another window or even other, user-defined terminal objects. Whenever a window is rendered to, the actual screen-writing is performed via that parent (or, if that has one too, then that parent, and so forth). Bear in mind that the cursor of a window's parent will hence be moved around etc when writing a given child window. Windows retain a memory of everything rendered "through" them (hence acting as display buffers), and if the parent's display is wiped, the window's content can be easily redrawn later. A window may also be flagged as invisible, preventing any changes to it from being rendered until it's flagged as visible once more. A parent terminal object may have multiple children assigned to it, and windows may overlap. For example, the Multishell system functions by assigning each tab a window covering the screen, each using the starting terminal display as its parent, and only one of which is visible at a time. ### Changes * **New in version 1.6** | | | | --- | --- | | [create(parent, nX, nY, nWidth, nHeight \[, bStartVisible\])](https://tweaked.cc/module/window.html#v:create) | Returns a terminal object that is a space within the specified parent terminal object. | [](https://tweaked.cc/module/window.html#v:create) create(parent, nX, nY, nWidth, nHeight \[, bStartVisible\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L106) Returns a terminal object that is a space within the specified parent terminal object. This can then be used (or even redirected to) in the same manner as eg a wrapped monitor. Refer to [the term API](https://tweaked.cc/module/term.html) for a list of functions available to it. [`term`](https://tweaked.cc/module/term.html) itself may not be passed as the parent, though [`term.native`](https://tweaked.cc/module/term.html#v:native) is acceptable. Generally, [`term.current`](https://tweaked.cc/module/term.html#v:current) or a wrapped monitor will be most suitable, though windows may even have other windows assigned as their parents. ### Parameters 1. parent [`term.Redirect`](https://tweaked.cc/module/term.html#ty:Redirect) The parent terminal redirect to draw to. 2. nX `number` The x coordinate this window is drawn at in the parent terminal 3. nY `number` The y coordinate this window is drawn at in the parent terminal 4. nWidth `number` The width of this window 5. nHeight `number` The height of this window 6. bStartVisible? `boolean` Whether this window is visible by default. Defaults to `true`. ### Returns 1. [`Window`](https://tweaked.cc/module/window.html#ty:Window) The constructed window ### Usage * Create a smaller window, fill it red and write some text to it. Run ᐅ local my\_window \= [window.create](https://tweaked.cc/module/window.html#v:create "Returns a terminal object that is a space within the specified parent terminal object.") ([term.current](https://tweaked.cc/module/term.html#v:current "Returns the current terminal object of the computer.") (), 1, 1, 20, 5) my\_window.setBackgroundColour([colours](https://tweaked.cc/module/colours.html "An alternative version of colors for lovers of British spelling.") .red) my\_window.setTextColour([colours](https://tweaked.cc/module/colours.html "An alternative version of colors for lovers of British spelling.") .white) my\_window.clear() my\_window.write("Testing my window!") * Create a smaller window and redirect to it. Run ᐅ local my\_window \= [window.create](https://tweaked.cc/module/window.html#v:create "Returns a terminal object that is a space within the specified parent terminal object.") ([term.current](https://tweaked.cc/module/term.html#v:current "Returns the current terminal object of the computer.") (), 1, 1, 25, 5) [term.redirect](https://tweaked.cc/module/term.html#v:redirect "Redirects terminal output to a monitor, a window, or any other custom terminal object.") (my\_window) print("Writing some long text which will wrap around and show the bounds of this window.") ### Changes * **New in version 1.6** ### Types ### [](https://tweaked.cc/module/window.html#ty:Window) Window The window object. Refer to the [module's documentation](https://tweaked.cc/module/window.html) for a full description. ### See also * **[`term.Redirect`](https://tweaked.cc/module/term.html#ty:Redirect) ** [](https://tweaked.cc/module/window.html#ty:Window:write) Window.write(sText)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L268) ### Parameters 1. sText [](https://tweaked.cc/module/window.html#ty:Window:blit) Window.blit(sText, sTextColor, sBackgroundColor)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L273) ### Parameters 1. sText 2. sTextColor 3. sBackgroundColor [](https://tweaked.cc/module/window.html#ty:Window:clear) Window.clear()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L285) [](https://tweaked.cc/module/window.html#ty:Window:clearLine) Window.clearLine()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L302) [](https://tweaked.cc/module/window.html#ty:Window:getCursorPos) Window.getCursorPos()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L316) [](https://tweaked.cc/module/window.html#ty:Window:setCursorPos) Window.setCursorPos(x, y)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L320) ### Parameters 1. x 2. y [](https://tweaked.cc/module/window.html#ty:Window:setCursorBlink) Window.setCursorBlink(blink)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L330) ### Parameters 1. blink [](https://tweaked.cc/module/window.html#ty:Window:getCursorBlink) Window.getCursorBlink()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L338) [](https://tweaked.cc/module/window.html#ty:Window:isColor) Window.isColor()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L346) [](https://tweaked.cc/module/window.html#ty:Window:isColour) Window.isColour()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L350) [](https://tweaked.cc/module/window.html#ty:Window:setTextColor) Window.setTextColor(color)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L354) ### Parameters 1. color [](https://tweaked.cc/module/window.html#ty:Window:setTextColour) Window.setTextColour(color)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L354) ### Parameters 1. color [](https://tweaked.cc/module/window.html#ty:Window:setPaletteColour) Window.setPaletteColour(colour, r, g, b)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L366) ### Parameters 1. colour 2. r 3. g 4. b [](https://tweaked.cc/module/window.html#ty:Window:setPaletteColor) Window.setPaletteColor(colour, r, g, b)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L366) ### Parameters 1. colour 2. r 3. g 4. b [](https://tweaked.cc/module/window.html#ty:Window:getPaletteColour) Window.getPaletteColour(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L391) ### Parameters 1. colour [](https://tweaked.cc/module/window.html#ty:Window:getPaletteColor) Window.getPaletteColor(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L391) ### Parameters 1. colour [](https://tweaked.cc/module/window.html#ty:Window:setBackgroundColor) Window.setBackgroundColor(color)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L399) ### Parameters 1. color [](https://tweaked.cc/module/window.html#ty:Window:setBackgroundColour) Window.setBackgroundColour(color)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L399) ### Parameters 1. color [](https://tweaked.cc/module/window.html#ty:Window:getSize) Window.getSize()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L407) [](https://tweaked.cc/module/window.html#ty:Window:scroll) Window.scroll(n)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L411) ### Parameters 1. n [](https://tweaked.cc/module/window.html#ty:Window:getTextColor) Window.getTextColor()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L435) [](https://tweaked.cc/module/window.html#ty:Window:getTextColour) Window.getTextColour()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L439) [](https://tweaked.cc/module/window.html#ty:Window:getBackgroundColor) Window.getBackgroundColor()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L443) [](https://tweaked.cc/module/window.html#ty:Window:getBackgroundColour) Window.getBackgroundColour()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L447) [](https://tweaked.cc/module/window.html#ty:Window:getLine) Window.getLine(y)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L459) Get the buffered contents of a line in this window. ### Parameters 1. y `number` The y position of the line to get. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The textual content of this line. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The text colours of this line, suitable for use with [`term.blit`](https://tweaked.cc/module/term.html#v:blit) . 3. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The background colours of this line, suitable for use with [`term.blit`](https://tweaked.cc/module/term.html#v:blit) . ### Throws * If `y` is not between 1 and this window's height. ### Changes * **New in version 1.84.0** [](https://tweaked.cc/module/window.html#ty:Window:setVisible) Window.setVisible(visible)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L478) Set whether this window is visible. Invisible windows will not be drawn to the screen until they are made visible again. Making an invisible window visible will immediately draw it. ### Parameters 1. visible `boolean` Whether this window is visible. [](https://tweaked.cc/module/window.html#ty:Window:isVisible) Window.isVisible()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L494) Get whether this window is visible. Invisible windows will not be drawn to the screen until they are made visible again. ### Returns 1. `boolean` Whether this window is visible. ### See also * **[`Window:setVisible`](https://tweaked.cc/module/window.html#ty:Window:setVisible) ** ### Changes * **New in version 1.94.0** [](https://tweaked.cc/module/window.html#ty:Window:redraw) Window.redraw()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L500) Draw this window. This does nothing if the window is not visible. ### See also * **[`Window:setVisible`](https://tweaked.cc/module/window.html#ty:Window:setVisible) ** [](https://tweaked.cc/module/window.html#ty:Window:restoreCursor) Window.restoreCursor()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L512) Set the current terminal's cursor to where this window's cursor is. This does nothing if the window is not visible. [](https://tweaked.cc/module/window.html#ty:Window:getPosition) Window.getPosition()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L524) Get the position of the top left corner of this window. ### Returns 1. `number` The x position of this window. 2. `number` The y position of this window. [](https://tweaked.cc/module/window.html#ty:Window:reposition) Window.reposition(new\_x, new\_y \[, new\_width, new\_height \[, new\_parent\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua#L541) Reposition or resize the given window. This function also accepts arguments to change the size of this window. It is recommended that you fire a `term_resize` event after changing a window's, to allow programs to adjust their sizing. ### Parameters 1. new\_x `number` The new x position of this window. 2. new\_y `number` The new y position of this window. 3. new\_width? `number` The new width of this window. 4. new\_height `number` The new height of this window. 5. new\_parent? [`term.Redirect`](https://tweaked.cc/module/term.html#ty:Redirect) The new redirect object this window should draw to. ### Changes * **Changed in version 1.85.0:** Add `new_parent` parameter. --- # cc.audio.dfpwm cc.audio.dfpwm ============== Convert between streams of DFPWM audio data and a list of amplitudes. DFPWM (Dynamic Filter Pulse Width Modulation) is an audio codec designed by GreaseMonkey. It's a relatively compact format compared to raw PCM data, only using 1 bit per sample, but is simple enough to encode and decode in real time. Typically DFPWM audio is read from [the filesystem](https://tweaked.cc/module/fs.html#ty:ReadHandle) or [a web request](https://tweaked.cc/module/http.html#ty:Response) as a string, and converted to a format suitable for [`speaker.playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) . Encoding and decoding files --------------------------- This module exposes two key functions, [`make_decoder`](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_decoder) and [`make_encoder`](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_encoder) , which construct a new decoder or encoder. The returned encoder/decoder is itself a function, which converts between the two kinds of data. These encoders and decoders have lots of hidden state, so you should be careful to use the same encoder or decoder for a specific audio stream. Typically you will want to create a decoder for each stream of audio you read, and an encoder for each one you write. Converting audio to DFPWM ------------------------- DFPWM is not a popular file format and so standard audio processing tools may not have an option to export to it. Instead, you can convert audio files online using [music.madefor.cc](https://music.madefor.cc/ "DFPWM audio converter for Computronics and CC: Tweaked") , the [LionRay Wav Converter](https://github.com/gamax92/LionRay/ "LionRay Wav Converter ") Java application or [FFmpeg](https://ffmpeg.org/ "FFmpeg command-line audio manipulation library") 5.1 or later. ### Usage * Reads "data/example.dfpwm" in chunks, decodes them and then doubles the speed of the audio. The resulting audio is then re-encoded and saved to "speedy.dfpwm". This processed audio can then be played with the `speaker` program. Run ᐅ local [dfpwm](https://tweaked.cc/library/cc.audio.dfpwm.html "Convert between streams of DFPWM audio data and a list of amplitudes.") \= require("cc.audio.dfpwm") local encoder \= [dfpwm.make\_encoder](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_encoder "Create a new encoder for converting PCM audio data into DFPWM.") () local decoder \= [dfpwm.make\_decoder](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_decoder "Create a new decoder for converting DFPWM into PCM audio data.") () local out \= [fs.open](https://tweaked.cc/module/fs.html#v:open "Opens a file for reading or writing at a path.") ("speedy.dfpwm", "wb") for input in [io.lines](https://tweaked.cc/module/io.html#v:lines "Opens the given file name in read mode and returns an iterator that, each time it is called, returns a new line from the file.") ("data/example.dfpwm", 16 \* 1024 \* 2) do local decoded \= decoder(input) local output \= {} \-- Read two samples at once and take the average. for i \= 1, #decoded, 2 do local value\_1, value\_2 \= decoded\[i\], decoded\[i + 1\] output\[(i + 1) / 2\] \= (value\_1 + value\_2) / 2 end out.write(encoder(output)) sleep(0) \-- This program takes a while to run, so we need to make sure we yield. end out.close() ### See also * **[`Playing audio with speakers`](https://tweaked.cc/guide/speaker_audio.html) ** Gives a more general introduction to audio processing and the speaker. * **[`speaker.playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) ** To play the decoded audio data. ### Changes * **New in version 1.100.0** | | | | --- | --- | | [make\_encoder()](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_encoder) | Create a new encoder for converting PCM audio data into DFPWM. | | [encode(input)](https://tweaked.cc/library/cc.audio.dfpwm.html#v:encode) | A convenience function for encoding a complete file of audio at once. | | [make\_decoder()](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_decoder) | Create a new decoder for converting DFPWM into PCM audio data. | | [decode(input)](https://tweaked.cc/library/cc.audio.dfpwm.html#v:decode) | A convenience function for decoding a complete file of audio at once. | [](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_encoder) make\_encoder()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/audio/dfpwm.lua#L104) Create a new encoder for converting PCM audio data into DFPWM. The returned encoder is itself a function. This function accepts a table of amplitude data between -128 and 127 and returns the encoded DFPWM data. ##### ⚠ Reusing encoders Encoders have lots of internal state which tracks the state of the current stream. If you reuse an encoder for multiple streams, or use different encoders for the same stream, the resulting audio may not sound correct. ### Returns 1. function(pcm: { `number`... }):[`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The encoder function ### See also * **[`encode`](https://tweaked.cc/library/cc.audio.dfpwm.html#v:encode) ** A helper function for encoding an entire file of audio at once. [](https://tweaked.cc/library/cc.audio.dfpwm.html#v:encode) encode(input)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/audio/dfpwm.lua#L220) A convenience function for encoding a complete file of audio at once. This should only be used for complete pieces of audio. If you are writing multiple chunks to the same place, you should use an encoder returned by [`make_encoder`](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_encoder) instead. ### Parameters 1. input { `number`... } The table of amplitude data. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The encoded DFPWM data. ### See also * **[`make_encoder`](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_encoder) ** [](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_decoder) make\_decoder()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/audio/dfpwm.lua#L162) Create a new decoder for converting DFPWM into PCM audio data. The returned decoder is itself a function. This function accepts a string and returns a table of amplitudes, each value between -128 and 127. ##### ⚠ Reusing decoders Decoders have lots of internal state which tracks the state of the current stream. If you reuse an decoder for multiple streams, or use different decoders for the same stream, the resulting audio may not sound correct. ### Returns 1. function(dfpwm: [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ):{ `number`... } The encoder function ### Usage * Reads "data/example.dfpwm" in blocks of 16KiB (the speaker can accept a maximum of 128×1024 samples), decodes them and then plays them through the speaker. Run ᐅ local [dfpwm](https://tweaked.cc/library/cc.audio.dfpwm.html "Convert between streams of DFPWM audio data and a list of amplitudes.") \= require "cc.audio.dfpwm" local speaker \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("speaker") local decoder \= [dfpwm.make\_decoder](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_decoder "Create a new decoder for converting DFPWM into PCM audio data.") () for input in [io.lines](https://tweaked.cc/module/io.html#v:lines "Opens the given file name in read mode and returns an iterator that, each time it is called, returns a new line from the file.") ("data/example.dfpwm", 16 \* 1024) do local decoded \= decoder(input) while not speaker.playAudio(decoded) do [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("speaker\_audio\_empty") end end ### See also * **[`decode`](https://tweaked.cc/library/cc.audio.dfpwm.html#v:decode) ** A helper function for decoding an entire file of audio at once. [](https://tweaked.cc/library/cc.audio.dfpwm.html#v:decode) decode(input)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/audio/dfpwm.lua#L206) A convenience function for decoding a complete file of audio at once. This should only be used for short files. For larger files, one should read the file in chunks and process it using [`make_decoder`](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_decoder) . ### Parameters 1. input [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The DFPWM data to convert. ### Returns 1. { `number`... } The produced amplitude data. ### See also * **[`make_decoder`](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_decoder) ** --- # cc.base64 cc.base64 ========= The [`cc.base64`](https://tweaked.cc/library/cc.base64.html) module provides functions for converting binary data to and from [Base64](https://en.wikipedia.org/wiki/Base64) . ### Usage * Encode and decode a string from Base64. Run ᐅ local [base64](https://tweaked.cc/library/cc.base64.html "The cc.base64 module provides functions for converting binary data to and from Base64.") \= require "cc.base64" print([base64.encode](https://tweaked.cc/library/cc.base64.html#v:encode "Encode a binary string to Base64.") ("Hello, world")) print([base64.decode](https://tweaked.cc/library/cc.base64.html#v:decode "Decode a Base64-encoded string back to its original data.") ("SGVsbG8sIHdvcmxk")) ### Changes * **New in version 1.119.0** | | | | --- | --- | | [encode(str \[, alt\_chars="+/"\])](https://tweaked.cc/library/cc.base64.html#v:encode) | Encode a binary string to Base64. | | [decode(str \[, alt\_chars="+/"\])](https://tweaked.cc/library/cc.base64.html#v:decode) | Decode a Base64-encoded string back to its original data. | [](https://tweaked.cc/library/cc.base64.html#v:encode) encode(str \[, alt\_chars="+/"\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/base64.lua#L46) Encode a binary string to Base64. ### Parameters 1. str [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The binary data to encode. 2. alt\_chars? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) = A string of length 2, used to encode the 62nd and 63rd bit. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The Base64 encoded data. ### Usage * Convert a string to Base64 Run ᐅ local [base64](https://tweaked.cc/library/cc.base64.html "The cc.base64 module provides functions for converting binary data to and from Base64.") \= require "cc.base64" print([base64.encode](https://tweaked.cc/library/cc.base64.html#v:encode "Encode a binary string to Base64.") ("Hello, world!")) * Convert a string to [base64url](https://datatracker.ietf.org/doc/html/rfc4648#section-5 "Base 64 Encoding with URL and Filename Safe Alphabet") . This is an alternative form of Base64, where the string is encoded with `"-_"` instead of `"+/"`. This allows the string to be more easily used in URLs, though the padding `=` will still need escaping with [`textutils.urlEncode`](https://tweaked.cc/module/textutils.html#v:urlEncode) . Run ᐅ local [base64](https://tweaked.cc/library/cc.base64.html "The cc.base64 module provides functions for converting binary data to and from Base64.") \= require "cc.base64" print([base64.encode](https://tweaked.cc/library/cc.base64.html#v:encode "Encode a binary string to Base64.") ("Test: \\255\\230", "-\_")) [](https://tweaked.cc/library/cc.base64.html#v:decode) decode(str \[, alt\_chars="+/"\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/base64.lua#L120) Decode a Base64-encoded string back to its original data. This function requires the data to be valid Base64 with the trailing padding bytes. ### Parameters 1. str [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The Base64-encoded data to decode. 2. alt\_chars? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) = A string of length 2, used to encode the 62nd and 63rd bit. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The decoded data. #### Or 1. nil If the data is not valid Base64, or is missing the trailing padding. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The reason the data failed to decode. ### Usage * Decode a string from Base64 Run ᐅ local [base64](https://tweaked.cc/library/cc.base64.html "The cc.base64 module provides functions for converting binary data to and from Base64.") \= require "cc.base64" print([base64.decode](https://tweaked.cc/library/cc.base64.html#v:decode "Decode a Base64-encoded string back to its original data.") ("SGVsbG8sIHdvcmxk")) * Decode [base64url](https://datatracker.ietf.org/doc/html/rfc4648#section-5 "Base 64 Encoding with URL and Filename Safe Alphabet") \-encoded data. Run ᐅ local [base64](https://tweaked.cc/library/cc.base64.html "The cc.base64 module provides functions for converting binary data to and from Base64.") \= require "cc.base64" print([base64.decode](https://tweaked.cc/library/cc.base64.html#v:decode "Decode a Base64-encoded string back to its original data.") ("VGVzdDog\_-Y=", "-\_")) --- # cc.completion cc.completion ============= A collection of helper methods for working with input completion, such as that require by [`_G.read`](https://tweaked.cc/module/_G.html#v:read) . ### See also * **[`cc.shell.completion`](https://tweaked.cc/library/cc.shell.completion.html) ** For additional helpers to use with [`shell.setCompletionFunction`](https://tweaked.cc/module/shell.html#v:setCompletionFunction) . ### Changes * **New in version 1.85.0** | | | | --- | --- | | [choice(text, choices \[, add\_space\])](https://tweaked.cc/library/cc.completion.html#v:choice) | Complete from a choice of one or more strings. | | [peripheral(text \[, add\_space\])](https://tweaked.cc/library/cc.completion.html#v:peripheral) | Complete the name of a currently attached peripheral. | | [side(text \[, add\_space\])](https://tweaked.cc/library/cc.completion.html#v:side) | Complete the side of a computer. | | [setting(text \[, add\_space\])](https://tweaked.cc/library/cc.completion.html#v:setting) | Complete a [setting](https://tweaked.cc/module/settings.html)
. | | [command(text \[, add\_space\])](https://tweaked.cc/library/cc.completion.html#v:command) | Complete the name of a Minecraft [command](https://tweaked.cc/module/commands.html)
. | [](https://tweaked.cc/library/cc.completion.html#v:choice) choice(text, choices \[, add\_space\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua#L42) Complete from a choice of one or more strings. ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The input string to complete. 2. choices { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } The list of choices to complete from. 3. add\_space? `boolean` Whether to add a space after the completed item. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } A list of suffixes of matching strings. ### Usage * Call [`_G.read`](https://tweaked.cc/module/_G.html#v:read) , completing the names of various animals. Run ᐅ local [completion](https://tweaked.cc/library/cc.completion.html "A collection of helper methods for working with input completion, such as that require by _G.read.") \= require "cc.completion" local animals \= { "dog", "cat", "lion", "unicorn" } read(nil, nil, function(text) return [completion.choice](https://tweaked.cc/library/cc.completion.html#v:choice "Complete from a choice of one or more strings.") (text, animals) end) [](https://tweaked.cc/library/cc.completion.html#v:peripheral) peripheral(text \[, add\_space\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua#L57) Complete the name of a currently attached peripheral. ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The input string to complete. 2. add\_space? `boolean` Whether to add a space after the completed name. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } A list of suffixes of matching peripherals. ### Usage * Run ᐅ local [completion](https://tweaked.cc/library/cc.completion.html "A collection of helper methods for working with input completion, such as that require by _G.read.") \= require "cc.completion" read(nil, nil, [completion.peripheral](https://tweaked.cc/library/cc.completion.html#v:peripheral "Complete the name of a currently attached peripheral.") ) [](https://tweaked.cc/library/cc.completion.html#v:side) side(text \[, add\_space\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua#L73) Complete the side of a computer. ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The input string to complete. 2. add\_space? `boolean` Whether to add a space after the completed side. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } A list of suffixes of matching sides. ### Usage * Run ᐅ local [completion](https://tweaked.cc/library/cc.completion.html "A collection of helper methods for working with input completion, such as that require by _G.read.") \= require "cc.completion" read(nil, nil, [completion.side](https://tweaked.cc/library/cc.completion.html#v:side "Complete the side of a computer.") ) [](https://tweaked.cc/library/cc.completion.html#v:setting) setting(text \[, add\_space\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua#L87) Complete a [setting](https://tweaked.cc/module/settings.html) . ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The input string to complete. 2. add\_space? `boolean` Whether to add a space after the completed settings. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } A list of suffixes of matching settings. ### Usage * Run ᐅ local [completion](https://tweaked.cc/library/cc.completion.html "A collection of helper methods for working with input completion, such as that require by _G.read.") \= require "cc.completion" read(nil, nil, [completion.setting](https://tweaked.cc/library/cc.completion.html#v:setting "Complete a setting.") ) [](https://tweaked.cc/library/cc.completion.html#v:command) command(text \[, add\_space\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua#L103) Complete the name of a Minecraft [command](https://tweaked.cc/module/commands.html) . ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The input string to complete. 2. add\_space? `boolean` Whether to add a space after the completed command. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } A list of suffixes of matching commands. ### Usage * Run ᐅ local [completion](https://tweaked.cc/library/cc.completion.html "A collection of helper methods for working with input completion, such as that require by _G.read.") \= require "cc.completion" read(nil, nil, [completion.command](https://tweaked.cc/library/cc.completion.html#v:command "Complete the name of a Minecraft command.") ) --- # cc.expect cc.expect ========= The [`cc.expect`](https://tweaked.cc/library/cc.expect.html) library provides helper functions for verifying that function arguments are well-formed and of the correct type. ### Usage * Define a basic function and check it has the correct arguments. Run ᐅ local [expect](https://tweaked.cc/library/cc.expect.html "The cc.expect library provides helper functions for verifying that function arguments are well-formed and of the correct type.") \= require "cc.expect" local [expect](https://tweaked.cc/library/cc.expect.html#v:expect "Expect an argument to have a specific type.") , [field](https://tweaked.cc/library/cc.expect.html#v:field "Expect an field to have a specific type.") \= [expect.expect](https://tweaked.cc/library/cc.expect.html#v:expect "Expect an argument to have a specific type.") , [expect.field](https://tweaked.cc/library/cc.expect.html#v:field "Expect an field to have a specific type.") local function add\_person(name, info) [expect](https://tweaked.cc/library/cc.expect.html#v:expect "Expect an argument to have a specific type.") (1, name, "string") [expect](https://tweaked.cc/library/cc.expect.html#v:expect "Expect an argument to have a specific type.") (2, info, "table", "nil") if info then print("Got age=", [field](https://tweaked.cc/library/cc.expect.html#v:field "Expect an field to have a specific type.") (info, "age", "number")) print("Got gender=", [field](https://tweaked.cc/library/cc.expect.html#v:field "Expect an field to have a specific type.") (info, "gender", "string", "nil")) end end add\_person("Anastazja") \-- \`info' is optional add\_person("Kion", { age \= 23 }) \-- \`gender' is optional add\_person("Caoimhin", { age \= 23, gender \= true }) \-- error! ### Changes * **New in version 1.84.0** * **Changed in version 1.96.0:** The module can now be called directly as a function, which wraps around `expect.expect`. | | | | --- | --- | | [expect(index, value, ...)](https://tweaked.cc/library/cc.expect.html#v:expect) | Expect an argument to have a specific type. | | [field(tbl, index, ...)](https://tweaked.cc/library/cc.expect.html#v:field) | Expect an field to have a specific type. | | [range(num \[, min=-math.huge \[, max=math.huge\]\])](https://tweaked.cc/library/cc.expect.html#v:range) | Expect a number to be within a specific range. | [](https://tweaked.cc/library/cc.expect.html#v:expect) expect(index, value, ...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/expect.lua#L67) Expect an argument to have a specific type. ### Parameters 1. index `number` The 1-based argument index. 2. value The argument's value. 3. ... [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The allowed types of the argument. ### Returns 1. The given `value`. ### Throws * If the value is not one of the allowed types. [](https://tweaked.cc/library/cc.expect.html#v:field) field(tbl, index, ...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/expect.lua#L95) Expect an field to have a specific type. ### Parameters 1. tbl [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The table to index. 2. index [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The field name to check. 3. ... [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The allowed types of the argument. ### Returns 1. The contents of the given field. ### Throws * If the field is not one of the allowed types. [](https://tweaked.cc/library/cc.expect.html#v:range) range(num \[, min=-math.huge \[, max=math.huge\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/expect.lua#L126) Expect a number to be within a specific range. ### Parameters 1. num `number` The value to check. 2. min? `number` = The minimum value. 3. max? `number` = The maximum value. ### Returns 1. The given `value`. ### Throws * If the value is outside of the allowed range. ### Changes * **New in version 1.96.0** --- # cc.image.nft cc.image.nft ============ Read and draw nft ("Nitrogen Fingers Text") images. nft ("Nitrogen Fingers Text") is a file format for drawing basic images. Unlike the images that [`paintutils.parseImage`](https://tweaked.cc/module/paintutils.html#v:parseImage) uses, nft supports coloured text as well as simple coloured pixels. ### Usage * Load an image from `example.nft` and draw it. Run ᐅ local [nft](https://tweaked.cc/library/cc.image.nft.html "Read and draw nft ("Nitrogen Fingers Text") images.") \= require "cc.image.nft" local image \= assert([nft.load](https://tweaked.cc/library/cc.image.nft.html#v:load "Load an nft image from a file.") ("data/example.nft")) [nft.draw](https://tweaked.cc/library/cc.image.nft.html#v:draw "Draw an nft image to the screen.") (image, [term.getCursorPos](https://tweaked.cc/module/term.html#v:getCursorPos "Get the position of the cursor.") ()) ### Changes * **New in version 1.90.0** | | | | --- | --- | | [parse(image)](https://tweaked.cc/library/cc.image.nft.html#v:parse) | Parse an nft image from a string. | | [load(path)](https://tweaked.cc/library/cc.image.nft.html#v:load) | Load an nft image from a file. | | [draw(image, xPos, yPos \[, target\])](https://tweaked.cc/library/cc.image.nft.html#v:draw) | Draw an nft image to the screen. | [](https://tweaked.cc/library/cc.image.nft.html#v:parse) parse(image)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/image/nft.lua#L25) Parse an nft image from a string. ### Parameters 1. image [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The image contents. ### Returns 1. table The parsed image. [](https://tweaked.cc/library/cc.image.nft.html#v:load) load(path)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/image/nft.lua#L78) Load an nft image from a file. ### Parameters 1. path [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The file to load. ### Returns 1. [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The parsed image. #### Or 1. nil If the file does not exist or could not be loaded. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) An error message explaining why the file could not be loaded. [](https://tweaked.cc/library/cc.image.nft.html#v:draw) draw(image, xPos, yPos \[, target\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/image/nft.lua#L95) Draw an nft image to the screen. ### Parameters 1. image [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) An image, as returned from [`load`](https://tweaked.cc/library/cc.image.nft.html#v:load) or [`parse`](https://tweaked.cc/library/cc.image.nft.html#v:parse) . 2. xPos `number` The x position to start drawing at. 3. yPos `number` The y position to start drawing at. 4. target? [`term.Redirect`](https://tweaked.cc/module/term.html#ty:Redirect) The terminal redirect to draw to. Defaults to the current terminal. --- # cc.pretty cc.pretty ========= A pretty printer for rendering data structures in an aesthetically pleasing manner. In order to display something using [`cc.pretty`](https://tweaked.cc/library/cc.pretty.html) , you build up a series of [documents](https://tweaked.cc/library/cc.pretty.html#ty:Doc) . These behave a little bit like strings; you can concatenate them together and then print them to the screen. However, documents also allow you to control how they should be printed. There are several functions (such as [`nest`](https://tweaked.cc/library/cc.pretty.html#v:nest) and [`group`](https://tweaked.cc/library/cc.pretty.html#v:group) ) which allow you to control the "layout" of the document. When you come to display the document, the 'best' (most compact) layout is used. The structure of this module is based on [A Prettier Printer](https://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf "A Prettier Printer") . ### Usage * Print a table to the terminal Run ᐅ local [pretty](https://tweaked.cc/library/cc.pretty.html "A pretty printer for rendering data structures in an aesthetically pleasing manner.") \= require "cc.pretty" [pretty.pretty\_print](https://tweaked.cc/library/cc.pretty.html#v:pretty_print "A shortcut for calling pretty and print together.") ({ 1, 2, 3 }) * Build a custom document and display it Run ᐅ local [pretty](https://tweaked.cc/library/cc.pretty.html "A pretty printer for rendering data structures in an aesthetically pleasing manner.") \= require "cc.pretty" [pretty.print](https://tweaked.cc/library/cc.pretty.html#v:print "Display a document on the terminal with a trailing new line.") ([pretty.group](https://tweaked.cc/library/cc.pretty.html#v:group "Builds a document which is displayed on a single line if there is enough room, or as normal if not.") ([pretty.text](https://tweaked.cc/library/cc.pretty.html#v:text "Create a new document from a string.") ("hello") .. [pretty.space\_line](https://tweaked.cc/library/cc.pretty.html#v:space_line "A line break.") .. [pretty.text](https://tweaked.cc/library/cc.pretty.html#v:text "Create a new document from a string.") ("world"))) ### Changes * **New in version 1.87.0** | | | | --- | --- | | [empty](https://tweaked.cc/library/cc.pretty.html#v:empty) | An empty document. | | [space](https://tweaked.cc/library/cc.pretty.html#v:space) | A document with a single space in it. | | [line](https://tweaked.cc/library/cc.pretty.html#v:line) | A line break. | | [space\_line](https://tweaked.cc/library/cc.pretty.html#v:space_line) | A line break. | | [text(text \[, colour\])](https://tweaked.cc/library/cc.pretty.html#v:text) | Create a new document from a string. | | [concat(...)](https://tweaked.cc/library/cc.pretty.html#v:concat) | Concatenate several documents together. | | [nest(depth, doc)](https://tweaked.cc/library/cc.pretty.html#v:nest) | Indent later lines of the given document with the given number of spaces. | | [group(doc)](https://tweaked.cc/library/cc.pretty.html#v:group) | Builds a document which is displayed on a single line if there is enough room, or as normal if not. | | [write(doc \[, ribbon\_frac=0.6\])](https://tweaked.cc/library/cc.pretty.html#v:write) | Display a document on the terminal. | | [print(doc \[, ribbon\_frac=0.6\])](https://tweaked.cc/library/cc.pretty.html#v:print) | Display a document on the terminal with a trailing new line. | | [render(doc \[, width \[, ribbon\_frac=0.6\]\])](https://tweaked.cc/library/cc.pretty.html#v:render) | Render a document, converting it into a string. | | [pretty(obj \[, options\])](https://tweaked.cc/library/cc.pretty.html#v:pretty) | Pretty-print an arbitrary object, converting it into a document. | | [pretty\_print(obj \[, options \[, ribbon\_frac=0.6\]\])](https://tweaked.cc/library/cc.pretty.html#v:pretty_print) | A shortcut for calling [`pretty`](https://tweaked.cc/library/cc.pretty.html#v:pretty)
and [`print`](https://tweaked.cc/library/cc.pretty.html#v:print)
together. | [](https://tweaked.cc/library/cc.pretty.html#v:empty) empty[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua#L57) An empty document. [](https://tweaked.cc/library/cc.pretty.html#v:space) space[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua#L60) A document with a single space in it. [](https://tweaked.cc/library/cc.pretty.html#v:line) line[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua#L63) A line break. When collapsed with [`group`](https://tweaked.cc/library/cc.pretty.html#v:group) , this will be replaced with [`empty`](https://tweaked.cc/library/cc.pretty.html#v:empty) . [](https://tweaked.cc/library/cc.pretty.html#v:space_line) space\_line[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua#L66) A line break. When collapsed with [`group`](https://tweaked.cc/library/cc.pretty.html#v:group) , this will be replaced with [`space`](https://tweaked.cc/library/cc.pretty.html#v:space) . [](https://tweaked.cc/library/cc.pretty.html#v:text) text(text \[, colour\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua#L87) Create a new document from a string. If your string contains multiple lines, [`group`](https://tweaked.cc/library/cc.pretty.html#v:group) will flatten the string into a single line, with spaces between each line. ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The string to construct a new document with. 2. colour? `number` The colour this text should be printed with. If not given, we default to the current colour. ### Returns 1. [`Doc`](https://tweaked.cc/library/cc.pretty.html#ty:Doc) The document with the provided text. ### Usage * Write some blue text. Run ᐅ local [pretty](https://tweaked.cc/library/cc.pretty.html "A pretty printer for rendering data structures in an aesthetically pleasing manner.") \= require "cc.pretty" [pretty.print](https://tweaked.cc/library/cc.pretty.html#v:print "Display a document on the terminal with a trailing new line.") ([pretty.text](https://tweaked.cc/library/cc.pretty.html#v:text "Create a new document from a string.") ("Hello!", [colours](https://tweaked.cc/module/colours.html "An alternative version of colors for lovers of British spelling.") .blue)) [](https://tweaked.cc/library/cc.pretty.html#v:concat) concat(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua#L126) Concatenate several documents together. This behaves very similar to string concatenation. ### Parameters 1. ... [`Doc`](https://tweaked.cc/library/cc.pretty.html#ty:Doc) | [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The documents to concatenate. ### Returns 1. [`Doc`](https://tweaked.cc/library/cc.pretty.html#ty:Doc) The concatenated documents. ### Usage * Run ᐅ local [pretty](https://tweaked.cc/library/cc.pretty.html "A pretty printer for rendering data structures in an aesthetically pleasing manner.") \= require "cc.pretty" local doc1, doc2 \= [pretty.text](https://tweaked.cc/library/cc.pretty.html#v:text "Create a new document from a string.") ("doc1"), [pretty.text](https://tweaked.cc/library/cc.pretty.html#v:text "Create a new document from a string.") ("doc2") print([pretty.concat](https://tweaked.cc/library/cc.pretty.html#v:concat "Concatenate several documents together.") (doc1, " - ", doc2)) print(doc1 .. " - " .. doc2) \-- Also supports .. [](https://tweaked.cc/library/cc.pretty.html#v:nest) nest(depth, doc)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua#L161) Indent later lines of the given document with the given number of spaces. For instance, nesting the document foo bar by two spaces will produce foo bar ### Parameters 1. depth `number` The number of spaces with which the document should be indented. 2. doc [`Doc`](https://tweaked.cc/library/cc.pretty.html#ty:Doc) The document to indent. ### Returns 1. [`Doc`](https://tweaked.cc/library/cc.pretty.html#ty:Doc) The nested document. ### Usage * Run ᐅ local [pretty](https://tweaked.cc/library/cc.pretty.html "A pretty printer for rendering data structures in an aesthetically pleasing manner.") \= require "cc.pretty" print([pretty.nest](https://tweaked.cc/library/cc.pretty.html#v:nest "Indent later lines of the given document with the given number of spaces.") (2, [pretty.text](https://tweaked.cc/library/cc.pretty.html#v:text "Create a new document from a string.") ("foo\\nbar"))) [](https://tweaked.cc/library/cc.pretty.html#v:group) group(doc)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua#L200) Builds a document which is displayed on a single line if there is enough room, or as normal if not. ### Parameters 1. doc [`Doc`](https://tweaked.cc/library/cc.pretty.html#ty:Doc) The document to group. ### Returns 1. [`Doc`](https://tweaked.cc/library/cc.pretty.html#ty:Doc) The grouped document. ### Usage * Uses group to show things being displayed on one or multiple lines. Run ᐅ local [pretty](https://tweaked.cc/library/cc.pretty.html "A pretty printer for rendering data structures in an aesthetically pleasing manner.") \= require "cc.pretty" local doc \= [pretty.group](https://tweaked.cc/library/cc.pretty.html#v:group "Builds a document which is displayed on a single line if there is enough room, or as normal if not.") ("Hello" .. [pretty.space\_line](https://tweaked.cc/library/cc.pretty.html#v:space_line "A line break.") .. "World") print([pretty.render](https://tweaked.cc/library/cc.pretty.html#v:render "Render a document, converting it into a string.") (doc, 5)) \-- On multiple lines print([pretty.render](https://tweaked.cc/library/cc.pretty.html#v:render "Render a document, converting it into a string.") (doc, 20)) \-- Collapsed onto one. [](https://tweaked.cc/library/cc.pretty.html#v:write) write(doc \[, ribbon\_frac=0.6\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua#L233) Display a document on the terminal. ### Parameters 1. doc [`Doc`](https://tweaked.cc/library/cc.pretty.html#ty:Doc) The document to render 2. ribbon\_frac? `number` = The maximum fraction of the width that we should write in. [](https://tweaked.cc/library/cc.pretty.html#v:print) print(doc \[, ribbon\_frac=0.6\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua#L295) Display a document on the terminal with a trailing new line. ### Parameters 1. doc [`Doc`](https://tweaked.cc/library/cc.pretty.html#ty:Doc) The document to render. 2. ribbon\_frac? `number` = The maximum fraction of the width that we should write in. [](https://tweaked.cc/library/cc.pretty.html#v:render) render(doc \[, width \[, ribbon\_frac=0.6\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua#L309) Render a document, converting it into a string. ### Parameters 1. doc [`Doc`](https://tweaked.cc/library/cc.pretty.html#ty:Doc) The document to render. 2. width? `number` The maximum width of this document. Note that long strings will not be wrapped to fit this width - it is only used for finding the best layout. 3. ribbon\_frac? `number` = The maximum fraction of the width that we should write in. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The rendered document as a string. [](https://tweaked.cc/library/cc.pretty.html#v:pretty) pretty(obj \[, options\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua#L471) Pretty-print an arbitrary object, converting it into a document. This can then be rendered with [`write`](https://tweaked.cc/library/cc.pretty.html#v:write) or [`print`](https://tweaked.cc/library/cc.pretty.html#v:print) . ### Parameters 1. obj The object to pretty-print. 2. options? { function\_args = `boolean`, function\_source = `boolean` } Controls how various properties are displayed. * `function_args`: Show the arguments to a function if known (`false` by default). * `function_source`: Show where the function was defined, instead of `function: xxxxxxxx` (`false` by default). ### Returns 1. [`Doc`](https://tweaked.cc/library/cc.pretty.html#ty:Doc) The object formatted as a document. ### Usage * Display a table on the screen Run ᐅ local [pretty](https://tweaked.cc/library/cc.pretty.html "A pretty printer for rendering data structures in an aesthetically pleasing manner.") \= require "cc.pretty" [pretty.print](https://tweaked.cc/library/cc.pretty.html#v:print "Display a document on the terminal with a trailing new line.") ([pretty.pretty](https://tweaked.cc/library/cc.pretty.html#v:pretty "Pretty-print an arbitrary object, converting it into a document.") ({ 1, 2, 3 })) ### See also * **[`pretty_print`](https://tweaked.cc/library/cc.pretty.html#v:pretty_print) ** for a shorthand to prettify and print an object. ### Changes * **Changed in version 1.88.0:** Added `options` argument. [](https://tweaked.cc/library/cc.pretty.html#v:pretty_print) pretty\_print(obj \[, options \[, ribbon\_frac=0.6\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua#L501) A shortcut for calling [`pretty`](https://tweaked.cc/library/cc.pretty.html#v:pretty) and [`print`](https://tweaked.cc/library/cc.pretty.html#v:print) together. ### Parameters 1. obj The object to pretty-print. 2. options? { function\_args = `boolean`, function\_source = `boolean` } Controls how various properties are displayed. * `function_args`: Show the arguments to a function if known (`false` by default). * `function_source`: Show where the function was defined, instead of `function: xxxxxxxx` (`false` by default). 3. ribbon\_frac? `number` = The maximum fraction of the width that we should write in. ### Usage * Display a table on the screen. Run ᐅ local [pretty](https://tweaked.cc/library/cc.pretty.html "A pretty printer for rendering data structures in an aesthetically pleasing manner.") \= require "cc.pretty" [pretty.pretty\_print](https://tweaked.cc/library/cc.pretty.html#v:pretty_print "A shortcut for calling pretty and print together.") ({ 1, 2, 3 }) ### See also * **[`pretty`](https://tweaked.cc/library/cc.pretty.html#v:pretty) ** * **[`print`](https://tweaked.cc/library/cc.pretty.html#v:print) ** ### Changes * **New in version 1.99** ### Types ### [](https://tweaked.cc/library/cc.pretty.html#ty:Doc) Doc A document containing formatted text, with multiple possible layouts. Documents effectively represent a sequence of strings in alternative layouts, which we will try to print in the most compact form necessary. --- # cc.require cc.require ========== A pure Lua implementation of the builtin [`require`](https://www.lua.org/manual/5.1/manual.html#pdf-require) function and [`package`](https://www.lua.org/manual/5.1/manual.html#5.3) library. Generally you do not need to use this module - it is injected into the every program's environment. However, it may be useful when building a custom shell or when running programs yourself. ### Usage * Construct the package and require function, and insert them into a custom environment. Run ᐅ local [r](https://tweaked.cc/library/cc.require.html "A pure Lua implementation of the builtin require function and package library.") \= require "cc.require" local env \= setmetatable({}, { \_\_index \= \_ENV }) env.require, env.package \= [r.make](https://tweaked.cc/library/cc.require.html#v:make "Build an implementation of Lua's package library, and a require function to load modules within it.") (env, "/") \-- Now we have our own require function, separate to the original. local r2 \= env.require "cc.require" print([r](https://tweaked.cc/library/cc.require.html "A pure Lua implementation of the builtin require function and package library.") , r2) ### See also * **[`Reusing code with require`](https://tweaked.cc/guide/using_require.html) ** For an introduction on how to use [`require`](https://www.lua.org/manual/5.1/manual.html#pdf-require) . ### Changes * **New in version 1.88.0** | | | | --- | --- | | [make(env, dir)](https://tweaked.cc/library/cc.require.html#v:make) | Build an implementation of Lua's [`package`](https://www.lua.org/manual/5.1/manual.html#5.3)
library, and a [`require`](https://www.lua.org/manual/5.1/manual.html#pdf-require)
function to load modules within it. | [](https://tweaked.cc/library/cc.require.html#v:make) make(env, dir)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/require.lua#L120) Build an implementation of Lua's [`package`](https://www.lua.org/manual/5.1/manual.html#5.3) library, and a [`require`](https://www.lua.org/manual/5.1/manual.html#pdf-require) function to load modules within it. ### Parameters 1. env [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The environment to load packages into. 2. dir [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The directory that relative packages are loaded from. ### Returns 1. `function` The new [`require`](https://www.lua.org/manual/5.1/manual.html#pdf-require) function. 2. [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The new [`package`](https://www.lua.org/manual/5.1/manual.html#5.3) library. --- # cc.shell.completion cc.shell.completion =================== A collection of helper methods for working with shell completion. Most programs may be completed using the [`build`](https://tweaked.cc/library/cc.shell.completion.html#v:build) helper method, rather than manually switching on the argument index. Note, the helper functions within this module do not accept an argument index, and so are not directly usable with the [`shell.setCompletionFunction`](https://tweaked.cc/module/shell.html#v:setCompletionFunction) . Instead, wrap them using [`build`](https://tweaked.cc/library/cc.shell.completion.html#v:build) , or your own custom function. ### Usage * Register a completion handler for example.lua which prompts for a choice of options, followed by a directory, and then multiple files. Run ᐅ local [completion](https://tweaked.cc/library/cc.shell.completion.html "A collection of helper methods for working with shell completion.") \= require "cc.shell.completion" local complete \= [completion.build](https://tweaked.cc/library/cc.shell.completion.html#v:build "A helper function for building shell completion arguments.") ( { [completion.choice](https://tweaked.cc/library/cc.shell.completion.html#v:choice "Wraps cc.completion.choice as a build compatible function.") , { "get", "put" } }, [completion.dir](https://tweaked.cc/library/cc.shell.completion.html#v:dir "Complete the name of a directory relative to the current working directory.") , { [completion.file](https://tweaked.cc/library/cc.shell.completion.html#v:file "Complete the name of a file relative to the current working directory.") , many \= true } ) [shell.setCompletionFunction](https://tweaked.cc/module/shell.html#v:setCompletionFunction "Set the completion function for a program.") ("example.lua", complete) read(nil, nil, [shell.complete](https://tweaked.cc/module/shell.html#v:complete "Complete a shell command line.") , "example ") ### See also * **[`cc.completion`](https://tweaked.cc/library/cc.completion.html) ** For more general helpers, suitable for use with [`_G.read`](https://tweaked.cc/module/_G.html#v:read) . * **[`shell.setCompletionFunction`](https://tweaked.cc/module/shell.html#v:setCompletionFunction) ** ### Changes * **New in version 1.85.0** | | | | --- | --- | | [file(shell, text)](https://tweaked.cc/library/cc.shell.completion.html#v:file) | Complete the name of a file relative to the current working directory. | | [dir(shell, text)](https://tweaked.cc/library/cc.shell.completion.html#v:dir) | Complete the name of a directory relative to the current working directory. | | [dirOrFile(shell, text, previous \[, add\_space\])](https://tweaked.cc/library/cc.shell.completion.html#v:dirOrFile) | Complete the name of a file or directory relative to the current working directory. | | [program(shell, text)](https://tweaked.cc/library/cc.shell.completion.html#v:program) | Complete the name of a program. | | [programWithArgs(shell, text, previous, starting)](https://tweaked.cc/library/cc.shell.completion.html#v:programWithArgs) | Complete arguments of a program. | | [help](https://tweaked.cc/library/cc.shell.completion.html#v:help) | Wraps [`help.completeTopic`](https://tweaked.cc/module/help.html#v:completeTopic)
as a [`build`](https://tweaked.cc/library/cc.shell.completion.html#v:build)
compatible function. | | [choice](https://tweaked.cc/library/cc.shell.completion.html#v:choice) | Wraps [`cc.completion.choice`](https://tweaked.cc/library/cc.completion.html#v:choice)
as a [`build`](https://tweaked.cc/library/cc.shell.completion.html#v:build)
compatible function. | | [peripheral](https://tweaked.cc/library/cc.shell.completion.html#v:peripheral) | Wraps [`cc.completion.peripheral`](https://tweaked.cc/library/cc.completion.html#v:peripheral)
as a [`build`](https://tweaked.cc/library/cc.shell.completion.html#v:build)
compatible function. | | [side](https://tweaked.cc/library/cc.shell.completion.html#v:side) | Wraps [`cc.completion.side`](https://tweaked.cc/library/cc.completion.html#v:side)
as a [`build`](https://tweaked.cc/library/cc.shell.completion.html#v:build)
compatible function. | | [setting](https://tweaked.cc/library/cc.shell.completion.html#v:setting) | Wraps [`cc.completion.setting`](https://tweaked.cc/library/cc.completion.html#v:setting)
as a [`build`](https://tweaked.cc/library/cc.shell.completion.html#v:build)
compatible function. | | [command](https://tweaked.cc/library/cc.shell.completion.html#v:command) | Wraps [`cc.completion.command`](https://tweaked.cc/library/cc.completion.html#v:command)
as a [`build`](https://tweaked.cc/library/cc.shell.completion.html#v:build)
compatible function. | | [build(...)](https://tweaked.cc/library/cc.shell.completion.html#v:build) | A helper function for building shell completion arguments. | [](https://tweaked.cc/library/cc.shell.completion.html#v:file) file(shell, text)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua#L40) Complete the name of a file relative to the current working directory. ### Parameters 1. shell [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The shell we're completing in. 2. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Current text to complete. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } A list of suffixes of matching files. [](https://tweaked.cc/library/cc.shell.completion.html#v:dir) dir(shell, text)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua#L53) Complete the name of a directory relative to the current working directory. ### Parameters 1. shell [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The shell we're completing in. 2. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Current text to complete. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } A list of suffixes of matching directories. [](https://tweaked.cc/library/cc.shell.completion.html#v:dirOrFile) dirOrFile(shell, text, previous \[, add\_space\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua#L69) Complete the name of a file or directory relative to the current working directory. ### Parameters 1. shell [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The shell we're completing in. 2. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Current text to complete. 3. previous { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } The shell arguments before this one. 4. add\_space? `boolean` Whether to add a space after the completed item. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } A list of suffixes of matching files and directories. [](https://tweaked.cc/library/cc.shell.completion.html#v:program) program(shell, text)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua#L98) Complete the name of a program. ### Parameters 1. shell [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The shell we're completing in. 2. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Current text to complete. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } A list of suffixes of matching programs. ### See also * **[`shell.completeProgram`](https://tweaked.cc/module/shell.html#v:completeProgram) ** [](https://tweaked.cc/library/cc.shell.completion.html#v:programWithArgs) programWithArgs(shell, text, previous, starting)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua#L110) Complete arguments of a program. ### Parameters 1. shell [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) The shell we're completing in. 2. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) Current text to complete. 3. previous { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } The shell arguments before this one. 4. starting `number` Which argument index this program and args start at. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } A list of suffixes of matching programs or arguments. ### Changes * **New in version 1.97.0** [](https://tweaked.cc/library/cc.shell.completion.html#v:help) help[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua#L200) Wraps [`help.completeTopic`](https://tweaked.cc/module/help.html#v:completeTopic) as a [`build`](https://tweaked.cc/library/cc.shell.completion.html#v:build) compatible function. [](https://tweaked.cc/library/cc.shell.completion.html#v:choice) choice[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua#L201) Wraps [`cc.completion.choice`](https://tweaked.cc/library/cc.completion.html#v:choice) as a [`build`](https://tweaked.cc/library/cc.shell.completion.html#v:build) compatible function. [](https://tweaked.cc/library/cc.shell.completion.html#v:peripheral) peripheral[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua#L202) Wraps [`cc.completion.peripheral`](https://tweaked.cc/library/cc.completion.html#v:peripheral) as a [`build`](https://tweaked.cc/library/cc.shell.completion.html#v:build) compatible function. [](https://tweaked.cc/library/cc.shell.completion.html#v:side) side[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua#L203) Wraps [`cc.completion.side`](https://tweaked.cc/library/cc.completion.html#v:side) as a [`build`](https://tweaked.cc/library/cc.shell.completion.html#v:build) compatible function. [](https://tweaked.cc/library/cc.shell.completion.html#v:setting) setting[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua#L204) Wraps [`cc.completion.setting`](https://tweaked.cc/library/cc.completion.html#v:setting) as a [`build`](https://tweaked.cc/library/cc.shell.completion.html#v:build) compatible function. [](https://tweaked.cc/library/cc.shell.completion.html#v:command) command[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua#L205) Wraps [`cc.completion.command`](https://tweaked.cc/library/cc.completion.html#v:command) as a [`build`](https://tweaked.cc/library/cc.shell.completion.html#v:build) compatible function. [](https://tweaked.cc/library/cc.shell.completion.html#v:build) build(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua#L158) A helper function for building shell completion arguments. This accepts a series of single-argument completion functions, and combines them into a function suitable for use with [`shell.setCompletionFunction`](https://tweaked.cc/module/shell.html#v:setCompletionFunction) . ### Parameters 1. ... nil | [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) | `function` Every argument to [`build`](https://tweaked.cc/library/cc.shell.completion.html#v:build) represents an argument to the program you wish to complete. Each argument can be one of three types: * `nil`: This argument will not be completed. * A function: This argument will be completed with the given function. It is called with the [`shell`](https://tweaked.cc/module/shell.html) object, the string to complete and the arguments before this one. * A table: This acts as a more powerful version of the function case. The table must have a function as the first item - this will be called with the shell, string and preceding arguments as above, but also followed by any additional items in the table. This provides a more convenient interface to pass options to your completion functions. If this table is the last argument, it may also set the `many` key to true, which states this function should be used to complete any remaining arguments. --- # command command ======= This peripheral allows you to interact with command blocks. Command blocks are only wrapped as peripherals if the `enable_command_block` option is true within the config. This API is _not_ the same as the [`commands`](https://tweaked.cc/module/commands.html) API, which is exposed on command computers. | | | | --- | --- | | [getCommand()](https://tweaked.cc/peripheral/command.html#v:getCommand) | Get the command this command block will run. | | [setCommand(command)](https://tweaked.cc/peripheral/command.html#v:setCommand) | Set the command block's command. | | [runCommand()](https://tweaked.cc/peripheral/command.html#v:runCommand) | Execute the command block once. | [](https://tweaked.cc/peripheral/command.html#v:getCommand) getCommand()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/commandblock/CommandBlockPeripheral.java#L40) Get the command this command block will run. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The current command. [](https://tweaked.cc/peripheral/command.html#v:setCommand) setCommand(command)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/commandblock/CommandBlockPeripheral.java#L50) Set the command block's command. ### Parameters 1. command [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The new command. [](https://tweaked.cc/peripheral/command.html#v:runCommand) runCommand()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/commandblock/CommandBlockPeripheral.java#L63) Execute the command block once. ### Returns 1. `boolean` If the command completed successfully. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil A failure message. --- # computer computer ======== A computer or turtle wrapped as a peripheral. This allows for basic interaction with adjacent computers. Computers wrapped as peripherals will have the type `computer` while turtles will be `turtle`. | | | | --- | --- | | [turnOn()](https://tweaked.cc/peripheral/computer.html#v:turnOn) | Turn the other computer on. | | [shutdown()](https://tweaked.cc/peripheral/computer.html#v:shutdown) | Shutdown the other computer. | | [reboot()](https://tweaked.cc/peripheral/computer.html#v:reboot) | Reboot or turn on the other computer. | | [getID()](https://tweaked.cc/peripheral/computer.html#v:getID) | Get the other computer's ID. | | [isOn()](https://tweaked.cc/peripheral/computer.html#v:isOn) | Determine if the other computer is on. | | [getLabel()](https://tweaked.cc/peripheral/computer.html#v:getLabel) | Get the other computer's label. | [](https://tweaked.cc/peripheral/computer.html#v:turnOn) turnOn()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/computer/blocks/ComputerPeripheral.java#L37) Turn the other computer on. [](https://tweaked.cc/peripheral/computer.html#v:shutdown) shutdown()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/computer/blocks/ComputerPeripheral.java#L50) Shutdown the other computer. [](https://tweaked.cc/peripheral/computer.html#v:reboot) reboot()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/computer/blocks/ComputerPeripheral.java#L63) Reboot or turn on the other computer. [](https://tweaked.cc/peripheral/computer.html#v:getID) getID()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/computer/blocks/ComputerPeripheral.java#L79) Get the other computer's ID. ### Returns 1. `number` The computer's ID. ### See also * **[`os.getComputerID`](https://tweaked.cc/module/os.html#v:getComputerID) ** To get your computer's ID. [](https://tweaked.cc/peripheral/computer.html#v:isOn) isOn()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/computer/blocks/ComputerPeripheral.java#L90) Determine if the other computer is on. ### Returns 1. `boolean` If the computer is on. [](https://tweaked.cc/peripheral/computer.html#v:getLabel) getLabel()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/computer/blocks/ComputerPeripheral.java#L102) Get the other computer's label. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The computer's label. ### See also * **[`os.getComputerLabel`](https://tweaked.cc/module/os.html#v:getComputerLabel) ** To get your label. --- # cc.strings cc.strings ========== Various utilities for working with strings and text. ### See also * **[`textutils`](https://tweaked.cc/module/textutils.html) ** For additional string related utilities. ### Changes * **New in version 1.95.0** | | | | --- | --- | | [wrap(text \[, width\])](https://tweaked.cc/library/cc.strings.html#v:wrap) | Wraps a block of text, so that each line fits within the given width. | | [ensure\_width(line \[, width\])](https://tweaked.cc/library/cc.strings.html#v:ensure_width) | Makes the input string a fixed width. | | [split(str, deliminator \[, plain=false \[, limit\]\])](https://tweaked.cc/library/cc.strings.html#v:split) | Split a string into parts, each separated by a deliminator. | [](https://tweaked.cc/library/cc.strings.html#v:wrap) wrap(text \[, width\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/strings.lua#L32) Wraps a block of text, so that each line fits within the given width. This may be useful if you want to wrap text before displaying it to a [`monitor`](https://tweaked.cc/peripheral/monitor.html) or [`printer`](https://tweaked.cc/peripheral/printer.html) without using [print](https://tweaked.cc/module/_G.html#v:print) . ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The string to wrap. 2. width? `number` The width to constrain to, defaults to the width of the terminal. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } The wrapped input string as a list of lines. ### Usage * Wrap a string and write it to the terminal. Run ᐅ [term.clear](https://tweaked.cc/module/term.html#v:clear "Clears the terminal, filling it with the current background colour.") () local lines \= [require "cc.strings".wrap](https://tweaked.cc/library/cc.strings.html#v:wrap "Wraps a block of text, so that each line fits within the given width.") ("This is a long piece of text", 10) for i \= 1, #lines do [term.setCursorPos](https://tweaked.cc/module/term.html#v:setCursorPos "Set the position of the cursor.") (1, i) [term.write](https://tweaked.cc/module/term.html#v:write "Write text at the current cursor position, moving the cursor to the end of the text.") (lines\[i\]) end [](https://tweaked.cc/library/cc.strings.html#v:ensure_width) ensure\_width(line \[, width\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/strings.lua#L100) Makes the input string a fixed width. This either truncates it, or pads it with spaces. ### Parameters 1. line [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The string to normalise. 2. width? `number` The width to constrain to, defaults to the width of the terminal. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The string with a specific width. ### Usage * Run ᐅ [require "cc.strings".ensure\_width](https://tweaked.cc/library/cc.strings.html#v:ensure_width "Makes the input string a fixed width.") ("a short string", 20) * Run ᐅ [require "cc.strings".ensure\_width](https://tweaked.cc/library/cc.strings.html#v:ensure_width "Makes the input string a fixed width.") ("a rather long string which is truncated", 20) [](https://tweaked.cc/library/cc.strings.html#v:split) split(str, deliminator \[, plain=false \[, limit\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/strings.lua#L142) Split a string into parts, each separated by a deliminator. For instance, splitting the string `"a b c"` with the deliminator `" "`, would return a table with three strings: `"a"`, `"b"`, and `"c"`. By default, the deliminator is given as a [Lua pattern](https://www.lua.org/manual/5.3/manual.html#6.4.1) . Passing `true` to the `plain` argument will cause the deliminator to be treated as a litteral string. ### Parameters 1. str [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The string to split. 2. deliminator [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The pattern to split this string on. 3. plain? `boolean` = Treat the deliminator as a plain string, rather than a pattern. 4. limit? `number` The maximum number of elements in the returned list. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } The list of split strings. ### Usage * Split a string into words. Run ᐅ [require "cc.strings".split](https://tweaked.cc/library/cc.strings.html#v:split "Split a string into parts, each separated by a deliminator.") ("This is a sentence.", "%s+") * Split a string by "-" into at most 3 elements. Run ᐅ [require "cc.strings".split](https://tweaked.cc/library/cc.strings.html#v:split "Split a string into parts, each separated by a deliminator.") ("a-separated-string-of-sorts", "-", true, 3) ### See also * **[`table.concat`](https://www.lua.org/manual/5.1/manual.html#pdf-table.concat) ** To join strings together. ### Changes * **New in version 1.112.0** --- # drive drive ===== Disk drives are a peripheral which allow you to read and write to floppy disks and other "mountable media" (such as computers or turtles). They also allow you to [play records](https://tweaked.cc/peripheral/drive.html#v:playAudio) . When a disk drive attaches some mount (such as a floppy disk or computer), it attaches a folder called `disk`, `disk2`, etc... to the root directory of the computer. This folder can be used to interact with the files on that disk. When a disk is inserted, a `disk` event is fired, with the side peripheral is on. Likewise, when the disk is detached, a `disk_eject` event is fired. Recipe ------ **Disk Drive** ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Redstone Dust](https://tweaked.cc/images/items/minecraft/redstone.png "Redstone Dust") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Redstone Dust](https://tweaked.cc/images/items/minecraft/redstone.png "Redstone Dust") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Disk Drive](https://tweaked.cc/images/items/computercraft/disk_drive.png "Disk Drive") | | | | --- | --- | | [isDiskPresent()](https://tweaked.cc/peripheral/drive.html#v:isDiskPresent) | Returns whether a disk is currently inserted in the drive. | | [getDiskLabel()](https://tweaked.cc/peripheral/drive.html#v:getDiskLabel) | Returns the label of the disk in the drive if available. | | [setDiskLabel(\[label\])](https://tweaked.cc/peripheral/drive.html#v:setDiskLabel) | Sets or clears the label for a disk. | | [hasData()](https://tweaked.cc/peripheral/drive.html#v:hasData) | Returns whether a disk with data is inserted. | | [getMountPath()](https://tweaked.cc/peripheral/drive.html#v:getMountPath) | Returns the mount path for the inserted disk. | | [hasAudio()](https://tweaked.cc/peripheral/drive.html#v:hasAudio) | Returns whether a disk with audio is inserted. | | [getAudioTitle()](https://tweaked.cc/peripheral/drive.html#v:getAudioTitle) | Returns the title of the inserted audio disk. | | [playAudio()](https://tweaked.cc/peripheral/drive.html#v:playAudio) | Plays the audio in the inserted disk, if available. | | [stopAudio()](https://tweaked.cc/peripheral/drive.html#v:stopAudio) | Stops any audio that may be playing. | | [ejectDisk()](https://tweaked.cc/peripheral/drive.html#v:ejectDisk) | Ejects any disk that may be in the drive. | | [getDiskID()](https://tweaked.cc/peripheral/drive.html#v:getDiskID) | Returns the ID of the disk inserted in the drive. | [](https://tweaked.cc/peripheral/drive.html#v:isDiskPresent) isDiskPresent()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java#L52) Returns whether a disk is currently inserted in the drive. ### Returns 1. `boolean` Whether a disk is currently inserted in the drive. [](https://tweaked.cc/peripheral/drive.html#v:getDiskLabel) getDiskLabel()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java#L63) Returns the label of the disk in the drive if available. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The label of the disk, or `nil` if either no disk is inserted or the disk doesn't have a label. [](https://tweaked.cc/peripheral/drive.html#v:setDiskLabel) setDiskLabel(\[label\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java#L80) Sets or clears the label for a disk. If no label or `nil` is passed, the label will be cleared. If the inserted disk's label can't be changed (for example, a record), an error will be thrown. ### Parameters 1. label? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The new label of the disk, or `nil` to clear. ### Throws * If the disk's label can't be changed. [](https://tweaked.cc/peripheral/drive.html#v:hasData) hasData()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java#L95) Returns whether a disk with data is inserted. ### Returns 1. `boolean` Whether a disk with data is inserted. [](https://tweaked.cc/peripheral/drive.html#v:getMountPath) getMountPath()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java#L106) Returns the mount path for the inserted disk. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The mount path for the disk, or `nil` if no data disk is inserted. [](https://tweaked.cc/peripheral/drive.html#v:hasAudio) hasAudio()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java#L117) Returns whether a disk with audio is inserted. ### Returns 1. `boolean` Whether a disk with audio is inserted. [](https://tweaked.cc/peripheral/drive.html#v:getAudioTitle) getAudioTitle()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java#L128) Returns the title of the inserted audio disk. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil | false The title of the audio, `false` if no disk is inserted, or `nil` if the disk has no audio. [](https://tweaked.cc/peripheral/drive.html#v:playAudio) playAudio()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java#L138) Plays the audio in the inserted disk, if available. [](https://tweaked.cc/peripheral/drive.html#v:stopAudio) stopAudio()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java#L148) Stops any audio that may be playing. ### See also * **[`playAudio`](https://tweaked.cc/peripheral/drive.html#v:playAudio) ** [](https://tweaked.cc/peripheral/drive.html#v:ejectDisk) ejectDisk()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java#L156) Ejects any disk that may be in the drive. [](https://tweaked.cc/peripheral/drive.html#v:getDiskID) getDiskID()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java#L168) Returns the ID of the disk inserted in the drive. ### Returns 1. `number` | nil The ID of the disk in the drive, or `nil` if no disk with an ID is inserted. ### Changes * **New in version 1.4** --- # modem modem ===== Modems allow you to send messages between computers over long distances. ##### tip Modems provide a fairly basic set of methods, which makes them very flexible but often hard to work with. The [`rednet`](https://tweaked.cc/module/rednet.html) API is built on top of modems, and provides a more user-friendly interface. Sending and receiving messages ------------------------------ Modems operate on a series of channels, a bit like frequencies on a radio. Any modem can send a message on a particular channel, but only those which have [opened](https://tweaked.cc/peripheral/modem.html#v:open) the channel and are "listening in" can receive messages. Channels are represented as an integer between 0 and 65535 inclusive. These channels don't have any defined meaning, though some APIs or programs will assign a meaning to them. For instance, the [`gps`](https://tweaked.cc/module/gps.html) module sends all its messages on channel 65534 ([`gps.CHANNEL_GPS`](https://tweaked.cc/module/gps.html#v:CHANNEL_GPS) ), while [`rednet`](https://tweaked.cc/module/rednet.html) uses channels equal to the computer's ID. * Sending messages is done with the [`transmit`](https://tweaked.cc/peripheral/modem.html#v:transmit) message. * Receiving messages is done by listening to the [`modem_message`](https://tweaked.cc/event/modem_message.html) event. Types of modem -------------- CC: Tweaked comes with three kinds of modem, with different capabilities. * **Wireless modems:** Wireless modems can send messages to any other wireless modem. They can be placed next to a computer, or equipped as a pocket computer or turtle upgrade. Wireless modems have a limited range, only sending messages to modems within 64 blocks. This range increases linearly once the modem is above y=96, to a maximum of 384 at world height. * **Ender modems:** These are upgraded versions of normal wireless modems. They do not have a distance limit, and can send messages between dimensions. * **Wired modems:** These send messages to other any other wired modems connected to the same network (using _Networking Cable_). They also can be used to attach additional peripherals to a computer. Recipes ------- **Wireless Modem** ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Ender Pearl](https://tweaked.cc/images/items/minecraft/ender_pearl.png "Ender Pearl") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Wireless Modem](https://tweaked.cc/images/items/computercraft/wireless_modem_normal.png "Wireless Modem") **Ender Modem** ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Eye of Ender](https://tweaked.cc/images/items/minecraft/ender_eye.png "Eye of Ender") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Ender Modem](https://tweaked.cc/images/items/computercraft/wireless_modem_advanced.png "Ender Modem") **Wired Modem** ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Redstone Dust](https://tweaked.cc/images/items/minecraft/redstone.png "Redstone Dust") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Wired Modem](https://tweaked.cc/images/items/computercraft/wired_modem.png "Wired Modem") **Networking Cable** ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Redstone Dust](https://tweaked.cc/images/items/minecraft/redstone.png "Redstone Dust") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Networking Cable](https://tweaked.cc/images/items/computercraft/cable.png "Networking Cable")6 **Wired Modem** ![Wired Modem](https://tweaked.cc/images/items/computercraft/wired_modem.png "Wired Modem") ![Wired Modem](https://tweaked.cc/images/items/computercraft/wired_modem_full.png "Wired Modem") ### Usage * Wrap a modem and a message on channel 15, requesting a response on channel 43. Then wait for a message to arrive on channel 43 and print it. Run ᐅ local modem \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("modem") or error("No modem attached", 0) modem.open(43) \-- Open 43 so we can receive replies \-- Send our message modem.transmit(15, 43, "Hello, world!") \-- And wait for a reply local event, side, channel, replyChannel, message, distance repeat event, side, channel, replyChannel, message, distance \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("modem\_message") until channel \== 43 print("Received a reply: " .. tostring(message)) ### See also * **[`modem_message`](https://tweaked.cc/event/modem_message.html) ** Queued when a modem receives a message on an [open channel](https://tweaked.cc/peripheral/modem.html#v:open) . * **[`rednet`](https://tweaked.cc/module/rednet.html) ** A networking API built on top of the modem peripheral. | | | | --- | --- | | [open(channel)](https://tweaked.cc/peripheral/modem.html#v:open) | Open a channel on a modem. | | [isOpen(channel)](https://tweaked.cc/peripheral/modem.html#v:isOpen) | Check if a channel is open. | | [close(channel)](https://tweaked.cc/peripheral/modem.html#v:close) | Close an open channel, meaning it will no longer receive messages. | | [closeAll()](https://tweaked.cc/peripheral/modem.html#v:closeAll) | Close all open channels. | | [transmit(channel, replyChannel, payload)](https://tweaked.cc/peripheral/modem.html#v:transmit) | Sends a modem message on a certain channel. | | [isWireless()](https://tweaked.cc/peripheral/modem.html#v:isWireless) | Determine if this is a wired or wireless modem. | | [getNamesRemote()](https://tweaked.cc/peripheral/modem.html#v:getNamesRemote) | List all remote peripherals on the wired network. | | [isPresentRemote(name)](https://tweaked.cc/peripheral/modem.html#v:isPresentRemote) | Determine if a peripheral is available on this wired network. | | [getTypeRemote(name)](https://tweaked.cc/peripheral/modem.html#v:getTypeRemote) | Get the type of a peripheral is available on this wired network. | | [hasTypeRemote(name, type)](https://tweaked.cc/peripheral/modem.html#v:hasTypeRemote) | Check a peripheral is of a particular type. | | [getMethodsRemote(name)](https://tweaked.cc/peripheral/modem.html#v:getMethodsRemote) | Get all available methods for the remote peripheral with the given name. | | [callRemote(remoteName, method, ...)](https://tweaked.cc/peripheral/modem.html#v:callRemote) | Call a method on a peripheral on this wired network. | | [getNameLocal()](https://tweaked.cc/peripheral/modem.html#v:getNameLocal) | Returns the network name of the current computer, if the modem is on. | [](https://tweaked.cc/peripheral/modem.html#v:open) open(channel)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/ModemPeripheral.java#L160) Open a channel on a modem. A channel must be open in order to receive messages. Modems can have up to 128 channels open at one time. ### Parameters 1. channel `number` The channel to open. This must be a number between 0 and 65535. ### Throws * If the channel is out of range. * If there are too many open channels. [](https://tweaked.cc/peripheral/modem.html#v:isOpen) isOpen(channel)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/ModemPeripheral.java#L172) Check if a channel is open. ### Parameters 1. channel `number` The channel to check. ### Returns 1. `boolean` Whether the channel is open. ### Throws * If the channel is out of range. [](https://tweaked.cc/peripheral/modem.html#v:close) close(channel)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/ModemPeripheral.java#L183) Close an open channel, meaning it will no longer receive messages. ### Parameters 1. channel `number` The channel to close. ### Throws * If the channel is out of range. [](https://tweaked.cc/peripheral/modem.html#v:closeAll) closeAll()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/ModemPeripheral.java#L191) Close all open channels. [](https://tweaked.cc/peripheral/modem.html#v:transmit) transmit(channel, replyChannel, payload)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/ModemPeripheral.java#L217) Sends a modem message on a certain channel. Modems listening on the channel will queue a `modem_message` event on adjacent computers. ##### 🛈 note The channel does not need be open to send a message. ### Parameters 1. channel `number` The channel to send messages on. 2. replyChannel `number` The channel that responses to this message should be sent on. This can be the same as `channel` or entirely different. The channel must have been [opened](https://tweaked.cc/peripheral/modem.html#v:open) on the sending computer in order to receive the replies. 3. payload `any` The object to send. This can be any primitive type (boolean, number, string) as well as tables. Other types (like functions), as well as metatables, will not be transmitted. ### Throws * If the channel is out of range. ### Usage * Wrap a modem and a message on channel 15, requesting a response on channel 43. Run ᐅ local modem \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("modem") or error("No modem attached", 0) modem.transmit(15, 43, "Hello, world!") [](https://tweaked.cc/peripheral/modem.html#v:isWireless) isWireless()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/ModemPeripheral.java#L244) Determine if this is a wired or wireless modem. Some methods (namely those dealing with wired networks and remote peripherals) are only available on wired modems. ### Returns 1. `boolean` `true` if this is a wireless modem. [](https://tweaked.cc/peripheral/modem.html#v:getNamesRemote) getNamesRemote()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java#L98) List all remote peripherals on the wired network. If this computer is attached to the network, it _will not_ be included in this list. ##### 🛈 note This function only appears on wired modems. Check [`isWireless`](https://tweaked.cc/peripheral/modem.html#v:isWireless) returns false before calling it. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } Remote peripheral names on the network. [](https://tweaked.cc/peripheral/modem.html#v:isPresentRemote) isPresentRemote(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java#L115) Determine if a peripheral is available on this wired network. ##### 🛈 note This function only appears on wired modems. Check [`isWireless`](https://tweaked.cc/peripheral/modem.html#v:isWireless) returns false before calling it. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The peripheral's name. ### Returns 1. `boolean` boolean If a peripheral is present with the given name. ### See also * **[`peripheral.isPresent`](https://tweaked.cc/module/peripheral.html#v:isPresent) ** [](https://tweaked.cc/peripheral/modem.html#v:getTypeRemote) getTypeRemote(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java#L133) Get the type of a peripheral is available on this wired network. ##### 🛈 note This function only appears on wired modems. Check [`isWireless`](https://tweaked.cc/peripheral/modem.html#v:isWireless) returns false before calling it. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The peripheral's name. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The peripheral's type, or `nil` if it is not present. ### See also * **[`peripheral.getType`](https://tweaked.cc/module/peripheral.html#v:getType) ** ### Changes * **Changed in version 1.99:** Peripherals can have multiple types - this function returns multiple values. [](https://tweaked.cc/peripheral/modem.html#v:hasTypeRemote) hasTypeRemote(name, type)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java#L153) Check a peripheral is of a particular type. ##### 🛈 note This function only appears on wired modems. Check [`isWireless`](https://tweaked.cc/peripheral/modem.html#v:isWireless) returns false before calling it. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The peripheral's name. 2. type [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The type to check. ### Returns 1. `boolean` | nil If a peripheral has a particular type, or `nil` if it is not present. ### See also * **[`peripheral.getType`](https://tweaked.cc/module/peripheral.html#v:getType) ** ### Changes * **New in version 1.99** [](https://tweaked.cc/peripheral/modem.html#v:getMethodsRemote) getMethodsRemote(name)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java#L171) Get all available methods for the remote peripheral with the given name. ##### 🛈 note This function only appears on wired modems. Check [`isWireless`](https://tweaked.cc/peripheral/modem.html#v:isWireless) returns false before calling it. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The peripheral's name. ### Returns 1. { [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) ... } | nil A list of methods provided by this peripheral, or `nil` if it is not present. ### See also * **[`peripheral.getMethods`](https://tweaked.cc/module/peripheral.html#v:getMethods) ** [](https://tweaked.cc/peripheral/modem.html#v:callRemote) callRemote(remoteName, method, ...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java#L196) Call a method on a peripheral on this wired network. ##### 🛈 note This function only appears on wired modems. Check [`isWireless`](https://tweaked.cc/peripheral/modem.html#v:isWireless) returns false before calling it. ### Parameters 1. remoteName [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the peripheral to invoke the method on. 2. method [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the method 3. ... Additional arguments to pass to the method ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The return values of the peripheral method. ### See also * **[`peripheral.call`](https://tweaked.cc/module/peripheral.html#v:call) ** [](https://tweaked.cc/peripheral/modem.html#v:getNameLocal) getNameLocal()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java#L218) Returns the network name of the current computer, if the modem is on. This may be used by other computers on the network to wrap this computer as a peripheral. ##### 🛈 note This function only appears on wired modems. Check [`isWireless`](https://tweaked.cc/peripheral/modem.html#v:isWireless) returns false before calling it. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) | nil The current computer's name on the wired network. ### Changes * **New in version 1.80pr1.7** --- # energy_storage energy\_storage =============== Methods for interacting with blocks which store energy. This works with energy storage blocks, as well as generators and machines which consume energy. ##### 🛈 note Due to limitations with Forge's energy API, it is not possible to measure throughput (i.e. FE used/generated per tick). ### Changes * **New in version 1.94.0** | | | | --- | --- | | [getEnergy()](https://tweaked.cc/generic_peripheral/energy_storage.html#v:getEnergy) | Get the energy of this block. | | [getEnergyCapacity()](https://tweaked.cc/generic_peripheral/energy_storage.html#v:getEnergyCapacity) | Get the maximum amount of energy this block can store. | [](https://tweaked.cc/generic_peripheral/energy_storage.html#v:getEnergy) getEnergy()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/AbstractEnergyMethods.java#L42) Get the energy of this block. ### Returns 1. `number` The energy stored in this block, in FE. [](https://tweaked.cc/generic_peripheral/energy_storage.html#v:getEnergyCapacity) getEnergyCapacity()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/AbstractEnergyMethods.java#L51) Get the maximum amount of energy this block can store. ### Returns 1. `number` The energy capacity of this block. --- # disk disk ==== The [`disk`](https://tweaked.cc/module/disk.html) event is fired when a disk is inserted into an adjacent or networked disk drive. Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The side of the disk drive that had a disk inserted. Example ------- Prints a message when a disk is inserted: Run ᐅ while true do local event, side \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("disk") print("Inserted a disk on side " .. side) end ### See also * **[`disk_eject`](https://tweaked.cc/event/disk_eject.html) ** For the event sent when a disk is removed. --- # alarm alarm ===== The [`alarm`](https://tweaked.cc/event/alarm.html) event is fired when an alarm started with [`os.setAlarm`](https://tweaked.cc/module/os.html#v:setAlarm) completes. Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. `number`: The ID of the alarm that finished. Example ------- Starts a timer and then waits for it to complete. Run ᐅ local alarm\_id \= [os.setAlarm](https://tweaked.cc/module/os.html#v:setAlarm "Sets an alarm that will fire at the specified in-game time.") ([os.time](https://tweaked.cc/module/os.html#v:time "Returns the current time depending on the string passed in.") () + 0.05) local event, id repeat event, id \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("alarm") until id \== alarm\_id print("Alarm with ID " .. id .. " was fired") ### See also * **[`os.setAlarm`](https://tweaked.cc/module/os.html#v:setAlarm) ** To start an alarm. --- # char char ==== The [`char`](https://tweaked.cc/event/char.html) event is fired when a character is typed on the keyboard. The [`char`](https://tweaked.cc/event/char.html) event is different to a key press. Sometimes multiple key presses may result in one character being typed (for instance, on some European keyboards). Similarly, some keys (e.g. Ctrl) do not have any corresponding character. The [`key`](https://tweaked.cc/event/key.html) should be used if you want to listen to key presses themselves. Return values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The string representing the character that was pressed. Example ------- Prints each character the user presses: Run ᐅ while true do local event, character \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("char") print(character .. " was pressed.") end ### See also * **[`key`](https://tweaked.cc/event/key.html) ** To listen to any key press. --- # computer_command computer\_command ================= The [`computer_command`](https://tweaked.cc/event/computer_command.html) event is fired when the [`/computercraft queue` command](https://tweaked.cc/reference/computercraft_command.html#queue) is run for the current command computer. Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) …: The arguments passed to the command. Example ------- Prints the contents of messages sent: Run ᐅ while true do local event \= {[os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("computer\_command")} print("Received message:", table.unpack(event, 2)) end --- # http_check http\_check =========== The [`http_check`](https://tweaked.cc/event/http_check.html) event is fired when a URL check finishes. This event is normally handled inside [`http.checkURL`](https://tweaked.cc/module/http.html#v:checkURL) , but it can still be seen when using [`http.checkURLAsync`](https://tweaked.cc/module/http.html#v:checkURLAsync) . Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The URL requested to be checked. 3. `boolean`: Whether the check succeeded. 4. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) |`nil`: If the check failed, a reason explaining why the check failed. ### See also * **[`http.checkURLAsync`](https://tweaked.cc/module/http.html#v:checkURLAsync) ** To check a URL asynchronously. --- # file_transfer file\_transfer ============== The [`file_transfer`](https://tweaked.cc/event/file_transfer.html) event is queued when a user drags-and-drops a file on an open computer. This event contains a single argument of type [`TransferredFiles`](https://tweaked.cc/event/file_transfer.html#ty:TransferredFiles) , which can be used to [get the files to be transferred](https://tweaked.cc/event/file_transfer.html#ty:TransferredFiles:getFiles) . Each file returned is a [binary file handle](https://tweaked.cc/module/fs.html#ty:ReadHandle) with an additional [getName](https://tweaked.cc/event/file_transfer.html#ty:TransferredFile:getName) method. Return values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name 2. [`TransferredFiles`](https://tweaked.cc/event/file_transfer.html#ty:TransferredFiles) : The list of transferred files. Example ------- Waits for a user to drop files on top of the computer, then prints the list of files and the size of each file. Run ᐅ local \_, files \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("file\_transfer") for \_, file in ipairs(files.getFiles()) do \-- Seek to the end of the file to get its size, then go back to the beginning. local size \= file.seek("end") file.seek("set", 0) print(file.getName() .. " " .. size) end Example ------- Save each transferred file to the computer's storage. Run ᐅ local \_, files \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("file\_transfer") for \_, file in ipairs(files.getFiles()) do local handle \= [fs.open](https://tweaked.cc/module/fs.html#v:open "Opens a file for reading or writing at a path.") (file.getName(), "wb") handle.write(file.readAll()) handle.close() file.close() end ### Changes * **New in version 1.101.0** ### Types ### [](https://tweaked.cc/event/file_transfer.html#ty:TransferredFiles) TransferredFiles A list of files that have been transferred to this computer. [](https://tweaked.cc/event/file_transfer.html#ty:TransferredFiles:getFiles) TransferredFiles.getFiles()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/transfer/TransferredFiles.java#L40) All the files that are being transferred to this computer. ### Returns 1. { [`file_transfer.TransferredFile`](https://tweaked.cc/event/file_transfer.html#ty:TransferredFile) ... } The list of files. ### [](https://tweaked.cc/event/file_transfer.html#ty:TransferredFile) TransferredFile A binary file handle that has been transferred to this computer. This inherits all methods of [binary file handles](https://tweaked.cc/module/fs.html#ty:ReadHandle) , meaning you can use the standard [read functions](https://tweaked.cc/module/fs.html#ty:ReadHandle:read) to access the contents of the file. ### See also * **[`fs.ReadHandle`](https://tweaked.cc/module/fs.html#ty:ReadHandle) ** [](https://tweaked.cc/event/file_transfer.html#ty:TransferredFile:getName) TransferredFile.getName()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/transfer/TransferredFile.java#L38) Get the name of this file being transferred. ### Returns 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The file's name. --- # disk_eject disk\_eject =========== The [`disk_eject`](https://tweaked.cc/event/disk_eject.html) event is fired when a disk is removed from an adjacent or networked disk drive. Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The side of the disk drive that had a disk removed. Example ------- Prints a message when a disk is removed: Run ᐅ while true do local event, side \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("disk\_eject") print("Removed a disk on side " .. side) end ### See also * **[`disk`](https://tweaked.cc/module/disk.html) ** For the event sent when a disk is inserted. --- # http_failure http\_failure ============= The [`http_failure`](https://tweaked.cc/event/http_failure.html) event is fired when an HTTP request fails. This event is normally handled inside [`http.get`](https://tweaked.cc/module/http.html#v:get) and [`http.post`](https://tweaked.cc/module/http.html#v:post) , but it can still be seen when using [`http.request`](https://tweaked.cc/module/http.html#v:request) . Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The URL of the site requested. 3. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : An error describing the failure. 4. [`http.Response`](https://tweaked.cc/module/http.html#ty:Response) |`nil`: A response handle if the connection succeeded, but the server's response indicated failure. Example ------- Prints an error why the website cannot be contacted: Run ᐅ local myURL \= "https://does.not.exist.tweaked.cc" [http.request](https://tweaked.cc/module/http.html#v:request "Asynchronously make a HTTP request to the given url.") (myURL) local event, url, err repeat event, url, err \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("http\_failure") until url \== myURL print("The URL " .. url .. " could not be reached: " .. err) Prints the contents of a webpage that does not exist: Run ᐅ local myURL \= "https://tweaked.cc/this/does/not/exist" [http.request](https://tweaked.cc/module/http.html#v:request "Asynchronously make a HTTP request to the given url.") (myURL) local event, url, err, handle repeat event, url, err, handle \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("http\_failure") until url \== myURL print("The URL " .. url .. " could not be reached: " .. err) print(handle.getResponseCode()) handle.close() ### See also * **[`http.request`](https://tweaked.cc/module/http.html#v:request) ** To send an HTTP request. --- # key_up key\_up ======= Fired whenever a key is released (or the terminal is closed while a key was being pressed). This event returns a numerical "key code" (for instance, F1 is 290). This value may vary between versions and so it is recommended to use the constants in the [`keys`](https://tweaked.cc/module/keys.html) API rather than hard coding numeric values. Return values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. `number`: The numerical key value of the key pressed. Example ------- Prints each key released on the keyboard whenever a [`key_up`](https://tweaked.cc/event/key_up.html) event is fired. Run ᐅ while true do local event, key \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("key\_up") local name \= [keys.getName](https://tweaked.cc/module/keys.html#v:getName "Translates a numerical key code to a human-readable name.") (key) or "unknown key" print(name .. " was released.") end ### See also * **[`keys`](https://tweaked.cc/module/keys.html) ** For a lookup table of the given keys. --- # http_success http\_success ============= The [`http_success`](https://tweaked.cc/event/http_success.html) event is fired when an HTTP request returns successfully. This event is normally handled inside [`http.get`](https://tweaked.cc/module/http.html#v:get) and [`http.post`](https://tweaked.cc/module/http.html#v:post) , but it can still be seen when using [`http.request`](https://tweaked.cc/module/http.html#v:request) . Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The URL of the site requested. 3. [`http.Response`](https://tweaked.cc/module/http.html#ty:Response) : The successful HTTP response. Example ------- Prints the content of a website (this may fail if the request fails): Run ᐅ local myURL \= "https://tweaked.cc/" [http.request](https://tweaked.cc/module/http.html#v:request "Asynchronously make a HTTP request to the given url.") (myURL) local event, url, handle repeat event, url, handle \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("http\_success") until url \== myURL print("Contents of " .. url .. ":") print(handle.readAll()) handle.close() ### See also * **[`http.request`](https://tweaked.cc/module/http.html#v:request) ** To make an HTTP request. --- # key key === This event is fired when any key is pressed while the terminal is focused. This event returns a numerical "key code" (for instance, F1 is 290). This value may vary between versions and so it is recommended to use the constants in the [`keys`](https://tweaked.cc/module/keys.html) API rather than hard coding numeric values. If the button pressed represented a printable character, then the [`key`](https://tweaked.cc/event/key.html) event will be followed immediately by a [`char`](https://tweaked.cc/event/char.html) event. If you are consuming text input, use a [`char`](https://tweaked.cc/event/char.html) event instead! Return values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. `number`: The numerical key value of the key pressed. 3. `boolean`: Whether the key event was generated while holding the key (`true`), rather than pressing it the first time (`false`). Example ------- Prints each key when the user presses it, and if the key is being held. Run ᐅ while true do local event, key, is\_held \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("key") print(("%s held=%s"):format([keys.getName](https://tweaked.cc/module/keys.html#v:getName "Translates a numerical key code to a human-readable name.") (key), is\_held)) end --- # monitor_resize monitor\_resize =============== The [`monitor_resize`](https://tweaked.cc/event/monitor_resize.html) event is fired when an adjacent or networked [monitor's](https://tweaked.cc/peripheral/monitor.html) size is changed. Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The side or network ID of the monitor that was resized. Example ------- Prints a message when a monitor is resized: Run ᐅ while true do local event, side \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("monitor\_resize") print("The monitor on side " .. side .. " was resized.") end --- # modem_message modem\_message ============== The [`modem_message`](https://tweaked.cc/event/modem_message.html) event is fired when a message is received on an open channel on any [`modem`](https://tweaked.cc/peripheral/modem.html) . Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The side of the modem that received the message. 3. `number`: The channel that the message was sent on. 4. `number`: The reply channel set by the sender. 5. `any`: The message as sent by the sender. 6. `number`|`nil`: The distance between the sender and the receiver in blocks, or `nil` if the message was sent between dimensions. Example ------- Wraps a [`modem`](https://tweaked.cc/peripheral/modem.html) peripheral, opens channel 0 for listening, and prints all received messages. Run ᐅ local modem \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("modem") or error("No modem attached", 0) modem.open(0) while true do local event, side, channel, replyChannel, message, distance \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("modem\_message") print(("Message received on side %s on channel %d (reply to %d) from %f blocks away with message %s"):format( side, channel, replyChannel, distance, tostring(message) )) end --- # monitor_touch monitor\_touch ============== The [`monitor_touch`](https://tweaked.cc/event/monitor_touch.html) event is fired when an adjacent or networked [Advanced Monitor](https://tweaked.cc/peripheral/monitor.html) is right-clicked. Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The side or network ID of the monitor that was touched. 3. `number`: The X coordinate of the touch, in characters. 4. `number`: The Y coordinate of the touch, in characters. Example ------- Prints a message when a monitor is touched: Run ᐅ while true do local event, side, x, y \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("monitor\_touch") print("The monitor on side " .. side .. " was touched at (" .. x .. ", " .. y .. ")") end --- # fluid_storage fluid\_storage ============== Methods for interacting with tanks and other fluid storage blocks. ### Changes * **New in version 1.94.0** | | | | --- | --- | | [tanks()](https://tweaked.cc/generic_peripheral/fluid_storage.html#v:tanks) | Get all "tanks" in this fluid storage. | | [pushFluid(toName \[, limit \[, fluidName\]\])](https://tweaked.cc/generic_peripheral/fluid_storage.html#v:pushFluid) | Move a fluid from one fluid container to another connected one. | | [pullFluid(fromName \[, limit \[, fluidName\]\])](https://tweaked.cc/generic_peripheral/fluid_storage.html#v:pullFluid) | Move a fluid from a connected fluid container into this one. | [](https://tweaked.cc/generic_peripheral/fluid_storage.html#v:tanks) tanks()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/AbstractFluidMethods.java#L48) Get all "tanks" in this fluid storage. Each tank either contains some amount of fluid or is empty. Tanks with fluids inside will return some basic information about the fluid, including its name and amount. The returned table is sparse, and so empty tanks will be `nil` - it is recommended to loop over using [`pairs`](https://www.lua.org/manual/5.1/manual.html#pdf-pairs) rather than [`ipairs`](https://www.lua.org/manual/5.1/manual.html#pdf-ipairs) . ### Returns 1. { [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) | nil... } Basic information about all fluids in this fluid storage. [](https://tweaked.cc/generic_peripheral/fluid_storage.html#v:pushFluid) pushFluid(toName \[, limit \[, fluidName\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/AbstractFluidMethods.java#L67) Move a fluid from one fluid container to another connected one. This allows you to pull fluid in the current fluid container to another container _on the same wired network_. Both containers must attached to wired modems which are connected via a cable. ### Parameters 1. toName [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the peripheral/container to push to. This is the string given to [`peripheral.wrap`](https://tweaked.cc/module/peripheral.html#v:wrap) , and displayed by the wired modem. 2. limit? `number` The maximum amount of fluid to move. 3. fluidName? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The fluid to move. If not given, an arbitrary fluid will be chosen. ### Returns 1. `number` The amount of moved fluid. ### Throws * If the peripheral to transfer to doesn't exist or isn't an fluid container. ### See also * **[`peripheral.getName`](https://tweaked.cc/module/peripheral.html#v:getName) ** Allows you to get the name of a [wrapped](https://tweaked.cc/module/peripheral.html#v:wrap) peripheral. [](https://tweaked.cc/generic_peripheral/fluid_storage.html#v:pullFluid) pullFluid(fromName \[, limit \[, fluidName\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/AbstractFluidMethods.java#L88) Move a fluid from a connected fluid container into this one. This allows you to pull fluid in the current fluid container from another container _on the same wired network_. Both containers must be attached to wired modems which are connected via a cable. ### Parameters 1. fromName [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the peripheral/container to push to. This is the string given to [`peripheral.wrap`](https://tweaked.cc/module/peripheral.html#v:wrap) , and displayed by the wired modem. 2. limit? `number` The maximum amount of fluid to move. 3. fluidName? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The fluid to move. If not given, an arbitrary fluid will be chosen. ### Returns 1. `number` The amount of moved fluid. ### Throws * If the peripheral to transfer to doesn't exist or isn't an fluid container. ### See also * **[`peripheral.getName`](https://tweaked.cc/module/peripheral.html#v:getName) ** Allows you to get the name of a [wrapped](https://tweaked.cc/module/peripheral.html#v:wrap) peripheral. --- # printer printer ======= The printer peripheral allows printing text onto pages. These pages can then be crafted together into printed pages or books. Printers require ink (one of the coloured dyes) and paper in order to function. Once loaded, a new page can be started with [`newPage`](https://tweaked.cc/peripheral/printer.html#v:newPage) . Then the printer can be used similarly to a normal terminal; [text can be written](https://tweaked.cc/peripheral/printer.html#v:write) , and [the cursor moved](https://tweaked.cc/peripheral/printer.html#v:setCursorPos) . Once all text has been printed, [`endPage`](https://tweaked.cc/peripheral/printer.html#v:endPage) should be called to finally print the page. Recipes ------- **Printer** ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Redstone Dust](https://tweaked.cc/images/items/minecraft/redstone.png "Redstone Dust") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Black Dye](https://tweaked.cc/images/items/minecraft/black_dye.png "Black Dye") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Printer](https://tweaked.cc/images/items/computercraft/printer.png "Printer") **Printed Pages** ![Printed Page](https://tweaked.cc/images/items/computercraft/printed_page.png "Printed Page") ![Printed Page](https://tweaked.cc/images/items/computercraft/printed_page.png "Printed Page") ![String](https://tweaked.cc/images/items/minecraft/string.png "String") ![Printed Pages](https://tweaked.cc/images/items/computercraft/printed_pages.png "Printed Pages") **Printed Book** ![Leather](https://tweaked.cc/images/items/minecraft/leather.png "Leather") ![Printed Page](https://tweaked.cc/images/items/computercraft/printed_page.png "Printed Page") ![String](https://tweaked.cc/images/items/minecraft/string.png "String") ![Printed Book](https://tweaked.cc/images/items/computercraft/printed_book.png "Printed Book") ### Usage * Print a page titled "Hello" with a small message on it. Run ᐅ local printer \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("printer") \-- Start a new page, or print an error. if not printer.newPage() then error("Cannot start a new page. Do you have ink and paper?") end \-- Write to the page printer.setPageTitle("Hello") printer.write("This is my first page") printer.setCursorPos(1, 3) printer.write("This is two lines below.") \-- And finally print the page! if not printer.endPage() then error("Cannot end the page. Is there enough space?") end ### See also * **[`cc.strings.wrap`](https://tweaked.cc/library/cc.strings.html#v:wrap) ** To wrap text before printing it. | | | | --- | --- | | [write(text)](https://tweaked.cc/peripheral/printer.html#v:write) | Writes text to the current page. | | [getCursorPos()](https://tweaked.cc/peripheral/printer.html#v:getCursorPos) | Returns the current position of the cursor on the page. | | [setCursorPos(x, y)](https://tweaked.cc/peripheral/printer.html#v:setCursorPos) | Sets the position of the cursor on the page. | | [getPageSize()](https://tweaked.cc/peripheral/printer.html#v:getPageSize) | Returns the size of the current page. | | [newPage()](https://tweaked.cc/peripheral/printer.html#v:newPage) | Starts printing a new page. | | [endPage()](https://tweaked.cc/peripheral/printer.html#v:endPage) | Finalizes printing of the current page and outputs it to the tray. | | [setPageTitle(\[title\])](https://tweaked.cc/peripheral/printer.html#v:setPageTitle) | Sets the title of the current page. | | [getInkLevel()](https://tweaked.cc/peripheral/printer.html#v:getInkLevel) | Returns the amount of ink left in the printer. | | [getPaperLevel()](https://tweaked.cc/peripheral/printer.html#v:getPaperLevel) | Returns the amount of paper left in the printer. | [](https://tweaked.cc/peripheral/printer.html#v:write) write(text)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java#L81) Writes text to the current page. ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The value to write to the page. ### Throws * If any values couldn't be converted to a string, or if no page is started. [](https://tweaked.cc/peripheral/printer.html#v:getCursorPos) getCursorPos()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java#L97) Returns the current position of the cursor on the page. ### Returns 1. `number` The X position of the cursor. 2. `number` The Y position of the cursor. ### Throws * If a page isn't being printed. [](https://tweaked.cc/peripheral/printer.html#v:setCursorPos) setCursorPos(x, y)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java#L112) Sets the position of the cursor on the page. ### Parameters 1. x `number` The X coordinate to set the cursor at. 2. y `number` The Y coordinate to set the cursor at. ### Throws * If a page isn't being printed. [](https://tweaked.cc/peripheral/printer.html#v:getPageSize) getPageSize()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java#L126) Returns the size of the current page. ### Returns 1. `number` The width of the page. 2. `number` The height of the page. ### Throws * If a page isn't being printed. [](https://tweaked.cc/peripheral/printer.html#v:newPage) newPage()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java#L139) Starts printing a new page. ### Returns 1. `boolean` Whether a new page could be started. [](https://tweaked.cc/peripheral/printer.html#v:endPage) endPage()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java#L150) Finalizes printing of the current page and outputs it to the tray. ### Returns 1. `boolean` Whether the page could be successfully finished. ### Throws * If a page isn't being printed. [](https://tweaked.cc/peripheral/printer.html#v:setPageTitle) setPageTitle(\[title\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java#L162) Sets the title of the current page. ### Parameters 1. title? [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The title to set for the page. ### Throws * If a page isn't being printed. [](https://tweaked.cc/peripheral/printer.html#v:getInkLevel) getInkLevel()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java#L173) Returns the amount of ink left in the printer. ### Returns 1. `number` The amount of ink available to print with. [](https://tweaked.cc/peripheral/printer.html#v:getPaperLevel) getPaperLevel()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java#L183) Returns the amount of paper left in the printer. ### Returns 1. `number` The amount of paper available to print with. --- # redstone_relay redstone\_relay =============== The redstone relay is a peripheral that allows reading and outputting redstone signals. While this is not very useful on its own (as computers have the same functionality [built-in](https://tweaked.cc/module/redstone.html) ), this can be used with [wired modems](https://tweaked.cc/peripheral/modem.html) to interact with multiple redstone signals from the same computer. The peripheral provides largely identical methods to a computer's built-in [`redstone`](https://tweaked.cc/module/redstone.html) API, allowing setting signals on all six sides of the block ("top", "bottom", "left", "right", "front" and "back"). Recipe ------ **Redstone Relay** ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Redstone Dust](https://tweaked.cc/images/items/minecraft/redstone.png "Redstone Dust") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Redstone Dust](https://tweaked.cc/images/items/minecraft/redstone.png "Redstone Dust") ![Wired Modem](https://tweaked.cc/images/items/computercraft/wired_modem.png "Wired Modem") ![Redstone Dust](https://tweaked.cc/images/items/minecraft/redstone.png "Redstone Dust") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Redstone Dust](https://tweaked.cc/images/items/minecraft/redstone.png "Redstone Dust") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Redstone Relay](https://tweaked.cc/images/items/computercraft/redstone_relay.png "Redstone Relay") ### Usage * Toggle the redstone signal above the computer every 0.5 seconds. Run ᐅ local relay \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("redstone\_relay") while true do relay.setOutput("top", not relay.getOutput("top")) sleep(0.5) end ### Changes * **New in version 1.114.0** | | | | --- | --- | | [setOutput(side, on)](https://tweaked.cc/peripheral/redstone_relay.html#v:setOutput) | Turn the redstone signal of a specific side on or off. | | [getOutput(side)](https://tweaked.cc/peripheral/redstone_relay.html#v:getOutput) | Get the current redstone output of a specific side. | | [getInput(side)](https://tweaked.cc/peripheral/redstone_relay.html#v:getInput) | Get the current redstone input of a specific side. | | [setAnalogOutput(side, value)](https://tweaked.cc/peripheral/redstone_relay.html#v:setAnalogOutput) | Set the redstone signal strength for a specific side. | | [setAnalogueOutput(side, value)](https://tweaked.cc/peripheral/redstone_relay.html#v:setAnalogueOutput) | Set the redstone signal strength for a specific side. | | [getAnalogOutput(side)](https://tweaked.cc/peripheral/redstone_relay.html#v:getAnalogOutput) | Get the redstone output signal strength for a specific side. | | [getAnalogueOutput(side)](https://tweaked.cc/peripheral/redstone_relay.html#v:getAnalogueOutput) | Get the redstone output signal strength for a specific side. | | [getAnalogInput(side)](https://tweaked.cc/peripheral/redstone_relay.html#v:getAnalogInput) | Get the redstone input signal strength for a specific side. | | [getAnalogueInput(side)](https://tweaked.cc/peripheral/redstone_relay.html#v:getAnalogueInput) | Get the redstone input signal strength for a specific side. | | [setBundledOutput(side, output)](https://tweaked.cc/peripheral/redstone_relay.html#v:setBundledOutput) | Set the bundled cable output for a specific side. | | [getBundledOutput(side)](https://tweaked.cc/peripheral/redstone_relay.html#v:getBundledOutput) | Get the bundled cable output for a specific side. | | [getBundledInput(side)](https://tweaked.cc/peripheral/redstone_relay.html#v:getBundledInput) | Get the bundled cable input for a specific side. | | [testBundledInput(side, mask)](https://tweaked.cc/peripheral/redstone_relay.html#v:testBundledInput) | Determine if a specific combination of colours are on for the given side. | [](https://tweaked.cc/peripheral/redstone_relay.html#v:setOutput) setOutput(side, on)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L27) Turn the redstone signal of a specific side on or off. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to set. 2. on `boolean` Whether the redstone signal should be on or off. When on, a signal strength of 15 is emitted. [](https://tweaked.cc/peripheral/redstone_relay.html#v:getOutput) getOutput(side)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L39) Get the current redstone output of a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to get. ### Returns 1. `boolean` Whether the redstone output is on or off. ### See also * **[`setOutput`](https://tweaked.cc/peripheral/redstone_relay.html#v:setOutput) ** [](https://tweaked.cc/peripheral/redstone_relay.html#v:getInput) getInput(side)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L50) Get the current redstone input of a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to get. ### Returns 1. `boolean` Whether the redstone input is on or off. [](https://tweaked.cc/peripheral/redstone_relay.html#v:setAnalogOutput) setAnalogOutput(side, value)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L63) Set the redstone signal strength for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to set. 2. value `number` The signal strength between 0 and 15. ### Throws * If `value` is not between 0 and 15. ### Changes * **New in version 1.51** [](https://tweaked.cc/peripheral/redstone_relay.html#v:setAnalogueOutput) setAnalogueOutput(side, value)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L63) Set the redstone signal strength for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to set. 2. value `number` The signal strength between 0 and 15. ### Throws * If `value` is not between 0 and 15. ### Changes * **New in version 1.51** [](https://tweaked.cc/peripheral/redstone_relay.html#v:getAnalogOutput) getAnalogOutput(side)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L77) Get the redstone output signal strength for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to get. ### Returns 1. `number` The output signal strength, between 0 and 15. ### See also * **[`setAnalogOutput`](https://tweaked.cc/peripheral/redstone_relay.html#v:setAnalogOutput) ** ### Changes * **New in version 1.51** [](https://tweaked.cc/peripheral/redstone_relay.html#v:getAnalogueOutput) getAnalogueOutput(side)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L77) Get the redstone output signal strength for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to get. ### Returns 1. `number` The output signal strength, between 0 and 15. ### See also * **[`setAnalogOutput`](https://tweaked.cc/peripheral/redstone_relay.html#v:setAnalogOutput) ** ### Changes * **New in version 1.51** [](https://tweaked.cc/peripheral/redstone_relay.html#v:getAnalogInput) getAnalogInput(side)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L89) Get the redstone input signal strength for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to get. ### Returns 1. `number` The input signal strength, between 0 and 15. ### Changes * **New in version 1.51** [](https://tweaked.cc/peripheral/redstone_relay.html#v:getAnalogueInput) getAnalogueInput(side)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L89) Get the redstone input signal strength for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to get. ### Returns 1. `number` The input signal strength, between 0 and 15. ### Changes * **New in version 1.51** [](https://tweaked.cc/peripheral/redstone_relay.html#v:setBundledOutput) setBundledOutput(side, output)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L102) Set the bundled cable output for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to set. 2. output `number` The colour bitmask to set. ### See also * **[`colors.subtract`](https://tweaked.cc/module/colors.html#v:subtract) ** For removing a colour from the bitmask. * **[`colors.combine`](https://tweaked.cc/module/colors.html#v:combine) ** For adding a color to the bitmask. [](https://tweaked.cc/peripheral/redstone_relay.html#v:getBundledOutput) getBundledOutput(side)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L113) Get the bundled cable output for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to get. ### Returns 1. `number` The bundle cable's output. [](https://tweaked.cc/peripheral/redstone_relay.html#v:getBundledInput) getBundledInput(side)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L125) Get the bundled cable input for a specific side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to get. ### Returns 1. `number` The bundle cable's input. ### See also * **[`testBundledInput`](https://tweaked.cc/peripheral/redstone_relay.html#v:testBundledInput) ** To determine if a specific colour is set. [](https://tweaked.cc/peripheral/redstone_relay.html#v:testBundledInput) testBundledInput(side, mask)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneMethods.java#L142) Determine if a specific combination of colours are on for the given side. ### Parameters 1. side [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The side to test. 2. mask `number` The mask to test. ### Returns 1. `boolean` If the colours are on. ### Usage * Check if [`colors.white`](https://tweaked.cc/module/colors.html#v:white) and [`colors.black`](https://tweaked.cc/module/colors.html#v:black) are on above this block. Run ᐅ print([redstone.testBundledInput](https://tweaked.cc/module/redstone.html#v:testBundledInput "Determine if a specific combination of colours are on for the given side.") ("top", [colors.combine](https://tweaked.cc/module/colors.html#v:combine "Combines a set of colors (or sets of colors) into a larger set.") ([colors.white](https://tweaked.cc/module/colors.html#v:white "White: Written as 0 in paint files and term.blit, has a default terminal colour of #F0F0F0.") , [colors.black](https://tweaked.cc/module/colors.html#v:black "Black: Written as f in paint files and term.blit, has a default terminal colour of #111111.") ))) ### See also * **[`getBundledInput`](https://tweaked.cc/peripheral/redstone_relay.html#v:getBundledInput) ** --- # monitor monitor ======= Monitors are a block which act as a terminal, displaying information on one side. This allows them to be read and interacted with in-world without opening a GUI. Monitors act as [terminal redirects](https://tweaked.cc/module/term.html#ty:Redirect) and so expose the same methods, as well as several additional ones, which are documented below. If the monitor is resized (by adding new blocks to the monitor, or by calling [`setTextScale`](https://tweaked.cc/peripheral/monitor.html#v:setTextScale) ), then a [`monitor_resize`](https://tweaked.cc/event/monitor_resize.html) event will be queued. Like computers, monitors come in both normal (no colour) and advanced (colour) varieties. Advanced monitors be right clicked, which will trigger a [`monitor_touch`](https://tweaked.cc/event/monitor_touch.html) event. Recipes ------- **Monitor** ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Glass Pane](https://tweaked.cc/images/items/minecraft/glass_pane.png "Glass Pane") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Monitor](https://tweaked.cc/images/items/computercraft/monitor_normal.png "Monitor") **Advanced Monitor** ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Glass Pane](https://tweaked.cc/images/items/minecraft/glass_pane.png "Glass Pane") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Gold Ingot](https://tweaked.cc/images/items/minecraft/gold_ingot.png "Gold Ingot") ![Advanced Monitor](https://tweaked.cc/images/items/computercraft/monitor_advanced.png "Advanced Monitor")4 ### Usage * Write "Hello, world!" to an adjacent monitor: Run ᐅ local monitor \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("monitor") monitor.setCursorPos(1, 1) monitor.write("Hello, world!") ### See also * **[`monitor_resize`](https://tweaked.cc/event/monitor_resize.html) ** Queued when a monitor is resized. * **[`monitor_touch`](https://tweaked.cc/event/monitor_touch.html) ** Queued when an advanced monitor is clicked. | | | | --- | --- | | [setTextScale(scale)](https://tweaked.cc/peripheral/monitor.html#v:setTextScale) | Set the scale of this monitor. | | [getTextScale()](https://tweaked.cc/peripheral/monitor.html#v:getTextScale) | Get the monitor's current text scale. | | [write(text)](https://tweaked.cc/peripheral/monitor.html#v:write) | Write `text` at the current cursor position, moving the cursor to the end of the text. | | [scroll(y)](https://tweaked.cc/peripheral/monitor.html#v:scroll) | Move all positions up (or down) by `y` pixels. | | [getCursorPos()](https://tweaked.cc/peripheral/monitor.html#v:getCursorPos) | Get the position of the cursor. | | [setCursorPos(x, y)](https://tweaked.cc/peripheral/monitor.html#v:setCursorPos) | Set the position of the cursor. | | [getCursorBlink()](https://tweaked.cc/peripheral/monitor.html#v:getCursorBlink) | Checks if the cursor is currently blinking. | | [setCursorBlink(blink)](https://tweaked.cc/peripheral/monitor.html#v:setCursorBlink) | Sets whether the cursor should be visible (and blinking) at the current [cursor position](https://tweaked.cc/peripheral/monitor.html#v:getCursorPos)
. | | [getSize()](https://tweaked.cc/peripheral/monitor.html#v:getSize) | Get the size of the terminal. | | [clear()](https://tweaked.cc/peripheral/monitor.html#v:clear) | Clears the terminal, filling it with the [current background colour](https://tweaked.cc/peripheral/monitor.html#v:getBackgroundColour)
. | | [clearLine()](https://tweaked.cc/peripheral/monitor.html#v:clearLine) | Clears the line the cursor is currently on, filling it with the [current background colour](https://tweaked.cc/peripheral/monitor.html#v:getBackgroundColour)
. | | [getTextColour()](https://tweaked.cc/peripheral/monitor.html#v:getTextColour) | Return the colour that new text will be written as. | | [getTextColor()](https://tweaked.cc/peripheral/monitor.html#v:getTextColor) | Return the colour that new text will be written as. | | [setTextColour(colour)](https://tweaked.cc/peripheral/monitor.html#v:setTextColour) | Set the colour that new text will be written as. | | [setTextColor(colour)](https://tweaked.cc/peripheral/monitor.html#v:setTextColor) | Set the colour that new text will be written as. | | [getBackgroundColour()](https://tweaked.cc/peripheral/monitor.html#v:getBackgroundColour) | Return the current background colour. | | [getBackgroundColor()](https://tweaked.cc/peripheral/monitor.html#v:getBackgroundColor) | Return the current background colour. | | [setBackgroundColour(colour)](https://tweaked.cc/peripheral/monitor.html#v:setBackgroundColour) | Set the current background colour. | | [setBackgroundColor(colour)](https://tweaked.cc/peripheral/monitor.html#v:setBackgroundColor) | Set the current background colour. | | [isColour()](https://tweaked.cc/peripheral/monitor.html#v:isColour) | Determine if this terminal supports colour. | | [isColor()](https://tweaked.cc/peripheral/monitor.html#v:isColor) | Determine if this terminal supports colour. | | [blit(text, textColour, backgroundColour)](https://tweaked.cc/peripheral/monitor.html#v:blit) | Writes `text` to the terminal with the specific foreground and background colours. | | [setPaletteColour(...)](https://tweaked.cc/peripheral/monitor.html#v:setPaletteColour) | Set the palette for a specific colour. | | [setPaletteColor(...)](https://tweaked.cc/peripheral/monitor.html#v:setPaletteColor) | Set the palette for a specific colour. | | [getPaletteColour(colour)](https://tweaked.cc/peripheral/monitor.html#v:getPaletteColour) | Get the current palette for a specific colour. | | [getPaletteColor(colour)](https://tweaked.cc/peripheral/monitor.html#v:getPaletteColor) | Get the current palette for a specific colour. | [](https://tweaked.cc/peripheral/monitor.html#v:setTextScale) setTextScale(scale)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/monitor/MonitorPeripheral.java#L66) Set the scale of this monitor. A larger scale will result in the monitor having a lower resolution, but display text much larger. ### Parameters 1. scale `number` The monitor's scale. This must be a multiple of 0.5 between 0.5 and 5. ### Throws * If the scale is out of range. ### See also * **[`getTextScale`](https://tweaked.cc/peripheral/monitor.html#v:getTextScale) ** [](https://tweaked.cc/peripheral/monitor.html#v:getTextScale) getTextScale()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/monitor/MonitorPeripheral.java#L80) Get the monitor's current text scale. ### Returns 1. `number` The monitor's current scale. ### Throws * If the monitor cannot be found. ### Changes * **New in version 1.81.0** [](https://tweaked.cc/peripheral/monitor.html#v:write) write(text)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L38) Write `text` at the current cursor position, moving the cursor to the end of the text. Unlike functions like [`_G.write`](https://tweaked.cc/module/_G.html#v:write) and [`print`](https://www.lua.org/manual/5.1/manual.html#pdf-print) , this does not wrap the text - it simply copies the text to the current terminal line. ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The text to write. [](https://tweaked.cc/peripheral/monitor.html#v:scroll) scroll(y)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L57) Move all positions up (or down) by `y` pixels. Every pixel in the terminal will be replaced by the line `y` pixels below it. If `y` is negative, it will copy pixels from above instead. ### Parameters 1. y `number` The number of lines to move up by. This may be a negative number. [](https://tweaked.cc/peripheral/monitor.html#v:getCursorPos) getCursorPos()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L70) Get the position of the cursor. ### Returns 1. `number` The x position of the cursor. 2. `number` The y position of the cursor. [](https://tweaked.cc/peripheral/monitor.html#v:setCursorPos) setCursorPos(x, y)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L83) Set the position of the cursor. [Terminal writes](https://tweaked.cc/peripheral/monitor.html#v:write) will begin from this position. ### Parameters 1. x `number` The new x position of the cursor. 2. y `number` The new y position of the cursor. [](https://tweaked.cc/peripheral/monitor.html#v:getCursorBlink) getCursorBlink()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L98) Checks if the cursor is currently blinking. ### Returns 1. `boolean` If the cursor is blinking. ### Changes * **New in version 1.80pr1.9** [](https://tweaked.cc/peripheral/monitor.html#v:setCursorBlink) setCursorBlink(blink)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L109) Sets whether the cursor should be visible (and blinking) at the current [cursor position](https://tweaked.cc/peripheral/monitor.html#v:getCursorPos) . ### Parameters 1. blink `boolean` Whether the cursor should blink. [](https://tweaked.cc/peripheral/monitor.html#v:getSize) getSize()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L125) Get the size of the terminal. ### Returns 1. `number` The terminal's width. 2. `number` The terminal's height. [](https://tweaked.cc/peripheral/monitor.html#v:clear) clear()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L136) Clears the terminal, filling it with the [current background colour](https://tweaked.cc/peripheral/monitor.html#v:getBackgroundColour) . [](https://tweaked.cc/peripheral/monitor.html#v:clearLine) clearLine()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L147) Clears the line the cursor is currently on, filling it with the [current background colour](https://tweaked.cc/peripheral/monitor.html#v:getBackgroundColour) . [](https://tweaked.cc/peripheral/monitor.html#v:getTextColour) getTextColour()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L160) Return the colour that new text will be written as. ### Returns 1. `number` The current text colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants, returned by this function. ### Changes * **New in version 1.74** [](https://tweaked.cc/peripheral/monitor.html#v:getTextColor) getTextColor()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L160) Return the colour that new text will be written as. ### Returns 1. `number` The current text colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants, returned by this function. ### Changes * **New in version 1.74** [](https://tweaked.cc/peripheral/monitor.html#v:setTextColour) setTextColour(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L174) Set the colour that new text will be written as. ### Parameters 1. colour `number` The new text colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants. ### Changes * **New in version 1.45** * **Changed in version 1.80pr1:** Standard computers can now use all 16 colors, being changed to grayscale on screen. [](https://tweaked.cc/peripheral/monitor.html#v:setTextColor) setTextColor(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L174) Set the colour that new text will be written as. ### Parameters 1. colour `number` The new text colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants. ### Changes * **New in version 1.45** * **Changed in version 1.80pr1:** Standard computers can now use all 16 colors, being changed to grayscale on screen. [](https://tweaked.cc/peripheral/monitor.html#v:getBackgroundColour) getBackgroundColour()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L192) Return the current background colour. This is used when [writing text](https://tweaked.cc/peripheral/monitor.html#v:write) and [clearing](https://tweaked.cc/peripheral/monitor.html#v:clear) the terminal. ### Returns 1. `number` The current background colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants, returned by this function. ### Changes * **New in version 1.74** [](https://tweaked.cc/peripheral/monitor.html#v:getBackgroundColor) getBackgroundColor()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L192) Return the current background colour. This is used when [writing text](https://tweaked.cc/peripheral/monitor.html#v:write) and [clearing](https://tweaked.cc/peripheral/monitor.html#v:clear) the terminal. ### Returns 1. `number` The current background colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants, returned by this function. ### Changes * **New in version 1.74** [](https://tweaked.cc/peripheral/monitor.html#v:setBackgroundColour) setBackgroundColour(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L207) Set the current background colour. This is used when [writing text](https://tweaked.cc/peripheral/monitor.html#v:write) and [clearing](https://tweaked.cc/peripheral/monitor.html#v:clear) the terminal. ### Parameters 1. colour `number` The new background colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants. ### Changes * **New in version 1.45** * **Changed in version 1.80pr1:** Standard computers can now use all 16 colors, being changed to grayscale on screen. [](https://tweaked.cc/peripheral/monitor.html#v:setBackgroundColor) setBackgroundColor(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L207) Set the current background colour. This is used when [writing text](https://tweaked.cc/peripheral/monitor.html#v:write) and [clearing](https://tweaked.cc/peripheral/monitor.html#v:clear) the terminal. ### Parameters 1. colour `number` The new background colour. ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants. ### Changes * **New in version 1.45** * **Changed in version 1.80pr1:** Standard computers can now use all 16 colors, being changed to grayscale on screen. [](https://tweaked.cc/peripheral/monitor.html#v:isColour) isColour()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L226) Determine if this terminal supports colour. Terminals which do not support colour will still allow writing coloured text/backgrounds, but it will be displayed in greyscale. ### Returns 1. `boolean` Whether this terminal supports colour. ### Changes * **New in version 1.45** [](https://tweaked.cc/peripheral/monitor.html#v:isColor) isColor()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L226) Determine if this terminal supports colour. Terminals which do not support colour will still allow writing coloured text/backgrounds, but it will be displayed in greyscale. ### Returns 1. `boolean` Whether this terminal supports colour. ### Changes * **New in version 1.45** [](https://tweaked.cc/peripheral/monitor.html#v:blit) blit(text, textColour, backgroundColour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L253) Writes `text` to the terminal with the specific foreground and background colours. As with [`write`](https://tweaked.cc/peripheral/monitor.html#v:write) , the text will be written at the current cursor location, with the cursor moving to the end of the text. `textColour` and `backgroundColour` must both be strings the same length as `text`. All characters represent a single hexadecimal digit, which is converted to one of CC's colours. For instance, `"a"` corresponds to purple. ### Parameters 1. text [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The text to write. 2. textColour [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The corresponding text colours. 3. backgroundColour [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The corresponding background colours. ### Throws * If the three inputs are not the same length. ### Usage * Prints "Hello, world!" in rainbow text. Run ᐅ [term.blit](https://tweaked.cc/module/term.html#v:blit "Writes text to the terminal with the specific foreground and background colours.") ("Hello, world!","01234456789ab","0000000000000") ### See also * **[`colors`](https://tweaked.cc/module/colors.html) ** For a list of colour constants, and their hexadecimal values. ### Changes * **New in version 1.74** * **Changed in version 1.80pr1:** Standard computers can now use all 16 colors, being changed to grayscale on screen. [](https://tweaked.cc/peripheral/monitor.html#v:setPaletteColour) setPaletteColour(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L299) Set the palette for a specific colour. ComputerCraft's palette system allows you to change how a specific colour should be displayed. For instance, you can make [`colors.red`](https://tweaked.cc/module/colors.html#v:red) _more red_ by setting its palette to #FF0000. This does now allow you to draw more colours - you are still limited to 16 on the screen at one time - but you can change _which_ colours are used. ### Parameters 1. index `number` The colour whose palette should be changed. 2. colour `number` A 24-bit integer representing the RGB value of the colour. For instance the integer `0xFF0000` corresponds to the colour #FF0000. #### Or 1. index `number` The colour whose palette should be changed. 2. r `number` The intensity of the red channel, between 0 and 1. 3. g `number` The intensity of the green channel, between 0 and 1. 4. b `number` The intensity of the blue channel, between 0 and 1. ### Usage * Change the [red colour](https://tweaked.cc/module/colors.html#v:red) from the default #CC4C4C to #FF0000. Run ᐅ [term.setPaletteColour](https://tweaked.cc/module/term.html#v:setPaletteColour "Set the palette for a specific colour.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") , 0xFF0000) [term.setTextColour](https://tweaked.cc/module/term.html#v:setTextColour "Set the colour that new text will be written as.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") ) print("Hello, world!") * As above, but specifying each colour channel separately. Run ᐅ [term.setPaletteColour](https://tweaked.cc/module/term.html#v:setPaletteColour "Set the palette for a specific colour.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") , 1, 0, 0) [term.setTextColour](https://tweaked.cc/module/term.html#v:setTextColour "Set the colour that new text will be written as.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") ) print("Hello, world!") ### See also * **[`colors.unpackRGB`](https://tweaked.cc/module/colors.html#v:unpackRGB) ** To convert from the 24-bit format to three separate channels. * **[`colors.packRGB`](https://tweaked.cc/module/colors.html#v:packRGB) ** To convert from three separate channels to the 24-bit format. ### Changes * **New in version 1.80pr1** [](https://tweaked.cc/peripheral/monitor.html#v:setPaletteColor) setPaletteColor(...)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L299) Set the palette for a specific colour. ComputerCraft's palette system allows you to change how a specific colour should be displayed. For instance, you can make [`colors.red`](https://tweaked.cc/module/colors.html#v:red) _more red_ by setting its palette to #FF0000. This does now allow you to draw more colours - you are still limited to 16 on the screen at one time - but you can change _which_ colours are used. ### Parameters 1. index `number` The colour whose palette should be changed. 2. colour `number` A 24-bit integer representing the RGB value of the colour. For instance the integer `0xFF0000` corresponds to the colour #FF0000. #### Or 1. index `number` The colour whose palette should be changed. 2. r `number` The intensity of the red channel, between 0 and 1. 3. g `number` The intensity of the green channel, between 0 and 1. 4. b `number` The intensity of the blue channel, between 0 and 1. ### Usage * Change the [red colour](https://tweaked.cc/module/colors.html#v:red) from the default #CC4C4C to #FF0000. Run ᐅ [term.setPaletteColour](https://tweaked.cc/module/term.html#v:setPaletteColour "Set the palette for a specific colour.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") , 0xFF0000) [term.setTextColour](https://tweaked.cc/module/term.html#v:setTextColour "Set the colour that new text will be written as.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") ) print("Hello, world!") * As above, but specifying each colour channel separately. Run ᐅ [term.setPaletteColour](https://tweaked.cc/module/term.html#v:setPaletteColour "Set the palette for a specific colour.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") , 1, 0, 0) [term.setTextColour](https://tweaked.cc/module/term.html#v:setTextColour "Set the colour that new text will be written as.") ([colors.red](https://tweaked.cc/module/colors.html#v:red "Red: Written as e in paint files and term.blit, has a default terminal colour of #CC4C4C.") ) print("Hello, world!") ### See also * **[`colors.unpackRGB`](https://tweaked.cc/module/colors.html#v:unpackRGB) ** To convert from the 24-bit format to three separate channels. * **[`colors.packRGB`](https://tweaked.cc/module/colors.html#v:packRGB) ** To convert from three separate channels to the 24-bit format. ### Changes * **New in version 1.80pr1** [](https://tweaked.cc/peripheral/monitor.html#v:getPaletteColour) getPaletteColour(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L325) Get the current palette for a specific colour. ### Parameters 1. colour `number` The colour whose palette should be fetched. ### Returns 1. `number` The red channel, will be between 0 and 1. 2. `number` The green channel, will be between 0 and 1. 3. `number` The blue channel, will be between 0 and 1. ### Changes * **New in version 1.80pr1** [](https://tweaked.cc/peripheral/monitor.html#v:getPaletteColor) getPaletteColor(colour)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java#L325) Get the current palette for a specific colour. ### Parameters 1. colour `number` The colour whose palette should be fetched. ### Returns 1. `number` The red channel, will be between 0 and 1. 2. `number` The green channel, will be between 0 and 1. 3. `number` The blue channel, will be between 0 and 1. ### Changes * **New in version 1.80pr1** --- # speaker speaker ======= The speaker peripheral allows your computer to play notes and other sounds. The speaker can play three kinds of sound, in increasing orders of complexity: * [`playNote`](https://tweaked.cc/peripheral/speaker.html#v:playNote) allows you to play noteblock note. * [`playSound`](https://tweaked.cc/peripheral/speaker.html#v:playSound) plays any Minecraft sound, such as block sounds or mob noises. * [`playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) can play arbitrary audio. Recipe ------ **Speaker** ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Note Block](https://tweaked.cc/images/items/minecraft/note_block.png "Note Block") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Redstone Dust](https://tweaked.cc/images/items/minecraft/redstone.png "Redstone Dust") ![Stone](https://tweaked.cc/images/items/minecraft/stone.png "Stone") ![Speaker](https://tweaked.cc/images/items/computercraft/speaker.png "Speaker") ### Changes * **New in version 1.80pr1** | | | | --- | --- | | [playNote(instrument \[, volume \[, pitch\]\])](https://tweaked.cc/peripheral/speaker.html#v:playNote) | Plays a note block note through the speaker. | | [playSound(name \[, volume \[, pitch\]\])](https://tweaked.cc/peripheral/speaker.html#v:playSound) | Plays a Minecraft sound through the speaker. | | [playAudio(audio \[, volume\])](https://tweaked.cc/peripheral/speaker.html#v:playAudio) | Attempt to stream some audio data to the speaker. | | [stop()](https://tweaked.cc/peripheral/speaker.html#v:stop) | Stop all audio being played by this speaker. | [](https://tweaked.cc/peripheral/speaker.html#v:playNote) playNote(instrument \[, volume \[, pitch\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java#L211) Plays a note block note through the speaker. This takes the name of a note to play, as well as optionally the volume and pitch to play the note at. The pitch argument uses semitones as the unit. This directly maps to the number of clicks on a note block. For reference, 0, 12, and 24 map to F#, and 6 and 18 map to C. A maximum of 8 notes can be played in a single tick. If this limit is hit, this function will return `false`. ### Valid instruments The speaker supports [all of Minecraft's noteblock instruments](https://minecraft.wiki/w/Note_Block#Instruments) . These are: `"harp"`, `"basedrum"`, `"snare"`, `"hat"`, `"bass"`, `"flute"`, `"bell"`, `"guitar"`, `"chime"`, `"xylophone"`, `"iron_xylophone"`, `"cow_bell"`, `"didgeridoo"`, `"bit"`, `"banjo"` and `"pling"`. ### Parameters 1. instrument [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The instrument to use to play this note. 2. volume? `number` The volume to play the note at, from 0.0 to 3.0. Defaults to 1.0. 3. pitch? `number` The pitch to play the note at in semitones, from 0 to 24. Defaults to 12. ### Returns 1. `boolean` Whether the note could be played as the limit was reached. ### Throws * If the instrument doesn't exist. [](https://tweaked.cc/peripheral/speaker.html#v:playSound) playSound(name \[, volume \[, pitch\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java#L256) Plays a Minecraft sound through the speaker. This takes the name of a [vanilla Minecraft](https://minecraft.wiki/w/Sounds.json) or modded sound, such as `"minecraft:block.note_block.harp"`, as well as an optional volume and pitch. Only one sound can be played at once. This function will return `false` if another sound was started this tick, or if some [audio](https://tweaked.cc/peripheral/speaker.html#v:playAudio) is still playing. ### Parameters 1. name [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the sound to play. 2. volume? `number` The volume to play the sound at, from 0.0 to 3.0. Defaults to 1.0. 3. pitch? `number` The speed to play the sound at, from 0.5 to 2.0. Defaults to 1.0. ### Returns 1. `boolean` Whether the sound could be played. ### Throws * If the sound name was invalid. ### Usage * Play a creeper hiss with the speaker. Run ᐅ local speaker \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("speaker") speaker.playSound("entity.creeper.primed") [](https://tweaked.cc/peripheral/speaker.html#v:playAudio) playAudio(audio \[, volume\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java#L323) Attempt to stream some audio data to the speaker. This accepts a list of audio samples as amplitudes between -128 and 127. These are stored in an internal buffer and played back at 48kHz. If this buffer is full, this function will return `false`. Programs should wait for a [`speaker_audio_empty`](https://tweaked.cc/event/speaker_audio_empty.html) event before trying to play audio again. The speaker only buffers a single call to [`playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) at once. This means if you try to play a small number of samples, you'll have a lot of stutter. You should try to play as many samples in one call as possible (up to 128×1024), as this reduces the chances of audio stuttering or halting, especially when the server or computer is lagging. While the speaker accepts 8-bit PCM audio, the audio stream is re-encoded before being played. This means that the supplied samples may not be played out exactly. [Playing audio with speakers](https://tweaked.cc/guide/speaker_audio.html) provides a more complete guide to using speakers. ### Parameters 1. audio { `number`... } A list of amplitudes. 2. volume? `number` The volume to play this audio at. If not given, defaults to the previous volume given to [`playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) . ### Returns 1. `boolean` If there was room to accept this audio data. ### Throws * If the audio data is malformed. ### Usage * Read an audio file, decode it using [`cc.audio.dfpwm`](https://tweaked.cc/library/cc.audio.dfpwm.html) , and play it using the speaker. Run ᐅ local [dfpwm](https://tweaked.cc/library/cc.audio.dfpwm.html "Convert between streams of DFPWM audio data and a list of amplitudes.") \= require("cc.audio.dfpwm") local speaker \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("speaker") local decoder \= [dfpwm.make\_decoder](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_decoder "Create a new decoder for converting DFPWM into PCM audio data.") () for chunk in [io.lines](https://tweaked.cc/module/io.html#v:lines "Opens the given file name in read mode and returns an iterator that, each time it is called, returns a new line from the file.") ("data/example.dfpwm", 16 \* 1024) do local buffer \= decoder(chunk) while not speaker.playAudio(buffer) do [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("speaker\_audio\_empty") end end ### See also * **[`cc.audio.dfpwm`](https://tweaked.cc/library/cc.audio.dfpwm.html) ** Provides utilities for decoding DFPWM audio files into a format which can be played by the speaker. * **[`Playing audio with speakers`](https://tweaked.cc/guide/speaker_audio.html) ** For a more complete introduction to the [`playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) function. ### Changes * **New in version 1.100** [](https://tweaked.cc/peripheral/speaker.html#v:stop) stop()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java#L350) Stop all audio being played by this speaker. This clears any audio that [`playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) had queued and stops the latest sound played by [`playSound`](https://tweaked.cc/peripheral/speaker.html#v:playSound) . ### Changes * **New in version 1.100** --- # inventory inventory ========= Methods for interacting with inventories. ### Changes * **New in version 1.94.0** | | | | --- | --- | | [size()](https://tweaked.cc/generic_peripheral/inventory.html#v:size) | Get the size of this inventory. | | [list()](https://tweaked.cc/generic_peripheral/inventory.html#v:list) | List all items in this inventory. | | [getItemDetail(slot)](https://tweaked.cc/generic_peripheral/inventory.html#v:getItemDetail) | Get [detailed information](https://tweaked.cc/reference/item_details.html)
about an item. | | [getItemLimit(slot)](https://tweaked.cc/generic_peripheral/inventory.html#v:getItemLimit) | Get the maximum number of items which can be stored in this slot. | | [pushItems(toName, fromSlot \[, limit \[, toSlot\]\])](https://tweaked.cc/generic_peripheral/inventory.html#v:pushItems) | Push items from one inventory to another connected one. | | [pullItems(fromName, fromSlot \[, limit \[, toSlot\]\])](https://tweaked.cc/generic_peripheral/inventory.html#v:pullItems) | Pull items from a connected inventory into this one. | [](https://tweaked.cc/generic_peripheral/inventory.html#v:size) size()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/AbstractInventoryMethods.java#L42) Get the size of this inventory. ### Returns 1. `number` The number of slots in this inventory. [](https://tweaked.cc/generic_peripheral/inventory.html#v:list) list()[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/AbstractInventoryMethods.java#L69) List all items in this inventory. This returns a table, with an entry for each slot. Each item in the inventory is represented by a table containing [some basic information](https://tweaked.cc/reference/item_details.html) . More information can be fetched with [`getItemDetail`](https://tweaked.cc/generic_peripheral/inventory.html#v:getItemDetail) . The table contains the item `name`, the `count` and an a (potentially nil) hash of the item's `nbt.` This NBT data doesn't contain anything useful, but allows you to distinguish identical items. The returned table is sparse, and so empty slots will be `nil` - it is recommended to loop over using [`pairs`](https://www.lua.org/manual/5.1/manual.html#pdf-pairs) rather than [`ipairs`](https://www.lua.org/manual/5.1/manual.html#pdf-ipairs) . ### Returns 1. { [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) | nil... } Basic information about all items in this inventory. ### Usage * Find an adjacent chest and print all items in it. Run ᐅ local chest \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("minecraft:chest") for slot, item in pairs(chest.list()) do print(("%d x %s in slot %d"):format(item.count, item.name, slot)) end ### See also * **[`Item details`](https://tweaked.cc/reference/item_details.html) ** [](https://tweaked.cc/generic_peripheral/inventory.html#v:getItemDetail) getItemDetail(slot)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/AbstractInventoryMethods.java#L95) Get [detailed information](https://tweaked.cc/reference/item_details.html) about an item. ### Parameters 1. slot `number` The slot to get information about. ### Returns 1. [`table`](https://www.lua.org/manual/5.1/manual.html#5.5) | nil Information about the item in this slot, or `nil` if it is empty. ### Throws * If the slot is out of range. ### Usage * Print some information about the first in a chest. Run ᐅ local chest \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("minecraft:chest") local item \= chest.getItemDetail(1) if not item then print("No item") return end print(("%s (%s)"):format(item.displayName, item.name)) print(("Count: %d/%d"):format(item.count, item.maxCount)) if item.damage then print(("Damage: %d/%d"):format(item.damage, item.maxDamage)) end ### See also * **[`Item details`](https://tweaked.cc/reference/item_details.html) ** [](https://tweaked.cc/generic_peripheral/inventory.html#v:getItemLimit) getItemLimit(slot)[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/AbstractInventoryMethods.java#L120) Get the maximum number of items which can be stored in this slot. Typically this will be limited to 64 items. However, some inventories (such as barrels or caches) can store hundreds or thousands of items in one slot. ### Parameters 1. slot `number` The slot ### Returns 1. `number` The maximum number of items in this slot. ### Throws * If the slot is out of range. ### Usage * Count the maximum number of items an adjacent chest can hold. Run ᐅ local chest \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("minecraft:chest") local total \= 0 for i \= 1, chest.size() do total \= total + chest.getItemLimit(i) end print(total) ### Changes * **New in version 1.96.0** [](https://tweaked.cc/generic_peripheral/inventory.html#v:pushItems) pushItems(toName, fromSlot \[, limit \[, toSlot\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/AbstractInventoryMethods.java#L148) Push items from one inventory to another connected one. This allows you to push an item in an inventory to another inventory _on the same wired network_. Both inventories must attached to wired modems which are connected via a cable. ### Parameters 1. toName [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the peripheral/inventory to push to. This is the string given to [`peripheral.wrap`](https://tweaked.cc/module/peripheral.html#v:wrap) , and displayed by the wired modem. 2. fromSlot `number` The slot in the current inventory to move items to. 3. limit? `number` The maximum number of items to move. Defaults to the current stack limit. 4. toSlot? `number` The slot in the target inventory to move to. If not given, the item will be inserted into any slot. ### Returns 1. `number` The number of transferred items. ### Throws * If the peripheral to transfer to doesn't exist or isn't an inventory. * If either source or destination slot is out of range. ### Usage * Wrap two chests, and push an item from one to another. Run ᐅ local chest\_a \= [peripheral.wrap](https://tweaked.cc/module/peripheral.html#v:wrap "Get a table containing all functions available on a peripheral.") ("minecraft:chest\_0") local chest\_b \= [peripheral.wrap](https://tweaked.cc/module/peripheral.html#v:wrap "Get a table containing all functions available on a peripheral.") ("minecraft:chest\_1") chest\_a.pushItems([peripheral.getName](https://tweaked.cc/module/peripheral.html#v:getName "Get the name of a peripheral wrapped with peripheral.wrap.") (chest\_b), 1) ### See also * **[`peripheral.getName`](https://tweaked.cc/module/peripheral.html#v:getName) ** Allows you to get the name of a [wrapped](https://tweaked.cc/module/peripheral.html#v:wrap) peripheral. [](https://tweaked.cc/generic_peripheral/inventory.html#v:pullItems) pullItems(fromName, fromSlot \[, limit \[, toSlot\]\])[Source](https://github.com/cc-tweaked/CC-Tweaked/blob/8bdea64474143a081ac8689c225bcc17bd8be213/projects/common/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/AbstractInventoryMethods.java#L178) Pull items from a connected inventory into this one. This allows you to transfer items between inventories _on the same wired network_. Both this and the source inventory must attached to wired modems which are connected via a cable. ### Parameters 1. fromName [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The name of the peripheral/inventory to pull from. This is the string given to [`peripheral.wrap`](https://tweaked.cc/module/peripheral.html#v:wrap) , and displayed by the wired modem. 2. fromSlot `number` The slot in the source inventory to move items from. 3. limit? `number` The maximum number of items to move. Defaults to the current stack limit. 4. toSlot? `number` The slot in current inventory to move to. If not given, the item will be inserted into any slot. ### Returns 1. `number` The number of transferred items. ### Throws * If the peripheral to transfer to doesn't exist or isn't an inventory. * If either source or destination slot is out of range. ### Usage * Wrap two chests, and push an item from one to another. Run ᐅ local chest\_a \= [peripheral.wrap](https://tweaked.cc/module/peripheral.html#v:wrap "Get a table containing all functions available on a peripheral.") ("minecraft:chest\_0") local chest\_b \= [peripheral.wrap](https://tweaked.cc/module/peripheral.html#v:wrap "Get a table containing all functions available on a peripheral.") ("minecraft:chest\_1") chest\_a.pullItems([peripheral.getName](https://tweaked.cc/module/peripheral.html#v:getName "Get the name of a peripheral wrapped with peripheral.wrap.") (chest\_b), 1) ### See also * **[`peripheral.getName`](https://tweaked.cc/module/peripheral.html#v:getName) ** Allows you to get the name of a [wrapped](https://tweaked.cc/module/peripheral.html#v:wrap) peripheral. --- # mouse_click mouse\_click ============ This event is fired when the terminal is clicked with a mouse. This event is only fired on advanced computers (including advanced turtles and pocket computers). Return values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. `number`: The mouse button that was clicked. 3. `number`: The X-coordinate of the click. 4. `number`: The Y-coordinate of the click. Mouse buttons ------------- Several mouse events ([`mouse_click`](https://tweaked.cc/event/mouse_click.html) , [`mouse_up`](https://tweaked.cc/event/mouse_up.html) , [`mouse_scroll`](https://tweaked.cc/event/mouse_scroll.html) ) contain a "mouse button" code. This takes a numerical value depending on which button on your mouse was last pressed when this event occurred. | Button Code | Mouse Button | | --- | --- | | 1 | Left button | | 2 | Right button | | 3 | Middle button | Example ------- Print the button and the coordinates whenever the mouse is clicked. Run ᐅ while true do local event, button, x, y \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("mouse\_click") print(("The mouse button %s was pressed at %d, %d"):format(button, x, y)) end --- # mouse_drag mouse\_drag =========== This event is fired every time the mouse is moved while a mouse button is being held. Return values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. `number`: The [mouse button](https://tweaked.cc/event/mouse_click.html#Mouse_buttons) that is being pressed. 3. `number`: The X-coordinate of the mouse. 4. `number`: The Y-coordinate of the mouse. Example ------- Print the button and the coordinates whenever the mouse is dragged. Run ᐅ while true do local event, button, x, y \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("mouse\_drag") print(("The mouse button %s was dragged at %d, %d"):format(button, x, y)) end ### See also * **[`mouse_click`](https://tweaked.cc/event/mouse_click.html) ** For when a mouse button is initially pressed. --- # mouse_scroll mouse\_scroll ============= This event is fired when a mouse wheel is scrolled in the terminal. Return values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. `number`: The direction of the scroll. (-1 = up, 1 = down) 3. `number`: The X-coordinate of the mouse when scrolling. 4. `number`: The Y-coordinate of the mouse when scrolling. Example ------- Prints the direction of each scroll, and the position of the mouse at the time. Run ᐅ while true do local event, dir, x, y \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("mouse\_scroll") print(("The mouse was scrolled in direction %s at %d, %d"):format(dir, x, y)) end --- # mouse_up mouse\_up ========= This event is fired when a mouse button is released or a held mouse leaves the computer's terminal. Return values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. `number`: The [mouse button](https://tweaked.cc/event/mouse_click.html#Mouse_buttons) that was released. 3. `number`: The X-coordinate of the mouse. 4. `number`: The Y-coordinate of the mouse. Example ------- Prints the coordinates and button number whenever the mouse is released. Run ᐅ while true do local event, button, x, y \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("mouse\_up") print(("The mouse button %s was released at %d, %d"):format(button, x, y)) end --- # paste paste ===== The [`paste`](https://tweaked.cc/event/paste.html) event is fired when text is pasted into the computer through Ctrl-V (or ⌘V on Mac). Return values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) The text that was pasted. Example ------- Prints pasted text: Run ᐅ while true do local event, text \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("paste") print('"' .. text .. '" was pasted') end --- # peripheral peripheral ========== The [`peripheral`](https://tweaked.cc/module/peripheral.html) event is fired when a peripheral is attached on a side or to a modem. Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The side the peripheral was attached to. Example ------- Prints a message when a peripheral is attached: Run ᐅ while true do local event, side \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("peripheral") print("A peripheral was attached on side " .. side) end ### See also * **[`peripheral_detach`](https://tweaked.cc/event/peripheral_detach.html) ** For the event fired when a peripheral is detached. --- # speaker_audio_empty speaker\_audio\_empty ===================== Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The name of the speaker which is available to play more audio. Example ------- This uses [`io.lines`](https://tweaked.cc/module/io.html#v:lines) to read audio data in blocks of 16KiB from "example\_song.dfpwm", and then attempts to play it using [`speaker.playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) . If the speaker's buffer is full, it waits for an event and tries again. Run ᐅ local [dfpwm](https://tweaked.cc/library/cc.audio.dfpwm.html "Convert between streams of DFPWM audio data and a list of amplitudes.") \= require("cc.audio.dfpwm") local speaker \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("speaker") local decoder \= [dfpwm.make\_decoder](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_decoder "Create a new decoder for converting DFPWM into PCM audio data.") () for chunk in [io.lines](https://tweaked.cc/module/io.html#v:lines "Opens the given file name in read mode and returns an iterator that, each time it is called, returns a new line from the file.") ("data/example.dfpwm", 16 \* 1024) do local buffer \= decoder(chunk) while not speaker.playAudio(buffer) do [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("speaker\_audio\_empty") end end ### See also * **[`speaker.playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) ** To play audio using the speaker --- # setting_changed setting\_changed ================ The [`setting_changed`](https://tweaked.cc/event/setting_changed.html) event is fired when a setting is modified with the [`settings`](https://tweaked.cc/module/settings.html) API. Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The name of the setting that was changed. 3. `any`: The value the setting was set to. 4. `any`: The previous value of the setting. Example ------- [Update a setting](https://tweaked.cc/module/settings.html#v:set) , and then wait for the corresponding `setting_changed` event. Run ᐅ [settings.set](https://tweaked.cc/module/settings.html#v:set "Set the value of a setting.") ("my.setting", 123) print([os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("setting\_changed")) ### See also * **[`settings`](https://tweaked.cc/module/settings.html) ** --- # peripheral_detach peripheral\_detach ================== The [`peripheral_detach`](https://tweaked.cc/event/peripheral_detach.html) event is fired when a peripheral is detached from a side or from a modem. Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The side the peripheral was detached from. Example ------- Prints a message when a peripheral is detached: Run ᐅ while true do local event, side \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("peripheral\_detach") print("A peripheral was detached on side " .. side) end ### See also * **[`peripheral`](https://tweaked.cc/module/peripheral.html) ** For the event fired when a peripheral is attached. --- # redstone redstone ======== The [`redstone`](https://tweaked.cc/event/redstone.html) event is fired whenever any redstone inputs on the computer or [relay](https://tweaked.cc/peripheral/redstone_relay.html) change. Return values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. Example ------- Prints a message when a redstone input changes: Run ᐅ while true do [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("redstone") print("A redstone input has changed!") end See also -------- * [The `redstone` API on computers](https://tweaked.cc/module/redstone.html) * [The `redstone_relay` peripheral](https://tweaked.cc/peripheral/redstone_relay.html) --- # rednet_message rednet\_message =============== The [`rednet_message`](https://tweaked.cc/event/rednet_message.html) event is fired when a message is sent over Rednet. This event is usually handled by [`rednet.receive`](https://tweaked.cc/module/rednet.html#v:receive) , but it can also be pulled manually. [`rednet_message`](https://tweaked.cc/event/rednet_message.html) events are sent by [`rednet.run`](https://tweaked.cc/module/rednet.html#v:run) in the top-level coroutine in response to [`modem_message`](https://tweaked.cc/event/modem_message.html) events. A [`rednet_message`](https://tweaked.cc/event/rednet_message.html) event is always preceded by a [`modem_message`](https://tweaked.cc/event/modem_message.html) event. They are generated inside CraftOS rather than being sent by the ComputerCraft machine. Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. `number`: The ID of the sending computer. 3. `any`: The message sent. 4. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) |`nil`: The protocol of the message, if provided. Example ------- Prints a message when one is sent: Run ᐅ while true do local event, sender, message, protocol \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("rednet\_message") if protocol ~= nil then print("Received message from " .. sender .. " with protocol " .. protocol .. " and message " .. tostring(message)) else print("Received message from " .. sender .. " with message " .. tostring(message)) end end ### See also * **[`modem_message`](https://tweaked.cc/event/modem_message.html) ** For raw modem messages sent outside of Rednet. * **[`rednet.receive`](https://tweaked.cc/module/rednet.html#v:receive) ** To wait for a Rednet message with an optional timeout and protocol filter. --- # task_complete task\_complete ============== The [`task_complete`](https://tweaked.cc/event/task_complete.html) event is fired when an asynchronous task completes. This is usually handled inside the function call that queued the task; however, functions such as [`commands.execAsync`](https://tweaked.cc/module/commands.html#v:execAsync) return immediately so the user can wait for completion. Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. `number`: The ID of the task that completed. 3. `boolean`: Whether the command succeeded. 4. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : If the command failed, an error message explaining the failure. (This is not present if the command succeeded.) 5. …: Any parameters returned from the command. Example ------- Prints the results of an asynchronous command: Run ᐅ local taskID \= [commands.execAsync](https://tweaked.cc/module/commands.html#v:execAsync "Asynchronously execute a command.") ("say Hello") local event repeat event \= {[os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("task\_complete")} until event\[2\] \== taskID if event\[3\] \== true then print("Task " .. event\[2\] .. " succeeded:", table.unpack(event, 4)) else print("Task " .. event\[2\] .. " failed: " .. event\[4\]) end ### See also * **[`commands.execAsync`](https://tweaked.cc/module/commands.html#v:execAsync) ** To run a command which fires a task\_complete event. --- # term_resize term\_resize ============ The [`term_resize`](https://tweaked.cc/event/term_resize.html) event is fired when the main terminal is resized. For instance: * When a the tab bar is shown or hidden in [`multishell`](https://tweaked.cc/module/multishell.html) . * When the terminal is redirected to a monitor via the "monitor" program and the monitor is resized. When this event fires, some parts of the terminal may have been moved or deleted. Simple terminal programs (those not using [`term.setCursorPos`](https://tweaked.cc/module/term.html#v:setCursorPos) ) can ignore this event, but more complex GUI programs should redraw the entire screen. Return values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. Example ------- Print a message each time the terminal is resized. Run ᐅ while true do [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("term\_resize") local w, h \= [term.getSize](https://tweaked.cc/module/term.html#v:getSize "Get the size of the terminal.") () print("The term was resized to (" .. w .. ", " .. h .. ")") end --- # terminate terminate ========= The [`terminate`](https://tweaked.cc/event/terminate.html) event is fired when Ctrl-T is held down. This event is normally handled by [`os.pullEvent`](https://tweaked.cc/module/os.html#v:pullEvent) , and will not be returned. However, [`os.pullEventRaw`](https://tweaked.cc/module/os.html#v:pullEventRaw) will return this event when fired. [`terminate`](https://tweaked.cc/event/terminate.html) will be sent even when a filter is provided to [`os.pullEventRaw`](https://tweaked.cc/module/os.html#v:pullEventRaw) . When using [`os.pullEventRaw`](https://tweaked.cc/module/os.html#v:pullEventRaw) with a filter, make sure to check that the event is not [`terminate`](https://tweaked.cc/event/terminate.html) . Return values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. Example ------- Prints a message when Ctrl-T is held: Run ᐅ while true do local event \= [os.pullEventRaw](https://tweaked.cc/module/os.html#v:pullEventRaw "Pause execution of the current thread and waits for events, including the terminate event.") ("terminate") if event \== "terminate" then print("Terminate requested!") end end Exits when Ctrl-T is held: Run ᐅ while true do [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") () end --- # turtle_inventory turtle\_inventory ================= The [`turtle_inventory`](https://tweaked.cc/event/turtle_inventory.html) event is fired when a turtle's inventory is changed. Return values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. Example ------- Prints a message when the inventory is changed: Run ᐅ while true do [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("turtle\_inventory") print("The inventory was changed.") end --- # timer timer ===== The [`timer`](https://tweaked.cc/event/timer.html) event is fired when a timer started with [`os.startTimer`](https://tweaked.cc/module/os.html#v:startTimer) completes. Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. `number`: The ID of the timer that finished. Example ------- Start and wait for a timer to finish. Run ᐅ local timer\_id \= [os.startTimer](https://tweaked.cc/module/os.html#v:startTimer "Starts a timer that will run for the specified number of seconds.") (2) local event, id repeat event, id \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("timer") until id \== timer\_id print("Timer with ID " .. id .. " was fired") ### See also * **[`os.startTimer`](https://tweaked.cc/module/os.html#v:startTimer) ** To start a timer. --- # websocket_closed websocket\_closed ================= The [`websocket_closed`](https://tweaked.cc/event/websocket_closed.html) event is fired when an open WebSocket connection is closed. Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The URL of the WebSocket that was closed. 3. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) |`nil`: The [server-provided reason](https://www.rfc-editor.org/rfc/rfc6455.html#section-7.1.6 "The WebSocket Connection Close Reason, RFC 6455") the websocket was closed. This will be `nil` if the connection was closed abnormally. 4. `number`|`nil`: The [connection close code](https://www.rfc-editor.org/rfc/rfc6455.html#section-7.1.5 "The WebSocket Connection Close Code, RFC 6455") , indicating why the socket was closed. This will be `nil` if the connection was closed abnormally. Example ------- Prints a message when a WebSocket is closed (this may take a minute): Run ᐅ local myURL \= "wss://example.tweaked.cc/echo" local ws \= [http.websocket](https://tweaked.cc/module/http.html#v:websocket "Open a websocket.") (myURL) local event, url repeat event, url \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("websocket\_closed") until url \== myURL print("The WebSocket at " .. url .. " was closed.") --- # websocket_failure websocket\_failure ================== The [`websocket_failure`](https://tweaked.cc/event/websocket_failure.html) event is fired when a WebSocket connection request fails. This event is normally handled inside [`http.websocket`](https://tweaked.cc/module/http.html#v:websocket) , but it can still be seen when using [`http.websocketAsync`](https://tweaked.cc/module/http.html#v:websocketAsync) . Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The URL of the site requested. 3. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : An error describing the failure. Example ------- Prints an error why the website cannot be contacted: Run ᐅ local myURL \= "wss://example.tweaked.cc/not-a-websocket" [http.websocketAsync](https://tweaked.cc/module/http.html#v:websocketAsync "Asynchronously open a websocket.") (myURL) local event, url, err repeat event, url, err \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("websocket\_failure") until url \== myURL print("The URL " .. url .. " could not be reached: " .. err) ### See also * **[`http.websocketAsync`](https://tweaked.cc/module/http.html#v:websocketAsync) ** To send an HTTP request. --- # websocket_success websocket\_success ================== The [`websocket_success`](https://tweaked.cc/event/websocket_success.html) event is fired when a WebSocket connection request returns successfully. This event is normally handled inside [`http.websocket`](https://tweaked.cc/module/http.html#v:websocket) , but it can still be seen when using [`http.websocketAsync`](https://tweaked.cc/module/http.html#v:websocketAsync) . Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The URL of the site. 3. [`http.Websocket`](https://tweaked.cc/module/http.html#ty:Websocket) : The handle for the WebSocket. Example ------- Prints the content of a website (this may fail if the request fails): Run ᐅ local myURL \= "wss://example.tweaked.cc/echo" [http.websocketAsync](https://tweaked.cc/module/http.html#v:websocketAsync "Asynchronously open a websocket.") (myURL) local event, url, handle repeat event, url, handle \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("websocket\_success") until url \== myURL print("Connected to " .. url) handle.send("Hello!") print(handle.receive()) handle.close() ### See also * **[`http.websocketAsync`](https://tweaked.cc/module/http.html#v:websocketAsync) ** To open a WebSocket asynchronously. --- # websocket_message websocket\_message ================== The [`websocket_message`](https://tweaked.cc/event/websocket_message.html) event is fired when a message is received on an open WebSocket connection. This event is normally handled by [`http.Websocket.receive`](https://tweaked.cc/module/http.html#ty:Websocket:receive) , but it can also be pulled manually. Return Values ------------- 1. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The event name. 2. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The URL of the WebSocket. 3. [`string`](https://www.lua.org/manual/5.1/manual.html#5.4) : The contents of the message. 4. `boolean`: Whether this is a binary message. Example ------- Prints a message sent by a WebSocket: Run ᐅ local myURL \= "wss://example.tweaked.cc/echo" local ws \= [http.websocket](https://tweaked.cc/module/http.html#v:websocket "Open a websocket.") (myURL) ws.send("Hello!") local event, url, message repeat event, url, message \= [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("websocket\_message") until url \== myURL print("Received message from " .. url .. " with contents " .. message) ws.close() --- # Setting up GPS Setting up GPS ============== The [`gps`](https://tweaked.cc/module/gps.html) API allows a computer to find its current position using a [wireless modem](https://tweaked.cc/peripheral/modem.html) . This works by communicating with other computers (called _GPS hosts_) that already know their position, finding the distance to those computers (with [`modem_message`](https://tweaked.cc/event/modem_message.html) ), and using that to derive its position from theirs (with a process known as [trilateration](https://en.wikipedia.org/wiki/Trilateration) . In order for this to work, we need our GPS hosts set up in a specific pattern, each one differing in position on at least one axis. This guide takes you through the process of setting up a _constellation_ of GPS hosts, and using them to determine a computer's position. Prerequisites ------------- You will need: * Four computers. * Four Ender Modems. Normal Wireless Modems may be be used, but the range of the GPS constellation will be severely limited. Additionally, you will need another computer and a wireless modem, in order to test that GPS works! Picking an area --------------- First, choose a place to build your GPS constellation. This should be a 10x10x10 cube, though you can make this smaller if needed. The larger a constellation is, the more accurate it is over large distances, but even a 5x5x5 constellation should serve a several thousand block radius. Every computer must be loaded in order for other computers to use GPS, so it is recommended to build your GPS constellation in a single chunk that will always be loaded. You may want to choose an area in an already chunk-loaded part of your base, or in the [spawn chunks](https://minecraft.wiki/w/Spawn_chunk "Spawn Chunk — Minecraft Wiki") . You can use F3+G to view the chunk boundaries if needed. This is the example area we will be building our constellation in: ![An empty 10x10x10 area, with the axis marked with smooth stone.](https://tweaked.cc/gps-constellation-area-8f979d93.png) Building the constellation -------------------------- 1. Place down your first computer in a corner of your area, and put a modem on top. 2. Head to the two adjacent corners of your area, place down another two computers and put a modem on top of each. 3. Pillar up above the first computer to the top of your cube, and place the final computer. Place a modem on the computer. You should now have something like this: ![The same area as before, but with a computer in each corner.](https://tweaked.cc/gps-constellation-built-171b5f8f.png) Configuring the constellation ----------------------------- Now that the structure of your constellation is built, we need to configure each host in it. 1. Press F3 to open Minecraft's debug screen. 2. Go back to the first computer and look at it. On the right of the screen about halfway down you should see an entry labelled `Targeted Block`, the numbers correspond to the position of the block that you are looking at. Write these numbers down. 3. Open the computer's UI, and run `edit startup.lua`. 4. Type the following code into the file, replacing `x`, `y`, and `z` with the coordinates you just wrote down. Run ᐅ [shell.run](https://tweaked.cc/module/shell.html#v:run "Run a program with the supplied arguments.") ("gps", "host", x, y, z) 5. Save the file, and then reboot the computer (hold Ctrl+R or run the `reboot` program) to run the startup program. Repeat this process for the other three computers. Congratulations, your constellation is now fully set up! You can test it by placing another computer close by, placing a wireless modem on it, and running the `gps locate` program (or calling the [`gps.locate`](https://tweaked.cc/module/gps.html#v:locate) function). --- # Playing audio with speakers Playing audio with speakers =========================== CC: Tweaked's speaker peripheral provides a powerful way to play any audio you like with the [`speaker.playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) method. However, for people unfamiliar with digital audio, it's not the most intuitive thing to use. This guide provides an introduction to digital audio, demonstrates how to play music with CC: Tweaked's speakers, and then briefly discusses the more complex topic of audio processing. A short introduction to digital audio ------------------------------------- When sound is recorded it is captured as an analogue signal, effectively the electrical version of a sound wave. However, this signal is continuous, and so can't be used directly by a computer. Instead, we measure (or _sample_) the amplitude of the wave many times a second and then _quantise_ that amplitude, rounding it to the nearest representable value. This representation of sound - a long, uniformly sampled list of amplitudes is referred to as [Pulse-code Modulation](https://en.wikipedia.org/wiki/Pulse-code_modulation "Pulse-code Modulation - Wikipedia") (PCM). PCM can be thought of as the "standard" audio format, as it's incredibly easy to work with. For instance, to mix two pieces of audio together, you can just add samples from the two tracks together and take the average. CC: Tweaked's speakers also work with PCM audio. It plays back 48,000 samples a second, where each sample is an integer between -128 and 127. This is more commonly referred to as 48kHz and an 8-bit resolution. Let's now look at a quick example. We're going to generate a [Sine Wave](https://en.wikipedia.org/wiki/Sine_wave "Sine wave - Wikipedia") at 220Hz, which sounds like a low monotonous hum. First we wrap our speaker peripheral, and then we fill a table (also referred to as a _buffer_) with 128×1024 samples - this is the maximum number of samples a speaker can accept in one go. In order to fill this buffer, we need to do a little maths. We want to play 220 sine waves each second, where each sine wave completes a full oscillation in 2π "units". This means one seconds worth of audio is 2×π×220 "units" long. We then need to split this into 48k samples, basically meaning for each sample we move 2×π×220/48k "along" the sine curve. Run ᐅ local speaker \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("speaker") local buffer \= {} local t, dt \= 0, 2 \* math.pi \* 220 / 48000 for i \= 1, 128 \* 1024 do buffer\[i\] \= math.floor(math.sin(t) \* 127) t \= (t + dt) % (math.pi \* 2) end speaker.playAudio(buffer) Streaming audio --------------- You might notice that the above snippet only generates a short bit of audio - a little over 2.7 seconds. While we could try increasing the number of loop iterations, we'll get an error when we try to play it through the speaker: the sound buffer is too large for it to handle. Our 2.7 seconds of audio is stored in a table with over 130 _thousand_ elements. If we wanted to play a full minute of sine waves (and why wouldn't you?), you'd need a table with almost 3 _million_. Suddenly you find these numbers adding up very quickly, and these tables take up more and more memory. Instead of building our entire song (well, sine wave) in one go, we can produce it in small batches, each of which get passed off to [`speaker.playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) when the time is right. This allows us to build a _stream_ of audio, where we read chunks of audio one at a time (either from a file or a tone generator like above), do some optional processing to each one, and then play them. Let's adapt our example from above to do that instead. Run ᐅ local speaker \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("speaker") local t, dt \= 0, 2 \* math.pi \* 220 / 48000 while true do local buffer \= {} for i \= 1, 16 \* 1024 \* 8 do buffer\[i\] \= math.floor(math.sin(t) \* 127) t \= (t + dt) % (math.pi \* 2) end while not speaker.playAudio(buffer) do [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("speaker\_audio\_empty") end end It looks pretty similar to before, aside from we've wrapped the generation and playing code in a while loop, and added a rather odd loop with [`speaker.playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) and [`os.pullEvent`](https://tweaked.cc/module/os.html#v:pullEvent) . Let's talk about this loop, why do we need to keep calling [`speaker.playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) ? Remember that what we're trying to do here is avoid keeping too much audio in memory at once. However, if we're generating audio quicker than the speakers can play it, we're not helping at all - all this audio is still hanging around waiting to be played! In order to avoid this, the speaker rejects any new chunks of audio if its backlog is too large. When this happens, [`speaker.playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) returns false. Once enough audio has played, and the backlog has been reduced, a [`speaker_audio_empty`](https://tweaked.cc/event/speaker_audio_empty.html) event is queued, and we can try to play our chunk once more. Storing audio ------------- PCM is a fantastic way of representing audio when we want to manipulate it, but it's not very efficient when we want to store it to disk. Compare the size of a WAV file (which uses PCM) to an equivalent MP3, it's often 5 times the size. Instead, we store audio in special formats (or _codecs_) and then convert them to PCM when we need to do processing on them. Modern audio codecs use some incredibly impressive techniques to compress the audio as much as possible while preserving sound quality. However, due to CC: Tweaked's limited processing power, it's not really possible to use these from your computer. Instead, we need something much simpler. DFPWM (Dynamic Filter Pulse Width Modulation) is the de facto standard audio format of the ComputerCraft (and OpenComputers) world. Originally popularised by the add-on mod [Computronics](https://github.com/Vexatos/Computronics/ "Computronics on GitHub") , CC:T now has built-in support for it with the [`cc.audio.dfpwm`](https://tweaked.cc/library/cc.audio.dfpwm.html) module. This allows you to read DFPWM files from disk, decode them to PCM, and then play them using the speaker. Let's dive in with an example, and we'll explain things afterwards: Run ᐅ local [dfpwm](https://tweaked.cc/library/cc.audio.dfpwm.html "Convert between streams of DFPWM audio data and a list of amplitudes.") \= require("cc.audio.dfpwm") local speaker \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("speaker") local decoder \= [dfpwm.make\_decoder](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_decoder "Create a new decoder for converting DFPWM into PCM audio data.") () for chunk in [io.lines](https://tweaked.cc/module/io.html#v:lines "Opens the given file name in read mode and returns an iterator that, each time it is called, returns a new line from the file.") ("data/example.dfpwm", 16 \* 1024) do local buffer \= decoder(chunk) while not speaker.playAudio(buffer) do [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("speaker\_audio\_empty") end end Once again, we see the [`speaker.playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) /[`speaker_audio_empty`](https://tweaked.cc/event/speaker_audio_empty.html) loop. However, the rest of the program is a little different. First, we require the DFPWM module and call [`cc.audio.dfpwm.make_decoder`](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_decoder) to construct a new decoder. This decoder accepts blocks of DFPWM data and converts it to a list of 8-bit amplitudes, which we can then play with our speaker. As mentioned above, [`speaker.playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) accepts at most 128×1024 samples in one go. DFPWM uses a single bit for each sample, which means we want to process our audio in chunks of 16×1024 bytes (16KiB). In order to do this, we use [`io.lines`](https://tweaked.cc/module/io.html#v:lines) , which provides a nice way to loop over chunks of a file. You can of course just use [`fs.open`](https://tweaked.cc/module/fs.html#v:open) and [`fs.ReadHandle.read`](https://tweaked.cc/module/fs.html#ty:ReadHandle:read) if you prefer. Processing audio ---------------- As mentioned near the beginning of this guide, PCM audio is pretty easy to work with as it's just a list of amplitudes. You can mix together samples from different streams by adding their amplitudes, change the rate of playback by removing samples, etc... Let's put together a small demonstration here. We're going to add a small delay effect to the song above, so that you hear a faint echo a second and a half later. In order to do this, we'll follow a format similar to the previous example, decoding the audio and then playing it. However, we'll also add some new logic between those two steps, which loops over every sample in our chunk of audio, and adds the sample from 1.5 seconds ago to it. For this, we'll need to keep track of the last 72k samples - exactly 1.5 seconds worth of audio. We can do this using a [Ring Buffer](https://en.wikipedia.org/wiki/Circular_buffer "Circular buffer - Wikipedia") , which helps makes things a little more efficient. Run ᐅ local [dfpwm](https://tweaked.cc/library/cc.audio.dfpwm.html "Convert between streams of DFPWM audio data and a list of amplitudes.") \= require("cc.audio.dfpwm") local speaker \= [peripheral.find](https://tweaked.cc/module/peripheral.html#v:find "Find all peripherals of a specific type, and return the wrapped peripherals.") ("speaker") \-- Speakers play at 48kHz, so 1.5 seconds is 72k samples. We first fill our buffer \-- with 0s, as there's nothing to echo at the start of the track! local samples\_i, samples\_n \= 1, 48000 \* 1.5 local samples \= {} for i \= 1, samples\_n do samples\[i\] \= 0 end local decoder \= [dfpwm.make\_decoder](https://tweaked.cc/library/cc.audio.dfpwm.html#v:make_decoder "Create a new decoder for converting DFPWM into PCM audio data.") () for chunk in [io.lines](https://tweaked.cc/module/io.html#v:lines "Opens the given file name in read mode and returns an iterator that, each time it is called, returns a new line from the file.") ("data/example.dfpwm", 16 \* 1024) do local buffer \= decoder(chunk) for i \= 1, #buffer do local original\_value \= buffer\[i\] \-- Replace this sample with its current amplitude plus the amplitude from 1.5 seconds ago. \-- We scale both to ensure the resulting value is still between -128 and 127. buffer\[i\] \= original\_value \* 0.6 + samples\[samples\_i\] \* 0.4 \-- Now store the current sample, and move the "head" of our ring buffer forward one place. samples\[samples\_i\] \= original\_value samples\_i \= samples\_i + 1 if samples\_i \> samples\_n then samples\_i \= 1 end end while not speaker.playAudio(buffer) do [os.pullEvent](https://tweaked.cc/module/os.html#v:pullEvent "Pause execution of the current thread and waits for any events matching filter.") ("speaker\_audio\_empty") end \-- The audio processing above can be quite slow and preparing the first batch of audio \-- may timeout the computer. We sleep to avoid this. \-- There's definitely better ways of handling this - this is just an example! sleep(0.05) end ##### 🛈 Confused? Don't worry if you don't understand this example. It's quite advanced, and does use some ideas that this guide doesn't cover. That said, don't be afraid to ask [the community for help](https://tweaked.cc/#community) . It's worth noting that the examples of audio processing we've mentioned here are about manipulating the _amplitude_ of the wave. If you wanted to modify the _frequency_ (for instance, shifting the pitch), things get rather more complex. For this, you'd need to use the [Fast Fourier transform](https://en.wikipedia.org/wiki/Fast_Fourier_transform "Fast Fourier transform - Wikipedia") to convert the stream of amplitudes to frequencies, process those, and then convert them back to amplitudes. This is, I'm afraid, left as an exercise to the reader. ### See also * **[`speaker.playAudio`](https://tweaked.cc/peripheral/speaker.html#v:playAudio) ** Play PCM audio using a speaker. * **[`cc.audio.dfpwm`](https://tweaked.cc/library/cc.audio.dfpwm.html) ** Provides utilities for encoding and decoding DFPWM files. --- # Reusing code with require Reusing code with require ========================= A library is a collection of useful functions and other definitions which is stored separately to your main program. You might want to create a library because you have some functions which are used in multiple programs, or just to split your program into multiple more modular files. Let's say we want to create a small library to make working with the [terminal](https://tweaked.cc/module/term.html) a little easier. We'll provide two functions: `reset`, which clears the terminal and sets the cursor to (1, 1), and `write_center`, which prints some text in the middle of the screen. Start off by creating a file called `more_term.lua`: Run ᐅ local function reset() [term.clear](https://tweaked.cc/module/term.html#v:clear "Clears the terminal, filling it with the current background colour.") () [term.setCursorPos](https://tweaked.cc/module/term.html#v:setCursorPos "Set the position of the cursor.") (1, 1) end local function write\_center(text) local x, y \= [term.getCursorPos](https://tweaked.cc/module/term.html#v:getCursorPos "Get the position of the cursor.") () local width, height \= [term.getSize](https://tweaked.cc/module/term.html#v:getSize "Get the size of the terminal.") () [term.setCursorPos](https://tweaked.cc/module/term.html#v:setCursorPos "Set the position of the cursor.") (math.floor((width \- #text) / 2) + 1, y) [term.write](https://tweaked.cc/module/term.html#v:write "Write text at the current cursor position, moving the cursor to the end of the text.") (text) end return { reset \= reset, write\_center \= write\_center } Now, what's going on here? We define our two functions as one might expect, and then at the bottom return a table with the two functions. When we require this library, this table is what is returned. With that, we can then call the original functions. Now create a new file, with the following: Run ᐅ local more\_term \= require("more\_term") more\_term.reset() more\_term.write\_center("Hello, world!") When run, this'll clear the screen and print some text in the middle of the first line. require in depth ---------------- While the previous section is a good introduction to how [`require`](https://www.lua.org/manual/5.1/manual.html#pdf-require) operates, there are a couple of remaining points which are worth mentioning for more advanced usage. ### Libraries can return anything In our above example, we return a table containing the functions we want to expose. However, it's worth pointing out that you can return ''anything'' from your library - a table, a function or even just a string! [`require`](https://www.lua.org/manual/5.1/manual.html#pdf-require) treats them all the same, and just returns whatever your library provides. ### Module resolution and the package path In the above examples, we defined our library in a file, and [`require`](https://www.lua.org/manual/5.1/manual.html#pdf-require) read from it. While this is what you'll do most of the time, it is possible to make [`require`](https://www.lua.org/manual/5.1/manual.html#pdf-require) look elsewhere for your library, such as downloading from a website or loading from an in-memory library store. As a result, the _module name_ you pass to [`require`](https://www.lua.org/manual/5.1/manual.html#pdf-require) doesn't correspond to a file path. One common mistake is to load code from a sub-directory using `require("folder/library")` or even `require("folder/library.lua")`, neither of which will do quite what you expect. When loading libraries (also referred to as _modules_) from files, [`require`](https://www.lua.org/manual/5.1/manual.html#pdf-require) searches along the [_module path_](https://www.lua.org/manual/5.1/manual.html#pdf-package.path) . By default, this looks something like: * `?.lua` * `?/init.lua` * `/rom/modules/main/?.lua` * etc... When you call `require("my_library")`, [`require`](https://www.lua.org/manual/5.1/manual.html#pdf-require) replaces the `?` in each element of the path with your module name, and checks if the file exists. In this case, we'd look for `my_library.lua`, `my_library/init.lua`, `/rom/modules/main/my_library.lua` and so on. Note that this works _relative to the current program_, so if your program is actually called `folder/program`, then we'll look for `folder/my_library.lua`, etc... One other caveat is loading libraries from sub-directories. For instance, say we have a file `my/fancy/library.lua`. This can be loaded by using `require("my.fancy.library")` - the '.'s are replaced with '/' before we start looking for the library. External links -------------- There are several external resources which go into require in a little more detail: * The [Lua Module tutorial](http://lua-users.org/wiki/ModulesTutorial) on the Lua wiki. * [Lua's manual section on `require`](https://www.lua.org/manual/5.1/manual.html#pdf-require) . --- # Block details Block details ============= Several functions in CC: Tweaked, such as [`turtle.inspect`](https://tweaked.cc/module/turtle.html#v:inspect) and [`commands.getBlockInfo`](https://tweaked.cc/module/commands.html#v:getBlockInfo) provide a way to get information about a block in the world. This page details information about blocks that CC: Tweaked may return. Basic information ----------------- Block information will _always_ contain: * `name: string`: The namespaced ID for this block, e.g. `minecraft:dirt`. See [the Minecraft wiki](https://minecraft.wiki/w/Java_Edition_data_values#Blocks "Java Edition data values on the Minecraft Wiki") for a list of vanilla block IDs. * `state: { [string] = any}`: A table containing the block state of the block. ### Example A fully hydrated block of farmland: { name \= "minecraft:farmland", state \= { moisture \= 7 } } An extended piston, facing upwards: { name \= "minecraft:piston", state \= { facing \= "up", extended \= true } } Block tags ---------- The [tags](https://minecraft.wiki/w/Block_tag_%28Java_Edition%29 "Block tags on the Minecraft Wiki") a block has. * `tags: { [string] = boolean }`: The set of tags for this block. This is a mapping of tag name to `true`. While the representation of tags is a little more complicated then a single list, this makes it very easy to check if a block has a certain tag: Run ᐅ \--- Check if the block in front of the turtle is a log. local function is\_log() local ok, block \= [turtle.inspect](https://tweaked.cc/module/turtle.html#v:inspect "Get information about the block in front of the turtle.") () return ok and block.tags\["minecraft:logs"\] end ### Example A fully hydrated block of farmland: { name \= "minecraft:farmland", state \= { ... }, tags \= { \["minecraft:mineable/shovel"\] \= true, } } Map colour ---------- The colour the block will appear on the map, if specified. * `mapColour?: number`: The colour of the block, as an RGB hex value. * `mapColor?: number`: The color of the block, as an RGB hex value. The map colour is just returned as a plain number (e.g. `9923917` for farmland). It can either be displayed in hex with [`string.format`](https://www.lua.org/manual/5.1/manual.html#pdf-string.format) , or converted to individual RGB values with [`colors.unpackRGB`](https://tweaked.cc/module/colors.html#v:unpackRGB) . ### Example A fully hydrated block of farmland: { name \= "minecraft:farmland", state \= { ... }, mapColour \= 9923917, mapColor \= 9923917, } ### Changes * **New in version 1.64** * **Changed in version 1.76:** Added block state. * **Changed in version 1.117.0:** Added map colour. --- # Incompatibilities between versions Incompatibilities between versions ================================== CC: Tweaked tries to remain as compatible between versions as possible, meaning most programs written for older versions of the mod should run fine on later versions. ##### ⚠ External peripherals While CC: Tweaked is relatively stable across versions, this may not be true for other mods which add their own peripherals. Older programs which interact with external blocks may not work on newer versions of the game. However, some changes to the underlying game, or CC: Tweaked's own internals may break some programs. This page serves as documentation for breaking changes and "gotchas" one should look out for between versions. [](https://tweaked.cc/reference/breaking_changes.html#cct-1.109) CC: Tweaked 1.109.0 to 1.109.3 ----------------------------------------------------------------------------------------------- * Update to Lua 5.2: * Support for Lua 5.0's pseudo-argument `arg` has been removed. You should always use `...` for varargs. * Environments are no longer baked into the runtime, and instead use the `_ENV` local or upvalue. [`getfenv`](https://www.lua.org/manual/5.1/manual.html#pdf-getfenv) /[`setfenv`](https://www.lua.org/manual/5.1/manual.html#pdf-setfenv) now only work on Lua functions with an `_ENV` upvalue. [`getfenv`](https://www.lua.org/manual/5.1/manual.html#pdf-getfenv) will return the global environment when called with other functions, and [`setfenv`](https://www.lua.org/manual/5.1/manual.html#pdf-setfenv) will have no effect. * [`load`](https://www.lua.org/manual/5.1/manual.html#pdf-load) /[`loadstring`](https://www.lua.org/manual/5.1/manual.html#pdf-loadstring) defaults to using the global environment (`_G`) rather than the current coroutine's environment. * Support for dumping functions ([`string.dump`](https://www.lua.org/manual/5.1/manual.html#pdf-string.dump) ) and loading binary chunks has been removed. * [`math.random`](https://www.lua.org/manual/5.1/manual.html#pdf-math.random) now uses Lua 5.4's random number generator. * File handles, HTTP requests and websockets now always use the original bytes rather than encoding/decoding to UTF-8. Files containing non-ASCII characters will be read back differently if using text mode. [](https://tweaked.cc/reference/breaking_changes.html#mc-1.13) Minecraft 1.13 ----------------------------------------------------------------------------- * The "key code" for [`key`](https://tweaked.cc/event/key.html) and [`key_up`](https://tweaked.cc/event/key_up.html) events has changed, due to Minecraft updating to LWJGL 3. Make sure you're using the constants provided by the [`keys`](https://tweaked.cc/module/keys.html) API, rather than hard-coding numerical values. Related to this change, the numpad enter key now has a different key code to the enter key. You may need to adjust your programs to handle both. (Note, the `keys.numpadEnter` constant was defined in pre-1.13 versions of CC, but the `keys.enter` constant was queued when the key was pressed) * Minecraft 1.13 removed the concept of item damage and block metadata (see ["The Flattening"](https://minecraft.wiki/w/Java_Edition_1.13/Flattening) ). As a result [`turtle.inspect`](https://tweaked.cc/module/turtle.html#v:inspect) no longer provides block metadata, and [`turtle.getItemDetail`](https://tweaked.cc/module/turtle.html#v:getItemDetail) no longer provides damage. * Block states (`turtle.inspect().state`) should provide all the same information as block metadata, but in a much more understandable format. * Item and block names now represent a unique item type. For instance, wool is split into 16 separate items (`minecraft:white_wool`, etc...) rather than a single `minecraft:wool` with each meta/damage value specifying the colour. * Custom ROMs are now provided using data packs rather than resource packs. This should mostly be a matter of renaming the "assets" folder to "data", and placing it in "datapacks", but there are a couple of other gotchas to look out for: * Data packs [impose some restrictions on file names](https://minecraft.wiki/w/Tutorials/Creating_a_data_pack#Legal_characters) . As a result, your programs and directories must all be lower case. * Due to how data packs are read by CC: Tweaked, you may need to use the `/reload` command to see changes to your pack show up on the computer. See [the example datapack](https://github.com/cc-tweaked/datapack-example "An example datapack for CC: Tweaked") for how to get started. * Turtles can now be waterlogged and move "through" water sources rather than breaking them. [](https://tweaked.cc/reference/breaking_changes.html#cc-1.88) CC: Tweaked 1.88.0 --------------------------------------------------------------------------------- * Unlabelled computers and turtles now keep their ID when broken, meaning that unlabelled computers/items do not stack. [](https://tweaked.cc/reference/breaking_changes.html#cc-1.80) ComputerCraft 1.80pr1 ------------------------------------------------------------------------------------ * Programs run via [`shell.run`](https://tweaked.cc/module/shell.html#v:run) are now started in their own isolated environment. This means globals set by programs will not be accessible outside of this program. * Programs containing `/` are looked up in the current directory and are no longer looked up on the path. For instance, you can no longer type `turtle/excavate` to run `/rom/programs/turtle/excavate.lua`. --- # The /computercraft command The /computercraft command ========================== CC: Tweaked provides a `/computercraft` command for server owners to manage running computers on a server. [](https://tweaked.cc/reference/computercraft_command.html#permissions) Permissions ----------------------------------------------------------------------------------- As the `/computercraft` command is mostly intended for debugging and administrative purposes, its sub-commands typically require you to have op (or similar). * All players have access to the [`queue`](https://tweaked.cc/reference/computercraft_command.html#queue "/computercraft queue") sub-command. * On a multi-player server, all other commands require op. * On a single-player world, the player can run the [`dump`](https://tweaked.cc/reference/computercraft_command.html#dump "/computercraft dump") , [`turn-on`](https://tweaked.cc/reference/computercraft_command.html#turn-on "/computercraft turn-on") /[`shutdown`](https://tweaked.cc/reference/computercraft_command.html#shutdown "/computercraft shutdown") , and [`track`](https://tweaked.cc/reference/computercraft_command.html#track "/computercraft track") sub-commands, even when cheats are not enabled. The [`tp`](https://tweaked.cc/reference/computercraft_command.html#tp "/computercraft tp") and [`view`](https://tweaked.cc/reference/computercraft_command.html#view "/computercraft view") commands require cheats. If a permission mod such as [LuckPerms](https://github.com/LuckPerms/LuckPerms/ "A permissions plugin for Minecraft servers.") is installed[1](https://tweaked.cc/reference/computercraft_command.html#fn-permission) , you can configure access to the individual sub-commands. Each sub-command creates a `computercraft.command.NAME` permission node to control which players can execute it. [](https://tweaked.cc/reference/computercraft_command.html#computer-selectors) Computer selectors ------------------------------------------------------------------------------------------------- Some commands (such as [`tp`](https://tweaked.cc/reference/computercraft_command.html#tp "/computercraft tp") or [`turn-on`](https://tweaked.cc/reference/computercraft_command.html#turn-on "/computercraft turn-on") ) target a specific computer, or a list of computers. To specify which computers to operate on, you must use "computer selectors". Computer selectors are similar to Minecraft's [entity target selectors](https://minecraft.wiki/w/Target_selectors "Target Selectors on the Minecraft wiki") , but targeting computers instead. They allow you to select one or more computers, based on a set of predicates. The following predicates are supported: * `id=`: Select computer(s) with a specific id. * `instance=`: Select the computer with the given instance id. * `family=`: Select computers based on their type. * `label=