Beginners guide into game development using the
Gameplay3D game engine framework


Gameplay3D is an open-source, cross-platform, 3D engine that is aimed at supporting indie game developers who want to develop desktop and mobile games.
Gameplay currently supports:
    BlackBerry 10 and BlackBerry PlayBook 2.0
    Apple iOS 5.1 for iPhone and iPad
    Google Android 2.3+
    Apple Mac OS X
    Microsoft Windows
    Linux

Unofficially it also supports more because it’s open sourced.
IE: linux ARM devices like openpandora, the Linux single-board computers like the Raspberry Pi, beagleboard, Arduino etc and phones like the Nokia N9 & N900
Windows phone support has been done by somebody in the community.

Gameplay3D is mainly targeted at mobile devices and this is the lowest common denominator.
This means no advanced GPU features like dynamic shadowing, geometry shaders etc.

On the up side, Gameplay3D has a flexible interface for mobiles/tablets already built in!
This includes virtual gamepad (joysticks and buttons), gestures and basic User Interface (forms/tick boxs/radio buttons/buttons/sliders etc) - see all the features on their site.
Some game engines which target mobile do not implement these, leaving the developer to reinvent the wheel!

Below are some images from Gameplay3D samples:
Mobile-UI.png
sample06-racer.jpg

Not in the samples:
demo-survive-shooter.jpg
Click to enlarge.

The engine is led by Sean Paul Taylor, sgrenier and dgough from RIM’s Blackberry.
With contributions from the community.
Obviously, the benefit for RIM is that they will hopefully get your game on it’s Blackberry devices too!
There is no requirement for the game developer to be on BB devices nor to advertise their engine.
However, there are minor parts of Gameplay3D which haven’t been completed for iOS nor Android while BB’s implementation is there.
For example gamepad support, here is the open issue listing.
I guess this is fair enough, as they don’t work for iOS nor Android so the community can step in and submit these.

The source code is hosted on RIM’s github
With two branches, master(Current release) and next(Future release).

It doesn’t have all the flashy bells and whistles of more larger game engines.
It currently has no editor (like Unity 3D), instead adopting the philosophy that the 3d creation tool is the game editor.
This means, you are relying on your asset creation package for assets but also scene (level) design/layout etc.
This is actually very intuitive and closer to how larger game companies create their levels using Maya (bigger companies develop their own tools & formats).

If you interested in Gameplay3D, here is a good video intro:

And also watch this GDC presentation by the creators for a lower level understanding.

Let’s start by looking at 3D asset creation.

Gameplay3D Assets creation (FBX)

Gameplay3D uses the Autodesk FBX file format as its source for 3D assets.
This is good and bad.

The Good

  • It’s an industry standard, inter-application format - support for animations, materials, lights, cameras etc
  • It’s maintained and updated regularly by Autodesk
  • It has an free* and open* SDK - There’s restrictions like no redistribution of the SDK binaries (library only).
  • FBX naturally support scene graphs- which Gameplay3D is designed around.

The bad

  • It’s not free and open sourced, FBX file format is proprietary.
  • Not all 3D application fully support FBX export ie: Blender

So why doesn’t Gameplay3D use Collada, an open standard?
The arguments for and against are well documented and can be found on google.
Basically, Collada started as a good idea but it wasn’t clear in it’s specifications resulting in different implementations between applications, resulting in failing at what it was meant to achieve - An application interchange format.
Also it hasn’t been maintained for many years now.

How to get good FBX support?

From blender?
You’ll need a .blend format converter like unwrap3d (I haven’t tested this).
Or blender’s .dae export to .fbx via autodesk’s free convert, which works but with with issues (not recommended).
Both of these solutions are not 100% reliable but better then blender’s FBX support.

Indie doesn’t mean free!
Blender is great value for sure! but it’s not dependable for FBX.
Unity3D has great .blend support because it imports the .blend file and automatically converts it to a FBX file internally.
If you are a blender artist and your client asks you for 2012/13 FBX format (non unity3D) assets, would you take that work?

Other software?
There’s a lot of 3D authoring packages!
The better ones are usually paid for because it’s maintained and supported.

If you are a programmer (indie/hobbyist games programmer) and doing blocking out and basic animation (programmer art) you still need excellent FBX support.
I can recommend shade3D for unity for programmer art - it’s free! but has no normals on FBX export.
Shade3D basic has no FBX limitations for only $100USD, texturing is included in standard.

FBX support is a overall a good thing because it’s a clear, well supported, industry standard file format.
I wrote a detailed overview on Gameplay3D asset creation with Shade3D for Unity.

3D game development for beginners

Gameplay3D is based on Open GL and Open GL ES for mobile/tablets.
It’s programmed in C++.

