Blitz3D+ Command Reference

WorldLoadState ( world )

Parameters

world - a world handle, usually one returned by LoadWorldAsync

Description

Returns the loading state of a world as one of the WORLD_LOAD_* constants.

The possible states are:
WORLD_LOAD_READY (0): the world is fully published and selectable
WORLD_LOAD_QUEUED (1): the request has been accepted and is waiting for the background worker
WORLD_LOAD_READING (2): the .world manifest is being read and validated
WORLD_LOAD_DECODING (3): required assets are being decoded on the worker
WORLD_LOAD_FINALIZING (4): resources and entities are being created on the main thread under the load budget
WORLD_LOAD_FAILED (5): the load ended with an error - read WorldLoadError
WORLD_LOAD_CANCELLED (6): cancellation completed without publishing anything

Use the named constants in your code; the numbers are documented for logs and tools. A world made with CreateWorld always reports WORLD_LOAD_READY.

Every loading loop should handle both terminal states, WORLD_LOAD_FAILED and WORLD_LOAD_CANCELLED - neither ever becomes ready, so waiting only on WorldReady would spin forever. Terminal states never change afterwards; a failed or cancelled world is only good for FreeWorld.

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

Requires Extended mode.

See also: LoadWorldAsync, WorldReady, WorldLoadError, WorldLoadStage, CancelWorldLoad.

Example

; WorldLoadState Example
; ----------------------
; Requires Extended mode.

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

; A simple loading screen lives in the default world
camera=CreateCamera()
PositionEntity camera,0,0,-5
light=CreateLight()
RotateEntity light,45,45,0
spinner=CreateCube()
EntityColor spinner,80,170,255

; Start loading the castle world in the background
castle_world=LoadWorldAsync("../../../samples/worlds/castle/castle.world")

; Watch the state advance through the loading pipeline
While Not WorldReady(castle_world)
    state=WorldLoadState(castle_world)
    If state=WORLD_LOAD_FAILED Then RuntimeError WorldLoadError(castle_world)

    TurnEntity spinner,0.5,1,0.25
    RenderWorld
    Text 0,0,"Loading the castle world..."
    Text 0,20,"WorldLoadState(castle_world) = "+state_name(state)
    Flip
Wend

; The world is ready: select it and use its authored camera
SetWorld castle_world
castle_cam=FindWorldEntity(castle_world,"camera-main")
PointEntity castle_cam,FindWorldEntity(castle_world,"castle")

; A spinning beacon shows the loaded world animating
beacon=CreateCube()
ScaleEntity beacon,4,4,4
PositionEntity beacon,0,45,0
EntityColor beacon,255,200,80

While Not KeyDown(1)

    TurnEntity beacon,0,1,0

    ; Arrow keys move the camera (bigger steps suit the castle's scale)
    If KeyDown(200) Then MoveEntity castle_cam,0,0,1
    If KeyDown(208) Then MoveEntity castle_cam,0,0,-1
    If KeyDown(203) Then TurnEntity castle_cam,0,1,0
    If KeyDown(205) Then TurnEntity castle_cam,0,-1,0

    RenderWorld

    Text 0,0,"Arrow keys: move camera   Esc: exit"
    Text 0,20,"WorldLoadState(castle_world) = "+state_name(WorldLoadState(castle_world))

    Flip

Wend

FreeWorld castle_world
End

; Turn a WorldLoadState value into a readable name
Function state_name$(state)
    Select state
        Case WORLD_LOAD_QUEUED
            Return "WORLD_LOAD_QUEUED"
        Case WORLD_LOAD_READING
            Return "WORLD_LOAD_READING"
        Case WORLD_LOAD_DECODING
            Return "WORLD_LOAD_DECODING"
        Case WORLD_LOAD_FINALIZING
            Return "WORLD_LOAD_FINALIZING"
        Case WORLD_LOAD_READY
            Return "WORLD_LOAD_READY"
        Case WORLD_LOAD_FAILED
            Return "WORLD_LOAD_FAILED"
        Case WORLD_LOAD_CANCELLED
            Return "WORLD_LOAD_CANCELLED"
    End Select
    Return "unknown"
End Function

Index