ArduEngine: a Simple Framework for Creating Games on Arduboy

Arduboy

How I Know Arduboy

I know Arduboy when I was in college around 2014 ~ 2015, it was a Kickstarter project. I was very interested on that project since it’s a game system the size of a credit card, but I couldn’t back the project since I don’t have credit card. Moving forward to 2017 when I totally forgot about Arduboy, I attended GameStart Asia in Singapore. I found an Arduboy stand on the corner, and without any hesitation, I bought one of it, and it came with Sirene game from TeamARG.

Creating Arduboy Games

As a programmer, I tried to create my own game on Arduboy. After a few days learning, hacking code, find references, I manage to create my first Arduboy game called DanceRow, an Online Dance Game clone that was popular in Asia but without online functionality. Then when it comes to Arduboy Game Jam 2, I created 2 more games, one is Santa’s Factory, and the other is Prize Frenzy. And since I participate on that Jam, thanks to the Arduboy team, I got a free Arduboy 🙂.

What I learnt after creating my own games was, I found that I had to rewrite the same code every time I create an empty project, since we were only given 2 methods when it first created. And, most of my code structure is following what has been done by others E.g. TeamARG.

2 methods on new project from Arduino IDE

ArduEngine Came To Mind

Then I came with an idea to create ArduEngine, a simple Framework (or engine, I don’t know what’s the difference 🤔) for creating games on Arduboy. Right now, it only has basic functionalities such as write a text, draw rectangle, draw an image, basic scene functionality, and so on. But I believe that it’s enough to create many simple games on Arduboy.

You can get the project on GitHub

Warning : I only try this on Mac. I don’t know what would happen if you try it with different OS.

Create Your First Project

First, you need python installed on your computer. Go to the ArduEngine directory, then you run this command:

./ArduEngine.sh [ProjectName]

Two things to remember when naming your game, it must be:

• Alphanumeric only
• No space character

After that, ArduEngine will generate a folder with your game name. Inside that folder, will be your workplace to develop your game. It has this structure:

The structure of new project using ArduEngine

What’s Inside the Files

Once you create your first project, you’ll be given a default ArduEngine project containing ArduEngine folder, YourProjectName.ino, Images.h, SceneID.h, and SplashScreen.cpp , all of them will be inside YourProjectName folder.

ArduEngine Folder

This is the core library of the engine. What components that are available on it, will be explained on the next section.

ArduboyGame.ino

This is the main file. Note that, the name of the file is your game name, and it must match with the root folder name. This file will have 3 basic functions: InitializeScenes(), setup(),and loop() .

InitializeScenes() function

As you can see, you have to initialise all of your game scenes here. Once you create a new scene, it will automatically registered to the main engine. In the end of the line, you have to specify which scene that should be rendered.

setup() function

This will be called once when player turn on their Arduboy. I provide you with basic settings for initiate Arduboy game.

loop() function

This will be called on every frame. Take a look at this line of code:

arduEngine->Update(arduboy);

This will make Update(arduboy) on arduEngine called on every frame. it will handle all updating and rendering on all ArduEngine’s Objects.

Images.h

You have to put all of your image resources on this file.

Example of an image resource

SceneID.h

You can specify which scene is rendered by ArduEngine by telling it which scene ID that should be rendered. You have to store your scene ID in this file, then you can include it wherever you need to jump to different scene.

Example of scene ID

SplashScreen.cpp

This file is the example of ArduScene. If you want to create another scene, you can create a new file and copy & paste the template from this file. Once you create a new scene, you have to initialise it on the main file, then create an ID for that scene.

SplashScreen: an ArduScene template

What happens on this scene is, it will create an ArduSprite object, and if we go to this scene, it will show the image.

Right now, logo object is attached to the global engine, so wherever you are on any scene, it will be rendered, since currently we’re not store any information of this object belongs to which scene. Currently, the only solution is we create all objects on Load() and we remove all object on the engine on Destroy() . I’ll show you how to do it in the next post with the real game project.

ArduEngine’s Components

On the previous section, you saw about ArduSprite and ArduScene. These are the ArduEngine’s components that will be given to you to make your live easier while developing an Arduboy games.

ArduEngine’s Objects

If you’re working with ArduEngine, you’ll be given 3 basic ArduObjects:

• ArduRect : It’s basically an arduboy.rect() but, I wrap it so it’s easier for you to manipulate the object.
• ArduSprite : Again, it’s basically an arduboy.drawBitmap() for drawing an image.
• ArduText : It’s a wrapper of arduboy.print().

Every time you create these objects, it’ll be rendered by ArduEngine automatically.

ArduScene

In ArduEngine, you’ll be working on ArduScene. You can move between scene by changing the active scene ID on ArduEngine. Right now, you have to create this ArduScene template manually (Copy and paste, or type it manually), but I’ll be working on to generate it automatically.

On ArduScene, you’ll be given 4 basic methods that will be called from ArduEngine.

1. The Constructor itself: Will be called once when the game start.
2. Load(): Will be called once when we’re entering this scene.
3. Run(): Will be called every frame when we’re in this scene.
4. Destroy(): Will be called once when we’re leaving this scene.

What’s Next

Right now, I’m still working on finalising the ArduEngine, and I plan to create a simple game using ArduEngine to show you on how to use the framework. The purpose of this post is not to give documentation on how to use ArduEngine, but only for introduction about this framework.

I’ll give the update about the stable version of the framework, the documentation, and the game that using ArduEngine. For more information, you can try to create your own ArduEngine project and play around with it.

Have fun.