WIXLIB

1232ch01final.qxd2/27/0411:44 AMPage 6Chapter 1One of the reasons that I like to collect the extension JAR files in this directory instead of simply using them where they were installed originally is that itmakes for a more readable classpath. I would rather use a short argument suchas J:\ext\javaws.jar instead of a long one such as C:\Program Files\Java WebStart\javaws.jar. Also, sometimes space characters in a directory name such asProgram Files confuse applications that use it in the classpath.Finally, and probably most importantly, is that it consolidates all of yourextension libraries for your project where it is easy to put them under versioncontrol. It seems a bit odd to put a third-party binary file under version controlwhen you can usually just download another copy from the third-party web sitewhenever you need it. This is unreliable, however, as there might be dependencies in the code that require you to use an older version of a library that is nolonger distributed from the vendor site. When your ext/ directory is under version control, you have a snapshot of the versions of all the different extensionlibraries that are known to work reliably with your project. It also makes it easieron your fellow developers, including you if you ever need to move to anotherdevelopment machine. You can pull the JAR files from the version control systeminstead of downloading them all over again from multiple vendor web sites.Directory libThe lib/ directory is the destination directory for your compiled Java classes:The files that end with the .class file name extension. This is the -classpathargument to your javac compile command and the -cp argument to the javaexecution command.The abbreviation lib stands for library. Keep in mind, however, that thisdirectory is only for the compiled counterparts to the source code files in thesrc/ directory. You should keep your third-party libraries in a different directorysuch as ext/ as you want to be able to flush the lib/ directory to get rid of outdated versions of the compiled classes without fear that you will be deletingsomething hard to replace. Because all the files in the lib/ directory are derivedfrom the src/ directory, there is no reason to place them under version control.Directory licThe lic/ directory contains copies of the Open Source software licenses. This isdescribed in more detail later in this chapter.6

1232ch01final.qxd2/27/0411:44 AMPage 7Development SetupDirectory resYou use the res/ directory to keep the resource files you need to complete yourbuild separate from the Java source code files. It includes JAR manifests, WARconfiguration files, multimedia resources such as audio and graphics, and staticdata files.Each source code file has an appropriate position within the src/ directoryhierarchy based upon its package prefix. This is not true with other types of filesused in the build. Rather than putting those files in the src/ root directory orsomewhere below, such as a directory that corresponds to the package that contains the main class for the application, I just keep them in a separate directoryaltogether, the res/ directory.Directory srcThe src/ directory contains the uncompiled Java source code: the files with the.java file name extension. This is also a place for your Hypertext MarkupLanguage (HTML) javadoc descriptions. The javadoc utility looks for the filepackage.html in each directory in the source path and assumes it contains adescription of the classes in the package that corresponds to the directory level.Directory tmpThe tmp/ directory is created during the build process to hold working files temporarily. The directory is usually destroyed when the build ends. If your build isinterrupted due to a compile error, this directory might not get removed. It doesnot hurt to leave this directory in existence if you find it, as the next successfulbuild first deletes it automatically, creates it anew, then deletes it again. If you dodecide to delete it manually, the only restriction is that you do not do it while abuild is running.Introducing XMLTo build, package, and deploy your games, you need to understand the basics ofExtensible Markup Language (XML). XML is also useful for storing game dataand user preferences on the hard drive and passing multi-player messages overthe network. This section introduces XML briefly.XML allows you to describe data using human-readable text. In the following example, note how each data value is encapsulated in an opening andclosing element tag pair that names the data field.7

1232ch01final.qxd2/27/0411:44 AMPage 8Chapter 1 book title Advanced Java Game Programming /title author David Wallace Croft /author publisher Apress /publisher pubdate 2004 /pubdate /book Those familiar with HTML will recognize the similarities. It looks like HTMLexcept that I have created my own element names such as book and title. HTMLalready defines the element title, but here I have given it a new semantic, ormeaning, that differs within the context of my book definition. Indeed, this abilityto define new elements is why XML is considered “extensible.”Despite the flexibility in being able to define new element names, there areenough constraints in the XML format that parsers do not need to be customizeduniquely for each definition. Such restrictions include a strict hierarchical nestingof elements. For example, the following XML syntax with overlapping tag boundaries would generate a parsing error. b i Illegal XML /b /i Although the preceding code might be valid in HTML, the proper way tonest the elements in Extensible Hypertext Markup Language (XHTML)—a definition of XML that replaces HTML—would be as follows. i b Legal XML /b /i Hundreds, perhaps thousands, of XML definitions now cover everythingfrom genealogy to electronic commerce. Wherever data needs to be exchangedin a transparent manner using standard parsers that are readily available in allthe major programming languages, XML provides a solution.Further information on the subject of XML is easily accessible from a largenumber of sources as XML has rapidly become a widely adopted technology. Asa quickly digestible introduction and handy reference book, I recommend theXML Pocket Reference, 2nd edition by Robert Eckstein (O’Reilly & Associates,2001).Compiling with AntAnt is the Open Source tool that you will use for compiling the example gamesource code. Ant is more powerful than older tools such as make as it is extensibleand cross-platform. Although some warn against it, you might want to considerusing Ant as a universal scripting language to replace your platform-specific8

