Skip to content

ludus::content::scene_cook

Ludus Wiki · API overview · Browse API

Namespace

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/best_effort_import.h

Enumerations

SceneSourceFormat

enum class SceneSourceFormat : uint8
Scene source container recognised by DetectSceneSourceFormat.

Related types: uint8

Unknown

Unknown
Not recognised.

Pbrt

Pbrt
pbrt-v4 scene description text.

Gltf

Gltf
glTF 2.0 JSON (.gltf) or binary container (.glb).

Obj

Obj
Wavefront OBJ text.

LudusScene

LudusScene
Ludus scene source JSON (.luscene.json); see Ludus::SceneSource.

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/best_effort_import.h

AssetErrorCode

enum class AssetErrorCode : uint8
Stable failure vocabulary shared with the Editor result protocol.

Related types: uint8

InvalidScene

InvalidScene
The level, catalog or bundle violates the profile.

AssetCorrupt

AssetCorrupt
Stored bytes are unreadable, malformed or fail their digest.

InstallCancelled

InstallCancelled
The caller's cancellation hook fired.

Conflict

Conflict
Files changed underneath the operation (compare-and-publish failed).

Busy

Busy
Another process holds the project lock, or a reader tried to write.

MissingTools

MissingTools
The host lacks the native facilities (only Linux and macOS are supported), or no entropy was available for a new UUID (see AssetOptions::EntropyOrNull).

UnsupportedScene

UnsupportedScene
The source scene could not be converted.

StorageFailure

StorageFailure
A filesystem operation failed.

RecoveryRequired

RecoveryRequired
A failed import rollback left recovery files behind.

DestinationExists

DestinationExists
The release destination already exists.

OutOfMemory

OutOfMemory
An allocation failed.

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

DumpLayout

enum class DumpLayout : uint8
Byte layout of DumpLevel and PublishLevel outputs.

Related types: uint8

Canonical

Canonical
canonical(): what scene-release.json stores.

Indented

Indented
json.dumps(indent=2, sort_keys=True), for people reading a terminal.

Line

Line
json.dumps(sort_keys=True) on one line, for machine-readable CLI output.

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

EditorSceneOperation

enum class EditorSceneOperation : uint8
Operations the Editor runs in process (scene_editor.operate).

Related types: uint8

Open

Open
Read, validate and assemble a saved level.

Import

Import
Prepare an import candidate without publishing the catalog.

CommitImport

CommitImport
Publish a prepared candidate catalog.

PreviewImport

PreviewImport
Plan an import without writing anything: Response holds schema, ok, profile, the import report, source_digest (see AssetOptions::ExpectedSourceDigest) and, after a reference fallback, reference_rejection.

Save

Save
Save the level after checking the bytes on disk.

Assemble

Assemble
Validate and assemble an unsaved level.

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

Constants and variables

BEST_EFFORT_PROFILE

constexpr std::string_view ludus::content::scene_cook::BEST_EFFORT_PROFILE = "pbrt-best-effort-v1"
Profile identifier of the pbrt-v4 importer, recorded in the import report and the catalog.

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/best_effort_import.h

GLTF_BEST_EFFORT_PROFILE

constexpr std::string_view ludus::content::scene_cook::GLTF_BEST_EFFORT_PROFILE = "gltf-best-effort-v1"
Profile identifier of the glTF 2.0 / GLB importer.

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/best_effort_import.h

OBJ_BEST_EFFORT_PROFILE

constexpr std::string_view ludus::content::scene_cook::OBJ_BEST_EFFORT_PROFILE = "obj-best-effort-v1"
Profile identifier of the Wavefront OBJ/MTL importer.

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/best_effort_import.h

LUDUS_SCENE_PROFILE

constexpr std::string_view ludus::content::scene_cook::LUDUS_SCENE_PROFILE = "ludus-scene-v1"
Profile identifier of the Ludus scene source (.luscene.json) importer.

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/best_effort_import.h

IMPORT_REPORT_SCHEMA

constexpr uint32 ludus::content::scene_cook::IMPORT_REPORT_SCHEMA = 1
Version of the import report JSON schema.

Related types: uint32

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/best_effort_import.h

MAX_SOURCE_BYTES

constexpr usize ludus::content::scene_cook::MAX_SOURCE_BYTES = usize{64} * 1024 * 1024
Largest source file admitted by the cooker (bundles are bounded by scene_format::BundleLimits). Also bounds each best-effort text source: pbrt includes, MTL libraries and glTF JSON.

