Blitz3D+ Command Reference

WorldAssetSound ( asset )

Parameters

asset - a ready sound asset handle returned by FindWorldAsset

Description

Returns an ordinary sound handle from a ready sound asset.

The result behaves exactly like a LoadSound handle: PlaySound it, EmitSound it from an entity, loop it. Whether it acts as a positional 3D sound comes from the asset's spatial option in the .world file, the same way Load3DSound differs from LoadSound. The wave data was decoded on the background worker, so grabbing the handle costs no decode hitch.

The returned handle is yours: it stays valid after the source world is freed, and you must release it with FreeSound when you are done. The asset handle itself dies with its world.

The asset must be a sound and must be ready, or the call is a runtime error - check WorldAssetReady first for streaming or manual assets.

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

Requires Extended mode.

See also: FindWorldAsset, WorldAssetReady, WorldAssetTexture, WorldAssetShader, LoadSound, FreeSound.

Example

; WorldAssetSound 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 spinning crate stands in for a shooting player
crate=CreateCube()
PositionEntity crate,0,1,0
EntityColor crate,80,170,255

; 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

; WorldAssetSound turns the ready sound asset into an ordinary
; sound reference, decoded on a worker thread during loading
sound_asset=FindWorldAsset(manifest,"ready-sound")
sound=WorldAssetSound(sound_asset)

; The reference survives freeing the source manifest world
FreeWorld manifest

channel=0

While Not KeyDown(1)

    ; Space fires the asset sound
    If KeyHit(57) Then channel=PlaySound(sound)

    If channel And ChannelPlaying(channel) Then playing=1 Else playing=0

    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,"Space: play the asset sound   Arrow keys: move camera   Esc: exit"
    Text 0,20,"WorldAssetSound returned sound "+sound+"   playing = "+playing

    Flip

Wend

FreeSound sound
End

Index