igGameCenter API Developer Guide >> Creating a new game board
The most important part of the igGameCenter API is a script, handling all the events within the game boards. This handler accepts commands like "JOIN" or "MOVE", executes them and returns a new state of the game board (i.e. a list of all new events, a list of players and guests joined to the board and an information about the game itself). In addition this handler is used for keep-alive purposes, i.e. the external application should send a special command ("REFRESH") on periodic basis when there are no requests for execution of other commands.

For requesting an execution of a command an external application should send a POST request to the following API script:
http://<server_prefix>.iggamecenter.com/api_handler.php
containing the following parameters:
Field Name Field Content
app_id Application unique ID
app_code Application secret passcode
uid Member's ID that was received during authorization procedure)
session_id Unique session ID that was received during authorization procedure)
sid Session ID of the board.
cmd Requested command.

If this parameter is omitted then the handler assumes "REFRESH" command.
lasteid ID of a last event received in a previous call to the handler.

This parameter could be omitted on a first call to the handler.
Additional parameters can be required for different commands.

Below is a list of acceptable commands:
JOIN - this is a first command that should be sent by external application to any board. This command accepts the following parameter that should be included in a POST request in addition to the parameters mentioned above:
place This is an optional parameter telling the handler to place the joining member on a corresponding side of the game board. If this parameter is omitted then the handler initially joins the member to the board as a guest.
PLACE - this command can be sent by external application for placing the joined member on specified side of the game board (the action that is performed when a member clicks "Sit down" button) or returning him back to a guest list ("Stand up" button). This command accepts the following parameter that should be included in a POST request in addition to the parameters mentioned above:
place This is a required parameter telling the handler to place the joined member on a corresponding side of the game board. A value of 0 returns the member back to a guest list.

LEAVE - this command can be sent by external application for making the member to leave the board immediately.

SETUP - this command can be sent by external application before the game is started for setting up the game options. The command is accepted by the handler just from players or the game board owner. This command accepts the following parameters:

private 0 - the game board should be public.

1 - the game board should be private.
scored 0 - a score of each player should not be recalculated when the game is finished.

1 - a score of each player should be recalculated when the game is finished according to the game result.
timerTotal the total time for each player (measured in seconds, 0 - for unlimited time)
timerInc the additional amount of time each player gets after each move (measured in seconds, 0 - for no increment)

Additional parameters are accepted depending on a game (i.e. a number of initial seeds in each pit can be set for Kalah game). For a list of all currently available games and their specific parameters refer to this page.

START - this command should be sent by external application after placing the joined member on some side of the game board. The command indicates that the member is ready for starting the game with the current opponent. This command does not require any additional parameters.
Important remark #1: "Standing up" from the place cancels the start offering thus the "START" command should be sent again after sitting back on some place.
Important remark #2: The game is started when start offering is received from each player.

END - this command can be sent by external application when the member requests the end of the game either for himself (giving up) or for an opponent (claiming his loss). The command accepts the following parameter:

type The type of the "end game" request. Can contain the following values:

GIVEUP The member gives up. This request sets the player status to "LOST". The game can continue without the member under some circumstances if there were more then two players in the game.
OFFERDRAW The member offers or accepts draw. When a draw offering is received from each player, the game is finished and the player statuses are set to "DRAW".

Important remark #1: making a move by any player cancels all previous draw offerings.
Important remark #2: not all games support this request.
CLAIMQUIT The member claims loss of an opponent who quit the active game. This request will be accepted by the handler if all of the following conditions are true:
   - it is a turn of one of the opponents.
   - this opponent left the game more then 5 minutes ago.
MSG - this command can be sent by external application for adding a new message to a chat window. This command accepts the following parameter:
message the text of the new message.
MOVE - this command can be sent by external application for making a move in the game. This command accepts the following parameter:
move The code of the move.

The move code format depends on the actual game.For a list of all currently available games and their specific move codes refer to this page.

