Introduction
Developing any game to completion certainly is no small task. If you have come this far, your next step might very well be looking for ways to monetize your creation. In case your game is fit for the mobile HTML5 market (touch controls!), licensing it is one of the most attractive options.
One of the companies looking for good quality mobile HTML5 games is Yepi.com. If you sold a license to them, part of the agreement will be the implementation of their API in your game.
Now this might pose an intimidating hurdle at first, since Construct 2 developers aren't necessarily versed in actual coding. It's the beauty of C2 that you don't need to be. But now you will be confronted with some Javascript in their API documentation. What to do?
I created a little plugin to make the implementation easier. This tutorial will guide you through the process of adding full Yepi.com API functionality to your C2 game.
Download Yepi plugin
Obviously the first step is to download the Yepi plugin and add it to your project.
Taking a look at the Yepi documentation again you will realize that there are two types of events that are needed for the API (speaking generally of "events" here, not in the C2 sense).
Namely those are Game Sending Events and Game Receiving Events.
Game Sending Events
Game Sending Events require the call of a javascript function. This may also be done by other means, for example the CallJS plugin. With this plugin you will simply have to apply four actions to support all of the Game Sending Events.
1. Game Loading Complete
Simply have an "On Start of Layout"-event in your first layout with the action "Loading complete". Done.
2. Level Complete
When a level is completed, you will likey have events to display the overall score or something else before you go to the next level. Be sure to use the action "Level Complete" there.
3. Game Over
The player ran out of lives or the game is finished? Add the action "Game Over" to your event.
4. Level end/Game Over (send score)
It is usually at the end of a level or the game when the player's score is determined. Use the action "Send Score" with your score variable.
Game Receiving Events
Game Receiving Events require to listen to requests by the API. This includes turning the audio on and off, pausing and unpausing, restarting the game and lastly resizing it. For the Game Receiving Events you will be able to use conditions.
1. Sound On
You can use the action "Set silent" of the audio object.
2. Sound Off
Same here. Use "Set silent" and set it to active.
3. Pause game
Here's it's just a matter of adding an action which pauses your game. Setting the timescale to 0 might just do it, however I recommend using rexrainbow's Pause plugin.
4. Unpause game
You might have guessed how this should look:
5. Game Restart
Simply use this condition with an action that goes back to the title or rather the level selection layout, if there happens to be one.
6. Game Resize
The most complex API feature your game needs to support is certainly the resizing on request. This means you cannot use any of the fullscreen modes, as you need full control over the canvas size at all times. Set fullscreen to off in the project properties.
The Yepi API might want to scale your game to sizes with pretty wild aspect ratios. There may be games that are designed to support almost any size, showing more or less of the level area. Endless runners for example can work this way.
But I go out on a limb here and assume that your game is much more likely to be designed for a certain aspect ratio. With that in mind, you need to find the scale that fits best into the by the API requested size.
I recommend making a new event sheet handling the resizing (and possibly other Game Receiving Events as well) which you include with any other relevant event sheet. If you didn't add the function object to your project yet, I'd also suggest to do so now, as it makes things a lot handier.
It's also not a bad idea to create two global variables for the native width and height of your game. If all of your layouts have exactly the native size, which is likely in case your game doesn't scroll, then you don't need these (use the expressions LayoutWidth and LayoutHeight instead).
Add another global variable to hold the currently desired scale.
Make a new function, call it "findScale" or some other unused function name. To create a new function add an event with an "On function"-condition of the Function object.
Two parameters will be passed to this function. The first for the requested width and a second one for the height.
Add an action setting the scale variable like the following:
Function.param(0)/natWidth
This finds the maximum scale by checking how often your native width fits into the requested width.
Now this would only be correct if your game still fit vertically into the browser window. To test for this add a sub-event with a "Compare two values"-condition of the System object.
Here you enter some math again:
scale*natHeight > Browser.ExecJS("window.innerHeight")
Pair this with the action
set global variable scale to Function.param(1)/natHeight
to base the scale on the height instead.
And to complete this add a new event with an action calling the yet undefined function "applyScale".
Now create the function called "applyScale". We need it to execute two actions. First it should set the canvas size and then change the layout scale. Both actions are again of the System object.
set canvas size to natWidth[i]scale and natHeight[/i]scale
set layout scale to scale
To have the just created functions work with the API, simply create an event with the "On resize request"-condition calling the function "findScale". The plugin provides two expressions Yepi.Width and Yepi.Height. Add those as function parameters.
Another thing you shouldn't forget is setting the scale on start of every layout. You can add the following event to your Yepi event sheet:
On start of layout -> call "applyScale"
Okay, there is still the special case of the first layout. This should by default be sized to fit the browser window, like letterbox fullscreen would. So for your first layout, create this event:
On start of layout -> call "findScale" Browser.ExecJS("window.innerWidth"),Browser.ExecJS("window.innerHeight")
Note that if the player is able to return to the first layout, this event shouldn't be executed again. You can use a global variable to check for this.
Congratulations, you just completed the hardest part of the implementation! But there is still more to learn.
The kinks
The Yepi API depends on two javascript files: mYepiAPI.js and mYepiAPI_Local.js. Both are included in the plugin folder. Unfortunately you can only define one dependency in C2 plugins, which is a little inconvienent here.
This means that you will get javascript errors when previewing your game which is making use of the Game Receiving Events. To test your creation you should export it instead and try it on your localhost.
Copy mYepiAPI_Local.js and mYepiAPI_Tester.js manually to your game folder.
To prevent you from having to edit the exported index.html file all the time, there is an adjusted one in the plugin folder. It's called index2.html so it doesn't get overwritten when you export. Also copy this file to your game folder. You might want to rename the title in the html file to the name of your game.
Now you can run your game from the url localhost/yourgame/index2.html.
The mYepiAPI_Tester.js enables API testing control and status shown above your game in the browser window. To make use of it you have to uncomment a line in index2.html.
Before you zip your game and upload it to the Yepi online API tester you need to comment out the mYepiAPI_Tester line again and also remember to use index2.html, but rename it to index.html in the archive.
And this concludes the tutorial. I hope this will help out a few folks trying to make a buck from their C2 games. Feel free to ask additional questions in the comments. Thanks for reading!