Skip to content

GameMaker

Checklist

Before we start with how, let’s quickly make clear what we expect when implementing our SDK:

  1. Implement the loading events gameLoadingStart(), gameLoadingProgress(), gameLoadingFinished().

  2. Trigger the 1st gameplayStart() upon the first user-input like a keystroke or mouseclick when the user is in the actual gameplay, so not in the menu.

  3. Trigger a gameplayStop() when the gameplay stops and is not interactive anymore.
    e.g. at a pause-screen or when the user has finished a level or is game-over.

  4. Implement the first commercialBreak() right before the first gameplayStart(). Implement at least 1 other commercialBreak() in the game.
    Ideally the commercialBreak() is always right before a gameplayStart().

  5. If applicable, implement at least 1 rewardedBreak() position in the game.

  6. Implement at least 1 happy moment in the game happyTime(), e.g. upon finishing a level or unlocking an achievement.

Common mistakes:

  • Remember to block gameplay and gameplay audio during a commercialBreak() or rewardedBreak().
    You can find instructions below

  • Fire gameplayStart()s and gameplayStop()s at appropriate moments.

  • Make sure you are using the latest version of the SDK.

Basic implementation

1. Adding the Poki SDK Extension

GameMaker 2

First add the extension to your library via the GameMaker Marketplace.

GameMaker Marketplace

  1. Open GameMaker
  2. Click in the menu on Marketplace
  3. Click Open Marketplace
  4. Search for poki
  5. Click on the Poki SDK
  6. Now press the green Add to Account button

Next we need to download it:

  1. Click in the menu on Marketplace
  2. Click My Library
  3. select the Poki SDK
  4. In the far right screen press Download

GameMaker 1

Download and install the PokiSDK:

  1. Download the Poki SDK extension from the GameMaker MarketPlace.
  2. Open Game Maker
  3. In the resource tree right-click Extensions and select Import Extension
  4. Select the downloaded PokiSDK.GMEZ.

2. Setting up the index.html template

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

  1. If you don’t use an index.html template yet
    1. Run your game as HTML5
    2. Open page source (right click Inspect Source)
    3. Copy all of the contents into a new file named index.html
    4. In GM resource tree, right-click Included Files, pick Insert Included File, pick your index.html file.
    5. In resource tree, pick Options > HTML5 > General > Advanced > included file as index.html, and point it to your file. Don’t forget to click OK! (in GMS1, this is in Global Game Settings > HTML5 > General)
  2. Right-click index.html in Included Files, pick Show in Explorer / Show in Finder
  3. Open the file with a code editor, or, failing that, a plaintext editor
  4. Find the line on the bottom that says
<script>window.onload = GameMaker_Init;</script>

and replace it with

<!-- 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);
        }
        //PokiSDK.setDebug(true); <-- Uncomment this line for debugging
    });
    })();
</script>
<!-- Poki end -->

3. Setting up the Loading Bar

I'm not using a Custom Loading Bar

  1. In GM resource tree, pick Options > HTML5 > General > Loading bar extension, change to poki_loadbar. Don’t forget to click OK!
  2. 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)
// https://yal.cc/gamemaker-html5-loading-bar-extended/
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 am using a Custom Loading Bar

  1. 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.gameLoadingStart();
    PokiSDK.gameLoadingProgress({ percentageDone: current/total });

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

}

Phew, now that's out of the way lets continue with the fun stuff!

Next steps

1. Integrating the functions

We require you to implement the following functions:

gameplayStart

The gameplayStart() event should be triggered every time when a level starts or when the user first interacts with the actual game (i.e. not in a menu, unless the game is the menu for example in a clicker game). The 1st gameplayStart() should be triggered upon the first user-input (keystroke or mouse-click) in the actual gameplay.

gameplayStop

The gameplayStop() should be triggered every time the gameplay halts, like in the case of a level finish, game-over or when going back to a menu or pausing the game, etc.

poki_gameplay_start();
poki_gameplay_stop();

Continue playing

Heads up! Don’t forget to trigger a gameplayStart after triggering a gameplayStop, i.e. after a "pause"

Commercial break

As described earlier, commercial breaks are used to display advertisements and should be triggered on natural breaks in your game. We' like to see that you implement the commercialBreak when the user has shown the intent to continue playing , i.e. on a play/restart/level-select button. We require you to implement at least 2 breaks:

  • It is mandatory to implement the first commercialBreak() in the beginning of the game right before the first gameplayStart().

  • For your other commercialBreak(s), we recommend you to always trigger a commercialBreak() right before a gameplayStart().
    If you are having trouble to identify the correct moments, your Poki contact will also help with properly identifying these moments.

Syntax:

poki_commercial_break(callback_script, custom_value)

Example usage:

poki_commercial_break(my_callback_script, "CommercialBreak")

and then 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. See

Rewarded break

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.)..

Syntax:

poki_rewarded_break(callback_script, custom_value)

Example usage:

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

Happy time

We would love to know what you believe to be the happy moments in your game. This could be the unlocking of a new car, or triggering a super combo in the game. We will use this in order to display cool animations on our portals. Please integrate at least one happy time.

poki_happy_time(<intensity>)
//<intensity> is of type float between 0.0 and 1.0 and allows us to scale the intensity of happiness. You can for instance on a small happy moment trigger a happyTime(0.1) and on an extremely happy moment trigger happyTime(1.0)

//Example:
poki_happy_time(0.5);

2. Integrate game logic

Extra logic is required between triggering a commercialBreak and finishing it. Some things to keep in mind when triggering ads:

  1. All adds need to be triggered via user interaction, e.g. a click of a button or a keyboard key press
  2. All audio must be muted during advertisements
  3. Gameplay must be paused during advertisements

This is a basic example displaying this:

//First we mute audio
audio_master_gain(0);
//Then we trigger the commercialBreak
poki_commercial_break(callback_script, "CommercialBreak")

and then 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);
}

3. Sitelocking

Sitelocking

Protecting your game from theft is very important to us.

In order to sitelock your game please include our sitelock code in the index.html of your game inside the function fin(ok){} as a seperate line. This line of code will auto-execute and bounce the page back to Poki.com whenever the window.location doesn't equal qa.poki.com,qa-files.poki.com or localhost:.

Please request this piece of code from your Poki contact. If we make it public it’d be easy for tech-savvy people to remove. :)

4. Full example

You can download a full working GMZ sample of everything described here.

QA Tool - Testing your game

Now test your SDK-implementation via our QA Tool. Make sure to send us the log of your QA-session by downloading it at the bottom of the page and sending it to developersupport@poki.com along with the build. This will not work offline or you must use a local server.

Final deliverables

Congrats! You’ve now successfully implemented the Poki SDK. Please send the following to developersupport@poki.com or to your Poki contact:

  • Final game build (Production Build, so no debug-version)
  • QA-log
  • Image assets:
    • Thumbnail (preferably 628x628 px, PNG-file)
    • Character-image (Large size, PNG-file)
    • Game-title (PNG-file)
    • Main background of the game (PNG-file)
    • 2 to 3 game-items (PNG-files)

That's it

We’ll check your QA-report and if all correct notify you that your game can go live!

Big thanks to YellowAfterlife for helping us with this extension!