@april-cs-npm/arcade-core 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,83 @@
-# 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.
+# @april-cs-npm/arcade-core
+
+Pure JavaScript game logic for 2048. No UI, no DOM, no framework — just
+functions that take a board and return a new board, so the same logic can run
+in Node, in tests, or inside any app.
+
+Built for the CS5610 arcade project.
+
+## Install
+
+```bash
+npm install @april-cs-npm/arcade-core
+```
+
+## The board
+
+A board is a 4×4 array of rows. Each cell is a number, where `0` means empty.
+
+```js
+const board = [
+  [2, 2, 0, 0],
+  [0, 0, 0, 0],
+  [4, 0, 0, 0],
+  [4, 0, 0, 0],
+];
+```
+
+A direction is one of: `"left"`, `"right"`, `"up"`, `"down"`.
+
+## Usage
+
+```js
+import { move, spawn, hasMoves, score } from '@april-cs-npm/arcade-core';
+
+// Slide and merge tiles. Returns a NEW board; the input is never changed.
+const afterMove = move(board, 'left');
+
+// How many points that move earned (the sum of tiles created by merges).
+const points = score(board, 'left');
+
+// Drop a new 2 or 4 into a random empty cell. Returns a NEW board.
+const afterSpawn = spawn(afterMove);
+
+// Is the game still playable? false means game over.
+const canKeepPlaying = hasMoves(afterSpawn);
+```
+
+## API
+
+### `move(board, direction)`
+Slides every tile as far as it can go in `direction`, merging equal neighbours
+once per move, and returns the new board. Does not mutate the input.
+
+### `score(board, direction)`
+Returns the points a move in `direction` would earn: the total value of every
+tile created by a merge.
+
+### `spawn(board, rng?)`
+Returns a new board with one new tile (a `2` 90% of the time, a `4` 10%) placed
+in a random empty cell. If the board is full, it is returned unchanged.
+
+`rng` is optional and defaults to `Math.random`. Pass your own function
+returning a number in `[0, 1)` to make spawning deterministic (useful for tests
+and for seeded games):
+
+```js
+const afterSpawn = spawn(board, () => 0); // always picks the first empty cell
+```
+
+### `hasMoves(board)`
+Returns `true` if any direction would change the board, and `false` when no
+move is possible (game over).
+
+## Notes
+
+- Every function is pure: it returns a new board and never changes the one you
+  pass in.
+- The package contains no Svelte and no DOM access, so it runs anywhere plain
+  JavaScript runs.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@april-cs-npm/arcade-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  
+  "description": "npm package for the 2048 logic: move, spawn, hasMoves, score",
+  "main": "src/index.js",
+  "files": ["src"],
+  "scripts": {
+    "test": "node test/core.test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aprilyanggarwood/ying-yang-arcade-core.git"
+  },
+  "keywords": [],
+  "author": "April Yang",
+  "license": "MIT",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/aprilyanggarwood/ying-yang-arcade-core/issues"
+  },
+  "homepage": "https://github.com/aprilyanggarwood/ying-yang-arcade-core#readme"
+}

package/src/hasMoves.js

