Manual

Manual

Noise and random numbers

Abyss gives a game two kinds of randomness that come out the same every time for the same seed. Noise is smooth: a number for each place that changes gently from place to place, what terrain, caves and clouds are made of. GameRandom is a stream of independent numbers, for dice, spawn points and loot, and a hash that turns a place into a number without keeping anything.

Both give the same numbers for the same seed on every machine, and keep giving them from one engine version to the next, since a world saved as a seed depends on them.

Noise

A Noise is a value: make one with its settings, and sample it anywhere. It allocates nothing and is safe to use from any number of threads at once, parallel systems' slices included.

var hills = new Noise(seed){    Kind = NoiseKind.Simplex,    Frequency = 1f / 128,    Fractal = NoiseFractal.Fbm,    Octaves = 5,};
float height = 64 + (24 * hills.Sample(x, z));   // a number from -1 to 1, scaled to 40 to 88
SettingWhat it doesDefault
SeedWhich of the possible patterns: another seed, another world.0
KindThe pattern each layer makes; see the table below.Simplex
FrequencyHow many features to a unit: places are multiplied by it first. 1/128 puts features about 128 units apart.0.01, about 100 units apart
FractalHow layers are summed; None is one layer.None
OctavesHow many layers a fractal sums, from 1 to 16.3
LacunarityHow much finer each layer is than the last: 2 halves its features.2
GainHow much fainter each layer is than the last: 0.5 halves it.0.5

Noise is a record struct, so a variation is a copy with one setting changed: hills with { Seed = seed + 1 }.

Kinds

KindWhat it makes
PerlinSmooth hills and hollows, from a gradient at each corner of a square grid. It is 0 at every corner, so a frequency of 1 sampled at whole numbers gives nothing but 0.
SimplexAs smooth as Perlin, with fewer runs along the grid's lines, and cheaper in 3D.
ValueSoft blobs: a value at each corner of a grid, blended between them.
CellularCells: how far a place is from the nearest of points scattered one to each square, -1 on a point and rising toward 1 between them. Cracks, scales, cobbles.
CellsRegions: the value of the nearest scattered point, the same across its whole cell. Patches such as biomes.

Fractals

FractalWhat it makes
NoneOne layer.
FbmLayers, each finer and fainter than the last: mountains with hills on them and bumps on those.
RidgedLayers folded at 0 into sharp crests: ridges, ranges, veins.
BillowLayers folded at 0 into round heaps: clouds, rolling dunes.

Every kind and fractal stays within -1 to 1. Perlin and simplex noise rarely go past ±0.9.

Sampling

Sample(x, y) reads the noise on a plane and Sample(x, y, z) in space. For a whole grid, Fill is faster than a sample at a time:

// A 16 by 16 heightmap, one unit apart, from (x0, z0): the place (i, j) is heights[j * 16 + i].Span<float> heights = stackalloc float[16 * 16];hills.Fill(heights, x0, z0, 16, 16);
// A 16 by 16 by 16 block, the place (i, j, k) at caves[(k * 16 + j) * 16 + i].var holes = new Noise(seed + 1) { Kind = NoiseKind.Cellular, Frequency = 1f / 24 };float[] caves = new float[16 * 16 * 16];holes.Fill(caves, x0, y0, z0, 16, 16, 16);

Both take a last step, the distance between places, 1 unless you pass another. The span must hold at least width × height (× depth) numbers, or the call throws.

Warping

Warp(x, y, amplitude) pushes a place up to amplitude units each way by the noise. Sampling another noise at the pushed place makes it swirl and fold instead of lying in even bands:

var push = new Noise(seed + 7) { Frequency = 1f / 200 };(float wx, float wz) = push.Warp(x, z, 40f);float height = hills.Sample(wx, wz);

Warp(x, y, z, amplitude) does the same in space.

Random numbers

A GameRandom is a stream of numbers from a seed, a ulong: the same seed gives the same numbers, in the same order, everywhere.

var random = new GameRandom(20261109);
int roll = random.Range(1, 7);                     // a die: 1 to 6float spread = random.Range(-0.5f, 0.5f);bool rare = random.Chance(0.05f);                  // one time in twentyVector3 aim = random.OnUnitSphere();Quaternion turn = random.Rotation();string loot = random.Pick(drops);                  // drops: a span or a listrandom.Shuffle(deck);                              // deck: a span
MemberWhat it gives
NextUInt()Any of the 2³² whole numbers.
NextFloat()A number from 0 up to, but not, 1.
Range(int min, int maxExclusive)A whole number from min up to, but not, maxExclusive, each as likely.
Range(float min, float max)A number from min up to max.
Chance(probability)True as often as the probability says: 0.25 one time in four.
OnUnitCircle(), InsideUnitCircle()A point on, or inside, the circle of radius 1, every direction or part as likely.
OnUnitSphere(), InsideUnitSphere()A point on, or inside, the sphere of radius 1.
Rotation()A rotation, every one as likely.
Pick(items)One of the items, each as likely; throws for none.
Shuffle(items)Puts the items in an order every order is as likely as.

new GameRandom(), with no seed, starts a stream different each time. GameRandom.Shared is a stream of that kind kept for each thread, for numbers that never need to come again.

A stream is PCG32: small, fast and good for anything but security. For keys and tokens use .NET's System.Security.Cryptography.RandomNumberGenerator.

One GameRandom is for one thread. Inside a parallel system's slices, use GameRandom.Shared, which each thread has its own of, or a hash. A GameRandom is a class, so it cannot be a component's field: keep it in a plugin's field or a service, or keep a seed in the component and hash from it.

Numbers made of a place

GameRandom.Hash(seed, x, y, z) is a whole number made of a seed and a place, the same every time it is asked. Its seed is an int, as a Noise's is. Nothing is kept between calls, so a world made from a seed comes out the same whichever part of it is made first, and any thread can ask:

// Whether a tree stands at this column of the world.bool tree = GameRandom.Hash01(seed, x, 0, z) < 0.02f;
// Which of eight ores a block is.int ore = (int)(GameRandom.Hash(seed, x, y, z) % 8);

Hash(seed, x) and Hash(seed, x, y) take a place on a line and on a grid. Hash01(seed, x, y, z) is the hash as a number from 0 up to, but not, 1.

Give each use its own seed, such as the world's seed plus a number for each, so the trees do not follow the ore.

In the Scripting API