logovictory.png

Using the C# Metacog Client Library for Unity3D

unity3d.png

Overview

The Metacog Platform services are exposed as a set of RESTFul API endpoints and therefore can be accessed from any programming language that support basic HTTP interaction. The data ingestion endpoint is the only exception, being exposed as an Amazon Kinesis stream and the connection to it can be done by using the different AWS SDK provided by Amazon.  

For pure HTML and Javascript projects, Metacog offers the Javascript Metacog Client Library, which interact with both the Metacog Restful API and the Amazon kinesis stream, by embedding the AWS SDK for javascript.

In addition to the Metacog Javascript Client Library (let’s call it Metacog JSCL, for the sake of brevity) there is also the Metacog C# Client Library (Metacog C#CL), designed for use within the Unity3D Game Engine.  The current version of the C#CL currently supports a subset of the functionality of the JSCL (logging events, right now), but it is under active development and you can expect to access the same functionality from both versions very soon.

This tutorial explains how to obtain, install, configure and integrate the C#CL into your Unity3D projects, in order to log events from Unity3D into the Metacog Platform, taking as base the Shooter tutorial.

About the Unity3D target runtimes

 The Unity3D C# environment is a layer that is reinterpreted into native languages when you compile the project for specific targets. From the point of view of the C#CL, we should take care of two cases: WebGL targets, compiled to a “assembling-like” form of javascript (via emscript) and the other targets, that can offer a more complete support for low level functionality, like threading.

Due to the use of this low level functionality, the AWS SDK for C# can run in all the Unity3D targets, except WebGL.  So, the Metacog C#CL uses the following architecture depending on the target to overcome this limitation:

 In the no-WebGL targets, the C#CL uses the AWS C# SDK to establish communication with the data ingestion endpoint. In the other hand, for the WebGL target, the C#CL function is reduced to communicate events to the Javascript Client Library, through a set of javascript connector functions (Located in the Metacog.Unity3D javascript module of the JSCL). No heavy processing is done inside the Unity3D build, as all the processing and communication with the backend will happen in javascript space.  

In conclusion, you need to add to your project the AWS C#SDK and the Metacog JSCL in order to cover all the compilation targets offered by Unity3D.

Adding the AWS C# SDK

To add the AWS SDK to your project, just download and install the kinesis package following the instructions from the official page: http://docs.aws.amazon.com/mobile/sdkforunity/developerguide/setup-unity.html

Adding the Metacog C# Client Library

The MC#CL can be downloaded from metacog site and imported into your project, or installed directly from the Unity3D marketplace:

Whatever the method you choose, you should get a Metacog folder in your Assets, with the following content:

Adding the Metacog Javascript CLient Library

For this step, you first need to produce a webGL build in order to generate the required index.html file: that’s the place where we are going to add the dependencies. As the build process always override the index.html, it is a good idea to keep a copy of the file so you won’t need to repeat these steps at every build:

  1. After the “UnityLoader.js” script tag, add a reference to the jquery library (it is a dependency for the JSCL).
  2. Add the dependency to the Metacog Javascript Library itself. You can reference it from the CDN (“//cdn.metacog.com/metacog-x.x.x.js”)

Metacog Authentication

In order to interact with the Metacog Platform, you need to initialize the library passing the credentials provided when the account for your organization was created into the platform.

You will need to add the Metacog Controller Component into the scene. In this case, we created an empty Object, named “MetacogController”, and we dragged into it the “Metacog” script:  

The script will expose the authentication field. In the above screenshot, you can see that “PublisherID” and “ApplicationID” were filled with demo values (you can also use this values for testing) and a WidgetID is defined, to identify in a unique way the events in the backend.

Declaring Events

You have to design what events to send to Metacog, and what information to store in them.

The C#CL expose a static method to send events:

Metacog.Send(string eventName, object data, EventType eventType) 

The “data” object should be a serializable class. For the Shooter tutorial, we create a “MyEvents.cs” file and declare as a Class each event that we want to log (we omit here the constructors as we are interested in showing the types and the data carried by each one):

namespace MyEvents

{

    [Serializable]

    public class ShootEvent {

        public Vector3 playerPos;

        public Vector3 dir;

    }

    [Serializable]

    public class TakeDamage {

        public int damage;

        public int healt;

    }

    [Serializable]

    public class Death{

        public bool isDeath;

    }

    [Serializable]

    public class EnemyNew  {

        public string name;

    }

    [Serializable]

    public class EnemyAttackEvt {

        public int damage;

    }

    [Serializable]

    public class EnemyDead{..}  

Logging Events

With the Client Library in place, the authentication parameters defined and the declaration of the events, the only remaining step is add calls to Metacog.Send in the relevant points of the source code of the project. Let’s explore a couple of examples in the Shooter tutorial:

Managers/EnemyManager.cs:

The enemyManager script is in charge of spawn the different enemy prefabs periodically.

We added both the MetacogSDK and MyEvents namespaces and called MetacogSDK.Metacog.Send passing a new EnemyNew event instance:

 

Player/PlayerShooting.cs

In this script, we want to log a ShootEvent inside the Shoot method. The constructor of the event receives the origin and the direction vector of the shoot’s ray:

Conclusion

The Instrumentation of a Unity3D project involves the configuration step of downloading, installing and configuring the library and its dependencies, and a second step of declaring events and sending them from specific points in the code. After that, you will be able to review and process the data using the other services offered by the Metacog Platform.