Skip to content

gamemaker-banner

PokiSDK - GameMaker

Thanks to YellowAfterLife 

1. Initialize the SDK

Please follow the steps below to implement our SDK in GameMaker projects. First, you must download and install the PokiSDK.

GameMaker 1

In order to download the Poki SDK extension from the GameMaker Marketplace: Run GameMaker, right-click Extensions and select Import Extension in the resource tree. Then select the downloaded PokiSDK.GMEZ.

GameMaker 2

First, add the extension to your library via the GameMaker Marketplace. Run GameMaker, check the menu for Marketplace and hit Open Marketplace. Search for poki and click on the Poki SDK. You can now activate it by pressing the green Add to Account button.


After that, you need to download the extension. Hit My Library in the marketplace and select Poki SDK. Then you can proceed with the download.


2. Set up the index.html file

Now we need to set up our index.html file. The PokiSDK requires you to send information about the loading progress of your game. Since the loading experience happens before the actual game starts, we need to make some changes to the html file to make sure everything is set up correctly.

In GameMaker Studio 1, this is in Global Game Settings > HTML5 > General

If you don’t use an index.html template yet, we can help you create it quickly. Run your game as HTML5 in the browser and hit Inspect Source after right-clicking. Copy the contents into a new file named index.html. In GameMaker’s resource tree, right-click Included Files and insert the file you’ve just created.

Now all you need to do is open this file in a text editor and replace the following line: 

<script>window.onload = GameMaker_Init;</script>

with the following code: 

<!-- Poki start -->
<script src="//game-cdn.poki.com/scripts/v2/poki-sdk.js"></script>
<script>(function() {
    function fin(ok) {
        window.PokiSDK_OK = ok;
        GameMaker_Init();
    }
    window.addEventListener("load", function(_) {
        window.PokiSDK_loadState = 0;
        if (window.PokiSDK) {
            PokiSDK.init().then(function() {
            fin(true);
        }).catch(function() {
            fin(false);
        });
        } else {
            window.PokiSDK = null;
            fin(false);
        }
    });
    })();
</script>
<!-- Poki end -->


3. Implement the game loading logic

In order to provide an accurate conversion to play metric for your game, please fire the following events when your loading has started and finished:

I’m not using a custom loading bar

In the GameMaker resource tree, pick Options > HTML5 > General > Loading bar extension, and change it to poki_loadbar.

Create a new script called gmcallback_poki_loadbar, paste the following in there: 

/// gmcallback_poki_loadbar(context, current, total, width, height, img_width, img_height)
var r;
var pc = argument1; // progress current
var pt = argument2; // progress total
var cw = argument3; // canvas width
var ch = argument4; // canvas height
var iw = argument5; // image width
var ih = argument6; // image height

//All these arguments can be used to customize the full loading exprience.
//This example is very basic and only uses a few arguments

switch (argument0) {
    case "image_rect": // ([left, top, width, height] in pixels)
        r[0] = (current_time div 500) mod 4 * (iw div 4);
        r[1] = 0;
        r[2] = 0;
        r[3] = 0;
        return r;
    case "background_color": return "#79FEE7";
    case "bar_background_color": return "#79FEE7";
    case "bar_foreground_color": return "#009CFF";
    case "bar_border_color": return "#002B50";
    case "bar_width": return round(cw * 0.6); // (px)
    case "bar_height": return 20; // (px)
    case "bar_border_width": return 2; // (px)
    case "bar_offset": return 0; // (px from image)
}
return undefined;

Coloring the Loading Bar

Tweak the colors/parameters to your liking (see the linked blog post for reference)

I’m using a custom loading bar

Open your custom loading bar JS extension in a code editor, insert the following at the start of the loading bar function:

// current, total are your function arguments
if (window.PokiSDK) {
    if (window.PokiSDK_loadState == 0) {
        window.PokiSDK_loadState = 1;
    PokiSDK.gameLoadingProgress({ percentageDone: current/total });

    if (current >= total && window.PokiSDK_loadState != 2) {
        window.PokiSDK_loadState = 2;
        PokiSDK.gameLoadingFinished();

}


4. Implement the gameplay events

Use the  🎮 gameplayStart()  event to describe when users are playing your game (e.g. level start and unpause).

Use the  ☠ gameplayStop()  event to describe when users aren’t playing your game (e.g. level finish, game over, pause, quit to menu).

// first level loads, player clicks anywhere
poki_gameplay_start();
// player is playing
// player loses round
poki_gameplay_stop();
// game over screen pops up


5. Implement commercialBreak

Commercial breaks are used to display video ads and should be triggered on natural breaks in your game. Throughout the rest of your game, we recommend you implement the  🎞 commercialBreak()  before every  🎮 gameplayStart() , i.e. whenever the user has shown an intent to continue playing.

// gameplay stops (don't forget to fire gameplayStop)
poki_commercial_break(my_callback_script, "CommercialBreak")

Now create a script called my_callback_script with the following code:

function my_callback_script(argument0, argument1) {
    if (argument1 == "CommercialBreak") {
        show_message("Commercial Break done!");
    }
}

You can reuse the my_callback_script for other callbacks as well. Based on argument1 you can decide to do different things. For example for a rewarded break you can decide to give the user a reward.

Important information about commercialBreaks

Not every single  🎞 commercialBreak()  will trigger an ad. Poki’s system will determine when a user is ready for another ad, so feel free to signal as many commercial break opportunities as possible.


6. Implement rewardedBreak

Rewarded breaks allow for a user to choose to watch a rewarded video ad in exchange for a certain benefit in the game (e.g. more coins, etc.). When using  🎬 rewardedBreak() , please make it clear to the player beforehand that they’re about to watch an ad.

// gameplay stops (don't forget to fire gameplayStop)
poki_rewarded_break(my_callback_script, "RewardedBreak")

and then create a script called my_callback_script with the following code:

function my_callback_script(argument0, argument1) {    
    if (argument1 == "RewardedBreak") {
        if(argument0){
            show_message("User should get a reward!");
        } else {
            show_message("User cancelled or closed the ad, so no reward!");
        }
    }
}

About the rewardedBreak timer

 🎬 rewardedBreak()  affects the timing of  🎞 commercialBreak()  - When a user interacts with a rewarded break, our system’s ad timer is reset to ensure the user does not immediately see another ad.


Final Steps

Disable sound and input during ads

Make sure that audio and keyboard input are disabled during commercialBreaks, so that the game doesn’t interfere with the ad:

// fire gameplayStop
// mute the audio
audio_master_gain(0);
// then trigger the commercialBreak
poki_commercial_break(callback_script, "CommercialBreak")
Then place this in the callback_script:

if (argument1 == "CommercialBreak") {
    // now the commercialBreak is done
    show_message("Commercial Break done!");
    // we unmute the audio
    audio_master_gain(1);
}


Upload and test your game in Poki for Developers

Congrats, you’ve successfully implemented the PokiSDK! Now upload your game to the Poki Inspector and test it there. When you’re happy with the implementation, send us a review request and we’ll play the game. Feel free to contact us via Discord or developersupport@poki.com if you’re stuck..