@clunkyard/sdk 0.0.0-stage → 2.0.0

package/core.js

@@ -0,0 +1,229 @@
+'use strict';
+// The robot core's wasm32 build (sdk/core/dist/clunkyard-core.wasm) in
+// process, for the DSL interpreters and later the JavaScript binding
+// (docs/design/robot-core.md sections 1.4 and 4.2).
+//
+// Each robot gets its own instance and a memory-port session in it: lines go
+// in with feed() and replies come out with reply(). A panic in the core
+// traps the whole instance (wasm32 cannot unwind), so every call goes
+// through invoke(), which on a WebAssembly.RuntimeError discards the
+// instance, instantiates the module afresh, feeds it the kept hello and hands
+// it the panic count and the tick that faulted. It then throws a CoreFault.
+// The turn is answered as usual with send(), and the core writes an empty
+// act for it; the next state plays on a fresh session, as on native. After
+// three faults in a match the core answers every state with an empty act.
+//
+// The module is passed in as bytes or a compiled WebAssembly.Module, so a
+// bundle can carry it; loadDefault() reads the committed file in Node.
+
+const { API_VERSION, SIZE: WORDS_SIZE } = require('./words');
+
+const OK = 0, NONE = 1, SHORT = 2;
+const EVENTS = [null, 'hello', 'state', 'end'];
+const [API_MAJOR, API_MINOR] = API_VERSION.split('.').map(Number);
+const encoder = new TextEncoder(), decoder = new TextDecoder();
+
+// A negative status from the core, with its message.
+class CoreError extends Error {
+  constructor(symbol, status, message) {
+    super(`${symbol}: ${message || `status ${status}`}`);
+    this.status = status;
+  }
+}
+
+// The core trapped; the robot now runs on a fresh instance.
+class CoreFault extends Error {
+  constructor(symbol, cause, panics) {
+    super(`a fault in the core (${symbol}); it is not the robot's: ${cause.message}`);
+    this.cause = cause;
+    this.panics = panics;
+  }
+}
+
+function compile(source) {
+  const module = source instanceof WebAssembly.Module ? source : new WebAssembly.Module(source);
+  const imports = WebAssembly.Module.imports(module);
+  if (imports.length) throw new Error(`the core imports nothing, but this module imports ${imports.map(item => `${item.module}.${item.name}`).join(', ')}`);
+  return module;
+}
+
+class CoreRobot {
+  constructor(module, { binding = 'clunkyard-dsl', version = API_VERSION } = {}) {
+    this.module = module;
+    this.binding = binding;
+    this.version = version;
+    this.panics = 0;
+    this.hello = null;
+    // The last state line read, for the tick of a fault.
+    this.state = null;
+    this.fed = null;
+    this.instantiate();
+  }
+
+  instantiate() {
+    this.exports = new WebAssembly.Instance(this.module, {}).exports;
+    this.scratchSize = 0;
+    this.scratch = 0;
+    this.reserve(1 << 16);
+    const name = encoder.encode(this.binding), version = encoder.encode(this.version);
+    const at = this.write(new Uint8Array([...name, ...version]), 8);
+    const status = this.exports.cy_open_memory(API_MAJOR, API_MINOR, at, name.length, at + name.length, version.length, this.scratch);
+    if (status !== OK) throw new CoreError('cy_open_memory', status);
+    this.handle = this.view().getUint32(this.scratch, true);
+  }
+
+  // Memory moves when it grows, so every read takes a fresh view.
+  view() { return new DataView(this.exports.memory.buffer); }
+  bytes() { return new Uint8Array(this.exports.memory.buffer); }
+
+  // At least size bytes of scratch memory, 8-byte aligned.
+  reserve(size) {
+    if (size <= this.scratchSize) return;
+    if (this.scratch) this.exports.cy_free(this.scratch, this.scratchSize);
+    this.scratchSize = Math.max(size, this.scratchSize * 2);
+    this.scratch = this.exports.cy_alloc(this.scratchSize);
+    if (!this.scratch) throw new Error('the core is out of memory');
+  }
+
+  // Copies bytes into scratch memory at offset, giving their address.
+  write(bytes, offset = 0) {
+    this.reserve(offset + bytes.length);
+    this.bytes().set(bytes, this.scratch + offset);
+    return this.scratch + offset;
+  }
+
+  // Calls an export, recovering from a trap.
+  invoke(symbol, ...args) {
+    try {
+      return this.exports[symbol](...args);
+    } catch (error) {
+      if (!(error instanceof WebAssembly.RuntimeError)) throw error;
+      this.recover(symbol);
+      throw new CoreFault(symbol, error, this.panics);
+    }
+  }
+
+  // A trap in next() came while reading the line just fed, so that line is
+  // the hello to keep or the state whose tick to answer.
+  recover(symbol) {
+    if (symbol === 'cy_session_next' && this.fed !== null) {
+      let type = null;
+      try { type = JSON.parse(this.fed).type; } catch { /* not JSON: the state stays as it was */ }
+      if (type === 'hello') Object.assign(this, { hello: this.fed, state: null, panics: 0 });
+      else if (type === 'state') this.state = this.fed;
+    }
+    this.panics += 1;
+    this.instantiate();
+    const tick = this.state === null ? -1 : JSON.parse(this.state).tick;
+    if (this.hello !== null) {
+      try {
+        this.feedLine(this.hello);
+        this.check('cy_session_next', this.exports.cy_session_next(this.handle, this.scratch));
+      } catch (error) {
+        // The hello itself traps: carry on without it.
+        if (!(error instanceof WebAssembly.RuntimeError)) throw error;
+        this.instantiate();
+        this.hello = null;
+      }
+    }
+    this.exports.cy_wasm_recover(this.handle, this.panics, tick);
+  }
+
+  check(symbol, status) {
+    if (status < 0) throw new CoreError(symbol, status, this.lastError());
+    return status;
+  }
+
+  lastError() {
+    const status = this.exports.cy_last_error(this.handle, this.scratch + 8, this.scratchSize - 8, this.scratch);
+    return status === OK ? decoder.decode(this.bytes().subarray(this.scratch + 8, this.scratch + 8 + this.view().getUint32(this.scratch, true))) : '';
+  }
+
+  feedLine(line) {
+    const bytes = encoder.encode(line);
+    return this.exports.cy_session_feed(this.handle, this.write(bytes), bytes.length);
+  }
+
+  // ---- the session ----
+
+  // Hands the core one line; next() then reads it.
+  feed(line) {
+    this.fed = line;
+    const bytes = encoder.encode(line);
+    const at = this.write(bytes);
+    this.check('cy_session_feed', this.invoke('cy_session_feed', this.handle, at, bytes.length));
+  }
+
+  // 'hello', 'state' or 'end'. The hello is kept for a recovery, and a new
+  // one starts the panic count again.
+  next() {
+    this.check('cy_session_next', this.invoke('cy_session_next', this.handle, this.scratch));
+    const event = EVENTS[this.view().getInt32(this.scratch, true)];
+    if (event === 'hello') Object.assign(this, { hello: this.fed, state: null, panics: 0 });
+    else if (event === 'state') this.state = this.fed;
+    return event;
+  }
+
+  send() { this.check('cy_session_send', this.invoke('cy_session_send', this.handle)); }
+
+  forfeit(code, message = '') {
+    const a = encoder.encode(code), b = encoder.encode(message);
+    const at = this.write(new Uint8Array([...a, ...b]));
+    this.check('cy_session_forfeit', this.invoke('cy_session_forfeit', this.handle, at, a.length, at + a.length, b.length));
+  }
+
+  // The next line the core wrote, or null.
+  reply() {
+    for (;;) {
+      const status = this.check('cy_session_reply', this.invoke('cy_session_reply', this.handle, this.scratch + 8, this.scratchSize - 8, this.scratch));
+      if (status === NONE) return null;
+      const length = this.view().getUint32(this.scratch, true);
+      if (status === SHORT) { this.reserve(length + 8); continue; }
+      return decoder.decode(this.bytes().subarray(this.scratch + 8, this.scratch + 8 + length));
+    }
+  }
+
+  // ---- the DSL ----
+
+  // The words record (cy_dsl_words_v1) for this state, one f64 a word; see
+  // src/dsl/words.js read().
+  words() {
+    this.reserve(WORDS_SIZE);
+    this.check('cy_dsl_fill_v1', this.invoke('cy_dsl_fill_v1', this.handle, this.scratch));
+    return new Float64Array(this.exports.memory.buffer.slice(this.scratch, this.scratch + WORDS_SIZE));
+  }
+
+  // A control's per-field setter (words.js CONTROLS): a number, text, or
+  // nothing for a flag. The core clamps and writes the act.
+  set(symbol, value) {
+    let status;
+    if (value === undefined) status = this.invoke(symbol, this.handle);
+    else if (typeof value === 'string') {
+      const bytes = encoder.encode(value);
+      status = this.invoke(symbol, this.handle, this.write(bytes), bytes.length);
+    } else status = this.invoke(symbol, this.handle, value);
+    return this.check(symbol, status);
+  }
+
+  close() {
+    this.exports.cy_close(this.handle);
+    this.handle = 0;
+  }
+}
+
+// The core, compiled once; robot() opens one robot on its own instance.
+function load(source) {
+  const module = compile(source);
+  return { module, robot: options => new CoreRobot(module, options) };
+}
+
+let committed = null;
+function loadDefault() {
+  if (!committed) {
+    const fs = require('node:fs'), path = require('node:path');
+    committed = load(fs.readFileSync(path.join(__dirname, '../../sdk/core/dist/clunkyard-core.wasm')));
+  }
+  return committed;
+}
+
+module.exports = { load, loadDefault, compile, CoreRobot, CoreError, CoreFault, OK, NONE, SHORT };

