@zixial3/arcade-core 1.0.0 → 1.1.0

package/README.md

@@ -14,14 +14,14 @@ A board is a square array of numbers where `0` means empty.
 
 ```js
 import {
-  createBoard,
   move,
   spawn,
   hasMoves,
   canMove,
+  startBoard,
 } from "@zixial3/arcade-core";
 
-let board = spawn(spawn(createBoard())); // empty 4×4 board with two starting tiles
+let board = startBoard(); // empty 4×4 board with two starting tiles
 
 if (canMove(board, "left")) {
   board = move(board, "left"); // slide and merge
@@ -42,7 +42,9 @@ Every function returns a **new** board and never mutates its input.
 | `hasMoves(board)`                     | `true` if any direction would change the board; `false` means game over.                        |
 | `canMove(board, direction)`           | `true` if moving in `direction` would change the board.                                         |
 | `moveWithDetails(board, direction)`   | `{ board, moves, merges, points, changed }`: where every tile went, for animations and scoring. |
+| `startBoard(rng?, size?)`             | Empty board (default 4×4) with two starting tiles.                                              |
 | `createBoard(size?)`                  | Empty board.                                                                                    |
+| `createRng(seed)`                     | Seeded random number generator to pass as `rng`. Its `state` resumes the same sequence.         |
 | `emptyCells(board)`, `maxTile(board)` | Helpers.                                                                                        |
 
 `direction` is `'up' | 'down' | 'left' | 'right'`.
@@ -65,6 +67,19 @@ const { board, points } = moveWithDetails([[2, 2, 4, 4], ...], 'left');
 // board[0] → [4, 8, 0, 0], points → 12
 ```
 
+### Seeded games
+
+```js
+import { createRng, startBoard, spawn } from "@zixial3/arcade-core";
+
+const rng = createRng(1234);
+let board = startBoard(rng); // same starting tiles for seed 1234, every time
+board = spawn(move(board, "up"), rng); // same spawn for the same move
+
+const saved = rng.state; // save this…
+const resumed = createRng(saved); // …and pick up exactly where you left off
+```
+
 ## Development
 
 ```bash

package/dist/index.d.ts

@@ -55,3 +55,6 @@ export declare function emptyCells(board: Board): Position[];
 export declare function spawn(board: Board, rng?: Rng): Board;
 /** The largest tile on the board. */
 export declare function maxTile(board: Board): number;
+/** An empty board with two starting tiles. */
+export declare function startBoard(rng?: Rng, size?: number): Board;
+export { createRng, type SeededRng } from './rng.js';

package/dist/index.js

@@ -105,3 +105,8 @@ export function spawn(board, rng = Math.random) {
 export function maxTile(board) {
     return Math.max(0, ...board.flat());
 }
+/** An empty board with two starting tiles. */
+export function startBoard(rng = Math.random, size = 4) {
+    return spawn(spawn(createBoard(size), rng), rng);
+}
+export { createRng } from './rng.js';

package/dist/rng.d.ts

@@ -0,0 +1,12 @@
+import type { Rng } from './index.js';
+/** A seeded `Rng` whose current position can be saved and resumed. */
+export interface SeededRng extends Rng {
+    /** Pass this to `createRng` to continue the exact same sequence later. */
+    readonly state: number;
+}
+/**
+ * Creates a deterministic random number generator (mulberry32).
+ * The same seed always produces the same sequence, so the same moves
+ * always spawn tiles in the same places.
+ */
+export declare function createRng(seed: number): SeededRng;

package/dist/rng.js

@@ -0,0 +1,16 @@
+/**
+ * Creates a deterministic random number generator (mulberry32).
+ * The same seed always produces the same sequence, so the same moves
+ * always spawn tiles in the same places.
+ */
+export function createRng(seed) {
+    let state = seed >>> 0;
+    const next = () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    return Object.defineProperty(next, 'state', { get: () => state });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zixial3/arcade-core",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Pure, framework-free game logic for 2048.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm run build && npm test",
+    "prebuild": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
   },
   "keywords": [
     "2048",