Blitz3D+ Command Reference

WorldLoadError$ ( world )

Parameters

world - a world handle, usually one returned by LoadWorldAsync

Description

Returns the retained error text for a failed world load, or an empty string.

Once WorldLoadState reports WORLD_LOAD_FAILED, this tells you why: a validation problem in the .world source (with the file, line, and column where it applies), a missing or broken asset dependency, or a memory-limit failure listing the requested, in-use, and limit byte counts. The text is meant to be actionable - log it or show it, then FreeWorld the handle.

The error is retained with the world, so you can read it any time after the failure until the handle is freed. For any world that has not failed - still loading, ready, cancelled, or made with CreateWorld - it returns an empty string.

For the full story, see the Async World Loading guide.

Requires Extended mode.

See also: WorldLoadState, LoadWorldAsync, WorldAssetError, FreeWorld.

Example

; WorldLoadError Example
; ----------------------
; Requires Extended mode.

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

camera=CreateCamera()
PositionEntity camera,0,1,-5
light=CreateLight()
RotateEntity light,45,45,0

; A warning-red cube marks the failed load in our scene
cube=CreateCube()
PositionEntity cube,0,1,0
EntityColor cube,255,80,80

; Deliberately load a world file that does not exist
bad_world=LoadWorldAsync("missing-example.world")

; Pump async loading until the failure is reported
While WorldLoadState(bad_world)<>WORLD_LOAD_FAILED
    UpdateAsyncLoads -1
Wend

; The failed world retains an actionable error message
message$=WorldLoadError(bad_world)
FreeWorld bad_world

While Not KeyDown(1)

    TurnEntity cube,0,1,0

    ; Arrow keys move the camera
    If KeyDown(200) Then MoveEntity camera,0,0,0.1
    If KeyDown(208) Then MoveEntity camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    RenderWorld

    Text 0,0,"Arrow keys: move camera   Esc: exit"
    Text 0,20,"The load failed as expected. WorldLoadError$ returned:"

    ; Show the retained message in screen-wide chunks
    For i=0 To 2
        Text 0,44+i*20,Mid(message,1+i*70,70)
    Next

    Flip

Wend

End

Index