# Virtual gamepad (touch) (input.virtualpad)

## What it is for

Shows an on-screen gamepad for touch screens, fully data-driven: sticks, buttons and d-pads placed per orientation, grouped in layouts switched at run time, feeding input.actions like a physical gamepad.

It needs `input.actions`, `game.engine`; installing it brings them in.

## Turn it on

Install the kit in a project, then change a setting (the values shown are its defaults):

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "input.virtualpad" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "input.virtualpad",
                              config: { "mode": "auto", "layout": "foot" } }
```

## First example

<!-- test: kits/game_engine/host/tests/input_virtualpad.rs::the_pad_hides_under_a_menu_and_its_settings_are_the_players -->
This is the body of the passing test `the_pad_hides_under_a_menu_and_its_settings_are_the_players`; the helper functions it calls are defined at the top of the same test file.

```rust
#[test]
fn the_pad_hides_under_a_menu_and_its_settings_are_the_players() {
    let mut s = session(json!({ "mode": "shown" }));
    assert_eq!(
        call(&mut s, "pointerDown", json!([1, 1161, 601])),
        json!("jump")
    );
    s.apply(&json!({ "op": "set", "path": "menu.open", "value": true }))
        .unwrap();
    step(&mut s);
    // Hidden: what was held is released.
    assert_eq!(call(&mut s, "visible", json!([])), json!(false));
    assert_eq!(call(&mut s, "feeding", json!([]))["buttons"], json!([]));
    assert_eq!(call(&mut s, "setOption", json!(["size", 120])), json!(true));
    assert_eq!(
        call(&mut s, "setOption", json!(["opacity", 5])),
        json!(true)
    );
    assert_eq!(
        call(&mut s, "setOption", json!(["mode", "hidden"])),
        json!(true)
    );
    assert_eq!(
        call(&mut s, "values", json!([])),
        json!({ "mode": "hidden", "opacity": 0.2, "scale": 1.2 })
    );
    assert_eq!(call(&mut s, "reload", json!([])), json!(true));
    assert_eq!(
        call(&mut s, "icon", json!(["jump"]))["strokes"],
        json!([[0.5, 0.8333, 0.5, 0.25], [0.25, 0.5, 0.5, 0.25, 0.75, 0.5]])
    );
    let save = s.apply(&json!({ "op": "save" })).unwrap();
    assert!(save["kits"].get("input.virtualpad").is_none());
}
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `mode` | string | `"auto"` | `auto`, `shown`, `hidden` | auto: shown on a touch screen without a gamepad; shown; hidden. |
| `layout` | string | `"foot"` |  | The layout used when no layout rule selects one. |
| `layouts` | array | `[{"id": "foot", "label": {"en": "On foot", "f…` |  | The layouts of the game: on foot, vehicle, menu… Each is a full description of the controls. |
| `layoutRules` | array | `[{"layout": "vehicle", "var": "", "tag": "dri…` |  | Selects a layout by itself: the first rule that holds wins, else `layout` / setLayout(id). |
| `icons` | array | `[{"action": "enter_exit", "icon": "exit", "va…` |  | The icon of a button by context: the first rule of its action that holds; a rule without a condition is the default icon of the… |
| `iconSet` | string | `"default"` |  | The icon set in use: `default` (built-in) or one of iconSets, whose icons win over the built-in ones of the same name. |
| `iconSets` | array | `[]` |  | Icon sets carried as data. |
| `style` | object | `{"color": "", "fill": "", "active": "", "bord…` |  | The look of the pad. |
| `hideInMenus` | boolean | `true` |  | Hide the pad while a menu or the end screen is open. |
| `haptics` | boolean | `true` |  | A short vibration when a control is pressed (where the device allows it). |

## Services, events, variables

- Service `input.virtualpad`: view(lang), visible(), mode() / setMode(auto | shown | hidden), layout() / layouts() / setLayout(id), setViewport(w, h, safe), setEnvironment(touch, gamepad), pointerDown / pointerMove / pointerUp, press(control, down), stick(control, x, y), feeding(), zones(), controlOf(action), icon(name), icons()
- Events emitted:
  - `virtualpad.changed` (`visible`, `layout`) — The pad appeared, disappeared or changed layout: an interface redraws, a HUD reads zones() again.
- Events listened to: `game.phase`, `menu.screen`, `menu.action`, `menu.tab`, `menu.language`, `endscreen.shown`, `endscreen.screen`, `endscreen.action`, `ui.theme.changed`, `i18n.language`, `interaction.available`, `interaction.hidden`
- Variables:
  - `virtualpad.visible` (boolean) — Virtual gamepad visible
  - `virtualpad.layout` (string) — Virtual gamepad layout

## Hooks and modding

- Moddable settings: `mode`, `layout`, `layouts`, `layoutRules`, `icons`, `iconSet`, `iconSets`, `style`, `hideInMenus`, `haptics`

## Engines

Declared targets: `web`, `godot`, `unity`, `unreal`, `rust`. `gripforge kit api input.virtualpad` lists the exact settings and services of your version.

## Versions

Kit version 1.3.0.