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"
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 file inside it. your folder hierarchy should look like this. Capture_2016_08_21_21_16_56_489 now open src\secrethq\utils\  and apply the following modifications after


  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 available here, but this will break any custom code you already made to your 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 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 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 after


  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 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 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 :, for iOS you need to backup the following files :, BBHook.h,


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)
  • Really man, appreciated your post. You really dug into deep to find the rabbit hole. But your process is so difficult that I got into fear to test it. 🙁
    Again really awesome post.

    • Ezelia

      Unfortunately, there is no simple/clean way to do it, Buildbox runtimes don’t provide any API to access those events, so the only available solution for now is using such hacks 🙂

  • Andre Spears

    When will the rest of the tutorials be ready?

  • Niaz Mohammad

    So far the best hacks available. Thanks a lot man

    • Niaz Mohammad

      Waiting for the next 🙂 Specially the “achievements”