Get Battery Percentage (OS)

[ausername97531]

There was once a function like this - OS.get_power_percent_left()
I dont know why it was removed but I would like to request the following functions:
OS.get_battery_percent()
OS.get_battery_status()
With status "-1" = stationary PC, "0" = not connected, "1" = charging.
I have a Windows implementation that looks like this:

---

#include <iostream>
#include "Windows.h"

// range 0 - 100, value 255 is *unknown*
int get_battery_percent(){
    SYSTEM_POWER_STATUS container;
    GetSystemPowerStatus(&container);
    int batteryPercent = container.BatteryLifePercent;
    if(batteryPercent<101){return batteryPercent;}
    return 100;
}

// 1 = High—the battery capacity is at more than 66 percent
// 2 = Low—the battery capacity is at less than 33 percent
// 4 = Critical—the battery capacity is at less than five percent
// 8 = Charging
// 128 = No System BATTERY
// 255 = *unknown* status
// FUNCTION TO RETURN 1 IF CHARGING, 0 IF NOT, OR -1 IF STATIONARY PC.
int get_battery_status(){
    SYSTEM_POWER_STATUS container;
    GetSystemPowerStatus(&container);
    int batteryFlag = container.BatteryFlag;
    if(batteryFlag == 8){return 1;}
    if(batteryFlag == 128 || batteryFlag == 255){return -1;}
    return 0;
}

int main() {
    std::cout << "Status = " << get_battery_status() << std::endl;
    std::cout << "Percentage = " << get_battery_percent() << std::endl;

    return 0;
}

[Calinou]

This was attempted a while ago, but was removed because the implementation was never completed.

That said, the Web platform has also removed its battery status API (as it could be used to fingerprint users, leading to privacy issues). This means an implementation in Godot wouldn't be able to work in web exports.

[ausername97531]

How about returning standard values for all platforms that havent or cant be implemented, and if a platform isnt supported yet then a developer for that platform if they want that function could add an implementation?

get_battery_status() - could return "-2" if a platform isnt implemented and when checking the documentation the user would find out what it means.

[Mickeon]

Getting the power status and percentage sounds pretty useful, especially for mobile games, which may want to account for it without user intervention. Never had a chance to use the methods in 3.x, but I always thought their existence was neat.

[timkrief]

This would be useful for mobile to display it to users for an always on display kind of app for instance.

[Calinou]

Note that recent Android versions have a way to show the status bar as a persistent overlay (with foreground color only), even though the game remains fullscreen. This allows the player to see the time, battery status and notification icons while playing a game with the full screen real estate available.

I don't know if iOS has an equivalent of this.

cc @syntaxerror247

[Zireael07]

How recent is "recent"?

[syntaxerror247]

This feature is actually not recent; it has been achievable since quite a long time ago (I guess since Android 7). However, starting with Android 15, it now enforced by default.

Godot 4.5 fully supports this feature on all android versions. Just enable https://docs.godotengine.org/en/stable/classes/class_editorexportplatformandroid.html#class-editorexportplatformandroid-property-screen-edge-to-edge

[timkrief]

Interesting feature! However, that wouldn't work for an always on display, it could cause burn in. That also wouldn't work to prompt user to use a low battery mode either.

[syntaxerror247]

Having these methods seems useful to me, and I can confirm that it can be implemented on Android too.

[bruvzg]

iOS - https://developer.apple.com/documentation/uikit/uidevice/batterystate-swift.property?language=objc
macOS - https://developer.apple.com/documentation/iokit/1523867-iopsgetpowersourcedescription
Windows - https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-getsystempowerstatus
Web - https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API (limited availabilty)

So it should be possible to implement on all platforms.

[NovaDC]

Linux - https://sourceforge.net/p/acpiclient/code/ci/master/tree/ (really just parsing the files in the "/sys/class/power_supply/POWER_SUPPLY_NAME_HERE" directory - though it still requires that battery daemon to be installed at all, perhaps that to can be reflected in get_battery_status())
Android - https://developer.android.com/reference/android/os/BatteryManager