Inside Macintosh: Apple Game Sprockets Guide /

Chapter 4 - NetSprocket

Using NetSprocket

This section illustrates some of the basic ways you can use NetSprocket. It provides source code samples of a sample game that shows how you can

• initialize NetSprocket for use in your game
• host a game (optionally using the default human interface)
• join a game
• send and receive messages
• end the game.

Note

The code examples shown in this section provide only very rudimentary error handling.

Initializing NetSprocket

The NetSprocket shared library must be initialized by your application before you can use any NetSprocket functions. The library should be initialized once at application startup. Listing 4-1 shows you how to initialize NetSprocket.

Listing 4-1 Initializing NetSprocket

   err = NSpInitialize(550, 20000, 100, 'nspx', 100);
   if (err != noErr)  HandleError();

Note

Be sure to check for an error from this function. If NetSprocket returns an error, you may not call any other NetSprocket functions.

Hosting a Game

There are several things you must do to host a game, as detailed in the section below.

Creating a Protocol Reference and Advertising Your Game

First, you may optionally create protocol references. NetSprocket uses opaque protocol references and lists in order to insure that your game will function properly with transport protocols that are added to NetSprocket after your game is published. Since AppleTalk and TCP/IP are available on every Macintosh computer, you can specify default information for these protocols. Listing 4-2 illustrates how you can preconfigure AppleTalk with a default game name as it will appear to people browsing the AppleTalk network and create the protocol reference.

You do not have to create protocol references if you are going to use the default NetSprocket human interface. You only need to specify them if you want to set defaults yourself.

Note

This is the default name only. This name can be modified by the user if you display the host dialog box prior to actually hosting the game on the network.

Listing 4-2 Establishing the Game's Name and Creating a Protocol Reference

   NSpProtocolReference atRef, ipRef;

   // Do the dialog
   CopyPStr(gameName,   "\pMyGame");
   CopyPStr(gameType,   "\pExample10");

   // Set up our protocol list
   atRef = NSpProtocol_CreateAppleTalk(gameName, gameType, 0, 0);

Note

NetSprocket version 1.0 does not support the exclusion of players based on network speed or latency.

You can also create a TCP/IP protocol reference, as shown in Listing 4-3.

Listing 4-3 Creating a TCP/IP Protocol Reference

   ipRef = NSpProtocol_CreateIP(2002, 0, 0);

Note

There are a number of internet standards governing the assignment of ports. In general, ports 1-1023 are considered reserved, and should never be used by game developers. Ports 1024 and above are dynamic. Ports greater than 5000 are generally used for less-known services. Apple encourages you to choose a port greater than 5000 if you are going to assign a default port for your game. The port number is an unsigned 16 bit value from 0 to 65535.

Creating a Protocol List

The reason for creating and maintaining a protocol list is that NetSprocket can support multiple protocols in a single game. Whether or not you created any protocol references, you must create a protocol list. This protocol list will be passed to the NSpDoModalHostDialog function, or to the NSpGame_Host function. Listing 4-4 shows you how to create a protocol list.

Listing 4-4 Creating a Protocol List

   NSpProtocolListReferenceprotocolList;

   err = NSpProtocolList_New(NULL, &protocolList);
   if (err != noErr)  HandleError();

Note

When you create a protocol list, you can optionally append a protocol reference by passing it as the first parameter.

Adding Protocols to the Protocol List

When you have created your protocol list, you should add the protocols you support to your protocol list, as show in Listing 4-5.

Listing 4-5 Adding Supporting Protocols to a Protocol List

   err = NSpProtocolList_Append(protocolList, atRef);
   if (err != noErr)  HandleError();

Note

Once a protocol reference has been added to a protocol list, the list owns the reference. You should not attempt to free the reference in your game.

Presenting the Host Dialog Box

Once you've created your protocol list (and optionally set default information), you can present the default dialog box illustrated in Figure 4-4 for hosting a game by as shown in Listing 4-6.

Listing 4-6 Displaying the Host Dialog Box

   ok = NSpDoModalHostDialog(protocolList, gameName, playerName, 
password, NULL);
   if (!ok)  return;

Using the Host Function

Now that you have obtained and set the necessary configuration information, you are ready to actually host your game. Listing 4-7 shows you how.

