ludus::content::world_restore

Ludus Wiki · API overview · Browse API

Namespace

Declared in modules/content/world_restore/include/ludus/content/world_restore/world_restore.h

Related declarations

• ludus::content::world_restore::RestoreError
• ludus::content::world_restore::RestoreSummary

Enumerations

RestoreStatus

enum class RestoreStatus : foundation::uint8

Result of a two-pass World restore.

Related types: foundation::uint8

Success

Success

Every candidate was created and every required local link resolved; the bindings were published and the active world updated.

Malformed

Malformed

The record text is not valid JSON, has the wrong shape, or exceeds a limit.

UnsupportedVersion

UnsupportedVersion

The record is not a supported version-2 World record.

InvalidSchema

InvalidSchema

The schema JSON is malformed or does not describe the entity-typed properties.

InvalidIdentity

InvalidIdentity

A UUID field is not a nonnil version-4 identity, or two entities share one.

UnresolvedReference

UnresolvedReference

A required local link names a SourceObjectId that is not an entity of this record. The restore is rejected and the active world is unchanged.

CapacityExceeded

CapacityExceeded

The registry or binding table could not create/reserve capacity for the candidate. The active world is unchanged.

OutOfMemory

OutOfMemory

An allocation failed while staging the candidate. The active world is unchanged.

Declared in modules/content/world_restore/include/ludus/content/world_restore/world_restore.h

Functions

GetRestoreStatusName

const char * ludus::content::world_restore::GetRestoreStatusName(RestoreStatus status) noexcept

Return a stable, human-readable name for status. Never null.

Related types: RestoreStatus

Declared in modules/content/world_restore/include/ludus/content/world_restore/world_restore.h

TryRestoreWorld

RestoreStatus ludus::content::world_restore::TryRestoreWorld(std::string_view recordJson, std::string_view schemaJson, const foundation::identity::InstanceId &instance, gameplay::world::EntityRegistry &inoutRegistry, gameplay::world::WorldBindingTable &inoutBindings, RestoreSummary &outSummary, RestoreError &outError) noexcept

Restore a version-2 World record into a registry and binding table in two passes.

The restore is transactional at the World boundary:

• Pass 1 creates one entity per record entity in inoutRegistry and records its SourceObjectId -> EntityId mapping, without resolving any link, so a reference whose target appears later in the record still resolves.
• Pass 2 resolves each required local link (an entity-typed component property naming another entity's SourceObjectId) to the entity created in pass 1, then publishes all durable bindings to inoutBindings with one atomic TryActivate.

If any step fails — malformed input, an unresolved required link, a duplicate identity, or a capacity/allocation failure — the entities created in pass 1 are released, no binding is published, and the active world is left unchanged. Runtime owner, slot and generation values and object addresses are never read from or written to the record; only durable SourceObjectId/InstanceId values cross the boundary.

Parameter	Description
recordJson	The version-2 World record text (UTF-8 JSON).
schemaJson	The World schema identifying the entity-typed properties.
instance	The instance scope the activated level binds under; its InstanceId comes from the level's placement or save, not minted here. Must be nonnil.
inoutRegistry	A registry with enough spare capacity for every record entity; entities are created here and released again on failure.
inoutBindings	The binding table sized for inoutRegistry; durable bindings are published here only on success.
outSummary	Receives the created/published/resolved counts on success; unchanged otherwise.
outError	Receives the failing status and message on failure; set to a cleared value on success.

Returns

RestoreStatus::Success, or a failure status leaving the world unchanged.

Related types: gameplay::world::EntityRegistry · gameplay::world::WorldBindingTable · RestoreStatus · foundation::identity::InstanceId · RestoreError · RestoreSummary

Declared in modules/content/world_restore/include/ludus/content/world_restore/world_restore.h