Awarding coins

Coins are awarded on a per-player basis at the end of a game. See the GameControl API for more details. There are several methods that can be used to award coins. Choose the method that is most suitable to the game you are coding.

You will only to implement the calls listed below, the Whirled environment will take care of awarding the coins and notifying the players of their coin earnings.

Score based Payouts
If your game uses points of some kind, then most likely you will want to award coins based on those points. The score cannot be negative, and it must be an integer. Higher scores should be given for better work in the game, whether it is a single-person game or multiple players.

If you want to encourage players to get low scores, such as golf, elapsed time in a racing game, or number of guesses in a guessing game, then you must convert your score to a positive integer. One way to do this is to determine a hypothetical worse possible score, then subtract the player's points from that.

Both rating and a player's coin payout will be adjusted based on their score. Whirled will track every score reported by your game for its entire existence and will convert newly reported scores to a percentile value between 0 and 99 (inclusive) indicating the percentage of scores in the entire score history that are below the reported score. That percentile ranking will be used to adjust the players rating as well as to determine their individual coin payout.

Single Person Games
A game that is always a single person game should use endGameWithScore (score) call to payout coins.

_ctrl.game.endGameWithScore(score);

If you want to award coins without ending/unloading the game, for example, payout at levels. You will also need to add the following.

1. When the level is over, call endGameWithScore

2. When the player starts the next level, call playerReady to signal to the server to start tracking game play again..

/**** When the user finishes one level/game ****/ /**** call endGameWithScore, and then *********/ /**** reset the score back to zero   *********/ function myGameFinishLevel { _ctrl.game.endGameWithScore(score); score = 0; }

/****when the players starts the next level ****/ function myGameNewLevel {

_ctrl.game.playerReady; myGame.play; }

Multi-player Games
Games that are allowed to have multiple players should use endGameWithScores (playerIds, scores, payoutType). Both playerIds and scores are arrays. The payoutType will be one of the allowed integer constants. See below for options on payoutType.

Note that is not necessary for the game to end to make this call. You should simply call this API anytime you want to award points.

Here is one way this could be coded, in the method that is called when a game should end.

var playerIds :Array = []; var scores :Array = []; for each (var playerId :int in _gameCtrl.game.getOccupantIds) { var score :int = ''... look up this playerId's score....'' playerIds.push(playerId); scores.push(score); }       _gameCtrl.game.endGameWithScores(playerIds, scores, payoutType);

=Winner/Loser Games= In some multi-player games, there are no points; the only thing that matters is who won and who lost. These games should use endGameWithWinners (winnerIds, loserIds, payoutType). Both winnerIds and loserIds are arrays. The payoutType will be one of the allowed integer constants. See below for options on payoutType.

Players' ratings will be updated using the Elo algorithm: each player is rated against the average ratings of the players that they defeated or were defeated by. In a two player game this degenerates into the standard Elo algorithm.

=Payout Types= There are three ways that payouts can be determined in multi-player games. You can choose one of these options for your game, or you can add a lobby parameter and allow the player who sets up the table to select the option. See also payoutType

Performance-based
If the raw point score earned by a player in the game should be the only consideration for awarding coins, then the best choice for payout type is GameSubControl.TO_EACH_THEIR_OWN. This will award coins based on the points that each player earned compared to historical data on the server for that game, without regard to scores of other players at the table.

For example:

_gameCtrl.game.endGameWithScores(playerIds, scores, GameSubControl.TO_EACH_THEIR_OWN);

Cascading
GameSubControl.CASCADING_PAYOUT skews awards toward the winners by giving 50% of last place's payout to first place, 25% to the next inner pair of opponents (third to second in a four player game, for example), and so on. This will allow the winners of a game to earn more coins than the maximum possible using GameSubControl.TO_EACH_THEIR_OWN. ''Notes: Experiments need to be done to determine whether a loser with score zero will increase a winner's payout. This option may not be implemented server-side yet.''

For example:

_gameCtrl.game.endGameWithScores(playerIds, scores, GameSubControl.CASCADING_PAYOUT);

Winners Take All
GameSubControl.WINNERS_TAKE_ALL splits the total coins available to award to all players in the game among those identified as winners at the end of the game. This option probably makes the most sense when paired with endGameWithWinners. When used with endGameWithScores, the highest scoring player or players will be considered the winner(s). Note: This option may not be implemented server-side yet.

For example, either of these lines: _gameCtrl.game.endGameWithWinners(winnerIds, loserIds, GameSubControl.WINNERS_TAKE_ALL); _gameCtrl.game.endGameWithScores(playerIds, scores, GameSubControl.WINNERS_TAKE_ALL);

Lobby parameter for Payout type
The following steps will allow players to choose the payout type when they play the game.

Add custom parameter
In-game, edit the game, then click the Configuration tab. Add this line to the Custom Parameters box:



Read the parameter
At some point in your game, read the parameter and use it to set a payoutType variable. Here is one way that can be done:

var config :Object = _gameCtrl.game.getConfig; var matchType : String = config["Award split"]; var payoutType : int; if (matchType == "Performance") { payoutType = GameSubControl.TO_EACH_THEIR_OWN; } else if (matchType == "Cascading") { payoutType = GameSubControl.CASCADING_PAYOUT; } else if (matchType == "Winner take all") { payoutType = GameSubControl.WINNERS_TAKE_ALL; } else { payoutType = GameSubControl.TO_EACH_THEIR_OWN; _gameCtrl.local.feedback("Error reading award split type"); }

Award coins
Use any of the above methods of awarding coins, with your payoutType variable instead of the constant. For example:

_gameCtrl.game.endGameWithScores(playerIds, scores, payoutType);

Cheating!
Players WILL hack your game. Take some basic steps to make this harder by following the directions to prevent cheats.