Blitz3D+ Command Reference

WaitJoy ( [port] )

Parameters

port (optional) - which joystick to wait on; 0 is the first stick (default)

Description

Halts the program until a joystick button is pressed, then returns its number.

It is the pad version of WaitKey - the "press fire to start" pause for a title screen or an attract mode, with the button number coming back so you can act on which one was used.

The gotcha is that it blocks. Your loop stops, nothing animates, and anything drawn to the back buffer is still invisible, so draw the screen and Flip it before you call. It polls about fifty times a second while it waits and keeps the window responsive, and if the player closes the window instead of pressing anything the program ends there. In a running game use JoyHit inside your main loop instead.

Heads up: the current DirectX 12 runtime does not enumerate joysticks - it reports zero attached devices - so WaitJoy returns 0 immediately rather than waiting for anything. An out-of-range port behaves the same way. That is safer than hanging, but it also means a pause screen built only on WaitJoy will flash straight past, so guard it with JoyType and offer WaitKey as the fallback.

JoyWait is the same command under an older name.

See also: JoyWait, JoyHit, GetJoy, JoyType, WaitKey, WaitMouse.

Example

; WaitJoy Example
; ---------------

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

; WaitJoy halts the program until a joystick button is pressed and
; returns its number - a classic "press fire to start" pause.
; Draw the pause frame BEFORE blocking - and never block at all
; when no joystick is attached, or the wait could never end.
Cls
If JoyType()=0 Then
    Text 320,200,"No joystick detected - plug in a gamepad to try WaitJoy.",True
    Text 320,220,"WaitJoy would halt forever without one, so it is skipped.",True
Else
    Text 320,200,"*  G A M E   P A U S E D  *",True
    Text 320,220,"Press any pad button to resume",True
End If
Flip

button=0
If JoyType()>0 Then button=WaitJoy() ; blocks until a pad button is pressed

While Not KeyDown(1)

    Cls

    Text 0,0,"Esc: exit"
    If button>0 Then
        Text 0,20,"WaitJoy() returned button number "+button+" - game resumed!"
    Else
        Text 0,20,"WaitJoy() was skipped - no joystick attached."
    End If

    Flip

Wend

End

Index