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 a few thousand rows at a time and shows every entity, however many the program has. 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 inspector edits the common name, transform, visibility and enabled state, and the settings of a camera or light. 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

Add creates a Pivot, Camera, Light, Cube, Sphere, Cylinder, Cone, Quad or Plane at the viewport focus point, and in a standalone world a Particles effect. New objects start at the top level of the scene; to create one inside another object, right-click that object and choose Add Child. Primitives save directly in the world without an external model asset. The quad is a finite, two-sided 2 × 2 XZ surface; resize it with Scale. The plane is an infinite ground plane, as CreatePlane makes. They support selection, framing, transforms, duplication, and undo/redo.

In standalone mode, Assets is a tab of the panel below this same editor's views and edits the same open .world document. It supports all V1 asset kinds, previews, filtering, validation and reference-safe rename/removal, and Play runs a program on the saved world. 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, turn on Keep hierarchy and animation in its import options in Assets. 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 off, 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. The Problems list, which checks the document, is standalone only.

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\b3dworldedit.exe --assets [optional.world]

Standalone mode has one public WorldDocument owner, one dirty state, and one Save operation across Scene and Assets. Opening a scene file never makes its assets read-only, and editing assets preserves entity transforms, components, metadata, and unknown optional JSON members. --assets opens the editor as an asset library, with Assets filling its window.

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. A new world made in an asset library (--assets) contains 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 hierarchy.walk.v1 send the whole hierarchy with get-hierarchy, each entity before its children. The result has an entities array of the same summaries as get-children, plus parent for every entity that has one, and more, nextOffset and total (the entities in the world). Ask for the next page with after, the ID of the last entity received, and offset, the nextOffset received: the walk continues after that entity while it exists, and otherwise after that many entities. maximum asks for at most that many entities, up to the capability's hierarchyPageSize; a page can hold fewer to stay within the message limit. Pages taken while the program changes its hierarchy can repeat or miss entities, so read the hierarchy again when the session's hierarchy revision changes.

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, and with view.kept-selection.v1 only when it has changed. 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 32,768 entities. Selection is inspection state, not a world edit.

A render-view request carries its view's selection. Hosts advertising view.kept-selection.v1 keep the selection each view window last sent, so a frame whose selection has not changed can send keptSelection:true in its place; the host selects that view's selection again before drawing whenever another request has changed its selection. A result with selectionNeeded:true means the host had none kept for the window: send the selection with the next frame. Without either member, a frame leaves the host's selection as it is.

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 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