Hi. This is a project for fun and learning.
Perhaps it can be a full used project one day. No promises.
The intention is presents how to create a game aid to help game masters and players to play GURPS online. It will start in a desktop environment like a very simple project and I will add stuffs while it evolve. Like any open source free software any one can contribute, my GitHub link to the current source is in here.
Well the project will try to follow this:
- start simple and keep it simple as long as possible;
- it will use java once any computer have a java virtual machine installed and will function both in Linux, Windows and Mac;
- it will start on desktops, mobile will come one day;
- it will use JFace/SWT UI toolkits for user interfaces, this is used by the Eclipse Project and others;
- it will be a maven project for the sakes of my sanity.
The plan
The plan is to make from scratch a project able to help people play online. I aware of folks using a lot of technologies to play on-line from simple chats on GTalk, passing from Skype to MapTools. But I like to create one and no of this projects is dedicated to GURPS. The second purpose is presenting a tutorial for programmers learn JFace, SWT, java, maven, Eclipse and related topics.
But what will a minimal table top game aid needs? Will, the answer is not easy to point, but IMHO an on-line game aid needs a interface able to connect a group of persons. In the present days this both can be done by text chat and streaming with voice and text. Obviously a program capable of such thing exists a while, the best example is Skype and the Google tools if you is web based inclined. So a good game aid also can help people to do stuffs they done when playing in front of table, roll dices, check tables, find modifiers, etc. A full GURPS rule manager is out of scope for our little project right? So let start it small and add a feature each time.
- First we will create the very basic bare bone project, which will be cover in this part 1 post.
- Then we will create a minimal chat interface while implements a basic communication protocol.
- Then we will add a dice rolling feature, implementing the core GURPS rolls.
- Then we will add a multimedia interface to use both camera and voice based communication.
For a start it will suffice. In future I will add more stuffs 😉
The project
For the project I will use Eclipse. I assuming the reader is familiar with the tool, but will show some few steps to achieve the final result. I using the last Juno version on the present date with only the minimal Java bundle.
Starting setup
Well, the first step of all is to create the local repository. Open the Git Repositories view and copy and past the GitHub link on it (in this case my project is located in git@github.com:giganerds/EpicMaker.git).
Just do the next-next-finish approach once Eclipse fill the initial form for you and choose reasonable defaults in the rest of the wizard. You end up with the repository created but not initialized.
Well now we can start the project bare bone. Java dependency could become a hell, and to not start to hit the wall (heads first) we will use maven to help us. Juno’s maven integration is beautiful, just press CTRL+3 to open the shortcut aid and type “new maven project” probably you will use auto complete resource and press enter before type the entire phrase :). Pressing ENTER will raise the maven wizard. Check the first field… wait!!! No maven archetype?! Yes, no we will start with a simple bare bone project because a maven artifact for this does not exists (well, a suffice recent one at least). Trust me we will not need it right now.
Now lets fill the Artifact form for our project. I will start it with my custom group id (once I have this domain), and a 0.0.0 version which I will bump as need. If you following this on your desktop stay free to fill with what you feel pleasant. My project will be named ‘Epic Maker‘, am I felling poetic today? 😛
After finish press Finish (I know… bad pun!)
With the maven project staying lazy on Package Explorer is time to put it on our repository. Right-click it and choose Team → Share Project. On the wizard dialog choose Git and press Next.
Choose the previous git repo on Repository field and Finish him (Oh no other bad pun! Well, get used :D).
Nice! You already can commit the results, to do so Right-click otherwise the project choose Team → Commit or the repository and Commit. I will not make anyone decide when and what to commit but will make some suggestions mainly about branching, also the commit messages is your take.
TIP! I like to change between the Eclipse’s views with shortcuts, CTRL+F7 allow change between them in a ALT TAB fashion. Once over the repository on Git Repository view press CTRL+# to open the commit screen. Didn’t you love keyboard shortcuts? 🙂
Licenses and copyrights
Licensing your software is very important! Lets put some files on the source before continue. Create a licenses folder for organization. To let it simple I will put initially two licenses on the project, the source code free licensing GPL v3 and the Steve Jackson Game Online Policy for game aids. The first one is simply a save from http://www.gnu.org/licenses/gpl-3.0.txt. I also have in my eclipse a header put in the header of any coded file I created like this:
/*  *     This program is free software; you can redistribute it and/or modify  *     it under the terms of the GNU General Public License as published by  *     the Free Software Foundation; either version 3 of the License, or  *     (at your option) any later version.  *  *     This program is distributed in the hope that it will be useful,  *     but WITHOUT ANY WARRANTY; without even the implied warranty of  *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the  *     GNU General Public License for more details.  *  *     You should have received a copy of the GNU General Public License  *     along with this program; if not, write to the Free Software  *     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
You can put it on your Eclipse too. It’s a good practice. Choose menu Windows → Preferences→ Java→ Code Templates. Open Comments on the left panel and click on Files and then on Edit button.
The Steve Jackson Game Online Policy licensing is a complete different beast. You can read it from here and it take cares of the intellectual property from Steve Jackson Games, GURPS included. When you create a game aid for GURPS you need to include this license on it. For while we will save this on a text file to the source code. In later posts we will make an about dialog with it too. Just be sure to put this on a file substituting the appropriate fields, and pay attention which text files does not respect links and put the URL in a proper way.
[GAME NAME] is a trademark of Steve Jackson Games, and its rules and art are copyrighted by Steve Jackson Games. All rights are reserved by Steve Jackson Games. This game aid is the original creation of [YOUR NAME] and is released for free distribution, and not for resale, under the permissions granted in the <a href="http://www.sjgames.com/general/online_policy.html">Steve Jackson Games Online Policy</a>.
This will both protect you from legal acts and also make sure Steve Jackson rights will be preserved. It also make the world better once you distribute it like a free software ;).
Dependencies and repositories
Now its time to add to the maven pom a few useful libraries. The first two are JUnit and SLF4J. Well rounded java developers known this couple very well. JUnit is the unit test library for Java and SLF4J is a facade implementation for logging. I love both and any serious programmers will love it (or similar projects).
TIP! Before go ahead I recommend to configure your maven to download the source code or at least the javadoc for the dependencies. Your life will be easier once Eclipse recognize parameters names and show help when hovering your mouse over a class or method. Go on Eclipse preferences and set it like the picture bellow (checking as you wish the Download Artifact Sources/JavaDoc) .
Open the you pom project file and access the Dependency tab. Click in the Add button and fill the form like the figure (pay attention on Scope field, it must be test for JUnit, allowing use it only on unit tests).
For SLF4J its similar, but with Scope compile. Note I point to Log4j module, once it will make the heavy duty (logging actually) under the hood. SLF4J is just a wrapper for any log API.
Now the JFace part. JFace is a API to handle commons tasks when dealing with user interfaces. It function over SWT without hidden it. SWT, by itself, is a API to create desktop user interfaces using Java. Like mentioned both is used in Eclipse Project. We will not go for a full flagged OSGI project (who knows… one day) and will stick on a simple JFace interface. Trust me, it is very handful and will suffice for our original purpose. To integrate JFace with maven I found this and this on a Google Fu day (thank your Sonatyne, you saved my life). So we need to add the following text directly on the pom.xml source.
... Â Â Â <repositories> Â Â Â Â Â Â Â <repository> Â Â Â Â Â Â Â Â Â Â Â <id>swt-repo</id> Â Â Â Â Â Â Â Â Â Â Â <url>https://swt-repo.googlecode.com/svn/repo/</url> Â Â Â Â Â Â Â </repository> Â Â Â </repositories> Â Â Â <dependencies> ... Â Â Â Â Â Â Â <dependency>Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â <groupId>org.eclipse.swt</groupId>Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â <artifactId>org.eclipse.swt.gtk.linux.x86_64</artifactId>Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â <version>3.8</version>Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â </dependency>Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â <dependency>Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â <groupId>org.eclipse.ui</groupId>Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â <artifactId>org.eclipse.ui.workbench</artifactId>Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â <version>3.103.0.v20120530-1824</version>Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â </dependency>Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â </dependencies> ...
Pay attention to not destroy your preselected dependencies! Its does not have the latest version of SWT and JFace, but has a recent one (the official JFace/SWT repo have a “dinosauric” version not very suitable). When you save all this modifications maven will take care to download all jars, sources and docs.
Final adjustments
For the final steps lets make a defaults log4j.xml file for logging, set the default Java to version 1.7 and create a suitable Readme.md.
Create the following log4j.xml file inside src/main/resources and src/test/resources source folders.It will take care of logging about anything showing both class name and respective method which call the log.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration>
   <appender name="CONSOLE">
       <param name="Target" value="System.out" />
       <param name="Threshold" value="TRACE" />
       <layout>
           <param name="ConversionPattern" value="%d{ABSOLUTE} %-5p %t [%C{1}.%M(%F:%L)] %m%n" />
       </layout>
   </appender>
   <root>
       <priority value="TRACE" />
       <appender-ref ref="CONSOLE" />
   </root>
</log4j:configuration>
Note that it is configured to be very verbose for now (TRACE is enabled) but it will be undesirable when the final production version is out. This minimal file will be improved in the future.
You must noted the java project may have a warning (depending if you have or not java 5 on your machine) and it trying to use the Java 1.5 JRE of your system.
To make our maven project use java 1.7 we need to put a single piece of code on the pom.xml to force the compiler plugin to accept and use correct JRE and JDK.
   <build>        <plugins>            <plugin>                <artifactId>maven-compiler-plugin</artifactId>                <version>2.3.2</version>                <configuration>                    <source>1.7</source>                    <target>1.7</target>                    <showDeprecation>true</showDeprecation>                    <showWarnings>true</showWarnings>                    <fork>true</fork>                </configuration>            </plugin>        </plugins>    </build>
After apply this modification on the POM file and save, Eclipse will complain about a not updated project. To get rid of this right-clieck the Project and choose Maven → Update Project. On the screen which will show up select the epicmaker project and press OK.
At last we can add a readme file on project. GitHUb will parse and show a Readme.md. MD comes from Markdown and was originally created by John Grube. Put a content like the following lines on the Readme.md file inside git repository root (I make it out of eclipse).
Epic Maker ========= Epic Maker is a sample tabçe top GURPS game aid to help players and GMs to play online.
On GitHub it will looks like this
Commits, branchs and pushs
If you not committed the project yet its a good time to do it. It will create the master branch, which we will use to deliver stable versions.
To not pollute the master make sure to create a new branch right now called developer. Right-click the repository and choose Switch To → New Branch, fill the Branch name text field with ‘developer’ and press Finish.
This will be used to develop new features and bugfix without messing the main code.
At last I push both of my project branchs to the GitHub too. Just switch between then and tell to Eclipse make pushs for you right-clicking the repo and selecting Push.
End words
Well that is it for now.
We end up with a maven project able to start a fresh new GURPS game aid. Huhaa!
In the next part we will actually code!!!
Giganerds's Blog 