PokiSDK: GameMaker

Integration outline

1. Set up the SDK for GameMaker. Import the Poki GameMaker extension into your project.
2. Signal loading: fire gameLoadingFinished() when your game is done loading, so conversion to play is measured correctly.
3. Gameplay events: fire gameplayStart() on the player's first input and every return to gameplay; gameplayStop() on every interruption (pause, level end, game over, menu).
4. Ads: implement commercialBreak() at natural breaks before returning to gameplay, and rewardedBreak() for opt-in rewards. Mute audio and disable input during ads.
5. Test with the Poki Inspector to verify the event flow.

Event rules and the full order-of-events reference live in the SDK overview.

Thanks to YellowAfterLife for this integration.

Set up the SDK

Follow the steps below to implement our SDK in GameMaker projects. First, download and install the PokiSDK.

GameMaker 1

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

GameMaker 2

First, add the extension to your library via the GameMaker Marketplace. Run GameMaker, open the Marketplace menu, and hit Open Marketplace. Search for poki, click Poki SDK, and activate it with the green Add to Account button. After that, download the extension: hit My Library in the marketplace, select Poki SDK, and proceed with the download.

Set up the index.html file

Next, set up your index.html file. The PokiSDK needs information about your game's loading progress, and since loading happens before the game starts, the HTML file needs a few changes to wire this up correctly.

If you don't use an index.html template yet, you can create one quickly: run your game as HTML5 in the browser, right-click and hit Inspect Source, and copy the contents into a new file named index.html. In GameMaker's resource tree, right-click Included Files and insert the file you just created.

Now open that 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 -->

Implement the game loading logic

For an accurate conversion to play metric, fire the loading events when your loading starts and finishes.

If you're 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 and paste the following into it:

/// 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 experience.
//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;

If you're using a custom loading bar

Open your custom loading bar JS extension in a code editor and 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();

}

Gameplay events

Use poki_gameplay_start() to mark when players are playing your game (for example level start and unpause). Use poki_gameplay_stop() to mark when they aren't (for example level finish, game over, pause, or 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

commercialBreak

Commercial breaks show video ads and should be triggered at natural breaks in your game. Throughout the game we recommend calling the commercial break before every poki_gameplay_start(), that is, whenever the player has shown 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 my_callback_script for other callbacks too. Based on argument1 you can decide to do different things, for example granting a reward for a rewarded break.

rewardedBreak

Rewarded breaks let a player choose to watch a rewarded video ad in exchange for a benefit in the game (more coins, for example). When using a rewarded break, 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")

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!");
        }
    }
}

Final steps

Disable sound and input during ads

Make sure audio and keyboard input are disabled during commercial breaks so 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

Congratulations, you've 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. If you get stuck, reach out via Discord or developersupport@poki.com.