Debugging and Authoring Worlds

The Blitz3D+ World Editor has two entry points. A debug program can call DebugWorld to inspect its current live scene, or bin\b3dworldedit.exe can create and edit a .world file without a running game. The official interface is an Extended-mode Blitz3D+ program. Native code supplies public document, session, and renderer services; it does not supply the official editor window.

DebugWorld reference · Custom editor session API · Live sample · Starter world

Inspecting a running world

DebugWorld [world] is available to Extended debug programs after Graphics3D. It selects the given ready world, or the current world when omitted, and launches or activates the configured World Editor. The second parameter controls whether the program stops immediately.

Graphics3D 960,540,0,2
camera=CreateCamera()
cube=CreateCube()
NameEntity cube,"Inspectable cube"

DebugWorld GetWorld(),True

While Not KeyDown(1)
    TurnEntity cube,0,.5,0
    RenderWorld
    Flip
Wend

Continue resumes the same program while leaving the editor attached. Pause, a normal debugger break, or another DebugWorld call stops it again. Mutating controls are enabled only while paused. Closing the editor detaches it; it does not terminate the debugged program.

Live edits change the runtime objects themselves. Program code may overwrite an edited position or setting immediately after Continue. Program-owned entities are inspectable and editable, but V1 permits Delete and Reparent only for entities created by the editor.

Using the viewport

The detached camera, grid, selection bounds, and axes belong only to the editor presentation target. They do not add entities to the world, move a game camera, change entity enumeration, or appear in the game's rendered frame. In live mode the debug host renders the actual target world, performs picking, and calculates framing bounds. The overlays therefore use the same engine coordinate space and camera mathematics as the running scene.

Hierarchy and properties

The live hierarchy is transferred in bounded pages and displayed up to the 4,096-row V1 editor limit. Search filters the loaded hierarchy. Selecting a row fetches its current properties, selects it in 3D, and double-clicking frames it.

The V1 inspector edits the common name, local transform, visibility, and enabled state. Numeric values are validated before a transaction is sent. Live mutations include an expected revision so a stale editor cannot silently overwrite a newer program change.

Creating objects and managing assets

Marker, Camera, and Light create complete basic entities at the viewport focus point. In live mode a selected parent is used only when it was also created by the editor; otherwise the new object is a root.

In standalone mode, Assets is a workspace of this same editor and edits the same open .world document. It supports all V1 asset kinds, previews, filtering, validation, reference-safe rename/removal, and test loading. Select a model asset and use Place model in Scene to add an entity referencing that declaration. No second editor or collection file is opened.

To preserve a model's hierarchy, set Animated / hierarchy (0 or 1) to 1 in Assets and apply the option. This also works for static GLB files without animation clips. Expand the placed model in Scene to see its actual nested nodes. Rows marked [imported] can be selected, searched, and framed with F or a double-click; Ctrl-clicking geometry selects its imported node. Their local transforms are shown read-only. Edit the model instance to move, copy, or delete the whole asset. Saving keeps the source model reference, and the imported rows are rebuilt when the world opens. With the option set to 0, the model is loaded as one collapsed mesh.

In live mode, Place model opens a model-asset chooser for a saved .world collection inside this same application. The debug host prepares the selected declaration, creates a temporary source-backed runtime entity at the viewport focus point, and records enough provenance for a later snapshot. The full Assets and Validation workspaces remain standalone-document views in V1; they are labelled accordingly while attached.

Save As in live mode means Save Snapshot As. The debug host rejects procedural objects that have no representable source declaration, reports runtime-only animation/particle/physics/audio state, and atomically writes the representable scene only after confirmation. Saving never rebinds or restarts the running program.

Standalone authoring

bin\b3dworldedit.exe
bin\b3dworldedit.exe samples\world-editor\starter.world
bin\b3dassets.exe [optional.world]

Standalone mode has one public WorldDocument owner, one dirty state, and one Save operation across Scene, Assets, and Validation. Opening a scene file never makes its assets read-only, and editing assets preserves entity transforms, components, metadata, and unknown optional JSON members.

Save validates and atomically publishes the complete document. Save As rebases relative asset paths and adopts the new path only after success. The runtime mirror used by Scene is rebuilt from an immutable document snapshot, so a failed preview never replaces the current ready view.

Writing a custom editor

DebugWorld launches bin\b3dworldedit.exe by default. Set B3D_WORLD_EDITOR, or the per-user Software\Blitz3DPlus\WorldEditorV1\EditorExecutable registry value, to another executable to use a compatible editor. The runtime passes --session "descriptor.json". Consume that short-lived descriptor with OpenWorldEditorSession. Only the launched same-user process can claim it.

Inspection and mutation use bounded asynchronous JSON requests. The capability object defines protocol version 1, supported operation names, page size, and message limit. Runtime entity IDs are opaque session-scoped values, not Blitz entity handles or pointers. Bind a normal GUI Canvas with CreateWorldEditorView; rendering, picking, bounds, and selection overlays are then performed by the debug host's engine. The negotiated place-model and save-snapshot requests provide the same model-placement and snapshot path used by the bundled editor.

Hosts advertising view.multi-selection.v1 support SetWorldEditorViewSelection view, entity_id, True to add an entity without clearing the existing selection. Zero clears it; the default two-argument call still replaces it. Selection is sent on the next RenderWorldEditorView. The JSON set-selection operation accepts {"ids":["opaque-id",...]} (or the original single id), and get-selection returns an ids array. Malformed lists are rejected without changing selection; stale IDs are ignored. The limit is 4,096 entities. Selection is inspection state, not a world edit.

The view.project.v1 capability provides the read-only project-point request. Supply world:[x,y,z], positive viewport width/height, and the same camera object used for picking/rendering. The result's viewport:[x,y,depth] uses the debug host's native camera projection. This avoids duplicating the engine's projection conventions in custom editors.

With view.marquee.v1, marquee accepts that camera and viewport plus pixel coordinates x0,y0,x1,y1. It returns an ids array for intersecting projected native bounds, excluding hidden hierarchies and clipping at the near/far planes. It does not mutate selection. The bundled editor uses Ctrl-drag to add; Escape or lost capture cancels a drag. set-marquee uses the same rectangle and an enabled boolean to draw an outline on subsequent host-rendered frames; sending {"enabled":false} clears it. Keep at most one overlay update in flight and coalesce pointer movement rather than queueing every event.

view.frame-selection.v1 adds frame-selection with ids, camera, width and height. It returns target:[x,y,z] and distance for the entire selection, fitted with native projection and an 8% viewport margin. The caller retains its orbit orientation. These are read-only inspection operations and remain available while the program runs. The bundled editor ignores stale framing replies after selection, camera or viewport changes.

Availability

DebugWorld, b3dworldedit.exe, the b3dassets.exe compatibility launcher, public session commands, this guide, and the samples are included in Full Win32 and Win64 installations. They are absent from Original-only products.

Back to guides