Blitz3D+ Command Reference

WorldLoadProgress ( world )

Parameters

world - a world handle, usually one returned by LoadWorldAsync

Description

Returns a loading world's progress as a value from 0 through 1000.

This is the number behind a loading bar: divide by 10.0 for a percentage. Progress covers the required content only, never moves backwards, and reaches 1000 exactly when WorldReady becomes True. A world that is not loading asynchronously (for example one made with CreateWorld) reports 1000.

Progress is advisory - the stages are weighted estimates, so do not expect a perfectly smooth climb, and do not use it as the completion test. WorldReady and WorldLoadState decide when the world is usable. Optional streaming assets have their own counter in WorldStreamingProgress.

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

Requires Extended mode.

See also: WorldLoadStage, WorldReady, WorldLoadState, WorldStreamingProgress, LoadWorldAsync.

Example

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

While Not WorldReady(castle_world)
    If WorldLoadState(castle_world)=WORLD_LOAD_FAILED Then RuntimeError WorldLoadError(castle_world)

    ; WorldLoadProgress climbs from 0 to 1000 while the world loads
    progress=WorldLoadProgress(castle_world)

    TurnEntity spinner,0.5,1,0.25
    RenderWorld
    Text 0,0,"Loading the castle world..."
    Text 0,20,"WorldLoadProgress(castle_world) = "+progress+" / 1000 ("+(progress/10.0)+"%)"

    ; Draw the progress value as a loading bar
    Color 80,170,255
    Rect 0,44,progress/2,12,1
    Color 255,255,255
    Rect 0,44,500,12,0

    Flip
Wend

; Progress reaches exactly 1000 when WorldReady becomes true
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,"WorldLoadProgress(castle_world) = "+WorldLoadProgress(castle_world)+" - loading is complete"

    Flip

Wend

FreeWorld castle_world
End

Index