Press enter to see results or esc to cancel.

Hook layer for Android and iOS [Buildbox like a boss]

In this article we will add a hook layer to Buildbox Android export.
This hook layer will later give us the possibility to add custom services to Buildbox games, such as game analytics, achievements, multiple leaderboards, and even Everyplay video sharing service !

What’s a hook layer, why do we need it ?

Buildbox don’t provide any official way to hook events from code, except for custom ad networks.
The hook layer will make it possible to detect some important game events and allow us to execute custom code when they occure.

in this article we’ll add a hook layer which will detect the following events :

  • Custom button clicks.
  • play start (detected via a start button click),
  • play gameover,
  • score submit (with score value),

such events are important to detect : let’s say you want to unlock an achievement depending on the score value, for this you’ll need to know when the player loose (gameover event) and what is his score value.

Limitations :
Please note that this hook layer is a “hack”, it means that it use unofficial event detection code and could be broken by future Buildbox releases if the Buildbox development team decide to change the code behaviour.
the present code was tested with buildbox 2.1.x and 2.2.x .

 

Let’s start !

 

Creating a buildbox project

First we’ll create a buildbox project to which we’ll apply the modifications.

  1. Start buildbox and click “Create New”
    • in the project creator give a name to your project, I’ll use MyGame for this tutorial
      (MyGame will refer to buildbox project in the rest of this tutorial)
    • choose a game type from the provided templates (I’ll use ZigZag in this tutorial)
    • click “Create”
      scr1
  2. Switch to the Game Mind Map view and double click “Main Menu UI”
  3. Add an “Url button” and put it on top of the start button, resize it to fit exactly the size of start button.
    • uncheck “Block Touch Through”
    • set Url value to “#HOOK_Start”
    • set the name to “HOOK_Start”

scr2

 

Explanation :

Our hook layer will use url buttons to trigger custom actions, and to distinguish real url buttons from the hooked ones, we’ll prefix the hooked ones with “HOOK_” prefix.

Unchecking “Block Touch Through” will result in triggering both the Url button and the start button. so when the player will click on start button, he’ll actually also trigger url button.

Our hook layer will detect the url button click, and from the custom URL “#HOOK_Start” it’ll know which custom code to execute.

you can download the resulting bbdoc below

I know I could just put the bbdoc without explaining the steps to create it, but I want you to notice the custom URL buttons we created, they will be useful later
Download MyGame.bbdocbuildbox project file

 

Android Hook Layer

Make an android export to (we’ll assume that the export is located in build\mygame-android )

In your exported project open build\mygame-android\android\src folder.

Create com\ezelia\utils folder, and put BBHook.java file inside it.
your folder hierarchy should look like this.

Capture_2016_08_21_21_16_56_489

now open src\secrethq\utils\PTServicesBridge.java  and apply the following modifications

after

add

 

Modify initBridge function to :

 

modify openUrl function to :

 

Modify submitScrore function to :

 

modify isGameServiceAvialable function to :

Note : you can use an already modified version of PTServicesBridge.java available here, but this will break any custom code you already made to your PTServicesBridge.java file. if you are using the default buildbox v2.x export, you can safely use the provided version.

 

at this point the hook layer is ready, now we can add custom code to BBHook.java to handle our custom events.

 

Testing the hook

To illustrate that the hook is working we’ll show a toast message for game start and game over events.

Edit BBHook.java file

add the following imports

 

Modify onGenericEvent function to :

Note: The above code is triggered when the player click on a Url button with url value set to #HOOK_Start.

using the same logic you can create your custom hooked buttons : just create an url button with a url prefixed with #HOOK_  ; let’s say #HOOK_MyEvent, then add a conditional code inside onGenericEvent method, in our case the if syntax would be  if (event.equals(“MyEvent”)) { … }

 

Modify onGameOver function to :

 

Now build and run the game on your mobile.
when you click start you should see a toast message saying “Event:Game start ”

when you loose you should see the a toast message saying “Event:Game over”

Congratulations, your hook layer for android is ready 🙂

 

 

iOS Hook Layer

Make an iOS export to (we’ll assume that the build\mygame-ios

Open your exported project using xCode

Download the hook files and copy them inside the project.
you should have something like this

Capture_2016_08_21_21_00_12_366

 

BBHook.m and BBHook.h are the custom hook layer, iToast.m and iToast.h are helper files which let us display toast messages similar to Android.

to use iToast code you need a small configuration, otherwise you’ll get a compilation error.

click on PTPlayer in the project hierarchy then  Build Phases > Compile Sources

double click on the Compile Flags column beside iToast.m and add “-fno-objc-arc

Capture_2016_08_21_20_56_01_676

 

now edit AppController.mm

after

add

 

Edit didFinishLaunchingWithOptions method and add the following code between  mc->clean() and return YES  lines :

 

the bottom part of didFinishLaunchingWithOptions method should look like :

at this point, the hook layer is ready for iOS, we can add custom code to BBHook.mm to handle custom events

 

Testing iOS hook

Let’s add Toast messages to check that events are correctly detected, the same logic is used as in Android code.

Open BBHook.mm file

Modify onGenericEvent method to

 

Modify onGameOver method to

 

Build and run your project.

you’ll notice the toast messages when clicking starting the game and on gameover.

 

 

Note :
if you export the game to the same folder, Buildbox will overwrite the modified files.
one easy solution to avoid modifying the files each time is to keep a copy of modified files in a safe place, and replacing the original one each time you export a new project.

for android, you need to backup the following files : BBHook.java, PTServiceBridge.java

for iOS you need to backup the following files : BBHook.mm, BBHook.h, AppController.mm

 

Conclusion

In this tutorial we created a hook layer allowing us to trigger custom events and use them to run custom code.

we still didn’t add anything interesting to our project (except displaying toast messages), but this hook layer is the base for interesting addition we’ll see in next tutorials.

it’s important to have it up and running, and understand how it work, since this is the base for setting up multiple leaderboards, achievements, game analytics and everyplay video recording service.

you can do a simple exercice to check that you understand how this hook layer work : modify the buildbox game and add a hook code to display a Toast message (“Event:replay”) when the player loose and click on “Replay” button. if you do this correctly, you’re redy for next tutorials 🙂

 

 

You liked our content ? subscribe and get free resources to create your games

Indie Gamedev resources

Receive curated list of resources, specifically selected for indie game developers.
including graphics, music, tutorials, software ...etc

(one email per week max)