@aminuose/arcade-core 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 1.0.1
+
+No changes to the game logic.
+
+- Added `repository`, `bugs`, and `homepage` to `package.json`, so the npm page links to the GitHub repository.
+- Added a Svelte 5 example to the README that shows `slide`, `canMove`, `hasMoves`, and `spawn` working together.
+
+## 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,116 @@
-# 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');
+}
+```
+
+## Using it in a Svelte 5 app
+
+The package never imports Svelte, so the component below is the only place that knows about it. It keeps the board in `$state`, derives game over from it, and uses `slide` to get the points for each move.
+
+```svelte
+<script>
+  import { slide, spawn, canMove, hasMoves } from '@aminuose/arcade-core';
+
+  const emptyBoard = () => Array.from({ length: 4 }, () => [0, 0, 0, 0]);
+  const keys = { ArrowLeft: 'left', ArrowRight: 'right', ArrowUp: 'up', ArrowDown: 'down' };
+
+  let board = $state(spawn(spawn(emptyBoard())));
+  let score = $state(0);
+  let gameOver = $derived(!hasMoves(board));
+
+  function play(direction) {
+    if (!canMove(board, direction)) return;
+    const result = slide(board, direction);
+    board = spawn(result.board);
+    score += result.gained;
+  }
+
+  function onkeydown(event) {
+    const direction = keys[event.key];
+    if (direction) {
+      event.preventDefault();
+      play(direction);
+    }
+  }
+</script>
+
+<svelte:window {onkeydown} />
+
+<p>Score: {score}</p>
+{#if gameOver}<p>Game over</p>{/if}
+```
+
+## 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,21 @@
 {
   "name": "@aminuose/arcade-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "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"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AMINUOSE/arcade-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AMINUOSE/arcade-core/issues"
+  },
+  "homepage": "https://github.com/AMINUOSE/arcade-core#readme"
+}

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;
+}