@zixial3/arcade-core 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zixiao Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @zixial3/arcade-core
+
+Pure game logic for **2048**: no framework, no DOM, no globals. Works in Node and in the browser.
+
+## Install
+
+```bash
+npm install @zixial3/arcade-core
+```
+
+## Usage
+
+A board is a square array of numbers where `0` means empty.
+
+```js
+import {
+  move,
+  spawn,
+  hasMoves,
+  canMove,
+  startBoard,
+} from "@zixial3/arcade-core";
+
+let board = startBoard(); // empty 4×4 board with two starting tiles
+
+if (canMove(board, "left")) {
+  board = move(board, "left"); // slide and merge
+  board = spawn(board); // add a 2 or 4 in a random empty cell
+}
+
+if (!hasMoves(board)) console.log("game over");
+```
+
+Every function returns a **new** board and never mutates its input.
+
+## API
+
+| Function                              | Returns                                                                                         |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `move(board, direction)`              | New board after sliding every tile towards `direction` and merging equal neighbours once.       |
+| `spawn(board, rng?)`                  | New board with a 2 (90%) or 4 (10%) in a random empty cell. `rng` defaults to `Math.random`.    |
+| `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'`.
+
+### Merging rules
+
+Each tile merges at most once per move:
+
+```js
+move([[2, 2, 2, 2], ...], 'left'); // → [[4, 4, 0, 0], ...]
+move([[4, 4, 8, 0], ...], 'left'); // → [[8, 8, 0, 0], ...]
+```
+
+### Scoring
+
+`moveWithDetails` reports `points`, the sum of every tile created by a merge:
+
+```js
+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
+npm install
+npm test        # vitest
+npm run build   # TypeScript → dist/
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure game logic for 2048.
+ *
+ * A board is a square grid of numbers where 0 means "empty". Every function
+ * returns a new board and never mutates its input, touches the DOM, or reads
+ * global state. Randomness is injected through an `rng` argument.
+ */
+export type Board = number[][];
+export type Direction = 'up' | 'down' | 'left' | 'right';
+export declare const DIRECTIONS: readonly Direction[];
+/** A function returning a float in [0, 1), like `Math.random`. */
+export type Rng = () => number;
+export interface Position {
+    row: number;
+    col: number;
+}
+/** Where one tile travelled during a move. */
+export interface TileMove {
+    from: Position;
+    to: Position;
+}
+/** A cell where two tiles combined into one. */
+export interface Merge {
+    at: Position;
+    value: number;
+}
+export interface MoveResult {
+    board: Board;
+    /** One entry for every tile that was on the board before the move. */
+    moves: TileMove[];
+    merges: Merge[];
+    /** Sum of every tile created by a merge. */
+    points: number;
+    changed: boolean;
+}
+/** Creates an empty `size` × `size` board. */
+export declare function createBoard(size?: number): Board;
+/**
+ * Slides every tile towards `direction`, merging equal neighbours once each,
+ * and reports where every tile went.
+ */
+export declare function moveWithDetails(board: Board, direction: Direction): MoveResult;
+/** Slides and merges every tile in `direction` and returns the new board. */
+export declare function move(board: Board, direction: Direction): Board;
+/** True if moving in `direction` would change the board. */
+export declare function canMove(board: Board, direction: Direction): boolean;
+/** True if any direction would still change the board; false means game over. */
+export declare function hasMoves(board: Board): boolean;
+/** Positions of every empty cell, in reading order. */
+export declare function emptyCells(board: Board): Position[];
+/**
+ * Puts a 2 (90%) or a 4 (10%) in a random empty cell and returns the new board.
+ * A full board is returned unchanged (as a copy).
+ */
+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

@@ -0,0 +1,112 @@
+/**
+ * Pure game logic for 2048.
+ *
+ * A board is a square grid of numbers where 0 means "empty". Every function
+ * returns a new board and never mutates its input, touches the DOM, or reads
+ * global state. Randomness is injected through an `rng` argument.
+ */
+export const DIRECTIONS = ['up', 'down', 'left', 'right'];
+/** Creates an empty `size` × `size` board. */
+export function createBoard(size = 4) {
+    return Array.from({ length: size }, () => Array(size).fill(0));
+}
+/**
+ * Cells of each line, ordered from the edge the tiles slide towards.
+ * Moving left, row 0 is read left to right; moving down, column 0 is read
+ * bottom to top; and so on.
+ */
+function linesFor(size, direction) {
+    const indices = [...Array(size).keys()];
+    const reversed = [...indices].reverse();
+    switch (direction) {
+        case 'left':
+            return indices.map((row) => indices.map((col) => ({ row, col })));
+        case 'right':
+            return indices.map((row) => reversed.map((col) => ({ row, col })));
+        case 'up':
+            return indices.map((col) => indices.map((row) => ({ row, col })));
+        case 'down':
+            return indices.map((col) => reversed.map((row) => ({ row, col })));
+    }
+}
+/**
+ * Slides every tile towards `direction`, merging equal neighbours once each,
+ * and reports where every tile went.
+ */
+export function moveWithDetails(board, direction) {
+    const next = createBoard(board.length);
+    const moves = [];
+    const merges = [];
+    let points = 0;
+    for (const line of linesFor(board.length, direction)) {
+        let write = 0;
+        // Index in `line` of the last placed tile that may still merge.
+        let mergeable = -1;
+        for (const from of line) {
+            const value = board[from.row][from.col];
+            if (value === 0)
+                continue;
+            const previous = mergeable >= 0 ? line[mergeable] : undefined;
+            if (previous && next[previous.row][previous.col] === value) {
+                const merged = value * 2;
+                next[previous.row][previous.col] = merged;
+                moves.push({ from, to: previous });
+                merges.push({ at: previous, value: merged });
+                points += merged;
+                mergeable = -1;
+            }
+            else {
+                const to = line[write];
+                next[to.row][to.col] = value;
+                moves.push({ from, to });
+                mergeable = write;
+                write += 1;
+            }
+        }
+    }
+    const changed = moves.some(({ from, to }) => from.row !== to.row || from.col !== to.col);
+    return { board: next, moves, merges, points, changed };
+}
+/** Slides and merges every tile in `direction` and returns the new board. */
+export function move(board, direction) {
+    return moveWithDetails(board, direction).board;
+}
+/** True if moving in `direction` would change the board. */
+export function canMove(board, direction) {
+    return moveWithDetails(board, direction).changed;
+}
+/** True if any direction would still change the board; false means game over. */
+export function hasMoves(board) {
+    return DIRECTIONS.some((direction) => canMove(board, direction));
+}
+/** Positions of every empty cell, in reading order. */
+export function emptyCells(board) {
+    const cells = [];
+    board.forEach((row, r) => row.forEach((value, c) => {
+        if (value === 0)
+            cells.push({ row: r, col: c });
+    }));
+    return cells;
+}
+/**
+ * Puts a 2 (90%) or a 4 (10%) in a random empty cell and returns the new board.
+ * A full board is returned unchanged (as a copy).
+ */
+export function spawn(board, rng = Math.random) {
+    const next = board.map((row) => [...row]);
+    const cells = emptyCells(board);
+    if (cells.length === 0)
+        return next;
+    const cell = cells[Math.floor(rng() * cells.length)];
+    next[cell.row][cell.col] = rng() < 0.9 ? 2 : 4;
+    return next;
+}
+/** The largest tile on the board. */
+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,46 @@
-{
-  "name": "@zixial3/arcade-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@zixial3/arcade-core",
+  "version": "1.1.0",
+  "description": "Pure, framework-free game logic for 2048.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test",
+    "prebuild": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
+  },
+  "keywords": [
+    "2048",
+    "game",
+    "puzzle"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zixial3/arcade-core.git"
+  },
+  "homepage": "https://github.com/zixial3/arcade-core#readme",
+  "bugs": {
+    "url": "https://github.com/zixial3/arcade-core/issues"
+  },
+  "author": "Zixiao Liu"
+}