Related types: usize

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/limits.h

MAX_SOURCE_DATA_BYTES

constexpr usize ludus::content::scene_cook::MAX_SOURCE_DATA_BYTES = usize{1024} * 1024 * 1024
Largest binary scene data source read by the best-effort importers: a PLY mesh, an external or base64 glTF buffer, or a whole GLB container. Encoded bytes only; decoded geometry has its own budgets in the readers and the planner.

Related types: usize

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/limits.h

MAX_SOURCE_IMAGE_BYTES

constexpr usize ludus::content::scene_cook::MAX_SOURCE_IMAGE_BYTES = usize{256} * 1024 * 1024
Largest encoded image read for a texture or environment map, including an image embedded in a glTF buffer view or data URI.

Related types: usize

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/limits.h

MAX_REFERENCE_DOCUMENT_BYTES

constexpr usize ludus::content::scene_cook::MAX_REFERENCE_DOCUMENT_BYTES = usize{1024} * 1024
Inclusive source byte ceiling for the strict reference profile's entry document.

Related types: usize

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/limits.h

MAX_LICENSE_BYTES

constexpr usize ludus::content::scene_cook::MAX_LICENSE_BYTES = usize{1024} * 1024
Inclusive source byte ceiling for the strict reference profile's license text.

Related types: usize

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/limits.h

MAX_ASSET_BYTES

constexpr usize ludus::content::scene_cook::MAX_ASSET_BYTES = usize{384} * 1024 * 1024
Largest single artifact in bytes; also holds the largest cooked scene bundle (scene_format::IMPORT_LIMITS.BundleBytes). Dependency closure admission is separate.

Related types: usize

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/limits.h

MAX_RESIDENT_CLOSURE_BYTES

constexpr usize ludus::content::scene_cook::MAX_RESIDENT_CLOSURE_BYTES = usize{512} * 1024 * 1024
Largest logical dependency closure in encoded bytes, including material JSON, scene manifests and licenses in addition to geometry/texture payloads. Each selected logical resource is charged once, even when artifact files are shared. This does not enlarge the assembled bundle or establish a decoded/peak-memory budget.

Related types: usize

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/limits.h

MAX_METADATA_BYTES

constexpr usize ludus::content::scene_cook::MAX_METADATA_BYTES = usize{1024} * 1024
Largest level or metadata document in bytes.

Related types: usize

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/limits.h

MAX_CATALOG_BYTES

constexpr usize ludus::content::scene_cook::MAX_CATALOG_BYTES = usize{64} * 1024 * 1024
Largest project catalog (assets/catalog.json) in bytes. Imports record one digest of their source-input map per artifact, but records of the frozen reference profile and of earlier imports carry the full map (it feeds their artifact keys), so such catalogs grow with resources x source files: two imports of ~800-file pbrt scenes already pass 1 MiB. Matches the artifact limit rather than the small-document limit.

Related types: usize

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/limits.h

LEVEL_PROFILE

constexpr std::string_view ludus::content::scene_cook::LEVEL_PROFILE = "resident-reference-v1"
Profile identifier stored in every level document.

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

PROFILE

constexpr std::string_view ludus::content::scene_cook::PROFILE = "pbrt-reference-v1"
Profile identifier of the cooked bundle layout and manifest.

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

MATERIAL_PROFILE

constexpr std::string_view ludus::content::scene_cook::MATERIAL_PROFILE = "pbrt-reference-materials-v2"
Source-preserving RGB material import profile; v1 remains the frozen compatibility cooker.

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

Functions

ImportPbrtBestEffort

bool ludus::content::scene_cook::ImportPbrtBestEffort(std::string_view entryFile, const BestEffortOptions &options, BestEffortResult &outResult, CookError &outError, const Cancellation *cancelOrNull=nullptr) noexcept
Import a pbrt-v4 entry file with the best-effort profile.
ParameterDescription
entryFile
Native path of the .pbrt file. Its directory is the import root; Include/Import, PLY and image paths must resolve inside it.
options
Dry-run selection, companion environment and decoder job system.
outResult
Replaced on success. On a parse failure with diagnostics, outResult.Report still holds the report so the caller can show why.
outError
Set on failure: Invalid (syntax errors or nothing drawable), NotFound/IoError (entry file), Cancelled, OutOfMemory.
cancelOrNull
Optional cancellation hook polled per directive and per placement.

Returns

true on success.

Note

