esinxe

Version 1.1.0 · algorithm v1

esinxe is a polyglot deterministic random field for procedural software. Give it a seed and a structured key, and it returns the same value in Python, C, C++, C#, Ruby, JavaScript/TypeScript, Rust, Go, Java, and Kotlin. No prior values need to be generated, and work can be split across machines without changing the result.

import esinxe

world = esinxe.Random(20260611)

height = world.at2D(chunk_x, chunk_y, "terrain")
enemy = world.choose(
    ["archer", "scout", "guardian"],
    "enemy",
    esinxe.i64(chunk_x),
    esinxe.i64(chunk_y),
)
loot = world.weightedChoice(
    ["common", "rare", "legendary"],
    [80, 18, 2],
    "loot",
    esinxe.i64(chunk_x),
    esinxe.i64(chunk_y),
)

The output is intentionally predictable. esinxe is not cryptographic. Never use it for secrets, tokens, gambling, lotteries, or security decisions.

Project Guide

Need	Start here
Copy a language example	Language quick starts
Understand every operation	API reference
Implement or verify a port	Algorithm v1 specification
Understand design boundaries	Architecture
Review statistical evidence	RNG analysis
Contribute a change	Contributing guide
Report a vulnerability	Security policy

What It Solves

• Generate a world chunk independently while keeping borders and content stable.
• Regenerate loot, encounters, fixtures, or test data from durable identifiers.
• Partition simulation or sampling jobs without assigning mutable RNG streams.
• Add or remove unrelated generated features without shifting existing results.
• Reproduce a failure from the exact seed and structured key that produced it.

esinxe is not a noise library: adjacent coordinates are independent, not smooth. It is also not a replacement for a scientifically validated Monte Carlo generator. A future noise module can build spatial interpolation on top of this keyed core without changing algorithm v1.

Stable v1 API

Each seeded field provides:

• raw(key...): full unsigned 64-bit value.
• int(max, key...): unbiased [0, max) integer.
• range(min, max, key...): unbiased [min, max) integer.
• float01(key...): upper 53 bits mapped to [0, 1).
• at2D(x, y, namespace?) and at3D(x, y, z, namespace?).
• chanceRatio(numerator, denominator, key...).
• choose(items, key...).
• shuffle(items, key...): deterministic Fisher-Yates copy.
• weightedChoice(items, integerWeights, key...).

Structured keys support signed int64, unsigned uint64, UTF-8 strings, and bytes. Use explicit signed/unsigned constructors in compatibility-sensitive code. Integer weights and rational probabilities are the portable conformance surface; floating wrappers are deliberately excluded.

The formal byte encoding, FNV-1a pass, rejection sampling, mixer, domains, and error rules are frozen in SPEC_V1.md. Golden outputs live in tests/vectors-v1.json and are generated by scripts/generate_vectors.py.

Existing Stream API

The original Next* family remains compatible:

• Next() / NextRaw() advance a stream.
• NextAt(offset) / NextRawAt(offset) address an offset directly.
• NextMax*, NextMinMax*, and list helpers retain their existing behavior.

Keyed calls read only the seed and never alter stream position.

Try It

Use the hosted deterministic field inspector, or run it locally:

python3 -m http.server 8765

Then visit http://localhost:8765/demo/. Change the seed, namespace, display mode, and language snippet while inspecting the same deterministic 2D field.

Per-language examples are collected in docs/QUICK_STARTS.md. Runnable Python examples cover procedural world content and partition-independent jobs.

Benchmarks

Python 3.9 on Apple silicon, best of five, 200,000 values, native extension enabled. These categories are intentionally separated because keyed hashing, stream stepping, and native batches solve different jobs.

Category	Operation	Values/second
Random access	raw(u64(i))	147,813
Random access	NextRawAt(i)	727,349
Sequential	NextRaw()	756,255
Sequential	Next()	365,370
Sequential	NextMax(100)	435,483
Batch	NextList(N)	11,778,823
Batch	NextListMax(N, 100)	54,397,109

Regenerate locally with:

python3 setup.py build_ext --inplace
ESINXE_BENCH_N=200000 python3 scripts/benchmark.py

Install and Publication Status

The repository is the source of truth until registry access is available.

Port	Version	Registry status	Source install
Python	1.1.0	Not published	python3 -m pip install -e .
JavaScript/TypeScript	1.1.0	Not published	import JavaScript/src/index.js
Rust	1.1.0	Not published	path dependency on Rust/
Go	algorithm v1	Not published	local module under Go/
Java/Kotlin	algorithm v1	Not published	compile sources under JVM/
C/C++/C#/Ruby	algorithm v1	Not published	include/load repository sources

The historical Python/Esinxepy1-0-0.py filename remains a compatibility shim.

Verification

Run all available compiler, conformance, statistical, native-extension, and packaging checks:

./scripts/ci.sh

The script explicitly names missing toolchains instead of treating them as a pass. Statistical conclusions remain bounded to the included sample sizes; see docs/RNG_ANALYSIS.md for the practical quality verdict.

Project Policy

Algorithm compatibility follows the versioning policy. Changes are recorded in the changelog, releases follow the release checklist, and community help is described in SUPPORT.md. Contributions are governed by the Code of Conduct.