Install CraftOS-PC

CraftOS-PC is the local harness used to run this repo's Lua outside of Minecraft. See ADR-0005 for why.

Minimum version: v2.8.3. just install runs craftos --version to verify it is on $PATH and recent enough.

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.

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.

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.

Updating

Repeat the steps above against the newer release. The bundle replacement is in-place; the user data directory is preserved.

2.8 KiB Raw Blame History