• # Learning How to write a 2D UFO game using the Orx Portable Game Engine - Part 1

General and Gameplay Programming

# Overview

Welcome to the 2D UFO game guide using the Orx Portable Game Engine.

My aim for this tutorial is to take you through all the steps to build a UFO game from scratch.

The aim of our game is to allow the player to control a UFO by applying physical forces to move it around. The player must collect pickups to increase their score to win.

I should openly acknowledge that this series is cheekily inspired by the 2D UFO tutorial written for Unity.

It makes an excellent comparison of the approaches between Orx and Unity. It is also a perfect way to highlight one of the major parts that makes Orx unique among other game engines, its Data Driven Configuration System.

You'll get very familiar with this system very soon. It's at the very heart of just about every game written using Orx.

If you are very new to game development, don't worry. We'll take it nice and slow and try to explain everything in very simple terms. The only knowledge you will need is some simple C++.

I'd like say a huge thank you to FullyBugged for providing the graphics for this series of articles.

# What are we making?

Visit the video below to see the look and gameplay of the final game:

# Getting Orx

The latest up to date version of Orx can be cloned from github and set up with:

git clone https://github.com/orx/orx.git

Once cloning has completed, the setup script in the root of the files will start automatically for you. This script creates an $ORX environment variable for your system. The variable will point to the code subfolder where you cloned Orx. Why? I'll get to the in a moment, but it'll make your life easier. The setup script also creates several projects for various IDEs and operating system: Visual Studio, Codelite, Code::Blocks, and gmake. You can pick one of these projects to build the Orx library. # Building the Orx Library While the Orx headers are provided, you need to compile the Orx library so that your own games can link to it. Because the setup script has already created a suitable a project for you (using premake), you can simply open one for your chosen OS/IDE and compile the Orx library yourself. There are three configurations to compile: Debug, Profile and Release. You will need to compile all three. For more details on compiling the Orx lbrary at: http://orx-project.org/wiki/en/tutorials/cloning_orx_from_github at the Orx learning wiki. # The$ORX Environment Variable

I promised I would explain what this is for. Once you have compiled all three orx library files, you will find them in the code/lib/dynamic folder:

• orx.dll
• orxd.dll
• orxp.dll

Also, link libraries will be available in the same folder:

• orx.lib
• orxd.lib
• orxp.lib

When it comes time to create our own game project, we would normally be forced to copy these library files and includes into every project.

A better way is to have our projects point to the libraries and includes located at the folder that the $ORX environment variable points to (for example: C:\Dev\orx\code). This means that your projects will always know where to find the Orx library. And should you ever clone and re-compile a new version of Orx, your game projects can make immediate use of the newer version. # Setting up a 2D UFO Project Now the you have the Orx libraries cloned and compiled, you will need a blank project for your game. Supported options are: Visual Studio, CodeLite, Code::Blocks, XCode or gmake, depending on your operating system. Once you have a game project, you can use it to work through the steps in this tutorial. Orx provides a very nice system for auto creating game projects for you. In the root of the Orx repo, you will find either the init.bat (for Windows) or init.sh (Mac/Linux) command. Create a project for our 2D game from the command line in the Orx folder and running: init c:\temp\ufo or init.sh ~/ufo Orx will create a project for each IDE supported by your OS at the specified location. You can copy this folder anywhere, and your project will always compile and link due to the$ORX environment variable. It knows where the libraries and includes are for Orx.

Open your project using your favourite IDE from within the ufo/build folder.

When the blank template loads, there are two main folders to note in your solution:

• config
• src

Firstly, the src folder contains a single source file, ufo.cpp. This is where we will add the c++ code for the game. The config folder contains configuration files for our game.

# What is config?

Orx is a data driven 2D game engine. Many of the elements in your game, like objects, spawners, music etc, do not need to be defined in code. They can be defined (or configured) using config files.

You can make a range of complex multi-part objects with special behaviours and effects in Orx, and bring them into your game with a single line of code. You'll see this in the following chapters of this guide.

