Accessing the Android Compass through Unity 3D.

OK, let’s go ahead and get this out of the way. This post is not for beginners or the faint of heart. There is no way to access Android’s Magnetic Field Sensor (aka the compass) directly from Unity, so in order to do that we’re going to have to write a custom plugin. This is not an easy task, and I honestly don’t know how well I can explain it – so… stick with me and hopefully we’ll get through this together. (Note: At the time of this writing I’m using Unity 3.4 so if you’re a traveler from the distant future, I don’t know how much of this will still be valid)

Quick Overview of custom plug-ins:

Writing a custom plugin is very poorly documented, and anyone who does it pretty much has to figure it all out by themselves. For Android, here’s the process:

1. Write a custom Java jar file.
2. Write a C(++) library using JNI to access the jar file and compile it into a .so file using Android NDK
3. Import the DLL (.so file) into C# script inside unity and access all the magic.

Now, I’m not that great of a C developer, so I opted to do the following instead:

1. Write a custom Java jar file.
2. Use the AndroidJNI helper function embedded in Unity to access the jar file.

The latter method is the one we’re going to use today.

Step 1: Setting up your environment

Here is a list of things that you should already have installed on your computer:

– Java
– Android SDK

You should also have your version of Java’s bin directory in your path – that way you can call different java commands from anywhere.

After you’ve created a new Unity Project, you’ll need to create the following folders:

Plugins\Android\src\com\yourcompany\yourgamename

* The namespace here is incredibly important. It doesn’t matter what you call com.yourcompany.yourgamename, it just matters that we use it everywhere in this game and plugin. So with that in mind, in Unity go to File->Build Settings -> Player Settings and put your namespace in the Bundle Identifier field. Last note – Case totally matters.

Now that we’ve got everything set up it’s time for…

Step 2: Writing our Java plugin

In the Plugins\Android\src folder create a new file called CompassActivity.java. Open this with your favorite text editor.

Copy and paste the Java code below but know that you’re going to have to change the package to the namespace we created in step 1:

package com.yourcompany.yourgamename;

import com.unity3d.player.UnityPlayerActivity;

import android.content.Context;
import android.hardware.Sensor;
import android.hardware.SensorEvent;
import android.hardware.SensorEventListener;
import android.hardware.SensorManager;
import android.os.Bundle;
import android.util.Config;
import android.util.Log;
import android.app.Activity;

public class CompassActivity extends UnityPlayerActivity {
private static final String TAG = "Compass";

private SensorManager mSensorManager;
private Sensor mSensor;

static public float xmag;
static public float ymag;
static public float zmag;

private final SensorEventListener mListener = new SensorEventListener() {
public void onSensorChanged(SensorEvent event) {
if (Config.DEBUG) Log.d(TAG,
"sensorChanged (" + event.values[0] + ", " + event.values[1] + ", " + event.values[2] + ")");

xmag = event.values[0];
ymag = event.values[1];
zmag = event.values[2];
}

public void onAccuracyChanged(Sensor sensor, int accuracy) {
}
};

@Override
protected void onCreate(Bundle icicle) {
super.onCreate(icicle);
mSensorManager = (SensorManager)getSystemService(Context.SENSOR_SERVICE);
mSensor = mSensorManager.getDefaultSensor(Sensor.TYPE_ORIENTATION);
}

@Override
protected void onResume()
{
if (Config.DEBUG) Log.d(TAG, "onResume");
super.onResume();

mSensorManager.registerListener(mListener, mSensor,
SensorManager.SENSOR_DELAY_GAME);
}

@Override
protected void onStop()
{
if (Config.DEBUG) Log.d(TAG, "onStop");
mSensorManager.unregisterListener(mListener);
super.onStop();
}

public static float getX() {
return xmag;
}

public static float getY() {
return ymag;
}

public static float getZ() {
return zmag;
}
}

Once you’ve changed the package namespace and saved the file, open a command prompt and cd to the src directory. We’re going to run the following java commands to compile, sign, and jar our plugin: (note: You may need to alter the classpath and bootclasspath to match your system)

1.> javac CompassActivity.java -classpath C:\Program Files (x86)\Unity\Editor\Data\PlaybackEngines\androidplayer\bin\classes.jar -bootclasspath C:\android-sdk-windows\platforms\android-8\android.jar -d .

2.> javap -s com.yourcompany.yourgamename.CompassActivity

3.> jar cvfM ../Compass.jar com/

Once you’ve finished those three steps you should now have a file called Compass.jar in your Plugins\Android\ folder.

Step 3: Setting up our AndroidManifest.xml

The AndroidManifest.xml is very important. When your Unity App launches on the Android device, this file will tell it to load our .jar file instead of the UnityPlayer.jar file. Our jar file takes over because it extends the UnityPlayer Activity (which loads the UnityPlayer Activity). You’ll want to create the file AndroidManifest.xml in our \Plugins\Android folder. (Note: Don’t forget to change your package here as well)

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.yourcompany.yourgamename"
      android:versionCode="1"
      android:versionName="1.0">
    <uses-sdk android:minSdkVersion="8" />

	<application android:icon="@drawable/icon" android:label="@string/app_name">
        <activity android:name=".CompassActivity"
                  android:label="@string/app_name">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

Step 4: Accessing the Plugin from Unity
At this point we could build our application and push it to our phone and everything would work correctly, but we haven’t pulled any information out of it. If you look at the Java code I’ve written three methods called GetX, GetY, and GetZ. We’re going to call those methods from Unity and get the output (which in turn will give us the X, Y, and Z values from the Magnetic Sensor).  For this example we’re going to output the values to the GUI. First, create a new C# file (it doesn’t matter what you call it). Here’s what we need to put in it: (don’t forget to change the namespace)

using UnityEngine;
using System.Collections;
using System;

public class CompassJNI : MonoBehaviour {
	static float 	xValue;
	static float	yValue;
	static float	zValue;

	// Use this for initialization
	void Start () {
		AndroidJNI.AttachCurrentThread();
	}

	void Update() {
		using (AndroidJavaClass cls_UnityPlayer = new AndroidJavaClass("com.unity3d.player.UnityPlayer")) {

			using (AndroidJavaObject obj_Activity = cls_UnityPlayer.GetStatic("currentActivity")) {

				AndroidJavaClass cls_CompassActivity = new AndroidJavaClass("com.yourcompany.yourgamename.CompassActivity");

				cls_CompassActivity.CallStatic("Init", obj_Activity);

				xValue = cls_CompassActivity.CallStatic("getX");
				yValue = cls_CompassActivity.CallStatic("getY");
				zValue = cls_CompassActivity.CallStatic("getZ");

			}
		}

		Debug.Log("Compass values are " + xValue.ToString() + "," + yValue.ToString() + "," + zValue.ToString());
	}

	void OnGUI() {
		GUI.Label(new Rect(Screen.width / 2 -200, Screen.height / 2, 400,100), "xmag = " + xValue.ToString() + " ymag = " + yValue.ToString() + " zmag = " + zValue.ToString());
	}
}

Attach this script to your camera and build your application. You should see the 3 Values change as you move your Android Device around.  And there you go – we’re now accessing the compass.

Hopefully these steps will give you a better understanding of how Unity custom plugins work. There’s a lot of information in here and plenty of places for things to screw up, so if you have any issues leave a comment and I’ll do my best to help.

If this tutorial helped you out, why don’t you go buy one of my video games =)