Cross-Platform Game Programming with gameplay3d/Getting Started

What is gameplay3d?

The gameplay3d project is an open-source, cross-platform, 3D framework that is aimed at supporting indie game developers who want to develop desktop and mobile games. The primary development language is C++, although Lua scripting is also supported.

A major motivation behind gameplay3d is to allow developers to make their games available on as many platforms as possible. It is platform-specific only where necessary, which maximises the possibility for code re-use across different platforms.

Gameplay3d is also designed to allow fast iterating and prototyping, which enables developers to realise and test ideas quickly and easily.

Prequisites

Hardware

Your hardware will need to support:

• OpenGL 3.2 (desktop); or
• OpenGL ES 2.0 (mobile)

Knowledge

A strong grasp of C++ is required in order to use gameplay3d, as is an understanding of 3D graphics principles.

Some knowledge of the OpenGL API and the GLSL shader language is very helpful, although not strictly necessary to get started using gameplay3d.

Similarly, familiarity with Lua is helpful if one wishes to use gameplay3d's Lua scripting support (although use of Lua scripting is entirely optional).

Some useful links for learning about C++, 3D graphics, OpenGL and Lua can be found in Links to other useful resources.

Using this book

If you are completely new to gameplay3d, we recommend that you begin by reading the first 4 chapters of this book (i.e. this chapter, An Overview of the Game Class, gameplay3d Design Concepts and Creating a Scene) to get an overview of how gameplay3d works. After that, feel free to skip around as required!

Installation

Regardless of which platform you are using, you will first need to get hold of a copy of the gameplay3d repository, which is hosted at https://github.com/blackberry/GamePlay

Windows

The simplest way to clone the gameplay3d repository is to:

• click on the "Download ZIP" icon on the gameplay3d GitHub page; and
• extract the files to a folder of your choice.

Alternatively, if you have git installed and want to take advantage of the version control features it offers, you can:

• open git bash in a folder of your choice; and
• run the command $ git clone https://github.com/blackberry/GamePlay.git.

The second step is to install the external dependencies on which gameplay3d relies. This is done by running the install.bat script.

The dependencies which gameplay3d uses are as follows:

• bullet - for physics
• freetype2 - for font conversion
• glew - for loading OpenGL extensions
• lua - for scripting
• oggvorbis - for compressed audio
• openal - for positional audio
• png - for image decompression
• tinyxml2 - for XML parsing
• zlib - for data decompression

The third step is to make sure that you have Visual Studio Express 2013 for Windows Desktop installed, which is free to install and use.

After cloning the repository, installing the dependencies and installing VS2013, you are ready to open the gameplay solution (i.e. gameplay.sln). Before you run any of the samples for the first time, you will need to build the gameplay3d library, which in VS2013 can be done as follows:

• Build > Build Solution (F7)

Mac

See how to install gameplay3d in mac from the internet. Let's google. It will be added here soon

Linux

This section demonstrates how to install gameplay3d on Ubuntu Linux.

First, make sure you have GIT installed. This can be done either through the Ubuntu Software Centre or by typing the following from the terminal:

sudo apt-get install git

Second, there are a number of other software packages that you need to have installed. To install these, type the following from the terminal:

sudo apt-get install build-essential gcc cmake libglu1-mesa-dev libogg-dev libopenal-dev gtk-2.0-dev curl libpcrecpp0:i386

This installs the following packages (to the extent that they are not already installed):

• build-essential - this contains contains various required tools for compiling/building software from source
• gcc - the GNU Compiler Collection
• cmake - CMake, used for managing the build process
• libglu1-mesa-dev - the OpenGL utility library development files; includes headers and static libraries for compiling programs with GLU
• libogg-dev - Ogg bitstream library development files (used for compressed audio)
• libopenal-dev - development files for the software implementation of the OpenAL (audio) API
• gtk-2.0-dev - development files for the GTK+ library
• curl - cURL, a command line tool for transferring data with URL syntax
• libpcrecpp0:i386 - a C++ library of functions to support regular expressions

Third, if you haven't done so already, use git to clone the gameplay3d repository in your desired location.

Fourth, run the following command-line from the top-level directory of your gameplay3d repository, which installs the external dependencies listed in #Windows above:

./install.sh

This script requires curl.

Fifth, build the gameplay3d library by running the following from the top-level directory of your gameplay3d repository:

mkdir build
cd build
cmake ..
make

Trying out the samples

Gameplay3d comes with a generous selection of samples. Between them, they demonstrate most of the concepts and classes found in gameplay3d. We strongly recommend that you familiarise yourself with all of the samples (particularly the "samples-browser" sample) and borrow/adapt the code in these samples in your own projects.

Windows

• Right click the sample you want to run
• Set as StartUp Project
• Debug > Start Debugging (F5)

Linux

In order to run a sample (here the "sample-browser" sample is used as a demonstration), run the following from the top-level directory of your GamePlay repository:

cd build/samples/browser
./sample-browser

Creating your first gameplay3d project

All platforms

To create a new cross-platform game project, run the script newproject from the repo root:

• newproject.bat (on Windows)
• newproject.sh (on Mac or Linux).

The following is an example of running the newproject.bat script:

  1. Enter a name for the new project.
  
   This name will be given to the project 
   executable and a folder with this name
   will be created to store all project files.
  
  Project name: test
  
  2. Enter a game title.
  
   On some platforms, this title is used to
   identify the game during installation and
   on shortcuts/icons.
  
  Title: Test
  
  3. Enter a short game description.
   
  Description: Test Game
  
  4. Enter a unique identifier for your project.
  
   This should be a human readable package name,
   containing at least two words separated by a
   period (eg. com.surname.gamename).
  
  Unique ID: org.gameplay3d.test
  
  5. Enter author name.
  
   On BlackBerry targets, this is used for
   signing and must match the developer name
   of your development certificate.
  
  Author: My Company
  
  6. Enter your game's main class name.
  
   Your initial game header and source file
   will be given this name and a class with
   this name will be created in these files.
  
  Class name: TestGame
  
  7. Enter the project path.
  
   This can be a relative path, absolute path,
   or empty for the current folder. Note that
   a project folder named test will also
   be created inside this folder.
  
  Path: samples
  
    1 file copied.
    ...

Adding and running the new project

Windows

• Add the Visual Studio project to the existing gameplay.sln solution;
• Set the "gameplay" project as a dependency (right-click on the new project, click "Project Dependencies…", and select the "gameplay" project)
• Build and run.

Linux

• Open the terminal and navigate to the "build" folder contained inside your new project folder.

• Run the following commands:

cmake ..
make

• Run the newly-created executable file, which will be found in [projectname]/build/bin/linux/.