Introduction

• What is CraftOS-PC?
• Downloading & Installing
• Getting Started
• Save Data Location
• Standards Mode
• Migrating from CCEmuX
• CraftOS-PC Mobile

New Features in CraftOS-PC

• Peripheral Emulation
• File System Mounting
• Screenshots & Recording
• Multiple Computers
• ComputerCraft Configuration
• Graphics Mode
• HTTP & WebSocket Server
• CC: Tweaked Features
• Auto-Updater
• Debugger
• Command-Line Flags
• Rendering Options
• Raw Mode
• VS Code Extension
• Plugin System
• CraftOS-PC Accelerated

Other Information

• CraftOS-PC Online
• CraftOS-PC Remote
• Latest Development Build
• Error Messages
• Report a Bug
• Privacy Policy
• Contact
• Changelog

API Reference

• CC: Tweaked Documentation
• Lua Reference
• CraftOS APIs (Old Wiki)

ComputerCraft Configuration

CraftOS-PC includes the same configuration options available in base ComputerCraft, plus some more to control the new features in CraftOS-PC. These options are global to all computers (except isColor).

Variables

These are the config variables available as of CraftOS-PC v2.5.2. Variables marked global.json only are not exported through the config API and must be edited manually.

• abortTimeout [17000]: Maximum time to wait for a program to yield before forcibly terminating
• checkUpdates [true]: Whether to check for updates at program start
• cliControlKeyMode [0] (global.json only): Sets the way CLI mode reads control keys
  • 0: Control/Alt keys are available with Home/End, and original keys can be pressed in combination with Shift
  • 1: Opposite of mode 0; Control/Alt are available with Shift+Home/End
  • 2: Control/Alt keys can be pressed with Esc, C/A
  • 3: Control/Alt keys can be pressed with Ctrl-C/Ctrl-\
  • 4: Disable Control/Alt key emulation
• clockSpeed [20]: Terminal refresh rate
• computerName [] (computer-local): Name of the computer (cannot be set with config API)
• computerWidth/computerHeight [51/19] (computer-local): Default size of the current computer in characters
• configReadOnly [false]: Whether the configuration settings should not be able to be changed inside CraftOS (if true, must be disabled from global.json)
• customCharScale [] (global.json only): Set this to change the default character scale
• customFontPath [] (global.json only): Set this to specify a custom font in BMP format (hdfont will use the built-in HD font)
• customFontScale [] (global.json only): When using a custom font (besides hdfont), set this to specify the scale divisor for the font (1 = 12x18, 2 = 6x9 (default), 3 = 4x6)
• debug_enable [false]: Whether to enable the debug API (removed as of CraftOS-PC v2.6)
• default_computer_settings []: A string with some default settings to set in the settings API
• defaultWidth/defaultHeight [51/19]: The default size of new terminal windows
• disable_lua51_features [false]: Whether to disable some Lua 5.1-only features in the BIOS
• dropFilePath [false]: If set, dropping a file on the window will paste its path rather than copying it into the computer
• extendMargins [false]: Whether to extend colored margins to the edges of the screen, independent of standards mode
• http_blacklist [local IPs]: An array of IP addresses or hostnames to block; this takes priority over the whitelist
• http_enable [true]: Whether to enable the http API
• http_max_download [16777216]: The maximum size of an HTTP response to accept, in bytes
• http_max_requests [16]: The maximum number of HTTP requests to make at a time
• http_max_upload [4194304]: The maximum size of an entire HTTP request, including POST data and headers, in bytes
• http_max_websocket_message [65535]: The maximum size of one WebSocket message, in bytes
• http_max_websockets [4]: The maximum number of open WebSocket connections to allow
• http_proxy_server/http_proxy_port []: Allows using a proxy for HTTP connections
• http_timeout [30000]: The amount of time to wait for an HTTP request/response before terminating, in milliseconds
• http_websocket_enabled [true]: Whether to enable WebSocket support in the http API
• http_whitelist ["*"]: An array of IP addresses or hostnames to allow; any not in the list will be blocked
• ignoreHotkeys [false]: Whether to ignore hotkeys such as F2, F3, F11
• initialComputer [0]: The computer to start when opening CraftOS-PC
• isColor [true] (computer-local): Whether the emulated computer is an Advanced Computer (color) or Standard Computer (no color)
• keepOpenOnShutdown [false]: Whether to leave computer windows open after the computer shuts down; it can be rebooted with Ctrl+R
• maximumFilesOpen [128]: Maximum number of files that can be open at once
• maxRecordingLength [15]: The maximum number of seconds that a recording will run until it auto-stops (note that longer time * higher framerate = longer write time = higher memory usage)
• maxOpenPorts [128]: The maximum number of ports (channels) that may be open on a single modem
• monitorsUseMouseEvents [false]: Whether monitors should send mouse_* events (v2.3.4 and below behavior)
• mount_mode [1]: Specifies security settings for mounting directories
  • none (0): Do not allow mounting directories
  • ro strict or ro_strict (1): Force all mounts to be read-only
  • ro (2): Mounts default to read-only if not explicitly specified
  • rw (3): Mounts default to read-write unless marked read-only (v2.1.2 and below behavior)
