TweetFollow Us on Twitter

Happy Face CTB Game

Volume Number: 13 (1997)
Issue Number: 2
Column Tag: Communications Toolbox

HappyFace

By Mark Chally, Covina, California

Using the Communications Toolbox to build an interactive, two-player game

The purpose of this article is to implement a simple, two-player, interactive game as a means to explore Apple's Macintosh Communications Toolbox. It includes methods for using the Connection Manager to send and receive information. This article builds on the fundamentals learned in the DebugTerm article, found in MacTech 12.10 (October, 1996).

Introduction to HappyFace. Where did it come from?

After DebugTerm went to press, I suggested a follow-up article to further exploit the CTB. I thought a simple game would be entertaining and instructive. Time was short, but the challenge was exciting. Of several possible game ideas, HappyFace was the clear choice, having the advantages of simplicity and entertainment value.

Long before Barney the dinosaur would be loathed by adults everywhere, there were happy faces. Surely you remember the little yellow pill-shaped guys with Kool-Aid grins, found on T-shirts, pins, and bumper stickers accompanied by "Have a Nice Day." Soon, T-shirts displayed happy faces with bullet holes in their foreheads from which blood oozed. Later, arcade games appeared in which players would use mallets to strike gophers' heads as they poked up through holes. Finally, Mike Darweesh wrote the Macintosh game "Bonk," based on the gopher games. In Bonk, players click on silly heads as they appear in a grid, before they disappear - at progressively shorter intervals. HappyFace was inspired by that weird combination of sarcasm and gaming.

How do you play it?

HappyFace is a two-player game that gives you the opportunity to smack those little yellow critters. You use the CTB to connect with your opponent. HappyFace does not care what tool is used to establish the connection, but it does expect the tool to support a means to simultaneously send and receive data using the standard CTB functions. Most, if not all connection tools do this. You earn points by striking the faces as they appear on a grid. The first player having 25 points wins.

When launched, if HappyFace cannot find the preferences file in the program's folder it poses the Connection Settings dialog (Figure 1).

Figure 1. Connection Settings Dialog with Apple Modem Tool's default options.

If the user cancels the dialog, the program beeps and aborts. Otherwise, it creates a game window with 64 squares, eight rows and eight columns. HappyFace then waits for the user to establish a connection, which is initiated using the Connect, Listen, and Settings items on the Connection menu.

Once a connection has been established, either player may select New Game from the File menu. When the game begins, each player's copy creates five happy faces which inhabit randomly selected squares in both players' windows (Figure 2).

Figure 2. The HappyFace window with no faces struck.

Each player may then strike happy faces by clicking on them using the cursor - which becomes a mallet whenever it is positioned over the window. As the faces are struck, their features (eyes and mouths) change color and shape. Faces which have not been struck have blue features. Those struck by the player using the local copy receive green features, and those struck by the opponent receive red ones (Figure 3).

Figure 3. The HappyFace window with faces struck by both players.

