'''Version History:'''
 * 4th December 2004 - olsner - Created, UNDONE
 * 21st January 2005 - olsner - Updated with new MP interfaces.
 * 5th February 2005 - olsner - Documented event objects, added onDisconnect and server's onChat event callbacks
 * 23nd February 2005 - olsner - Player slots, client connect/disconnect events, session maps
 * 7th July 2005 - Stuart - Transferred Simon's doc to the Wiki.

'''Summary:'''
A run-through of the !JavaScript interfaces to common network operations.

= Setting up Game Parameters =

Game parameters such as the map file and number of players are set up using the g_GameAttributes global.

== '''g_GameAttributes''' Object Properties ==
 * '''numSlots''': the maximum number of slots available. Limited upwards to the max_players config value (default 6).
 * '''mapFile''': a map file path, relative to maps/scenarios/, default "test01.pmp"
 * '''slots''': An array of player slots

== '''g_GameAttributes''' Methods ==
 * getOpenSlot(): return the first open slot object

= Setting up Player Slots =

Each item in the '''g_GameAttributes.slots''' array is an object of type '''!PlayerSlot'''. A player slot can be:

 * Open,
 * Closed, 
 * Assigned to a Session,
 * Assigned to a Local player, or 
 * Assigned to an AI player (TBD).

Player slot 0 is automatically allocated to the server (MP) or local (SP) player; remaining slots are by default Open.

== '''!PlayerSlot''' Object Properties ==
 * '''player''': the Player object associated with the slot. Use to change civ/colour
 * '''session''': only available on the server and if the slot is associated to a session. Points to the server's session object.
 * '''assignment''': returns the current assignment status of the slot as a string ("open", "closed", "session" or "local")

== '''!PlayerSlot''' Methods ==
 * '''assignClosed(): Set the slot status to Closed
 * '''assignLocal(): Set the slot status to a Local player
 * '''assignOpen(): Set the slot status to Open (unassigned)
 * '''assignToSession(session): Assign the slot to a connected session
 * '''assignToAI()''': TBD

Note that the '''assign*''' methods can only be called on the server.

= Starting an SP Game =

Simple: Set up the '''g_GameAttributes''' object as you like it and call '''startGame()'''

= Hosting an MP Game =

Call '''createServer()''' to create the server object. There are two ways to get at that object once it's created: either use the '''g_NetServer''' global or save the return value of the '''createServer''' function. Use '''g_GameAttributes''' to set up all the common attributes like the map file to use etc etc.

Once the server object is created, you modify the server parameters by setting the properties of the server object.

== !NetServer Object Properties ==
 * '''serverPlayerName:''' the name of the local player on the server; default '''"Noname Server Player"'''
 * '''serverName:''' the name of the server (for things like lobby [if we ever make one], and sent to the connecting client for identification); default '''"Noname Server"'''
 * '''welcomeMessage:''' sent to connecting clients as part of the handshake. Place for your license notice or terms of usage, or just a welcome message :P. Default '''"Noname Server Welcome Message"'''
 * '''port:''' the port to open and listen for incoming connections. The default is '''20595''' (you can also set -1 to just return to the default port).
 * '''sessions:''' a list of sessions, use the session's integer Session ID as index. Elements are of type '''!NetServerSession'''

== !NetServer Event Callbacks ==
 * '''onChat:''' called when a chat message arrives from one of the clients.  The passed '''event''' object has the following properties:
  * '''message:''' the text message that was sent
  * '''sender:''' the name of the originating client
 * '''onClientConnect:''' a new client has connected (and entered the password if there was any). The passed '''event''' object has the following properties: 
  * '''id:''' The session ID that was assigned to the session
  * '''name:''' The name of the session
  * '''session:''' The session object (Only available on the server)
 * '''onClientDisconnect:''' one of the clients has been disconnected. The event object has the same properties as the '''onClientConnect''' event.

== !NetServer Methods ==
 * '''open():''' start listening on the set port and accept incoming connections

== !NetServerSession Object Properties: ==
 * '''id:''' the numeric session id
 * '''name:''' the name of the session ("John", "leetfisher2000", etc)

When you're done with setting up these parameters, you open the port and start the actual server by calling the '''open()''' method on your server object.

== Example Server Code ==

{{{
  // Create the server object, store it in server
  // You could also skip setting server and just use g_NetServer instead
  var server=createServer();
  // Set up a custom welcome message:
  server.welcomeMessage="Greetings! This is my Server!"
  // Custom port number - just to spice things up a bit :P
  server.port=3000
  
  // All done - now start listening for incoming clients
  var res=server.open();
  if (!res)
      // error
  else
      // success - proceed to the next server screen
}}}

Wait for players to join, assign them to slots as you want, then start the game with '''startGame()'''.

= Joining an MP Game =

Like setting up the MP server, joining an MP game is done by creating a client object, setting it up, and asking it to connect to the server.

== !NetClient Object Properties ==
 * '''password:''' the password to send to the server when asked
 * '''playerName:''' the name to present yourself as to the server
 * '''sessions:''' a list of session objects (synchronized with the server's sessions array - see above). These session objects have the same properties as '''!NetServerSessions''' (see above).

== !NetClient Event Callbacks ==
 * '''onStartGame:''' a function or script string that is called when the server signals that the game is to be started
 * '''onChat:''' called whenever a chat message arrives from the server. See '''!NetServer.onChat''' above.
 * '''onConnectComplete:''' called when the connection to the server is complete or if the connect attempt failed. The passed '''event''' object has the following properties:
  * '''success:''' a boolean, true if the connect was successful, false otherwise
  * '''message:''' an error message or "OK"
 * '''onDisconnect: called when the client gets disconnected from the server. The passed '''event''' object has the following properties:
  * '''message:''' an error message or "OK"
 * '''onClientConnect:''' See '''!NetServer.onClientConnect''' above.
 * '''onClientDisconnect:''' See '''!NetServer.onClientDisconnect''' above.

