The JavaScript and TypeScript binding

The Clunkyard robot API in Node, over the robot core's WebAssembly build. The generated API and TypeScript declarations share the DSL's core loader; the binding contains no physics, tracking or protocol parser.

Requires Node 20 or later. For local development, install the npm package under the same name your robot imports in the arena:

npm install clunkyard@npm:@clunkyard/sdk

Keep require('clunkyard') or import ... from 'clunkyard' in robot source. The alias includes the core's WebAssembly build and TypeScript declarations. Commit package.json and package-lock.json; keep node_modules/ out of source uploads. The arena supplies its own matching binding during hosted builds. Standalone Node applications may instead install @clunkyard/sdk and import @clunkyard/sdk directly.

To build and play a real match, clone the JavaScript starter or TypeScript starter and run make, make match and make replay. Without Make, use npx @clunkyard/cli build, match and replay. The shared CLI downloads the separate engine and launcher; the npm SDK package provides the robot API. The player kit explains setup and current tooling. cy.play(robot, lines) also accepts recorded protocol lines for in-memory tests.

For a shared SDK installation, run make install SDK=/opt/clunkyard/sdk. The arena's TypeScript 6 compiler resolves the declaration with tsc --ignoreConfig --ignoreDeprecations 6.0 --target ES2022 --module commonjs --baseUrl /opt/clunkyard/sdk/bindings/javascript bot.ts. Run either language with NODE_PATH=/opt/clunkyard/sdk/bindings/javascript /opt/clunkyard/sdk/bindings/javascript/run bot.js. The launcher preserves the protocol pipe and sends standard output to standard error before user code runs, including writes made through fs.

Subsystems are properties of the robot. Facts are properties, calls use camelCase, and controls take an object of the fields to set. Later controls merge with earlier ones in the same turn. Optional results are null. Throw new cy.Forfeit(code, message) to forfeit. Other exceptions are logged with their trace and the turn sends the controls already set.

A tiny robot

const cy = require('clunkyard');

class Tiny extends cy.Robot {
  onTurn() {
    const target = this.sensors.nearest;
    if (target === null) {
      this.drive.set({ throttle: 0.75, turn: 0.25 });
      this.scanner.set({ heading: this.me.heading, arc: 40 });
      this.status.set({ text: 'SEARCH', value: this.scanner.last.arc });
      return;
    }
    const power = this.gun.powerForFlightTime(target.range, 1);
    const aim = this.gun.lead(target, power);
    this.gun.aim({ heading: aim ? aim.heading : target.bearing,
      pitch: aim ? aim.pitch : target.elevation });
    if (this.gun.canFire(power, 10)) this.gun.fire({ power });
    this.drive.set({ throttle: 0.5,
      turn: cy.angles.clamp(cy.angles.angleDiff(target.bearing, this.me.heading)) });
    this.scanner.set({ heading: target.bearing, arc: 10 });
    this.status.set({ text: 'TRACK', value: target.range });
  }
}

cy.run(new Tiny());

make test SDK=/opt/clunkyard/sdk checks the generated API against the core's conformance vectors, including exact floating-point results and act lines. The README example also participates in the cross-language identity check.

Names

Every entry of the robot API 2.0.0 in JavaScript / TypeScript. names.md has every language side by side.

Download this page as Markdown