> For the complete documentation index, see [llms.txt](https://docs.webtonative.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.webtonative.com/javascript-apis/game-mode-functions.md).

# Game Mode Functions

Functions to read the device's game mode and tell the system what state your web game is in, so it can tune performance and battery for it.

> You'll need to import the javascript file in your website before starting from this [link](https://docs.webtonative.com/javascript-apis/getting-started).

> **Platform support:** Game Mode works on both Android and iOS. On iOS, the system's Game Mode is turned on from WebToNative's dashboard and needs no code. The functions on this page are Android only. On iOS they reject with `"<function> is only available on Android"`.

> **Enable it first:** Game Mode must be turned on for your app in the WebToNative dashboard. If it is off, the functions still reply, but the mode is always `"unsupported"`.

***

## Get Game Mode

Reads the game mode the user has picked for your app in the system settings.

{% tabs %}
{% tab title="Plain Javascript" %}

```javascript
window.WTN.GameMode.getGameMode()
  .then(function (response) {
    if (response.mode === "unsupported") {
      // Game Mode is off in the dashboard, or the device doesn't support it.
      return;
    }
    // Your code: e.g. lower graphics quality when response.mode is the battery mode.
  })
  .catch(function (error) {
    console.error(error); // not inside a WebToNative Android app
  });
```

{% endtab %}

{% tab title="npm" %}

```javascript
import { getGameMode } from "webtonative/GameMode";

getGameMode()
  .then((response) => {
    if (response.mode === "unsupported") {
      // Game Mode is off in the dashboard, or the device doesn't support it.
      return;
    }
    // Your code: e.g. lower graphics quality when response.mode is the battery mode.
  })
  .catch((error) => {
    console.error(error); // not inside a WebToNative Android app
  });
```

{% endtab %}
{% endtabs %}

**Response:**

| Key    | Type     | Description                                                                           |
| ------ | -------- | ------------------------------------------------------------------------------------- |
| `mode` | `String` | The current game mode. `"unsupported"` when Game Mode is turned off in the dashboard. |

**Example responses:**

```json
{ "mode": "unsupported" }
```

**Notes:**

* Android doesn't tell the app when the user changes the game mode. Call `getGameMode()` again when the page becomes visible:

```javascript
document.addEventListener("visibilitychange", function () {
  if (!document.hidden) window.WTN.GameMode.getGameMode().then(applyMode);
});
```

***

## Set Game State

Tells the system what your game is doing right now, e.g. loading a level or in gameplay the user shouldn't be interrupted in.

{% tabs %}
{% tab title="Plain Javascript" %}

```javascript
window.WTN.GameMode.setGameState({
  isLoading: false,
  mode: "gameplayUninterruptible"
})
  .then(function (response) {
    if (response.success === false) {
      // The state wasn't accepted, e.g. an invalid mode.
      return;
    }
    // Done.
  })
  .catch(function (error) {
    console.error(error); // not inside a WebToNative Android app
  });
```

{% endtab %}

{% tab title="npm" %}

```javascript
import { setGameState } from "webtonative/GameMode";

setGameState({
  isLoading: false,
  mode: "gameplayUninterruptible"
})
  .then((response) => {
    if (response.success === false) {
      // The state wasn't accepted, e.g. an invalid mode.
      return;
    }
    // Done.
  })
  .catch((error) => {
    console.error(error); // not inside a WebToNative Android app
  });
```

{% endtab %}
{% endtabs %}

**Parameters:**

| Key         | Type      | Required | Description                                                        |
| ----------- | --------- | -------- | ------------------------------------------------------------------ |
| `isLoading` | `Boolean` | No       | `true` while the game is loading. Default `false`.                 |
| `mode`      | `String`  | Yes      | What the game is doing. See [Game state modes](#game-state-modes). |

### Game state modes

| Mode                      | Meaning                                                                |
| ------------------------- | ---------------------------------------------------------------------- |
| `none`                    | No specific state.                                                     |
| `gameplayInterruptible`   | In gameplay that can be interrupted, e.g. a turn-based or paused game. |
| `gameplayUninterruptible` | In gameplay that shouldn't be interrupted, e.g. a live match.          |
| `content`                 | Showing non-gameplay content, e.g. menus or a cutscene.                |

**Response:**

| Key       | Type      | Description                                                     |
| --------- | --------- | --------------------------------------------------------------- |
| `success` | `Boolean` | `false` when the state wasn't accepted, e.g. an invalid `mode`. |

***

## How the Functions Reply

Every `WTN.GameMode` function returns a Promise. A call ends in one of two ways:

| Outcome  | Where it lands | What it means                                                                                              |
| -------- | -------------- | ---------------------------------------------------------------------------------------------------------- |
| Rejected | `.catch`       | The call couldn't be made (not inside a WebToNative Android app, or the app is too old). Nothing was sent. |
| Resolved | `.then`        | The app replied. Check the response: `mode` can be `"unsupported"`, and `success` can be `false`.          |

### Errors

A promise rejects only in these cases. The rejection value is a plain string.

| When                                                                         | Message                                                                                                        | Fix                                                                         |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Any function is called outside a WebToNative app (e.g. in a desktop browser) | `"This function will work in Native App Powered By WebToNative"`                                               | Only call these functions inside the app.                                   |
| Any function is called in the iOS app                                        | `"<function> is only available on Android"`, e.g. `"getGameMode is only available on Android"`                 | Only call these functions on Android. Check `WTN.isAndroidApp` first.       |
| The Android app was built before this function was added                     | `"<function> is not supported in this app version"`, e.g. `"getGameMode is not supported in this app version"` | Rebuild the app from the WebToNative dashboard and update it on the device. |

***

## Notes

* If Game Mode is turned off in the dashboard, the functions still reply, and `getGameMode()` returns `mode: "unsupported"`.
