# getGamepads()

The `getGamepads()` function provides access to connected game controllers in OSL applications. It returns an array of gamepad objects with normalized properties for easy access to controller inputs.

```javascript
// Get all connected gamepads
array gamepads = getGamepads()

// Check if any gamepad is connected
if gamepads.len > 0 (
  // Use the first gamepad
  gamepad @= gamepads[1]
  say "Gamepad mode enabled"
)
```

## Return Value

Returns an array of gamepad objects, with each object containing the following properties:

* `id`: String identifying the gamepad
* `index`: Numeric index of the gamepad
* `connected`: Boolean indicating if the gamepad is connected
* `timestamp`: The last time the gamepad state was updated
* `mapping`: String indicating the mapping type (e.g., "standard")
* `axes`: Array of objects representing analog sticks, each with:
  * `x`: X-axis value (range: -1.0 to 1.0)
  * `y`: Y-axis value (range: -1.0 to 1.0, inverted for natural directional control)
* `buttons`: Array of button objects, each with:
  * `pressed`: Boolean indicating if the button is pressed
  * `touched`: Boolean indicating if the button is touched
  * `value`: Numeric value of the button pressure (range: 0.0 to 1.0)
* `haptic`: Function to trigger vibration feedback on the controller (when supported)

## Common Button Indexes

Standard gamepad mappings can be found below:[Mappings](https://w3c.github.io/gamepad/#remapping)

## Example application

An app with support for gamepads is Arrow by Mist, source code found below:

[Arrow On Github](https://github.com/RoturTW/apps/blob/main/all/arrow/script.osl)

## Example: Checking a Specific Button Press

```javascript
if gamepads.len > 0 (
  // Check if the A button (index 1) is pressed
  if gamepads[1].buttons[1]["pressed"] (
    say "A button pressed!"
  )
)
```

## Example: Reading Analog Stick Values

```javascript
if gamepads.len > 0 (
  // Get left stick X and Y values
  leftX = gamepads[1].axes[1].x
  leftY = gamepads[1].axes[1].y
  
  // Move a character based on left stick position
  player.x += leftX * player.speed
  player.y += leftY * player.speed
)
```

## Example: Using Haptic Feedback

```javascript
if gamepads.len > 0 (
  // Trigger vibration on the controller
  void gamepads[1].haptic({
    duration: 100,       /* vibration duration in milliseconds */
    weakMagnitude: 0.5,  /* intensity of the weak motor (0.0 to 1.0) */
    strongMagnitude: 0.8  /* intensity of the strong motor (0.0 to 1.0) */
  })
)
```

## Notes

* If no gamepads are connected, the function returns an empty array.
* Gamepad support varies by browser and device.
* The haptic function may not work on all controllers or platforms.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://osl.mistium.com/functions/getgamepads.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.