Blitz3D+ Command Reference

PositionEntity entity,x#,y#,z#[,global]

Parameters

entity - entity handle

x# - x coordinate that entity will be positioned at
y# - y coordinate that entity will be positioned at
z# - z coordinate that entity will be positioned at

global (optional) - true to position relative to 0,0,0 rather than to a parent entity's position; false (default)

Description

Positions an entity at an absolute position in 3D space.

Entities live in an x,y,z coordinate system. 0,0,0 is the centre of the world; with a camera at the origin facing the default direction, a positive z puts an entity in front of the camera, positive x is to its right and positive y is up. Use PositionEntity to place things - spawn points, level layout, teleports - and the relative commands to move them about afterwards.

For a child entity, the coordinates are relative to its parent unless you pass true for global, in which case the entity is placed at the given world position regardless of where its parent is.

This is one of three ways to change position:

PositionEntity - jumps the entity to an absolute position.
MoveEntity - moves along the entity's own local axes (direction depends on which way it faces).
TranslateEntity - moves along the world axes, ignoring the entity's orientation.

Gotcha: teleporting an entity that uses the collision system can leave a huge one-frame movement for collisions to resolve; call ResetEntity after a big reposition to forget the old position.

See also: MoveEntity, TranslateEntity, ResetEntity, PositionMesh.

Example

; PositionEntity Example
; ----------------------

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

camera=CreateCamera()
PositionEntity camera,0,0,-10

light=CreateLight()
RotateEntity light,45,45,0

; A beacon placed by absolute coordinates
beacon=CreateSphere(16)
ScaleEntity beacon,0.5,0.5,0.5
EntityColor beacon,255,60,60

x#=0
y#=0
z#=0

While Not KeyDown(1)

    ; Cursor keys and A/Z adjust the target coordinates
    If KeyDown(203) Then x=x-0.1
    If KeyDown(205) Then x=x+0.1
    If KeyDown(208) Then y=y-0.1
    If KeyDown(200) Then y=y+0.1
    If KeyDown(44) Then z=z-0.1
    If KeyDown(30) Then z=z+0.1

    ; PositionEntity places the beacon at an ABSOLUTE point in world space.
    ; Compare MoveEntity (relative, local axes) and TranslateEntity
    ; (relative, world axes).
    PositionEntity beacon,x,y,z

    RenderWorld

    Text 0,0,"Cursors/A/Z: change coordinates   Esc: exit"
    Text 0,20,"PositionEntity beacon,"+x+","+y+","+z

    Flip

Wend

End

Index