Enable the web host to control low-processor mode settings

[adamscott]

Describe the project you are working on

I'm working on a project that is like CodePen, but for Godot, for educative purposes. The user will be able to follow a tutorial on a web page, then scroll down to an actual editor (that uses a Codemirror text editor and a Godot editor player) to try out the new learned concept. Then, when the exercise is done, the user will be able to scroll down to continue the course.

For now, we are targeting using that concept for our online courses, but we have a plan to broaden this tool for more uses, such as a way to quickly share Godot code or proofs-of-concept online.

Describe the problem or limitation you are having in your project

Loading 6 instances of the Godot engine editor is not a lightweight task, as to put lightly. Especially if they all run the code at 60fps non-stop, with no way to reduce the process load.

And as loading an instance can take up to 20 seconds, it's not a good idea to shut down an instance when it's not used. The user could be tempted to go back to a previous exercise in the page to better understand a principle and reload the exercise from scratch could prove to be frustrating.

There's instances where the browser can crash the tab when it's too heavy (Firefox is known to do this in our project).

There's the fact that our students may not have the latest and greatest CPUs and GPUs. A lot of them could even run the exercises on tablets or mobile.

So it's important for the web host to be able to control which instance should have the full process power. Ideally, it should be possible to suspend the activity of an instance at will.

As we intend to broaden afterwards that project from running our controlled code to running arbitrary projects from users, we will not necessarily control the contents of a project.

Also, there's the fact that we use <iframe> to integrate the "exercise player". This makes it that the player itself will not be able to know when the game would be in a viewable position. It may be in the <iframe> viewport, but the <iframe> could be not in view.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

godotengine/godot#79711 will make it possible to run Godot outside of the Javascript main thread.

Therefore this override is not needed anymore. This makes it possible to enable effectively the low-processor mode on the web platform.
https://github.com/godotengine/godot/blob/6758a7f8c07d1f4c8ec4f052ded6d26402967ebe/platform/web/os_web.h#L91-L93

So, the idea would be for the host to be able to decide when to allocate resources to a game instance, especially if numerous games are meant to be played in the same browser tab. The idea is that the host is better placed to know than the game instances themselves.

There's a feature that already exist on the desktop and on mobile that effectively handles that issue. It's the "low-processor mode".

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

It's pretty easy to implement this feature.

The trick relies on exposing OS.low_processor_usage_mode and OS.low_processor_usage_mode_sleep_usec to the web host. Then, the host could edit those values at will, depending on the host logic.

Loading

sequenceDiagram
    participant Web as Web page (host)
    participant Bindings as JS Bindings
    participant Godot

    Godot ->> Bindings: Setup callbacks

    Web ->> Bindings: Get `lowProcessorUsageMode`
    Bindings ->> Godot: Run `getLowProcessorUsageModeCallback`
    Godot ->> Bindings: Return `OS.low_processor_usage_mode`
    Bindings ->> Web: Get value

    critical The web host wants to use the low processor usage mode
        Web ->> Bindings: Set `lowProcessorUsageMode` to `true`
        Bindings ->> Godot: Run `setLowProcessorUsageModeCallback` with param 1
        Godot ->> Godot: Set `OS.low_processor_usage_mode`
        Web ->> Bindings: Set `lowProcessorUsageModeSleepUsec` to a high value
        Bindings ->> Godot: Run `setLowProcessorUsageModeSleepUsecCallback` with value as param
        Godot ->> Godot: Set `OS.low_processor_usage_mode_sleep_usec`
    end

If this enhancement will not be used often, can it be worked around with a few lines of script?

This could be worked around using JavaScriptBridge, but it's inconvenient.

Is there a reason why this should be core and not an add-on in the asset library?

As said previously, it could be an add-on, but it removes the ability for the host to edit values that affect the behaviour of the page. Without the ability for the host to install arbitrary add-ons, this makes it necessary for each game running on a web page to explicitly have that add-on installed, which may introduce issues if the add-on is not present.