Blitz3D+ Command Reference

WorldAssetError$ ( asset )

Parameters

asset - an asset handle returned by FindWorldAsset

Description

Returns the retained error text for a failed world asset, or an empty string.

Required assets that break fail the whole load (see WorldLoadError), but streaming and manual assets fail quietly on their own: the world stays perfectly playable, the asset just never becomes ready. This query tells you why - a missing file, a decode problem, or a memory-limit refusal - so you can log it or fall back to a default resource.

The usual pattern pairs it with WorldAssetReady in a polling loop: not ready and no error means still preparing; not ready with an error means give up on that asset. It returns an empty string while an asset is still preparing and after it loads successfully.

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

Requires Extended mode.

See also: WorldAssetReady, FindWorldAsset, WorldLoadError, WorldStreaming.

Example

; WorldAssetError 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 warning-red cube marks the broken asset in our scene
cube=CreateCube()
PositionEntity cube,0,1,0
EntityColor cube,255,80,80

; 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

; 'broken-sound' deliberately points at an image file, so its
; background preparation is doomed to fail; 'ready-sound' is fine.
; Resolving a manual asset starts its preparation
broken_asset=FindWorldAsset(manifest,"broken-sound")
good_asset=FindWorldAsset(manifest,"ready-sound")

While Not KeyDown(1)

    ; An empty string means no error has occurred (yet)
    broken_error$=WorldAssetError(broken_asset)
    good_error$=WorldAssetError(good_asset)

    TurnEntity cube,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,"WorldAssetError$(good_asset) = '"+good_error+"'"
    Text 0,40,"WorldAssetError$(broken_asset) = '"+broken_error+"'"

    Flip

Wend

FreeWorld manifest
End

Index