Synchronous file I/O on Linux and macOS; other targets report Unsupported until the browser source file system lands. Deterministic: equal inputs give equal bytes.

Related types: BestEffortOptions · BestEffortResult · Cancellation · CookError

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/best_effort_import.h

ImportGltfBestEffort

bool ludus::content::scene_cook::ImportGltfBestEffort(std::string_view entryFile, const BestEffortOptions &options, BestEffortResult &outResult, CookError &outError, const Cancellation *cancelOrNull=nullptr) noexcept
Import a glTF 2.0 (.gltf) or GLB (.glb) entry file with the best-effort profile. The static triangle-mesh subset (node hierarchy, instancing, core metallic-roughness materials, perspective cameras, KHR_lights_punctual) is read; unsupported content is reported. A file that requires an unsupported extension fails with Invalid.
ParameterDescription
entryFile
Native path of the entry file. Its directory is the import root; external buffers and images must resolve inside it. Data URIs are decoded in memory.
options
Dry-run selection, companion environment and decoder job system.
outResult
Replaced. On a failure with diagnostics, outResult.Report still holds the report so the caller can show why.
outError
Set on failure: Invalid (malformed input, unsupported required features or nothing drawable), NotFound/IoError (entry file), Cancelled, OutOfMemory.
cancelOrNull
Optional cancellation hook polled per node, primitive and placement.

Returns

true on success.

Note

Same platform and determinism contract as ImportPbrtBestEffort.

Related types: BestEffortOptions · BestEffortResult · Cancellation · CookError

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/best_effort_import.h

ImportObjBestEffort

bool ludus::content::scene_cook::ImportObjBestEffort(std::string_view entryFile, const BestEffortOptions &options, BestEffortResult &outResult, CookError &outError, const Cancellation *cancelOrNull=nullptr) noexcept
Import a Wavefront OBJ entry file and the MTL libraries it names. Faces are fan-triangulated (at most 64 corners), Phong-style materials are mapped to metallic-roughness with the documented conversion, and the result is fitted to LUSCN.
ParameterDescription
entryFile
Native path of the .obj file; its directory is the import root and material libraries and textures must resolve inside it.
options
Dry-run selection, companion environment and decoder job system.
outResult
Replaced; on a failure with diagnostics the report is kept.
outError
Set on failure: Invalid (malformed records, zero or out-of-range indices, limits, nothing drawable), NotFound/IoError (entry file), Cancelled, OutOfMemory.
cancelOrNull
Optional cancellation hook polled every few thousand lines.

Returns

true on success.

Note

Same platform and determinism contract as ImportPbrtBestEffort. The entry is streamed; memory grows with the retained geometry, not the file size.

Related types: BestEffortOptions · BestEffortResult · Cancellation · CookError

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/best_effort_import.h

ImportLudusScene

bool ludus::content::scene_cook::ImportLudusScene(std::string_view entryFile, const BestEffortOptions &options, BestEffortResult &outResult, CookError &outError, const Cancellation *cancelOrNull=nullptr) noexcept
Import a Ludus scene source (.luscene.json) entry file with the ludus-scene-v1 profile. The document is validated by Ludus::SceneSource; its convex polygons become flat-shaded triangle fans, its emitting materials become required area lights with their exact radiance, and its camera becomes the start view. Emitters reflect as white rough surfaces in LUSCN, which the report records as a warning.
ParameterDescription
entryFile
Native path of the entry file. Its directory is the import root; a LICENSE.txt or LICENSE.md beside it is recorded like the other importers'.
options
Dry-run selection, companion environment and decoder job system.
outResult
Replaced; on a failure with diagnostics the report is kept.
outError
Set on failure: Invalid (an invalid document, or a scene beyond the cooked profile), NotFound/IoError (entry file), Cancelled, OutOfMemory.
cancelOrNull
Optional cancellation hook polled per object.

Returns

true on success.

Note

Same platform and determinism contract as ImportPbrtBestEffort.

Related types: BestEffortOptions · BestEffortResult · Cancellation · CookError

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/best_effort_import.h

DetectSceneSourceFormat

SceneSourceFormat ludus::content::scene_cook::DetectSceneSourceFormat(std::span< const uint8 > prefix, std::string_view fileName) noexcept
Classify a scene source from its first bytes, falling back to the file name extension only when the content is not decisive (for example a comment-only prefix). GLB magic selects Gltf; a JSON object whose first member is "format": "ludus.scene" selects LudusScene and any other leading '{' selects Gltf; an OBJ record keyword selects Obj and a capitalised pbrt directive selects Pbrt.
ParameterDescription
prefix
Leading bytes of the file (4 KiB is plenty); may be empty.
fileName
Name used only for the extension fallback.

