Android Plugin Development with Java and C++

Easier plugin development for Android

Starting with ShiVa 1.9.2 and the Authoring Tool 1.4, we have greatly improved Android plugin development. It is now possible to include JAR files in plugins and also in the “Additional Files” tab of the UAT. We added a Java bridge to make plugins communicate much more easily with Java and the Activities through JNI. In a nutshell, you can now create self-contained plugins (C/C++ and Java code) for Android with ShiVa.

Plugin Creation in ShiVa

Your new plugin workflow starts inside ShiVa. Create a new Plugin (Data Explorer > Plugins).

For this tutorial, we are going to create an example plugin called ToastLite. Our plugin will only contain one function: ToastLite.show ( sText ), which simply shows a Java label.

We will call that function in our game when pressing a HUD button.

Building the Bridge with Visual Studio

Open the Windows Plugin by double-clicking on the plugin in ShiVa. Go to the Settings gear in the “Windows” line and select “Open Project”. The Visual Studio Solution will open.

In the Plugin.h file, add this:

virtual void SetJavaVM ( void* _pJavaVM );
void *pJavaVM;

In the Plugin.cpp file, add that:

void ToastLite::SetJavaVM ( void* _pJavaVM )
{
	pJavaVM = _pJavaVM ;
}

In your $api.cpp file (ex: ToastLite.cpp), add:

#if defined(__ANDROID__)
	#include <jni.h>

	static JNIEnv *ToastLite_GetJNIEnv ( )
	{
		JNIEnv *pJNIEnv ;

		if ( ToastLite::GetInstance ( )->pJavaVM
		&& ( ((JavaVM*)(ToastLite::GetInstance ( )->pJavaVM))->GetEnv (
		(void**) &pJNIEnv, JNI_VERSION_1_4 )
		>= 0 ) )
		{
			return pJNIEnv ;
		}
		return NULL ;
	}
#endif

In the same file, in your Lua-to-C Callback int Callback_ToastLite_show ( int _iInCount, const S3DX::AIVariable *_pIn, S3DX::AIVariable *_pOut ),
call your Java static functions package: com.stonetrip.toastlite, class: ToastLite, function: ToastLite_Show (String) by adding the following code below:

JNIEnv *pJNIEnv = ToastLite_GetJNIEnv ( ) ;
jclass pJNIClass = pJNIEnv->FindClass ( "com/stonetrip/toastlite/LibToastLite" ) ;
jmethodID pJNIMethodID = pJNIEnv->GetStaticMethodID ( pJNIClass,
"ToastLite_Show", "(Ljava/lang/String;)V" ) ;

jstring _sText = pJNIEnv->NewStringUTF ( sText.GetStringValue ( ) ) ;
pJNIEnv->CallStaticVoidMethod ( pJNIClass, pJNIMethodID, _sText ) ;

Now compile your plugin. You can do this inside ShiVa directly:

Java Plugin Programming in Eclipse

Your workflow continues with Eclipse. Here we will create all the Java code used in our plugin, and export is as a self-contained .jar file.

Create a new Android project for your java classes.

Set your project as library. Right click on the Project > Properties > Android, and check “Is Library”. The project will now be generated as a .jar file instead of an .apk.

In case you need to access the Activity or the View of the applicaion, add S3DXAndroidTools.jar to your project. This .jar file can be found in Plugins\$yourplugin\Sources\S3DX, alternatively in the UAT (Windows: Data/Windows/Android/Build/S3DX; Mac: Contents/Resources/Data/Mac/Android/Build/S3DX). Note that the file is only included in plugins created with ShiVa 1.9.2 beta4 or greater.

S3DXAndroidTools.jar has to be placed in the /libs folder of the Eclipse project and then added to the Project: Right click on the Project > Properties > Java Build Path > Libraries > Add JARs.

Create a package for your classes and create your classes. Our example package is called com.stonetrip.toastlite and contains the file libToastLite.java.

Create static methods in your class. Those methods will be called from the base plugin source files. In our example, we have created public static void ToastLite_Show (String sText).

package com.stonetrip.toastlite;

import android.app.Activity;
import android.widget.Toast;

import com.stonetrip.android.tools.*;

public class LibToastLite
{
    public static void ToastLite_Show (final String sText)
    {
        final Activity oThis = S3DXAndroidTools.getMainActivity();
        try {
        	oThis.runOnUiThread(new Runnable ( )
			{
			public void run ( )
				{
				Toast.makeText(oThis, sText, Toast.LENGTH_SHORT).show();
				}
			});
        	}
        catch ( Exception e ) { }
    }
}

The .jar file is automatically generated in the /bin folder of your project. If the file is missing, that’s because you had build errors along the way.

Copy the .jar file to the ShiVa Plugin Android content folder. In our case, that would be /Plugins/com.stonetrip.toastlite/Contents/Android.

If your java class depends on other .jar files, copy those .jar files in the same place (Contents/Android). This will be the case if you are making plugins for a 3rd party SDK, like Flurry for instance (FlurryAgent.jar).

ShiVa Export

You can build your Android Plugin solution from within ShiVa. Double-click on your plugin, then go to the Settings gear in the Android line and select “Recompile” or “Compile”. This will generate the required .a library.

If you are building on a Mac, execute the project makefile:

cd "%PLUGIN_FOLDER%/Make/Android
make -f "ToastLite.makefile"

If everything went well, both the Windows/C++ and the Android/a plugin should light up green:

All that is left for you to do now is the export from ShiVa. Do not forget to reference your new plugins in the Game Editor!

The exported STK will contain both .a and .jar files. Our Authoring Tool will compile them together, the user does not need to worry about adding native C++ or Java Files in the UAT.

Build your .apk using the ShiVa Authoring Tools v1.4.0.beta9 or greater.