[Android] Add support for the new Game-Mode API

[pavly-gerges]

The Android team has launched a new API that's shipped with Android-12, the Game-Mode API reads the system game mode configuration to optimize the game accordingly using jMonkeyEngine APIs or submitting a call to the Android Stock Game interventions APIs, the first approach to this should be integrating a call to the Game-Mode API and adding a listener for that to be handled independently through users actions, for example, altering Lod, loading low-poly models or playing with frame-rates and disabling game filters.

A dummy example:

public interface GameMode {
      void onDisabled(GameManager gameManager);
      void onPerformanceEnabled(GameManager gameManager);
      void onBatterySaverEnabled(GameManager gameManager);
      void onStandardEnabled(GameManager gameManager);
}

...

// Later on JmeSurfaceView
GameMode gameMode;
...
// Only call this for Android 12 and higher devices
if ( Build.VERSION.SDK_INT >= Build.VERSION_CODES.S ) {
  // Get GameManager from SystemService
  GameManager gameManager = Context.getSystemService(GameManager.class);

  // Returns the selected GameMode
  int gameMode = gameManager.getGameMode();
  if (gameMode == UNSUPPORTED) {
      gameMode.onDisabled(gameManager);
  } else if (gameMode == STANDARD) {
      gameMode.onStandardEnabled(gameManager);
  } else if (gameMode == BATTERY) {
      gameMode.onBatterySaverEnabled(gameManager);
  } else if (gameMode == PERFORMANCE) {
      gameMode.onPerformanceEnabled(gameManager);
  }
} else {
      gameMode.onDisabled(gameManager);
}

[github-actions]

💰 This issue has a bounty

Resolve it to receive a reward.
For details (amount, rules, eligibility), see: https://hub.jmonkeyengine.org/t/bounty-program-trial-starts-today/49394/

If you want to start working on this, comment on this issue with your intent.
If accepted by a maintainer, the issue will be assigned to you.

Additional info

The bounty is only for the following things:

• add listener in a way that devs can bind their own logic to gamemodes as described in the issue
• add a small example to prove it works (can be just one of the jme3-examples files, with a println when the game mode changes)

No need to implement the actual battery saving/performance logic in jme, that is beyond the scope of this bounty.

Note: The pr that fixes this issue, ideally should not break compatibility with older devices. Use reflect if needed.

[hunterbastian]

I would like to work on this bounty.

I have a local implementation draft ready for Android Game Mode API support on JmeSurfaceView. It adds a game mode listener, queries Android's GameManager on renderer start and activity resume using reflection for older SDK compatibility, and includes a small Android example activity that logs the selected mode.

Local verification so far:

./gradlew :jme3-android:compileJava --no-daemon
javac compile of GameModeSurfaceViewActivity.java against the built jme3-core, jme3-android, jme3-examples, android.jar, and cached AndroidX lifecycle/annotation jars
git diff --check

I have not opened a PR yet because the Android example app still needs full Android SDK verification on my machine.

[jaime-jmebot]

Opened #2961 to resolve this issue.

What it adds:

• com.jme3.system.android.GameMode (enum mirroring the platform constants: unsupported/standard/performance/battery) and OnGameModeChanged, the listener that maps the per-mode callbacks sketched in the report.
• com.jme3.system.android.AndroidGameMode, a reflection-based bridge to android.app.GameManager that reads the current mode and registers/unregisters a game mode listener. On devices older than Android 12 (or when the platform reports no game mode) the listener is notified once with GameMode.UNSUPPORTED, so a single code path works everywhere; nothing API-31 is referenced at compile time.
• Hooks on JmeSurfaceView and on AndroidHarnessFragment (setOnGameModeChanged), registered on start/attach and unregistered on destroy.
• A small example, TestGameModeActivity in jme3-android-examples, that prints/logs the mode on every change (adb shell am start -n org.jmonkeyengine.jme3androidexamples/.TestGameModeActivity, adb logcat -s TestGameModeActivity).

No actual battery/performance behaviour is implemented in the engine, as the bounty scoped that out. Note for review: the sandbox could not provision Gradle, so validation was done by compiling jme3-core, jme3-android and the new example with javac; CI is the gate for the Gradle build and for the Android example module.