Saving and exporting resource projects
Requires Extended mode. Open samples/courtyard/courtyard.world
in World Editor, or run samples/courtyard/Courtyard.bb for a scene
combining prefabs, physics, particles, appearance and audio resources.
For saved clip defaults, events and root motion, see Animation sets and samples/animation-sets.
Save All and recovery
File > Save All collects applied drafts from every open resource editor using its selected sharing scope. New/embedded resources, instance material overrides and physics binding changes join the same validated save. Named resource files keep their current paths; use contextual Save As to choose a different path. Save All asks for a world filename if this is its first save. Ordinary Save retains its document scope. Committed scene and shared-resource edits use one workspace undo history. Resource-window drafts retain local history until Save commits them. Undo changes staged sources and does not rewrite disk; Save All publishes that result.
The editor finds a common folder containing changed workspace documents, asking for a project folder when it cannot infer one. The public API takes that boundary explicitly. Every proposed document validates against the other proposed documents, and all opened disk revisions must still match. An external modification or deleted file causes a conflict; reopen it and reconcile your edits.
Before replacing any document, Save All stages its outputs, original backups
and a versioned journal in .b3d-save-journal. Replacements occur in a
deterministic order. An interrupted save reports the replaced and unreplaced files.
Keep that folder until recovery succeeds. File > Recover Interrupted Save restores
the originals. Reopen all affected editors afterwards.
b3dworldc --recover C:/Projects/Courtyard rollback b3dworldc --recover C:/Projects/Courtyard finish
Recovery verifies every backup and current destination before changing files. It refuses to overwrite an external change. Finishing also checks the retained dependency revisions; rollback remains available after unrelated media changes. A second interrupted recovery can be retried. This is filesystem journal recovery, not a promise of power-loss durability on every device. Save sets are limited to 256 documents and 64 MiB each of proposed source and original backups.
Dependencies and workspace history
File > Project Dependencies lists descriptors, their direct assets, dirty state and known consumers. Select a dependency and use Go to dependency to navigate its descriptor. Embed stores a descriptor in its owner; Extract stages a new external file; Move references stages a rebased copy and updates known consumers. The old file is retained. These operations and their undo/redo become durable with Save All. Multiple distinct definitions cannot share one resource ID; embedding one of several aliases for the same external resource is rejected. Consolidate those aliases or make an independent local copy first. Optional extensions need relocation providers; reference operations currently reject unknown extension payloads.
Scene and Assets undo/redo include committed shared-resource changes and their scene overrides. Open resource windows are closed through their normal save/discard flow before workspace history or references change. Reopening a resource reads its staged source. Save As to a different world file starts a new workspace history. Test loads an immutable workspace snapshot and identifies its revision; apply/save resource-window drafts first to include their edits. Loading a snapshot does not activate audio or change global presentation settings.
For tools, OpenWorldDocumentWorkspace opens the descriptor closure. WorldDocumentWorkspaceJson reports document revisions and consumers. A transaction uses the following envelope; this example changes a resource and its referring world as one operation:
{
"protocol": "blitz3d.document-workspace-edit", "version": 1,
"expectedRevision": 3, "operation": "edit", "label": "Change shared asset",
"changes": [
{"path": "scene.world", "revision": 2, "source": "...complete world JSON..."},
{"path": "paint.material", "revision": 1, "source": "...complete material JSON..."}
]
}
Call EditWorldDocumentWorkspace(document,edit). expectedRevision is the current WorldDocumentWorkspaceRevision; each change uses the per-document revision from the report. Revision zero creates a new file in an existing directory, without writing it. Existing formats cannot change. Other operations are undo/redo (no extra fields), embed (document and alias), extract (document, alias and destination), and move (document and destination). Paths resolve from the world directory. Conflicts, duplicate paths, malformed fields and invalid resulting graphs leave everything unchanged. History is bounded to 128 entries and 64 MiB; the workspace holds at most 256 descriptors and 64 MiB of authored source. Raw media remains external.
SaveWorldDocumentSet also accepts optional world_file and expected_destination_revision arguments to choose a first world destination or save the complete workspace to a new location. Existing destinations require an observed SHA-256. Publication remains journalled, including staged resources, and the old world is retained. LoadWorldResourceDocument and the optional world_document argument of CreateResourceDocument use staged dependencies when making an editable draft. WorldDocumentWorkspaceUndoSource returns the next world source for a read-only protection check. Save applies to the active file. If a saved world would require staged resource identities or new files, use Save All to publish those dependencies together. Save All before moving the world itself with Save As. The editor requires the first world save before extracting or moving external references. Code that frees the world should save the closure first if later file-based loading needs those staged resources.
Export a project
File > Export Project reads an export plan and writes a new directory. It
exports saved disk contents; use Save All first. The same operation is available
through b3dworldc and ExportWorldProject. No source file
is changed and an existing destination is never replaced.
{
"format": "blitz3d.resource-export", "version": 1,
"projectRoot": ".",
"roots": ["scene.world", "sounds/code-only.sound"],
"files": ["Game.exe", "LICENSE.txt"],
"dependencies": {"models/old.x": ["textures/old.png"]},
"extensions": {"example.notes": []}
}
projectRoot is relative to the plan. All other file lists are
relative to that root. roots explicitly includes resources loaded by
code: filenames assembled in a program cannot be inferred from a world. The
optional files list includes executables, licences and other application
data. Each dependencies key is an included opaque file, followed by
all its sidecars. An empty list explicitly declares no sidecars. The
extensions map provides the same declaration for optional resource
or unknown glTF extensions; these extensions must use portable relative paths.
b3dworldc --collect export.json b3dworldc --export export.json C:/Games/CourtyardExport
Collection follows the native document dependency graph and inspects glTF/GLB buffers and images, B3D texture tables and compiled .b3shader bytecode paths, including shadow and displacement fallback stages. Opaque models such as .x/.3ds need explicit sidecar lists. Uncompiled shader source must be compiled first. Engine-owned shader requirements are recorded and supplied by the matching native runtime/executable.
The project-relative layout is preserved, absolute paths in known document fields are rebased, and resource IDs are unchanged. Paths outside the root, directory links, nonportable Windows filenames, ASCII case collisions, conflicting IDs, missing dependencies and unknown dependencies fail export. Collection is bounded to 16,384 files, 32 dependency levels, 256 MiB per file and 1 GiB of inputs; native descriptor limits also apply. The sorted manifest records content hashes, source hashes, roots and explicit providers. Staged documents are validated at their relocated paths before the directory is published.
Use architecture-matched compiler/runtime binaries to build the game. Include
its executable in files or compile into the exported tree. Test it
from its intended working directory with the editor, source tree and installation
search path unavailable. Export validation verifies dependency closure, not media
decode, rendered output or audio playback.
Live sessions
Host and editor use session protocol 2 and reject mismatched descriptors, claims, requests, state and responses. Capability metadata names all eight delivered resource kinds, authored-reference snapshots and the offline/restart structural editing policy. Snapshots preserve authored resource references; procedural resource configuration, particle/solver state, playing channels, global mixer state and camera history are not reconstructed. Snapshot messages report these limits.
Save All uses the sharing scope selected in every open resource editor, including new/embedded definitions, instance material overrides and physics body binding changes. It waits for prepared previews and physics candidate validation, then publishes the combined world/resource graph. Material texture copies use the existing portable authoring step. Conflicting edits to the same value stop the batch and preserve its drafts. Terrain data edits still need explicit Export edited data or Reset before a descriptor save. A pending recovery journal retains required copied media.
For editor steps and F1 help, see the World Editor User Guide.