As it turns out, all of the previously created games in this book exist in a three-dimensional space. You may have noticed that, for example, when setting the position of a camera object (in the alignCamera method of the BaseActor class), you have x, y, and z components to set. If the x-axis and the y-axis represent the horizontal and vertical directions on the screen, respectively, then the z-axis corresponds to a straight line pointing toward the viewer, perpendicular to the xy plane—the plane containing the x and y axes. The camera can be thought of as being positioned on the z axis, pointing straight toward the xy plane ; all of the game entities have implicitly had their z coordinate set to 0. This configuration is illustrated in Figure 16-2, which shows roughly how the camera sees the Starfish Collector game from previous chapters.

Your previous projects have relied heavily on the Stage class, which manages the Camera and a Batch object (for rendering purposes). To create 3D scenes , you need the “3D versions” of these objects, provided by the PerspectiveCamera and ModelBatch classes, which will be covered in detail next. However, there is no corresponding stage-like object to manage them, and so you will create your own manager class (called Stage3D) in a later section.

To render a scene, you can use one of two types of cameras: an orthographic camera or a perspective camera . (The Stage class uses an OrthographicCamera object for rendering.) The difference between these two is in how they represent, or project, a 3D scene onto a 2D surface such as a computer screen. To illustrate the difference, consider one of the simplest 3D shapes: a cube. Figure 16-3 shows an orthographic projection and a perspective projection of a cube. In an orthogonal projection , if the edges of an object have the same length, then they will be drawn as having the same length in the projection, regardless of their distance from the viewer. This is in contrast to a perspective projection, in which objects with two edges of the same length may appear different in the projection; an edge that is farther away from the viewer will appear shorter. This also has the side effect that, if two edges of an object are parallel, then they remain parallel in an orthographic projection, but they appear to converge in a perspective projection . (In a perspective drawing, the point at which all such edges appear to converge is called the vanishing point .)

When initializing a PerspectiveCamera object, you have to define the region visible to the camera, which has the shape of a truncated pyramid, or frustum (illustrated in Figure 16-4). This is specified by five parameters: the field of view (an angle that represents how far the camera can see to either side), the width and height of the rectangle onto which the scene is being projected (determined by a Viewport object in LibGDX), and the near and far values (which represent the closest and farthest distances that the camera will include while rendering).

The next new class is ModelBatch . Just as a SpriteBatch object can be used to render two-dimensional Texture objects, ModelBatch is used to render three-dimensional objects. The data needed to describe the appearance of a three-dimensional object is contained in a Model object, which consists of two major components: Mesh and Material. A mesh is a collection of vertices, edges, and triangular faces that define the shape of an object . A material contains color or texture data that is applied to the mesh; the material defines the appearance of the mesh while rendering. Figure 16-5 contains two images of a teapot: a wireframe representation of the mesh, and its appearance after applying a material. This particular teapot is a classic model called the Utah teapot , created by the computer scientist Martin Newell in 1975. Models can be loaded from standard 3D object file formats.

Models can be created in two ways in LibGDX. Using the ModelLoader class, a model can be loaded from standard 3D object file formats (such as the Wavefront format, typically indicated by the .obj file extension), which may also contain references to image files used by the accompanying material. Alternatively, some basic shapes (such as spheres and boxes) can be generated at runtime using the ModelBuilder class. You will see examples of both of these approaches over the course of this chapter.

Finally, in order to give 3D models a realistic appearance, the effects of light sources need to be considered. In fact, if lights are not added to a scene, you will not be able to see anything at all! Lights are managed by the Environment class. The two types of lighting effects you will use are ambient light and directional light. Ambient light provides overall illumination and shines equally from all directions. Typically, it is important to include ambient light in a scene so that even the sides facing away from a light source will be somewhat visible (although this amount may vary depending on the type of location you are simulating). A directional light is used to simulate light shining throughout the scene in a particular direction. This helps provide a sense of depth in a scene, in particular allowing you to distinguish between different faces when an object’s material consists of just a single color. Figure 16-6 illustrates these effects with two renderings of a cube. In the image on the left, the scene contains only ambient light, which makes it difficult to see all the edges of the cube. The image on the right has a directional light, primarily aimed toward the left (and thus the right side of the cube appears brightest).

