Blitz3D+ Command Reference

DebugWorld [world][,pause]

Parameters

world (optional) - a ready world handle; zero or an omitted handle selects the current world (default)

pause (optional) - True stops the debug program at the current statement (default); False opens or retargets the editor without stopping the program or taking keyboard focus from the game window

Description

Opens the Blitz3D+ Debug World Editor for the selected world.

By default the debug program stops at the current statement. Pass False for pause to open the editor in passive observation mode and let the program continue immediately. Click the editor when you want to interact with it. A debug executable and Graphics3D are required, and it cannot be called by a Worker Function.

The editor renders through its own camera and presentation target, so free-roam navigation does not move a game camera or draw editor helpers into the game window. While stopped, you can inspect the hierarchy, edit supported world and entity properties, create markers/cameras/lights, and use the Assets workspace. Supported source-backed live assets appear there as protected declarations: they can be inspected and placed but not edited or deleted. New assets may be added, previewed, placed and saved. Procedural geometry without a source file remains an entity rather than becoming a reusable asset. Continue and Pause use the same execution state as the normal debugger.

Live edits are changes to the current runtime objects. Program code can replace them normally after Continue. Whole-model appearance edits are runtime-only. Save As writes state representable by .world version 1 and reports omitted runtime-only state. Choose All objects to replace programmatic construction with a complete representable world, or New objects only to write an additions layer. The latter excludes existing renderable objects, retains only the parent pivots needed to preserve new-object transforms/hierarchy, and prunes unreferenced original assets.

Program-owned entities cannot be deleted or reparented in V1. Entities created by the editor can be deleted, reparented, and undone safely. Custom editors launched with --session connect back through OpenWorldEditorSession.

See the Debug World Editor guide for controls, standalone authoring, snapshot limits, and the World Asset Collection workflow.

Requires Extended mode.

See also: GetWorld, SetWorld, LoadWorldAsync, OpenWorldEditorSession, DebugEntityBounds.

Example

; DebugWorld Example
; ------------------
; Run this as an Extended debug program.

Graphics3D 960,540,0,2
SetBuffer BackBuffer()

camera=CreateCamera()
PositionEntity camera,0,3,-8
light=CreateLight(2)
PositionEntity light,2,5,-3
cube=CreateCube()
NameEntity cube,"Inspectable cube"
EntityColor cube,80,170,255

; False opens the live world without stopping execution.
DebugWorld GetWorld(),False

While Not KeyDown(1)
    TurnEntity cube,0,0.5,0
    RenderWorld
    Text 20,20,"Press Escape to exit; use DebugWorld to inspect the live scene"
    Flip
Wend
End

Index