1232ch01final.qxd2/27/0411:44 AMPage 9Development Setupbatch or script files. If it lacks a function you need, Ant happily allows you tointegrate any Java code you want to write to increase its capabilities.Ant is distributed from the Apache Jakarta Project web site and has gainedrapid and almost universal acceptance by the Java community. If you have notalready learned how to use Ant, you should consider doing so. You can start byreading the online documentation at http://ant.apache.org/. project name "myproject" default "compile" target name "compile" [.] /target target name "archive" depends "compile" [.] /target /project Ant takes its instructions on how to compile the source code from an XMLbuild file with a default name of build.xml. A build file is organized as a projectwith multiple targets. Each target contains zero or more tasks that are the commands executed by the Ant processor.The tasks in a target are usually related in a set that might depend upon thesuccessful completion of one or more previous targets. For example, I mighthave a target called archive that archives the latest version of my source codeand moves it to a backup directory. The archive target might depend uponanother target called compile that attempts to compile the entire library. If I runAnt on my project build file with the target archive specified as a command-lineargument, Ant first attempts to run the compile target. If that step fails, it terminates operations without proceeding to archive.You can compile and run most of the example game source code by runningAnt on the build.xml file in the library root directory using the default target. Thefollowing is a line-by-line review of the first part of the file that you use to buildthe main demonstration program. This is the build code that you could adapt tocompile and package your own games. project name "croftsoft" default "demo" If this build file is executed without specifying a target as a command-lineargument, Ant assumes the default demo target. property name "arc dir" value "arc"/ property name "res dir" value "res"/ property name "src dir" value "src"/ property name "tmp dir" value "tmp"/ 9

1232ch01final.qxd2/27/0411:44 AMPage 10Chapter 1To prevent the directory names from being hard-coded in the rest of thebuild file, define them here using property variables. Once a property value isdefined, it cannot be redefined later in the build file. You might need to adjustthese directory names to match your own preference. target name "init" mkdirdir " {arc dir}"/ delete dir " {tmp dir}"/ mkdirdir " {tmp dir}"/ tstamp format property "TODAY ISO" pattern "yyyy-MM-dd"/ format property "YEAR"pattern "yyyy"/ /tstamp /target The default target demo indirectly depends on target init so I will review theinit target first. It starts by creating the output and temporary working directories. If the output directory arc dir already exists, the build file presses onwithout throwing an error. The temporary directory is re-created to make sureno old files are left behind from a previous build attempt.Task tstamp sets a property called TODAY ISO to a value representing thecurrent date in International Standards Organization (ISO) format such as1999-12-31. Some of the following targets use this property to append thedate to archive file names. target name "shooter prep" depends "init" copy todir " {tmp dir}/media/shooter" fileset dir " {res dir}/apps/shooter/media" include name "shooter bang.png"/ include name "shooter boom.png"/ include name "shooter rest.png"/ include name "bang.wav"/ include name "explode.wav"/ /fileset /copy /target In preparation for compiling the demo, the resource files for a game arecopied from the resource directory to the temporary working directory. The preceding code demonstrates a variant of the copy command that uses a fileset.Rather than issue a separate copy command for each file, you use the fileset tagto copy all the files to the temporary working directory in a single command. Youcan also use wildcards and pattern matching to describe the files to include in a10

1232ch01final.qxd2/27/0411:44 AMPage 11Development Setupfileset. I like to specify the files individually by name so that I know exactlywhat is being packaged. target name "collection prep1"depends "basics prep,dodger prep,fraction prep,mars prep"/ target name "collection prep2"depends "road prep,shooter prep,sprite prep,tile prep,zombie prep"/ target name "collection prepare"depends "collection prep1,collection prep2" copy file " {res dir}/apps/images/croftsoft.png"todir " {tmp dir}/images"/ /target Target collection prepare depends on collection prep1 and collection prep2.I break it up this way so that the depends tag value does not run too long. The purpose of collection prepare is to copy all the resource files for the individual gamesthat go into the CroftSoft Collection into the temporary working directory. It alsocopies any additional resource files, such as croftsoft.png, which you use for theframe icon. target name "collection compile" depends "collection prepare" javac srcdir " {src dir}" destdir " {tmp dir}" includename .java"/ include name "com/croftsoft/ajgp/basics/BasicsExample.java"/ [.] include name "com/croftsoft/apps/zombie/Zombie.java"/ /javac /target You use the javac task to compile the source code in the src dir directoryand output the compiled class files to tmp dir. Normally you would only need toinclude the main class and javac would be smart enough to compile all the otherclasses that are required. In this case, however, the individual game applets arelinked dynamically instead of statically and you must also name them explicitly.This is described further in the next chapter.11

