Develop a robot on your computer

Choose a language starter from Clunkyard's game kit. Each repository contains the same starter as the online editor, normal source files and a small Makefile. Shared build, download and match code lives in the @clunkyard/cli npm package. Bring Node 20+ with npm and your existing compiler or interpreter; the CLI downloads the common engine and only that language's binding.

For C:

git clone https://github.com/clunkyard/starter-c.git
cd starter-c
make doctor
make
make match
make replay

The first run downloads the CLI through npm, along with the match engine and your language's SDK. Downloaded files go under .clunkyard/ in your project. Install your compiler or interpreter separately. To use an existing matching native SDK, set CLUNKYARD_SDK to its path.

Supported platforms

Install Node 20+ with npm and your selected language's compiler or interpreter. The CLI downloads the SDK for your operating system and CPU, then builds with those tools. It never installs compilers or the all-language builder.

JavaScript, TypeScript and the Vane/Cadence/Glyph Node routes work on Linux, macOS and Windows through the WebAssembly core. TypeScript also needs its compiler. Other local profiles, including the Wasmtime-based profiles, use Linux packages. You can use hosted builds and trials when your computer lacks a language's local SDK or toolchain.

On macOS, C/C++ use Xcode Command Line Tools. On Windows, use MSVC's Developer PowerShell or Developer Command Prompt for C/C++, or a working Clang toolchain. Python, Rust's MSVC toolchain and C# can use ordinary PowerShell; SDK binding installation needs no Unix shell or GNU Make. Use the direct CLI commands below if Make is not installed.

The native macOS core targets macOS 11 or later; Node and your selected compiler can have a newer OS requirement. Rust's desktop binding loads the shared C runtime, so it rebuilds with your Rust compiler without bundling another compiler's standard library. Compiler-specific modules rebuild after your toolchain version changes. A custom matching installation can be selected with an absolute or relative CLUNKYARD_SDK path.

Without Make, use the CLI directly from the project directory:

npx @clunkyard/cli doctor
npx @clunkyard/cli build
npx @clunkyard/cli match
npx @clunkyard/cli replay

You can also create the same starter without cloning its repository:

npx @clunkyard/cli new c my-robot

Replace c with your language and choose a directory that does not exist yet. The CLI reads bot.json from your current directory; use --project PATH to work on another project. doctor checks the selected tools and never installs one automatically.

Your project

Keep your robot source, bot.json, README, .gitignore, small Makefile and any normal language build files. JavaScript and TypeScript projects also keep package.json and package-lock.json for the npm SDK.

The Makefile uses CLUNKYARD ?= npx --yes @clunkyard/cli, so tooling updates are available without editing every starter. To record the CLI version used for a trial:

npx @clunkyard/cli --version

Record that version with your source commit and language lockfiles when comparing trials. Ordinary setup commands use the current CLI.

JavaScript and TypeScript from npm

Use starter-javascript or starter-typescript for the complete edit, build, match and replay flow. Their robot API is available on npm as @clunkyard/sdk. To add it to another Node 20+ project:

npm install clunkyard@npm:@clunkyard/sdk

Use require('clunkyard') or import ... from 'clunkyard' in robot source so the same import works in the hosted arena. The package includes the WebAssembly core and TypeScript declarations. Keep the generated package-lock.json in Git and use npm ci to restore its exact dependency versions. Keep node_modules/ ignored. TypeScript also needs your installed TypeScript compiler. For local matches, use a starter project: its CLI and Make targets provide the match engine and the matching SDK.

Install only your adapter's dependencies

doctor checks the selected compiler commands and adapter prerequisites. It reports a missing dependency with an installation hint; it never installs one. Use the language guide's official installation links for the toolchain.

Other bindings use their listed compiler/interpreter and normal system libraries. Compiler-specific SDK modules are rebuilt by that installation. Native qualification uses Ubuntu 24.04 and the recorded release toolchains; a different compiler version can still require a language-specific adjustment.

Repeat a real local trial

npx @clunkyard/cli match 42 2d classic
npx @clunkyard/cli match 77 3d zero-g
npx @clunkyard/cli replay replays/trial-42.json

Edit the entry file, rebuild and repeat several seeds and rulesets. Keep a baseline commit. The replay records the engine's real states, shots, hits and failures; pause and step through the first useful difference. Local programs run as your user. Local timing is useful for compatibility checks but does not replace authoritative arena budget qualification.

See local trials for matched comparisons and both seat orders, and the C API and ABI and adapter guides for the complete API.

Use a contained toolchain when needed

The C, Python, JavaScript and DSL starters also offer an optional Dockerfile. It uses official public Node and Ubuntu 24.04 bases and installs the selected toolchain. It does not require a Clunkyard registry login or download 56 languages. Native SDK packages use the same glibc baseline as the container.

mkdir -p replays
docker build -t my-clunkyard-c .
docker run --rm -v "$PWD/replays:/workspace/replays" my-clunkyard-c match

The first image build downloads its public base and selected OS packages; the first run downloads its pinned SDK and engine. Containers currently target Linux x86-64. Other CPUs can request --platform linux/amd64 for both commands with emulation overhead. On Linux, output created by the container may need an ownership adjustment. Use the native Make route when the toolchain is already installed.

Connect the project to the arena

Open New bot and choose a language starter or a published House bot, then choose its source home. For a private arena project, install the @clunkyard/git helper from npm, sign in with an agent access key and copy the clone command from the bot's Connections → Private Git panel. Edit, commit and push: each accepted push saves a source revision and queues its hosted build. The private Git guide explains how to bring an existing language starter into that private clone and merge browser or WebDAV edits before pushing.

For code already on GitHub, choose An existing GitHub project. Connect your personal account, then pick a repository, branch and project folder. Clunkyard reads its language from bot.json; its first revision contains your selected source. For a new starter or House copy, choose My GitHub account as its source home and confirm the new private repository's name and source. Commits pushed to the selected ref become immutable saved source revisions and queue builds. Run an arena trial, then follow its replay back to the revision that played.

Save browser edits before syncing, and resolve conflicts explicitly. Keep SDK downloads, output and access tokens out of Git. Browser editing and WebDAV remain available for players who prefer them.

Public releases retain their checksums. A changed release requires a new version, rather than overwriting an asset that an existing checkout pins.

Connect code running on your computer

Use Node 22+ for the connection's built-in WebSocket client. Copy the connection settings from your bot's Connections panel into shell environment variables: CLUNKYARD_REMOTE_URL, CLUNKYARD_REMOTE_TOKEN and CLUNKYARD_BOT_ID. Keep the key out of source and command arguments. Then run from your robot directory:

npx @clunkyard/cli connect
npx @clunkyard/cli connect --strategist python3 strategist.py

With no command, the CLI builds the project and starts its SDK-aware stdio runner, including the downloaded language binding and native library. Use an explicit command only for a self-contained protocol program with its dependencies already installed.

The shared CLI contains the same remote bridge as the standalone download. It starts your command without a shell, sends match messages over its standard input/output and reconnects when the network drops. A remote robot plays Open; a strategist supplies policy to its hosted reflex between turns. The child receives no Clunkyard connection keys. For additional environment variables your program needs, list their names in CLUNKYARD_BOT_ENV_ALLOW. Keep the CLI running until the match ends; Ctrl-C stops the connection and child processes.

Download this page as Markdown