nicerand

A "nice" random library for video games and applications where true randomness feels unfair.

Available in: Python | C++ | TypeScript

The Problem

True randomness doesn't feel random to humans. When your game plays the same background song twice in a row, or drops the same loot three times consecutively, players think "this is broken" — even though it's statistically valid.

The Solution

nicerand provides random selection with memory. It tracks recent picks and prevents items from repeating until a cooldown period has passed.

from nicerand import NiceRandom

playlist = NiceRandom(["rock", "jazz", "electronic", "classical", "pop"])
song = playlist.pick()  # Won't repeat immediately (default cooldown: 1)

# For shuffle bag (all items before any repeat):
items = ["A", "B", "C", "D", "E"]
bag = NiceRandom(items, cooldown=len(items))

Features

• Cooldown-based selection — Items can't repeat until N other items have been picked
• Simple default — cooldown=1 prevents immediate repeats (the most common complaint)
• Shuffle bag mode — Set cooldown=len(items) for full rotation before any repeat
• Weighted support — Some items can appear more frequently (while still respecting cooldowns)
• Zero dependencies — Pure implementations, no external libraries required

Language Support

Language	Install	Docs
Python	pip install nicerand	python/README.md
C++	Header-only (C++17)	cpp/README.md
TypeScript	npm install nicerand	typescript/README.md

How It Works

1. Maintain a history queue of recently picked items
2. When picking, exclude items currently in the history
3. Randomly select from the remaining available items
4. Add the picked item to the history (oldest items fall off)

This creates the illusion of "fair" randomness that players expect.

Prior Art

• Shuffle bags
• "No repeat" shuffle algorithms (music players)
• Pseudo-random distribution (Dota 2 critical hits)

License

MIT