Scripting API

Scripting API

GameRandom

Class in Abyss.Core, from Abyss.Core.

Random numbers for a game: a stream of them from a seed, the same stream for the same seed on every system — new GameRandom(seed).Range(0, 6) — and, without one, GameRandom.Shared. And numbers that are not a stream at all but a function of where: GameRandom.Hash gives the same number for the same seed and place every time it is asked, which is what lets a world made from a seed be made again, a piece at a time, in any order.

public sealed class GameRandom

Remarks

A stream is PCG32 (Melissa O'Neill, pcg-random.org): small, fast, and good enough for anything but cryptography — System.Security.Cryptography.RandomNumberGenerator is for that. One instance is for one thread; GameRandom.Shared is one per thread. The numbers a seed gives, and every hash, are kept the same from one engine version to the next, since a saved world depends on them.

Constructors

GameRandom

public GameRandom(ulong seed)

A stream of numbers from seed: the same seed, the same numbers.

Parameters

  • seed

GameRandom

public GameRandom()

A stream of numbers from a seed nobody chose: different each time.

The clock and the count of streams made are mixed each on its own before they meet: XORed as they were, a clock one tick on and a count one more cancelled where both were even, and two streams made one after the other were the same.

Properties

Shared

public static GameRandom Shared { get; }

A stream for this thread, seeded by nobody: for numbers that need not come again.

Methods

NextUInt

public uint NextUInt()

The next number, any of the 2³² there are.

NextFloat

public float NextFloat()

The next number from 0 up to but not 1.

Range

public int Range(int min, int maxExclusive)

A whole number from min up to but not maxExclusive, each as likely as the next — Range(1, 7) is a die.

Parameters

  • min
  • maxExclusive

Exceptions

  • ArgumentOutOfRangeException: maxExclusive is not above min.

Range

public float Range(float min, float max)

A number from min up to max.

Parameters

  • min
  • max

Chance

public bool Chance(float probability)

True as often as probability says: 0.25 one time in four.

Parameters

  • probability

OnUnitCircle

public Vector2 OnUnitCircle()

A point on the circle of radius 1 about the origin, every direction as likely.

InsideUnitCircle

public Vector2 InsideUnitCircle()

A point inside the circle of radius 1, every part of it as likely.

OnUnitSphere

public Vector3 OnUnitSphere()

A point on the sphere of radius 1 about the origin, every direction as likely.

InsideUnitSphere

public Vector3 InsideUnitSphere()

A point inside the sphere of radius 1, every part of it as likely.

Rotation

public Quaternion Rotation()

A turn, every one as likely (Ken Shoemake's uniform rotation).

Pick<T>

public T Pick<T>(ReadOnlySpan<T> items)

One of items, each as likely.

Type parameters

  • T

Parameters

  • items

Exceptions

  • ArgumentException: There are none.

Pick<T>

public T Pick<T>(IReadOnlyList<T> items)

One of items, each as likely.

Type parameters

  • T

Parameters

  • items

Exceptions

  • ArgumentException: There are none.

Shuffle<T>

public void Shuffle<T>(Span<T> items)

Puts items in an order every order is as likely as (Fisher and Yates).

Type parameters

  • T

Parameters

  • items

Hash

public static uint Hash(int seed, int x)

A number made of seed and a place along a line, the same every time.

Parameters

  • seed
  • x

Hash

public static uint Hash(int seed, int x, int y)

A number made of seed and a place on a grid, the same every time.

Parameters

  • seed
  • x
  • y

Hash

public static uint Hash(int seed, int x, int y, int z)

A number made of seed and a place in a grid, the same every time — whether a tree stands at a column, which ore a block is — so a world made from a seed comes out the same whichever part of it is made first.

Parameters

  • seed
  • x
  • y
  • z

Hash01

public static float Hash01(int seed, int x, int y, int z)

GameRandom.Hash as a number from 0 up to but not 1.

Parameters

  • seed
  • x
  • y
  • z