|
entity - an entity published from a .world document key$ - the metadata key to look up |
|
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. See also: CountWorldEntityMetadata, WorldEntityMetadataKey, FindWorldEntity, WorldEntityID, LoadWorldAsync. |
; WorldEntityMetadata Example
; ---------------------------
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