== !NetClient Methods ==
 * '''beginConnect(serverIP, port):''' Connect to server at the given IP. (Port number is optional.)

== Example Client Code ==
{{{
  var client=createClient();
  
  client.playerName=playerName;
  
  client.onStartGame=function () {
      // The server has called Start Game!, so we better switch to the session GUI and stuff
      // like that.
  };
  
  client.onChat=function (event) {
      ....
  };
  
  client.onConnectComplete=function (event) {
      ....
  };
  
  client.onDisconnect=function (event) {
      ....
  };
  
  // Join MP game
  var success = client.beginConnect(serverIP[, port]); // port is optional
  if (!success) {
      // error
  }
  // NOTE just because beginConnect returns true, that doesn't mean that the client is
  // successfully connected. That isn't known until onConnectComplete is called.
}}}

When the server user clicks Start!, all clients will simultaneously start their simulations, and the '''onStartGame''' event function is called.

= Ending a Game =

Calling '''endGame()''' will immediately end the game, disconnect from the server (MP client), shut down the server and disconnect all clients (MP server).

= Game Setup Global Functions =

== startGame ==
 * '''Overview:'''
  * Begin the process of starting a game.
 * '''Syntax:''' 
  * success = startGame()
 * '''Parameters:'''
  * 
 * '''Returns:'''
  * success [bool]
 * '''Notes:'''
  * Performs necessary initialization while calling back into the main loop, so the game remains responsive to display+user input.
  * When complete, the engine calls the reallyStartGame JS function.
 * '''TODO:'''
  * Replace startGame with create(Game|Server|Client)/game.start() - after merging CGame and CGameAttributes

== endGame ==
 * '''Overview:'''
  * Immediately ends the current game (if any).
 * '''Syntax:''' 
  * endGame();
 * '''Parameters:'''
  * 
 * '''Returns:'''
  * 
 * '''Notes:'''
  * 

== createClient ==
 * '''Overview:'''
  * Create a new network client object.
 * '''Syntax:''' 
  * client = createClient();
 * '''Parameters:'''
  * 
 * '''Returns:'''
  * network client object
 * '''Notes:'''
  * 

== createServer ==
 * '''Overview:'''
  * Create a new network server object.
 * '''Syntax:''' 
  * server = createServer();
 * '''Parameters:'''
  * 
 * '''Returns:'''
  * network server object
 * '''Notes:'''
  *