Class RandomID

Provides static utility methods for generating random identifiers of various formats. Covers 32-bit and 64-bit numeric IDs, hexadecimal strings, URL-safe Base64 strings, alphanumeric strings, and RFC 4122 version 4 GUIDs.

Inheritance
object
RandomID
Inherited Members
Namespace: Scylla.Core.Util.Random
Assembly: ScyllaCore.dll
Syntax
public static class RandomID
Remarks

All generation methods accept any IRandomSource, enabling deterministic and reproducible ID generation when a seeded RNG is used. For IDs that must be cryptographically unpredictable (e.g., session tokens or security nonces), pass a CreateCrypto() source.

Numeric IDs generated by Generate32(IRandomSource) and Generate64(IRandomSource) are guaranteed to be non-zero so that the zero value (Empty32 / Empty64) can be used as a sentinel representing an absent or uninitialized ID.

Fields

Empty32

The sentinel value representing an empty or uninitialized 32-bit ID. Generate32(IRandomSource) never returns this value, so it can be used to test whether a uint ID has been assigned. Use IsEmpty(uint) for an explicit check.

Declaration
public const uint Empty32 = 0
Field Value
Type Description
uint

Empty64

The sentinel value representing an empty or uninitialized 64-bit ID. Generate64(IRandomSource) never returns this value, so it can be used to test whether a ulong ID has been assigned. Use IsEmpty(ulong) for an explicit check.

Declaration
public const ulong Empty64 = 0
Field Value
Type Description
ulong

Methods

Generate32(IRandomSource)

Generates a random non-zero 32-bit unsigned integer ID by drawing from the full [1, uint.MaxValue] range. If the underlying RNG produces zero, the draw is retried until a non-zero value is obtained. In practice, the retry probability is approximately 1 in 4 billion and is negligible.

Declaration
public static uint Generate32(IRandomSource rng)
Parameters
Type Name Description
IRandomSource rng

The random source to use for generation.
Returns
Type Description
uint

A random uint value in the range [1, uint.MaxValue]. The return value is never equal to Empty32.
Exceptions
Type Condition
ArgumentNullException

Thrown if rng is null.
See Also

Generate64(IRandomSource)

Generates a random non-zero 64-bit unsigned integer ID by drawing from the full [1, ulong.MaxValue] range. If the underlying RNG produces zero, the draw is retried until a non-zero value is obtained. The retry probability is approximately 1 in 1.8 × 1019 and is entirely negligible.

Declaration
public static ulong Generate64(IRandomSource rng)
Parameters
Type Name Description
IRandomSource rng

The random source to use for generation.
Returns
Type Description
ulong

A random ulong value in the range [1, ulong.MaxValue]. The return value is never equal to Empty64.
Exceptions
Type Condition
ArgumentNullException

Thrown if rng is null.
See Also

GenerateAlphanumeric(IRandomSource, int)

Generates a random alphanumeric string of exactly length characters. Each character is independently and uniformly sampled from the 62-character set a-z, A-Z, and 0-9, providing approximately 5.95 bits of entropy per character. Delegates to NextAlphanumeric(IRandomSource) for character generation.

Declaration
public static string GenerateAlphanumeric(IRandomSource rng, int length = 16)
Parameters
Type Name Description
IRandomSource rng

The random source to use for character selection.
int length

The exact number of alphanumeric characters in the resulting string. Must be at least 1. Defaults to 16 (approximately 95 bits of entropy).
Returns
Type Description
string

A string of exactly length characters, each drawn uniformly from a-z, A-Z, and 0-9.
Exceptions
Type Condition
ArgumentNullException

Thrown if rng is null.
ArgumentOutOfRangeException

Thrown if length is less than 1.
See Also

GenerateBase64(IRandomSource, int)

Generates a random URL-safe Base64 string derived from byteLength random bytes. The resulting string uses the URL-safe alphabet (+ replaced by -, / replaced by _) and has all trailing = padding characters removed, making it safe for direct use in URLs and file names without further encoding.

Declaration
public static string GenerateBase64(IRandomSource rng, int byteLength = 12)
Parameters
Type Name Description
IRandomSource rng

The random source used to fill the byte array before encoding.
int byteLength

The number of random bytes to generate, which determines the entropy and resulting string length. Must be at least 1. Defaults to 12.
Returns
Type Description
string

A URL-safe, unpadded Base64 string with no whitespace, containing characters from A-Z, a-z, 0-9, -, and _.
Remarks

The output string length depends on byteLength: Base64 encodes 3 bytes as 4 characters, so the unpadded character count is ceil(byteLength * 4 / 3). For the default of 12 bytes, the result is always 16 characters (96 bits of entropy).

Exceptions
Type Condition
ArgumentNullException

Thrown if rng is null.
ArgumentOutOfRangeException

Thrown if byteLength is less than 1.
See Also

GenerateGUID(IRandomSource)

Generates a random RFC 4122 version 4 GUID using the specified random source. The method fills 16 bytes from rng, then sets the version nibble to 0x4 and the variant bits to the RFC 4122 value (0b10xx xxxx), ensuring the result is a structurally valid UUID v4.

Declaration
public static Guid GenerateGUID(IRandomSource rng)
Parameters
Type Name Description
IRandomSource rng

The random source used to fill the 16-byte payload of the GUID.
Returns
Type Description
Guid

A Guid conforming to RFC 4122 version 4 (random) format.
Remarks

If a seeded, deterministic IRandomSource is provided, the produced GUID is fully reproducible and therefore not cryptographically unpredictable. For security-sensitive use cases (e.g., session tokens), pass a CreateCrypto() source, or use the system NewGuid() method which always uses a cryptographically secure RNG internally.

Deterministic GUIDs are useful in gameplay scenarios where the same seed must always produce the same object identifiers (e.g., level generation, save/load replay).

Exceptions
Type Condition
ArgumentNullException

Thrown if rng is null.

GenerateHex(IRandomSource, int)

Generates a random lowercase hexadecimal string of exactly length characters. Each character is independently and uniformly sampled from the 16-character set 0123456789abcdef, providing 4 bits of entropy per character.

Declaration
public static string GenerateHex(IRandomSource rng, int length = 16)
Parameters
Type Name Description
IRandomSource rng

The random source to use for character selection.
int length

The exact number of hexadecimal characters in the resulting string. Must be at least 1. Defaults to 16 (64 bits of entropy).
Returns
Type Description
string

A lowercase hexadecimal string of exactly length characters.
Exceptions
Type Condition
ArgumentNullException

Thrown if rng is null.
ArgumentOutOfRangeException

Thrown if length is less than 1.
See Also

IsEmpty(uint)

Returns true if the specified 32-bit ID equals Empty32 (zero), indicating that no valid ID has been assigned.

Declaration
public static bool IsEmpty(uint id)
Parameters
Type Name Description
uint id

The 32-bit unsigned integer ID to test.
Returns
Type Description
bool

true if id is equal to Empty32; otherwise, false.
See Also

IsEmpty(ulong)

Returns true if the specified 64-bit ID equals Empty64 (zero), indicating that no valid ID has been assigned.

Declaration
public static bool IsEmpty(ulong id)
Parameters
Type Name Description
ulong id

The 64-bit unsigned integer ID to test.
Returns
Type Description
bool

true if id is equal to Empty64; otherwise, false.
See Also