Skip to content

Advanced usage

Jump to bottom Edit New page
Miroslav Chmelka edited this page Feb 28, 2023 · 67 revisions

GAMEE framework provides also other functionalities that might be helpful. Using them is optional.

gamee.gameInit

In order to use some of the described functions, you must declare them first during gameInit in the gameCapabilities array. Allowed values are "saveState", "replay", "ghostMode","socialData","playerData","logEvents","rewardedAds", "missions" and "platformExtraLife".

Parameters

  • controller -string- Controller type
  • controllerOptions -json- Controller options
  • gameCapabilities -string[]- Required game capabilities
  • callback -callback- Ready callback
  • silentMode -boolean- (Optional) Required game capabilities

Passing capabilities example

var capabilities = ["saveState", "replay", "ghostMode", "socialData","playerData",
"logEvents","rewardedAds","missions","platformExtraLife"];
var silentMode = true; // default value when parameter is not passed as false

gamee.gameInit("FullScreen", {}, capabilities, function(error, data) {
    if(error !== null)
        throw error;

    var myController = data.controller;
    var sound = data.sound;

    // based on game capabilities, you will obtain additional data
    var saveState = data.saveState;  // contains data you previously saved
    var replayData = data.replayData;
    var socialData = data.socialData;
    var platform = data.platform; // contains the platform the player is using
                                  // it could be "android","ios","web","mobile_web"
    var country = data.country; // player country in ISO 3166-1 alpha-2
    var locale = data.locale; // contains the country and the language of the player
                              // for example "en_US","es_MX","pt_BZ"...
    var gameContext = data.gameContext; // contains the context of the game it could
                                        // be "normal" or "battle" or "mission"
    var initData = data.initData; // json received if a player access the game 
                                  // with some init data

    var environment = data.environment; // development/production

    var matchmakingUserID = data.matchmakingUserID; // UserId of user from notification click through
    var gameContextId = data.gameContextId;

    var missionData = {
        id: "",  //game mission or special app mission 
        value: "", 
        difficulty: "easy",
        difficultyData: "", //json
    };

... // your code that should make game ready
}, silentMode);

gamee.updateScore

updateScore can be used to send ghost score. Then score of the ghost is updated instead of score of the player. This signature can be used only in game with active ghost mode.

Passing ghost score

// signature score, ghostSign, callback
gamee.updateScore(10, true, function(error) {
    if(error !== null)
        throw error;
});

gamee.updateMissionProgress

Updates the mission progress on the platform level, making it visible for the player after the game over. Should be called with every mission progress change.

  • progress -int- % progress of a specific mission, number in <0, 100> range

*Requires declared capability "missions" during gamee.Init

Simplest example

gamee.updateMissionProgress(10); // set mission progress to 10%

Another usage

gamee.updateMissionProgress(10, function(error) {
    if(error !== null)
        throw error;
});

gamee.gameSave

  • saveState -string- Data you want to store from the game.

*Requires declared capability "saveState" during gamee.Init

Simplest usage

gamee.gameSave("Data you want to save");

Complete usage

If opt_share param is true, platform will trigger screen asking player to share the progress with his actual score. The game must be paused during this process. The game continues when it receives a resume message.

var dataToSave = {
    life: 95,
    score: 150
};

// Signature data, opt_share (default false), opt_callback
gamee.gameSave(JSON.stringify(dataToSave), true, function(error) {
    if(error !== null)
        throw error;
});

gamee.requestBattleData

Will get data about a battle when the context is "battle". If the context is different, returns empty data.

Parameters

  • callback -callback- callback

Complete usage

gamee.requestBattleData(function (error, data) {

    if (!error && data) {
        console.log(data)
        /* {"battle":{"id":"35a0a5e9-868e-43e9-9cff-6415ec9c13fa","name":"Destroyer test","type":"energy-limited","endTime":"2019-06-05T08:02:13+00:00","usersCount":1,"extraPool":null,"author":{"id":1234,"firstname":"Name","lastname":"Lastname","nickname":"coolnickname","photo":"https://url.com","level":12,"levelTitle":"pro","globalScore":4428,"verified":true,"membership":"basic","iFollow":false,"followersCount":103,"pairedGroup":null}}}; */
    }
});

gamee.requestSocial

Will get more social data about Gamee players. If the player is not logged in then the parameter data.socialData.player will be empty.

*Requires declared capability "socialData" during gamee.Init

Complete usage