Gameplay3D is a great cross platform framework and I recommend it if you know:

    [1]. Programming (C/C++/C#/Java etc not Visual Basic, scripting etc)
    [2]. Basic 3D Programming (vectors/matrices/local/world etc)
    [3]. Game design/programming (level/asset/AI/Logic/Patterns etc)

If you don’t understand these at a fundamental level you will most likely struggle just like I did… and still do.
So I decided to document my process here.
I’m a java/C programmer with some experience with #1 & #2 and none at #3 (Net Yaroze) but I’m no expert!
I recommend actually buying a good book, each on the above 3 points above, especially 2!
Or Google is your friend.

#1. Programming C++
It’s critical to understand C++ at an advance level!
Gameplay3D is very heavy on:

  • STL Templates/Containers etc.
  • Polymorphism, inheritance etc.
  • Namespaces.
  • Custom class for multi-platform support.

C++ guide:
http://www.informit.com/guides/guide.aspx?g=cplusplus

Moving From Java to C++:
http://people.eecs.ku.edu/~miller/Courses/JavaToC++/JavaToC++.html

C++ tutorial for C users:
http://www.4p8.com/eric.brasseur/cppcen.html

#2. Basic 3D Programming
Gameplay3D assumes the user has 3d programming experience, so it’s not for beginners.
Most of my issues have been because of lack of 3d programming experience.
Google ‘3d programming theory’ to find resources.
This mostly involves not understanding the maths, but knowing what maths function to apply to get your expected results.
Read wolfire’s blog for a good example.

#3. Game design/programming
There’s a lot of information on games programming.
Gameplay3D design is very similar to DirectX 9, I have and recommend:

I can also recommend the DigiPen youtube videos.

Gameplay3D development

Now you know the basics above (C++, 3D & games programming) you are ready to start in Gameplay3D development.

I recommend this process to start with:
First choose your 3D Asset tool wisely, are you a programmer or 3D artist or both?
Even programmers need block out objects/animation, programmer art.
Which tool has the best and reliable FBX support? Blender doesn’t.
What features does it use? and what is the learning curve?
Develop a good asset workflow early.
See Gameplay3D asset creation with Shade3D for Unity here.

Next, set up your Development environment (see wiki).
Make sure you can drill down into classes/functions/headers etc.
Generate the doxygen API docs and integrated it into your IDE.
This way you can get help on a method/class by pressing the F1 key.

Start development by following these steps:
[1]. Read ALL of the wiki: setting up, Development Guide and File Formats Reference.
[2]. Step through all the code samples, step into Gameplay3D where your not sure what it’s doing.
[3]. Goto 1, repeat until you know what each line of code in each sample is doing.
[4]. Create your new project.
[5]. Incrementally add features from samples and add your own assets.
[6]. Develop your workflow, between asset creation tool and Gameplay3D, ie export scripts, .GPB building and viewing batch files.
[7]. Refer to the source code for help, stepping into Gameplay3D.
[8]. Search the forum for help - Someone has already asked the same question ie: black screen, blender issues etc.
[9]. Don’t waist peoples time with obvious questions, or questions that get repeated in the forums.
[10]. post a question.

Update: 4th Jan 2013: Common Gameplay3D beginner issues

Gameplay-Encoder issues

The encoder is used to convert from FBX to GPB.
It’s a separate program in the BIN folder, the source code is available for debugging and compiling.
Read the encoder’s wiki here.

If the encoder creates the GPB it’s not necessarily correct.
The encoder doesn’t have any error checking and assumes the FBX has been created with the official FBX SDK.
Blender doesn’t, it uses a python script which is reversed engineered from the official SDK.

Next, you run your gameplay3D executable to load your GPB file.
Three things will likely happen:
1. It throws an exception error

Unfortunately the wiki page is only maintainable by the Gameplay3D admins and there is a bit of information missing.
For example there’s a -m option which creates your .material file.
This file tells gameplay3D what shaders, uniforms, samplers and renderState etc to use on each object.
If this file is missing or incorrect you will see an error like this:

readProperties — Error reading line from file.
Assertion failed: (0), function readProperties
gameplay/src/Properties.cpp, line 142.

The best way I found to figure out the errors is by stepping through the code.
This is a pain but a valid exercise especially when trying to use FBX created from programs which don’t use the current FBX SDK ie Blender, Fragmotion etc.

2. Black window
If your executable runs but you get a black window, this means you have either:
[1]. A light issue, what type of light are you using? where are your lights? is it pointed correctly?
[2]. A material issue, Is the texture correct? is the shader correct? Render State? Techniques? etc.
[3]. A camera issue, where is your camera? is it pointed correctly?

3. Display 3d Object
Profit! :)

Useful links

Gameplay3d:
Gameplay3d wiki
Gameplay3d forum
IRC: #gameplay3d on freenode server.

Free models:
http://thefree3dmodels.com
http://www.texturequalitypro.com/

Game info:
http://wiki.polycount.com/

Game design:
http://www.youtube.com/watch?v=fZyy-sEL7H8
http://www.kuro5hin.org/story/2005/7/28/235328/642

Screen recorders, to share your work or problems :/
http://camstudio.org/ or
http://www.fraps.com/ (better for directx)
recordmydesktop (linux)

That’s it for now, hope this helped.

Comments now disabled.
For comments or questions, please post on twitter @mgarcia.