UNDO - this command can be sent by external application for handling reversion requests. This command accepts the following parameter:

type The type of the "undo" request. Can contain the following values:

ASK The member asks to undo to the specified position. The position is specified by the additional parameter move_ind that indicated the index of the move the member wants to revert to.
ACCEPT The member accepts the undo request. The game is reverted back to the requested position.
REJECT The member rejects the undo request. The game is not reverted back to the requested position.
FORBID The member forbids undo requests. The game is not reverted back to the requested position and no further undo requests are accepted for this game.

REFRESH - this command is used for keep-alive purposes, i.e. the external application should send this command every 10-15 seconds when there are no requests for execution of other commands.

RESTART - this command is used to start a new game on the same board with the same opponent when the current game is finished.



After execution of the requested command the handler returns one of the following responses:
Failure response:

<errorMessage>--Some error message--</errorMessage>

Success response:

<handlerData>
<sessionInfo cmd="REFRESH"
             curtime="1185775602"
             status="FINISHED"
             owner="126" />
<memberInfo active="0" finished="0" place="0" />
<playerList>
    <player uid="126" name="welinton.borges" sex="M" score="302" place="2" stat="WIN"
            lastRefresh="1185293041" online="0" active="0" finished="1" />
    <player uid="128" name="smokieye" sex="-" score="63" place="1" stat="LOST"
            lastRefresh="1185292981" online="0" active="0" finished="1" />
</playerList>
<guestList>
    <guest uid="2" score="0" name="Arty" />
</guestList>
<eventList>
    <event eid="43201" stamp="1185291587" uid="126" type="JOIN" data="welinton.borges" />
    <event eid="43202" stamp="1185291590" uid="126" type="PLACE" data="2" />
    <event eid="43227" stamp="1185292257" uid="128" type="JOIN" data="smokieye" />
    <event eid="43228" stamp="1185292257" uid="128" type="PLACE" data="1" />
    <event eid="43229" stamp="1185292269" uid="0" type="NOTICE" data="smokieye clicks START" />
    <event eid="43238" stamp="1185292368" uid="0" type="NOTICE" data="welinton.borges clicks START" />
    <event eid="43244" stamp="1185292524" uid="128" type="MOVE" data="NG1-F3" />
    <event eid="43246" stamp="1185292554" uid="126" type="MOVE" data="NB8-C6" />
    <event eid="43247" stamp="1185292565" uid="128" type="MOVE" data="NB1-C3" />
    <event eid="43249" stamp="1185292573" uid="126" type="MOVE" data=" E7-E5" />
    <event eid="43251" stamp="1185292598" uid="128" type="MOVE" data=" E2-E4" />
    <event eid="43256" stamp="1185292618" uid="126" type="MOVE" data="BF8-B4" />
    <event eid="43278" stamp="1185292841" uid="126" type="MOVE" data="QF6-G6" />
    <event eid="43279" stamp="1185292852" uid="128" type="MOVE" data="NF3xE5" />
    <event eid="43281" stamp="1185292865" uid="128" type="MSG" data="mistake" />
    <event eid="43282" stamp="1185292867" uid="126" type="MOVE" data="QG6xG2 #" />
    <event eid="43284" stamp="1185292981" uid="128" type="LEAVE" data="smokieye" />
    <event eid="43285" stamp="1185293041" uid="126" type="LEAVE" data="welinton.borges" />
    <event eid="49814" stamp="1185775602" uid="1" type="JOIN" data="Arty" />
</eventList>
<gameData>
    <board>w20000w500w7w800 ... 100b70000b60000b2</board>
    <wCaptured>20120</wCaptured>
    <bCaptured>20210</bCaptured>
</gameData>
<gameOptions>
    <hidden>0</hidden>
    <scored>1</scored>
