Click on the title image to go to the main page
 Main Page
 Contact Logo
Last Updated: 12th Nov, 2008, 12:37 GMT



JOGRE is a Java based client/server games engine which allows the creation of online multiplayer games. To illustrate JOGRE in action the following labelled image shows a JOGRE server and two clients, Dave and Bob.

At the top of the image is a screenshot of a server running in a DOS command prompt (1) Under the server is a screenshot of 2 chess clients, Dave (2) and Bob . These are currently programmed as Swing JFrames / JApplets. The client window is composed of a list of all the users currently logged on (3), a list of all the tables currently being played (4) and a global message chat window (5) where users can broadcast messages to each other.


A user creates a table frame (6) by clicking on the "New Game" button which brings up another window. In the screenshot user Dave has created a table, which the user Bob has joined.

When both players Bob and Dave have sat down (sit button) and requested to start (start button) then the game begins. When a player sits down this is updated on the player list (7) on the bottom left of the screen. The two players can chat to each other using a table chat window (8). The actual game itself is displayed in the middle of the screen (9) and this is the only bit that differs from game to game i.e. the JOGRE API takes care of the rest of the user/table logic and GUI interface.

Other functionality which JOGRE provides is the ability for a user to send a private chat message to another player. To do this a user selects another user from the list (3) and then clicks the message button. The following screenshot shows Dave having a private message with Bob.


Tables in JOGRE have the ability to be either public or private. If the table is public then any user in the system can join this table (using the "Join" button) and play. However, if a table is declared as private then only users which are invited can join (using the "Invite" button).

This is the basics of what JOGRE is about. The beauty of the API in JOGRE is that when a new game is created all this functionality previously discribed exists in the API and only game needs to be worried about. The API is discribed in more detail in the next section.

[ top ]

At present there are 23 multi-player JOGRE games. Here they are in alphabetical order:


Abstrac is a card game for 2 players. Players take turns picking cards from the deck. Points are scored for sets (cards of the same values of different suits) and runs (cards of the same suit that are of consecutive values) collected. But each card a player takes increases the values of his opponent's sets and runs...


The jogre version of battlehips is played on two square grids, one for each player. On one grid the player arranges his own ships and records the shots by the opponent. On the other grid, the player records his own shots. Whoever sinks all of the opponents battleships wins the game.


Camelot is a 2 player board game programmed using JOGRE by Richard Walter. The board is a 12x16 board with some pieces removed. The two squares at the top and bottom are the players castles. There are several ways to win this game which involve moving players into the other player castle pieces or capturing pieces.

Car tricks

Car Tricks is a unique car racing game in that no one person controls a specific car. Instead, players try to predict the entire order of finish for all the cars in the race. All players can influence the speed of a car through their card play. The player that most closely predicted the finishing order of each car will emerge victoriously.


A version of checkers has also been created using the JOGRE API. The rules of checkers arn't quite as complex as chess. The aim of the game in checkers is to capture all the opponents pieces by jumping over them in a diagonal fashion.


A playable version of chess has been created using the JOGRE API. The aim of chess is to checkmate the opponents king piece so that it cannot move. The rules of chess are complex but the majority of them have been implemented.

Chinese Checkers

Chinese Checkers is a board game that can be played by two to six people. It is a variant of Halma; the objective of the game is to place one's pieces in the corner opposite their starting position of a pitted hexagram by single moves or jumps over other pieces.


The next game is an old turn based family classic Connect Four where a player drops his coloured pieces down each column. When a player gets four in a row horizontally, vertically or diagonally the game is won.


The game dots starts with an empty grid of dots, players takes turns adding a single horizontal or vertical line between two unjoined adjacent dots. A player who completes the fourth side of a box earns one point and takes another turn (the box will be filled with the players colour). The player with the most boxes wins the game.


The game Go is a very old Chinese game. The two players, black and white, battle to maximize the territory they control, seeking to surround large areas of the board with their stones, to capture any opposing stones that invade these areas, and to protect their own stones from capture.

Grand Prix Jumping

In Grand Prix Jumping, players use cards to move their horses around the track and over jumps. Cards are distributed via a "divide and choose" method where one player will divide cards into two piles and the other player will choose which pile to take. Points are accumulated during the game and the player finishing with the fewer fault points is the victor.


Players take turns placing a stone of their color on a single cell within the overall playing board. The goal is to form a connected path of your stones linking the opposing sides of the board marked by your colors, before your opponent connects his sides in a similar fashion. The first player to complete his connection wins the game.

Ninety Nine

