Amazon Honor System Click Here to Pay Learn More

by Forest J. Handford

In this chapter we will show how to add DirectSetup and AutoPlay to our Space Adventure.  We will also go over how to launch a game from Microsoft's Gaming Zone and other semi-final touches.

Reckoning with the Dead
When we added DirectPlay to Space Adventure we also added dead reckoning.  Dead reckoning may sound like a 3d shooter game but it's actually a navigational system invented by sailors.  When traveling across the ocean, before GPS, it was very tough to find out where a ship was.  If a ship kept the same velocity since the last time they had checked where they were a ship crew could calculate their new position with vector math.  I won't go into the formulas but you should look at the ApplyDelta function to see how we found the location of remote players that hadn't sent a position recently.

The PC may never be as easy to play games on as a dedicated system that you just throw a cartridge into but with your setup program and AutoPlay you can get some of the ease.  AutoPlay is what causes the setup program on a game, like StarCraft, to automatically execute when the game's CD is inserted into the CD-ROM.  AutoPlay can be disabled in a user's registry and doesn't exist on Windows 3.x or Windows NT before the 4.0 version so don't expect it will run.  AutoPlay usually only runs on CD-ROM's but can also run on disk drives, remote drives, fixed drives, and even a RAM disk.

To qualify for Microsoft's Windows 95 logo program you need to use AutoPlay.  So if you want that silly logo that says your program in Window's 95 compatible you must do this.

To use AutoPlay you must create a text file in the root directory of your disk or CD-ROM called AUTORUN.INF .  In this text file the top line should have the following:

The program automatically executed by AutoPlay is defined with the following line:
open=game.exe    /AUTOPLAY

You can have the CD icon changed to a bitmap, executable's icon or icon file as follows:

You can add to the CD's context menu, the menu from left-clicking, shell commands as follows:
shell\readme\command=notepad readme.txt
shell\readme=View ReadMe File
shell\install\command=setup.exe /INSTALL
shell\install=Install Game

If we placed Space Adventure on a CD with the readme.txt and setup.exe files in the root directory our AUTORUN.INF file would be as follows:
open=setup.exe    /AUTOPLAY
shell\readme\command=notepad readme.txt
shell\readme=View ReadMe File
shell\install\command=setup.exe /INSTALL
shell\install=Install Space Adventure

Our Setup Program
We need some specific features for our setup program.  A good DirectX setup program should do the following, install DirectX if the user doesn't have DirectX, copy our game files to the hard disk, and make any needed registry entries.

All DirectSetup applications should come with the DSetup.dll , DSetup16.dll and DSetup32.dll .  These files contain definitions for DirectSetup functions.

Any developer can freely install DirectX with the files that Microsoft provides.  Currently our site doesn't provide this ability because the minimum amount of required files needs 15 MB.  Our website only currently has 30 MB so we can't use that much for this program.  If the user does get the files and puts them in a directX subdirectory of where the setup program is than DirectX 5 can be installed.  All DirectX developers selling full-ware games SHOULD allow the user to install DirectX with their setup program.

To install DirectX you can must call the following:
int WINAPI DirectXSetup(HWND hWnd,    // The parent window
        LPSTR lpszRootPath,    // A pointer to the string that defines the root of the
                               // DirectX setup files or NULL
        DWORD dwFlags);   // DSETUP_DIRECTX to install all drivers and components
                          // DSETUP_TESTINSTALL the default, install nothing but test setup
                          // DSETUP_DXCORE install components but no drivers
                          // DSETUP_DSOUNDDRV install sound drivers only
                          // DSETUP_DDRAWDRW install display drivers only

If you use the above function it will do all the work for you and may return any of the following flags:

Flag Description
DSETUPERR_SUCCESS Yeah, success and no reboot required
DSETUPERR_SUCCESS_RESTART Success but a reboot is needed
DSETUPERR_OUTOFDISKSPACE The client needs more disk space
DSETUPERR_UNKNOWNOS Unsupported operating system
DSETUPERR_USERHITCANCEL The user canceled the installation

Using the setup above is fine but the DirectX installer window may not coincide with the environment you want your player to experience.  Before calling DirectXSetup you can call the following:
INT WINAPI DirectXSetupSetCallback(DSETUP_CALLBACK CallBack);    // A pointer to your
                                                                 // callback function

