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: