Skip to content

Commit 0e2a08f

Browse files
committed
Add documentation for JavaClassWrapper and AndroidRuntime plugin
1 parent 0a2feff commit 0e2a08f

File tree

2 files changed

+104
-0
lines changed

2 files changed

+104
-0
lines changed

tutorials/platform/android/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,4 @@ Android
1010
android_library
1111
android_plugin
1212
android_in_app_purchases
13+
javaclasswrapper_and_androidruntimeplugin
Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
.. _doc_javaclasswrapper_and_androidruntimeplugin:
2+
3+
Integrating with Android APIs
4+
=============================
5+
6+
The Android platform has numerous APIs as well as a rich ecosystem of third-party libraries with wide and diverse functionality:
7+
8+
- Push notifications
9+
- Analytics
10+
- Login
11+
- Ads
12+
- etc...
13+
14+
These don't make sense in Godot core itself so Godot has long provided an :ref:`Android plugin system <doc_android_plugin>`.
15+
The :ref:`Android plugin system <doc_android_plugin>` enables developers to create Godot Android plugins using Java or Kotlin code, with provides an interface to access and use Android APIs or third-party libraries in Godot projects from GDScript, C# or GDExtension.
16+
17+
.. code-block:: kotlin
18+
19+
class MyAndroidSingleton(godot: Godot?) : GodotPlugin(godot) {
20+
@UsedByGodot
21+
fun doSomething(value: String) {
22+
// ...
23+
}
24+
}
25+
26+
27+
Writing an Android plugin however requires knowledge of Java or Kotlin code, which most Godot developers do not have.
28+
As such there are many Android APIs and third-party libraries that don't have a Godot plugin that developers can interface with.
29+
In fact, this is one of the main reasons that developers cite for not being able to switch to Godot from other game engines.
30+
31+
To address this, we've introduced a couple of tools in **Godot 4.4** to simplify the process for developers to access Android APIs and third-party libraries.
32+
33+
JavaClassWrapper (Godot singleton)
34+
----------------------------------
35+
36+
``JavaClassWrapper`` is a Godot singleton which allows for creating instances of Java / Kotlin classes and calling methods on them using only GDScript, C# or GDExtension.
37+
38+
.. code-block:: gdscript
39+
40+
var LocalDateTime = JavaClassWrapper.wrap("java.time.LocalDateTime")
41+
var DateTimeFormatter = JavaClassWrapper.wrap("java.time.format.DateTimeFormatter")
42+
43+
var datetime = LocalDateTime.now()
44+
var formatter = DateTimeFormatter.ofPattern("dd-MM-yyyy HH:mm:ss")
45+
46+
print(datetime.format(formatter))
47+
48+
In the code snippet above, ``JavaClassWrapper`` is used from GDScript to access the Java ``LocalDateTime`` and ``DateTimeFormatter`` classes.
49+
Through ``JavaClassWrapper``, we can call the Java classes methods directly from GDScript as if they were GDScript methods.
50+
51+
AndroidRuntime plugin
52+
---------------------
53+
54+
``JavaClassWrapper`` is great, but to do many things on Android, you need access to various Android lifecycle / runtime objects.
55+
``AndroidRuntime`` plugin is a built-in Godot Android plugin that allows you to do this.
56+
57+
Combining ``JavaClassWrapper`` and ``AndroidRuntime`` plugin allows developers to access and use Android APIs without switching away from GDScript, or using any tools aside from Godot itself.
58+
This is **huge** for the adoption of Godot for Android development:
59+
60+
- If you need to do something simple, or only use a small part of a third-party library, you don't have to make a plugin
61+
- It allows developers to quickly integrate Android functionality
62+
- It allows developers to create Godot addons using only GDScript and ``JavaClassWrapper`` (no Java or Kotlin needed)
63+
64+
.. note::
65+
66+
Godot will automatically include ``.jar`` or ``.aar`` files it find in the project ``addons`` directory when exporting.
67+
So to use a third-party library, you can just drop its ``.jar`` or ``.aar`` file in the ``addons`` directory, and call its method directly from GDScript using ``JavaClassWrapper``.
68+
69+
Example: Show an Android toast
70+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71+
72+
.. code-block:: gdscript
73+
74+
# Retrieve the AndroidRuntime singleton
75+
var android_runtime = Engine.get_singleton("AndroidRuntime")
76+
if android_runtime:
77+
# Retrieve the Android Activity instance
78+
var activity = android_runtime.getActivity()
79+
80+
# Create a Godot Callable to wrap the toast display logic.
81+
var toastCallable = func ():
82+
# Use JavaClassWrapper to retrieve the android.widget.Toast class, then make and show a toast using the class APIs
83+
var ToastClass = JavaClassWrapper.wrap("android.widget.Toast")
84+
ToastClass.makeText(activity, "This is a test", ToastClass.LENGTH_LONG).show()
85+
86+
# Wrap the Callable in a Java Runnable and run it on the Android UI thread to show the toast
87+
activity.runOnUiThread(android_runtime.createRunnableFromGodotCallable(toastCallable))
88+
89+
Example: Vibrate the device
90+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
91+
92+
.. code-block:: gdscript
93+
94+
# Retrieve the AndroidRuntime singleton
95+
var android_runtime = Engine.get_singleton("AndroidRuntime")
96+
if android_runtime:
97+
# Retrieve the Android Vibrator system service and check if the device supports it
98+
var vibrator_service = android_runtime.getApplicationContext().getSystemService("vibrator")
99+
if vibrator_service and vibrator_service.hasVibrator():
100+
# Configure and run a VibrationEffect
101+
var VibrationEffect = JavaClassWrapper.wrap("android.os.VibrationEffect")
102+
var effect = VibrationEffect.createOneShot(500, VibrationEffect.DEFAULT_AMPLITUDE)
103+
vibrator_service.vibrate(effect)

0 commit comments

Comments
 (0)