package/index.d.ts

@@ -0,0 +1,254 @@
+// Generated from protocol/v2/api.json; do not edit. Run make api.
+
+export interface Vec3 {
+  x: number;
+  y: number;
+  z: number;
+}
+export interface Rotation {
+  yaw: number;
+  pitch: number;
+  roll: number;
+}
+export interface Direction {
+  heading: number;
+  pitch: number;
+}
+export interface Attitude {
+  forward: Vec3;
+  right: Vec3;
+  up: Vec3;
+}
+export interface Applied {
+  force: Vec3;
+  torque: Rotation;
+  brake: number;
+}
+export interface Scan {
+  heading: number;
+  pitch: number;
+  arc: number;
+  range: number;
+}
+export interface Contact {
+  slot: number;
+  source: "scan" | "proximity" | "faint" | "beam" | "muzzle" | "motion" | "ping";
+  range: number;
+  bearing: number;
+  elevation: number;
+  bearingError: number;
+  rangeError: number;
+  position: Vec3;
+}
+export interface Cue {
+  source: "scan" | "proximity" | "faint" | "beam" | "muzzle" | "motion" | "ping";
+  tick: number;
+  bearingError: number;
+  position: Vec3;
+}
+export interface Solution {
+  heading: number;
+  pitch: number;
+  time: number;
+}
+export interface Zone {
+  shape: "circle" | "sphere" | "column";
+  radius: number;
+  center: Vec3;
+  margin(point: Vec3): number | null;
+  contains(point: Vec3, margin?: number): boolean | null;
+  distanceFrom(point: Vec3): number | null;
+}
+export interface Storm {
+  shape: "circle" | "sphere" | "column";
+  radius: number;
+  dps: number;
+  center: Vec3;
+  velocity: Vec3;
+  margin(point: Vec3): number | null;
+  contains(point: Vec3, margin?: number): boolean | null;
+  distanceFrom(point: Vec3): number | null;
+}
+export interface Hill {
+  shape: "circle" | "sphere" | "column";
+  holder: number;
+  contested: boolean;
+  movesTick: number;
+  heldTicks: number;
+  bestHeldTicks: number;
+  radius: number;
+  center: Vec3;
+  next: Vec3;
+  margin(point: Vec3): number | null;
+  contains(point: Vec3, margin?: number): boolean | null;
+  distanceFrom(point: Vec3): number | null;
+}
+export interface Pickup {
+  kind: "energy" | "health" | "armour";
+  expiresTick: number;
+  amount: number;
+  position: Vec3;
+}
+export interface Compute {
+  k: number;
+  quanta: number;
+  unit: "operations" | "fuel" | "cpu-ms";
+}
+export interface Match {
+  readonly mode: "2d" | "3d";
+  readonly ruleset: "classic" | "inertial-2d" | "gravity-flat" | "gravity-hills" | "zero-g";
+  readonly control: "direct" | "forces";
+  readonly robots: number;
+  readonly is3d: boolean;
+  readonly tickRate: number;
+  readonly maxTicks: number;
+  robotId(slot: number): string;
+}
+export interface Clock {
+  readonly tick: number;
+  readonly seconds: number;
+  readonly remainingTicks: number;
+}
+export interface Arena {
+  readonly size: Vec3;
+  readonly gravity: Vec3;
+  readonly terrainKind: "none" | "flat" | "hills";
+  groundHeight(x: number, y: number): number;
+}
+export interface Me {
+  readonly health: number;
+  readonly position: Vec3;
+  readonly velocity: Vec3;
+  readonly heading: number;
+  readonly pitch: number;
+  readonly roll: number;
+  readonly angularVelocity: Rotation;
+  readonly attitude: Attitude;
+  readonly grounded: boolean;
+  readonly altitude: number;
+  readonly applied: Applied;
+}
+export interface Battery {
+  readonly charge: number;
+  readonly capacity: number;
+  readonly regen: number;
+  readonly sustainableDrive: number;
+  readonly compute: Compute | null;
+  driveCost(fraction: number): number;
+}
+export interface Drive {
+  readonly hoverLift: number;
+  set(fields?: { throttle?: number; turn?: number; pitchTurn?: number }): void;
+  forces(fields?: { thrust?: number; strafe?: number; lift?: number; yawTorque?: number; pitchTorque?: number; rollTorque?: number; brake?: number }): void;
+  get(field: "throttle" | "turn" | "pitchTurn" | "thrust" | "strafe" | "lift" | "yawTorque" | "pitchTorque" | "rollTorque" | "brake"): number | string | null;
+}
+export interface Gun {
+  readonly aimNow: Direction;
+  readonly cooldownTicks: number;
+  readonly spread: number;
+  readonly maxPower: number;
+  readonly damageScale: number;
+  canFire(power: number, reserve: number): boolean;
+  shotSpeed(power: number): number;
+  shotCost(power: number): number;
+  reloadTicks(power: number): number;
+  shotDamage(power: number): number;
+  powerForSpeed(speed: number): number;
+  powerForFlightTime(range: number, seconds: number): number;
+  lead(contact: Contact, power: number): Solution | null;
+  leadPoint(position: Vec3, velocity: Vec3, power: number): Solution | null;
+  aim(fields?: { heading?: number; pitch?: number }): void;
+  fire(fields?: { power?: number }): void;
+  get(field: "heading" | "pitch" | "fire" | "power"): number | string | null;
+}
+export interface Scanner {
+  readonly last: Scan;
+  readonly proximityRange: number;
+  reach(arc: number): number;
+  arcForReach(range: number): number;
+  set(fields?: { heading?: number; arc?: number; pitch?: number }): void;
+  get(field: "heading" | "arc" | "pitch"): number | string | null;
+}
+export interface Sensors {
+  readonly contacts: Array<Contact>;
+  readonly nearest: Contact | null;
+  readonly cues: Array<Contact>;
+  contact(slot: number): Contact | null;
+  positionOf(contact: Contact): Vec3;
+}
+export interface Tracker {
+  readonly cue: Cue | null;
+  readonly nearestBearingRate: number;
+  velocity(slot: number): Vec3;
+  position(slot: number): Vec3 | null;
+  lastSeen(slot: number): number | null;
+  configure(smoothing?: number, forgetTicks?: number, cueTicks?: number): void;
+}
+export interface Nav {
+  readonly zone: Zone | null;
+  readonly storm: Storm | null;
+  readonly hill: Hill | null;
+  readonly pickups: Array<Pickup>;
+  nearestPickup(kind?: "energy" | "health" | "armour"): Pickup | null;
+  fieldDistance(a: Vec3, b: Vec3): number;
+}
+export interface Score {
+  readonly me: number | null;
+  readonly best: number | null;
+  readonly armour: number | null;
+}
+export interface Angles {
+  normalize(degrees: number): number;
+  angleDiff(target: number, current: number): number;
+  bearingTo(from: Vec3, to: Vec3): number;
+  elevationTo(from: Vec3, to: Vec3): number;
+  direction(heading: number, pitch: number): Vec3;
+  distance(a: Vec3, b: Vec3): number;
+  clamp(value: number, low?: number, high?: number): number;
+}
+export interface Status {
+  set(fields?: { text?: string; value?: number }): void;
+  get(field: "text" | "value"): number | string | null;
+}
+export interface Raw {
+  number(path: string): number | null;
+  text(path: string): string | null;
+  has(path: string): boolean;
+  flag(path: string): boolean | null;
+  count(path: string): number | null;
+  line(): string;
+  extra(json: string): void;
+}
+export interface Session {
+  readonly event: "hello" | "state" | "end";
+  next(): "hello" | "state" | "end";
+  send(): void;
+  forfeit(code: string, message: string): void;
+  log(line: string): void;
+  feed(line: string): void;
+  reply(): string | null;
+}
+export class Robot {
+  match: Match;
+  clock: Clock;
+  arena: Arena;
+  me: Me;
+  battery: Battery;
+  drive: Drive;
+  gun: Gun;
+  scanner: Scanner;
+  sensors: Sensors;
+  tracker: Tracker;
+  nav: Nav;
+  score: Score;
+  angles: Angles;
+  status: Status;
+  raw: Raw;
+  session: Session;
+  onStart(): void;
+  onTurn(): void;
+}
+export class Forfeit extends Error { constructor(code: string, message?: string); }
+export const angles: Angles;
+export function run(robot: Robot, options?: { bindingName?: string }): Promise<void>;
+export function play(robot: Robot, lines: Iterable<string>, options?: { bindingName?: string }): string[];

