From J2Play

Jump to: navigation, search

PHP Documentation

PHP Games How-to Add

Adding J2Play

Perform the following 4 steps to enable the J2Play API's explained in detailed below:

1. Download J2Play PHP toolkit
2. Include Core File
3. Init J2Play PHP GDK
4. Setting up Heart Beat

1. Download J2Play PHP toolkit

J2Play PHP toolkit Image:J2play-php-toolkit.zip

2. Include core file

Add the following include declaration on the top of the php file.

// change the relative path according to your directory
require_once("../j2play-php/J2PlayCore.php);

3. Init J2play php GDK

Add session_start() at top of your game pages before html header to enable php session. And then, call j2play_init() to initialize the j2play-php library.

session_start();
j2play_init();

j2play_init() will automatically parse the user information from the URL parameters and initialize library using these information.

4. Heart beat

Call j2play_heart_beat() in interval of 1 min to keep the heart beat.

j2play_heart_beat();

You can use sajax (or other ajax library) and following javascript making heart beat to be ajax call instead of refresh you page.

<script type="text/javascript">
  resetHeartBeatTimer();
  
  function resetHeartBeatTimer()
  {
    clearTimeout(heartBeatTimerId);
    heartBeatTimerId=setTimeout(onHeartBeatLoop,60000); // call HeartBeat in 1 min
  }
  
  function onHeartBeatLoop()
  {
    x_j2play_heart_beat(); // javascript ajax call wrapper from sajax library
    heartBeatTimerId=setTimeout(onHeartBeatLoop,60000); // call HeartBeat in 1 min
  }
</script>

When creating a game in which calling the heartbeat through javascript is not an option, then the heartbeat should be called once per page load, to signal that the user is still playing.

Save/Restore game data

If your game has some state data need to store, you can use following API. Be careful, all game data is saved relate to a specific challenge, and single player game is considered as a self challenge, So if you save single player game twice, the later one will overwrite the first one.

J2PlayGameStorage::saveGameData()

Save game data, data type must be string, you are responsible for serializing all game data to a char stream.

J2PlayGameStorage::loadGameData()

Load game data, You are responsible for unserialize.

J2PlayGameStorage::deleteGameData()

Delete game data You should not delete the game data when game end except the action of challenge is expired or declined. Game data will be store in challenge system for a while in case player gonna to browser back to old game result later. When challenge system gonna to delete game data for storage space, it will using expire action to do that.

User information

You can access user information through J2PlayController.

Get controller object

You can use J2PlayController::getInstance() to get the unique instance of J2PlayController

$controller=J2PlayController::getInstance();

J2PlayController::getUsername()

Get username, the username used by specific site or network.

J2PlayController::getPassword()

Get password.

J2PlayController::getNickname()

Get nickname, which is the name shown on screen

J2PlayController::getUserID()

Get user identification, which is the unique name used to identify user. It include the username and network information.

J2PlayController::getNetworkID()

Get network identification string, which is used to identify different web community sites.

J2PlayController::getRefererLink()

Get the originating site of the player.

Leaderboards

Leaderboards is list which record the best score of game. For using leaderboard feature, you have to report the score to J2play game environment.

Two different kind of score

There are two different kind of scores which J2play-php library support. One is accumulative score, other is high record. No matter what king of score type it is, the score is array of values which defined by developer. Leaderborder will sort according to score value in sequence. Because system store all score in one interface, you cannot use both two kind of scores in one game

Accumulative

Player can get level, experience, money or other bonus from game. The amount of bonus is accumulative. So you will get bigger and bigger number with time passed. We call this kind of score "Accumulative". You can use J2PlayScore class to handle this kind of score

J2PlayScore object

The J2PlayScore is class specific for accumulative score. You can get/set/adjust player's score by it. You can get the score object for different player by

$score=j2play_get_score($userID);

This function is simple wrapper for

J2PlayController::getInstance()->getScore($userID);

But we recommend the first code for compatibility. And then, you can use following API to get/set/update the score status of player.

J2PlayScore::isScoreSet()

This method is the judgment for whether the player have score record or not

J2PlayScore::getValues()

Get the saved score value array

J2PlayScore::setValues()

Set the saved score value array, it will overwrite the old value

J2PlayScore::updateValues()

Update the saved score value array, it will increase or decrease the scores according the delta values you give

High Record

Player can get score, time record or other kind of record in game play. We call this kind of score as "High record", you can report this kind of record to leaderboard, and the best scores will be sorted and shown.

J2PlayGameStorage::reportHighRecord()

You can use this method to report the high record of current game

Badges

define a badge

Badge is defined in platform server. It consists of 1)badgeID, 2)badgeProperties

badgeID: number; // define type of badge
badgeProperties: ca.j2x.flash.util.Map; // define the arguments of badge

Every property in badgeProperties is a pair of id=>value

id: Number; // identification of badge argument
value: String; // the value of specific badge argument

J2PlayGameStorage::badgeEarn()

Send a platform event to platform server, notifying that player got a badge.

Credits

