| asset - an asset handle returned by FindWorldAsset |
|
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. In a world loaded with WORLD_LOAD_PLACEHOLDERS, a model, picture, heightmap, sound or shader whose file is missing or cannot be read loads as a placeholder - a magenta checkered box for a model - so it is ready and still has an error: the error says why the placeholder stands in for it, such as "The file is missing: " and the file's path. An editor can show that next to the object, as the World Editor does. For the full story, see the Async World Loading guide. See also: WorldAssetReady, FindWorldAsset, WorldLoadError, WorldStreaming. |
; WorldAssetError Example
; -----------------------
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