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.

On Windows, the World Editor button, the globe on the debugger toolbar, does the same for the current world without a call in your code. Click it while the program runs or is stopped after Graphics3D: the program pauses at its current statement, and the editor opens or comes to the front.

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 view dropdown lists Free, Top, Bottom, Front, Back, Left and Right, followed by a Camera: entry for every camera in the hierarchy. Choose a camera to follow its current world position, rotation (including roll and parent transforms), projection, zoom, clipping, aspect, clear/fog settings, shadows and camera effects. The canvas supplies the viewport size. Each split view can follow a different camera, and edits appear automatically.

While following, the projection selector reads From camera and viewport navigation is locked. Choose Free or a direction to restore the editor view. Renaming preserves the choice; deleting the camera restores the editor view. Layout presets retain document camera IDs. Live camera IDs belong to one session and are not saved in portable presets.

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

Cameras have a body-and-lens outline in Scene. Light bulbs have parallel arrows for directional lights, outward rays for point lights, and a cone for spot lights. These outlines remain visible when unselected, follow the entity's rotation, and stay readable while zooming or using orthographic views. Selected entities also retain their transform axes. The outlines are editor overlays and do not add objects to the saved world.

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.

Entities the program never passed to NameEntity, such as the camera in the example above, are listed by kind: Camera, Light, Model, Pivot. The label is only how the editor shows them; their names stay empty in the program and in saved snapshots until you type one in the inspector. Searching for a kind, or for unnamed, finds them.

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, Light, Cube, Sphere, Cylinder, Cone, and Plane create complete 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. Primitives save directly in the world without an external model asset. The plane is a finite, two-sided 2 × 2 XZ surface; resize it with Scale. They support selection, framing, transforms, duplication, and undo/redo.

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. Double-click a model card or its expanded preview in Assets to place an instance at the scene focus point and show Scene with it selected and framed.

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, double-click a model in Assets to place it into the paused world. The debug host prepares its source declaration and retains it for later snapshots. Assets shows supported live resources and allows new assets to be added. Validation remains a standalone workspace.

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.

A new world contains a Default Light point light in the Scene hierarchy. It can be moved, edited, or deleted like any other entity, and both the light and ambient setting are saved with the world. Opening an existing world uses its saved lighting without adding a preview light. New asset-only collections contain no scene entities.

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 2, 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. Host and editor must be rebuilt together; mismatched protocol versions are rejected. The resource capability metadata reports authored-reference capture and offline structural editing; see resource project workflows.

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, public session commands, the World Editor (bin\b3dworldedit.exe, or bin/b3dworldedit on a Mac), this guide, and the samples are included in Full installations for Win32, Win64 and the Mac, and are absent from Original-only products. The debugger's World Editor button, the b3dassets.exe compatibility launcher, and choosing another editor with the registry value are Windows-only, and iOS programs cannot use DebugWorld or the session commands. Blitz3D+ on Mac and iOS explains the differences on a Mac.

Back to guides