Gamepad

The gamepad is based on an XBox-style gamepad. Scion2D supports up to 4 controllers/gamepads. The gamepad usually will have two analog thumb sticks, a D-Pad, four face buttons, two shoulder buttons, two analog trigger buttons, and two center buttons.

Action Buttons

Button	Type	Description
GP_BTN_A	action button	One of the four action buttons on the controller. Usually the `A` button on the XBox and the `Circle` button on a playstation style controller.
GP_BTN_B	action button	One of the four action buttons on the controller. Usually the `B` button on the XBox and the `Circle` button on a playstation style controller.
GP_BTN_X	action button	One of the four action buttons on the controller. Usually the `X` button on the XBox and the `Circle` button on a playstation style controller.
GP_BTN_A	action button	One of the four action buttons on the controller. Usually the `Y` button on the XBox and the `Circle` button on a playstation style controller.

Special Buttons

Button	Type	Description
GP_BTN_BACK	special button	One of the three special buttons on the controller. Usually the `SELECT` button on the XBox and the `Circle` button on a playstation style controller.
GP_BTN_START	special button	One of the three special buttons on the controller. Usually the `START` button on the XBox and the `Circle` button on a playstation style controller.
GP_BTN_GUIDE	special button	One of the three special buttons on the controller. May not be supported by your controller.

Axes

The axes are buttons and joysticks that use analog input values rather than a digital/bool input.

Button	Type	Description
AXIS_X1	x axis	Axis X1 is the horizontal axis of the `LEFT` analog stick. The analog values are `-32768` for fully left and `32767` for fully right.
AXIS_Y1	y axis	Axis Y1 is the vertical axis of the `LEFT` analog stick. The analog values are `-32768` for fully up and `32767` for fully down.
AXIS_X2	x axis	Axis X2 is the horizontal axis of the `RIGHT` analog stick. The analog values are `-32768` for fully left and `32767` for fully right.
AXIS_Y2	y axis	Axis Y2 is the vertical axis of the `RIGHT` analog stick. The analog values are `-32768` for fully up and `32767` for fully down.
AXIS_Z1	z axis	Axis Z1 is the axis for the `LEFT` trigger analog. The analog values are `-32768` for fully released and `32767` for fully pressed.
AXIS_Z2	y axis	Axis Z2 is the vertical axis of the `RIGHT` trigger analog. The analog values are `-32768` for fully released and `32767` for fully pressed.

Hat Values

Not all controllers have hats. The hat is basically the DPAD; however, it also has the diagonal directions. We use the hat values based on a number that is returned depending on the direction that is pressed. The typical hat values are as follows:

Direction	Hat Value
UP	1
RIGHT	2
UP RIGHT	3
DOWN	4
DOWN RIGHT	6
LEFT	8
UP LEFT	9
DOWN LEFT	12

Functions:

All of the controller functions take the index of which controller is being used. We are allowed up to 4 controllers in the engine. The index is basically the SLOT of the controller.

Function	Description
just_pressed(index, btn)	The just pressed function is used when the user only wants the `btn` to register once per press, and the reset upon released.
just_released(index, btn)	This will return true whenever the `btn` argument has been released.
pressed(index, btn)	Returns true whenever the button is held down. Used when the user needs continuous input from the btn.
get_axis_position(index, axis)	This will return an analog value for the desired axis. The value returned will be between `-32768 and 32767`. Please see the Axes for more information.
get_hat_value(index)	This will return the current value of the controllers `HAT`, if the controller has a hat. Please see the Hat Values for more information.

Examples

Left Stick Analog


    -- Get current x speed from the analog value
    local x_analog = Gamepad.get_axis_position(1, AXIS_X1) 
    local x_multiplier = x_analog / 32768
    local x_speed = speed * x_multiplier

    -- Get current y speed from the analog value
    local y_analog = Gamepad.get_axis_position(1, AXIS_Y1) 
    local y_multiplier = y_analog / 32768
    local y_speed = speed * y_multiplier

    -- Set the linear velocity
    local physics = entity:get_component(Physics)
    physics:set_linear_velocity(x_speed, y_speed)
    
    -- This does not take into consideration the dead zone of the axis
    -- The dead zone varies from controller to controller

Using hat values for movement


    -- Get the hat value for controller 1
    local direction = Gamepad.get_hat_value(1)
    
    -- move the player based on the current hat value
    if direction == 0 then 
        -- TODO: Stop the player
    elseif direction == 1 then 
        -- TODO: Move the player up
    elseif direction == 2 then 
        -- TODO: Move the player right
    elseif direction == 3 then 
        -- TODO: Move the player up to the right
    elseif direction == 4 then 
        -- TODO: Move the player down
    elseif direction == 6 then 
        -- TODO: Move the player down to the right
    elseif direction == 8 then 
        -- TODO: Move the player left
    elseif direction == 9 then 
        -- TODO: Move the player up to the left
    elseif direction == 12 then 
        -- TODO: Move the player down to the left
    end

    -- This is a simplification of what we could use
    -- the hat values for.

Using just_pressed for UI


    if Gamepad.just_pressed(1, GP_DPAD_UP) then 
        -- Move cursor up
    elseif Gamepad.just_pressed(1, GP_DPAD_RIGHT) then 
        -- Move cursor right
    elseif Gamepad.just_pressed(1, GP_DPAD_DOWN) then 
        -- Move cursor down
    elseif Gamepad.just_pressed(1, GP_DPAD_LEFT) then 
        -- Move cursor left
    end

Scion2D Documentation