@fortemate/dicechess-engine-wasm 0.4.0

package/README.md

@@ -0,0 +1,108 @@
+# @fortemate/dicechess-engine 🎲♟️
+
+High-performance, cross-platform game engine and move generator for **Dice Chess**, compiled to pure Javascript (ES Modules) with full TypeScript type declarations.
+
+Designed for maximum performance in web browsers, hybrid apps, and Node.js servers.
+
+---
+
+## Installation
+
+Install the package via npm or your preferred package manager:
+
+```bash
+npm install @fortemate/dicechess-engine
+```
+
+---
+
+## Quick Start (JavaScript / TypeScript)
+
+The package is distributed as a standard ES Module (`type: "module"`).
+
+```javascript
+import { DiceChess } from '@fortemate/dicechess-engine';
+
+// Dice Chess FEN (DFEN) encodes the board state and the current dice pool as the 7th field
+// (e.g. "PN" represents a rolled Pawn (P) and Knight (N))
+const dfen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1 PN";
+
+// 1. Get all legal moves as a flat array of UCI strings for the DFEN position
+const legalMoves = DiceChess.getLegalUciMoves(dfen);
+
+console.log("Legal moves in this turn:", legalMoves);
+// e.g. ["e2e3", "e2e4", "b1c3", "b1a3", ...]
+
+// 2. Apply a micro-move. Note that applyMove preserves the active color
+// (White) since a Dice Chess turn may consist of multiple micro-moves.
+// Arguments: (dfen, fromSquare, toSquare, optionalPromotionPiece)
+const nextDfen = DiceChess.applyMove(dfen, "e2", "e4");
+console.log("DFEN after micro-move:", nextDfen);
+
+// 3. Explicitly end the turn when the player has exhausted their dice.
+// This toggles the active color to Black, increments the move counter,
+// and clears any stale en-passant targets from the previous turn.
+const finalDfen = DiceChess.endTurn(nextDfen);
+console.log("DFEN after ending turn:", finalDfen);
+
+// 4. Discover available bots (search algorithms)
+const bots = DiceChess.getAvailableBots();
+console.log("Available bots:", bots);
+// e.g. [ { id: 'random', name: 'Random', description: '...', difficulty: 1, isExperimental: false }, ... ]
+
+// 5. Discover the built-in time-management policies.
+const timePolicies = DiceChess.getAvailableTimePolicies();
+console.log("Available time policies:", timePolicies);
+// [ "empirical-v1", "legacy-linear-v1" ]
+
+// 6. Compute the best sequence of micro-moves using the greedy bot search
+// Arguments: (dfen, optionalOptions)
+const botResult = DiceChess.getBestMove(finalDfen, { algorithm: "greedy" });
+console.log("Bot moves:", botResult.moves);
+// e.g. [ { from: "g8", to: "f6" } ]
+
+// Clock-aware searches use empirical-v1 by default. Pass legacy-linear-v1 to
+// reproduce the original allocation for rollback or an A/B comparison.
+const timedResult = DiceChess.getBestMove(finalDfen, {
+  algorithm: "monte-carlo",
+  clock: { remainingMs: 180_000, incrementMs: 2_000, moveNumber: 8 },
+  timePolicy: "empirical-v1",
+});
+console.log("Effective budget (ms):", timedResult.budgetMs);
+
+// 7. Doubling Cube & Draw Offers (New)
+// Check if the bot wants to offer a double before its turn:
+const shouldDouble = DiceChess.shouldBotOfferDouble(finalDfen, 1);
+
+// Check if the bot accepts a double proposed by the opponent (Take/Drop):
+const acceptDouble = DiceChess.shouldBotAcceptDouble(finalDfen, 2);
+
+// Check if the bot wants to offer a draw:
+const offerDraw = DiceChess.shouldBotOfferDraw(finalDfen);
+
+// Check if the bot accepts a draw proposed by the opponent:
+const acceptDraw = DiceChess.shouldBotAcceptDraw(finalDfen);
+
+```
+
+---
+
+## Features
+
+* **Complete Dice Chess Rules**: Implements turn sequencing, unblocking, promotion path calculations, and strict **Maximal Micro-moves Filtering**.
+* **Type-Safe**: Shipped with comprehensive TypeScript definition files (`.d.ts`) generated directly from the Scala compiler.
+* **Side-Effect Free**: Configured with `sideEffects: false` to allow advanced tree-shaking in modern bundlers like Vite, Webpack, and Rollup.
+* **Blazing Fast**: Optimized bitwise operations compiled via the advanced Scala.js optimizing linker.
+
+---
+
+## API Reference & Documentation
+
+* **[Interactive User & Developer Guide](https://fortemate.com/dicechess-engine/)**: Complete rules, architectural documentation, and live interactive visual catalogs.
+* **[GitHub Repository](https://github.com/fortemate/dicechess-engine)**: Source code, issue tracker, and contribution guidelines.
+
+---
+
+## License
+
+This package is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

package/__loader.js

@@ -0,0 +1,169 @@
+
+// This implementation follows no particular specification, but is the same as the JS backend.
+// It happens to coincide with java.lang.Long.hashCode() for common values.
+function bigintHashCode(x) {
+  var res = 0;
+  if (x < 0n)
+    x = ~x;
+  while (x !== 0n) {
+    res ^= Number(BigInt.asIntN(32, x));
+    x >>= 32n;
+  }
+  return res;
+}
+
+// JSSuperSelect support -- directly copied from the output of the JS backend
+function resolveSuperRef(superClass, propName) {
+  var getPrototypeOf = Object.getPrototyeOf;
+  var getOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;
+  var superProto = superClass.prototype;
+  while (superProto !== null) {
+    var desc = getOwnPropertyDescriptor(superProto, propName);
+    if (desc !== (void 0)) {
+      return desc;
+    }
+    superProto = getPrototypeOf(superProto);
+  }
+}
+function superSelect(superClass, self, propName) {
+  var desc = resolveSuperRef(superClass, propName);
+  if (desc !== (void 0)) {
+    var getter = desc.get;
+    return getter !== (void 0) ? getter.call(self) : getter.value;
+  }
+}
+function superSelectSet(superClass, self, propName, value) {
+  var desc = resolveSuperRef(superClass, propName);
+  if (desc !== (void 0)) {
+    var setter = desc.set;
+    if (setter !== (void 0)) {
+      setter.call(self, value);
+      return;
+    }
+  }
+  throw new TypeError("super has no setter '" + propName + "'.");
+}
+
+const scalaJSHelpers = {
+  // JSTag
+  JSTag: WebAssembly.JSTag,
+
+  // BinaryOp.===
+  is: Object.is,
+
+  // undefined
+  undef: void 0,
+  isUndef: (x) => x === (void 0),
+
+  // Constant boxes
+  bFalse: false,
+  bTrue: true,
+
+  // Boxes (upcast) -- most are identity at the JS level but with different types in Wasm
+  bIFallback: (x) => x,
+  bF: (x) => x,
+  bD: (x) => x,
+
+  // Unboxes (downcast, null is converted to the zero of the type as part of ToWebAssemblyValue)
+  uZ: (x) => x, // ToInt32 turns false into 0 and true into 1, so this is also an identity
+  uIFallback: (x) => x,
+  uF: (x) => x,
+  uD: (x) => x,
+
+  // Type tests
+  tZ: (x) => typeof x === 'boolean',
+  tI: (x) => typeof x === 'number' && Object.is(x | 0, x),
+  tF: (x) => typeof x === 'number' && (Math.fround(x) === x || x !== x),
+  tD: (x) => typeof x === 'number',
+
+  // Strings
+  jsValueToString: (x) => (x === void 0) ? "undefined" : x.toString(),
+  jsValueToStringForConcat: (x) => "" + x,
+  booleanToString: (b) => b ? "true" : "false",
+  intToString: (i) => "" + i,
+  longToString: (l) => "" + l, // l must be a bigint here
+  doubleToString: (d) => "" + d,
+
+  // Get the type of JS value of `x` in a single JS helper call, for the purpose of dispatch.
+  jsValueType: (x) => {
+    if (typeof x === 'number')
+      return 3;
+    if (typeof x === 'string')
+      return 2;
+    if (typeof x === 'boolean')
+      return x | 0; // JSValueTypeFalse or JSValueTypeTrue
+    if (typeof x === 'undefined')
+      return 4;
+    if (typeof x === 'bigint')
+      return 5;
+    if (typeof x === 'symbol')
+      return 6;
+    return 7;
+  },
+
+  // JS side of the `valueDescription` helper
+  // TODO: only emit this when required by checked behaviors
+  jsValueDescription: ((x) =>
+    (typeof x === 'number')
+      ? (Object.is(x, -0) ? "number(-0)" : ("number(" + x + ")"))
+      : (typeof x)
+  ),
+
+  // Identity hash code
+  bigintHashCode,
+  symbolDescription: (x) => {
+    var desc = x.description;
+    return (desc === void 0) ? null : desc;
+  },
+  idHashCodeGet: (map, obj) => map.get(obj) | 0, // undefined becomes 0
+  idHashCodeSet: (map, obj, value) => map.set(obj, value),
+
+  // Some support functions for CoreWasmLib
+  makeTypeError: (msg) => new TypeError(msg),
+
+  // JS interop
+  jsNewArray: () => [],
+  jsNewObject: () => ({}),
+  jsNewNoArg: (constr) => new constr(),
+  jsImportMeta: () => import.meta,
+  
+  jsDelete: (o, p) => { delete o[p]; },
+  jsForInStart: function*(o) { for (var k in o) yield k; },
+  jsForInNext: (g) => { var r = g.next(); return [r.value, r.done]; },
+  jsIsTruthy: (x) => !!x,
+
+  // Non-native JS class support
+  jsSuperSelect: superSelect,
+  jsSuperSelectSet: superSelectSet,
+}
+
+export async function load(wasmFileURL, exportSetters, privateJSFieldGetters,
+    privateJSFieldSetters, customJSHelpers, wtf16Strings) {
+  const myScalaJSHelpers = {
+    ...scalaJSHelpers,
+    idHashCodeMap: new WeakMap()
+  };
+  const importsObj = {
+    "__scalaJSHelpers": myScalaJSHelpers,
+    "__scalaJSExportSetters": exportSetters,
+    "privateJSFieldGetters": privateJSFieldGetters,
+    "privateJSFieldSetters": privateJSFieldSetters,
+    "__scalaJSCustomHelpers": customJSHelpers,
+    "wtf16Strings": wtf16Strings,
+  };
+  const options = {
+    builtins: ["js-string"],
+    importedStringConstants: "",
+  };
+  const resolvedURL = new URL(wasmFileURL, import.meta.url);
+  if (resolvedURL.protocol === 'file:') {
+    const { fileURLToPath } = await import("node:url");
+    const { readFile } = await import("node:fs/promises");
+    const wasmPath = fileURLToPath(resolvedURL);
+    const body = await readFile(wasmPath);
+    return WebAssembly.instantiate(body, importsObj, options);
+  } else {
+    return await WebAssembly.instantiateStreaming(fetch(resolvedURL), importsObj, options);
+  }
+}
+    

package/dicechess-engine.d.ts

@@ -0,0 +1,141 @@
+/**
+ * TypeScript declarations for the Scala.js Dice Chess Engine.
+ */
+export interface EngineFacadeApi {
+    /**
+     * Computes a bot move for the given DiceChess FEN (DFEN).
+     */
+    getBotMove(dfen: string, seed?: number): Record<string, string> | undefined;
+
+    /**
+     * Retrieves the dice value (1-6) of the piece at the specified square.
+     */
+    getPieceTypeAt(dfen: string, square: string): number | undefined;
+
+    /**
+     * Applies a move to the given DFEN and returns the resulting state.
+     */
+    applyMove(dfen: string, from: string, to: string, promotion?: string): string | undefined;
+
+    /**
+     * Explicitly ends the current turn, toggling the active color, incrementing full moves,
+     * and clearing any stale en-passant targets.
+     * @param dfen The current board state in DiceChess FEN notation.
+     */
+    endTurn(dfen: string): string | undefined;
+}
+
+export const EngineFacade: EngineFacadeApi;
+
+export type TimePolicyId = "empirical-v1" | "legacy-linear-v1";
+
+export interface ClockStateOptions {
+    remainingMs: number;
+    incrementMs?: number;
+    moveNumber?: number;
+    movesToGo?: number;
+}
+
+export interface BestMoveOptions {
+    algorithm?: string;
+    clock?: ClockStateOptions;
+    timePolicy?: TimePolicyId;
+    timeBudgetMs?: number;
+}
+
+export interface BestMoveResult {
+    moves: { from: string, to: string, promotion?: string }[];
+    score: number;
+    timeTakenMs: number;
+    budgetMs: number;
+}
+
+export interface DiceChessApi {
+    /**
+     * Returns metadata for all registered search algorithms.
+     */
+    getAvailableBots(): { id: string, name: string, description: string, difficulty: number, isExperimental: boolean }[];
+
+    /**
+     * Returns stable ids of the built-in time-management policies.
+     */
+    getAvailableTimePolicies(): TimePolicyId[];
+
+    /**
+     * Returns all legal moves as a flat array of UCI strings (e.g., ["e2e4", "e7e8q"]).
+     */
+    getLegalUciMoves(dfen: string): string[];
+
+    /**
+     * Returns the piece type associated with a dice roll.
+     */
+    getPieceFromDice(dice: number): string | null;
+
+    /**
+     * Registers a runtime bot that consults an opening book before delegating to an existing bot.
+     * `tsvString` contains tab-separated lines mapping canonical keys
+     * ("<placement> <color> <castling> <enPassant> <dice>") to comma-separated moves ("e2e4,f1c4").
+     * The decorated bot wraps `baseBotId` and is exposed under `newBotId` for later `getBestMove` calls.
+     * Returns `true` when registered, `false` when the base bot is unknown or the TSV is malformed.
+     */
+    registerOpeningBookBot(tsvString: string, baseBotId: string, newBotId: string, newBotName: string): boolean;
+
+    /**
+     * Computes the best sequence of micro-moves for the given position.
+     * `timeBudgetMs`, when positive and supported by the chosen algorithm (e.g. "monte-carlo"),
+     * bounds per-move thinking time by a wall-clock deadline; other algorithms ignore it.
+     */
+    getBestMove(dfen: string, options?: BestMoveOptions): BestMoveResult;
+
+    /**
+     * Applies a move to the given DFEN and returns the resulting state.
+     * @param dfen The starting board state in DiceChess FEN notation.
+     * @param from The algebraic notation of the starting square.
+     * @param to The algebraic notation of the target square.
+     * @param promotion The optional piece type to promote to (e.g. "q").
+     */
+    applyMove(dfen: string, from: string, to: string, promotion?: string): string | undefined;
+
+    /**
+     * Explicitly ends the current turn, toggling the active color, incrementing full moves,
+     * and clearing any stale en-passant targets.
+     * @param dfen The current board state in DiceChess FEN notation.
+     */
+    endTurn(dfen: string): string | undefined;
+
+    /**
+     * Determines whether the bot should offer a double before its dice roll.
+     */
+    shouldBotOfferDouble(dfen: string, currentStake: number, options?: { algorithm?: string }): boolean;
+
+    /**
+     * Determines whether the bot should accept (Take) or decline (Drop) a double from the opponent.
+     */
+    shouldBotAcceptDouble(dfen: string, currentStake: number, options?: { algorithm?: string }): boolean;
+
+    /**
+     * Determines whether the bot should offer a draw.
+     */
+    shouldBotOfferDraw(dfen: string, options?: { algorithm?: string }): boolean;
+
+    /**
+     * Determines whether the bot should accept a draw offered by the opponent.
+     */
+    shouldBotAcceptDraw(dfen: string, options?: { algorithm?: string }): boolean;
+
+    /**
+     * Estimates pre-roll equity with a Rao-Blackwellized Monte-Carlo rollout.
+     * For progressive use, call in batches (varying `seed`) and pool the per-batch results
+     * (`rollouts` is the batch size and `standardError` lets you combine batches).
+     * Returns a neutral `undecided = 1` result for an invalid DFEN.
+     */
+    estimateEquity(dfen: string, options?: { rollouts?: number, maxPlies?: number, seed?: number }): { whiteWin: number, blackWin: number, undecided: number, rollouts: number, standardError: number, varianceReductionVsVanilla: number };
+
+    /**
+     * Returns the canonical key (the DFEN of the position's symmetry-class representative),
+     * shared by all symmetry-equivalent positions — useful as a cache key. `undefined` for an invalid DFEN.
+     */
+    canonicalKey(dfen: string): string | undefined;
+}
+
+export const DiceChess: DiceChessApi;