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| Setting | What it does | Default |
|---|---|---|
Seed | Which of the possible patterns: another seed, another world. | 0 |
Kind | The pattern each layer makes; see the table below. | Simplex |
Frequency | How 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 |
Fractal | How layers are summed; None is one layer. | None |
Octaves | How many layers a fractal sums, from 1 to 16. | 3 |
Lacunarity | How much finer each layer is than the last: 2 halves its features. | 2 |
Gain | How 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
| Kind | What it makes |
|---|---|
Perlin | Smooth 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. |
Simplex | As smooth as Perlin, with fewer runs along the grid's lines, and cheaper in 3D. |
Value | Soft blobs: a value at each corner of a grid, blended between them. |
Cellular | Cells: 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. |
Cells | Regions: the value of the nearest scattered point, the same across its whole cell. Patches such as biomes. |
Fractals
| Fractal | What it makes |
|---|---|
None | One layer. |
Fbm | Layers, each finer and fainter than the last: mountains with hills on them and bumps on those. |
Ridged | Layers folded at 0 into sharp crests: ridges, ranges, veins. |
Billow | Layers 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| Member | What 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
- Noise, NoiseKind and NoiseFractal: smooth randomness.
- GameRandom: streams of random numbers, and hashes of places.
