An example planet rendering.

The primary tool I use for my art is GIMP. The method I used to make my planet renderings is a bit of a variation from the previously mentioned tutorial. For most planets, the majority of the steps are exactly the same. GIMP, fortunately, has extensive scripting capabilities. Being a programmer, it was only natural to utilize this to automate the more repetitive and boring tasks. At the end of this post are the two scripts I created to create my planets.

The first script creates a new planet, and has the following parameters:

• Image Size: The total size of the created image. This should be big enough to hold the planet plus three times the atmosphere thickness.
• Planet Size: The size (diameter) of the rendered planet.
• Planet Color: The color of the planet. This is not so important as you will likely replace it with your own texture.
• Outer Atmosphere Thickness: The thickness of the larger atmospheric haze.
• Inner Atmosphere Thickness: The thickness of the smaller, more opaque atmospheric haze.
• Atmosphere Color: The color of the atmosphere. Typically this will be a lighter shade of the planet color or white.
• Shadow Start: The distance along the planet diameter where the shadow starts.
• Shadow Stop: The distance along the planet diameter where the shadow reaches its darkest.
• Shadow Angle: The angle the light comes from.

After running this script, a basic planet is created. I also like to change the shadow occupancy to 90% so that the dark side of the planet is not completely black. The planet texture still needs to be created to replace the base planet layer. This is the most complicated, and the most interesting step. Unfortunately, how to make planet textures is beyond the scope of this post.

The second script maps a texture to a planet, then resizes it. There are only two parameters for this script.

• Planet Size: The size of the circle the texture will be remapped to.
• Refraction: How much to warp the texture.

To use the two scripts, your installation of GIMP needs python-fu installed and the files need to be placed in your plug-ins folder. The next time you open gimp, the scripts should appear as File/Create/Misc/Planet Creator and Filters/Planet/Map Texture. Here are the two scripts as well as some more example planets. Enjoy.

Planet Scripts

Example planet renderings.

Types of Grids

Everyone is familiar with the traditional square grid. It is also one of the easiest to understand and use in a game. All of the tiles lie in strait rows, and it can be easily indexed (using rows and columns). The primary drawback for a square grid is that each tile has only four adjacent neighbors. This limits movement to the four cardinal directions. To some extent, this shortcoming can be avoid by including the additional four diagonal tiles, but this is not entirely problem free. Diagonal moves need to count as something closer to a move and a half to make distance seem more natural. Also, there are some other questions like if there are two impassible tiles adjacent to the north and east, can you move diagonally between them?

Triangles can also be tessellated. There are not many games that use triangle tiles. They have the same disadvantages as square tiles, only worse. There are only three trivially adjacent tiles, and nine diagonally adjacent tiles. Indexing triangles is also not all that simple. For a tactical or strategic game, a triangle grid is probably not well suited. They may still be useful in puzzle type games, and because they are rarely used, could help make a game stand out.

In a hexagon grid, each tile has six adjacent tiles that share an edge, and no diagonal tiles. This means that there are six possible directions of movement with no ambiguities. Unfortunately, movement in any other direction must take a zig-zagging path. This on its own would not be so bad, except that either vertical or horizontal movement will always be non-strait. Hex tiles are also not as easy to index as square tiles.

Summary:

• Square: Pros: Easy to implement, intuitive, many examples. Cons: Diagonals can be complicated.
• Triangle: Pros: Unique design. Cons: Hard to implement, not many examples.
• Hexagon: Pros: Flexible movement without diagonals, many examples. Cons: More complicated than squares, some directions zig-zag.

There is another consideration which was not mentioned yet. Each type of grid has its own aesthetic qualities. That is, however very dependent on the individual and the type of game. Ultimately, you should use whichever grid is most suited to your game. People wont care whether there are triangle, square or hexagon tiles as long as the game is fun.

Hexagon Grids

As I already mentioned, I chose a hex grid for galaxy tactics, but that was not the only decision that needed to be made.

Grid Orientation

There are two orientations which hexagons are commonly tiled. We will call the first type “vertical” tiling because the tiles form a strait line in the vertical direction. The second type, “horizontal” tiling, has the tiles arranged in strait rows instead. The following two images demonstrate these two hexagon tiling schemes.

A vertical hex grid

A horizontal hex grid

An example of a game that uses a vertical hex grid is Hexic, while Civilization V uses a horizontal hex grid. I chose to use the later variation, but the two styles are ultimately the same grid rotated by 90 degrees. For whatever reason, indexing tiles in the horizontal arrangement is more intuitive for me and I think it looks better.

Indexing

Indexing is an important decision, as this is how you identify which tile is which. There are two obvious ways to index our horizontal hex grid. These are illustrated in the next two images.

One way of indexing a hex grid

Another way of indexing a hex grid