</gameOptions>
<elapsed>0.056</elapsed>
</handlerData>
where
Field / Param Name Field Content
handlerData The main container including a list of all new events, a list of players and guests joined to the board and an information about the game itself.
sessionInfo Contains an information about the current game session.
cmd a command that was sent with this request
curtime Unix timestamp of the current time on the server. Using this timestamp you can calculate a difference between local and server time and then use this difference for displaying local times of all game events occured in the current game board.
status A status of the board:

INIT - the board is just opened but the game is not active yet
ACTIVE - an active game is taking place on the board
FINISHED - a game is already finished on the board
owner An ID of the member who opened this board.
memberInfo A container for the information about the current connected member.
active 1 indicates that it is a turn of the member now.
finished 1 indicates that the member has already finished this game.
place 0 indicates that the current member is a guest. Other values indicate that the current member is a player sitting on a corresponding side of the game board. The relationship between the side and the value of this parameter depends on a game.
playerList A container for the information about all players in this game.
player A container for the information about a single player.
uid Member ID of the player.
name Player's name.
sex Player's sex.
score Player's score.
place Player's place.
stat Player's state:

NONE - the default state
OFFERSTART - the player clicked START button
OFFERDRAW - the player offered draw to his opponent
DRAW - the game was finished with a draw (the state of both players is DRAW)
WIN - the player won the game
LOST - the player lost the game
QUIT - the player quit the active game and his opponent claimed player's loss
lastRefresh Unix timestamp of the last time when this member was seen by the server. Using this value with a value of the curtime parameter of the sessionInfo tag it is possible to detect when it is allowed to claim player's loss.
timerLeft Number of seconds left for this member (0 for games with unlimited time).
online 1 indicates that this player is online in the game.
0 indicates that this player left the game.
active 1 indicates that it is a turn of the member now.
finished 1 indicates that the member has already finished this game.
guestList A container for the information about all guests in this game.
guest A container for the information about a single guest.
uid Member ID of the guest.
name Guest's name.
score Guest's score.
eventList A container for the information about all new events occured since the previous request sent to the handler.
event A container for the information about a single event.
eid A unique ID of the event.An external application should store the ID of the last event in eventList container and pass with the next request to the handler (lasteid parameter)
stamp Unix timestamp of the server time when this event occured.
uid An ID of a member who sent this event (could be 0 for notice events)
type & data A type of the event and a data associated with the event. The meaning of this data depends on the type of the event:

type meaning of the event meaning of the data
JOIN a member with specified ID joined to the board the name of the joined member
LEAVE a member left the board the name of the left member
PLACE a member changed his place the value indicating a new place (0 for "standing up")
OPTIONS a member changes game options n/a
START a member clicks START n/a
NOTICE some notification event the text of the notification message
MSG a member sent a chat message the text of the chat message
MOVE a member made a move the move code
UNDOASK a member asks to revert the game to some position the index of the move to revert to

UNDODONE

 the reversion request is accepted the index of the move to revert to
RESTART a new board is created upon request from a member the sid of the new board

Important remark: PLACE, MSG and MOVE events contain information about members' IDs only. If you want to display names of the members for corresponding events (i.e. in a chat window) then you need to store the data coming from JOIN events (containing the names) in some temporary table and then use it for getting the name by ID.
gameData A container for the information about the current state of the game board. This container could be absent if the state of the game board has not been changed since the previous request that was sent to the handler. The content of the container depends on actual game.
gameOptions A container for the information about the options of the game. This container could be absent if the state of the game has not been changed since the previous request sent to the handler. The content of the container depends on actual game but there are two common options defined for all games: private and scored.
private 0 - the game board is public.
1 - the game board is private.
scored 0 - a score of each player will not be recalculated when the game is finished.
1 - a score of each player will be recalculated when the game is finished according to the game result.
timerTotal the total time for each player (measured in seconds, 0 - for unlimited time)
timerInc the additional amount of time each player gets after each move (measured in seconds, 0 - for no increment)