Returns

The detected format, or Unknown.

Related types: SceneSourceFormat · uint8

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/best_effort_import.h

DetectSceneSourceFile

Status ludus::content::scene_cook::DetectSceneSourceFile(std::string_view entryFile, SceneSourceFormat &outFormat) noexcept
Read the first 4 KiB of entryFile and classify it with DetectSceneSourceFormat.
ParameterDescription
entryFile
Native path.
outFormat
Set only on Ok.

Returns

Ok, NotFound, IoError or Unsupported (no native file access on this target).

Related types: Status · SceneSourceFormat

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/best_effort_import.h

ImportSceneBestEffort

bool ludus::content::scene_cook::ImportSceneBestEffort(std::string_view entryFile, const BestEffortOptions &options, BestEffortResult &outResult, CookError &outError, const Cancellation *cancelOrNull=nullptr) noexcept
Import entryFile with the best-effort importer selected by DetectSceneSourceFile.

Returns

As the selected importer; Unsupported in outError when the format is unknown, NotFound/IoError when the entry cannot be read.

Related types: BestEffortOptions · BestEffortResult · Cancellation · CookError

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/best_effort_import.h

WriteBestEffortImport

bool ludus::content::scene_cook::WriteBestEffortImport(std::string_view output, const BestEffortResult &result, CookError &outError) noexcept
Write scene.luscn, import-report.json and (when present) LICENSE.txt below output.
ParameterDescription
output
Native directory; created with its parents when absent.
result
A non-dry-run result.
outError
Set on failure.

Returns

true when every file was atomically replaced.

Related types: BestEffortResult · CookError

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/best_effort_import.h

GetAssetErrorCodeName

std::string_view ludus::content::scene_cook::GetAssetErrorCodeName(AssetErrorCode code) noexcept
Stable code name, e.g. "AssetCorrupt".

Related types: AssetErrorCode

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

CreateLevel

bool ludus::content::scene_cook::CreateLevel(std::string_view name, const AssetOptions &options, foundation::Array< uint8 > &outLevel, AssetError &outError) noexcept
new_level(name): an empty level with a fresh UUID and the default camera.
ParameterDescription
name
Display name, stored verbatim.
options
UuidsOrNull selects the UUID source.
outLevel
Canonical level bytes.
outError
Set on failure.

Returns

true on success.

Related types: foundation::Array · uint8 · AssetError · AssetOptions

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

ValidateLevel

bool ludus::content::scene_cook::ValidateLevel(std::span< const uint8 > level, AssetError &outError) noexcept
validate_level: parse a level document and check every profile rule.
ParameterDescription
level
Level JSON bytes.
outError
Set on failure.

Returns

true when the level is valid.

Related types: uint8 · AssetError

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

ComposeLevelTransforms

bool ludus::content::scene_cook::ComposeLevelTransforms(std::span< const uint8 > level, foundation::Array< float32 > &outTransforms, AssetError &outError) noexcept
Compose every level object's mesh-to-world transform exactly as an assembled bundle stores it: parent chains compose in the reference's float64 order, then each value narrows to float32. Reads no project files, so the result covers placement only, never asset validity.
ParameterDescription
level
Level JSON bytes, validated as ValidateLevel does.
outTransforms
Replaced on success with twelve values per level object, in level order: the column-major mesh-to-world basis, then the translation (content::scene_format::OBJECT_TRANSFORM_COMPONENTS).
outError
Set on failure: an invalid level, a world transform outside the float32 range, or allocation failure.

Returns

true on success; failure preserves outTransforms.

Related types: foundation::Array · float32 · uint8 · AssetError

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

ReadCatalog

bool ludus::content::scene_cook::ReadCatalog(std::string_view root, foundation::Array< uint8 > &outCatalog, AssetError &outError) noexcept
catalog(root): the published catalog, or the empty catalog when none exists.
ParameterDescription
root
Project directory.
outCatalog
Canonical catalog bytes.
outError
Set on failure.

Returns

true on success.

Related types: foundation::Array · uint8 · AssetError

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

PrepareImport

