Running through Eclipse
From Gardenwiki
Purpose
These are some basic instructions for getting Eclipse set up for Game Gardens.
Setting up the Game Gardens Kit
Download the latest prebuilt Game Gardens Development Kit as described in the Reversi Tutorial.
Proceed through the Reversi Skeleton section, producing the source tree for a runnable (though not terribly exciting just yet) game.
Setting up a Workspace
Open Eclipse and create a new workspace in "gamegardens/games", where "gamegardens" is the directory in which you extracted GGDK archive:
Introducing Eclipse to Your Game
Select menu item "File->New->Project->Java Project from Existing Ant Buildfile":
Select your "gamegardens/games/reversi/build.xml" file.
Select the "compile [default]" target.
- Right-click the project name ("reversi") at the top of the Package Explorer view.
- Select "Properties".
- Select "Java Build Path" and choose the "Source" tab.
- Edit the "Default output folder:" entry at the bottom of the properties screen, setting it to "reversi/dist/classes".
- Select "Output folder" and set it to "Project's default output folder." (The Remove button will do this.)
- Now select the "Libraries" tab of the Properties editor.
- Remove the "gamegardens/games/reversi/dist/classes" entry (probably at the bottom of the list) by clicking it and then clicking the Remove button.
Your Package Explorer may have a Workspace link called "classes" listed now. You can delete it if you wish, it will not remove the actual "dist/classes" directory.
Eclipse Tips & Tricks
The basic setup is done. You can proceed with the regular tutorial from here. Below are some tips for taking advantage of Eclipse's fancy, newfangled Java programming support features.
Setting up a "Run Gendobj" External Tool
(tconkling Note: to get this to work using Eclipse 3.3.0 - the latest Eclipse at the time of writing (November 2, 2007) - I first had to right-click the build.xml file in the Project Explorer and choose "Run As->Ant Build". reversi build.xml didn't show up in my External Tools menu until I did this.)
- Select the arrow next to the "External Tools" button.
- Select "External Tools" from the menu. ("Open External Tools Dialog..." in Eclipse 3.3)
- Right-click "reversi build.xml" and select "Duplicate".
- Edit the "reversi.xml(1)" entry like so:
At the top:
- Change Name to "reversi build.xml [gendobj]".
In the Targets tab:
- Uncheck "compile".
- Check "gendobj".
- Click "Apply".
To add an entry at the top of the External Tools menu:
- Click the arrow next to "External Tools".
- Select "Organize Favorites".
- Select "Add".
- Select "reversi build.xml [gendobj]".
Now when you have changed a distributed object file, you can use "External Tools->reversi build.xml [gendobj]" instead of running ant from the command line.
Linking the Source and Javadocs
You can provide a link to the source and javadocs of a library, making it easy to check the purpose of a class or method. These instructions do so with the prebuilt source and document snapshots. The latest sources are available in a Subversion repository, but building the libraries and documentation from those is a bit complicated, and is not necessary for most users.
- Grab a snapshot of the narya source package.
- In the "gamegardens" directory (on systems with a GNUey shell environment):
% wget http://www.threerings.com/code/narya/narya-snapshot.zip % unzip narya-snapshot.zip
In the Eclipse Package Explorer:
- Right-click "narya-base.jar".
- Select "Properties" from the context menu.
- Select "Java Source Attachment".
- Select "External Folder".
- Enter (or browse to) the path "[base-dir]/gamegardens/narya/src/java", where [base-dir] is the directory in which you created "gamegardens".
- Return to the "narya-base.jar->Properties" screen.
- Now select "Javadoc Location".
- Enter (or browse to) the path "[base-dir]/gamegardens/narya/docs/api".
Repeat the process for "narya-distrib.jar".
The same process works for Nenya and Vilya:
% wget http://www.threerings.com/code/nenya/nenya-snapshot.zip ...
% wget http://www.threerings.com/code/vilya/vilya-snapshot.zip ...
You should now be able to open a browser window to Javadocs for classes defined in these libraries by selecting the class name in the source view and pressing Shift-F2. You can browse the library class's source by pressing F3. These hotkeys can, of course, be remapped to your taste.
You can add the Javadocs and sources for the Apache Commons and Samskivert libraries in the same way, but tracking down archives of the appropriate version of each is beyond the scope of this document.
It is also strongly recommended that you add the JDK documentation in the same way if you have not already done so.
Shuffling External Libraries Under the Rug
You can remove the (long) list of external libraries from the Package Explorer view by selecting "Package Explorer->Menu(this is a small downward-pointing triangle outline)->Filters" and checking "Libraries from external".
If you need to see them again later, uncheck it.
Setting Up a "Run-Server" Command
NOTE: This step is executed via the Ant task because the author didn't want to go into the details of fudging a toybox.properties file. It is handier to have a proper Run/Debug command, which may require a simple wrapper class, or there may be an Eclipse setting that will do the trick.
- Select the arrow next to the "External Tools" button.
- Select "External Tools" from the menu.
- Right-click "reversi build.xml" and select "Duplicate".
- Edit the "reversi build.xml (1)" thusly:
At the top:
- Change Name to "reversi build.xml [server]".
In the Main tab:
- Uncheck "Set an Input handler".
In the Targets tab:
- Uncheck "compile".
- Check "dist".
- Check "server".
- Ensure Target execution order is: dist, server
Click "Apply" and "Close".
Use "External Tools->Organize Favorites->Add" to add the command to the top of the External Tools list.
Setting Up a "Run-Client" Command
- Select menu item "Run->Run..."
- Create a new "Java Application" entry.
- Set "Main class" to "com.threerings.toybox.client.ToyBoxApp".
- Set "Program arguments" to "localhost 47624 ${string_prompt:User Name:laurel} secret"
- Set "VM arguments" to "-Dno_log_redir=true" (not pictured) so your client logs will go to an Eclipse console.
You can add an entry to the top of the Run menu with "Run->Organize Favorites".
Setting Up a "Run-View Test" Command
Create a Run command like before, but use "com.samskivert.reversi.ReversiBoardViewTest" for the Main class.
You can use Organize Favorites on the entry to put it at the top of the Run menu.
Adding Other Example Games
- Unzip the game archive in the "games" directory. Do a "Refresh" of the project within Eclipse so you can see the files within Eclipse. At this point you should have subfolders under games with the names "atlantis", "client". etc.
- Go into the properties for your "games" project to the Java Build Path section. Add all the jars from the "lib" directory: commons-beanutils, commons-collections, etc.
- Go under the source tab and add the various source directories: games/atlantis/src/java, games/sagashi/src/java, etc. I left the original "src" directory in the list, but it could be removed.
- Unless I've forgotten some essential step, you should be able to select Project on the menu bar, do a "clean" of "games" and have it come out with warnings only. If not, let me know what happened or what I forgot. To check that the compiles are really happening, in the Resource view, you should see a bin directory under the project with classes for the various games under it.
- Although we are not ready to run under Eclipse yet, it is a good idea to check that the files are loaded properly and in good shape. So try running one of the games, e.g. in one command window do:
cd yourEclipseDirectory\workspace\games\atlantis ant dist ant server
Watch for errors. If it goes well, it should say that the game server is running.
In another do:
cd yourEclipseDirectory\workspace\games\atlantis ant -Dusername=laurel client
If all is working well, you should now be ready to set up a table for the game. Try it and check that it works. Then shut it down for now, but remember the procedure above to recompile and start the server.
- At this point, I made a copy of the "sample" game directory and files, tediously changed all the references of "sample" to my game name, added my source directory to the project sources and kept doing necessary editing until the project under my game name ran just like the sample game. Of course, you could avoid a lot of this difficulty by just editing the sample game, but I didn't know how much trouble it would be to change the game name from "sample" at the end.
- At this point, my game was still essentially the sample game structure with a new name. (Figuring out how to set up a game within the server/client structure is a whole different topic which I am just beginning to learn.) I wanted to set it up to debug the client within Eclipse, so I set up a Java application Debug Configuration like this:
Under the Main tab: Set project ot "games" and "Main class" to com.threerings.toybox.client.ToyBoxApp
Under the Arguments tab: set Program arguments to "localhost 47624 Laurel secret"
- Create a toybox.properties file in the "games" folder with these contents:
resource_dir=dist resource_url=file://dist
Note that there are only two slashes in the last line. There are some references to the above that show three slashes, but I believe that two slashes is correct.
- After completing the above process, you should have a gamename/rsrc/i18n folder with containing a gamename.properties file. Copy this folder structure to the "bin" folder under "games" (substituting your own names appropriately). You will need to do this everytime a file within that structure changes, so it would be wise to make an Eclipse "builder" within your "games" project to do the update automatically during each build. This would be an "Ant Build" configuration type. This Ant file is not particularly elegant or foolproof,.but here it is:
<project name="gamename" default="copy" basedir="."> <target name="copy"> <copy todir="bin"> <fileset dir="gamename" includes="rsrc/**"/> </copy> </target> </project>
- Then add a builder step within your project properties to be executed last with these values:
- Name: CopyGamenameRsrc
- Under Main tab: Buildfile: ${workspace_loc:/games/copyGamenameRsrc.xml} Base Directory: {workspace_loc:/games}
- Under Refresh: Check "Refresh resources upon completion." and "The project containing the selected resource"
- Under Targets: Consider making Auto Build look like Manual Build, unless you want to be responsible for remembering to manually **build after a project property change.
In any event, check to make sure that you do have an appropriate bin/rsrc/i18n/gamename.properties file after this process. Otherwise, when your game displays its table options, you will see control names starting with "m." instead of the desired names.
- Test that this all works by compiling and starting the server as indicated above and then starting a client using the debug configuration you set up above. If everything works, you will get a client that looks exactly like the one you saw when you used ant -Dusername=laurel client If not, check your steps. It's also possible that I forgot something that I did. Be careful that the server actually starts and is not cut off by having its bind address be already in use. If this happens, you will either have to carefully use the Task Manager to remove it or else restart the computer.
- When the above has been tested, set a breakpoint within some client code that will be executed, such as instantiating the panel, and then repeat the last step to see whether it stops at your breakpoint and can continue.
