Blitz3D+ Command Reference

HandleSprite sprite,x_handle#,y_handle#

Parameters

sprite - sprite handle
x_handle# - horizontal pivot, in sprite units; 0 (default)
y_handle# - vertical pivot, in sprite units; 0 (default)

Description

Moves the pivot point of a sprite - the spot on the sprite that sits at its entity position.

A sprite spans from -1,-1 to +1,+1, and the handle is given in those same units: the point you name is the point that lands on the sprite position, and that the sprite rotates around. The default 0,0 puts the pivot in the middle, which is right for particles and explosions.

The classic case for changing it is a billboard tree. Its trunk should meet the ground at the sprite position, not float with the ground running through its middle, so HandleSprite tree,0,-1 moves the pivot to the bottom edge. The same trick puts a health bar above a character, hangs a sign from a bracket, or anchors a muzzle flash at the end of a barrel.

Because rotation happens about the handle, moving it also changes how RotateSprite behaves: a sprite handled at its bottom edge swings like a pendulum rather than spinning on the spot.

Values are not limited to the -1 to +1 range - larger numbers push the pivot outside the sprite altogether, which is one way to make something orbit a point.

See also: CreateSprite, LoadSprite, ScaleSprite, RotateSprite, SpriteViewMode.

Example

; HandleSprite Example
; --------------------

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

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

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

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

; A spinning logo sprite
logo=LoadSprite("media/b3dlogo.jpg")
ScaleSprite logo,1,0.5
PositionEntity logo,0,1.5,0

; A small marker fixed at the sprite's position, so you can see what
; point the sprite pivots around
pin=CreateSphere(8)
ScaleEntity pin,0.05,0.05,0.05
EntityColor pin,255,60,60
EntityFX pin,1
PositionEntity pin,0,1.5,0

; A sprite extends from -1,-1 to +1,+1 around its handle
hx#=0
hy#=0
info$="HandleSprite logo,0,0 (centre - spins in place)"

angle#=0

While Not KeyDown(1)

    ; Space cycles through three handle positions
    If KeyHit(57)
        preset=(preset+1) Mod 3
        If preset=0 Then hx=0 : hy=0 : info$="HandleSprite logo,0,0 (centre - spins in place)"
        If preset=1 Then hx=0 : hy=-1 : info$="HandleSprite logo,0,-1 (bottom edge - swings like a clock hand)"
        If preset=2 Then hx=-1 : hy=-1 : info$="HandleSprite logo,-1,-1 (corner - orbits the red pin)"
    EndIf

    ; HandleSprite moves the point the sprite hangs from and spins around
    HandleSprite logo,hx,hy

    ; Keep the sprite turning so the pivot point is obvious
    angle=angle+2
    RotateSprite logo,angle

    RenderWorld

    Text 0,0,"Space: cycle handle position   Esc: exit"
    Text 0,20,info$

    Flip

Wend

End

Index