One second after each face has been struck it dies and vanishes. The copy of HappyFace which created the face (the local copy or the opponent's) replaces it with a new one that inhabits another randomly selected square. The first player to strike 25 faces wins, at which time a dialog is displayed by each copy to inform the users of the good or bad news. When no game is in progress there is no mallet, and any faces remaining do not respond to being clicked. At any time during the connection a new game can be started, including while one is in progress. If a user quits while connected, the connection is closed. If a connection is closed, any game in progress ends.

CTB Recap and Comparison to DebugTerm

What is DebugTerm, and why read about it?

In the DebugTerm article, I implemented a C source file that could be compiled into a program under development to export debugging information through a CTB connection. It made a good introductory project because it required minimal CTB services. If you have not read it, I strongly suggest that you do since it provides an introduction to the CTB and some base code for HappyFace. In short, this article builds on that one.

Where did DebugTerm fall short?

DebugTerm is a good start, but not a complete program. Serving as a debugging tool, it takes shortcuts in opening and closing a connection that a user-friendly program should not. Secondly, it only sends information, it does not know how to receive it. Additionally, it only initiates a connection using CMOpen() to connect with another device or program; it does not know how to use CMListen(). Finally, it asks the connection tool not to use windows or menus, thus requiring no event processing. HappyFace addresses these new issues.

Making a Complete Application

Isolating connection logic

HappyFace behaves as a CTB program should. It initializes the CTB and creates and configures a connection record at launch time. However, CMOpen() is not executed until the user wishes to open a connection. In contrast, DebugTerm executes CMOpen() immediately after creating and configuring the connection record. DebugTerm also disposes of the connection record at the same time that it closes the connection. HappyFace waits until quitting time to dispose of the connection record, at which time it also saves the configuration. For this reason, the process of opening and closing connections is simple and reliable.

It pays to CMListen

Besides isolating the initialization from opening and the disposal from closing, HappyFace also adds a new and important way to connect: CMListen(). Some tools require one party to use CMListen() while waiting for the other to initiate the connection using CMOpen(). For example, in response to CMListen(), the Apple Modem Tool waits for a telephone call from another modem. The AppleTalk ADSP Tool registers itself on the network and waits for a connection request from an ADSP Tool using CMOpen(). Both expect the application to respond to CMOpen() by accepting the connection using CMAccept(). The Serial Tool does not support CMListen(). It uses CMOpen() to establish a connection through the serial port you choose. Unlike most tools, it does not care about whether anything is at the other end of the serial cable. HappyFace does another important thing that DebugTerm did not do - it polls the connection for incoming messages using CMRead().

Handling the interface

In addition to those details, HappyFace also accepts a new realm of responsibilities. It maintains a Connection menu that allows the user to decide when and how to choose and configure a tool, and establish a connection. This means that HappyFace has the duty of maintaining these menus, in addition to the events, most of which it passes along to the connection tool via CMEvent(), CMActivate() and CMResume(). These events may also be generated for additional windows or menus that HappyFace permits the tool to create and maintain. Certain events can be identified as belonging to the tool and passed along. HappyFace detects and delegates these.

Encapsulating CTB code

Virtually all of these activities, which relate solely to maintaining a CTB connection, are contained within CTB.c. HappyFace, merely an example of a CTB application, can take advantage of this by installing a few MENUs, passing along important events, and making a few simple function calls. The ease with which CTB.c can be used is apparent since CTB.h profiles only a few simple function calls.

Encoding a game message

There are three game actions requiring messages: start a new game, create a face, and strike a face. Communication logic is simplified by stuffing an entire message into a single byte of the form AAHHHVVV.

The first two bits represent the game action, the next three represent the horizontal position if applicable, and the last three represent the vertical position if applicable. Some bitwise manipulation is required when sending and receiving the message, but the utility of treating a single incoming character as an entire message greatly simplifies things.

Test Spin

Before exploring the workings of HappyFace, let's watch the game in action. There are many ways to connect using the CTB, but you should consider the following points that you may find remarkably similar to those of the DebugTerm article.

Means of Connection

If you have an AppleTalk network or intend to demo HappyFace on a single Mac, I recommend that you connect using the AppleTalk ADSP Tool. Otherwise, I recommend the Serial Tool. If you choose the Apple Modem Tool you can connect by modem, but probably will not have the opportunity to see both copies of HappyFace side-by-side. You may choose to use another tool, in which case I am interested in hearing about your experiences.

Using the Serial Tool you can connect two Macs, or even connect a Mac's modem port to the same Mac's printer port. To use the Serial Tool, you will require a null modem cable. This is the cable used for most printers and to communicate with a Newton by serial port. It is up to you to get the connection right, but if it works between terminal programs, it should work for HappyFace.

If you choose the AppleTalk ADSP Tool, you can connect between two Macs on a network, or from one Mac to itself. To connect a Mac to itself with the AppleTalk ADSP Tool no physical connection is necessary, but be sure AppleTalk is turned on in the Chooser or the tool will not load. If you need a copy of the AppleTalk ADSP Tool, you can find it on one of Apple's FTP sites. You may also find what you need on ETO or the CTB SDK. HappyFace needs the Communications Toolbox, 32-bit QuickDraw with at least a 16-color monitor setting, and the Sound Manager. It would be a good idea to use System 7.5 or later since HappyFace does not use Gestalt to check these.

Connecting to Yourself

If you choose to connect the Macintosh to itself, either by using the AppleTalk ADSP Tool for a virtual hookup, or Serial Tool from modem to printer port, you should keep one thing in mind. To connect a Macintosh to itself, you must use asynchronous calls. See the diatribes in the DebugTerm article about asynchronous calls and completion routines. HappyFace also has an "empty" completion routine. To allow a connection between two copies on the same machine, I compiled HappyFace using asynchronous calls. Though many readers without two Macs may wish to take advantage of this feature, you will find HappyFace awkward to play as a two-player game when both copies are on the same machine. Also, the HappyFace I compiled is a fat binary so that it will run native on PowerPC machines.

Bang Away!

You will need to use two instances of HappyFace. Ideally, these instances would be run on separate machines. However, if you want to run both copies on the same machine, simply make an additional copy in another folder and launch each separately. Preferences are stored in the application's folder. If you have already run HappyFace, you may wish to throw away the file named "HappyFace Prefs."

Launch one copy of HappyFace. If it finds no preferences file, it poses the Connection Settings Dialog before allowing you to do anything else. If not, select Settings from the Connection menu. In the dialog, use the Method popup to choose the connection tool you wish, such as the Serial Tool or the AppleTalk ADSP Tool (Figure 4).

Figure 4. Connection Settings Dialog with the AppleTalk ADSP Tool's options.

If you chose the AppleTalk ADSP Tool, you may choose a name for the machine by typing what you wish into the Local Name: field in the lower-right-hand corner. It is probably best not to change the Connection Type field, but if you do, both instances of HappyFace must have the same type. Press the OK button.

If you chose the Serial Tool, you can select the port settings that you require. The ones displayed are probably the best (Figure 5).

Figure 5. Connection Settings Dialog with the Serial Tool's options.

Regardless of how you set them, they should all be set the same for both copies of HappyFace, and the Current Port should be set to whichever port your cable is plugged into. Press the OK button.

If you chose the AppleTalk ADSP Tool, choose the Listen item from the Connection menu. You can tell that HappyFace is listening for a connection because the Listen item now reads Stop Listening, and the other items on the Connection menu are dimmed.

If you chose the Serial Tool, choose the Connect item from the Connection menu. You can tell that you are connected (to the serial cable) because the Disconnect item is now enabled and the other items on the Connection menu are dimmed.

Now you are ready to connect the second copy of HappyFace to the first. Launch the second copy. If you chose the AppleTalk ADSP Tool, choose it again from the second copy. You should see the name of the first, listening copy in the scrollable list on the right-hand side under the Name field. You may need to find the AppleTalk Zone that the first copy is in from the list on the left-hand side, under the Zone field. Select the name of the first copy, and press the OK button.

If you chose the Serial Tool, select the same settings as in the first copy, except the modem or printer port as necessary. Press the OK button.

Now select Connect from the Connection menu. The two copies of HappyFace should be ready to start a game. You can tell they are connected because the New Game item on the File menu, and the Disconnect item on the Connection menu are now enabled, and all the other items on the Connection menu are dimmed. If you select New Game from the File menu ten happy faces should appear in each window.

Use the cursor (mallet) to strike faces in each copy. You should see something like Figure 3 when faces are being struck from both copies. Notice how the features of a face struck locally become green, but those of one struck by an opponent turn red. Notice that HappyFace allows one second to pass before the face you struck "dies."

Normally the game ends when a player strikes 25 faces. Quitting either copy by selecting Quit from the File menu or closing the HappyFace window breaks the connection. Selecting Disconnect from the Connection menu also ends any game in progress. Continue to play as many games as it takes to get a feel for it.

Source Code Walk-through

HappyFace was written in C, using Metrowerks CodeWarrior Integrated Development Environment (IDE) 1.7. I used two project files - one for 68k, and one for PowerPC. If you use Symantec, MPW, or some other development system, you should not have much trouble creating project files. You will either want to print a copy of the source code or view it on your monitor alongside the article.

Overview

This project is divided into three separate code domains. The file CTB.c isolates the CTB code so that it can be used, much as a library would, along with CTB.h. It should require little modification to be included within another project. It contains private data structures and functions specific to the operation of the CTB. CTB.h contains useful constants and function prototypes to #include in other source files. Game.c contains functions and private data structures that are specific to the game logic, but have no specific knowledge of the CTB. Game.h contains prototypes for the Game.c functions that Main.c needs to call. Main.c contains the "boilerplate" code necessary to launch the program, handle simple events, maintain the cursor and menus, and quit.

Header files

CTB.h is similar to DebugTerm.h. In addition to function prototypes, it contains shared resource ID's, and literals for parameters and common error codes. I shamelessly kept the error codes from DebugTerm, although I could have developed a more extensive set. The literals, such as kAsync, help make the code readable. Game.h has prototypes to game functions that are called by Main.c.

CTB.c

This file contains C code necessary for Communications Toolbox connections. You are already familiar with most of it, having read about DebugTerm which was extended from DebugTerm.c. We now concentrate on new or modified functions.

It begins with a #include to CTB.h, then defines its literals and globals. One of the "new" features is a group of Universal Procedure Pointers (UPP), such as gCMCompletion, for PowerPC compatibility.

CMWriteProc(), formerly CMSendProc(), is unmodified. However, you should inspect it closely since I originally uploaded an outdated version of CMSendProc(), which I have since replaced with a more correct version.

ConnEvent() handles events for a connection tool window. It is called from the event loop to give the connection tool the first opportunity to handle the event. CTB tools poke their own handles (e.g. ConnHandle) into the refcon fields of their windows. Therefore, ConnEvent() finds the window associated to theEvent. Next, it makes sure it has a valid WindowPtr and ConnHandle. If not, it returns false, else it checks to see if the window's refcon is the same as the ConnHandle. If they are not the same, it returns false. Otherwise it returns true, indicating that the event was handled, after calling CMEvent() to delegate the event to the connection tool, which handles the event if appropriate.

ConnActivate() informs a connection tool of an activate event. Called from the place in the event loop where activate events are trapped, it passes the message on to the connection tool, indicating whether the window is being activated or deactivated. ConnActivate() saves the current GrafPort and sets it to the given window before calling CMActivate(), then restores the current GrafPort. I found this behavior, taken from sample code in Inside CTB, odd. I would have expected the WindowPtr to be passed as a parameter instead.

ConnResume() is structurally identical to ConnActivate(). It informs the connection tool of a resume (or suspend) event. The resuming parameter indicates whether the application is being suspended or resumed.

putc(), provided for simplicity, calls CMWriteProc() to send the character it receives as a parameter. It returns whatever value it receives from CMWriteProc().

CMReadProc() attempts to read *theSize characters by calling CMRead(). If gConn is not nil, it returns the value obtained by calling CMRead(). If there is no connection record, it passes back 0 as *theSize. This version of HappyFace always issues CMRead() calls synchronously to make the article simpler. Next time, we will need to expand its capability. CMReadProc() is a Pascal function so it can be called by the Terminal Manager or the File Transfer Manager in a broader implementation.

getc() tries to read a single character by calling CMReadProc(). If it finds none, it places a NULL in c. It returns whatever error CMReadProc() encounters.

InitCTBStuff(), essentially the same function as its DebugTerm counterpart, additionally generates UPPs for the CMCompletion(), CMWriteProc(), and CMReadProc() by calling the appropriate managers' functions.

ChooseConnection() has been modified to behave better in a modeless program environment. Now kNothingChosenErr is only returned if cancel is pressed (so that it can be trapped at startup when no preferences are found). It still returns noErr if the current tool is reconfigured or a different tool is selected, since we do not need to care because we never allow this dialog to be posed while connected. In all other cases, it returns whatever CMChoose() does.

NewConn() is one of three functions that replaces the functionality of DebugTerm's OpenDebugTerm(). NewConn() handles most of its functionality, making it almost identical. NewConn() does not call WritePrefs() or CMOpen() where OpenDebugTerm() did. These tasks are left to DisposeConn() and OpenConn(), respectively. It does a few additional things, however. It initializes gFlags to false, which, when passed to CTB functions, (currently, according to Inside CTB) indicates that we do not wish to send end-of-block indicators. It also passes the async parameter through to the global variable gAsyncCalls and sets gPrevStatus to an impossible token value, which will cause the status to be re-evaluated in IdleConn(). Finally, it calls GetMenu() for the handle to the Connection menu, which was installed in the main program. If NewConn() encounters an error, it returns it, else it returns noErr.

OpenConn(), called when the Connect item is selected from the Connection menu, calls CMOpen() to open a connection. First, however, it verifies that the connection record exists. It returns whatever value CMOpen() returns.

ListenConn() is called when the Listen item (or Stop Listening) is selected from the Connection menu. It first verifies that a connection record actually exists, and if so, it calls CMStatus(). If CMStatus() indicates that the tool is already listening for a connection, it calls CMAbort() to stop listening, else it calls CMListen(), instructing the tool to wait indefinitely (-1) for a connection. Unlike most functions which can be called synchronously or asynchronously, HappyFace calls CMListen() asynchronously regardless of the value of gAsyncCalls. It does this because some tools, such as the AppleTalk ADSP Tool, provide no opportunity to stop listening when asked to wait indefinitely. Using the asynchronous call allows the user to select Stop Listening, which causes ListenConn() to call CMAbort(). Some tools, such as the Serial Tool, do not support CMListen() at all, and return cmNotSupported. If an error occurs, the error is returned, else noErr is returned.

CloseConn() is one of two functions that split the duties previously performed by CloseDebugTerm(). When the user selects Disconnect from the Connection menu, it first verifies that the connection record exists, then verifies that the connection is open or opening. If so, it calls CMClose() to drop the connection.

DisposeConn() is the second of the two functions that split CloseDebugTerm()'s duties. Called before HappyFace exits, it first verifies that the connection record exists, then calls WritePrefs(). Once the preferences have been written, it closes the connection by calling CloseConn(), unlocks the connection handle, and calls CMDispose() to deallocate the connection record and any other data the tool may be using. Finally, it sets the connection handle to nil, and reports noErr. DisposeConn() does not report any error unless there is no connection record, because it is only called at application exit. In fact, it calls CloseConn() without checking to see if connected. It could check that first, and it could also report any errors returned by CloseConn() or CMDispose().

IdleConn(), called during each iteration of the event loop, performs periodic tasks necessary to support a connection tool. It begins by verifying that a connection record exists, and if not, it disables the connection menu items. Otherwise, it begins by calling CMIdle(), which gives the connection tool its housekeeping opportunity. Next, it checks the connection status. If an error occurs, it returns it, else if the tool has sensed an incoming call (cmStatusIncomingCallPresent) it calls CMAccept() to establish a connection. If the connection status has changed, it updates the Connection menu accordingly, updates the online parameter, updates gPrevStatus and returns any error that occurred.

DoConnMenu(), called by the main application's DoMenu() function when a connection menu item is selected, calls the appropriate CTB.c function. It doesn't bother to report or return errors, though you may wish to. It beeps in the case of an error, except kNothingChosenErr, returned by ChooseConn(). This is because kNothingChosenErr results from pressing the Cancel button, which is fine when resulting from a menu selection.

Game.c

This file contains functions to control the game activity, but no code specific to the CTB. It begins with a few groups of literals. Those in the first group denote spacing and graphics proportions. Those of the second indicate whether a square is occupied, and if so, what condition the occupying face is in. Those in the next control the bounds of the game logic. Following that are the codes for the possible game actions. Messages sent through the connection have these codes in the first two bits to indicate that a face has been made or struck, or that a new game has been started. Being a two-bit code, the possibilities are 0-3; 0 is skipped to avoid confusion with the NULL character. The literals in the last group are resource IDs.

Next in Game.c is the struct used to store information for a square.

typedef struct {
 short occupant; // kEmpty, kHealthy, kStruckLocally, kStruckByOpponent
    long age;               // TickCount() at status change
    Rect boundsRect;    // Bounding rectangle for gSquare
    Boolean madeLocally;// Keep track of whether made locally
} contents;

The occupant field contains a square's status. The age indicates at what TickCount() the square's status last changed. We want a face to take one second to die, so we have to watch the time. boundsRect holds the local coordinates of the square's rectangle. madeLocally indicates whether the local copy or opponent's copy created the face.

In the interest of fairness, we make sure that each copy maintains a fixed number of faces. When a face is created, it takes a variable amount of time to transmit the creation message to the opponent's copy. Using the convention introduced here, the players' individual copies effectively take turns. Thus, each player has a "net equal time delay" in the sum of the differences between the times at which faces are created and become visible.

Next is a group of globals, kept private to game.c using the static keyword. These are some of the most notable globals: gPixMapHand is an array of the pixmaps used to store the different drawn faces so that they can be copied to the game window. gMadeCount is used to represent the number of currently-living faces a copy has created. gLocalStruckCount and gOpponentStruckCount are used for keeping score. gSquare is the array of square contents. gStrikeHand and gSndChannelPtr are used to play the striking sound. gPicRect is a Rect with its top-left corner at the origin and the height and width of a square.

PlayStrikeSound(), called when a face is struck, verifies that the handle to the sound and pointer to the sound channel are valid, then calls SndPlay() asynchronously.

ShowScores() is called when a game ends to display the scores to each user. It counts the points up first to see if the game was actually played. If faces have been struck, it converts the numbers to strings using NumToString(), uses ParamText() to preload text for the Dialog Manager, then calls Alert().

DrawSquare() draws the appropriate image in the appropriate place on the game window. First it assures that the parameters, h and v, are within the valid range of rows and columns, then it sets the current GrafPort to the game window after saving the old GrafPort. It calls CopyBits() to copy the contents from the appropriate pixel map we already created to the appropriate place in the window. Finally, it restores the current GrafPort.

NewGame(), indirectly called when either player selects New from the File menu, initializes the game status variables, sets each square's contents as empty, and draws each square.

MakeGWorld(), borrowed from the Dave Mark article, calls NewGWorld() to allocate a fresh default GWorld to store squares' graphics in.

NewGameWindow(), called at application launch, initializes everything on which the game's logic rests. It begins by seeding the random number generator with the long integer which represents the current date and time. Then it attempts to create a new sound channel and load the SND resource for the strike sound, which it moves into high memory and locks if successful. Note that the sound playing code does not attempt to play the sound if either of these could not be allocated. Next, it calculates the size and position of the window, calls NewCWindow(), fills the gSquare array with empty squares, and calculates their rectangles. For each of the four graphics used to draw squares, it loads the pixel maps and draws them into their own separate GWorlds. Most of this was also taken from Dave Mark. Finally, it calls ShowWindow() to make the new window appear on the screen.

KillStruckFaces() is called by the IdleGame() function each time through the event loop. It looks at each square and determines if the square contains a face that has been struck by a player. If so, and if it was struck more than one second ago (kDyingTime), it makes the square empty, assigns the time of vacancy, redraws the square, and if the face was made by this copy it decrements the number of living faces made by this copy. Because gMadeCount will be less than kMaxMade, this will result in the eventual creation of a new face.

UpdateGameWindow(), called in response to an update event, saves the current GrafPort and sets it to the game window. Next it finds the Rect bounding the update region and uses it to decide which squares are in the region. After it has determined what range of rows and columns it needs to draw, it calls BeginUpdate() to keep from generating additional events, and draws them top-left to bottom-right. It calls EndUpdate() to cancel BeginUpdate() and sets the current GrafPort back to the saved one.

ShowStruckFace() is called when a face has been struck. It receives the horizontal and vertical location of the face, and whether the strike was local or by the opponent. It uses those parameters to update the square's information and redraw the square. Before returning, it plays the strike sound.

SendGameAction() assembles a game message and sends it. The message has three parts. The rest of the communication logic is greatly simplified by stuffing an entire message into a single byte. The first part is a two-bit action indicator, the next three bits indicate the horizontal component of the square's location, and the final three indicate the vertical component of the square's location.

First it loads the action indicator into the character, then shifts three bits to the left so that it can add in the horizontal component. Then it shifts three more bits to the left and adds the vertical component. Finally, it calls putc(), whose return value it also returns, to send the character.

SendNewGame() asks SendGameAction() to send a message with the kActionNewGame indicator through the connection (the horizontal and vertical components do not matter).

HandleOpponentStrike() is called in response to having received a message which indicates that the opponent has struck a face. First, it increments the opponent's score. Next, if the opponent has reached the winning score, it stops the game. Then, if the face is actually healthy, it calls ShowStruckFace() to change its status and redraw it. It always gives the opponent credit, but does not always change the square's status. It is theoretically possible for both players to strike a face "at the same time" and for the messages to "cross in the mail." Instead of using a tie-breaker to resolve the conflict, it gives both players credit. It does not draw in response to this case, because that would cause a face to change from green to red or red to green.

HandleWindowClick() is called when a mouse click in the game window is detected. First it determines which square, if any, was clicked, by reducing the Point to local coordinates and dividing by the pixel offset between squares. As an added protection, it verifies that the calculated value is in range, to avoid addressing a non-existent array member. If the row and column are valid and there is a healthy face in the indicated square, it uses SendGameAction() to inform the opponent of the successful strike. If no error is returned, it increments the player's score and compares it to kWinningScore. If the score has exceeded the winning score, the game will be stopped. It calls ShowStruckFace() to indicate to the user that the face has been struck.

ShowFace() puts a healthy face on a given square. It sets the square's status to indicate a healthy face, sets the age to TickCount(), and sets madeLocally according to the parameter that it receives. Finally, it calls DrawSquare() to draw the face in the game window.

MakeFace() is called when IdleGame() determines that it must place another face on the window to meet its quota, kMaxMade. First it randomly chooses a row and column, repeatedly, until an empty square is found. Next it informs the opponent's copy that it has created the face, and calls ShowFace() to show the user. Finally, it increments gMadeCount, the number of currently-living faces that have been made by the local copy.

HandleGameAction() dispatches game actions which have been received to the appropriate function, according to the action type. In some cases it starts or stops a game. Therefore, it passes back the resulting value of inProgress.

GetGameAction() is called by IdleGame() each time through the event loop. It determines whether a game message is waiting, and if so, dispatches it. First it calls getc() to read the character. If the character is not NULL and there is no error reading, it processes it. It extracts the action indicator by rotating a copy of the byte 6 bits to the right. Next it rotates another copy three bits to the right and looks at the least-significant three bits, which become the horizontal component. The least-significant three bits of the original become the vertical component. Finally, it delegates the interpretation of the message to HandleGameAction().

IdleGame() gets called once from each iteration of the event loop. It first calls GetGameAction() to dispatch any opponent actions waiting. Next it calls KillStruckFaces() to remove any faces struck more than one second before. If the game is still in progress and the number of faces is less than the quota, it calls MakeFace().

Main.c

Activities not specific to communications or game logic are conducted within this file. That leaves calling the procedures necessary for initializing the program, dispatching events, and quitting. Since most of us have seen this repeatedly, we will brush over the bulk of the code, discussing only the unusual or confusing parts of this file.

It begins by defining literals and usual globals. Some globals of note are gHammerHand, which points to the mallet cursor; gGameInProgress, which indicates whether a game is being played; and gOnline, which indicates that a connection is open.

ExitNow() is used as an emergency exit, while DoQuit() is called when a user chooses Quit from the File menu. Both call DisposeConn(), which makes sure the connection is closed if possible. DoQuit() also shows the scores if a game was in progress, because there will be no chance for the event loop to detect that the game ended.

InitApp(), in addition to calling SetupMenus(), also does a few other things. It allocates the hammer cursor's structure, moves it in to high memory, and locks it. It calls NewConn() to install a connection record, and if it fails, beeps and quits. It calls NewGameWindow() to create the game window and initialize supporting game logic, then finally initializes Main.c's own globals, gOnline and gGameInProgress.

DoMenu() handles menu selections in the usual way, with some exceptions. Since HappyFace adjusts the cursor, it provides an arrow cursor before putting up the About box. It sets gGameInProgress to true when a new game is started. Notice that it calls DoConnMenu() to delegate a selection from the Connection menu. It does this because it knows the menu's ID. There may be a less application-specific way to sense and handle Connection menu selections. Perhaps ConnEvent() could sniff them out instead.

AdjustCursor() was one of the more pesky details of this project. Called from various places in the event loop, it changes the cursor, if appropriate. According to some Apple documentation, you can set it up so that it only gets called when the mouse travels outside a given region, which is how HappyFace was written. You may notice that it gets called in a couple other places to work around various interface problems apparently not anticipated when MultiFinder was developed. I recommend maintaining the cursor at every opportunity from the event loop, which is what later Apple documentation seems to suggest. This seems to spread less code around without effecting performance.

Main() calls the initialization functions and runs the event loop. It uses gameWasInProgress to detect when gGameInProgress changes, and mouseRgn to pass to WaitNextEvent(). It calls AdjustCursor() if a game starts or stops, because we do not want to show the mallet if a game is not in progress. When a game ends, it calls ShowScores().

Next, it calls IdleConn() to give time to the connection tool. If it finds that the connection has been severed, it stops any game in progress, because a game cannot be played with no connection. It calls IdleGame(), regardless of whether a game is currently in progress, to allow Game.c to handle its own details, including removing dead faces.

For each event returned by WaitNextEvent(), it first gives ConnEvent() an opportunity to handle it by passing it to the connection tool if appropriate. If ConnEvent() cannot handle the event, IdleConn() continues its attempt to dispatch the event. Any activate event is delegated to ConnActivate(). If an update event is for a window other than the game window, it is ignored, otherwise it is passed to UpdateGameWindow(). A keypress means nothing to HappyFace unless it is a command-key combination, which is passed to DoMenu().

The mouse events are handled in the usual way. HandleWindowClick() is called for any click in the game window's content region, if a game is in progress. This responds to the user striking a face. Suspend and resume events are trapped and passed to the connection tool through ConnResume().

HappyFace.rsrc

HappyFace.rsrc features the usual cast of characters. Star roles are filled, such as the ALRT and DITL resources used by ShowScores(), the PICT resources used to draw happy faces, and the menus used both by CTB.c and Main.c. Supporting characters are such as the SND resource that plays when a face is struck, SICN resources that spice up CTB menus, and the CURS resource used to show the hammer when faces can be struck. Atmosphere is provided by still other resources that provide icons and bundle-oriented information, version information, and the about box props.

With the exception of MBAR, MENU, PICT, SND and ALRT IDs the application source code is oblivious to the resource file's contents - not that I recommend ripping out DITL resources or doing anything else that would confuse the resource manager or the Finder.

Conclusion

What have we learned?

In this article, we explored a complete application using Apple's Communications Toolbox. We created a simple, yet entertaining game to exploit key features of the Connection Manager. Building on a previous article, we have learned to listen for a connection, poll for data, and handle interface-related concerns such as building and maintaining a connection menu and delegating the appropriate events to the connection tool. We found that most of the tasks of maintaining a connection can be hidden from the main program. We scratched the surface of creating an interactive game, though elements of a serious, error checking application have been omitted.

Where do we go from here?

The next step is to develop a formal protocol. Such a protocol would detect transmission errors such as messages that do not reach their destinations, arrive incomplete, or arrive garbled. Such an undertaking will be the subject of the next article.

If you have comments or questions regarding this article, feel free to send them!

References

The following is a list of publications used to produce HappyFace.

  • Chally - Chally, Mark. "DebugTerm: A Poor Man's Debugging Terminal." MacTech Magazine 12:10, October, 1996.
  • Inside CTB - Apple Computer, Inc. Inside Macintosh® Communications Toolbox. Addison Wesley, 1991.
  • Inside Mac Files - Apple Computer, Inc. Inside Macintosh® Files. Addison Wesley, 1992.
  • Mark - Mark, Dave. "Color Animation, Part II." MacTech Magazine 11:05, May, 1994.
  • Surfer - Alex Kazim. "Surfer" (Sample application program with Pascal source code) Essentials•Tools•Objects Vol 13. Apple Computer, 1989.
 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Capto 1.2.9 - $29.99
Capto (was Voila) is an easy-to-use app that takes capturing, recording, video and image editing to the next level. With an intelligent file manager and quick sharing options, Capto is perfect for... Read more
Opera 51.0.2830.40 - High-performance We...
Opera is a fast and secure browser trusted by millions of users. With the intuitive interface, Speed Dial and visual bookmarks for organizing favorite sites, news feature with fresh, relevant content... Read more
GarageSale 7.0.13 - Create outstanding e...
GarageSale is a slick, full-featured client application for the eBay online auction system. Create and manage your auctions with ease. With GarageSale, you can create, edit, track, and manage... Read more
1Password 6.8.7 - Powerful password mana...
1Password is a password manager that uniquely brings you both security and convenience. It is the only program that provides anti-phishing protection and goes beyond password management by adding Web... Read more
Evernote 7.0.1 - Create searchable notes...
Evernote allows you to easily capture information in any environment using whatever device or platform you find most convenient, and makes this information accessible and searchable at anytime, from... Read more
MacUpdate Desktop 6.2.0 - $20.00
MacUpdate Desktop brings seamless 1-click app installs and version updates to your Mac. With a free MacUpdate account and MacUpdate Desktop 6, Mac users can now install almost any Mac app on... Read more
HoudahSpot 4.3.5 - Advanced file-search...
HoudahSpot is a versatile desktop search tool. Use HoudahSpot to locate hard-to-find files and keep frequently used files within reach. HoudahSpot will immediately feel familiar. It works just the... Read more
EtreCheck 4.0.4 - For troubleshooting yo...
EtreCheck is an app that displays the important details of your system configuration and allow you to copy that information to the Clipboard. It is meant to be used with Apple Support Communities to... Read more
WhatsApp 0.2.8361 - Desktop client for W...
WhatsApp is the desktop client for WhatsApp Messenger, a cross-platform mobile messaging app which allows you to exchange messages without having to pay for SMS. WhatsApp Messenger is available for... Read more
iClock 4.2 - Customize your menubar cloc...
iClock is a menu-bar replacement for Apple's default clock but with 100x features. Have your Apple or Google calendar in the menubar. Have the day, date, and time in different fonts and colors in the... Read more

Latest Forum Discussions

See All

Disc Drivin' 2 Guide - Tips for the...
We're all still playing quite a bit of Disc Drivin' 2 over here at 148Apps, and we've gotten pretty good at it. Now that we've spent some more time with the game and unlocked more powerups, check out some of these more advanced tips: | Read more »
Alto's Odyssey Guide - How to Tackl...
Alto’s Odyssey is a completely stunning and serene runner, but it can also be a bit tricky. Check out these to try and keep your cool while playing this endless runner: Don’t focus too much on tasks [Read more] | Read more »
Here's everything you need to know...
Alto's Odyssey is a really, really good game. If you don't believe me, you should definitely check out our review by clicking this link right here. It takes the ideas from the original Alto's Adventure, then subtly builds on them, creating... | Read more »
Alto's Odyssey (Games)
Alto's Odyssey 1.0.1 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.1 (iTunes) Description: Just beyond the horizon sits a majestic desert, vast and unexplored. Join Alto and his friends and set off on an endless... | Read more »
Vainglory 5v5: Everything you need to kn...
Vainglory just got bigger. [Read more] | Read more »
Check out these 5 games that are a lot l...
So you're in love with Minecraft, but you're looking for something else to play as well? You've come to the right place then, because this list is all about games that are a bit like Minecraft. Some of them, more than others. [Read more] | Read more »
Our top 5 characters from casual RPG Cre...
Creature Quest definitely lives up to its name with a host of collectible creatures based on fantasy tales and world mythologies. To celebrate Creature Quest’s first birthday, we’re going to lay out what we think are the five best characters in the... | Read more »
Around the Empire: What have you missed...
Did you know that Steel Media has a whole swathe of other sites dedicated to all aspects of mobile gaming? Sure you'll get the very best iPhone news, reviews, and opinions right here at 148Apps, but we don't want you missing out on a single piece... | Read more »
All the best games on sale for iPhone an...
Oh hi there, and welcome to our round-up of the best games that are currently on sale for iPhone and iPad. You thought I didn't see you there, did you, skulking behind the bushes? Trust me though, the bushes aren't where the best deals are. The... | Read more »
The Battle of Polytopia Guide - How to H...
A new update just released for The Battle of Polytopia (formerly Super Tribes), which introduces online multiplayer. For all the fans of Midjiwan’s lite take on Civilization, this is certainly welcome news, but playing online isn’t as easy and... | Read more »

Price Scanner via MacPrices.net

Amazon restocks MacBook Pros with models avai...
Amazon has restocked 15″ and 13″ Apple MacBook Pros with models on sale for up to $251 off MSRP. Shipping is free. Note that stock of some Macs may come and go (and some sell out quickly), so check... Read more
Lowest price of the year: 15″ 2.8GHz Apple Ma...
Amazon has the 2017 Space Gray 15″ 2.8GHz MacBook Pro on sale today for $251 off MSRP. Shipping is free: – 15″ 2.8GHz Touch Bar MacBook Pro Space Gray (MPTR2LL/A): $2148, $251 off MSRP Their price is... Read more
Apple restocks full line of Certified Refurbi...
Apple has restocked a full line of Apple Certified Refurbished 2017 13″ MacBook Pros for $200-$300 off MSRP. A standard Apple one-year warranty is included with each MacBook, and shipping is free.... Read more
Lowest sale price available for 13″ 1.8GHz Ma...
Focus Camera has the 2017 13″ 1.8GHz/128GB Apple MacBook Air on sale today for $829 including free shipping. Their price is $170 off MSRP, and it’s the lowest price available for a current 13″... Read more
21-inch 2.3GHz iMac on sale for $999, $100 of...
B&H Photo has the 2017 21″ 2.3GHz iMac (MMQA2LL/A) in stock and on sale for $999 including free shipping plus NY & NJ tax only. Their price is $100 off MSRP. Read more
Apple refurbished Mac minis in stock again st...
Apple has restocked Certified Refurbished Mac minis starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: – 1.4GHz Mac mini: $419 $80 off MSRP – 2.6GHz Mac... Read more
Tuesday MacBook Deals: $250 off 15″ 2.9GHz Ma...
Adorama has the Silver 15″ 2.9GHz Apple MacBook Pro on sale today for $250 off MSRP. Shipping is free, and Adorama charges sales tax for residents in NY & NJ only: – 15″ 2.9GHz Silver MacBook Pro... Read more
Save up to $350 with these Apple Certified Re...
Apple has a full line of Certified Refurbished iMacs available for up to $350 off original MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are available: – 27... Read more
B&H offers $200 discount on Silver 15″ Ma...
B&H Photo has Silver 15″ Apple MacBook Pros on sale for $200 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 15″ 2.8GHz Touch Bar MacBook Pro Silver (... Read more
12″ Apple iPad Pro Sale of the Year! Models u...
B&H Photo has 12″ #iPad Pros on sale for up to $150 off MSRP. Shipping is free, and B&H charges sales tax in NY & NJ only: – 12″ 64GB WiFi iPad Pro: $719 $80 off MSRP – 12″ 256GB WiFi... Read more

Jobs Board

*Apple* Retail - Multiple Positions - Apple,...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Solutions Consultant - Apple (United...
# Apple Solutions Consultant Job Number: 113523441 Orange, CA, California, United States Posted: 21-Feb-2018 Weekly Hours: 40.00 **Job Summary** Are you passionate Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Sr. Experience Designer, Today at *Apple* -...
# Sr. Experience Designer, Today at Apple Job Number: 56495251 Santa Clara Valley, California, United States Posted: 18-Jan-2018 Weekly Hours: 40.00 **Job Summary** Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.