@@ -0,0 +1,24 @@
+import { move } from './move.js';
+
+// true if two boards have the same contents
+function sameBoard(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function hasMoves(board) {
+  const directions = ['left', 'right', 'up', 'down'];
+
+  // if ANY direction changes the board, a move is still possible
+  for (const direction of directions) {
+    const moved = move(board, direction);
+    if (!sameBoard(moved, board)) {
+      return true;
+    }
+  }
+
+  // none of the four directions changed anything
+  return false;
+}
+
+
+export { hasMoves };

package/src/index.js

@@ -0,0 +1,4 @@
+export { move } from './move.js';
+export { spawn } from './spawn.js';
+export { hasMoves } from './hasMoves.js';
+export { score } from './score.js';

package/src/move.js

@@ -0,0 +1,64 @@
+function mergeRow(row) {
+  // STEP 1: keep only the non-zero numbers
+  const nums = row.filter((n) => n !== 0);
+
+  // STEP 2: merge equal neighbours once
+  const merged = [];
+  let i = 0;
+  while (i < nums.length) {
+    if (nums[i] === nums[i + 1]) {
+      merged.push(nums[i] + nums[i + 1]);
+      i += 2;   // skip both so they can't merge again
+    } else {
+      merged.push(nums[i]);
+      i += 1;
+    }
+  }
+
+  // STEP 3: pad with zeros until it's 4 long again
+  while (merged.length < 4) {
+    merged.push(0);
+  }
+
+  return merged;
+}
+
+function slideLeft(board) {
+  return board.map((row) => mergeRow(row));
+}
+
+
+function slideRight(board) {
+  // 1. reverse each row
+  const reversed = board.map((row) => row.slice().reverse());
+
+  // 2. slide left (reuse what you already built!)
+  const slid = slideLeft(reversed);
+
+  // 3. reverse each row back
+  return slid.map((row) => row.slice().reverse());
+}
+
+function transpose(board) {
+  return board[0].map((_, column) =>
+    board.map((row) => row[column]),
+  );
+}
+
+function move(board, direction) {
+  switch (direction) {
+    case 'left':
+      return slideLeft(board);
+    case 'right':
+      return slideRight(board);
+    case 'up':
+      return transpose(slideLeft(transpose(board)));
+    case 'down':
+      return transpose(slideRight(transpose(board)));
+    default:
+      throw new Error(`Invalid move direction: ${direction}`);
+  }
+}
+
+
+   export { mergeRow, slideLeft, slideRight, transpose, move };

package/src/score.js

@@ -0,0 +1,50 @@
+import { transpose } from './move.js';
+
+// points earned by merges in a single row when it slides left
+function rowScore(row) {
+  const nums = row.filter((n) => n !== 0);
+  let points = 0;
+  let i = 0;
+  while (i < nums.length) {
+    if (nums[i] === nums[i + 1]) {
+      points += nums[i] + nums[i + 1];   // a merge happened: add the NEW tile's value
+      i += 2;
+    } else {
+      i += 1;
+    }
+  }
+  return points;
+}
+
+// total points a move would earn in the given direction
+function score(board, direction) {
+  // reshape the board so `direction` points LEFT, the same way move() does,
+  // then sum rowScore across all rows.
+  let rows;
+  switch (direction) {
+    case 'left':
+      rows = board;
+      break;
+    case 'right':
+      rows = board.map((row) => row.slice().reverse());
+      break;
+    case 'up':
+      rows = transpose(board);
+      break;
+    case 'down':
+      rows = transpose(board).map((row) => row.slice().reverse());
+      break;
+    default:
+      throw new Error(`Invalid direction: ${direction}`);
+  }
+
+  // add up the score from every row
+  let total = 0;
+  for (const row of rows) {
+    total += rowScore(row);
+  }
+  return total;
+}
+
+
+export { score };

package/src/spawn.js

@@ -0,0 +1,31 @@
+// rng defaults to Math.random, but a caller can pass their own for testing/seeds
+function spawn(board, rng = Math.random) {
+  // 1. find all empty cells, as {row, col} positions
+  const empties = [];
+  for (let r = 0; r < board.length; r++) {
+    for (let c = 0; c < board[r].length; c++) {
+      if (board[r][c] === 0) {
+        empties.push({ r, c });
+      }
+    }
+  }
+
+  // 2. if the board is full, there is nowhere to spawn — return it unchanged
+  if (empties.length === 0) {
+    return board;
+  }
+
+  // 3. pick a random empty cell
+  const pick = empties[Math.floor(rng() * empties.length)];
+
+  // 4. decide the new tile: 90% a 2, 10% a 4 (standard 2048)
+  const value = rng() < 0.9 ? 2 : 4;
+
+  // 5. build a NEW board with that one cell changed (no mutation)
+  const next = board.map((row) => row.slice());   // copy every row
+  next[pick.r][pick.c] = value;
+  return next;
+}
+
+
+export { spawn };