Getting started

This guide takes you from a clean installation to a Kotlin program running inside a Minecraft computer. The primary authoring path is the project-based client IDE; a small editor and compiler inside each computer provide an autonomous terminal workflow. Both produce the same verified Compukter executable format.

Requirements

The independently distributed Create addon is optional on Minecraft 1.21.1. To use it, install both the addon and Create 6.0.10 through 6.0.x on client and server. It supports kinetic devices, Stock Ticker logistics, and steam boiler monitoring.

Additional Sable and Propulsion integrations are available on Minecraft 1.21.1.

The mod is required on both the client and server. macOS and ARM builds are not part of the current published artifacts.

Install Compukters

1. Install the Java, Minecraft, and NeoForge versions from one matching baseline above.
2. Download the matching compukters-<minecraft>-neoforge-<version>.jar asset from the latest Compukters release.
3. Put the JAR in the mods directory of the client and, for multiplayer, the server.
4. Start the game with the matching NeoForge profile. Compukters has no Architectury runtime dependency.

Use a disposable world while learning the current development release. Back up worlds before moving them between mod versions.

Place and open a computer

Compukters does not currently provide a survival recipe. In a creative world, open the Compukters creative tab and take a Compukter, or run:

/give @s compukters:compukter

Place the block and use it with an empty hand. Its terminal opens and the built-in shell displays a > prompt after the computer boots. Run help to see the currently available shell commands.

Use Left/Right, Home/End and Delete/Backspace to edit commands. Up/Down recall the last 32 commands; Down past the newest entry restores your unfinished draft and its cursor. History is bounded and belongs to the running shell session. Long commands scroll horizontally while editing; input is limited to 256 UTF-16 units. Ctrl+U clears the line. Ctrl+C cancels input at the prompt or stops the foreground program and its nested work, returning to the shell. Files already saved remain intact; interruption does not save an editor’s unsaved buffer.

The terminal retains the last 512 scrolled rows, available when you reopen it. Scroll with the mouse wheel or Shift+PageUp/PageDown; Shift+Home/End jumps to the oldest output or the live screen. Drag with the left mouse button to select any rectangular area, then press Ctrl+C to copy it. Escape clears the selection. Without a selection, Ctrl+C still stops the running program; Ctrl+Shift+C is always a local copy shortcut. Ctrl+V pastes into program input and returns to the live screen. The same controls work in the IDE target terminal. Screen clear preserves history; reboot starts a fresh terminal.

Run cmatrix for green terminal rain, or cmatrix 1 for a shorter delay between animation frames. The optional delay is 1–20 server ticks (default 2), in addition to time spent drawing under the VM budget. Press Ctrl+C to stop the animation and return to the shell. help cmatrix shows the command usage.

Use help <command> for usage. Relative paths start at /home; quote names containing spaces. For example:

mkdir -p "notes folder/archive"
edit "notes folder/message.txt"
cat "notes folder/message.txt"
mv "notes folder/message.txt" "notes folder/archive/message.txt"
rm "notes folder/archive/message.txt"

cat prints strict UTF-8 text up to 65,536 encoded bytes, preserving the file’s line endings without adding a newline. mv takes the complete destination path and refuses to replace an existing entry. rm removes a file or an empty directory; it does not delete a directory tree. Paths may contain . and ..; filesystem access normalizes them, and /rom remains read-only. Executable paths also normalize before the shell starts a child program.

Unload, resume and restart

Running computers hibernate when their carrier unloads and during orderly server shutdown. Loading them again continues the saved program, including unsaved editor text, terminal state and nested foreground programs. Timer waits retain their remaining ticks. A cleanly halted or shut-down computer stays off.

If a saved execution snapshot is corrupt or incompatible, the computer logs the failure and boots again from ROM, retaining its identity and /home files. An operator can request a fresh boot with /compukters reboot x y z for a loaded computer. This discards execution and unsaved edits, but retains the computer identity and /home files. Physics on Sable constructions keeps running while the computer restores. Restoration time depends on the saved execution, storage and server load.