Ninety-nine is a card game for 2, 3, or 4 players. It is a trick-taking game that can use ordinary Anglo-American playing cards. In ninety-nine, players bid for the number of tricks that they will take; players who gain exactly that number of tricks gain a significant bonus. One unusual feature of ninety-nine is that players bid by discarding three cards.


Octagons is a two player game developed by Richard Walter. In octagons one player is red and the other is blue. The goal of octagons is to connect two sides of the board by claiming spaces on the board. The red player is trying to connect the top and bottom of the board. The blue player is trying to connect the left and right sides of the board.


Another turn based game called propinquity has also been created. The aim of propinquity is to build up as much terrority as you can. You can capture enemy pieces by placing a piece of a higher value beside it. You can also strengthen your own cells by placing a new piece beside existing cells.


Quetris is a varient of tetris. Each shape is made from 5 blocks (as opposed to 4 for tetris). These shapes have the added ability to flip horizontally and vertically. Apart from this Quetris plays very much like a more challenging version of tetris.


The board game Reversi was developed by Anton Ugnich. Each reversi piece has a black side and a white side which are placed on a board. All of the opponent's pieces between your pieces are then turned over to become your color. The aim of the game is to own more pieces than your opponent.


Spades is a trick-taking game somewhat akin to Hearts but more closely related to bridge. The game is scored by hands, and the winner must make a certain number of points which is decided before the game begins. The player on the dealer's left makes the opening lead, and players must follow suit. To see the complete rules click here.


There exists a JOGRE version of the very popular Russian game Tetris. In tetris, blocks of four squares, fall down the screen with the aim to make solid horizontal lines. In JOGRE tetris if you create 2,3 or 4 horizontal line then 2,3, 4 lines respective lines appear on the opponents screen.

Texas Hold'em

Texas hold 'em is most popular version of poker. It is a community card game where each player may use any combination of the five community cards and the player's own two hole cards to make a poker hand. The objective of winning players is not winning every individual hand, but rather making correct decisions regarding how much to bet, raise, call or fold.


Tic-tac-toe, also called noughts and crosses and many other names, is a paper and pencil game between two players, O and X, who alternate in marking the spaces in a 33 board. A player wins by getting three of their own marks in a horizontal, vertical or diagonal row.


Triangulum is played on a triangular board made up of triangular spaces. The pieces are triangular tiles whose edges are painted different colors and have a basic value displayed in the middle. The game ends when no players have legal moves and there are no more tiles in the bag to be drawn. The player with the highest score is the winner.


Warwick the Kingmaker is a game for three to five players in which you and your opponents play feuding lords trying to get the most prestigious status in the realm. The victor is the player with the most prestige points at the end of the game. A player earns prestige points by the actions of his own house and by supporting another candidate house.

To see screenshots of these games click here.
[ top ]

The JOGRE API has been designed so that functionality which is common to all (or almost all) types of games is taken care of. This functionality includes organising users, table lists and player lists within tables. The API also deals with player chat which can be global, private to a table or private to an individual user.

The following diagram visually shows the package structure of the JOGRE API. The package structure has got simplier in alpha 0.2 with three main package for holding client classes, server classes and common classes which both the client and server make use of. The main package is the org.jogre package which most other packages exist under. However the JOGRE API is also packaged with the TableLayout jar file from clearthought (in yellow) which the org.jogre.awt package uses extensively and the XML parser NanoXML (in brown) which is used for sending communication in XML form.

Arrows are used to show the dependencies between packages. Most dependencies are in one direction to keep coupling low, except the awt and client packages (although the client to awt communication is achieved using interfaces).

  • info.clearthough.layout - TableLayout manager which provides the power of GridBagLayout but is much easier to use.
  • nanoxml - Very small XML parser which is used primarilaly for communication object serialization.
  • Common Packages
    • org.jogre.common - Contains classes which are used both in the server and a client. These are mostly data classes such as TableList, Table, UserList, User, PlayerList, Player etc which store details on users and tables currently being played. It also contains the important JogreModel class which is used to store the state of a game on client and on a server (optional).
    • org.jogre.common.playerstate - The state of a player is stored as classes in this directory (state design pattern). These states include viewing, seated, ready to play and game started.
    • org.jogre.common.util - Contains a number of utility packages which most of the other packages make use of. These include singleton classes which are used for loading properties/language labels. Also includes common file utilities and a small logger.
    • org.jogre.common.comm - Contains 2 interfaces and a number of communication classes. Most communication between a server and a Client is transferred as Comm objects.
  • Client Packages
    • org.jogre.client - Contains a number of classes specific to a JOGRE client.
    • org.jogre.client.awt - Contains various GUI components used in the creation of the JOGRE interface. Most of the key classes in the JOGRE API are in this package.

