jpEventQueue : Use it in your Native Project

Introduction

jpEventQueue is required by several of my plugins and most of the time, you only need to reference jpEventQueue in your ShiVa project and your are done.
However, you can use it with your own plugins or native code, to send events from your xCode or Android project to the ShiVa project.
This tutorial will learn you how to use jpEventQueue in your native projects and get rid of all of the hard stuff of handling events yourself.

Why using jpEventQueue ?

You should use jpEventQueue for 3 reasons :

• Because it is free : jpEventQueue is a free plugin, everyone can get it and use it in their projects
• Because you save time : With only one line of code, you will be able to send events directly from Objective-C or Java to the ShiVa project, without having to pass things throw several files, c++ code or so on.
• Because it is thread safe : In a native project, many things run on a background thread. Events that are not sent from the main thread may crash the application, so if you do it yourself you have to declare that your code has to run in the main thread each time you want to send an event. With jpEventQueue, you can directly call the functions it provides in a background thread, and it will automatically handle the thread problematics for you. There's no risk to forget a main thread declaration and get random crashes of your games.

1. Native project setup

Before you can use jpEventQueue in your native project, ensure the jpEventQueue library is referenced in that project.
If you are creating a new xCode or Android project from the Authoring Tool, verify that jpEventQueue is referenced in your ShiVa project before exporting the .stk file for the desired target. This way, the jpEventQueue library will automatically be referenced in the newly created native project.

In case the native project was already created, please refer to the following tutorial to learn how to add the plugin to your project :

Referencing a new Plugin in an Existing Native Project (iOS / Mac / Android)

iOS
Additionally for iOS only, you must download the Additional Files provided with jpEventQueue. It contains several header files (.h) you will use to be able to call functions that are inside the jpEventQueue static library. Refence them in your xCode project by drag and droping their parent folder in the Project Navigator of xCode and choose "Copy items if needed".

2. Include jpEventQueue

Import jpEventQueue from the file where you want to use it

iOS	Android
#import "jpEventQueue.h"	import com.jpierron.jpeventqueue.jpEventQueue;

3. jpEventQueue API

Sending an event

iOS	Android
[jpEventQueue push:@"MyAIModel" andEvent:@"onMyHandler"];	jpEventQueue.push("MyAIModel", onMyHandler");

Sending an event to any AIModel of the current user implementing the event handler

iOS	Android
[jpEventQueue push:@"onMyHandler"];	jpEventQueue.push("onMyHandler");

Sending events with parameters

You can add parameters by adding up to 10 arguments to the previous functions :

iOS
[jpEventQueue push:@"onMyHandler" p0:@"First param value" p1:"Second param value"]; [jpEventQueue push:@"MyAIModel" andEvent:@"onMyHandler" p0:@"First param value" p1:"Second param value"];

Android
jpEventQueue.push("onMyHandler", new jpAIVariableWrapper("First param value"), new jpAIVariableWrapper("Second param value")); jpEventQueue.push("MyAIModel", onMyHandler", new jpAIVariableWrapper("First param value"), new jpAIVariableWrapper("Second param value"));

3. Parameters type

In the above examples, you've seen how to send string parameters, but jpEventQueue handles several other types (string, boolean, number and nil value)

From an iOS project

Expected in ShiVa	Objective-C class	Examples	Note
nil	nil	- nil
string	NSString	@"Message from Objective-C" - [NSString stringWithCString:"Message from Objective-C" encoding:NSUTF8StringEncoding]
number	NSNumber	@5 - [NSNumber numberWithInt:5] - [NSNumber numberWithFloat:5.0f]
boolean	jpBoolWrapper	[jpBoolWrapper boolWrapperWithBool:YES] - [jpBoolWrapper boolWrapperWithBool:NO]	Add the following statement at the beginning of the file : #import "jpBooleanWrapper.h"

From an Android project

Expected in ShiVa	Java class	Examples
nil	null	- null
string	jpAIVariableWrapper ( String )	- new jpAIVariableWrapper("Message from Java")
number	jpAIVariableWrapper ( float )	- new jpAIVariableWrapper(5) - new jpAIVariableWrapper(5.0f)
boolean	jpAIVariableWrapper ( boolean )	- new jpAIVariableWrapper(true) - new jpAIVariableWrapper(false)