The first method is the most obvious. The tiles are indexed just like a square array, just with a slight zig-zagging in the vertical direction. This indexing is, however, very difficult to work with. Consider a tile in the first row, (x, 0). Its two neighbors in the row below are (x – 1, 1) and (x, 1). Simple enough, but what about a tile in the second row? the two neighbors below that tile are (x, 2) and (x + 1, 2). Depending on which row we are in, we need to use a different rule to determine which tiles are the adjacent. Everywhere we want to use the relative position of tiles, we must check whether we are on an even or odd row. The second method of indexing does not have this problem, and that is why I used it in galaxy tactics.

Useful Functions

Distance

The first function that will often be needed is the distance between two tiles. This function is actually quite simple.

public static int Distance(Point a, Point b)
{
    int dx = b.X - a.X;
    int dy = b.Y - a.Y;
    if (dx * dy < 0) // test if the signs are different
        return Math.Max(Math.Abs(dx), Math.Abs(dy));
    else
        return Math.Abs(dx) + Math.Abs(dy);
}

Grid Boundaries

If your grid is a bounded rectangle, it is often important to test whether a given point is within those bounds. The following function tests whether a point is within a rectangular grid starting at the origin.

public bool IsInGrid(int x, int y)
{
    return y >= 0 && y < Size.Y && (x + y / 2) >= 0 && (x + y / 2) < Size.X;
}

This is really just a regular point-within-rectangle test, but the x coordinate is offset by y / 2.

Neighbors

This function returns the adjacent neighbors to a tile (that are also in the grid using the above test). This is obviously quite useful for tasks such as pathfinding.

public List<Point> GetAdjacentTiles(int x, int y)
{
    List<Point> tiles = new List<Point>(6);
    if (IsInGrid(x    , y - 1)) tiles.Add(new Point(x    , y - 1)); // NW
    if (IsInGrid(x + 1, y - 1)) tiles.Add(new Point(x + 1, y - 1)); // NE
    if (IsInGrid(x - 1,     y)) tiles.Add(new Point(x - 1, y    )); // W
    if (IsInGrid(x + 1,     y)) tiles.Add(new Point(x + 1, y    )); // E
    if (IsInGrid(x - 1, y + 1)) tiles.Add(new Point(x - 1, y + 1)); // SW
    if (IsInGrid(x    , y + 1)) tiles.Add(new Point(x    , y + 1)); // SE
    return tiles;
}

To be continued…

Press read more for the full rules.

1 – Game Board

Galaxy Tactics is played on a hexagonal grid. The dimensions of the grid is dependent on the scope of an individual game, but is rectangular. An individual hexagon on the board is referred to as a tile. With the exception of the tiles at the boarder of the board, each tiles has six adjacent tiles (the six tiles that share a common edge).

Each tile also has a terrain type associated with it. Most common are planet and space tiles, but there may be additional terrain types with special rules.

Planets (which are composed of planet tiles) have special importance in the game. Each planet is marked by a planet tile with a star. A single planet is the group of all of the tiles reachable from a capital by only crossing planet tiles. In generally, the artwork on the board will make it clear where the boundaries of a planet are.

2 – Player Turns

The game proceeds in a “I go you go” fashion where one player takes their complete turn, followed by the next player. Each turn is divided into the following four phases:

1. Resource
2. Construction
3. Movement
4. Deployment

2.1 – Resource Phase

During the resource phase, a player collects resource points from each mine they control. Mines produce varying amounts of resources depending on where they are located and how developed they are. Regardless of the number of mines a player controls, they will always collect a minimum of 4 resource points.

2.2 – Construction Phase

During the construction phase, a player may spend the resources they have collected to build new units and structures. Structures are placed immediately. Units, however, are held in reserve, and will be placed on the board later in the turn. Any unused resource points are lost at the end of this phase.

2.3 – Movement Phase

During the movement phase, a player may move each of their units subject to the movement rules which will be described later. Once a unit has moved, it may not move again that turn even if it did not expend all of its available movement points.

2.4 – Deployment Phase

During the deployment phase, a player may place the units that they have in reserve. Due to the rules of unit placement, it may be possible that not all of the reserve units can be deployed. In this case any units still in reserve at the end of the phase are lost.

3 – Structures

Structures are a vital part of Galaxy tactics. They gather resources, produce supplies, and build new units.

3.1 – Ownership

A player only gains the benefits from structures on planets that they own. If a player is the only person who owns land units (i.e. infantry or armor divisions) on a planet, that player gains control of that planet. If multiple players own units on a planet, then the player who has a land unit in the capital gains control of the planet. In all other cases, a planet has no owner, and no players may utilize the structures on the planet.

3.2 – Construction

Players may only build or upgrade structures on planets they own. During the construction phase, players may buy structures. These come in three different levels with level 1 structures being the least advanced and level 3 structures the most advanced. When a structure is bought, it may be placed on the board with the following restrictions:

• A structure may only be placed on planets a player controls.
• Structures may only be placed on tiles containing resources. The resource does not have to match the type of structure, but if they do, the structure will gain additional bonuses.
• Only level 1 structures may be built on tiles without any existing structures.
• To place a structure on a tile with an existing structure, the new structure must be either the same type and one level higher or a different type and one level lower. There is one exception which is that level 1 structures can be replaced by any other level 1 structure.
• Only one structure may be placed on a tile per turn.

3.3 – Structure Types

There are three different types of structures that may be build.

Mine: Mines produce the resource needed to construct new buildings and units. A strong supply of resources is necessary to build a powerful army. Upgrading mine can, however, be expensive. Be careful not to neglect defense while upgrading your mines.

City: Cities produce supplies for your units. As you cannot produce new units when you don’t have enough supply, having a large number of cities is important in creating a large army. This must of course be balanced with the number or mines you control our you will end up with a lot of available supply and no way to utilize it.

Factory: Factories allow you to produce new units. There are, however, limits to how much a factory may produce in a single turn. First the is a resource limit. This is the maximum total cost of all the units produced at a factory in a turn. Second is the unit limit. This is the maximum number of units that may be produced. To fully utilize a factory, it may be necessarily to build a mix of powerful and cheap units.

4 – Units

Units form the forces that a player will use to conquer the galaxy.

4.1 – Movement

Each player controls a collection of units which they may move during their turn. Each unit has two attributes which influence where it may move. The first is movement. This is the number of tiles a unit may move during one turn. The second attribute is movement type. The movement type of a unit determines which type of terrains the unit may cross.

During the movement phase, a player selects one unit they own at a time. The player may then move this unit as many tiles as its movement attribute allows. There are, however, several restrictions to this movement. The first is that the unit may only move into tiles which contain terrain that the unit’s movement type allows them to traverse. For example, a cruise has a movement type of “Space” and can therefore not enter planet tiles.

While a unit may move through tiles which contain friendly units, it may not end its move in such a tile unless the unit there is capable of transporting the moving unit. A unit entering the tile of a hostile unit must immediately end its movement and engage in combat with the hostile unit. The rules for combat are described in the “Combat” section.

4.2 – Combat

When a unit moves into a tile containing a unit controlled by another player, the two units engage in combat. During combat, the two engaged units take alternating turns attacking their opponent. This continues until one of the units is destroyed. The unit that moved always attacks first, so it is advantages to engage your opponent before they engage you.

When attacking, a unit rolls a number of dice equal to the number of attacks it has. The unit’s attack bonus is added to each die. For each of these values that exceeds the defending unit’s defense, damage equal to the attacking unit’s attack damage is dealt to the defending unit. If the total amount of damage a unit has received equals or exceeds it toughness, it is destroyed and the other unit has won the combat.

4.3 – Deployment

Units in reserve are deployed at factories you have controlled for at least one turn (i.e. not factories you have built, upgraded, or captured that turn). When deploying new land units, they may be placed on either the tile for the factory or a tile adjacent to it (on a planet tile). Space units may be placed in any space tile adjacent to the planet. Units capable of crossing both planet and space tiles can be place as either land or space units. In all cases, the deployed unit must be placed on a tile that is unoccupied and which the unit can move through.

In order to deploy a unit at a factory, you must own the factory. Deploying the unit at that factory must also not exceed the factories resource or unit limit for the turn. The unit may also not be deployed if its supply cost would bring your total supply requirements above your available supply.

5 – Winning

A player wins the game when they control all planets.

Galaxy Tactics - Screenshot

-Eric

That is, however, no reason not to continue posting useful information. Over the next few weeks, I will be updating the previous tutorials so that they are stand-alone. Those should be more useful in the long run anyways. I will also begin posting some material on my new project, “Galaxy Tactics”.

-Eric

Minkowski Sum (and Difference)

The Minkowski sum is a simple operation to describe, but can be difficult to visualize. Given two sets, the Minkowski sum is the set of every element in the first set, added to every element in the second set. For example, consider the following two sets of points:

Set A: (1, 1), (2, 1)
Set B: (-2, 2), (-1, 2)

The Minkowski sum of A and B would be these four points:

(1, 1) + (-2, 2) = (-1, 3)
(1, 1) + (-1, 2) = (0, 3)
(2, 1) + (-2, 2) = (0, 4)
(2, 1) + (-1, 2) = (1, 3)

Figure 1 shows the Minkowski sum between the polygons A and B. Notice that while the resulting shape contains an infinite number of points, its boundary is defined by a very small subset of those. Not even all of the combinations of the vertices of A and B are needed to create the shape. This will turn out to be one of the reasons the GJK algorithm is efficient.

Figure 1: The Minkowski sum between polygons A and B.

The GJK algorithm uses a closely related operation, often called the Minkowski difference. Instead of adding the points, they are subtracted. This would be the equivalent of a Minkowski sum with the negative of the second set of points. Using the same to shapes from before, figure 2 shows their Minkowski difference.

Figure 2: The Minkowski difference between polygons A and B.