Listing 4-7 Hosting your game on the Network

   NSpGameReferencegMyGame;

   err = NSpGame_Host(&gMyGame, protocolList, 8, gameName, password, 
playerName, 0, kNSpClientServer, 0);
   if (err != noErr)  HandleError();

Disposing of the Protocol List

When you have created the game reference, you can dispose of your protocol list. You do not need to dispose of each element you added to the list. You can just dispose of the list itself, as shown in Listing 4-8.

Listing 4-8 Disposing of your Protocol List

   NSpProtocolList_Dispose(protocolList);

Joining A Game

The NSpDoModalJoinDialog function may be used to allow a player to browse an AppleTalk network and join a game. The dialog box provided for you in NetSProcket is shown in Figure 4-5.You may also develop your own join dialog box. Listing 4-9 shows you how to use the NSpDoModalJoinDialog function.

Listing 4-9 Calling the NSpDoModalJoinDialog function

   CopyPStr(gameType,   "\pExample10");
   address = NSpDoModalJoinDialog(gameType, "\pAvailable Games:", 
playerName, password, NULL);

The actual process of joining a game is show in Listing 4-10. The address is the address reference returned by a call to the NSpDoModalJoinDialog function. Alternatively, you could get your own OTAddress through your own join dialog box, and then convert it into a NetSprocket address reference by calling NSpConvertOTAddrToAddressReference.

The player name, type, and password are sent to the host. If the host requires a password, and the password provided here is not correct, this function will succeed, but your first message you receive from NetSprocket will be a join denied message.

Listing 4-10 Joining the game

   err = NSpGame_Join(&gMyGame, address, playerName, password, 0, 0, 
NULL, 0);
   if (err != noErr)  HandleError();

After executing the NSpGame_Join function, you should release the address reference, as shown in Listing 4-11

Listing 4-11 Releasing the address reference

      NSpReleaseAddressReference(ad.dress);

Receiving Messages From Other Players

Now that the game is in play, you will normally drop into your main event loop. In your event loop, you should send any messages you have, and receive any messages that may be pending. Listing 4-12 shows an example of how to receive message from other players.

Listing 4-12 sample game event loop

void DoHandleMessages(void)
{
   NSpMessageHeader*message;
   
   while ((message = NSpMessage_Get(gMyGame)) != NULL)
   {
      switch(message->what)
      {
         case kNSpJoinApproved:
            DoJoinApproved((NSpJoinApprovedMessage *) message);
         break;
         case kNSpPlayerJoined:
            DoPlayerJoined((NSpPlayerJoinedMessage*) message);
         break;
         
         case kNSpPlayerLeft:
            DoPlayerLeft((NSpPlayerLeftMessage*) message);
         break;
         
         case kPlayerLocation:
            DoPlayerLocation((PlayerLocationMessage*) message);
         break;
      }
      
      NSpMessage_Release(gMyGame, message);
   }
}

Sending Messages to Other Players

In the course of play, it is normal to send messages to other players. In Listing 4-13, you see an example of sending a message to everyone but yourself.

Listing 4-13 Sending a message to all players

   PlayerLocationMessagemessage;
   
   NSpClearMessageHeader(&message.header);
   
   message.header.what = kPlayerLocation;
   message.header.to = kNSpAllPlayers;
   
   message.header.messageLen = sizeof(PlayerLocationMessage);
   message.where = where;
      
   NSpMessage_Send(gMyGame, &message.header, kNSpSendFlag_Normal | 
kNSpSendFlag_SelfSend);

Ending The Game

When it is time to end the game, you simply call the NSpGame_Dispose function, as shown in Listing 4-14. If you specify the kNSpGameFlag_ForceTerminateGame flag when you call NSpGame_Dispose, the other players will be notified that the game is over, and it will be disposed. If you don't pass this flag, and you're the host, NetSprocket will attempt to negotiate a new host. If a new host cannot be found, the function will return an error and you should call it with the kNSpGameFlag_ForceTerminateGame flag if you want to force it to quit. If you're a client, the kNSpGameFlag_ForceTerminateGame is ignored

Listing 4-14 Terminating the game

      NSpGame_Dispose(gMyGame, kNSpGameFlag_ForceTerminateGame);

}