Blitz3D+ Command Reference

JoyRoll# ( [port] )

Parameters

port (optional) - which joystick to read; 0, the first attached stick (default)

Description

Returns the joystick's rotation-z axis scaled to degrees, from -180.0 to 180.0.

The third of the flight-stick trio, after JoyPitch (rotation-x) and JoyYaw (rotation-y). Rotation about z is the axis most twist-handle sticks report when you twist the grip - the rudder twist - which makes JoyRoll the one of the three you are most likely to see moving on real hardware. Games use it for banking, rudder control, or leaning round corners.

The "degrees" are a convenience dressing, not a measured angle: the engine takes the axis's raw -1 to 1 travel and multiplies by 180, so centred rest is 0.0 and full twist either way reads +/-180.0.

As with its siblings, most ordinary gamepads have nothing wired to this axis and report 0.0 forever, and layouts differ between sticks that do - one maker's twist is another's paddle. A quick axis-test screen in your options menu saves support headaches.

The modern Blitz3D+ runtime does not implement joystick input yet: JoyType always reports 0 and JoyRoll always returns 0.0 there, whatever is plugged in - so for now the example shows its no-joystick screen.

See also: JoyPitch, JoyYaw, JoyZ, JoyHat, JoyType.

Example

; JoyRoll Example
; ---------------

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

While Not KeyDown(1)

    Cls

    ; JoyRoll returns the stick's rotation-z axis scaled to
    ; degrees, from -180.0 to 180.0. On many flight sticks the
    ; twist grip reports here - the wings bank left/right.
    roll#=JoyRoll()

    If JoyType()=0 Then
        Text 0,0,"Esc: exit"
        Text 0,60,"No joystick detected - plug in a flight stick to try this example."
        Text 0,80,"With one attached, the wings below bank with the twist axis."
    Else
        Text 0,0,"Twist the stick (roll axis)   Esc: exit"
    End If

    ; Cockpit view: a fixed horizon and a banking wing bar
    cx=320
    cy=280
    Color 90,90,90
    Line cx-160,cy,cx+160,cy ; the horizon line
    Text cx+170,cy-6,"horizon"

    ; The wing bar banks clockwise as roll goes positive
    Color 255,220,0
    Line cx-Cos(roll)*80,cy-Sin(roll)*80,cx+Cos(roll)*80,cy+Sin(roll)*80
    Oval cx-6,cy-6,12,12,False ; the cockpit marker

    Color 255,255,255
    Text 0,20,"JoyRoll() = "+roll+" degrees"
    Text 0,40,"(JoyPitch() = "+JoyPitch()+"   JoyYaw() = "+JoyYaw()+")"

    Flip

Wend

End

Index