@aminuose/arcade-core 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 1.0.0
+
+Initial release.
+
+- `move(board, direction)` slides and merges tiles in any direction and returns a new board.
+- `spawn(board, rng?)` places a 2 or 4 in a random empty cell, with an optional `rng` for repeatable results.
+- `hasMoves(board)` reports whether the game can continue.
+- `canMove(board, direction)` reports whether a single direction would change the board.
+- `slide(board, direction)` does the same as `move` and also returns the points earned by the merges.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @aminuose/arcade-core
 
-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.
+Pure game logic for 2048. Every function takes a board and returns a new one, with no side effects. The package does not import Svelte, does not touch the DOM, and runs under plain Node or in any browser.
+
+## Install
+
+```sh
+npm install @aminuose/arcade-core
+```
+
+## Usage
+
+```js
+import { move, spawn, hasMoves, canMove } from '@aminuose/arcade-core';
+
+let board = [
+  [0, 0, 0, 0],
+  [0, 0, 0, 0],
+  [0, 0, 0, 0],
+  [0, 0, 0, 0],
+];
+
+board = spawn(spawn(board));
+
+if (canMove(board, 'left')) {
+  board = spawn(move(board, 'left'));
+}
+
+if (!hasMoves(board)) {
+  console.log('Game over');
+}
+```
+
+## Board and directions
+
+A board is a 4×4 array of rows. `0` is an empty cell and every other value is a tile.
+Directions are `'left'`, `'right'`, `'up'`, and `'down'`.
+
+## API
+
+### `move(board, direction)`
+
+Slides every tile as far as it can go in `direction`, merges equal neighbours once each, and returns the new board. The input board is not modified. Throws if `direction` is not one of the four above.
+
+```js
+move([[2, 2, 2, 2], [0, 0, 0, 0], [0, 0, 0, 0], [0, 0, 0, 0]], 'left')[0];
+// [4, 4, 0, 0]
+```
+
+A tile merges at most once per move, so `2 2 2 2` becomes `4 4` and `4 4 8` becomes `8 8`.
+
+### `spawn(board, rng?)`
+
+Puts a new `2` (90% of the time) or `4` (10%) in a random empty cell and returns the new board. If the board is full, an unchanged copy is returned.
+
+`rng` is an optional function that returns a number in `[0, 1)`. It defaults to `Math.random`. It is called once to pick the cell and once to pick the value, so the same sequence of values always produces the same board.
+
+### `hasMoves(board)`
+
+Returns `true` if any direction would still change the board, and `false` when the game is over.
+
+### `canMove(board, direction)`
+
+Returns `true` if sliding in `direction` would change the board, and `false` if nothing would happen. A move that changes nothing should not spawn a new tile.
+
+### `slide(board, direction)`
+
+Does the same work as `move` and also reports the points earned. Returns `{ board, gained }`, where `gained` is the total of every tile created by a merge.
+
+```js
+slide([[2, 2, 4, 4], [0, 0, 0, 0], [0, 0, 0, 0], [0, 0, 0, 0]], 'left').gained;
+// 4 + 8 = 12
+```
+
+## Development
+
+```sh
+npm test
+```

package/package.json

