FindWorldAsset ( world,id$ )

Parameters

world - a ready world loaded with LoadWorldAsync

id$ - the asset's stable ID as authored in the .world file

Description

Returns the asset handle for a stable ID declared in a loaded .world file, or 0.

This is the doorway into a world's asset list - especially an asset-only preload manifest, where a .world file declares textures, sounds, models, shaders, and heightmaps for your game to consume by ID instead of repeating file paths everywhere. Pass the handle it returns to WorldAssetReady, WorldAssetKind, and the typed accessors (WorldAssetTexture, WorldAssetSound, WorldAssetShader) or to CreateWorldAsset for models.

The world must be ready - looking into a still-loading handle is a runtime error. An ID that is not in the manifest returns 0, as does asking a plain CreateWorld world (it has no manifest). Resolving an asset declared with manual policy for the first time starts its background preparation: poll WorldAssetReady and check WorldAssetError before using a typed accessor.

Asset handles belong to their world: after FreeWorld they become invalid and using one is a runtime error. The public textures, sounds, and shaders returned by the typed accessors are separate handles and survive.

For the full story, see the Async World Loading guide and the Building .world Asset Collections guide.

Requires Extended mode.

See also: WorldAssetReady, WorldAssetError, WorldAssetKind, WorldAssetTexture, CreateWorldAsset, WorldAssetID.

Example

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

; Load the asset manifest world in the background
; (the path is relative to this example's directory)
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

; FindWorldAsset resolves a stable authored ID to an asset handle;
; an ID that is not in the manifest returns 0
texture_asset=FindWorldAsset(manifest,"display-texture")
missing_asset=FindWorldAsset(manifest,"no-such-id")

; Put the found asset to work: texture a spinning crate
tex=WorldAssetTexture(texture_asset)
crate=CreateCube()
PositionEntity crate,0,1,0
EntityTexture crate,tex

While Not KeyDown(1)

    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,"FindWorldAsset(manifest,'display-texture') = "+texture_asset
    Text 0,40,"FindWorldAsset(manifest,'no-such-id') = "+missing_asset+" (absent IDs return 0)"

    Flip

Wend

FreeTexture tex
FreeWorld manifest
End

Index

Blitz3D+ Command Reference

FindWorldAsset ( world,id$ )

Parameters

Description

Example