Loyalty credit is a point system, user keep gaining this points from game and spend them on game with some high-end feature.

J2PlayGameStorage::getLoyaltyPoint()

Get the number of loyalty point specific player has

J2PlayGameStorage::adjustLoyaltyPoint()

Increase or decrease loyalty point with description

Challenges

Player can challenge other players through challenge system. And challenge system will send challenge information through J2play GDK. You can get the challenge information through J2PlayChallenge class.

J2PlayChallenge

Get challenge object

The J2PlayChallenge is the interface class for challenge. You can get the instance by

$chalenge=j2play_get_challenge();

This function is simple wrapper for

J2PlayController::getInstance()->getChallenge()

But we recommend the first code for compatibility. And then, you can using following API to get all information about this challenge and update it.

J2PlayController::isChallenge()

Judgement of challenge state, you can know through this function whether this game is a challenge game or just a single player game. If this game is challenge, you can get the challenge object through j2play_get_challenge(), otherwise that function returns null.

J2PlayChallenge::updateGamePlaying()

Update player status in challenge to 'playing' at game start.

J2PlayChallenge::updateDecline()

Update the challenge information when challenge action is 'decline'

J2PlayChallenge::updateNextTurn()

At end of player's turn, update challenge status and notify challenge system to let next player start his turn.

J2PlayChallenge::getPlayerNumber()

Get the player number in this challenge

J2PlayChallenge::getMyIndex()

Get the index of current player in the players array of challenge

J2PlayChallenge::findPlayer()

Get the index of current player in the players array of challenge

J2PlayChallenge::getUserID()

Get the username, which identify the player in challenge system

J2PlayChallenge::getUsername()

Get the username in it's network.

J2PlayChallenge::getNickname()

Get the nickname, the player's screen name, which can be shown on screen

J2PlayChallenge::getGameStatus()

Get the status of current challenge game

J2PlayChallenge::getPlayerStatus()

Get the status of player

J2PlayChallenge::getPlayerPendingStatus()

Get the pending status of player

J2PlayChallenge::getPlayerResult()

Get game result of specific player.

J2PlayChallenge::setPlayerResult()

Set the game result of the challenge. You should set result before game finish. Game will be finished if every player call updateNextTure() with finish = true.

J2PlayChallenge::getDisplayMessage()

Get the information message string sent to this player.

J2PlayChallenge::setDisplayMessage()

Set the information message string sent to this player, which will be shown on challenge system as notification to the player. You should set it to show the game result information before game finish.

J2PlayChallenge::setDisplayMessages()

Set the information message strings for all players in a string array.

J2PlayChallenge::isOpen()

In the case of a rolling/quick challenge, if the challengee has yet to be determined, then the challenge is considered 'open', and J2PlayChallenge::isOpen() will return true.

Challenge action

Add handle of challenge action at start of game, right after you call j2play_init(). Usually, if the challenge is declined or expired, you should clear all game data you saved.

if (j2play_is_challenge())
{
  $action=J2PlayController::getInstance()->getAction();
  $challenge=j2play_get_challenge();
  switch($action)
  {
     case J2PLAY_CHALLENGE_ACTION_DECLINE:
       
       // delete all game data saved
       
       $challenge->updateDecline();
       break;
     case J2PLAY_CHALLENGE_ACTION_EXPIRE:
       
       // ..  delete all game data saved, maybe same as decline
       
       break;
     case J2PLAY_CHALLENGE_ACTION_ACCEPT:
       
       //  .. do your initialization for challenge receiver
       
       $challenge->updateGamePlaying();
       break;
     case J2PLAY_CHALLENGE_ACTION_CHALLENGE
       
       // .. do your initialization for challenger
       
       $challenge->updateGamePlaying();
       break;
     default:
       // error
  }
}

update at the beginning of turn

If you don't have any game data stored in system, you don't need to handle the action, but you always need to call updateGamePlaying() at beginning of turn.

update at the end of turn

At the end of player's turn, you should tell challenge system to launch next player to start his turn. It can be down be call the updateNextTurn() and set the current next player. If current player finishd all his move and never has any other chance to move, you should set the 'finish' flag. As all players in finished state, the game finish.

rolling challenges / quick challenges

If from your game, you would like to initiate a challenge with the first available opponent who is also looking for an open challenge, you want to use the J2PLAY_CHALLENGE_ACTION_FINDCHALLENGE action. This will check to see if there are any other players looking for rolling challenges, and if so answer them. If a rolling challenge does not yet exist, then one will be created. In either case, the player looking for a rolling challenge commences their round after a challenge is found or created. If a wager is specified for the challenge, then only challengers also interested in making the same wager will respond.

quick challenge creation

If you need to create a challenge between players outside the j2play framework (which will automatically present an interface to allow a user to challenge their friends) then you want to use the J2PLAY_CHALLENGE_ACTION_CREATECHALLENGE action, along with parameters specifying the username and nickname of the player to be challenged. These parameters are J2PLAY_PARAMETER_CHALLENGE_USERNAME and J2PLAY_PARAMETER_CHALLENGE_NICKNAME.