Getting Started with GamePlay3D under Mac OSX

I've been researching different game engines to use with our teaching next year. Of the many engines gameplay3D stood out for a number of reasons.

1. Open Source
2. Written in C++ and Lua scriptable
3. Works under Mac, Linux, Windows and mobile devices

This blog post is going to talk about the basic setup under mac osx and how to start a basic project, In this case I'm going to use xcode, however I do also have a basic qt creator project as well which I may do in another blog post.

Downloading the source

I'm going to download the source using git into my main root directory as this will make paths easier. To do this I do the following

cd
git clone https://github.com/blackberry/GamePlay.git

This may take a while but once it is done you should have a new directory called $(HOME)/GamePlay. Now we have to download the external dependancies. This is done via a script called install.sh Change into the GamePlay directory and run this script. This will take a while as it is quite a large file but it will download pre-built libs for all the platforms. Under mac osx these are built as 32bit static libs and may cause problems if you wish to link against other 64bit libs and I will do another blog post at a later date on how to build and link your own 64 bit version of the library but it is quite an involved process. In most cases the 32bit pre-built lib will be fine.

Compiling with xcode

Now we can open the xcode workspace (gameplay.xcworkspace) and configure and build the main gameplay static library.

To make development easier I'm going to setup the targets to build the library in the same root GamePlay directory. To do this we do the following first goto File->Workspace Settings in the xcode menu

Choose WorkSpace relative as shown below

Now we can build the library and the final lib should be placed in the directory GamePlay/DerivedData/gameplay/Build/Products/Debug. This actually builds a mac framework that we can copy into some other directory to use in our own projects. However for now we will leave it as it is.

Creating a new project

Gameplay comes with a newproject script that will copy a template project to a new location. Again I have modified this to make it easier to create new projects in directories other than the main GamePlay one. 

In an editor open up the GamePlay/newproject.sh script look for each instance of the cp command like this

cp "template/template.vcxproj" "$projPath/$projName.vcxproj"

Where it says "template/ we are going to pre-pend the path of the GamePlay install so in my example it's going to be $HOME/GamePlay/

cp "$HOME/GamePlay/template/template.vcxproj" "$projPath/$projName.vcxproj"

Do this for every cp command in the script.

Now this is done we can create a new directory to put our demos in. In my case I've created one called GamePlayDemos

mkdir GamePlayDemos
cd GamePlayDemos
~/GamePlay/newproject.sh

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:


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: ncca


5. Enter author name.

   On BlackBerry targets, this is used for
   signing and must match the developer name
   of your development certificate.

Author: jm


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: Test


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:./

Once the script has run you should see a folder like this

Now we can open the Test.xcodeproj file and get ready to build the demo. First we need to change the search paths for headers. By default they look like this

We need to add $(HOME)/GamePlay to each of these paths (or the directory you installed it into)

This will now allow the project to compile, however we still need to set the linker paths and do the same path addition

Add $(HOME)/GamePlay to the ../ paths as shown

Finally we need to add an additional path for the libgameplay.a location this can be done by selecting the build options and removing the original reference and locating the one we built earlier in the DerivedData directory as shown

The program should now run and give you the following screen.

I will do some more blog posts soon on using the game engine with maya.