LoadWorldAsync ( file$[,flags] )
Parameters
|
file$ - path to a .world scene file (strict UTF-8 JSON). Relative asset paths inside the file resolve from the .world file's own directory, not from your program's current directory. flags (optional) - loading options: WORLD_LOAD_DEFAULT (0): load required content, then stream optional assets automatically (default) WORLD_LOAD_NO_STREAMING (1): skip automatic streaming of optional assets |
Description
|
Starts loading a .world scene in the background and returns its world handle at once. This is how you load the next level while the current one keeps running: your game continues to update, render, play audio, and take input while Blitz3D+ reads, validates, decodes, and finalizes the new world behind the scenes. The classic pattern is a loading screen in one world and the real level arriving in another. The returned handle is a normal world handle, but it cannot be selected, rendered, updated, parented into, or used for audio until WorldReady returns True - doing so earlier is a runtime error. While waiting, show WorldLoadProgress and WorldLoadStage, and always check WorldLoadState for WORLD_LOAD_FAILED and WORLD_LOAD_CANCELLED - a failed load never becomes ready, and WorldLoadError explains what went wrong. A failed or cancelled load never changes your selected graphics or audio world. The main-thread finalization work happens automatically: Flip, FlipCanvas, Delay, and WaitTimer each service loading under the budget set by SetAsyncLoadBudget. A loop without any of those commands should call UpdateAsyncLoads itself. When you are done with a loaded world (or want to abandon a load immediately), free it with FreeWorld; to cancel politely and keep the handle around, use CancelWorldLoad. By default up to 8 worlds can load at the same time - starting more is a runtime error. A load that would exceed the engine's memory limits fails with the details in WorldLoadError. A .world file can also be an asset-only preload manifest with no placed entities; resolve its content through FindWorldAsset once ready. For the full story, see the Async World Loading guide. Requires Extended mode. See also: WorldReady, WorldLoadState, WorldLoadProgress, WorldLoadError, CancelWorldLoad, FreeWorld. |
Example
; LoadWorldAsync Example ; ---------------------- ; Requires Extended mode. Graphics3D 640,480,0,2 SetBuffer BackBuffer() ; A simple loading screen lives in the default world camera=CreateCamera() PositionEntity camera,0,0,-5 light=CreateLight() RotateEntity light,45,45,0 spinner=CreateCube() EntityColor spinner,80,170,255 ; Start loading the castle world in the background ; (the path is relative to this example's directory) castle_world=LoadWorldAsync("../../../samples/worlds/castle/castle.world") ; The loading screen keeps animating while the castle loads While Not WorldReady(castle_world) If WorldLoadState(castle_world)=WORLD_LOAD_FAILED Then RuntimeError WorldLoadError(castle_world) TurnEntity spinner,0.5,1,0.25 RenderWorld Text 0,0,"Loading the castle world..." Text 0,20,"Progress: "+(WorldLoadProgress(castle_world)/10.0)+"% Stage: "+WorldLoadStage(castle_world) Flip Wend ; The world is ready: select it and use its authored camera SetWorld castle_world castle_cam=FindWorldEntity(castle_world,"camera-main") PointEntity castle_cam,FindWorldEntity(castle_world,"castle") ; A spinning beacon shows the loaded world animating beacon=CreateCube() ScaleEntity beacon,4,4,4 PositionEntity beacon,0,45,0 EntityColor beacon,255,200,80 While Not KeyDown(1) TurnEntity beacon,0,1,0 ; Arrow keys move the camera (bigger steps suit the castle's scale) If KeyDown(200) Then MoveEntity castle_cam,0,0,1 If KeyDown(208) Then MoveEntity castle_cam,0,0,-1 If KeyDown(203) Then TurnEntity castle_cam,0,1,0 If KeyDown(205) Then TurnEntity castle_cam,0,-1,0 RenderWorld Text 0,0,"Arrow keys: move camera Esc: exit" Text 0,20,"LoadWorldAsync loaded the castle while the loading screen kept running" Flip Wend FreeWorld castle_world End
Index