Implement Android Toast in Godot 4

[llama-nl]

Describe the project you are working on

The project involves enhancing Godot 4's support for Android-specific features by integrating Android Toast notifications. Android Toast is a lightweight and visually subtle notification system that displays brief messages to the user without blocking the interface or requiring additional input. This proposal is aimed at developers creating Android games or apps with Godot who need quick, non-intrusive feedback or information delivery mechanisms.

Describe the problem or limitation you are having in your project

Currently, Godot lacks a built-in way to display Android-native Toast messages. Developers either need to implement this functionality manually through custom Java code or forego it entirely, relying on workarounds such as in-game UI labels, which:
• Are more obtrusive,
• Require additional design work to match Android's native style,
• Do not integrate seamlessly with the Android ecosystem.
Integrating Toast functionality into Godot allows developers to:
• Provide native Android user feedback (e.g., error messages, status updates) without creating custom UI.
• Save time by not having to write external Java code.
• Maintain a consistent experience with Android standards.

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

The proposal involves exposing a simple interface for displaying Toast notifications in Godot using Godot's Java Native Interface (JNI) bridge for Android. This functionality will be added as a core feature for Android exports in Godot.

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

1. JNI Bridge Code: The Android Java layer will include a static method to display Toast messages. This code will be part of the Android-specific platform code in Godot's engine source.

// In Godot's Android Java layer
public class GodotToast {
    public static void showToast(final String message, final int duration) {
        Activity activity = getActivity(); // Obtain current activity
        if (activity != null) {
            activity.runOnUiThread(() -> {
                Toast.makeText(activity, message, duration).show();
            });
        }
    }
}

2. Godot C++ Binding: The Godot C++ platform code will call the above Java method via JNI.

#include <jni.h>

void AndroidToast_show(const String &message, int duration) {
    JNIEnv *env = get_jni_env();
    if (!env) return;

    jclass godotToastClass = env->FindClass("org/godotengine/godot/GodotToast");
    jmethodID showToastMethod = env->GetStaticMethodID(godotToastClass, "showToast", "(Ljava/lang/String;I)V");

    jstring jMessage = env->NewStringUTF(message.utf8().get_data());
    env->CallStaticVoidMethod(godotToastClass, showToastMethod, jMessage, duration);
    env->DeleteLocalRef(jMessage);
    env->DeleteLocalRef(godotToastClass);
}

3. Script-Level API: A script API will be exposed for GDScript, allowing developers to trigger Toast messages from within their scripts.

class_name AndroidToast

static func show(message: String, duration: int = 0) -> void:
    if OS.get_name() == "Android":
        JavaClassWrapper.call_static("org/godotengine/godot/GodotToast", "showToast", message, duration)

4. Usage in Godot: Developers can call AndroidToast.show("Hello, world!", 0) in their GDScript to display a Toast message on Android.

Mock-Up: The implementation would integrate seamlessly with Godot's existing platform-specific scripting capabilities. A developer might create a simple UI button in the Godot editor that triggers the following script:

func _on_button_pressed():
    AndroidToast.show("Button clicked!", 0)

This results in a native Android Toast message saying "Button clicked!" appearing on the device.

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

This enhancement cannot be achieved directly in GDScript without JNI or external plugins. Developers would need to:

1. Write custom Java code for each project.
2. Rebuild the Android export templates to include their code.
   While possible, this is a time-consuming and error-prone process for something as simple as a Toast notification. A core implementation ensures ease of use and maintainability.

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

This feature is inherently tied to Android's native platform and relies on JNI calls, which are not easily handled through GDScript or a standalone asset. Including it as a core feature:

• Ensures seamless integration with Godot’s existing Android export pipeline.
• Reduces boilerplate for Android developers.
• Ensures future updates to Android and JNI are handled at the engine level without requiring external asset updates.

[syntaxerror247]

I also recently needed toast notifications in my app and considered implementing them as a core feature. However, I decided against it because it would be limited to Android . Besides, toast notifications likely wouldn’t be used frequently enough to justify adding them to the core.

This functionality can be easily replicated using Godot's GUI nodes, such as a panel combined with a timer.

If you really want Android native toast messages, then Plugin would be the best option. There is already a plugin for this in Assets Library.