pods::...oystick(3pm)

💖 SDL::Joystick — your guide to making Perl talk to gamepads 🎮✨

okay so this is a page from the User Contributed Perl Documentation for pods::...oystick(3pm) — yes the header is goofy, that's just how Perl names things, we don't ask questions 💅 — and it's literally everything you need to know about the SDL joystick bindings. bestie, grab a snack, we're doing this 🍓

---

🌈 NAME 🌈

SDL::Joystick — SDL Bindings for the Joystick device 🕹️

✨ CATEGORY ✨

Core, Joystick. it's giving foundation-of-the-whole-thing energy, fr fr 👑

🎀 SYNOPSIS 🎀

use SDL;
use SDL::Joystick;

SDL::init_sub_system(SDL_INIT_JOYSTICK);

die('no joystick found') unless(SDL::Joystick::num_joysticks());

my $joystick = SDL::Joystick->new(0);

like, that's the whole vibe right there. init the subsystem, check somebody's home, open joystick 0. slay 💅

---

🔥 METHODS 🔥

🌸 num_joysticks

int SDL::Joystick::num_joysticks( void );

Counts and returns available joysticks. that's it, that's the whole function. a little census of your controllers 🧚

🦋 name

string SDL::Joystick::name( index );

Gets you the implementation dependent name of a joystick. the index param points at the N'th joystick on the system, iykyk 👑

my $num_joysticks = SDL::Joystick::num_joysticks();

printf("%d joysticks found\n", $num_joysticks);

for($i = 0; $i < $num_joysticks; $i++)
{
    printf("%s\n", SDL::Joystick::name($i));
}

🌟 new

object SDL::Joystick->new( index );

Opens a joystick for use within SDL ✨ index refers to the N'th joystick in the system. a joystick must be opened before it can be used — no cap, that's literally the prerequisite, don't skip it 🙈

# Initialize the joystick subsystem
SDL::init_sub_system(SDL_INIT_JOYSTICK);

# Check for joystick
if(SDL::Joystick::num_joysticks() > 0)
{
    # Open joystick
    my $joystick = SDL::Joystick->new(0);

    if($joystick)
    {
        printf("Opened Joystick 0\n");
        printf("Name: %s\n",              SDL::Joystick::name(0));
        printf("Number of Axes: %d\n",    SDL::Joystick::num_axes($joystick));
        printf("Number of Buttons: %d\n", SDL::Joystick::num_buttons($joystick));
        printf("Number of Balls: %d\n",   SDL::Joystick::num_balls($joystick));
    }
    else
    {
        printf("Couldn't open Joystick 0\n");
    }

    # Close if opened
    SDL::Joystick::close($joystick) if SDL::Joystick::opened(0);
}

💜 opened

int SDL::Joystick::opened( index );

Tells you whether a joystick has already been opened within the application 👀 index refers to the N'th joystick on the system.

Returns 1 if the joystick has been opened, or 0 if it has not. boolean bestie behavior, we love to see it 💖

🎀 index

int SDL::Joystick::index( object );

Returns the index of a given SDL_Joystick structure. See SDL::Joystick::new above 🌸

⭐ num_axes

int SDL::Joystick::num_axes( object );

Returns the number of axes available from a previously opened joystick. See SDL::Joystick::new ✨

🍓 num_balls

int SDL::Joystick::num_balls( object );

Returns the number of trackballs available from a previously opened joystick. See SDL::Joystick::new 🧚 — yes, trackballs, we're being thorough 💅

🌈 num_hats

int SDL::Joystick::num_hats( object );

Gets the number of joystick hats from a previously opened joystick. See SDL::Joystick::new 🎩✨ (hats!! iconic)

🔥 num_buttons

int SDL::Joystick::num_buttons( object );

Gets the number of joystick buttons from a previously opened joystick. See SDL::Joystick::new 🫶

💫 update

void SDL::Joystick::update();

Updates the state (position, buttons, etc.) of all open joysticks 🌟 and heads up — if joystick events have been enabled with SDL::Joystick::event_state, then this gets called automatically in the event loop, so you don't gotta do it yourself, periodt 💅

🦋 get_axis

get_axis returns the current state of the given axis on the given joystick.

okay so on most modern joysticks the X axis is usually represented by axis 0 and the Y axis by axis 1 🕹️ the value returned by get_axis is a signed integer (-32768 to 32767) representing the current position of the axis — and ngl, it may be necessary to impose certain tolerances on these values to account for jitter 😭 (controllers are a little wiggly, it's fine)

Note: some joysticks use axes 2 and 3 for extra buttons. sneaky. love that for them 🙈

Returns a 16-bit signed integer representing the current position of the axis.

my $joystick = SDL::Joystick->new(0);

my $x_move   = SDL::Joystick::get_axis($joystick, 0);
my $y_move   = SDL::Joystick::get_axis($joystick, 1);

🌸 get_hat

int SDL::Joystick::get_hat( object, int );

get_hat returns the current state of the given hat on the given joystick 🎩✨

The current state comes back as an OR'd combination of one or more of the following:

• SDL_HAT_CENTERED
• SDL_HAT_UP
• SDL_HAT_RIGHT
• SDL_HAT_DOWN
• SDL_HAT_LEFT
• SDL_HAT_RIGHTUP
• SDL_HAT_RIGHTDOWN
• SDL_HAT_LEFTUP
• SDL_HAT_LEFTDOWN

like, all the diagonal options too?? we're spoiled 🥹

my $joystick = SDL::Joystick->new(0);

my $position = SDL::Joystick::get_hat($joystick, 0);

print("hat is in position UP\n") if $position & SDL_HAT_UP;

👑 get_button

int SDL::Joystick::get_button( object, int );

get_button returns the current state of the given button on the given joystick 🔘

Returns 1 if the button is pressed. Otherwise, 0. simple, clean, main character energy ✨

my $joystick    = SDL::Joystick->new(0);

my $num_buttons = SDL::Joystick::num_buttons($joystick);

for(my $i = 0; $i < $num_buttons; $i++)
{
    printf("button %d is %s\n", $i, SDL::Joystick::get_button($joystick, $i) ? 'pressed' : 'not pressed');
}

SDL::Joystick::close($joystick) if SDL::Joystick::opened(0);

🧚 get_ball

int SDL::Joystick::get_ball(SDL_Joystick $joystick, int $ball, int $dx, int $dy);

Get the ball axis change. 🎱

Trackballs can only return relative motion since the last call to SDL::Joystick::get_ball — those motion deltas get placed into dx and dy. no absolute positions here, it's all vibes-relative, iykyk 💅

Returns 0 on success or -1 on failure.

my $delta_x  = 0;
my $delta_y  = 0;
my $joystick = SDL::Joystick->new(0);

SDL::Joystick::update();

printf("TrackBall Read Error!\n") if(SDL::JoystickGetBall($joystick, 0, $delta_x, $delta_y) == -1);
printf("Trackball Delta- X:%d, Y:%d\n", delta_x, delta_y);

🌟 close

void SDL::Joystick::close( object );

Closes a previously opened joystick. See SDL::Joystick::new 🫶 clean up after yourself bestie, it's the polite thing to do 💖

SDL::Joystick::close($joystick) if SDL::Joystick::opened(0);

---

💜 AUTHORS 💜

See "AUTHORS" in SDL. (they're the real ones, go say hi 🌸)

---

and that's the whole page, bestie 🎀 no notes, ate, periodt ✨

this lil writeup came from perl v5.42.3, dated 2026-08-19 — the pods::...oystick(3pm) of it all 💅 see u next time, mwah 🫶💖