If you use the DirectXSetupSetCallback function you must provide a callback function.  The callback function should interact with the user according to why it was called.  Here is it's prototype:
DWORD DirectXSetupCallbackFunction(DWORD Reason,  // DSETUP_CB_MSG_NOMESSAGE no message
                // DSETUP_CB_MSG_BEGIN_INSTALL the install is starting
                // DSETUP_CB_MSG_BEGIN_INSTALL_RUNTIME runtime components are being installed
                // DSETUP_CB_MSG_BEGIN_INSTALL_DRIVERS drivers are being installed
                // DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE the driver in info is being upgraded
        DWORD MsgType,    // The type of message box to display the message
        LPSTR szMessage,  // The text for the message box
        void *pInfo);     // A pointer to the upgrade info

The Upgrade info is stored in type MSG_CB_UPGRADEINFO ..  The type is made up of a DWORD flag called UpgradeFlags .  Below is a table of the possible flags:

Flag Description
DSETUP_CB_UPGRADE_FORCE The upgrade must be performed for DirectX to run reliably
DSETUP_CB_UPGRADE_KEEP An unnecessary upgrade or one that would HURT the system
DSETUP_CB_UPGRADE_SAFE The driver is ok to be used and will be installed
DSETUP_CB_UPGRADE_UNKNOWN The driver won't be replaced unless the user wants it to be
DSETUP_CB_UPGRADE_HASWARNINGS The upgrade is not recommended because of possible effects to other programs
DSETUP_CB_UPGRADE_DEVICE_CANTBACKUP The driver cannot be backed up before it is replaced and therefore will be un restorable 
DSETUP_CB_UPGRADE_DEVICE_ACTIVE The driver is currently in use and therefore cannot be replaced
DSETUP_CB_UPGRADE_DEVICE_DISPLAY The driver is a display driver
DSETUP_CB_UPGRADE_DEVICE_MEDIA The driver is a media driver

You can return TRUE to allow the setup to do what it was asking to do or FALSE if you don't want it to be done.  You do not even have to tell the user what is going on but it is best to either have them fully aware or do the least harmful installation.  This decision may be decided by your target audience.  Is your audience children under ten that wouldn't know how to answer the questions or is it for pro computer users who could teach about computers?

Games can be launched by other applications using registry entries.  Third party software vendors and web sites, like Microsoft's gaming zone, provide a way to gather people around the world in a lobby environment that can launch your game.  To allow this feature you will need your setup program to make an entry in the registry.  DirectSetup can add a DirectPlay game to the registry with the following function:
int WINAPI DirectXRegisterApplication(HWND hWnd,    // The window
        LPDIRECTXREGISTERAPP lpDXRegApp);    // The address of a DIRECTXREGISTERAPP structure

The following is a table of the DIRECTXREGISTERAPP structure:

Member Description
DWORD dwSize The size of the structure
DWORD dwFlags Unused
LPSTR lpszApplication A pointer to a string that contains the games name
LPGUID lpGUID A pointer to the applications GUID
LPSTR lpszFilename A pointer to a sting holding the name of the executable
LPSTR lpszCommandLine A pointer to a string filled with any arguments to pass to the executable
LPSTR lpszPath A pointer to a string filled with the path for the executable
LPSTR lpszCurrentDirectory A pointer to a string that holds a path that will be the current directory for the game, this is usually the same as lpszPath

 Now let's look at how to play our game in the Zone.  Here is a picture from a Zone lobby:

Here is a screen shot of how you choose what game to launch:

Here is a screen shot of Joe and I before we battle to the death:

The Attack of Mutex!
Mutex may sound like something out of a cartoon or comic book but it is actually a computer science technique.  In some instances you don't want your program to be launched more than once, because it may hog a ton of resources, or for other reasons.  If you have a game on a CD and during the game ask the user to insert the CD you don't want the AutoPlay to start the installer on the CD so you use a Mutex.  A Mutex is a way to prevent more than one of the same application from running.  Here's the code you need for a Mutex in the beginning of your WinMain:
HANDLE hMutex; // The Mutex handle
hMutex = CreateMutex( NULL, FALSE, "There can be only one" ); // Create a Mutex

// Check for Mutex, if there is one close silently
if ( ( hMutex == NULL ) || ( GetLastError() == ERROR_ALREADY_EXISTS ) )
    CloseHandle( hMutex );
    return FALSE;

Before you leave the application use the following to close the Mutex:
CloseHandle( hMutex ); // Close the Mutex

You can place this code in any applications you create so they don't interfere with others.  For now we will just have it in the setup.

The Sample
To find out how to copy files and to create short-cuts view the sample.  These are great ways to allow the user to use your game with ease.  Now here's the entire project including the setup program:

< Files >

That may be it for this section.  I want to do a Direct3D section and add to this game.  The additions to the game will only take one chapter.  I'm also planning on cleaning up all of the chapters.


Amazon Honor System Click Here to Pay Learn More