Intro to Cactus2D Game Engine


In this post, we will present the main features of Cactus2D, an engine provided by the brazilian studio Sertão Games to assist the development of PC and Android games. Cactus2D employs a sophisticated model for the composition of objects that represent the elements of a game, implementing features that enable the creation of games for modern devices such as tablets and smartphones. It also supports the use of advanced data entry, such as touchscreen and accelerometer. Moreover, the rendering engine encapsulates libraries, physical simulation and assets pipeline in a game object component-driven model.Thus, the developer can be focused on creating the game itself, since Cactus2D allows the combination and reuse of resources to implement many of these games increasingly diverse. In addition, the developer can also use his creativity to make custom components according to his needs, just extending the available components, obeying the object model that will be explained later.

The Cactus2D is available to download from Google Code.

The Cactus2D Object Model

In the development of a game, it is necessary to represent all the elements that are part of it. These elements are called game objects, which can be characters, weapons, vehicles, among others. However not all the game objects are likely to be viewed on screen, because some are invisible and only serves to control. The game objects are the real entities of the game, because they suffer events and perform actions.

In addition to the game objects, it must also be set the different behaviors of each one of them. For this reason, some engines use an object model based in inheritance / specialization. In this model, shown in Figure 1, the classes that represent game objects must inherit from a core class, often called GameObject. Thus, a game object can be seen as a reusable container of features and basic attributes such as position and orientation, for example.

Figura 1. Inherated/Specialization Model of Game Objects.

For more specific objects, this approach requires the creation of subclasses to implement the specific features. Thus, when we need to model more complex objects, we get stuck on inheritance, since some objects need to inherit from more than one class, thus requiring a model with multiple inheritance, as shown in Figure 2. Not very often you need to have the same behaviors in game objects that are on different sides of the class hierarchy, and in addition, good practice guidance to the objects do not recommend overuse of inheritance due to various problems of reuse that entails.

Figure 2. Multiply Inherated in Inherated/Specialization Model.

For more specific objects, this approach requires the creation of subclasses to implement the specific features. Thus, when we need to model more complex objects, we get stuck on inheritance, since some objects need to inherit from more than one class, thus requiring a model with multiple inheritance, as shown in Figure 2. Not very often you need to have the same behaviors in game objects that are on different sides of the class hierarchy, and in addition, good practice guidance to the objects do not recommend overuse of inheritance due to various problems of reuse that entails.

Figure 3. Componentization Model of Game Objects.

In this model, it is possible to add and remove behaviors to a single game object, even at runtime, and also combine different behaviors. This last feature is what avoids the need of multiple inheritance and keeps the model closer to the real world, so that any object can have specific and / or common features, if compared to other game objects. In the example of figure 3, if it was necessary to instantiate an object of the car type, but with the behavior of rocket (a rocket car), we just add two components to the game object in use. This does not prevent them from having an object only with the car behavior and another object with only rocket behavior.

Cactus2D is a game engine that uses this componentization concept. It comes with several reusable components, but there’s also the possibility for the developer to create his own components, for any game can require specific components. There’s a class called GameObject that has a list of objects of the type Component. Every new behavior / feature that the game should require must extend the Component class. Yet every component inherits methods that are responsible for the game loops (update, physicsUpdate and render, for example). So, Cactus2D takes the responsibility of updating the game objects, receiving the player inputs, checking up the physics and rendering the changes.

Cactus2D Components

Cactus2D comes with several classes that represent reusable components which are very useful for most games. Here is a brief explanation about each one of these components.

SpriteRendererComponent: Component responsible for applying a texture on a game object by loading files that contain sprites.

AnimationComponent: Based on the sprites loaded with the SpriteRendererComponent, the AnimationComponent defines the animation settings for the game object, such as frequency and sequence of the sprites to be rendered.

PhysicsComponent: For every object that should interact with other objects and need to simulate real world physics, this component must be added.

TileMapComponent: Component responsible for loading and handling tilemaps on a game scene.

ButtonComponent: Defines a button that can be instantiated with two images (one to represent the button unpressed and the other to be rendered when the button is pressed).

LabelComponent: Component that draws a label on the screen based on the *. fnt file created for the game.

TouchComponent: Captures the game inputs on the touchscreen.

TransformComponent: Encapsulates the x, y and z coordinates of the game object’s position.

BoxCollider: Delimits a region to represent the physical area occupied by a game object.

Each one of these components can be added to the various objects of the game. For example, in a certain game we have a character who must jump over some obstacles to avoid colliding with them. In this case, the components to be used will be SpriteRendererComponent, AnimationComponent, PhysicsComponent and BoxCollider. With SpriteRendererComponent added to the game object (the character), you can define the file which contains the texture of the character to be rendered, with AnimationComponent you can define what is the range of sprites that appear in each animation. In addition, you also need to define the physical object that represents the character and the objects that represent the obstacles. For this, the PhysicsComponent and BoxCollider components should be added to each object that need to simulate physical collision.