There are three ufo config files in the config folder but for this guide, only one will actually be used in our game. This is:

ufo.ini

All our game configuration will be done there.

Over in the Orx library repo folder under orx/code/bin, there are two other config files:

• CreationTemplate.ini
• SettingsTemplate.ini

These are example configs and they list all the properties and values that are available to you. We will mainly concentrate on referring to the CreationTemplate.ini, which is for objects, sounds, etc. It's good idea to include these two files into your project for easy reference.

Alternatively you can view these online at https://github.com/orx/orx/blob/master/code/bin/CreationTemplate.ini and here: https://github.com/orx/orx/blob/master/code/bin/SettingsTemplate.ini

# The code template

Now to take a look at the basic ufo.cpp and see what is contained there.

The first function is the Init() function.

This function will execute when the game starts up. Here you can create objects have been defined in the config, or perform other set up tasks like handlers. We'll do both of these soon.

The Run() function is executed every main clock cycle. This is a good place to continually perform a task. Though there are better alternatives for this, and we will cover those later. This is mainly used to check for the quit key.

The Exit() function is where memory is cleaned up when your game quits. Orx cleans up nicely after itself. We won't use this function as part of this guide.

The Bootstrap() function is an optional function to use. This is used to tell Orx where to find the first config file for use in our game (ufo.ini). There is another way to do this, but for now, we'll use this function to inform Orx of the config.

Then of course, the main() function. We do not need to use this function in this guide.

Now that we have everything we need to get start, you should be able to compile successfully. Run the program and an Orx logo will appear slowly rotating.

Great. So now you have everything you need to start building the UFO game.

If you experience an issue compiling, check the troubleshooting article for Orx projects    for help.

# Setting up the game assets

Our game will have a background, a UFO which the player will control, and some pickups that the player can collect.

The UFO will be controlled by the player using the cursor keys.

First you'll need the assets to make the game. You can download the file  assets-for-orx-ufo-game.zip which contains:

The background file (background.png😞

The UFO and Pickup sprite images (ufo.png and pickup.png😞

And a pickup sound effect (pickup.ogg😞

Copy the .png files into your data/texture folder

Copy the .ogg file into your data/sound folder.

Now these files can be accessed by your project and included in the game.

# Setting up the Playfield

We will start by setting up the background object. This is done using config.

Open the ufo.ini config file in your editor and add the following:

[BackgroundGraphic]
Texture = background.png
Pivot   = center

The BackgroundGraphic defined here is called a Graphic Section. It has two properties defined. The first is Texture which has been set as background.png.

The Orx library knows where to find this image, due to the properties set in the Resource section:

[Resource]
Texture = ../../data/texture

So any texture files that are required (just like in our BackgroundGraphic section) will be located in the ../../data/texture folder.

The second parameter is Pivot. A pivot is the handle (or sometimes “hotspot” in other frameworks). This is set to be center. The position is 0,0 by default, just like the camera. The effect is to ensure the background sits in the center of our game window.

There are other values available for Pivot. To see the list of values, open the CreationTemplate.ini file in your editor. Scroll to the GraphicTemplate section and find Pivot in the list. There you can see all the possible values that could be used.

top left is also a typical value.

We need to define an object that will make use of this graphic. This will be the actual entity that is used in the game:

[BackgroundObject]
Graphic = BackgroundGraphic
Position = (0, 0, 0)

The Graphic property is the section BackgroundGraphic that we defined earlier. Our object will use that graphic.

The second property is the Position. In our world, this object will be created at (0, 0, 0). In Orx, the coordinates are (x, y, z). It may seem strange that Orx, being a 2D game engine has a Z axis. Actually Orx is 2.5D. It respects the Z axis for objects, and can use this for layering above or below other objects in the game.

To make the object appear in our game, we will add a line of code in our source file to create it.

In the Init() function of ufo.cpp, remove the default line:

orxObject_CreateFromConfig("Object");

and replace it with:

orxObject_CreateFromConfig("BackgroundObject");

Compile and run.

The old spinning logo is now replaced with a nice tiled background object.

Next, the ufo object is required. This is what the player will control. This will be covered in Part 2.

Report Article

## User Feedback

You need to be a member in order to leave a review

## Create an account

Register a new account

Great tutorial, I have been using ORX for a long time now for my hobby projects, it takes a little while to get used to the config files, but it is most definitely worth it.

I remember the first time I used ORX for a project, after I got hold of the config files, I added particle effects (the game had four elemental arrows, each required different particles and each particle had some extra effect - rotating and scaling, for instance) and death effects (enemy blinking + disappearing) to my game in a couple of hours.

ORX also has a very active community and any questions get answered pretty fast.

• 0
• 24
• 0
• 1
• 0

• 26
• 11
• 9
• 9
• 11
• ### Similar Content

• I am curious, if anyone would be interested in an RPG Adventure in a visual novel art style?
I loved Doki Doki and if I could create something in an RPG element, that would be THE BEST.
I am a complete noob however, that is the thing. Like I just started adventuring into coding two weeks ago. I love it so far.
I think I may be addicted. oof. Which is why I want to create something I have that itch. lol.
Basically if anyone who wants to pitch in for free, or not I'd be glad to include them in the credits section.
Also, I'd love to get the community involved in this, to create more fun RPG-esk things if that makes sense.
Where would I go for that?
• By komires
We are pleased to announce the release of Matali Physics 4.4. The latest version introduces comprehensive support for Android 9.0 Pie, iOS 12.x and macOS Mojave (version 10.14.x). Latest version also introduces Matali Render 3.4 add-on with normal mapping and parallax mapping based on the distance from the observer as well as other improvements and fixes.
What is Matali Physics?
Matali Physics is an advanced, multi-platform, high-performance 3d physics engine intended for games, virtual reality and physics-based simulations. Matali Physics and add-ons form physics environment which provides complex physical simulation and physics-based modeling of objects both real and imagined.
Main benefits of using Matali Physics:
Stable, high-performance solution supplied together with the rich set of add-ons for all major mobile and desktop platforms (both 32 and 64 bit)  Advanced samples ready to use in your own games  New features on request  Dedicated technical support  Regular updates and fixes

View full story

• I'm what you might consider a "casual prosumer" when it comes to commenting. I comment important stuff, but only if the code isn't written in a self-explanatory way. Which is why I've also adapted a really simple and descriptive naming scheme and done away with any and all notation systems.
That being said, there are occasions where I want to either document a whole system of code or provide a summarized walk-through on a per-function basis. This is where I find myself in a frustrating spot since none of the solutions on the market seem to be quite for what I want. So I figured I'd list things I want to achieve and what I want to avoid in hopes that I'm either not familiar with something or perhaps am simply not configuring stuff properly.
I'm willing to pay for a good solution.
The dream wish list of things I want and need:
full documentation generation, a la Doxygen a non-verbose (lightweight) and non-monolithic style non-XML style markup (eg the way Natural Docs does it, not Doxygen) no block comments in documentation (I use block comments extensively to manage code flow during development) partial documentation (I really don't want to provide an explanation for each and every argument and return type) a concise format with a clear layout, so no \param and \return shenanigans automatically filled in for me no duplication of obvious information (eg the function name) in the comments inline documentation no explicit flow direction (in/out/inout) in documentation, but rather taken directly from code - I already provide this information! proper macro expansion I've tried Atomineer and it doesn't work for me at all. So far the Doxygen style in general is pure bloat in my eyes since it becomes bothersome to maintain as soon as you make something as simple as a name change. Allow me to demonstrate by example:
Here's what a typical function in my code might look like:
_BASEMETHOD ECBool OnInitialize( IN MODIFY ResourceType& object, IN const char* type, OPTIONAL IN ISignalable* signalable = nullptr, OPTIONAL IN uint32 flags = 0) const { ... } _BASEMETHOD expands to 'virtual'. Atomineer doesn't handle this too well since it is adamant about placing the documentation below that line unless I take care to actually generate it on the word _BASEMETHOD itself.
Here's the default "trite" Atomineer generates:
/// Executes the initialize action /// /// \author yomama /// \date 12-Dec-18 /// /// \tparam ResourceType Type of the resource type. /// \param [in,out] {IN MODIFY ResourceType&} object The object. /// \param {IN const char*} type The type. /// \param [in,out] {OPTIONAL IN ISignalable*} signalable (Optional) If non-null, the signalable. /// \param {OPTIONAL IN uint32} custHandlerFlags The customer handler flags. /// /// \return {ECBool} An ECBool. This is close to being the least useful way to say what the function actually does. None of the auto-generated stuff makes sense, because it's already obvious from the names. In addition, data flow direction is assumed, not extrapolated from markup that already exists in the code (notice the in/out of signalable while certain conditions might force me to accept a non-const pointer, which is nevertheless never written to). The return type is obvious. Even the general description is obvious to the point of being insulting to the reader.
Of course this is all meant to be manually edited. However, the problem is that:
1) on the one hand, writing this stuff from scratch using this style of markup is time consuming and annoyingly verbose.
2) auto-generating the template and editing is also time consuming, because again, it's way too verbose.
Here's what an ideal way of commenting the above function looks to me:
/// Fill \p object with data and notify \p signalable once the procedure is complete. Runs asynchronously. _BASEMETHOD ECBool OnInitialize( IN MODIFY ResourceType& object, IN const char* type, OPTIONAL IN ISignalable* signalable = nullptr, /// Type-specific flags. See documentation of related resource type for possible values. OPTIONAL IN uint32 flags = 0) const { ... } That's it. This should be enough to generate feature-complete documentation when the docs are finally built. AND it's easy to read inline while writing code.
A major hurdle is that while I actually kinda like the Natural Docs style, to the best of my knowledge it's only able to generate documentation for things that have actually been manually documented. Facepalm. So no automatic full documentation of classes, inheritance diagrams, etc. This seemingly forces me into using Doxygen, which is much more feature complete, but suffers from the abovementioned stylistic bloat and for some reason cannot handle relatively simple macro expansions in imo-not-so-complicated cases. I simplified the following from a real world example, but this includes auto-generated class implementations, eg:
BEGIN_DEFAULT_HANDLER(foo) _BASEMETHOD const char* bar() const _OVERRIDE { return "yomama"; } END_DEFAULT_HANDLER(foo) which might expand into something like ---------> class foo : public crpt_base<foo> { base_interface* GetInterfaceClass() const _OVERRIDE { _STATIC foo_interface if; return &if; } _BASEMETHOD const char* bar() const _OVERRIDE { return "yomama"; } }; extern "C" _DLLEXPORT base_class* _fooFactory() { return static_cast<base_class*>(new foo); } Doxygen doesn't even recognize foo as a class.
The bottom line is it seems to me I shouldn't be asking for too much here. I'd really like the clear coding style I've adopted to pay off in more than just the code.
What's your approach? Any suggestions? Ideas or alternative options to explore?
• By komires
We are pleased to announce the release of Matali Physics 4.4. The latest version introduces comprehensive support for Android 9.0 Pie, iOS 12.x and macOS Mojave (version 10.14.x). Latest version also introduces Matali Render 3.4 add-on with normal mapping and parallax mapping based on the distance from the observer as well as other improvements and fixes.
What is Matali Physics?
Matali Physics is an advanced, multi-platform, high-performance 3d physics engine intended for games, virtual reality and physics-based simulations. Matali Physics and add-ons form physics environment which provides complex physical simulation and physics-based modeling of objects both real and imagined.
Main benefits of using Matali Physics:
Stable, high-performance solution supplied together with the rich set of add-ons for all major mobile and desktop platforms (both 32 and 64 bit)  Advanced samples ready to use in your own games  New features on request  Dedicated technical support  Regular updates and fixes