## Thursday, 20 February 2014

### GamePlay 3D 101

Another Guest post on my Blog, this time from Callum James and Ramesh Balachandran from the BSc. Software Development for Animation, Games and Effects course at the NCCA

## What is Gameplay 3D?

Gameplay 3D is an open-source, code based engine that is aimed at being cross-platform compatible. We decided to use this engine over others as we would have the most control over the features and optimisations of the program / game we create. Whilst giving you the tools to produce a simple piece of high quality in relatively little time, other game engines such as the Unreal Development Kit , are restrictive to their scripting functionality and UI interaction. Therefore, by using an open-source engine that has an established rendering engine, we are able to extend upon and create a new version of the engine in our own desired way.

## Our Preferred Gameplay 3D Setup There are multiple ways you can use the Gameplay 3D engine on different platforms. By default, the engine comes with source and project files for Visual Studio on Windows and an XCode project for MacOSX.  It is then up to you to get an environment set up for a Linux build. However this makes it a little cumbersome to be easily platform independant for efficient development. We however have come up with a simple solution to make it as easy as possible to pass your project between all three major platforms and quickly get up and running for development. Whilst it would be ideal to have a single development project for all three platforms, due to our desire to support not only Windows 7 but also Windows 8, we have had to separate the Windows build to its own Visual Studio project. For Mac and Linux, we then have a single Qt Creator project (.pro file) that very easily compiles and runs on both of the Unix flavours. As the VS project file and the Qt project files all read from the same sources, cross platform development is still quick, easy and affects all platforms. To ensure this works however it is important to keep a strict directory hierarchy to your project so that no file gets lost and you keep independant local file paths to a minimum.  Following is a quick overview into how to set up Gameplay 3D on each of the three major platforms in the way we have discussed here.

### Setting up Gameplay 3D on Unix - Linux and MacOSX Setting up Gameplay 3D to work on a Unix platform (either Linux or MacOSX) using Qt Creator, there are a few things you need to make sure are set and linked correctly. Here we will discuss what you need to ensure is set correctly and included in the .pro file so that your project will build and run successfully. The first thing you need to look at is your include and library paths. You need to ensure that your include paths are at least set to ./include to pick up on your header files.  Other directories to include are:

INCLUDEPATH += $$GAMEPLAY_DIR/gameplay/src INCLUDEPATH +=$$GAMEPLAY_DIR/gameplay/src/lua
INCLUDEPATH += $$GAMEPLAY_DIR/external-deps/bullet/include INCLUDEPATH +=$$GAMEPLAY_DIR/external-deps/lua/include
INCLUDEPATH += $$GAMEPLAY_DIR/external-deps/oggvorbis/include INCLUDEPATH +=$$GAMEPLAY_DIR/external-deps/png/include

Libraries to link up to for your projects are as follows for Linux:
unix:!macx{
LIBS += -L$$GAMEPLAY_DIR/external-deps/lua/lib/linux/x64/ -llua LIBS += -L/usr/local/lib -lBulletCollision -lBulletDynamics -lLinearMath LIBS += -L$$GAMEPLAY_DIR/external-deps/glew/lib/linux/x64/ -lGLEW
QMAKE_CXXFLAGS += $$system(pkg-config --cflags gtk+-2.0) LIBS += -lgtk-x11-2.0 -lglib-2.0 -lgobject-2.0 LIBS += -L$$GAMEPLAY_DIR/external-deps/oggvorbis/lib/linux/x64/ -lvorbis -logg
LIBS+=  -lrt -ldl -lpng -lopenal -lz -pthread -lGL -lX11
}

And for MacOSX:
macx:{
INCLUDEPATH+=/usr/local/include/
LIBS+= -L/usr/local/lib -lBulletDynamics  -lBulletCollision -lLinearMath
LIBS+= -L/usr/local/lib -lpng
LIBS += -L/ext-deps/fmod/lib/macosx -lfmodex
LIBS += -framework Cocoa -framework GameKit -framework IOKit -framework QuartzCore -framework OpenGL -framework OpenAL
LIBS+= -llua -lvorbis -lvorbisfile -logg -lz  -ldl -lpthread
}

These are all the include paths and libraries you will need to get started. It is however important to note on Mac, you need to make sure you are linking against the right architecture for your build. The external dependency libraries supplied with the Gameplay 3D library are all 32 bit so if you want to build 64 bit projects you will need to recompile the external libraries as 64 bit and then link to these. You will the need to include in your .pro file the following:
macx:QMAKE_CXXFLAGS+= -arch x86_64
macx:CONFIG+=x86_64