bool ludus::content::scene_cook::PrepareImport(std::string_view root, std::string_view source, std::span< const uint8 > level, const AssetOptions &options, ImportCandidate &outCandidate, AssetError &outError) noexcept
prepare_import: cook source, store its immutable artifacts and build a candidate level and catalog without publishing the catalog.
ParameterDescription
root
Project directory.
source
Directory holding the pbrt-reference-v1 scene.
level
Level the import is merged into; never saved here.
options
Cancellation, UUID source and provenance override.
outCandidate
Replaced on success.
outError
Set on failure.

Returns

true on success.

Related types: uint8 · AssetError · AssetOptions · ImportCandidate

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

CommitImport

bool ludus::content::scene_cook::CommitImport(std::string_view root, std::span< const uint8 > level, std::span< const uint8 > catalog, const Digest *publishedOrNull, std::string_view source, const AssetOptions &options, AssetError &outError) noexcept
commit_import: revalidate a candidate and publish its catalog when the published catalog still matches the one it was prepared against.
ParameterDescription
root
Project directory.
level
Candidate level bytes.
catalog
Candidate catalog bytes.
publishedOrNull
Digest of the catalog the candidate was prepared against; nullptr when no catalog was published.
source
Source directory, rechecked for changes.
options
Cancellation and provenance override.
outError
Set on failure.

Returns

true when the catalog was published.

Related types: uint8 · Digest · AssetError · AssetOptions

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

ImportScene

bool ludus::content::scene_cook::ImportScene(std::string_view root, std::string_view source, std::span< const uint8 > level, const AssetOptions &options, foundation::Array< uint8 > &outLevel, AssetError &outError) noexcept
import_scene: PrepareImport then CommitImport; never saves the level.
ParameterDescription
root
Project directory.
source
Source scene directory.
level
Level to merge into.
options
Cancellation, UUID source and provenance override.
outLevel
Canonical candidate level.
outError
Set on failure.

Returns

true when the catalog was published.

Related types: foundation::Array · uint8 · AssetError · AssetOptions

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

ImportSavedLevel

bool ludus::content::scene_cook::ImportSavedLevel(std::string_view root, std::string_view relative, std::string_view source, const AssetOptions &options, foundation::Array< uint8 > &outLevel, AssetError &outError) noexcept
import_saved_level: import into a saved level and publish the catalog and level together, rolling both back when either replacement fails.
ParameterDescription
root
Project directory.
relative
Project-relative .lulevel path.
source
Source scene directory.
options
Cancellation, UUID source and provenance override.
outLevel
Canonical saved level.
outError
Set on failure.

Returns

true on success.

Related types: foundation::Array · uint8 · AssetError · AssetOptions

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

SaveLevel

bool ludus::content::scene_cook::SaveLevel(std::string_view root, std::string_view relative, std::span< const uint8 > level, const foundation::Array< uint8 > *expectedOrNull, foundation::Array< uint8 > &outSaved, AssetError &outError) noexcept
save_level: validate the closure, compare the bytes on disk and replace the level.
ParameterDescription
root
Project directory.
relative
Project-relative .lulevel path.
level
Level bytes.
expectedOrNull
Bytes the file must still hold; nullptr requires that it does not exist.
outSaved
Canonical bytes written.
outError
Set on failure.

Returns

true on success.

Related types: foundation::Array · uint8 · AssetError

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

OpenLevel

bool ludus::content::scene_cook::OpenLevel(std::string_view root, std::string_view relative, foundation::Array< uint8 > &outLevel, AssetError &outError) noexcept
open_level: read, validate, and check the closure and assembly of a saved level.
ParameterDescription
root
Project directory.
relative
Project-relative .lulevel path.
outLevel
Canonical level bytes.
outError
Set on failure.

Returns

true on success.

Related types: foundation::Array · uint8 · AssetError

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

AssembleLevel

bool ludus::content::scene_cook::AssembleLevel(std::string_view root, std::span< const uint8 > level, std::span< const uint8 > catalog, foundation::Array< uint8 > &outBundle, AssetError &outError) noexcept
Assemble a level's exact closure without invoking its source importer. Legacy-only resources produce LUSCN v2; authored lighting/mesh records select v3. V3 retains emitter flags/power, independent bake UVs and instance identities derived from persistent object UUIDs. Imported analytic IDs are scoped by source artifact; environments sum without dropping sources. HDR maps must have matching dimensions. Profile/count/byte or combined environment-scale overflow rejects publication. A level without objects produces an empty bundle; this does not remove stored lighting.
ParameterDescription
root
Project directory.
level
Level bytes.
catalog
Candidate catalog bytes, or empty to use the published catalog.
outBundle
Bundle bytes.
outError
Set on failure.