• mounter_blacklist ["/"] (global.json only): Paths to disallow mounting from, overriding the whitelist if deeper than its entry
• mounter_no_ask [] (global.json only): A list of paths to allow mounting without prompting, regardless of showMountPrompt
• mounter_whitelist [User directories] (global.json only): Paths to allow mounting from, overriding the blacklist if deeper than its entry
• mouse_move_throttle [-1]: The amount of throttling placed on the mouse_move event
  • Values >0 will only send mouse_move events no less than that number of milliseconds apart
  • 0 will disable throttling; mouse_move events will always be sent (could cause lag)
  • Values <0 will disable the mouse_move event entirely
• preferredHardwareDriver []: The preferred driver to use with the hardware renderer. Run CraftOS-PC from the console with -r to list the available drivers (after tror).
• recordingFPS [10]: The framerate of GIF recordings. This value should be a divisor of clockSpeed, as the actual framerate is determined by integer division of both values.
• romReadOnly [true] (global.json only): Whether the ROM is mounted as read-only (change this only if you know what you're doing!) - note that in v2.4 this is reset when launched for the first time after updating
• showMountPrompt [true] (global.json only): Whether to prompt the user when mounting a directory (change this only if you know what you're doing!)
• snapToSize [true]: Whether to automatically snap window size to the nearest character size, keeping margins normalized
• snooperEnabled [false]: Whether to send crash reports to the developer's server (see the privacy policy on how this data is handled)
• standardsMode [false]: Enables a few extra compatibility options, such as 50ms timing and colored margins (see Standards Mode)
• startFullscreen [false] (computer-local): Whether to start the computer in fullscreen mode
• useDFPWM [false]: Whether to convert audio played through playAudio to DFPWM first
• useHardwareRenderer [false]: Whether to use the GPU for hardware-accelerated rendering
• useVsync [false]: Whether to enable Vsync with the hardware renderer
• useWebP [false]: Whether to take screenshots and recordings in WebP format (uses less data, but recordings don't work on Discord)
• vanilla [false]: Whether to disable all CraftOS-PC-specific features

Changing variables

Configuration variables can be changed using the "config" shell command, the config API, or by editing the JSON files manually.

From the shell

The "config" program allows you to change configuration variables from the shell. It has three subcommands: "get", "set", and "list". The "get" command will print the current value of a variable, "set" will change the value of a variable, and "list" will list all of the variables and their values. For example, "config set http_enable false" will disable the http API and all programs that use the Internet.

From Lua

The config API is the Lua interface to the configuration. config.get(name) will return the value of a variable, and config.set(name, value) will set the value of a variable. To list the variables available, config.list() returns a table with the names of each configuration variable available, and config.getType(name) returns the type a variable expects as a string.

• any get(string name): Returns the value of a configuration variable.
  • name: The name of the variable
  • Returns: The value of the variable
• string|nil set(string name, any value): Sets the value of a configuration variable.
  • name: The name of the variable
  • value: The new value of the variable
  • Returns: A message indicating whether CraftOS-PC needs to restart to apply the changes, or nil.
• void add(string name, string value): Adds an entry to a table config variable.
  • name: The name of the config option
  • value: The entry to add
• void remove(string name, string value): Removes an entry from a table config variable.
  • name: The name of the config option
  • value: The entry to remove
• table list(): Returns a list of all configuration variable names.
• number getType(string name): Returns the type of a variable.
  • name: The name of the variable
  • Returns: 0 for boolean, 1 for string, 2 for number, 3 for table

Manually

The configuration is stored at config in the CraftOS-PC data directory. This folder contains a file named global.json that stores the configuration global to all computers; as well as one JSON file for each computer ID that stores local configuration variables. These JSON files can be edited manually to set the variables, but note that the config will not be reloaded until CraftOS-PC is fully quit (all computers closed) and relaunched. In addition, be aware that CraftOS-PC saves the configuration files when it quits, so you should only edit the files when all instances of CraftOS-PC are closed.