Blitz3D+ Command Reference

FindWorldEntity ( world,id$ )

Parameters

world - a ready world loaded with LoadWorldAsync

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

Description

Returns the published entity with a stable authored ID in a loaded world, or 0.

When a .world scene is ready, this is how your code finds the pieces the level designer placed: the main camera, the player spawn marker, the boss door. The IDs come straight from the authored source, so they are dependable across loads and machines - no scanning entity names and hoping. The result is an ordinary entity handle: move it, parent to it, attach gameplay to it.

The world must be ready - looking into a still-loading handle is a runtime error. An ID that is not in the document returns 0, as does a plain CreateWorld world (it has no document), and so does an authored entity you have since freed with FreeEntity. Pair it with WorldEntityMetadata to read designer-authored strings off the entities you find.

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

Requires Extended mode.

See also: WorldEntityID, WorldEntityMetadata, LoadWorldAsync, WorldReady, EntityWorld.

Example

; FindWorldEntity Example
; -----------------------
; Requires Extended mode.

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

; Load a world whose author placed an invisible spawn marker
; (the path is relative to this example's directory)
world=LoadWorldAsync("../../../samples/worlds/help-marker.world")
While Not WorldReady(world)
    If WorldLoadState(world)=WORLD_LOAD_FAILED Then RuntimeError WorldLoadError(world)
    Cls
    Text 0,0,"Loading the marker world..."
    Flip
Wend

; Select the loaded world and give it a camera and a light
SetWorld world
camera=CreateCamera()
PositionEntity camera,0,1,-5
light=CreateLight()
RotateEntity light,45,45,0

; FindWorldEntity looks up the authored marker by its stable ID;
; an ID that was never authored returns 0
spawn=FindWorldEntity(world,"player-spawn")
missing=FindWorldEntity(world,"boss-spawn")

; Spawn a visible player cone exactly where the marker sits
player=CreateCone()
PositionEntity player,EntityX(spawn),EntityY(spawn),EntityZ(spawn)
EntityColor player,80,220,120
PointEntity camera,player

While Not KeyDown(1)

    TurnEntity player,0,2,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,"FindWorldEntity(world,'player-spawn') = "+spawn
    Text 0,40,"The cone was spawned at the marker: "+EntityX(spawn)+","+EntityY(spawn)+","+EntityZ(spawn)
    Text 0,60,"FindWorldEntity(world,'boss-spawn') = "+missing+" (absent IDs return 0)"

    Flip

Wend

FreeWorld world
End

Index