Blitz3D+ Command Reference

WorldAssetReady ( asset )

Parameters

asset - an asset handle returned by FindWorldAsset

Description

Returns True once a world asset is finalized and safe to consume.

When it returns True, the asset's typed accessor (WorldAssetTexture, WorldAssetSound, WorldAssetShader) or CreateWorldAsset for a model will succeed; calling them earlier is a runtime error. Assets declared with required policy are always ready by the time their world is, so this query matters for the other two policies: streaming assets become ready one by one while you play, and manual assets become ready some time after FindWorldAsset first triggers their preparation.

If an asset never becomes ready, ask WorldAssetError - a failed optional or manual asset stays not-ready forever but does not fail its world, so a polling loop should check both.

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

Requires Extended mode.

See also: FindWorldAsset, WorldAssetError, WorldAssetTexture, CreateWorldAsset, WorldStreaming.

Example

; WorldAssetReady 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 plain crate that will receive its texture once the asset is ready
crate=CreateCube()
PositionEntity crate,0,1,0

; Load the asset manifest world in the background
manifest=LoadWorldAsync("../../../samples/worlds/asset-preload.world")
While Not WorldReady(manifest)
    If WorldLoadState(manifest)=WORLD_LOAD_FAILED Then RuntimeError WorldLoadError(manifest)
    Cls
    Text 0,0,"Loading the asset manifest..."
    Flip
Wend

; 'manual-texture' uses manual loading policy: resolving the handle
; starts its background preparation
asset=FindWorldAsset(manifest,"manual-texture")
tex=0

While Not KeyDown(1)

    If WorldAssetError(asset)<>"" Then RuntimeError WorldAssetError(asset)

    ; The moment WorldAssetReady reports true, use the asset
    If tex=0 And WorldAssetReady(asset)
        tex=WorldAssetTexture(asset)
        EntityTexture crate,tex
    EndIf

    TurnEntity crate,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,"WorldAssetReady(asset) = "+WorldAssetReady(asset)
    If tex Then Text 0,40,"The crate wears the texture that just became ready"

    Flip

Wend

If tex Then FreeTexture tex
FreeWorld manifest
End

Index