Key Classes

A number of key classes exist in the JOGRE API. These key classes are abstract and need to be extended to be used. Also some of the classes contain abstract methods which must also be implemented. This pattern of creating an application is known as the Template Design Pattern - a programmer fills in the bits which are specific to his specific game - the rest is already done in the API classes. The naming convention is usually to replace the word Jogre with the name of the game. i.e. JogreModel becomes ChessModel.

Package Class/Interface Synopsis


This abstract class declares the main game frame where a user can see users of the left, tables on the top right and a broadcasting style message chat box on the bottom right. To create a new client frame for a game, such as Chess for example, a class called e.g. ChessClientFrame extends this class and implements 2 abstract methods for returning the correct JogreTableFrame class (e.g. ChessTableFrame).


The important JogreTableFrame which is where each game is played. Each time a new table is created one of these frames appear. This class creates the buttons at the top of the screen, the player list at the bottom left and the message chat box on the bottom right. The main game area is set in the sub classes e.g. ChessTableFrame using the setGamePanel (JPanel) method.

To use this class a class must extend it e.g. ChesTableFrame. Its fields must include a data model (JogreModel e.g. ChessModel), a view of the data (JogreComponent e.g. ChessBoardComponent) and a controller (JogreController e.g. ChessController) for understanding mouse movements etc on the view.

The constructor in the sub class should initialise these MVC fields and MUST call the setMVC (model, view, controller) method as this class makes use of these.


This class creates the view in the JOGRE MVC (model/view/controller) architecture. This class extends a JComponent and also implements the Observer interface. By implementing the Observer interface a change in the model (JogreModel) which calls the JogreModel.refreshObservers () method will automatically repaint this class.

Mouse/keys events can listened on using a JogreController which is set using the setController method of this class.



Adapter game controller class which creates empty methods for the MouseListener, MouseMotionListener and KeyListener event interfaces. This class also contains a link to the JogreModel, a connection thread to the server and also a JogreComponent where the mouse movements/key presses are taking place on.

To use this controller a class must extend it e.g. ChessController and then override one of its event methods, update the correct model and send communication to other users. To use the controller on a JogreComponent, a JogreComponent calls its public void setController (JogreController controller) method.



Abstract base class for table messages. This class is used for creating communication objects between games e.g. CommExecuteChessMove.

From alpha 0.2 it is only necessary to create objects for very complex games as communication properties can be used.



Abstract class which holds the state/model of a particular game when extended. This class extends the Observable class so that JogreComponent classes can update themselfs depending on changes made in this classes.

For a very simple example, to create the model for a game of tic-tac-toe a class TicTacToeModel should extend this class and add a 3x3 two dimensional int array i.e.

int [][] = {{0, 0, 0}, {0, 0, 0}, {0, 0, 0}}.

All of these key classes (with the exception of CommTableMessage) must be extended from the JOGRE API to create a new game. The following UML diagram shows how a game of chess can be created using the JOGRE API. The classes on the bottom are the chess classes and the classes at the top are from the JOGRE API / Java SDK.


The ChessClientFrame class contains a main method which when executed, creates a JFrame with the various users, tables and global chat on the screen. This screen generally doesn't change from game to game i.e. ChessClientFrame contains very little code. When the new table button is clicked a ChessTableFrame is created which is the key class of a game. The parent class JogreTableFrame creates buttons at the top, a player list and table chat on the bottom.

The actual game of chess is rendered in the middle of screen and is created in JOGRE using a MVC (model/view/controller) style architecture. The chess board in the middle (ChessBoardComponent) is created from an AbstractBoardComponent which can be used to easily create game boards (i.e. is also used to create a checkers board). The ChessModel contains data relating to a game of chess including an integer array of size 64 (8 by 8 cells of a chess board). Example values of the array are: 0 = Empty, 1 = White Pawn, 2 = White Knight etc. The ChessBoardComponent registers with the model so that every time the ChessModel changes the board will refresh itself with the pieces in the correct position.

The ChessController controls the ChessBoardComponent i.e. listens to mouse events and updates the ChessModel if a move has taken place. The JogreController also has a link to the TableConnectionThread and can inform the server that a move has taken place and keep other clients in synch.

This is a very brief introduction / summary of what is required to create a JOGRE game. A much more indepth look, with full source listings and UML diagrams is available in the various tutorials.

[ top ]
Copyright 2004-2008, JOGRE API and JOGRE Games, by Bob Marks