Blitz3D+ Command Reference

WorldEntityMetadata$ ( entity,key$ )

Parameters

entity - an entity published from a .world document

key$ - the metadata key to look up

Description

Returns the authored string metadata stored on a .world entity for a key, or an empty string.

A .world entity can carry a bag of designer-authored key/value strings - "enemyType"="grunt", "loot"="gold-small", "dialog"="intro-guard" - and this is how gameplay code reads them. It replaces the old trick of smuggling data into entity names and parsing them back out: the level defines the data, FindWorldEntity (or a collision) hands you the entity, and WorldEntityMetadata hands you the values.

A key the entity does not have returns an empty string, and so does any entity that was not created from a .world document. Values are read-only snapshots of the authored source - the runtime never changes them.

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

Requires Extended mode.

See also: FindWorldEntity, WorldEntityID, LoadWorldAsync.

Example

; WorldEntityMetadata Example
; ---------------------------
; Requires Extended mode.

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

; Load a world whose author placed a spawn marker carrying metadata
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

; The authored marker entity, found by its stable ID
spawn=FindWorldEntity(world,"player-spawn")

; WorldEntityMetadata$ reads authored string metadata by key;
; a key the author never set returns an empty string
role$=WorldEntityMetadata(spawn,"game.marker")
loot$=WorldEntityMetadata(spawn,"game.loot")

; Let the metadata drive game logic: spawn a green player cone
; on a marker whose role says it is the player spawn
player=CreateCone()
PositionEntity player,EntityX(spawn),EntityY(spawn),EntityZ(spawn)
If role="player-spawn" Then EntityColor player,80,220,120 Else EntityColor player,220,80,80
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,"WorldEntityMetadata$(spawn,'game.marker') = '"+role+"'"
    Text 0,40,"WorldEntityMetadata$(spawn,'game.loot') = '"+loot+"' (unset keys are empty)"

    Flip

Wend

FreeWorld world
End

Index