gamee.requestSocial(function (error, data) {
    if (data && data.socialData && data.socialData.friends) {
        data.socialData.friends.forEach(function (friend) {
            console.log(friend);
            // {name:"playerName", firstName: "John", lastName: "Wick", highScore:1000, avatar:url, userID: 123456, coins:1000}
    }

    if (data && data.socialData && data.socialData.player) {
        console.log(data.socialData.player)
        // {name:"playerName", firstName: "John", lastName: "Wick", highScore:1000, avatar:url, userID: 123456, coins:1000}
    }
});

gamee.requestPlayerData

Will get information about the current logged in player. If optional parameter playerID is used, it will ger information about any specific player.

Parameters

  • callback -callback- callback
  • playerId -number- (Optional) Requested player id data

*Requires declared capability "playerData" during gamee.Init

Complete usage

var playerId = 1234; // Optional
gamee.requestPlayerData(function (error, data) {

    if (data && data.player) {
        console.log(data.player)
        // {name:"playerName", firstName: "John", lastName: "Wick", highScore:1000, avatar:url, userID: 123456, coins:1000}
    }
}, playerId);

gamee.requestPlayerReplay

Will get information for Replay Mode.

*Requires declared capability "replay" during gamee.Init

Parameters

  • userID -number- The unique ID of the player you want to get the Replay Data.

Complete usage

gamee.requestPlayerReplay(usedID,function (error, data) {

    if (data) {
        var replayData = data.replayData.data
        var variant = data.replayData.variant
        // developer should use this data according to the game
    }
});

gamee.requestPlayerSaveState

Will get save state of specific user.

Parameters

  • userID -number- The unique ID of the player you want to get the Save State.

*Requires declared capability "saveState" during gamee.Init

Complete usage

gamee.requestPlayerSaveState(usedID,function (error, data) {

    if (data && data.saveState) {
        var saveState = data.saveState
        // developer should use this data according to the game
    }
});

gamee.logEvent

Events that the developer can store so he would be able to see statistics of the game.

Parameters

  • eventName -string- The name of the event, shouldn´t be longer than 24 characters.
  • eventValue -string- The value of the event, shouldn´t be longer than 160 characters.

*Requires declared capability "logEvents" during gamee.Init

Complete usage

gamee.logEvent("eventName","eventValue");

gamee.gameStart

An event that marks the actual start of gameplay.

  • games with lobby screen call gameStart once the player starts the actual gameplay
  • other games call gameStart upon receiving the start event

(!!!) Mandatory to implement for games using GameeJS 2.5 and later.

Complete usage

gamee.gameStart();

gamee.loadRewardedVideo

Function used to load rewarded ads inside the game. Using this function, you will know if there is any ad available and ready to be shown.

*Requires declared capability "rewardedAds" during gamee.Init

Complete usage

var isVideoReady = false
gamee.loadRewardedVideo(function(error,data){
    if(data && data.videoLoaded){
        // video loaded and is ready to be shown using gamee.showRewardedVideo
        isVideoReady = true
    }else{
        // video not available
        isVideoReady = false
    }
})

gamee.showRewardedVideo

Function used to show rewarded ads inside the games, you should load the video first using gamee.loadRewardedVideo.

*Requires declared capability "rewardedAds" during gamee.Init

Complete Usage

if(isVideoReady){
    gamee.showRewardedVideo(function(error,data){
	if(data && data.videoPlayed){
            //video played => user should get reward
	}else{
	   //video not played / skipped => user should not get reward
	}
    })
}

gamee.gameOver

In addition, gameOver can send data that could be used later to run the game in the replay mode or in the ghost mode. Same data are used for both modes, to reflex that it is possible to pass also saveState. You can also add saveState to the function, so you may stop using gamee.gameSave() and just make one call to the server

Parameters

  • replayData -json- (Optional) Data to use on replay mode or ghost mode.
  • callback -callback- (Optional) Callback.
  • saveState -string- (Optional) Data to use in the game.
  • hideOverlay -boolean- (Optional) Not show gamee overlay.

Usage with replayData

var replayData = {
    // your data here, can be stringified json for example
    data: JSON.stringify({"life":50,"level":10}),
    // optional property, useful for games with random levels, should contain seed
    variant: "0.58366025891155"
};

gamee.gameOver(replayData, function(error) {
    if(error !== null)
        throw error;
});

Usage with saveState

var saveState = JSON.stringify({"score":1000})

gamee.gameOver(null, null, saveState)

Usage with hideOverlay

gamee.gameOver(null, null, false, true)

gamee.emitter

Some events like "start" comes with params. In addition, this object emits also other events: "ghostHide" and "ghostShow".

(!!!) For games using GameeJS 2.5 and later it is mandatory to implement event "useExtraLife".

Complete usage

// Will be emitted when user will start game or restart it.
gamee.emitter.addEventListener("start", function(event) {
    ... // your code to start
    event.detail.opt_replay // if true, game must start as replay
    event.detail.opt_ghostMode // if true, game must start in ghostMode
                               // (unless replay is true)
    event.detail.opt_resetState // if true, game should toss its current saveState
    event.detail.replayData // contains the replayData of the player´s next friend
                            // to beat.

    event.detail.callback();
});

gamee.emitter.addEventListener("useExtraLife", function(event) {
    ... // your code to respawn player from the death position 
        // or the last checkpoint.

    event.detail.callback();
});


gamee.emitter.addEventListener("ghostHide", function(event) {
    ... // your code to hide anything related to ghost in game.

    event.detail.callback();
});

gamee.emitter.addEventListener("ghostShow", function(event) {
    ... // your code to show anything related to ghost in game again.

    event.detail.callback();
});
Add a custom footer
  1. Overview
  2. GAMEE Principles
  3. Guides
  4. Framework API
Clone this wiki locally