uuid

Parses a UUID string into its 16 raw bytes (big-endian, as stored on the wire).

Accepts the canonical (8-4-4-4-12) and the plain (32 hex digits) forms, in any letter case. Braces, URNs (urn:uuid:...) and surrounding whitespace are rejected.

Any version is accepted, so it also works as a validator.

uuid.parse( "6ba7b810-9dad-11d1-80b4-00c04fd430c8" ) -- "\x6B\xA7\xB8\x10..." (16 bytes)
uuid.parse( "6BA7B8109DAD11D180B400C04FD430C8" )     -- same bytes
uuid.parse( "not a uuid" )                           -- nil

Formats 16 raw bytes as a canonical (8-4-4-4-12, lower-case) UUID string, the inverse of uuid.parse.

The bytes are used as-is, version and variant bits are not touched.

uuid.toString( uuid.parse( "6BA7B810-9DAD-11D1-80B4-00C04FD430C8" ) ) -- "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
uuid.toString( string.rep( "\0", 16 ) )                               -- "00000000-0000-0000-0000-000000000000"

Returns a fast, process-unique identifier formatted as a UUID version 8.

Layout: ssssssss-rrrr-8rrr-Nrrr-rrrrcccccccc

• s - UNIX time in seconds when the prefix was rolled (library load).
• N, r - variant and 58 random bits, rolled together with s.
• c - 32-bit counter, increments on every call, the prefix is re-rolled when it overflows.

Identifiers never repeat within the process, sort in creation order and practically never collide between sessions or machines. They are trivially predictable, never use them as secrets.

Use it for cache file names, temporary keys and similar, prefer uuid.v7 for record identifiers.

When is_unique is given, identifiers are generated until it returns true, e.g. to skip names already taken by files from previous sessions. A callback that never returns true loops forever.

uuid.unique() -- e.g. "6902aa80-6ae3-8ad8-9f21-4c7b00000000"
uuid.unique() -- e.g. "6902aa80-6ae3-8ad8-9f21-4c7b00000001"

uuid.unique( function( uuid_str )
    return not File.exists( "/garrysmod/data/cache/" .. uuid_str .. ".dat" )
end )

Generates a UUID version 3 (name-based, MD5).

The UUID is the MD5 hash of the namespace bytes followed by the name, so the same namespace and name always give the same UUID, on any machine.

Prefer uuid.v5 for new identifiers, v3 exists for compatibility with systems that already use it.

uuid.v3( uuid.NAMESPACE_DNS, "www.example.com" ) -- "5df41881-3aed-3515-88a7-2f4a814cf09e"

Generates a UUID version 4 (random).

122 of the 128 bits are random, the remaining 6 hold the version and the variant. Unlike uuid.v7, it reveals nothing about when it was created, but it does not sort by creation time and scatters database index writes.

The bits come from math.random, unique in practice, but predictable, never use it as a secret, use crypto.random.bytes for secrets.

uuid.v4() -- e.g. "3f2b8c1e-9a4d-4e7f-b215-0c6d8e9fa123"

Generates a UUID version 5 (name-based, SHA-1).

The UUID is the first 16 bytes of the SHA-1 hash of the namespace bytes followed by the name, so the same namespace and name always give the same UUID, on any machine.

Useful for stable identifiers derived from existing keys, e.g. a UUID per SteamID or per file path. Anyone who knows the namespace and the name can compute the UUID, so it is not a secret.

local NAMESPACE_PLAYERS = uuid.parse( "a6c3c5f0-2b1e-4c7d-9f00-6d3e5b2a1c90" ) -- your own namespace, parsed once

uuid.v5( uuid.NAMESPACE_DNS, "www.example.com" ) -- "2ed6657d-e927-568b-95e1-2665a8aea6a2"
uuid.v5( NAMESPACE_PLAYERS, "STEAM_0:1:12345" )   -- same result every time

Generates a UUID version 7 (time-ordered).

The first 48 bits are the UNIX time in milliseconds, so UUIDs sort by creation time both as strings and as bytes, which keeps database indexes compact. The default choice for record identifiers.

Layout: tttttttt-tttt-7sss-Nrrr-rrrrrrrrrrrr

• t - 48-bit timestamp in milliseconds.
• s - 12 bits, without a timestamp the sub-millisecond fraction of the current time (RFC 9562, section 6.2, method 3), bumped when needed, so UUIDs generated by this process are strictly increasing, even within the same millisecond or when the clock goes backwards. With a timestamp they are random.
• N, r - variant and 62 random bits from math.random.

The creation time can be read back from the UUID, use uuid.v4 when that must stay hidden.

uuid.v7()                -- e.g. "019a326a-047b-7801-9c4f-5a6e0b1d2c3f"
uuid.v7( 1761782400123 ) -- "019a326a-047b-7xxx-..." (random tail)

Returns a UUID version 8 (custom) string from the given bytes.

UUID v8 carries application-defined data, only the version and variant bits are fixed, so 122 bits are free: the low 4 bits of uint8_7, the low 6 bits of uint8_9 and all other bytes.

Missing bytes default to 0, out of range values are wrapped to their allowed bits.

uuid.v8()                         -- "00000000-0000-8000-8000-000000000000"
uuid.v8( 0xDE, 0xAD, 0xBE, 0xEF ) -- "deadbeef-0000-8000-8000-000000000000"