ludus::content::identity_records¶
Ludus Wiki · API overview · Browse API
Namespace
Related declarations¶
- ludus::content::identity_records::EntityReferenceProperty
- ludus::content::identity_records::IdentityRecordError
- ludus::content::identity_records::MigrationDocument
- ludus::content::identity_records::MigrationManifest
- ludus::content::identity_records::MigrationObject
- ludus::content::identity_records::MigrationSource
Enumerations¶
IdentityRecordStatus¶
enum class IdentityRecordStatus : uint8
Result of reading, generating, replaying or publishing identity records.
Related types: uint8
Success¶
Success
The operation succeeded and its output is available.
Malformed¶
Malformed
Input is not valid JSON or does not have the required shape.
UnsupportedVersion¶
UnsupportedVersion
The
format, envelope version or another versioned field is not supported. Unsupported¶
Unsupported
The input uses a construct this stage does not migrate, such as a World scene extension.
InvalidIdentity¶
InvalidIdentity
A UUID is malformed, nil, not version 4 or not the RFC 9562 variant.
DuplicateIdentity¶
DuplicateIdentity
The same UUID appears twice in one manifest, including across documents.
InvalidLegacyId¶
InvalidLegacyId
A legacy ID or document path is repeated, or a legacy ID breaks the ID rule.
UnknownDocument¶
UnknownDocument
The manifest has no record for the requested document.
StaleManifest¶
StaleManifest
The document's legacy IDs differ from the manifest's: an ID is missing or extra.
UnresolvedReference¶
UnresolvedReference
An entity reference names no object of the same document.
Limit¶
Limit
Input or output exceeds a documented limit.
OutOfMemory¶
OutOfMemory
Allocation failed.
EntropyUnavailable¶
EntropyUnavailable
The entropy source is missing or failed; nothing was minted or written.
IdentityConflict¶
IdentityConflict
Every one of MAX_UUID_GENERATION_ATTEMPTS candidates collided with an existing identity.
AlreadyExists¶
AlreadyExists
The destination file already exists; it was left unchanged.
IoError¶
IoError
Reading or atomically publishing a file failed.
Constants and variables¶
MIGRATION_MANIFEST_FORMAT¶
constexpr std::string_view ludus::content::identity_records::MIGRATION_MANIFEST_FORMAT = "ludus.identity-migration"
Value of the manifest's
format member. MIGRATION_MANIFEST_VERSION¶
constexpr uint64 ludus::content::identity_records::MIGRATION_MANIFEST_VERSION = 1
The only manifest
version this reader and writer support. Related types: uint64
MAX_MANIFEST_BYTES¶
constexpr usize ludus::content::identity_records::MAX_MANIFEST_BYTES = usize{1024} * 1024
Largest accepted manifest text, in bytes.
Related types: usize
MAX_MANIFEST_DOCUMENTS¶
constexpr usize ludus::content::identity_records::MAX_MANIFEST_DOCUMENTS = 64
Most documents one manifest may describe.
Related types: usize
MAX_DOCUMENT_OBJECTS¶
constexpr usize ludus::content::identity_records::MAX_DOCUMENT_OBJECTS = 128
Most objects one manifest document may map (the Editor's World entity limit).
Related types: usize
MAX_LEGACY_ID_BYTES¶
constexpr usize ludus::content::identity_records::MAX_LEGACY_ID_BYTES = 64
Longest scoped legacy ID, in bytes. Matches the Editor's World ID rule.
Related types: usize
MAX_WORLD_DOCUMENT_BYTES¶
constexpr usize ludus::content::identity_records::MAX_WORLD_DOCUMENT_BYTES = usize{512} * 1024
Largest accepted version-1 World document, in bytes (the Editor's World limit).
Related types: usize
MAX_UUID_GENERATION_ATTEMPTS¶
constexpr usize ludus::content::identity_records::MAX_UUID_GENERATION_ATTEMPTS = 4
Candidate UUIDs tried for one new identity before generation reports IdentityConflict.
Related types: usize
WORLD_RECORD_VERSION_1¶
constexpr uint64 ludus::content::identity_records::WORLD_RECORD_VERSION_1 = 1
Envelope version of a World document whose objects carry only scoped string IDs.
Related types: uint64
Declared in modules/content/identity_records/include/ludus/content/identity_records/world_records.h
WORLD_RECORD_VERSION_2¶
constexpr uint64 ludus::content::identity_records::WORLD_RECORD_VERSION_2 = 2
Envelope version of a World document with a document UUID and one source-object UUID per entity.
Related types: uint64
Declared in modules/content/identity_records/include/ludus/content/identity_records/world_records.h
MAX_WORLD_SCHEMA_BYTES¶
constexpr usize ludus::content::identity_records::MAX_WORLD_SCHEMA_BYTES = usize{64} * 1024
Largest accepted World schema text, in bytes (the Editor's schema limit).
Related types: usize
Declared in modules/content/identity_records/include/ludus/content/identity_records/world_records.h
Functions¶
GetIdentityRecordStatusName¶
std::string_view ludus::content::identity_records::GetIdentityRecordStatusName(IdentityRecordStatus status) noexcept
Return a stable lowercase name for a status, for tools and logs.
Related types: IdentityRecordStatus
IsLegacyId¶
bool ludus::content::identity_records::IsLegacyId(std::string_view text) noexcept
Report whether text satisfies the scoped legacy ID rule.
1 to MAX_LEGACY_ID_BYTES ASCII letters, digits,
_, -, . or :. This is the Editor's World ID rule; the world-demo sample's [a-z0-9-]{1,31} IDs are a subset. GenerateMigrationManifest¶
IdentityRecordStatus ludus::content::identity_records::GenerateMigrationManifest(std::span< const MigrationSource > sources, const foundation::identity::EntropySource &entropy, MigrationManifest &outManifest, IdentityRecordError &outError) noexcept
Mint a migration manifest for a set of version-1 World documents.
Reads each document's entity IDs, then obtains one document UUID and one source-object UUID per entity from TryGenerateUuidV4(), in path order and then legacy-ID order. Every candidate is checked against the identities already minted for this manifest; a candidate that collides is replaced, at most MAX_UUID_GENERATION_ATTEMPTS times. No file is read or written and the documents are not changed. Call this once per content root and commit the result with PublishMigrationManifest(); never regenerate it for documents a committed manifest already covers.
| Parameter | Description |
|---|---|
sources |
Documents to migrate; paths must be distinct.
|
entropy |
Production code passes platform::GetSystemEntropySource(); tests inject controlled sources. There is no fallback generator.
|
outManifest |
Replaced on success; unchanged on failure.
|
outError |
Receives the failure; reset to Success on success.
|
Returns
Success, Malformed, UnsupportedVersion, InvalidLegacyId, Limit, OutOfMemory, EntropyUnavailable or IdentityConflict.
Related types: MigrationManifest · IdentityRecordStatus · IdentityRecordError · MigrationSource · foundation::identity::EntropySource
PublishMigrationManifest¶
IdentityRecordStatus ludus::content::identity_records::PublishMigrationManifest(std::string_view root, std::string_view path, const MigrationManifest &manifest, IdentityRecordError &outError) noexcept
Atomically create the manifest file; never replace an existing one.
Writes the canonical form through content::SaveFile() with no expected digest, so publication fails when the destination already exists or appears before the final rename. A failure leaves no partial manifest at
path. | Parameter | Description |
|---|---|
root |
Trusted existing native content root.
|
path |
Manifest path relative to
root; its parent directory must exist. |
manifest |
Validated manifest to publish.
|
outError |
Receives the failure; reset to Success on success.
|
Returns
Success, AlreadyExists, Limit, OutOfMemory or IoError (also for unsupported platforms).
Note
Synchronous Linux and macOS file I/O; call from tools, never from frame-critical paths.
Related types: MigrationManifest · IdentityRecordStatus · IdentityRecordError
ReadEntityReferenceProperties¶
IdentityRecordStatus ludus::content::identity_records::ReadEntityReferenceProperties(std::string_view schemaJson, foundation::Array< EntityReferenceProperty > &outProperties, IdentityRecordError &outError) noexcept
Collect the
entity-typed properties of a World schema. Reads the Editor's schema shape (
components[].id and components[].properties[] with id and type) and ignores the other members, which the Editor validates. | Parameter | Description |
|---|---|
schemaJson |
World schema text, at most MAX_WORLD_SCHEMA_BYTES.
|
outProperties |
Replaced on success, in schema order; unchanged on failure.
|
outError |
Receives the failure; reset to Success on success.
|
Returns
Success, Malformed, Limit or OutOfMemory.
Related types: IdentityRecordStatus · foundation::Array · EntityReferenceProperty · IdentityRecordError
Declared in modules/content/identity_records/include/ludus/content/identity_records/world_records.h
ApplyWorldMigration¶
IdentityRecordStatus ludus::content::identity_records::ApplyWorldMigration(const MigrationManifest &manifest, const MigrationSource &source, std::span< const EntityReferenceProperty > references, Bytes &outWorldJson, IdentityRecordError &outError) noexcept
Replay a committed manifest to turn one version-1 World document into a version-2 record.
The output is
{"version": 2, "schema", "document": <AssetId>, "entities": [{"uuid", "label", "name", "components"}]}. Each entity's version-1 id becomes its label; uuid is the manifest's SourceObjectId for that ID. A nonempty value of a property listed in references is rewritten from the target's legacy ID to the target's UUID; an empty value stays empty (no target). Entity order, the display name and every other value are preserved; output uses two-space indentation and a trailing newline. Replay is pure: it mints nothing, reads no files, and the same inputs always produce the same bytes.The manifest must describe exactly the document's IDs. A World entity missing from the manifest, or a manifest object missing from the World, reports StaleManifest instead of minting or dropping an identity. Documents that use the Editor's
scene extension, whose parent links are not yet migrated, report Unsupported. | Parameter | Description |
|---|---|
manifest |
Committed manifest.
|
source |
The document's path as recorded in the manifest, and its version-1 World JSON (at most MAX_WORLD_DOCUMENT_BYTES).
|
references |
Entity-typed properties, normally from ReadEntityReferenceProperties().
|
outWorldJson |
Replaced on success; unchanged on failure.
|
outError |
Receives the failure; reset to Success on success.
|
Returns
Success, Malformed, UnsupportedVersion, Unsupported, UnknownDocument, StaleManifest, InvalidLegacyId, UnresolvedReference, Limit or OutOfMemory.
Related types: Bytes · MigrationManifest · IdentityRecordStatus · EntityReferenceProperty · IdentityRecordError · MigrationSource
Declared in modules/content/identity_records/include/ludus/content/identity_records/world_records.h
DuplicateEntities¶
IdentityRecordStatus ludus::content::identity_records::DuplicateEntities(std::string_view recordJson, std::string_view schemaJson, std::span< const std::string_view > selected, const foundation::identity::EntropySource &entropy, Bytes &outRecordJson, IdentityRecordError &outError) noexcept
Duplicate a set of entities of a version-2 World record as one transaction.
Stage 4 graph duplication (docs/architecture/object-handles-uuid.md, "Authoring and prefab instances"). The selected entities are copied as a group:
- A fresh
SourceObjectIdis minted for each selected entity with TryGenerateUuidV4 andentropy, checked against every identity already in the record and those minted so far. A colliding candidate is regenerated at most MAX_UUID_GENERATION_ATTEMPTS times before IdentityConflict is reported. - The old-to-new table is built, the selected entities are cloned, and inside each clone every entity-typed reference whose target is in the copied set is rewritten to the target's new UUID. References to entities outside the copied set are deliberately retained unchanged.
- The clones are appended to the record and the whole document is re-emitted.
The transaction is all-or-nothing: on any failure — a malformed record, an unknown selected UUID, an unavailable entropy source, or an unresolved identity conflict — nothing is minted into the output and
outRecordJson is unchanged. Only durable SourceObjectId values are produced; no runtime handle, owner, slot or generation is read or written. Each clone's label is left equal to the source's; callers that need unique labels assign them separately.| Parameter | Description |
|---|---|
recordJson |
A version-2 World record (at most MAX_WORLD_DOCUMENT_BYTES).
|
schemaJson |
The World schema identifying the entity-typed properties.
|
selected |
The canonical UUID texts of the entities to duplicate; each must be an entity of the record and each must be distinct.
|
entropy |
The injected entropy source used to mint the new UUIDs.
|
outRecordJson |
Replaced with the version-2 record that also contains the clones on success; unchanged on failure.
|
outError |
Receives the failure; reset to Success on success.
|
Returns
Success, Malformed, UnsupportedVersion, InvalidIdentity, InvalidSchema's Malformed, UnresolvedReference, EntropyUnavailable, IdentityConflict, Limit or OutOfMemory.
Related types: Bytes · IdentityRecordStatus · IdentityRecordError · foundation::identity::EntropySource
Declared in modules/content/identity_records/include/ludus/content/identity_records/world_records.h