You are now ready to create a minimal code example that renders a cube in LibGDX using the previously mentioned classes. The result is a single blue box, oriented and shaded as on the right side of Figure 16-6. To begin, create a new project in BlueJ called Project3D , copy the +libs folder (if not using the BlueJ userlib folder) and its contents from a previous project into this new project’s directory, and restart BlueJ so that the JAR files are loaded correctly. You don’t need to copy any classes or assets to this project at this time. Rather than starting with the Game class as usual (which implements the ApplicationListener interface methods), this example will be self-contained; you will implement the interface yourself.

To begin, create a new class called CubeDemo that contains the following code, which includes the core of a 3D application : import statements, variable declarations (those that are referenced in multiple methods), and the methods required by the ApplicationListener interface . As was explained in Chapter 2, the create method is used to initialize objects, while the render method handles the game loop; the code for each of these methods is presented in detail later. (The other methods required by the interface aren’t fundamental to this example and so are not discussed later.)

The create method begins with initializing the Environment and adding a parameter (a subclass of the Attribute class) that defines the color of the ambient light in the scene. In general, shades of gray are used for lights (rather than, say, colors such as yellow or blue) so that your scene will not be tinted with unexpected colors. Then, an instance of a DirectionalLight is created using a brighter shade of gray, and its direction is specified (using a Vector3 object) to be primarily to the left and downward; after configuring its parameters, the light is added to the environment. A PerspectiveCamera is then initialized, with a field of view of 67 degrees and with near and far visibility set to 0.1 and 1000, respectively (these values have been chosen to guarantee that the view area contains the object you will add to the scene). The camera’s position is set, and the location it should initially be looking toward is specified via the lookAt method . Finally, a ModelBatch object is initialized, which will be used later when rendering. These steps “set the scene” and are accomplished by adding the following code to the create method :

The next task is to create instances of models to add to your scene. For the sake of simplicity in this example, you will use the createBox method of the ModelBuilder class to construct a cube. You must also create a Material to give the cube its appearance on screen; here, a solid blue diffuse color is used. (The diffuse color of an object is the apparent color of the object when illuminated by pure white light.)

You must also determine what types of data each vertex of the model should contain: in every case, vertices should store a position, but for this example, they also store color data and a vector (called the normal vector) that is used to determine how light reflects off an object, thus providing shading effects. Each of these attributes has a corresponding constant value defined in the Usage class ; position data corresponds to Usage.Position, color data corresponds to Usage.ColorPacked, normal vector data corresponds to Usage.Normal, and so forth. When a combination of this data is needed, a value is generated by adding together the constant values for each of the desired attributes. The resulting value is passed as a parameter to the createBox method.

You also need to decide on the dimensions of the box itself. Because of the scale used by many modeling programs, these values are often in the range from 1 to 10, and so you should use similar ranges of values when creating objects with the ModelBuilder class. After creating the Model (which you can think of as a template object), a ModelInstance is initialized. This object contains a copy of the information from the model, as well as a transformation matrix that stores position, rotation, and scaling data for this particular instance. The following code performs all these tasks and should be added to the create method:

Finally, the render method is given, which is where all the phases of the game loop happen. In this case, the program consists of a static scene, so there is no user input to process nor updating tasks to be done—just rendering to perform. The code for this method should appear relatively familiar. One difference is that the glClear function also needs to erase the depth information generated during the previous render, since the distance from the camera to each object in the scene may change if the camera moves around, in which case the depth values will need to be recalculated. Another difference is that the ModelBatch takes the PerspectiveCamera as input in its begin method. The corresponding code to add to the render method is as follows:

As usual, you’ll also need a launcher-style class, as shown here:

