Blitz3D+ Command Reference

WorldReady ( world )

Parameters

world - a world handle

Description

Returns True once a world is published and safe to select, render, and use.

This is the gate at the end of every LoadWorldAsync loading loop. Until it returns True, the loading world's handle cannot be passed to SetWorld or SetAudioWorld, rendered, updated, or parented into - any of those is a runtime error. Once True, the world is fully published: select it, grab its authored entities with FindWorldEntity, and play on. Worlds made with CreateWorld are ready immediately.

WorldReady does not wait for assets declared with streaming policy - those keep arriving in the background after the world is playable. Use WorldStreaming and WorldStreamingProgress if you want to show their progress.

Never wait on WorldReady alone: it stays False forever for a failed or cancelled load. Check WorldLoadState for WORLD_LOAD_FAILED and WORLD_LOAD_CANCELLED inside the same loop, or it can spin forever.

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

Requires Extended mode.

See also: LoadWorldAsync, WorldLoadState, WorldLoadProgress, WorldStreaming, SetWorld.

Example

; WorldReady 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")

; The handle exists at once, but WorldReady stays false until the
; world is fully published and safe to select, update and render
While Not WorldReady(castle_world)
    If WorldLoadState(castle_world)=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,"WorldReady(castle_world) = "+WorldReady(castle_world)
    Flip
Wend

; Only now is it safe to select the world 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,"WorldReady(castle_world) = "+WorldReady(castle_world)+" - the world is selected and rendering"

    Flip

Wend

FreeWorld castle_world
End

Index