Returns

true on success.

Related types: foundation::Array · uint8 · AssetError

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

DumpLevel

bool ludus::content::scene_cook::DumpLevel(std::string_view root, std::span< const uint8 > level, std::span< const uint8 > catalog, DumpLayout layout, foundation::Array< uint8 > &outDump, AssetError &outError) noexcept
dump: the level with its exact resident closure and byte total.
ParameterDescription
root
Project directory.
level
Level bytes.
catalog
Candidate catalog bytes, or empty to use the published catalog.
layout
Output layout.
outDump
JSON bytes.
outError
Set on failure.

Returns

true on success.

Related types: DumpLayout · foundation::Array · uint8 · AssetError

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

PublishLevel

bool ludus::content::scene_cook::PublishLevel(std::string_view root, std::span< const uint8 > level, std::string_view destination, DumpLayout layout, foundation::Array< uint8 > &outDump, AssetError &outError) noexcept
publish: write a deterministic loose-file release (closure, catalog, level, assembled bundle and scene-release.json) to a new directory.
ParameterDescription
root
Project directory.
level
Level bytes.
destination
Release directory; must not exist.
layout
Layout of outDump.
outDump
Dump of the published release.
outError
Set on failure.

Returns

true on success.

Related types: DumpLayout · foundation::Array · uint8 · AssetError

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

WriteFileAtomically

bool ludus::content::scene_cook::WriteFileAtomically(std::string_view path, std::span< const uint8 > data, AssetError &outError) noexcept
Write bytes with the catalog's atomic replacement protocol (used for ludus-cook scene assemble outputs).
ParameterDescription
path
Native file path; parent directories are created.
data
Bytes to write.
outError
Set on failure.

Returns

true on success.

Related types: uint8 · AssetError

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

OperateEditorScene

bool ludus::content::scene_cook::OperateEditorScene(const EditorSceneRequest &request, const AssetOptions &options, EditorSceneResult &outResult, AssetError &outError) noexcept
Run one Editor scene operation in process, replacing the scene_editor.py subprocess. Thread-safe with respect to other projects; same-project writers are serialised by the project lock.
ParameterDescription
request
Operation and inputs.
options
Cancellation, UUID source and provenance override.
outResult
Replaced on success; left unchanged on failure.
outError
Set on failure.

Returns

true on success.

Related types: AssetError · AssetOptions · EditorSceneRequest · EditorSceneResult

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/scene_assets.h

Cook

bool ludus::content::scene_cook::Cook(std::string_view source, CookResult &outResult, CookError &outError, const Cancellation *cancelOrNull=nullptr) noexcept
Cook one source directory containing scene-v4.pbrt and LICENSE.txt.
ParameterDescription
source
Native directory path; resolved before use, and its base name is recorded when the licence does not identify the staircase2 author.
outResult
Replaced on success; contents are unspecified on failure.
outError
Set on failure.
cancelOrNull
Optional cancellation hook; nullptr disables cancellation.

Returns

true on success.

Note

Synchronous file I/O. Symlinks below the source root are rejected.

Related types: Cancellation · CookError · CookResult

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

CookMaterials

bool ludus::content::scene_cook::CookMaterials(std::string_view source, CookResult &outResult, CookError &outError, const Cancellation *cancelOrNull=nullptr) noexcept
Cook the staircase2 PBRT subset with named materials, original texture UVs, exact linear reflectance and retained GGX/complex-IOR parameters into LUSCN v7. Coated diffuse resolves scalar eta/thickness and admits zero medium albedo, isotropic rough interfaces and the shared default internal depth/sample policy.
ParameterDescription
source
Native source directory; synchronous bounded file reads, no symlinks.
outResult
Replaced only on success; preserved on failure or cancellation.
outError
Failure status and diagnostic; cleared on entry.
cancelOrNull
Optional thread-safe cooperative cancellation hook.

Returns

True on success. Unsupported anisotropy, smooth conductors and roughness remapping reject.

Related types: Cancellation · CookError · CookResult

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

WriteCook

bool ludus::content::scene_cook::WriteCook(std::string_view output, const CookResult &result, CookError &outError) noexcept
Write scene.luscn, manifest.json and LICENSE.txt below output.
ParameterDescription
output
Native directory; created with its parents when absent.
result
Outputs from Cook.
outError
Set on failure.

Returns

true when every file was atomically replaced.

Related types: CookError · CookResult

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