Depending on the game, sometimes we need to customize specific components. For instance, now let’s imagine that our character must collect scores by touching some special obstacles. In this case, a customized component must be created to implement this specific need. This component should have a counter to store the scores and also other features to be decided according to the game’s need.

In fact, every game can be implemented using a library of reusable Cactus2D components added to the specific components that the game requires. Thus, the game will have objects with behaviors that interact with each other.


This is another important concept implemented in Cactus2D. Level is how the game phases and screens are known. Each menu, each splash screen, each scene is represented by a level. In games implemented with Cactus2D, every level must extend the Cactus2DLevel class.

Now we’re going to see the example that comes in the Cactus2D package sample. When you run this example, an object is created on the game screen, which will be controlled by touch, holding and dragging the object, for this, a drag and drop component will be used.

On the source code list 1, the code represents one level for the game screen. On this level is created a game object called “sertao” and three components are added to this game object. The first component is the SpriteRendererComponent (from the Cactus2D), which apply the texture with a ball to the object. The second component is the TouchComponent. The last component, was implemented to the sample. It encapsulates the drag and drop input behavior.

The init() method is always called by the engine when the level is loaded, this way, on the GameLevel example, all the composition needed for the level are defined on the beginning.

SourceCode List 1. GameLevel Implementation.

public class GameLevel extends Cactus2DLevel { 
   protected void init() {
      GameObject sertao = new GameObject("sertao");
      Texture texture = Cactus2DApplication.loadTexture("data/sertao.png");
      SpriteRendererComponent sr = new SpriteRendererComponent(texture);
      sertao.AddComponent(new TouchComponent(new Vector2(100, 100)));
      sertao.AddComponent(new DragNDropComponent());

The source code list 2, show the implementation of the specific component for this example. As you can see, the update() method are inherited from the component class. On this method, which is executed from every loop of the game, the position of the ball is updated by using the input of the device’s touchscreen. On the update() method we updated the game object by the attribute transform which are inherited from Component class.

SourceCode List 2. Implementation of the Drag and Drop component.

public class DragNDropComponent extends Component {
   public void onTouchStay(Vector2 touchPosition) {

To execute the game, you need to instantiate the level created and execute it, like on the source code list 3. On the PC, the touch option can be simulated by the click of the mouse.

SourceCode List 3. Class that execute the Sample.

public class Cactus2DSample {
   public static void main(String[] args) {
      Cactus2DApplication game = new Cactus2DApplication();
      game.loadLevel(new GameLevel());
      new JoglApplication(game, "Cactus2D Sample", 320, 600, false);

Creating an Android Project to run the Game

Up to now, we saw how a game implemented with Cactus2D works and how to run it. Until this moment, the game can run in any architecture, either Mac, Linux or Windows. However, we still need to install the game on an Android device, and for that we will show how to do this step by step.

First thing first, we need to create another project to execute our game in an Android environment. For that, go to Eclipse menu and choose the File -> New -> Android Project option. Choose the name Cactus2DSampleAndroid and click Next. On the next screen choose one of the SDK versions which you have installed and click Next one more time. In the last screen of the wizard complete the space with the project package: com.sertaogames.cactus2d and click on Finish. It’ll be created an Android project with a class named Activity (Cactus2DSampleAndroidActivity), which is responsible for initiating the Android application.

However, two more steps are still needed. The first one is to setup the project to include the Cactus2D in the classpath of the new Android project. For this, right click on the Android project and choose the Build Path -> Configure Build Path option. Select the Projects tab and inside of it click on the button Add. Select the Cactus2D project and confirm the operation. The second step is also to include some jars from the libgdx library, in the classpath. Go to: and download the new version of the project. On our example, we downloaded the project On the Android project you’ve to create a folder called libs and paste the jars gdx-backend-adroid.jar and dgx.jar, and the armeabi and armeabi-v7a folders which we found inside the libgdx-0.9.2 and add these jars in the classpath of the Android project.

You must also copy the content of the assets folder from Cactus2D project to the folder with the same name which exists in the Android project. After that, edit the Activity class like source code list 4.

SourceCode List 4. Method to execute the sample for Android

public void onCreate(Bundle savedInstanceState) {
   Cactus2DApplication game = new Cactus2DApplication();
   game.loadLevel(new GameLevel());
   initialize(game, false);

On this piece of code an object of Cactus2DApplication type is created, which is responsible for instantiating the first level to be executed, in other words the level defined on the GameLevel class. The last line shows how to call the libgdx library to execute the game and manage the game loop.

Compiling and Signing the Game

To install your application on an Android device, you need to sign it with a digital certificate which identifies the application’s author. Therefore, to release your application to the public, you need to get a valid private key, compile the application in release mode, sign your application with your private key and then, align the APK package final. These steps can be made on the command line or visually with the eclipse plugin. To do this process with the ADT, you only need to select the project in the “Package Explorer” option, click File -> Export, open the Android folder, select “Export Android Application”, and click Next. In the follow, the export assistant will available a step by step how do the process of signature of your application, where you can select a private key which exists or create a new key to sign the application.

Concluding remarks

We’ve seen the benefits that a good tool can provide in terms of productivity and speed of the game development process. The engine Cactus2D was presented as an alternative to accelerate the implementation of Android games. Following this proposal, the next steps for the tool upgrade include the availability of new components, such as integration with social networks and use of multitouch, and a visual editor for editing properties in the game where you can build objects by adding components to them. There are also plans for future versions architecture following the data-driven pattern.


Smart Composition of Game Objects using Dependency Injection. Passos, E. B., Sousa, J. W.; Clua, E. W. G; Murta. L. In: ACM Computers in Entertainment: CIE, Volume 7, Issue 4, Article #53, 2009

Unity3D Manual. Unity Technologies.

9 thoughts on “Intro to Cactus2D Game Engine

  1. Olá wansoul.

    Gostaria de entender uma coisa, se sua classe Cactus2DSampleAndroidActivity estende Activity ao implementar (sobrescrever) o método:

    public void onCreate(Bundle savedInstanceState) {
    Cactus2DApplication game = new Cactus2DApplication();
    game.loadLevel(new GameLevel());
    initialize(game, false); //de onde vem a implementação deste método initialize(…);

    De onde vem a implementação do método initialize(…)? Pois aparentemente ele não pertence a class Activity e nem a sua hierarquia.

    Obs: estou usando a versão 2.3.3 do android sdk.

    Grato pela atenção.

    • Está faltando a explicação que a classe Cactus2DSampleAndroidActivity deve extender a classe AndroidApplication (da hierarquia da biblioteca libgdx) em vez de Activity (da hierarquia padrão da sdk Android).

      O código completo da activity seria esse:

      public class CactusSampleActivity extends AndroidApplication {
      public void onCreate(Bundle savedInstanceState) {
      Cactus2DApplication game = new Cactus2DApplication();
      game.loadLevel(new GameLevel());
      initialize(game, false);

      • Quando faço isso, ele até compila e roda, abrindo o emulador, mas este trava com a mensagem “Force closed”… alguma ideia? Não tem mais nada no código além de seguir as instruções até aqui.

  2. Wansoul, beleza?
    Primeiramente parabéns para você e para a equipe envolvida no desenvolvimento do framework Cactus2D!
    A minha dúvida é sobre o ambiente mínimo necessário para poder usar o Cactus2D, pode me ajudar?
    Gostaria de saber quais as dependências externas e plugins usados que devo adicionar ao projeto e ao Eclispse e quais versões foram usadas, para que não haja problemas de compatibilidade.
    Fora isso solicito, por gentileza e por falta de experiência, que melhorem o passo a passo para criar o tutorial para abranger um público mais leigo para dar os primeiros passos.
    Gostaria de saber também se alguém começou, ou ao menos tentou, desenvolver um jogo de plataforma side-scrolling com o Cactus2D

    Agradeço a atenção!

    • Inicialmente obrigado pelo comentário.

      Acredito que todas as dependências estão incluídas no repositório, bastando ser adicionadas ao “build path” do Eclipse.

      Quando a um jogo side-scrolling, não conheço alguém que esteja fazendo, mas originalmente o jogo Candy Soldier iria ser um side-scroller, então as funcionalidades necessárias já estão incluídas:

      – o componente de tilemaps aceita mapas grandes, maiores que a tela sem problemas;
      – se você analisar os fontes, inclusive é possível se configurar a velocidade relativa de paralaxe em camadas de background diretamente em atributos de layer no editor Tiled (editor open source muito usado para tilemaps – usamos ele aqui na Sertão Games);
      – resta apenas criar um componente que atualize a câmera em função da posição do personagem (o paralaxe das camadas do tilemap vai funcionar de forma relativa à câmera);

      Erick Passos

  3. Olá parabéns pela Engine!
    Ano passado eu li a matéria sobre o Cactus2D na MundoJ e gostei bastante, segui o tutorial e rodei o Terremoto no Windows, através da JVM, funcionou tudo corretamente. Depois experimentei e fiz um porte para rodar com Jython, também funcionou legal. Dúvida:
    Vi que vocês pensam em utilizar xml para criar cenários e outras coisas, vocês cogitaram utilizar Python ou Lua, por exemplo, como linguagem de configuração e script? Acho que poderia simplificar a escrita e ainda dar inteligência, comparando ao xml.

    Obs.: não rodei Cactus2d + Jython + Android

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s