Blitz3D+ Command Reference

AlignToVector entity,vector_x#,vector_y#,vector_z#,axis[,rate#]

Parameters

entity - entity handle

vector_x# - x component of the vector
vector_y# - y component of the vector
vector_z# - z component of the vector

axis - axis of the entity that will be aligned to the vector
1: x-axis
2: y-axis
3: z-axis

rate# (optional) - how much of the remaining angle is turned each call, in the range 0 to 1. Values near 0 give a slow, smooth swing; 1 (default) snaps the entity to the vector instantly.

Description

Aligns an entity axis to a vector.

The entity is rotated so that its chosen local axis points along the vector. Align the z-axis (axis 3) to make an entity face along a direction of travel, or the y-axis (axis 2) to stand it upright on a surface. A classic use is tilting a car or character to match sloped ground: feed the surface normal from CollisionNX/CollisionNY/CollisionNZ (or PickedNX/NY/NZ) in as the vector.

Only the direction of the vector matters - it does not need to be unit length. A zero-length vector is ignored.

With a rate below 1 the entity turns only part of the way each call, so keep calling AlignToVector every frame in your main loop and the entity will ease smoothly onto the vector. With rate 1 a single call is enough.

See also: PointEntity, RotateEntity, TurnEntity, VectorPitch, VectorYaw.

Example

; AlignToVector Example
; ---------------------

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

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

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

; A compass needle that will swing to follow a vector
needle=CreateCone(16)
ScaleEntity needle,0.5,1.5,0.5
EntityColor needle,255,200,0

rate#=1.0

While Not KeyDown(1)

    ; [ / ] change the alignment rate: 1 snaps, near 0 swings smoothly
    If KeyDown(26) And rate>0.02 Then rate=rate-0.01
    If KeyDown(27) And rate<1 Then rate=rate+0.01

    ; The target vector rotates over time
    vx#=Sin(MilliSecs()/20.0)
    vy#=Cos(MilliSecs()/20.0)

    ; Align the needle's y axis (axis 2) to the rotating vector
    AlignToVector needle,vx,vy,0,2,rate

    ; 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,"[ / ] : alignment rate   Arrow keys: move camera   Esc: exit"
    Text 0,20,"AlignToVector needle,"+vx+","+vy+",0,2,"+rate

    Flip

Wend

End

Index