package/index.js

@@ -0,0 +1,55 @@
+'use strict';
+// Node's run loop. The generated API marshals calls to the core; the shared
+// wasm32 loader owns session parsing, act serialization and fault recovery.
+const {attach,subsystem,core,CoreError,CoreFault}=require('./api');
+
+class Forfeit extends Error {
+  constructor(code,message=''){super(message);this.code=code;}
+}
+class Robot { onStart(){} onTurn(){} }
+const angles=subsystem(core.robot({binding:'clunkyard-javascript-angles'}),'angles');
+function turn(robot,event){
+  try{event==='hello'?robot.onStart():robot.onTurn();}
+  catch(error){
+    if(error instanceof Forfeit){robot.session.forfeit(error.code,error.message);return;}
+    console.error(error.stack||error);
+  }
+  robot.session.send();
+}
+function next(robot){
+  try{return robot.session.next();}
+  catch(error){
+    console.error(error.stack||error);
+    if(error instanceof CoreFault||(error instanceof CoreError&&error.status===-6)){
+      try{robot.session.send();}catch(sendError){console.error(sendError.stack||sendError);return 'end';}
+    }
+    return null;
+  }
+}
+function play(robot,lines,options={}){
+  const handle=attach(robot,options),out=[];
+  try{
+    for(const line of lines){
+      robot.session.feed(line);const event=next(robot);if(event==='end')break;
+      if(event)turn(robot,event);let reply;while((reply=robot.session.reply())!==null)out.push(reply);
+    }
+    return out;
+  }finally{handle.close();}
+}
+async function run(robot,options={}){
+  const handle=attach(robot,options),stdoutWrite=process.stdout.write.bind(process.stdout);
+  const write=process.env.CLUNKYARD_PROTOCOL_FD==='3'
+    ? line=>{require('node:fs').writeSync(3,line);return true;}:stdoutWrite;
+  // Robot diagnostics use stderr. Only core replies use the captured writer.
+  const stdout=process.stdout.write;process.stdout.write=process.stderr.write.bind(process.stderr);
+  const lines=require('node:readline').createInterface({input:process.stdin,crlfDelay:Infinity});
+  try{
+    for await(const line of lines){
+      robot.session.feed(line);const event=next(robot);
+      if(event==='end')break;
+      if(event)turn(robot,event);
+      let reply;while((reply=robot.session.reply())!==null)if(!write(reply+'\n'))await new Promise(resolve=>process.stdout.once('drain',resolve));
+    }
+  }finally{lines.close();process.stdout.write=stdout;handle.close();}
+}
+module.exports={Robot,Forfeit,angles,run,play};