This page describes the steps required to create your Play By E-Mail game using the PBEM Engine. Each step will be described in as much detail as possible, linking to other pages if necessary.
Before you start
Please make sure you have the proper tools installed, and have mastered the proper skills to make a PBEM game. Also, please keep in mind that the PBEM Engine developers have their own projects and hobbies to worry about, so even if you have an awesome idea for a PBEM, you'll probably have to build it yourself. So, before you start, please use the following checklist:
Organizational
- Do you mind having to make your game both Free and Open Source software? The Engine is licensed under version 3 of the GNU General Public License, and your PBEM will be a plugin that makes extensive use of the PBEM Engine's classes, in many cases by creating subclasses, so your game must also use version 3 of the GPL. If you don't want this, stop reading now and don't use this framework.
- Do you have the time and dedication needed to finish this project? This thing isn't going to build itself, and even if you're going to let other people do most of the coding you'll still need time to manage them.
- Do you have a clear idea of the sort of game you want to make? Vague ideas have a tendency never to turn into actual games (we've been there, we know
), and a good design document makes it easier to attract other developers. - Is the game you want to create turn-based? While it is possible to make non turn-based games with the Engine, it was primarily designed to create turn-based games.
Technical
- Do you have experience programming in Java, version 1.5 or higher? If not you can stop reading right now, this framework requires a good grasp of Java to create a PBEM. The Engine can make a lot of tasks simple but you'll still need to code your game logic. You could try to let others do the programming while you do the designing, but this can be very hard unless you have some knowledge of Java.
- Do you have experience working with databases? A basic understanding of SQL, and access to a modern DBMS is required to make the Engine work.
- Do you have experience using the Hibernate framework? The Engine uses Hibernate with Annotations for persisting classes into a database, and you will probably need to use Hibernate queries and/or criteria to work with the database.
- Do you have experience creating web pages using HTML and CSS? This isn't strictly necessary, but will allow you to create a Game Master web interface for your game.
- Do you have experience using Freemarker templates? These are fairly easy to learn to use. Freemarker templates are used to generate turn reports as well as web pages using the builtin web server.
- Do you have knowledge using Apache Maven? Maven is the tool used to build the PBEM Engine, and is required to create your own PBEM. You could in theory do it without Maven, but it's a lot more work, and we won't help you.
Troubleshooting
If for some reason you can't figure out what to do next, or the Engine is giving you unexpected errors, feel free to contact us on our Ruleset Developers mailing list. If you find a bug with the software you can post a bug report on our issue tracking site.
Getting started
This section describes the first steps required to create your own PBEM. We will assume you have the following tools installed:
- Java 1.5 or higher, preferably Java EE 6 update 10 or higher
- Apache Maven 2
- We also recommend using a version control system with at least 1 non-local repository for tracking changes. We personally use Subversion, but any modern version control system will do.
And before we go any further, we want to explain some basic terminology:
| Word | Meaning |
|---|---|
| PBEM | Play By E-Mail game, a game played by sending and receiving e-mails |
| Ruleset | An implementation of a PBEM for use with the Engine. Basically a plugin that runs on top of the Engine, and uses it for most tasks |
| Turn | The simultaneous processing of all major player actions within a game |
| Check action | Each time the Engine checks if it has received any e-mails, it will also, for each received e-mail, check if it contains any commands it can process. The process of checking for and processing of received e-mails is called a Check Action |
| Process action | The processing of a turn is called a Process Action. All game-specific logic is carried out at this point, and each player is sent a report once it is done. |
To clarify, a typical PBEM using the Engine will work as follows:
- Every few minutes (configurable), a Check Action is performed. A Check Action fetches mails and processes them, for instance relaying messages from player to player, or recording commands to be executed for the next turn
- Once a week (configurable), a Process Action is performed. All recorded commands are executed, and each player receives a Turn report.
Setting up the project
Assuming you have Apache Maven installed, we start by creating our own project using the PBEM Engine quickstart.
$ mvn archetype:generate -DarchetypeCatalog=http://maven.pbemengine.nl/ -DarchetypeRepository=http://maven.pbemengine.nl/
This will generate a list of all available project quickstart packages on our server, which should only contain a single package. Enter the group and artifact ID of your PBEM (if you're new to Maven, consider the group ID to be similar to a package name, and the artifact ID to be a name for your project). After this action is completed you now have a new directory containing a basic Maven project structure containing a Ruleset class and some sample classes to use it with.
Creating a PBEM - 1. The basics
As we said in the “before you start” section earlier - before we start creating our play by e-mail game, we need to have an idea of the sort of game we want to make. Since this is supposed to be a simple tutorial, we will be creating a rather simple game based on Rock-paper-scissors. If you are unfamiliar with this game we suggest you check out the previous link first.
Designing the game
Our game is going to work as follows:
- Each turn a player may choose either Rock, Paper or Scissors
- At each Process action, a player's choice is compared to all other player's choices
- For each winning choice, a player gains 3 points
- For each draw, a player gains 1 point
- For each loss, a player gains no points
- Players can join at any moment, their initial score being zero point
- With each report, a ranking list is included to show who won the most matches, it also shows the choices made by each player.
- Players that do not send in a choice for their turn gain no points
- Players that do not send in a choice for 5 consecutive turns are removed from the game, their scores deleted
Each game monitors a single e-mail address, and users can send the following types of e-mails:
- An information request - gives details about the game, with the top scoring player, number of players, and most used choices
- A registration request - adds the player to the game
- A choice selection - An e-mail that sets the player's choice for the next turn
- A termination request - removes the player from the game
In addition to these e-mails, our game has the following “entities”. These are classes that are going to be mapped to database tables.
- Score entities - Contain the score of each player in a given turn
- Choice entities - Contain the choice of each player in a given turn
We will illustrate the use of the Engine with this example design.
Creating our project
We start by initializing a PBEM quickstart project with our pre-chosen parameters.
$ $ mvn archetype:generate -DarchetypeCatalog=http://maven.pbemengine.nl/ -DarchetypeRepository=http://maven.pbemengine.nl/
Use the following parameters:
| Parameter | Value |
|---|---|
| groupId | nl.pbemengine.tutorial |
| artifactId | Tutorial |
| version | 1.0-SNAPSHOT |
| packageName | nl.pbemengine.tutorial |
Make sure you have a Subversion copy of the Engine installed (using mvn install), otherwise your build will fail when you try to compile your ruleset! After Maven finishes, we have the following directory structure:
+ Tutorial
| pom.xml
+--+ src
+--+ main
+--+ java
+--+ nl
+--+ pbemengine
+--+ tutorial
| Rules.java
| MyReportGenerator.java
| MyTurnProcessor.java
| MyMailProcessor.java
This is a basic layout for a PBEM project. Once compiled, we can use the created Jar file directly as plugin for the PBEM Engine.
Now we will start the actual job of creating a PBEM. We will begin by inspecting the Rules class.