Secondly, local path set-up is vital to ensuring your project will run on all platforms without having to go through and change all of the paths to files and assets. The paths differ due to the way that the game is built on different platforms. On Linux (and Windows) it is built as a simple executable. Gameplay 3D built on OSX however utilises the MacOSX app bundle feature. When compiling on Mac, the application will be built into the directory ./application_name.app/Contents/MacOS. This is also where it will be run from. However because the executable is run from here and not the root directory, any assets it requires are no longer visible to it. As such, all the required assets need to be copied into the correct directory for the application to find them. On Linux and Windows, this is simple as the executable will look from assets in a res/ folder from the root directory. So within your root directory as long as your assets are stored within a res folder, you will be fine. However on Mac, the files you require for the game need to be copied into the Resources folder into a folder called res. The gameplay engine will then pick up on these resources. The config files also go into the Resources folder (but not the res) folder. These can then be picked up and read by the application when run. In the .pro file, you just need to ensure all the files you require are passed to QMAKE_BUNDLE_DATA. So for example, to copy some splash screen images to the correct directory and use them with a local path, you need the following in your .pro file:
SPLASHIMAGES += res/splash/logo_powered_white.png

macx:{
APP_SPLASH_IMAGES.path = Contents/Resources/res/splash
APP_SPLASH_IMAGES.files += SPLASHIMAGES

QMAKE_BUNDLE_DATA +=  … \
APP_SPLASH_IMAGES \
… \
}


Any other files you need also need to be added to QMAKE_BUNDLE_DATA in this manner, so for example to also add audio files, use:
QMAKE_BUNDLE_DATA +=  APP_AUDIO_FILES \
APP_SPLASH_IMAGES \
… \

The Gameplay engine will automatically pick up on them when located in this directry, but anything you write yourself using paths needs to be prefixed. Adding ../Resources/ to the front of any local paths used in your code will ensure your game looks into the right folder on Mac. To automatically do this, we have developed a very simple function as below:
#ifdef DARWIN
#define PATH_PREFIX "../Resources/"
#else
#define PATH_PREFIX ""
#endif

std::string GeneralUtils::PLATFORM_FILE_PATH(std::string _path)
{
return (PATH_PREFIX+_path);
}

The DARWIN define is set within the .pro file if the macx platform is detected, as follows:
unix:!macx: DEFINES += LINUX
macx: DEFINES += DARWIN

If this is all set up correctly, then local paths will work on all platforms without any need to change them.

### Setting up Gameplay 3D on Windows

The setup for programming with Gameplay 3D on Windows differs slightly from the Unix build. Due to the current operating system used for development on Windows (Windows 8.1 64-bit), there were issues in setting up Qt Creator to enable complete cross-platform programming. The IDE of choice was shifted to Visual Studio 2010. In order to set up the project to work with Unix build, the Visual Studio project settings need to be set up to correctly link to the Gameplay3D libraries as well as the correct Windows external dependencies. To make sure this is done correctly, the engine needs to be built using the Visual Studio project file accompanying the engine. The Gameplay3D files are compiled for a 64-bit architecture of Windows to work alongside the 64-bit architecture setup of the OSX and Linux builds. Once this is compiled, the Visual Studio project needs to correctly link to the engine header files as well as the necessary external dependency files. This is done under Project -> Properties -> Configuration Properties -> C/C++ in the ‘Additional Include Directories’ section. In this section, the paths to all of the header files would be added:
../../external-deps/lua/lib/windows/x64
../../external-deps/bullet/lib/windows/x64
../../external-deps/openal/lib/windows/x64
../../external-deps/oggvorbis/lib/windows/x64
../../external-deps/glew/lib/windows/x64
../../external-deps/png/lib/windows/x64
../../external-deps/zlib/lib/windows/x64

### 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

Author: jm

6. Enter your game's main class name.

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.

## Saturday, 11 May 2013

### GLSL tessellation Shaders under Mac OSX

So this interesting post appeared the other day saying that tessellation shaders were working  on Mac OSX. According to the documents and other things like GLView this is not the case.

I decided to spend the day investigating the claims to a) see if they were true, and b) see how I could replicate this in my own library.

The following video shows how I used the Mac OpenGL profiler to dig into the source code and find out how to do this.

The main code elements you need are the following defines

#ifdef DARWIN
#endif
#endif
#ifndef GL_PATCHES
#define GL_PATCHES 0x0000000e
#endif
#endif

Once this has been defined somewhere you can use the default OpenGL commands to create a shader, I chose to use the demo code / shader here the main thing to remember is that you must use GL_PATCHES to draw to the tessellation units.

The other problem is that code like
glPatchParameteri(GL_PATCH_VERTICES, 16);

is not available as the glPatchParam functions are not exposed, the good news is that you can set all of this in the shader so it is not too much of an issue. The updates have now been rolled into the core ngl library, and I will add some demos soon.

## Friday, 3 May 2013

### Install NGL / Qt on a new Mac

This video blog shows how to install all of the NGL environment on a brand new mac running Mountain Lion. The links to download qt are here and the main configuration for ngl etc is here.

This is how I set the alias for qt creator
export PATH=\$PATH:/Users/jmacey/Qt5.0.2/Qt\ Creator.app/Contents/MacOS
alias qtcreator='Qt\ Creator'


Next you need to follow the instructions here to install and setup NGL, you will need to install bzr which is a simple package from here.
Finally this example shows how to build the Qt 5 version of NGL and a basic demo