🎮 gamekit-utils

Minimal, fast and useful utilities for randomness, array manipulation and math — built for games, UI logic and generative design.

Lightweight toolkit for game developers, creative coders, and UI experimenters.

✅ What's the promise?

We're building a tiny, powerful toolkit for developers who create:

• 🎲 casual games
• 🧠 game logic systems
• ✨ creative procedural content
• 🧩 UI components with randomized behavior

Everything will be:

• [x] 🟢 Written in TypeScript
• [x] 🌳 Fully tree-shakable (ESM only)
• [x] 📦 Zero-dependency
• [x] 📘 Documented with practical examples
• [x] 🔬 Covered with unit tests (Vitest)
• [x] 🧪 100% test coverage
• [x] 🔄 Publish-ready as v1.0.0

🧪 Core Modules

| Status | Function | Description | |--------|--------------------------|--------------------------------------------| | ✅ | random(arr) | Pick a random element from a non-empty array | | ✅ | shuffle(arr) | Shuffle an array using Fisher–Yates | | ✅ | pickN(arr, n) | Pick N unique random elements | | ✅ | chance(percent) | Return true with a probability | | ✅ | clamp(val, min, max) | Clamp number within bounds | | ✅ | lerp(a, b, t) | Linear interpolation | | ✅ | normalize(a, b, t) | Normalize a value to a 0-1 range | | ✅ | create2D(rows, cols, fn) | Create a 2D array filled with a default value | | ✅ | getNeighbors(row, col, grid, diagonal) | Get neighbors of a cell in a 2D grid | | ✅ | pulse(from, to, phase, cycle) | Check if a phase is within a cyclic range |

⚡ Usage Examples

🎲 random

Picks a random element from a non-empty array.

import { random } from "gamekit-utils";

const enemies = ["orc", "troll", "goblin"];
const chosen: string = random(enemies);

console.log(chosen); // → e.g., "troll"

🔀 shuffle

Returns a shuffled copy of the original array (non-mutating).

import { shuffle } from "gamekit-utils";

const deck = [1, 2, 3, 4, 5];
const shuffled: number[] = shuffle(deck);

console.log(shuffled); // → e.g., [4, 1, 5, 3, 2]
console.log(deck);     // → original remains: [1, 2, 3, 4, 5]

🎯 pickN

Returns N unique random elements from the array (non-mutating).

import { pickN } from "gamekit-utils";

const names = ["Alice", "Bob", "Charlie", "Dave"];
const group = pickN(names, 2); // → e.g., ["Charlie", "Alice"]

🎰 chance

Returns true with a given probability (0–100%).

import { chance } from "gamekit-utils";

if (chance(30)) {
  console.log("You got lucky!"); // ~30% chance
}

📉 clamp

Clamps a number between min and max bounds.

import { clamp } from "gamekit-utils";

const hp = clamp(player.hp, 0, 100);
console.log(hp); // → between 0 and 100

📏 lerp

Returns a value interpolated between two numbers based on a ratio.

import { lerp } from "gamekit-utils";

const value = lerp(10, 20, 0.5);
console.log(value); // → 15

📏 normalize

Normalizes a value t from the range [a, b] to [0, 1].

import { normalize } from "gamekit-utils";

const n1 = normalize(10, 20, 15); // → 0.5
const n2 = normalize(0, 100, 25); // → 0.25

Grid Utilities

📐 create2D

Creates a 2D array of given size, filled with a default value.

import { create2D } from "gamekit-utils";

const grid = create2D(3, 4, 0);
/*
[
  [0, 0, 0, 0],
  [0, 0, 0, 0],
  [0, 0, 0, 0]
]
*/

🧭 getNeighbors

Returns the existing neighbors of a cell in a 2D grid.

import { getNeighbors } from "gamekit-utils";

const grid = [
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9],
];

getNeighbors(1, 1, grid);
// → [
//   { row: 0, col: 1, value: 2 },
//   { row: 2, col: 1, value: 8 },
//   { row: 1, col: 0, value: 4 },
//   { row: 1, col: 2, value: 6 }
// ]

⚡ pulse

Checks if the given phase is within the specified range in a cyclic manner.

import { pulse } from "gamekit-utils";

const isActive = pulse(0, 5, 3, 10);
console.log(isActive); // → 1


for (let i = 0; i < 11; i++) {
  console.log(i, pulse(0, 3, i, 5));
}

     i:  0   1   2   3   4   5   6   7   8   9   10
output:  1   1   1   0   0   1   1   1   0   0   1

📦 Installation

npm install gamekit-utils
# or
yarn add gamekit-utils

🧪 Core Modules (roadmap)

| Function | Since | Tested | Docs | Status | |---------------------|---------|--------|------|---------| | random(arr) | 0.0.1 | ✅ | ✅ | ✅ Done | | shuffle(arr) | 0.0.5 | ✅ | ✅ | ✅ Done | | pickN(arr, n) | 0.0.6 | ✅ | ✅ | ✅ Done | | chance(percent) | 0.0.7 | ✅ | ✅ | ✅ Done | | clamp(val, min, max) | 0.0.8 | ✅ | ✅ | ✅ Done | | lerp(a, b, t) | 0.0.9 | ✅ | ✅ | ✅ Done | | normalize(a, b, t) | 0.1.0 | ✅ | ✅ | ✅ Done | | create2D(rows, cols, fn) | 0.1.1 | ✅ | ✅ | ✅ Done | | getNeighbors(row, col, grid, diagonal) | 0.1.2 | ✅ | ✅ | ✅ Done | | pulse(from, to, phase, cycle) | 0.1.4 | ✅ | ✅ | ✅ Done |

💡 Author

Oleh Levchenko
GitHub: @leva13007
Support: buymeacoffee.com/zloyleva

📄 License

MIT © Oleh Levchenko