|
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): no streaming at all - skip automatic streaming of optional assets, and load all of the world's data at once even when its Loading settings ask for world streaming WORLD_LOAD_BEHAVIOURS_OFF (2): load the built-in behaviours switched off, for a program that drives everything itself; EnableBehaviour switches one on WORLD_LOAD_KEEP_ENTITIES (4): behaviours and zone triggers that remove an object hide it instead, for an editor that keeps handles to the world's entities WORLD_LOAD_PLACEHOLDERS (8): a model, picture, heightmap, sound or shader whose file is missing or cannot be read loads as a placeholder instead of failing the world, for an editor or tool that shows the rest WORLD_LOAD_STREAMING (16): stream the world's objects' data - meshes and textures load as cameras come near, and unload when memory runs short; see SetWorldStreaming Add flags together to combine them. |
|
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. A big world can stream. With WORLD_LOAD_STREAMING, or when the world's own Loading settings turn streaming on, the world places every object as usual, but WorldReady comes as soon as what the start view needs has loaded: the rest loads as cameras come near, and what is far away unloads again when memory runs short. Your program sees no difference apart from timing - anything that reads data not loaded loads it on the spot. See SetWorldStreaming and PreloadWorldView. A required asset whose file is missing or cannot be read fails the whole load, so a game never starts a level with a hole in it. A level editor, a mod loader or a tool that shows other people's worlds can pass WORLD_LOAD_PLACEHOLDERS instead: each such model loads as a magenta checkered box, 1 unit wide and 1 high, standing where the model would; a picture as that checker; a heightmap as flat ground; a sound as silence; and a shader as the standard one. The asset is then ready, and WorldAssetError says what is wrong with it. A placeholder box has no material slots, animations or levels of detail, so the world leaves those out, and anchors and bone attachments on it, keeping the objects where they were authored. The next load tries the files again. 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. See also: WorldReady, WorldLoadState, WorldLoadProgress, WorldLoadError, CancelWorldLoad, FreeWorld. |
; LoadWorldAsync Example
; ----------------------
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