The most important property of the Minkowski difference is the fact that if two objects are overlapping, the Minkowski difference of their shapes must contain the origin. It is simple to see why this is the case. Because the Minkowski difference subtracts every point in one set from every point in another, if there is any point in common between the two sets, that point is subtracted from itself. The Minkowski difference must therefore contain the point (0, 0), which is the origin. Figure 3 demonstrates the Minkowski difference between two intersecting polygons. The resulting shape contains the origin as expected.

Figure 3: When polygons A and B intersect, their Minkowski difference contains the origin.

Support Function

We can determine if two shapes intersect by finding whether their Minkowski difference contains the origin or not. The GJK algorithm does this by attempting to construct a triangle (or tetrahedron in the three dimensional case), with corners on the boundary of the Minkowski difference, that contains the origin. If the two shapes are convex, it is possible to form such a triangle if and only if the two shapes intersect.

Instead of constructing the Minkowski difference directly, a support function is used. It takes a direction, and returns the point in the Minkowski difference that is furthest in that direction. Let the Minkowski sum between shapes A and B be expressed as the following:

The Minkowski difference can then be written as this:

The support function must therefore return the following:

This has not improved the situation yet. The point in the Minkowski difference that maximizes this dot product still needs to be found, but using some algebra, this can be reduced to a simpler problem. Substituting the definition of the Minkowski difference into the support function results in this:

The distributing the dot product gives this:

The maximize function can now be divided:

Because both maximize functions are independent, these can be split into separate function:

The original support function can be divided into two separate support functions. By taking the support of the first shape and subtracting the support of the second shape in the opposite direction, we get the same result. Intuitively it is easy to understand why this works. If we want the point that is furthest in a given direction in the Minkowski difference, first we would go as far as possible in that direction in the first shape. Because the second shape is being subtracted from the first, we would then want the point that is furthest in the opposite direction. Using this technique, the Minkowski difference no longer needs to be explicitly constructed.

Construction the Simplex

A simplex is simply a generalization of a triangle. A 0-simplex is a single point, 1-simplex is a line, a 2-simplex is a triangle, and a 3-simplex is a tetrahedron. Because we are working in two dimensions, only the 0-simplex, 1-simplex, and 2-simplex are of interest. The goal of the GJK algorithm is to build a 2-simplex (a triangle) that contains the origin or determine that such a simplex cannot be constructed. This can be done by choosing a random direction and calling the support function. After that, points will be iteratively added and removed from the simplex. The algorithm is outlined in the following pseudo-code.

