Blitz3D+ Command Reference

VectorYaw# ( x#,y#,z# )

Parameters

x#,y#,z# - the direction vector to measure

Description

Returns the yaw angle, in degrees, that a direction vector is pointing.

Games are full of directions that arrive as three numbers - the gap between a turret and its target, a velocity, a surface normal, a joystick reading - and full of commands that want an angle instead. VectorYaw converts one to the other. Subtract the turret's position from the target's, feed the result in, and RotateEntity turret,0,VectorYaw(dx,dy,dz),0 swings it round to face the target exactly.

It measures the compass heading only: the y component is accepted but ignored, because yaw is the left-right half of an aim. Pair it with VectorPitch for the up-down half and you can point anything anywhere in one RotateEntity call.

The convention catches people out, so it is worth memorising the corners. Straight ahead, (0,0,1), is 0 degrees. To the right, (1,0,0), is -90 - not 90. To the left, (-1,0,0), is 90, and straight back, (0,0,-1), is 180. Angles increase turning to the left, which is the same direction TurnEntity and EntityYaw use, so everything stays consistent once you accept that right-hand headings are negative. A zero-length vector has no direction to report and comes back as 0.

The result is an absolute world heading, not a difference. If what you actually want is "how far do I need to turn from where I am facing", that is DeltaYaw, which does the subtraction and the wrapping for you.

See also: VectorPitch, DeltaYaw, EntityYaw, AlignToVector, PointEntity.

Example

; VectorYaw Example
; -----------------

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

camera=CreateCamera()
PositionEntity camera,0,7,-14
RotateEntity camera,20,0,0

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

ground=CreatePlane()
EntityTexture ground,LoadTexture("media/MossyGround.BMP")

; A turret that has to swing round to face whatever it is tracking
turret=CreateCube()
PositionEntity turret,0,1,0
barrel=CreateCylinder(12,True,turret)
ScaleEntity barrel,0.3,1.2,0.3
RotateEntity barrel,90,0,0
PositionEntity barrel,0,0,1.2

; The drone it is tracking, circling the turret
drone=CreateSphere(12)
ScaleEntity drone,0.5,0.5,0.5
EntityColor drone,240,120,60

radius#=6.0

While Not KeyDown(1)

    ; [ and ] change how wide the drone circles
    If KeyDown(26) And radius>2 Then radius=radius-0.05
    If KeyDown(27) And radius<10 Then radius=radius+0.05

    ; Fly the drone round the turret
    angle#=MilliSecs()/20.0
    PositionEntity drone,Sin(angle)*radius,1,Cos(angle)*radius

    ; The direction from the turret to the drone (both sit at the top level,
    ; so their local coordinates are already world coordinates)
    dx#=EntityX(drone)-EntityX(turret)
    dy#=EntityY(drone)-EntityY(turret)
    dz#=EntityZ(drone)-EntityZ(turret)

    ; VectorYaw turns that direction into a heading we can rotate to
    yaw#=VectorYaw(dx,dy,dz)
    RotateEntity turret,0,yaw,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,"[ / ]: change the drone's orbit   Arrows: camera   Esc: exit"
    Text 0,20,"VectorYaw("+dx+","+dy+","+dz+") = "+yaw
    Text 0,40,"RotateEntity turret,0,yaw,0 keeps the barrel on the drone"
    Text 0,60,"Straight ahead (0,0,1) is 0 degrees. VectorYaw(1,0,0) = "+VectorYaw(1,0,0)+", not 90"

    Flip

Wend

End

Index