Blitz3D+ Command Reference

WorldStreaming ( world )

Parameters

world - a world handle, usually one returned by LoadWorldAsync

Description

Returns True while a ready world's streaming assets are still arriving in the background.

A .world file can mark assets with streaming policy: nice-to-have content like later music tracks or cosmetic textures that should not hold up the first playable frame. WorldReady does not wait for them - they start automatically once the required content is prepared and keep loading while you play. WorldStreaming is True during that tail end of loading, and False once everything has arrived.

It also returns False when the world is not ready yet, when the world has no streaming assets, when the load was started with WORLD_LOAD_NO_STREAMING, and for plain CreateWorld worlds. A streaming asset that fails does not fail the world - its error is reported by WorldAssetError on that asset.

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

Requires Extended mode.

See also: WorldStreamingProgress, LoadWorldAsync, WorldReady, WorldAssetReady, WorldAssetError.

Example

; WorldStreaming 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

; The castle world declares its sound effects with streaming policy,
; so they may keep loading after the required world is playable
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)
    TurnEntity spinner,0.5,1,0.25
    RenderWorld
    Text 0,0,"Loading the required castle content..."
    Text 0,20,"Progress: "+(WorldLoadProgress(castle_world)/10.0)+"%"
    Flip
Wend

; Enter the castle immediately - no need to wait for streaming assets
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

    ; WorldStreaming reports whether optional assets are still arriving
    Text 0,0,"Arrow keys: move camera   Esc: exit"
    If WorldStreaming(castle_world)
        Text 0,20,"WorldStreaming(castle_world) = 1 - optional assets still arriving"
    Else
        Text 0,20,"WorldStreaming(castle_world) = 0 - every optional asset is prepared"
    EndIf

    Flip

Wend

FreeWorld castle_world
End

Index