function boolean intersects(Shape a, Shape b)
    // chose an initial direction
    Vector direction = (1, 0)
    // create the initial simplex
    Simplex simplex
    simplex = [getSupport(a, b, direction)]
    // set the direction to point towards the origin
    direction = -simplex.first()

    while(true)
        // add a new point
        simplex.add(getSupport(a, b, direction))
        // see if the new point was on the correct side of the origin
        if(!isSameDirection(direction, simplex.a)
            return false
        // process the simplex
        if(processSimplex(simplex, direction))
            return true

function Vector getSupport(Shape a, Shape b, Vector direction)
    return a.getSupport(direction) - b.getSupport(-direction)

function boolean isSameDirection(Vector v1, Vector v2)
    return v1.dot(v2) > 0

Other than processSimplex, that is the entire algorithm. The first thing we do is create an initial simplex. Since only one point is needed, an arbitrary direction is chosen and the support function is called with that direction. After the first point is added, a new direction is needed. Every time a new direction is chosen, it should be in towards the origin. With only one point, this is easy. The negative of our first point is the vector from that point, to the origin. After the initial simplex is created, the main loop is entered.

The main loop performs three actions. First a new point is added to the simplex using the getSupport function and the previous direction. We then check if the new point is on the same side of the origin as the last direction. If it is not, we have tried to get a point that was as far as possible in the chosen direction, but could not get all the way to the origin. This means there are no points on the other side of the origin, so the simplex will never be able to contain it. The algorithm can therefore terminate with the conclusion that the shapes do not intersect. The last step is the most complicated and that is the processSimplex function.

The process simplex function does three things. It checks if the origin is in the existing simplex. If this is the case, the shapes intersect. Second, it choses a new direction to expand the simplex in. This direction should be the vector from the closest point on the simplex to the origin. Finally, it removes any points from the simplex that are no longer necessary. How this is done is dependent on the size of the simplex. As mentioned earlier, because we are working in 2D, we are concerned with the 0-simplex, 1-simplex, and 2-simplex.

0-Simplex

The 0-simplex is a single point, and is the easiest to handle. The desired direction if simply the vector from the point to the origin. This case does not even need to be handled explicitly. We always have at least one point in the simplex and just before calling processSimplex, another is added. A 0-simplex will therefore never be passed into processSimplex.

1-Simplex

The 1-Simplex is a line. Let A be the most recent point added to the simplex. The area around the line can be divided into four regions as shown in figure 4.

Figure 4: A 1-simplex and the regions around it where the origin may lie.

We need to determine which of these regions the origin lies in. First, region 4 can immediately be eliminate because we were previously at B, then move towards the origin. A must be in the same direction as the origin or we would have terminated already so region 4, which is in the opposite direction, cannot contain the origin. To test if the origin is in region 1, we simply need to determine if the vector AB is in the same direction as AO. If it is, A becomes the new simplex (a 0-simplex) and the new direction vector is AO.

If the origin is not in region 1, it must be in region 2 or 3. These can be handled as a group. We first need a vector perpendicular to AB. In two dimensions, a vector perpendicular to (x, y) is simply (-y, x). This vector also needs to be in the direction of AO. If it is not, simply negate it. Instead of performing this check using an if statement, the dot product is used. Remember that the dot product is positive if two vectors are in the same direction, and negative if they are in opposite directions.

2-Simplex

The 2-simplex is the most complicated of the three cases. Let A, B, and C be the points of the simplex with A being the most recently added followed by B then C. Figure 5 shows the seven regions around the 2-simplex.

Figure 5: The 2-simplex and surrounding regions.

Again, we need to determine which region contains the origin. Regions 1, 2, and 3 can be immediately eliminated. This is because in the previous iterations we already determined that the origin must be between B and C and in the direction of A.

There are four remaining regions. If the origin is in the direction of AB and in the direction of the vector perpendicular to AB facing away from C, it is in region 4. Similarly, if the origin is in the direction of AC and in the direction of the vector perpendicular to AC facing away from B, it is in region 6. If the origin is in the opposite direction as both AB and AC, it is in region 5. Finally, if none of these cases are true, the origin is in region 7.

If the origin is in region 4, A and B become the new simplex and the search direction is perpendicular to AB facing away from C. Region 6 is similar with AC becoming the new simplex. If the origin is in region 5, A becomes the new simplex and the search direction is AO. Finally, if the origin is in region 7, we have determined that the Minkowski difference does contain the origin and the shapes intersect. The 2-simplex can be resolved using four if statements, of which only two ever need to be evaluated.

function boolean processSimplex(Simplex simplex, Vector direction)
    // we only need to handle to 1-simplex and 2-simplex
    if(simplex.size == 2) // 1-simplex
        // AO is in the same direction as AB
        if(isSameDirection(-simplex.a, simplex.b - simplex.a))
            // get the vector perpendicular to AB
            direction = (simplex.b - simplex.a).perpendicular
            // set direction to face O
            // if AO is not in the same direction as AB, the dot product will be negative
            // the scaling will therefore flip the direction to the opposite (correct) direction
            direction.scale(-simplex.a.dot(direction))
            // A and B remain in the simplex
            simplex = [simplex.a, simplex.b]
        else
            direction = -simplex.a
            // only A remains in the simplex
            simplex = [simplex.a]
    else // 2-simplex
        Vector AB = simplex.b - simplex.a
        Vector AC = simplex.c - simplex.a
        Vector AO = - simplex.a
        // the vector perpendicular to AB facing away from C
        Vector ACB = AB.perpendicular
        ACB = ACB.scale(ACB.dot(-AC))
        // the vector perpendicular to AC facing away from B
        Vector ABC = AC.perpendicular
        ABC= ABC.scale(ABC.dot(-AB))
        if(ACB.isSameDirection(AO))
            if(AB.isSameDirection(AO)) // region 4
                direction = ACB
                simplex = [simplex.a, simplex.b]
                return false
            else // region 5
                direction = AO
                simplex = [simplex.a]
                return false
        else if(ABC.isSameDirection(AO))
            if(AC.isSameDirection(AO)) // region 6
                direction = ABC
                simplex = [simplex.a, simplex.c]
                return false
            else // region 5 (again)
                direction = AO
                simplex = [simplex.a]
                return false
            else // region 5
        else // region 7
            return true

-Eric

A Basic Game

There are three main components to a basic game. The first is the GameLoop. This class manages the running of the game, calling update and draw at appropriate times. The GameContainer acts as an abstract interface between the game logic and the underlying implementation of the graphics, input, and other low level systems. Finally, the update and draw logic is contained in the class implementing the Game interface. Following is an example of a simple game:

import com.entropyinteractive.Game;
import com.entropyinteractive.GameContainer;
import com.entropyinteractive.GameLoop;
import com.entropyinteractive.WindowedGame;
import java.awt.Graphics2D;
import java.awt.event.KeyEvent;

public class Main implements Game
{
    public static void main(String[] args)
    {
        // create a stand-alone game
        GameContainer gc = new WindowedGame("Basic Game", 640, 480);
        // run the game with the default game loop
        gc.run(new GameLoop(), new Main());
        // exit when the game is finished
        System.exit(0);
    }

    @Override
    public void draw(GameContainer gc, Graphics2D g)
    {
        // add drawing logic here
    }

    @Override
    public void shutdown(GameContainer gc)
    {
        // add shutdown logic here
    }

    @Override
    public void startup(GameContainer gc)
    {
        // add startup logic here
    }

    @Override
    public void update(GameContainer gc, double delta)
    {
        // stop the game if the escape key is pressed
        if(gc.getKeyboard().isKeyPressed(KeyEvent.VK_ESCAPE)) gc.halt();
        // add update logic here
    }
}

The code is very simple. First a new game container is created. In this case the game container is a windowed game (i.e. a game running in AWT frame). Next, run is called on that game container passing in a game loop and a game to be run. This begins the game loop, which will continue until halt is called on the game container. Finally, when the game finishes running, the program exits.

The Main class itself is what implements the Game interface. It must therefore provide the draw, startup, shutdown, and update methods. The startup method is called immediately after the game loop begins running, and shutdown just before the game loop ends. The other two methods, update and draw, are called repeatedly by the game loop while the game is running.

The Game Loop

The game loop in Entropy Engine is intended to be flexible. It is design to robustly run a game in using several styles of update logic. The exact behavior can be set using the following four parameters:

• minDelta: This is the minimum time between updates. Update will never be called with a delta time less than this value, and if both update and draw finish in less time than minDelta, the game loop will sleep until minDelta seconds have passed.
• maxDelta: This is the maximum time between updates. Update will never be called with a delta time greater than this value. Depending on the next two parameters, if the game is running slow, multiple updates may be queued with maxDelta as the delta time to catch up. In this case, some calls to draw may be skipped to help the game catch up.
• maxUpdateDelay: This is the maximum amount of time an update will be delayed. If the game is running greater than maxUpdateDelay seconds behind, the game loop will re-sync with the real time and the queued updates will be skipped.
• maxDrawDelay: This is the maximum amount of time a draw will be delayed. If it has been greater than maxDrawDelay seconds since the last draw, draw will be called regardless of whether or not the game is running slow.

By setting these parameters appropriately, many different behaviors can be achieved. For example, setting minDelta to 0 and maxDelta to infinity would result in the simplest delta time game loop. Setting minDelta and maxDelta to the same value results in a fixed logic rate game loop. If maxUpdateDelay is 0, the game will slow down if the updates and draws are taking to long. Setting maxDrawDelay to 0 will result in a draw being called after every update.

Input

The three input types in Entropy Engine are keyboard, mouse, and mouse wheel. Each game container provides three methods to retrieve each of these. For example, during a call to update, the gc.getKeyboard() could be used to get the current instance of the keyboard input manager.

Each of the input managers provides several ways to access the input. All three include the getEvents method to retrieve a linked list of every input event that occurred since the last update. They also implement the Iterable interface to conveniently iterate over the those events. Each of the input classes includes various methods for common input related tasks. Details on these methods can be found in the Javadoc.

-Eric

Object Hierarchies

Traditionally, game entities used object hierarchies. Each layer added some amount of functionality. At the root was some form of generic object, and as you proceeded down the branches, the classes got increasingly specific. This tree like structure is a logical organization for objects that have a clear supertype-subtype relationship. In games, however, this can be very limiting. Consider the following example:

This object hierarchy is simple enough. The shack, mansion, and bank all fit in well defined categories. What happens if an new object, such as a apartment, needs to be added?

It is not clear what the apartment should inherit from. It has properties of both a a home and a business. The object hierarchy could always be refactored, but depending on its complexity, that may be easier said then done.

Composition

The alternative to object hierarchies is a concept called composition. The “is-a” relationship of inheritance is converted to a “has-a” relationship. The game entities become containers for various components, which determine its state and behavior. In the above example, an apartment may contain a building, home, and business object.

There are several advantages to this design pattern. First, the various components can remain loosely coupled. With a deep object hierarchy, a change near the root can have far reaching and unexpected consequences. In a composition, only the components that directly communicate are affected by changes to one another.

Composition can also make game entities more flexible. Adding additional behavior is as simple as adding a new component to the entity. In the above example, if banks and apartments now require rent, a new rent component can be added to those two components. The rent component could then ask the respective tenant components to pay their rent. This ability to quickly add and remove behavior from entities is a great advantage during development.

A third advantage is that the program becomes easier to understand. It is clear which behaviors and properties an entity has, simply by looking at its list of components.

Communication

The difficulty of a composition is communication. To build more complex behavior, the various components must be able to relay their state and events to each other. One possible way of doing this is by making the game entities store a reference to every type of component. At creation, an entity initializes the components it needs and leaves the remaining ones empty. When one component needs to communicate with another, it looks up the other component’s reference, and performs whatever actions are needed. This design works, but can become awkward when there is a large number of components, or when components are often added and removed from an entity (such as during development).

On the other end of the spectrum is the abstract approach. The entity knows nothing of the components it contains. It views them as abstract objects. Communication is facilitated via messages. When a component’s state changes, a message is created. This message is then forwarded to all of the other components in the entity. They may choose to handle it however they want. The problem with this approach is that there is a non-trivial amount of overhead when sending these messages. For may applications, this overhead is not important, and the messaging system offers a great deal flexibility.

A Hybrid Approach

The implementation described here lies somewhere between the two previous methods. When a component is added to an entity, all of the other components in that entity are informed. It is then their responsibility to keep a reference to the new component or not. Similarly, the components are informed whenever a component is removed from the entity.

This method has both advantages and disadvantages. The entity does not need to know anything about the components contained within, but the messaging overhead occurs only when components are added or removed (most commonly during entity construction). The components also have the option of communicating in whatever manner is most appropriate, whether it be through events, polling, or direct access.

This primarily comes at the cost of memory. Because each component must hold its own references, if multiple components depend on the same object, those references become redundant. Object creation can also become expensive. The number of messages passed at object creation is the square of the number of components.

Reducing the memory overhead would be difficult using this design, but the object creation cost can be reduced. First, the components can be divided into two categories, lightweight and heavyweight. Lightweight components do not need to know about other components. They are strictly data providers. This does not mean that they can not have behaviors of their own, they just do not need to know about the other components in the entity. The complexity of entity construction is now dependent primarily on the number of heavyweight components. It can contain many lightweight components without issue.

The second optimization is allowing for sub-entities. Entities can be added to other entities as if they were components. This creates a tree structure. Events are propagated horizontally and away from the root the tree. This creates an isolation between various components. For example, a physics entity can be created that will hold all of the physics related entities. Externally, other components may only need to be aware of the objects position, but internally there can be many components influencing its behavior. These two design choices will allow for the performance of the entity to be tuned, as well as grant some additional organizational options.

Implementation

Provided below is a minimalist implementation of the described entity system. The code is written in Java, but depends on very little on Java specific functionality.

-Eric

Component Interface:

public interface Component
{
    void componentAdded(Component c);
    void componentRemoved(Component c);
    boolean isLightweight();
}

Entity Class:

public class Entity implements Component
{
    private ArrayList<Component> heavyComps = new ArrayList<Component>();
    private ArrayList<Component> lightComps = new ArrayList<Component>();

    public Entity()
    {
        // do nothing
    }

    public final void addComponent(Component comp)
    {
        // safety check
        if(comp == null)
            Log.error(new NullPointerException("component == null"));

        // inform the heavyweight components that a new component has been added
        for(Component c : heavyComps) c.componentAdded(comp);

        if(comp.isLightweight())
        {
            // add the new component to the lightweight components
            lightComps.add(comp);
        }
        else
        {
            // inform the new component of the existing components
            for(Component c : lightComps) comp.componentAdded(c);
            for(Component c : heavyComps) comp.componentAdded(c);
            // add the new component to the heavyweight components
            heavyComps.add(comp);
        }
    }

    public final void removeComponent(Component comp)
    {
        // safety check
        if(comp == null)
            Log.error(new NullPointerException("component == null"));

        if(comp.isLightweight())
        {
            // remove the component from the lightweight components
            lightComps.remove(comp);
        }
        else
        {
            // remove the component from the heavyweight components
            heavyComps.remove(comp);
            // inform the other components that this component is being removed
            for(Component c : lightComps) comp.componentRemoved(c);
            for(Component c : heavyComps) comp.componentRemoved(c);
        }

        // inform this component that all the other componets are no longer
        // accesible
        for(Component c : heavyComps) c.componentRemoved(comp);
    }

    public void componentAdded(Component comp)
    {
        for(Component c : heavyComps) c.componentAdded(comp);
    }

    public void componentRemoved(Component comp)
    {
        for(Component c : heavyComps) c.componentRemoved(comp);
    }

    public final boolean isLightweight()
    {
        return false;
    }
}

public class AsteroidsInfinity extends Game
{
    private Path2D.Double ssTriangle;
    private double shipX;
    private double shipY;

Our simple game will require only three members, the shape used to draw the ship, and its x and y position. We will assign these values in the startup method.

    public void gameStartup()
    {
        Log.info(getClass().getSimpleName(), "Starting up game");

        // construct our ship
        ssTriangle = new Path2D.Double();
        ssTriangle.moveTo(0.0, -30.0);
        ssTriangle.lineTo(20.0, 20.0);
        ssTriangle.lineTo(0.0, 10.0);
        ssTriangle.lineTo(-20.0, 20.0);
        ssTriangle.closePath();
        // assign the initial location of the ship
        shipX = getWidth() / 2;
        shipY = getHeight() / 2;
    }

This creates the arrow shaped ship, and assigns it location to the center of the screen. Next is the update logic.

    public void gameUpdate(double delta)
    {
        Keyboard keyboard = getKeyboard();
        // poll the input for the arrow keys to control movement
        if(keyboard.isKeyPressed(KeyEvent.VK_UP))
            shipY -= 100.0 * delta;
        if(keyboard.isKeyPressed(KeyEvent.VK_DOWN))
            shipY += 100.0 * delta;
        if(keyboard.isKeyPressed(KeyEvent.VK_LEFT))
            shipX -= 100.0 * delta;
        if(keyboard.isKeyPressed(KeyEvent.VK_RIGHT))
            shipX += 100.0 * delta;

        // check the list of key events for a pressed escape key
        LinkedList<KeyEvent> keyEvents = keyboard.getEvents();
        for(KeyEvent event : keyEvents)
        {
            if((event.getID() == KeyEvent.KEY_PRESSED) &&
                    (event.getKeyCode() == KeyEvent.VK_ESCAPE))
            {
                stop();
            }
        }
    }

First we get the keyboard manager. To control the space ships movement we will use the polling style interface. We check each of the of the arrow keys and adjust the ships position appropriately if any of those keys are pressed. If the user presses the escape key, we want our program to exit. We don’t want to miss this event, so we will examine every key press during the last update interval. If the escape key was pressed, we will call stop to end the game. Now we need to implement the draw method.

    public void gameDraw(Graphics2D g)
    {
        // offset our drawing to the ships location
        g.translate(shipX, shipY);
        // draw the ship (fill then outline)
        g.setColor(Color.gray);
        g.fill(ssTriangle);
        g.setColor(Color.white);
        g.draw(ssTriangle);
    }

The drawing method first translates the canvas to the ships location, then fills and outlines the ship’s shape. The shutdown method also needs to be implemented, but it does not need to do anything.

    public void gameShutdown()
    {
        Log.info(getClass().getSimpleName(), "Shutting down game");
    }

What remains is the constructor and the main method.

    public AsteroidsInfinity()
    {
        // call game constructor
        super("Asteroids Infinity", 640, 480);
    }

    public static void main(String[] args)
    {
        Game game = new AsteroidsInfinity();
        game.run(1.0 / 60.0);
        System.exit(0);
    }

The constructor calls Game’s constructor with our desired title and size. The main method first creates an instance of AsteroidsInfinity, then calls run with the target logic rate. Finally, after run returns (after stop is called), we exit the program.

We have now completed a simple game. Next we will re-factor this code into the basis of our game engine. The complete source code for this example can be found in “Asteroids Infinity – Phase 1.zip”, here.

-Eric

import java.awt.Color;
import java.awt.Graphics2D;
import java.awt.event.KeyEvent;
import java.awt.geom.Path2D;
import java.util.LinkedList;

public class AsteroidsInfinity extends Game
{
    private Path2D.Double ssTriangle;
    private double shipX;
    private double shipY;

    public static void main(String[] args)
    {
        Game game = new AsteroidsInfinity();
        game.run(1.0 / 60.0);
        System.exit(0);
    }

    public AsteroidsInfinity()
    {
        // call game constructor
        super("Asteroids Infinity", 640, 480);
    }

    public void gameStartup()
    {
        Log.info(getClass().getSimpleName(), "Starting up game");

        // construct our ship
        ssTriangle = new Path2D.Double();
        ssTriangle.moveTo(0.0, -30.0);
        ssTriangle.lineTo(20.0, 20.0);
        ssTriangle.lineTo(0.0, 10.0);
        ssTriangle.lineTo(-20.0, 20.0);
        ssTriangle.closePath();
        // assign the initial location of the ship
        shipX = getWidth() / 2;
        shipY = getHeight() / 2;
    }

    public void gameUpdate(double delta)
    {
        Keyboard keyboard = getKeyboard();
        // poll the input for the arrow keys to control movement
        if(keyboard.isKeyPressed(KeyEvent.VK_UP))
            shipY -= 100.0 * delta;
        if(keyboard.isKeyPressed(KeyEvent.VK_DOWN))
            shipY += 100.0 * delta;
        if(keyboard.isKeyPressed(KeyEvent.VK_LEFT))
            shipX -= 100.0 * delta;
        if(keyboard.isKeyPressed(KeyEvent.VK_RIGHT))
            shipX += 100.0 * delta;

        // check the list of key events for a pressed escape key
        LinkedList<KeyEvent> keyEvents = keyboard.getEvents();
        for(KeyEvent event : keyEvents)
        {
            if((event.getID() == KeyEvent.KEY_PRESSED) &&
                    (event.getKeyCode() == KeyEvent.VK_ESCAPE))
            {
                stop();
            }
        }
    }

    public void gameDraw(Graphics2D g)
    {
        // offset our drawing to the ships location
        g.translate(shipX, shipY);
        // draw the ship (fill then outline)
        g.setColor(Color.gray);
        g.fill(ssTriangle);
        g.setColor(Color.white);
        g.draw(ssTriangle);
    }

    public void gameShutdown()
    {
        Log.info(getClass().getSimpleName(), "Shutting down game");
    }
}