Minimal, fast and useful utilities for randomness, array manipulation and math โ built for games, UI logic and generative design.
npm install gamekit-utilsMinimal, 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.
---
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
---
| 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 |
---
Picks a random element from a non-empty array.
``ts
import { random } from "gamekit-utils";
const enemies = ["orc", "troll", "goblin"];
const chosen: string = random(enemies);
console.log(chosen); // โ e.g., "troll"
`
Returns a shuffled copy of the original array (non-mutating).
`ts
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]
`
Returns N unique random elements from the array (non-mutating).
`ts
import { pickN } from "gamekit-utils";
const names = ["Alice", "Bob", "Charlie", "Dave"];
const group = pickN(names, 2); // โ e.g., ["Charlie", "Alice"]
`
Returns true with a given probability (0โ100%).
`ts
import { chance } from "gamekit-utils";
if (chance(30)) {
console.log("You got lucky!"); // ~30% chance
}
`
Clamps a number between min and max bounds.
`ts
import { clamp } from "gamekit-utils";
const hp = clamp(player.hp, 0, 100);
console.log(hp); // โ between 0 and 100
`
Returns a value interpolated between two numbers based on a ratio.
`ts
import { lerp } from "gamekit-utils";
const value = lerp(10, 20, 0.5);
console.log(value); // โ 15
`
Normalizes a value t from the range [a, b] to [0, 1].
`ts
import { normalize } from "gamekit-utils";
const n1 = normalize(10, 20, 15); // โ 0.5
const n2 = normalize(0, 100, 25); // โ 0.25
`
Creates a 2D array of given size, filled with a default value.
`ts
import { create2D } from "gamekit-utils";
const grid = create2D(3, 4, 0);
/*
[
[0, 0, 0, 0],
[0, 0, 0, 0],
[0, 0, 0, 0]
]
*/
`
Returns the existing neighbors of a cell in a 2D grid.
`ts
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 }
// ]
`
Checks if the given phase is within the specified range in a cyclic manner.
`ts
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
`
`bash`
npm install gamekit-utilsor
yarn add gamekit-utils
---
| 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 |
|
---
Oleh Levchenko
GitHub: @leva13007
Support: buymeacoffee.com/zloyleva
---
MIT ยฉ Oleh Levchenko