Blitz3D+ Command Reference

SetWorld world

Parameters

world - the world to select, or 0 for the protected default world

Description

Selects the current world.

The selected world is where parentless Create, Load, and Copy entity commands put their new entities, and it is the world that world-global commands act on: UpdateWorld, RenderWorld, CaptureWorld, Collisions, ClearCollisions, AmbientLight, WireFrame, and friends. Switching worlds is how you flip between scenes - update and render the menu world this frame, the game world the next. Passing a parent entity to a creation command overrides the selection: the child always joins its parent's world.

SetWorld only changes the selection. It does not move any entities, does not update or render anything, and does not touch the audio world - route 3D audio separately with SetAudioWorld. Your program starts with the default world selected, and SetWorld 0 always gets you back to it.

A world loaded with LoadWorldAsync cannot be selected until WorldReady returns True - selecting a loading, failed, or cancelled handle is a runtime error. When the selected world is freed, selection falls back to the default world automatically.

Requires Extended mode.

See also: GetWorld, CreateWorld, FreeWorld, SetAudioWorld, WorldReady, RenderWorld.

Example

; SetWorld Example
; ----------------
; Requires Extended mode.

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

; The default world holds the game scene: a red spinning cube
game_world=GetWorld()
game_camera=CreateCamera()
PositionEntity game_camera,0,1,-5
game_light=CreateLight()
RotateEntity game_light,45,45,0
cube=CreateCube()
PositionEntity cube,0,1,0
EntityColor cube,255,80,80

; A separate world holds the preview scene: a blue spinning sphere.
; SetWorld makes it the target for parentless entity creation
preview_world=CreateWorld()
SetWorld preview_world
preview_camera=CreateCamera()
PositionEntity preview_camera,0,1,-5
preview_light=CreateLight()
RotateEntity preview_light,45,45,0
sphere=CreateSphere()
PositionEntity sphere,0,1,0
EntityColor sphere,80,140,255

; Select the game world to start with
SetWorld game_world
active_camera=game_camera

While Not KeyDown(1)

    ; Space selects the other world - RenderWorld draws the selected one
    If KeyHit(57)
        If GetWorld()=game_world
            SetWorld preview_world
            active_camera=preview_camera
        Else
            SetWorld game_world
            active_camera=game_camera
        EndIf
    EndIf

    ; Both scenes keep animating, even the one not selected
    TurnEntity cube,0,1,0
    TurnEntity sphere,0,1,0

    ; Arrow keys move the selected world's camera
    If KeyDown(200) Then MoveEntity active_camera,0,0,0.1
    If KeyDown(208) Then MoveEntity active_camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity active_camera,0,1,0
    If KeyDown(205) Then TurnEntity active_camera,0,-1,0

    RenderWorld

    Text 0,0,"Space: select the other world   Arrow keys: move camera   Esc: exit"
    If GetWorld()=game_world Then scene$="game world (red cube)" Else scene$="preview world (blue sphere)"
    Text 0,20,"SetWorld selected "+GetWorld()+" - the "+scene

    Flip

Wend

FreeWorld preview_world
End

Index