1232ch01final.qxd2/27/0411:44 AMPage 12Chapter 1 target name "collection jar" depends "collection compile" echofile "manifest.txt" message "Main-Class: com.croftsoft.apps.collection.CroftSoftCollection" / jarbasedir " {tmp dir}"destfile " {arc dir}/collection.jar"manifest "manifest.txt"update "false"/ delete file "manifest.txt"/ delete dir " {tmp dir}"/ /target target name "demo" depends "collection jar" java fork "true" jar " {arc dir}/collection.jar"/ /target If the collection compile target compiles successfully, the collection jartarget executes. The collection jar target packages the temporary workingdirectory contents, which include compiled code and resource files. It overwritesthe old JAR file if it exists in the output arc dir directory. When completed, thetemporary directory is deleted and the newly created executable JAR is launchedin a separate Java Virtual Machine (JVM) for testing.The rest of the build file contains additional targets that compile demonstrations and examples that require optional packages beyond what the core J2SElibrary includes. A quick review of the comments embedded in the build file willtell you what optional packages are required to compile and run some of theadditional example games not included in the default demo target. You can safelyignore these other targets for now as I will cover them in later chapters of thebook.ant basicsIf Ant is properly installed, you should simply be able to enter the commandant in the directory containing the build.xml file and the default demo target willcompile and launch. If you want to specify a different target, you simply provideit as a command-line argument as shown in the preceding code. Target basics,for example, builds and launches an example game described at the end of thischapter. If you have not already done so, go ahead and build and run the demousing Ant and the example build file.12

1232ch01final.qxd2/27/0411:44 AMPage 13Development SetupUsing Open SourceHopefully by this point you have been able to compile and run the demonstration program successfully and are now ready to learn how to modify andincorporate the code library as described in the book to create your own games.Before you get too invested in the library, however, you should know the usagelimitations and requirements.Learning the Basics of CopyrightCopyright used to be a mystery to me until I did a little reading on the subject.Here are a few key basics I think every developer should know. You do not need to put a copyright statement on your work nor file paperwork for it to be copyrighted. It is copyrighted automatically by the simpleact of creation. Putting the copyright statement on your work and registering your copyright does help you when it comes to receiving damageawards for copyright infringement. You no longer need to append “All rights reserved” to your copyright statement. The law changed and it is now assumed. If you are an employee, your employer is the copyright holder of worksyou create on the job by default. If you are an independent contractor, youare the copyright holder by default unless your contract states otherwise.Your contract almost always states otherwise unless you drafted the contract yourself. If you create a work with someone else, then you both own the copyrightjointly unless an agreement states otherwise. Use and distributionrequires unanimous consent and you must share profits from such a work. It is possible to create a contract where the work is owned jointly withoutaccountability. In this case, each copyright holder can use the work without accounting to the other. It is as though they each own the copyrightindependently and do not need to share profits or seek mutual permission. This might be a useful arrangement if you are teaming with others tocreate a game for your portfolio instead of for profit. A copyright holder has the exclusive right to use, distribute, and modifythe work. If you create a work that incorporates a work by someone else,either in whole or in part, you have created a derivative work. You musthave the permission of the copyright holder of the original work in orderto create a derivative work legally.13

1232ch01final.qxd2/27/0411:44 AMPage 14Chapter 1 Copyright law makes an exception for fair use of a work. This means thatunder certain circumstances you can use a work without the permissionof the copyright holder. This is limited to just a few enumerated uses suchas parody, teaching, critical review, and news. There are land mines in theFair Use doctrine so beware. In general, you should not rely upon Fair Useto incorporate material into your game. Works created by the government are not entitled to copyright. This iswhy the space pictures taken by NASA are in the Public Domain. If youare creating a science fiction game that requires images of stars, planets,space shuttles, rockets, and astronauts, you are in luck. See http://gimpsavvy.com/PHOTO-ARCHIVE/ for a collection of Public Domain space photosyou can use in your games. A license is a grant of permission by a copyright holder to use a work.Licenses come in all shapes and sizes. Some are exclusive, meaning thatthe licensee is the only one who can use the work, and some are nonexclusive, meaning that many can use the work simultaneously. If yougrant an exclusive license to your game to someone for a limited time, youretain the copyright but you cannot allow someone else to use the gameduring that period. A common misperception is that if something is on the Web and it doesnot have a copyright statement on it, it is in the Public Domain and can beused without permission and without attribution. This is simply wrong

to create your own games using the game library and examples described in this book. Upgrading to 1.4 To compile and run the example games in this book, you need to download and install the Java 2 Software Development Kit (SDK), Standard Edition (J2SE), ver-sion 1.4 or later. “Java 2” refers to the Java