The base runtime, Sable observation addon and Propulsion engine controls support hibernation. Propulsion restores owned throttle, steering and thrust commands before the program continues. Missing or replaced engines leave their old handles stale; a control conflict triggers a fresh boot without overwriting another controller. Thrust can lapse during unload or restoration while construction physics keeps running.

Installing Create does not prevent hibernation when its Guest resources are unused. Active Create resources do not support capture yet; capture failure is logged and the computer starts fresh on its next load.

Path 1: build and run a project in the IDE

The IDE stores projects on the client under <game directory>/compukters/ide/projects. A project can contain multiple Kotlin files and can be deployed to the computer you opened it from.

1. Click IDE in the computer terminal or press Ctrl+I. Opening the IDE from the terminal automatically attaches that computer as the target. You can also look directly at a computer and press Ctrl+I.
2. Choose Create, enter hello, and confirm. The IDE creates compukter.toml and opens src/main.kt.
3. The new project already contains this Hello World program, with comments explaining the entry point, terminal output and IDE build/run actions. You can run it as is or change the greeting:

fun main() {
    println("Hello from Compukters!")
}

1. Use Resolve Dependencies and wait for success. This creates compukter.lock, which is required before building.
2. Press Ctrl+S, then use Build or press Ctrl+F9. Wait for the status line to report a successful build.
3. Use Deploy to install /home/hello on the attached computer. Confirm the overwrite dialog if that path already exists.
4. Open the Terminal tool on the right and run hello at the shell prompt.

The triangular Run action is the shortcut for the final sequence: it saves, builds, deploys the manifest program, and submits its installed path to the attached computer.

The IDE projects and Git guide covers opening existing directories, cloning HTTPS repositories, staging/committing changes, fast-forward pulls and file/folder rename.

Path 2: write directly inside the computer

The computer also carries a compact terminal editor and compiler. At the shell prompt, open a source file with edit hello.kt, enter the program above, press Ctrl+S, and then Ctrl+X. Compile it with:

kotlinc hello.kt

The terminal editor holds up to 4096 UTF-16 code units. Saving preserves the cursor position. Pasted tabs expand to four spaces and newlines inherit the current indentation; if the expanded paste does not fit, the editor shows Buffer full and leaves the document unchanged. Saving transfers UTF-8 bytes in bounded chunks and replaces the file atomically, including a completely full buffer. A failed save keeps the previous published file and leaves the document open with an error message.

Without -o, kotlinc writes an extensionless executable with the source basename. Run it from the shell:

hello

The terminal should print:

Hello from Compukters!

The source and executable live in this computer’s writable /home filesystem. The built-in edit, kotlinc, and shell programs live in the read-only /rom filesystem. /home survives ordinary saves and world reloads; breaking a computer removes its active filesystem and moves the data to a recoverable tombstone rather than treating the dropped block as a portable disk.

Useful IDE shortcuts

Current boundaries

Compukters intentionally supports a focused Kotlin subset. Do not assume arbitrary Kotlin/JVM libraries, Java interop, reflection, host threads or ordinary coroutine libraries are available. Collections and exceptions have defined supported subsets; check the matrices below for their exact boundaries. The Guest Kotlin support matrix indexes language features and links to the separate Guest API and IDE support pages. The stdlib support matrix lists callable Kotlin APIs. The Guest API reference lets you search declarations by name or package and follow source links from their signatures.

Programs execute in a deterministic managed VM rather than a general JVM. CPU work, memory, filesystem access, terminal I/O, processes, and redstone are admitted through bounded runtime contracts.

Next steps

• Connect a program to the world with Redstone GPIO.
• Put program output on an in-world Display.
• Explore kinetics, Stock Tickers, and boilers in the Create addon guide.
• Check exact language support in the Guest Kotlin support matrix.
• Contributors can continue with Architecture and Verification.
• Report a reproducible problem through GitHub Issues.