At this point, you should try out the code. Feel free to make some modifications and rerun the code to see the effects of your changes. For example, you could alter the color of the cube, the direction of the light source, or the location of the camera.

To facilitate and accelerate the development of future projects, in this section you’ll write some classes that function similarly to the BaseActor and Stage classes, but instead store data structures and methods useful for three-dimensional graphics. For convenience, you’ll continue adding code to the previously created project, which was called Project3D.

In this section, you’ll create the game Starfish Collector 3D, which, as the name suggests, is a 3D version of the Starfish Collector game introduced at the beginning of this book; a side-by-side comparison of these games is shown in Figure 16-9. As you may expect, the goal in this new game will be to help the turtle collect all the starfish . You control the turtle using the arrow keys: pressing the up arrow key moves the turtle forward, while pressing the left and right arrow keys turns the turtle to the left and to the right. Most of the difficult groundwork has been laid in the previous section. The remaining topics include loading complex models from external files, displaying an image that surrounds the game world, and performing simplified collision detection. As before, you will continue adding code to Project3D, as it already contains many of the classes you will need (BaseGame, BaseScreen, BaseActor3D, and Stage3D).

The first task, loading a model, is relatively straightforward. To do so, you need to use an extension of the ModelLoader class, called ObjLoader , which can import 3D models from files that use the Wavefront (*.obj) file format, and then you need to use ObjLoader class loadModel method, which takes a FileHandle as input and returns a Model. You can then use the model to create a ModelInstance that you use in a BaseActor3D object, as you did for the Box and Sphere classes. Since you will be importing multiple models in this game, it makes sense to make a new class that contains this functionality. Create a new class called ObjModel that contains the following code:

Next, you will need to surround your game world with an image so as to give the appearance of a sky in the background. In the previous 2D games in this book, you created a rectangular object that simply displayed an image of the sky. Because you’re in a 3D environment, here you’ll create a spherical object that is significantly larger than and surrounds your game world, and then you will apply a texture to it, such as the one shown in Figure 16-10. This is often referred to as a sky sphere or a sky dome . You may notice that the image appears slightly stretched near the top (and it would on the bottom, too, were the bottom not simply a gray color). This is because the image has been spherically distorted: while it looks strange as a rectangle, when the image is applied to a sphere, everything will appear to have the correct proportions. This the same phenomena that occurs when trying to make a flat, rectangular map of the Earth, which is roughly spherical; the map will inevitably contain distorted areas corresponding to the regions near the poles. There is a second difficulty that will arise when trying to implement a sky dome: textures applied to the material of an object are typically only visible when viewed from the outside of the object. (This convention is to increase the efficiency of 3D programs; there is no need to render objects from a perspective that the user will not see.) Fortunately, you can perform a geometric trick to resolve this problem: after creating the sphere, you will scale the mesh by –1 in the z direction; this will cause the sphere to turn itself “inside-out,” reversing the sides on which the image will be displayed.

The third and final concept to discuss is collision detection . To keep the level of complexity manageable, the motion and placement of your three-dimensional objects will be restricted to a two-dimensional plane, thus allowing this project to reuse collision code from the original BaseActor class. This technique is well-known in game development. Games that use this approach (those that have 3D graphics but restrict game play to a 2D plane and have restricted camera movement) are called 2.5D games . Figure 16-11 illustrates how the game will appear to the player, while on the right you can see the water represented by a grid and the collision polygons that will correspond to the pictured game entities (the two rocks and the turtle).

To incorporate collision into your project, you need to make some additions to the BaseActor3D class . First, add the following import statements:

Next, add the following variable declaration to the class:

Next are a pair of methods used to set the polygon to either a rectangular or an eight-sided polygon (octagon) shape. In both cases, you need to determine the dimensions of the object in the x and z dimensions; these quantities are analogous to the width and height in the two-dimensional case. These values can be determined by calculating the BoundingBox associated with the model, which is the smallest box that contains the entire model. A bounding box stores the dimensions of the model using two Vector3 objects, min and max, which store the values of the smallest and largest coordinates contained by the model, respectively. These values are used to create the array of vertices that is passed to the polygon object, as illustrated here:

Once the polygon has been set up, you need a method that returns the boundary polygon that has been updated to take the position, rotation, and scale into account. Recall that because of the orientation of the coordinate axes, the horizontal plane contains the x-axis and the z-axis, and so these values will be used when updating the position and scale of the polygon, while the turn angle (the rotation around the y-axis) will be used to set its rotation. Add the following code to the BaseActor3D class:

Next, you need methods to detect overlap (to check if the turtle has collected a starfish) and prevent overlap (so that the rocks behave as solids and the turtle cannot pass through them). These methods, which you also need to add to the BaseActor3D class, are identical to those from the BaseActor class, except that a BaseActor3D object must be passed in as a parameter. Add the following code :

Finally, you will recreate some methods from the Actor and BaseActor classes to work with lists: getList, count, and remove. First, add the following import statement to the BaseActor3D class:

Then, add the following code to the BaseActor3D class :

At this point, the BaseActor3D class has all the core functionality you will need for the Starfish Collector 3D game. In this game, the water will be displayed using a Box object, the sky dome will be displayed using a Sphere object, and the turtle, starfish, and rocks will use imported model data from the ObjModel class. Create a new class called Turtle with the following code:

Next, create a class called Starfish with the following code. Note that the act method is being used to make the starfish rotate.

Next, create a class called Rock with the following code :

To display the number of remaining starfish in a label, you will set up a LabelStyle object as you have done previously. In the BaseGame class, add the following import statements:

Then, add the following variable declaration:

To initialize the labelStyle object, add the following code to the create method:

Now you can set up the screen that contains the actual game. Begin by creating a new class called LevelScreen with the following code:

In the initialize method, you need to set up the floor and the sky dome, which will be scaled to a very large size. You also need to initialize the turtle, as well as a number of rocks and starfish. As before, you should also set the camera position and direction so that many of the objects you have added are in view when the game begins. Finally, you should initialize the labels and add them to the user-interface table . To accomplish these tasks, add the following code to the initialize method:

In the update method , you need to check for user input and move the turtle accordingly, keeping the camera directed toward the turtle. You also need to prevent overlap between the turtle and the rock objects, and if the turtle overlaps a starfish, the starfish should be “collected” and removed from the game. Finally, you need to update the label that displays the number of starfish left, and if there are none left, display the “You Win!” message. To implement all of this, add the following code to the update method:

At this point, the Starfish Collector 3D gameplay code is complete. To play this game, you need to create a new class called StarfishCollector3DGame as follows:

Also, create a new class called Launcher3 as follows:

Now, run your project, help the turtle collect all the starfish, and enjoy the 3D graphics as you play!

This chapter may have only scratched the surface of 3D game programming, but it’s a topic that entails a lot of material. You explored the components of 3D scenes, perspective cameras, and lighting. You learned that 3D models contain meshes and materials, and that instances of models store transformation data (position, rotation, and scale) using matrices. You adapted and extended your custom game development framework to include 3D versions of actors and stages and learned the many ways you can move objects around in a three-dimensional world. Finally, you put your skills (and your code) to the test by creating a pair of interactive demo programs.

With the foundation laid in this chapter, you are now ready to create some games with 3D graphics (and 2.5D gameplay, for simplicity). A great place to start is recreating some of the earlier projects from this book. Games such as Rectangle Destroyer can be recreated simply using boxes and spheres. For other games, you will likely want to use pre-created model files (similar to the turtle, starfish, and rock). Some websites from which you can download model files (in a variety of formats) include the following:

Once you have downloaded a 3D model, and before loading it into LibGDX, you can view and modify it if desired using 3D graphics software such as Blender, which is freely available at www.blender.org , or, for the artistically inclined, Blender can even be used to create 3D models from scratch.

Once again, congratulations on finishing the final game project in this book! The next chapter concludes with some general advice and possible next steps in game development.