@@ -1,6 +1,13 @@
 {
   "name": "@aminuose/arcade-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Pure game logic for 2048: move, spawn, hasMoves, and canMove.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": "./src/index.js",
+  "files": ["src", "CHANGELOG.md"],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": ["2048", "game", "arcade"]
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { move, slide } from './move.js';
+export { spawn } from './spawn.js';
+export { hasMoves, canMove } from './moves.js';

package/src/mergeRow.js

@@ -0,0 +1,29 @@
+/**
+ * Slides one row toward index 0 and merges equal neighbours.
+ * Each tile merges at most once per call.
+ *
+ * @param {number[]} row
+ * @returns {{ row: number[], gained: number }} the new row and the points earned
+ */
+export function mergeRow(row) {
+  const tiles = row.filter((value) => value !== 0);
+  const merged = [];
+  let gained = 0;
+
+  for (let i = 0; i < tiles.length; i++) {
+    if (tiles[i] === tiles[i + 1]) {
+      const value = tiles[i] * 2;
+      merged.push(value);
+      gained += value;
+      i++;
+    } else {
+      merged.push(tiles[i]);
+    }
+  }
+
+  while (merged.length < row.length) {
+    merged.push(0);
+  }
+
+  return { row: merged, gained };
+}

package/src/move.js

@@ -0,0 +1,45 @@
+import { mergeRow } from './mergeRow.js';
+
+const DIRECTIONS = ['left', 'right', 'up', 'down'];
+
+const transpose = (board) => board[0].map((_, col) => board.map((row) => row[col]));
+
+/**
+ * Same as move, but also reports the points earned by the merges.
+ *
+ * @param {number[][]} board
+ * @param {'left' | 'right' | 'up' | 'down'} direction
+ * @returns {{ board: number[][], gained: number }}
+ */
+export function slide(board, direction) {
+  if (!DIRECTIONS.includes(direction)) {
+    throw new Error(`Unknown direction: ${direction}`);
+  }
+
+  const vertical = direction === 'up' || direction === 'down';
+  const reversed = direction === 'right' || direction === 'down';
+
+  let lines = vertical ? transpose(board) : board;
+  let gained = 0;
+
+  lines = lines.map((line) => {
+    const input = reversed ? [...line].reverse() : line;
+    const result = mergeRow(input);
+    gained += result.gained;
+    return reversed ? result.row.reverse() : result.row;
+  });
+
+  return { board: vertical ? transpose(lines) : lines, gained };
+}
+
+/**
+ * Slides every tile as far as it can go in the given direction and merges
+ * equal neighbours once each. Returns a new board; the input is not modified.
+ *
+ * @param {number[][]} board
+ * @param {'left' | 'right' | 'up' | 'down'} direction
+ * @returns {number[][]}
+ */
+export function move(board, direction) {
+  return slide(board, direction).board;
+}

package/src/moves.js

@@ -0,0 +1,26 @@
+import { move } from './move.js';
+
+const DIRECTIONS = ['left', 'right', 'up', 'down'];
+
+const sameBoard = (a, b) => a.every((row, r) => row.every((value, c) => value === b[r][c]));
+
+/**
+ * Whether sliding in the given direction would change the board.
+ *
+ * @param {number[][]} board
+ * @param {'left' | 'right' | 'up' | 'down'} direction
+ * @returns {boolean}
+ */
+export function canMove(board, direction) {
+  return !sameBoard(board, move(board, direction));
+}
+
+/**
+ * Whether any direction would still change the board. False means game over.
+ *
+ * @param {number[][]} board
+ * @returns {boolean}
+ */
+export function hasMoves(board) {
+  return DIRECTIONS.some((direction) => canMove(board, direction));
+}

package/src/spawn.js

@@ -0,0 +1,26 @@
+const FOUR_CHANCE = 0.1;
+
+/**
+ * Puts a new 2 (90%) or 4 (10%) in a random empty cell. Returns a new board;
+ * a full board is returned as an unchanged copy.
+ *
+ * @param {number[][]} board
+ * @param {() => number} [rng] returns a number in [0, 1), defaults to Math.random
+ * @returns {number[][]}
+ */
+export function spawn(board, rng = Math.random) {
+  const next = board.map((row) => [...row]);
+  const empty = [];
+
+  next.forEach((row, r) => {
+    row.forEach((value, c) => {
+      if (value === 0) empty.push([r, c]);
+    });
+  });
+
+  if (empty.length === 0) return next;
+
+  const [r, c] = empty[Math.floor(rng() * empty.length)];
+  next[r][c] = rng() < FOUR_CHANCE ? 4 : 2;
+  return next;
+}