4.6 KiB
Install CraftOS-PC
CraftOS-PC is the local harness used to run this repo's Lua outside of Minecraft. See ADR-0005 for why.
CraftOS-PC is the emulator; craftos is the command-line executable it installs. For the broader upstream documentation index, see craftos_pc_glossary.md.
Minimum version: v2.8.3. just install runs craftos --version to verify it is on $PATH and recent enough; it also checks that jq and luacheck are installed.
The upstream installation page is https://www.craftos-pc.cc/docs/installation. The notes below pin the version we test against and add a SHA-256 verification step.
macOS
There is no Homebrew cask, so the install is a manual drag-to-Applications from the official GitHub release.
# 1. Download the dmg and the published hashes.
curl -L -o ~/Downloads/CraftOS-PC.dmg \
https://github.com/MCJack123/craftos2/releases/download/v2.8.3/CraftOS-PC.dmg
# 2. Verify the SHA-256.
curl -sL https://github.com/MCJack123/craftos2/releases/download/v2.8.3/sha256-hashes.txt \
| grep CraftOS-PC.dmg
shasum -a 256 ~/Downloads/CraftOS-PC.dmg
# The two hashes must match.
# 3. Mount, install, unmount.
hdiutil attach ~/Downloads/CraftOS-PC.dmg -nobrowse
rm -rf /Applications/CraftOS-PC.app
cp -R "/Volumes/CraftOS-PC/CraftOS-PC.app" /Applications/
hdiutil detach "/Volumes/CraftOS-PC"
# 4. Clear Gatekeeper quarantine so the first launch is not blocked.
xattr -dr com.apple.quarantine /Applications/CraftOS-PC.app
The binary is not on $PATH by default. Add a symlink so just check-craftos can find it:
ln -sf /Applications/CraftOS-PC.app/Contents/MacOS/craftos /usr/local/bin/craftos
User data (computer state, settings) lives in ~/Library/Application Support/CraftOS-PC and survives a reinstall. The steps above only touch the .app bundle.
When running headless tests on macOS, prefer passing the app bundle's resource directory explicitly if craftos is reached through the /usr/local/bin/craftos symlink:
craftos --headless --rom /Applications/CraftOS-PC.app/Contents/Resources --exec 'print("__TRAPOS_TEST_OK__"); os.shutdown()'
Windows
Download CraftOS-PC-Setup.exe from the latest release and run it. The installer puts craftos.exe on %PATH%.
User data: %appdata%\CraftOS-PC.
Linux
Download CraftOS-PC.x86_64.AppImage from the latest release, make it executable, and symlink it into $PATH:
chmod +x ~/Downloads/CraftOS-PC.x86_64.AppImage
sudo ln -sf "$HOME/Downloads/CraftOS-PC.x86_64.AppImage" /usr/local/bin/craftos
User data: ~/.local/share/craftos-pc.
Verify
craftos --version
Must report CraftOS-PC v2.8.3 or newer. Once this works, just install will succeed.
To verify that CraftOS-PC can boot a computer, not only print its executable version, run:
craftos --headless --exec 'print("__TRAPOS_TEST_OK__"); os.shutdown()'
On macOS, use the --rom form shown above if the command fails with Could not mount ROM.
Running tests
just test runs the headless smoke tests in tests/ through CraftOS-PC. On macOS the recipe passes --rom /Applications/CraftOS-PC.app/Contents/Resources because the /usr/local/bin/craftos symlink loses ROM auto-discovery; on Linux and Windows no flag is needed. just ci runs the same tests after luacheck.
Repository-local launches
just craftos launches CraftOS-PC with persistent save data rooted at .craftos instead of the platform default user-data directory. Generated files live under .craftos/config/ and .craftos/computer/, while the root .gitignore keeps that state untracked.
The recipe mounts the repository root read-only at /trapos so code can read /trapos/manifest.json. It also uses jq to read manifest.json and mount each shipped top-level directory read-only at its ComputerCraft root path, such as /apis, /programs, /servers, and /startup.
Pass CraftOS-PC flags directly after the recipe name, for example:
just craftos --headless --exec 'print("__TRAPOS_TEST_OK__"); os.shutdown()'
just repl delegates to just craftos --cli for human interactive use only. LLM agents must not run just repl.
See Command-Line Flags for --headless, --exec, --script, --rom, and --mount-*. See Error Messages for Could not mount ROM and other boot-time failures.
Updating
Repeat the steps above against the newer release. The bundle replacement is in-place; the user data directory is preserved.