SDK

Install the SDK and test locally

The Smaz Games SDK is a single JavaScript file of about 15KB with no dependencies. It connects your game to the site's saves, pause and sound controls, player accounts, invites, ads and error log. Current version: 0.2.0. See the changelog.

Install

1. Download arcade-sdk.js.
2. Put it in your build folder, next to index.html.
3. Load it before your game code.

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="./arcade-sdk.js"></script>
  </head>
  <body>
    <canvas id="game"></canvas>
    <script type="module" src="./game.js"></script>
  </body>
</html>

Include the file in your ZIP. Do not load it from another address: games cannot load scripts from other sites.

The SDK creates one global object. Its name is OpenArcade, kept from the first release; SmazGames refers to the same object.

Minimal integration

const sdk = window.OpenArcade;

async function start() {
  sdk.loadingStart();
  const env = await sdk.init();           // site settings, player and capabilities
  applySound(!env.muted);
  if (env.paused) pauseGame();

  const save = await sdk.load('progress');  // { data, revision, schemaVersion }
  const state = save.data ?? { level: 1 };
  await loadAssets(p => sdk.loadingProgress(p));
  sdk.loadingStop();

  sdk.onHost(({ paused, muted }) => {
    applySound(!muted);
    paused ? pauseGame() : resumeGame();
  });

  sdk.gameplayStart();                     // the player can now play
}

async function onLevelComplete(state) {
  sdk.gameplayStop();
  sdk.happyMoment();
  await sdk.save('progress', state, 1);
}

start();

Every method is listed in the SDK reference.

Local test mode

When your game is opened anywhere other than inside the Smaz Games player, for example from http://localhost:8080, the SDK runs in local test mode. OpenArcade.environment is 'local' and nothing is sent anywhere:

• Saves and data use your browser's localStorage (keys start with oa:standalone:).
• No player is signed in, ads return unavailable, and invites return a link to the current page.
• Error reports are written to the console instead of being sent. Analytics events are not sent; they appear in the console in debug mode.

Add these query parameters to the page address to test other paths:

Serve the build folder with any static web server, for example npx serve build or python3 -m http.server. Opening index.html from the file system usually fails, because browsers block WebAssembly and module scripts from file:// pages.

Note: Your local server does not apply the sandbox rules. A game that uses cookies, pop-ups, alert() or files from other sites will work locally and fail on Smaz Games. Test the uploaded build in the private preview before you submit.

Test on Smaz Games

• The SDK test game runs in the real player frame. It exercises saves, guest import, pause, sound, rewarded ads, the player token, invites, events and error reports.
• Each uploaded version has a Private preview on your dashboard. It uses the exact build, the real sandbox and the real SDK host, with saves kept separate from live progress. Error reports from previews appear in your error log.

Debug mode

OpenArcade.setDebug(true), init({ debug: true }) or ?smazDebug=1 turns on console logging of every request (→), response (←) and host message. The setting is remembered in this browser until you call setDebug(false). Debug mode changes nothing else.

Unity

Copy arcade-sdk.js into your WebGL template folder and add <script src="arcade-sdk.js"></script> to the template's index.html. Then add a .jslib file under Assets/Plugins/WebGL/:

mergeInto(LibraryManager.library, {
  SmazInit: function () {
    OpenArcade.init().then(function () { SendMessage('Smaz', 'OnSmazReady', ''); });
  },
  SmazGameplayStart: function () { OpenArcade.gameplayStart(); },
  SmazGameplayStop: function () { OpenArcade.gameplayStop(); },
  SmazLoad: function () {
    OpenArcade.data.getItem('save').then(function (value) {
      SendMessage('Smaz', 'OnLoaded', value || '');
    });
  },
  SmazSave: function (json) {
    OpenArcade.data.setItem('save', UTF8ToString(json)).then(
      function () { SendMessage('Smaz', 'OnSaved', ''); },
      function (e) { SendMessage('Smaz', 'OnSaveFailed', e.message); });
  }
});

using System.Runtime.InteropServices;
using UnityEngine;

public class Smaz : MonoBehaviour {
  [DllImport("__Internal")] static extern void SmazInit();
  [DllImport("__Internal")] static extern void SmazGameplayStart();
  [DllImport("__Internal")] static extern void SmazLoad();
  [DllImport("__Internal")] static extern void SmazSave(string json);

  void Start() {
#if UNITY_WEBGL && !UNITY_EDITOR
    SmazInit();
#endif
  }
  void OnSmazReady() { SmazLoad(); }
  void OnLoaded(string json) { /* restore state, then */ SmazGameplayStart(); }
  void OnSaved() { }
  void OnSaveFailed(string message) { Debug.LogWarning(message); }
}

Put the Smaz component on a GameObject named Smaz so SendMessage can find it.

Godot

Copy arcade-sdk.js next to the exported index.html and add <script src="arcade-sdk.js"></script> to Head Include in the Web export preset. In Godot 4:

extends Node

var _sdk
var _on_loaded = JavaScriptBridge.create_callback(_loaded)

func _ready():
    if OS.has_feature("web"):
        _sdk = JavaScriptBridge.get_interface("OpenArcade")
        _sdk.data.getItem("save").then(_on_loaded)

func _loaded(args):
    var text = args[0]
    # restore state from text (null when there is no save)
    _sdk.gameplayStart()

func save_game(text: String):
    if _sdk:
        _sdk.data.setItem("save", text)

Keep a reference to every callback you create, as above, or Godot frees it before the promise resolves.

Other engines

Any engine that can call JavaScript can use the SDK: Construct 3 (scripting or the Browser object), GameMaker (extensions with JavaScript functions), Defold (html5.run or a native extension), GDevelop (JavaScript code events). Call the methods on window.OpenArcade.