Engine Startup Life Cycle
GameSalad has a delegate system that will allow you to hook into certain events in the GameSalad Engine.
When GameSalad is done loading the engine, it calls the global (or window) function onEngineLoad.
window.onEngineLoad = function () {
}
At this point you have access to the global variable gse (GameSalad Engine). This isn’t an instance of the engine, but a point of access to the engine.
The next thing to happen is that you can register a callback function that is run when the engine is “Ready”.
You can do this by calling the gse.ready() method and passing a callback function. The argument to this callback function IS the actual engine instance that is running the game.
window.onEngineLoad = function () {
gse.ready(function (engine) {
// Environment specific init code goes here.
});
}
Now let’s look at this engine instance.
In default-index.html you will see a lot of code inside the ready callback. All this code does stuff that is specific to the platform (because the HTML5 engine is used in more than just websites, the code here can look different). Here are the basics of what’s usually in there.
window.onEngineLoad = function () {
gse.ready(function (engine) {
// Environment specific init code goes here.
engine.setRenderFrame('gse-player'); // The ID of the DIV that will contain where the game renders.
// Options for how the engine tries to adjust the window size and how it renders.
engine.setOptions({
'viewport-reference': 'window',
'Viewport-fit’: 'letterbox'
});
// This loads any options passed as query parameters. You can usually omit this.
engine.loadOptionsFromURL();
// This loads the game.
engine.load();
});
}
Handling Game Events with Delegates
Now, let’s look at the delegates. The GameSalad engine object has a method called engine.appendDelegate that takes a HashMap of functions. Possible functions are documented here:
https://support.gamesalad.com/support/solutions/articles/42000112581
Here is a minimal implementation that covers what do while the engine is in a “loading” state (i.e. before the game begins or between scenes).
window.onEngineLoad = function () {
gse.ready(function (engine) {
// Define delegates
// Get a reference to a div that shows a loading indicator.
var loadingElement = document.getElementById('gse-loading');
const playerDelegate = {
onLoadingBegin: function() {
console.log("Loading begin.");
engine.showOverlay(); // Signals engine to show the internal loading indicator.
loadingElement.style.visibility = 'visible'; // Make our own overlay visible.
},
onLoadingEnd: function() {
loadingElement.style.visibility = 'hidden'; // Hide our own overlay
engine.hideOverlay(); // Signals the engine show the internal loading indicator.
}
}
engine.appendDelegate(playerDelegate)
// Environment specific init code goes here.
engine.setRenderFrame('gse-player'); // The ID of the DIV that will contain where the game renders.
// Options for how the engine tries to adjust the window size and how it renders.
engine.setOptions({
'viewport-reference': 'window',
'Viewport-fit’: 'letterbox'
});
engine.loadOptionsFromURL(); // This loads any options passed as query parameters. You can usually omit this.
engine.load() // This loads the game.
});
}
To handle more functions, you add functions that match the spec in our doc to the player delegate.
Writing Values To Engine with postEvent
Finally, how to send information INTO the engine. The engine has a postEvent method, which lets you tell the engine certain things have happened. You can use two events:
'externalWriteGameAttribute'
and
'loadExternalImage'
For ‘externalWriteGameAttribute’ the postEvent arguments are as follows:
engine.postEvent('externalWriteGameAttribute', null, <attribute path>, value)
<attribute path> is a string that tells the engine what attribute to set. You can only set game level attributes and for custom attributes (attributes you create), you will need to know the internal ID of the attribute. You can find this by hovering over the name of the attribute in Creator 2.
For image replacement you will call it as follows:
engine.postEvent('loadExternalImage', null, <image name>, url);
loadExternalImage only replaces existing images in the engine. <image name> is a string with the name of the image that you see in the Creator image library. The URL is a string with the URL of the image.
Example: Ad Network Support
A common request is how to allow GameSalad to use different ad networks as part of a web arcade. We’ll use Lagged SDK as an example, because that’s one of Google Adsens’s partners.
First you’ll need to load the ad library, so we’ll need to add something like this in our sample-index.html / index.html file inside the <head> block:
<script type="text/javascript" src="https://lagged.com/api/rev-share/lagged.js"></script>
Next we’ll want to implement a delegate to actually show the interstitial or rewarded ad:
window.onEngineLoad = function() {
// This initializes the LaggedAPI with your own keys.
LaggedAPI.init('YOU_DEV_ID', 'YOUR_PUBLISHER_ID');
// We're going to ask Lagged if there are reward ads available and tell it what to do when the ads are displayed.
// When Lagged figures out if ads are available it will return ad availability and a function to show the ad.
// We'll want to store the function to show ads later.
let showRewardAds = null;
function onRewardAdAvailable(adsAvailable, showAdFunc) {
// No ads available, let's null out the function.
if (!adsAvailable) {
showRewardAds = null;
return;
}
// Set up a function to display ads
showRewardAds = function() {
// Pause the game
gse.pauseGame();
// Show ads using Lagged's ad function
showAdsFunc();
}
}
// This handles the response when the ad is complete.
function onRewardAdComplete(rewardUser) {
// Check if the user should get the reward
if (rewardUser) {
// Set the gamesalad adReward attributes
engine.postEvent('externalWriteGameAttribute', null, 'game.attributes.adReward.name', 'Reward Ad');
engine.postEvent('externalWriteGameAttribute', null, 'game.attributes.adReward.value', 10); // Adjust this to your actual reward.
}
// Check to make sure we have another ad available.
LaggedAPI.GEvents.reward(onRewardAdAvailable, onRewardAdComplete);
// Resume the game.
gse.playGame();
}
// Grab ad availability for the first time:
LaggedAPI.GEvents.reward(onRewardAdAvailable, onRewardAdComplete);
gse.ready(function(engine) {
// Define delegates
// Get a reference to a div that shows a loading indicator.
var loadingElement = document.getElementById('gse-loading');
const playerDelegate = {
onLoadingBegin: function() {
console.log("Loading begin.");
engine.showOverlay(); // Signals engine to show the internal loading indicator.
loadingElement.style.visibility = 'visible'; // Make our own overlay visible.
},
onLoadingEnd: function() {
loadingElement.style.visibility = 'hidden'; // Hide our own overlay
engine.hideOverlay(); // Signals the engine show the internal loading indicator.
},
onSceneAboutToChange: function(sceneKey, sceneName, adType)) {
if (adType === 1) {
// Display interstitial
gse.pauseGame();
LaggedAPI.APIAds.show(function() {
// Resume game when done.
gse.playGame();
});
} else if (adType === 2) {
// Display rewarded ads if available
if (showRewardAds != null) {
showRewardAds();
}
}
}
}
engine.appendDelegate(playerDelegate)
// Environment specific init code goes here.
engine.setRenderFrame('gse-player'); // The ID of the DIV that will contain where the game renders.
// Options for how the engine tries to adjust the window size and how it renders.
engine.setOptions({
'viewport-reference': 'window',
'Viewport-fit': 'letterbox'
});
engine.loadOptionsFromURL(); // This loads any options passed as query parameters. You can usually omit this.
engine.load() // This loads the game.
});
}