Grafixator-API

The libgdx Grafixator API loads in your grafixator game to your project and renders it exactly the same as designed in the editor (with the same sprite tweening, player/camera movement, player/enemy fire, box2d, box2d lights, particle effects, collisions etc).

However, as each game is different, the API makes it very easy to completely change any of this behavior to use your own custom logic.

It is assumed you are familiar with setting up your project in Libgdx. If not, please refer to the libgdx documentation.

Getting Started

There are 2 ways to use the Grafixator API:

Download and include the grafixtor.jar API in your core project lib folder. Add grafixator.jar to your build path and attach the source (grafixator-source.jar).
Import the Grafixator API as new project. In this case add the project to your build path.

Git clone location:

https://github.com/SteveyO/grafixator.git

Dependencies

The Grafixator API has 4 dependencies.

Ensure that all of these are on your buildpath, if not already. The gdx.jar will already be in your core project so use that.
If you are using Gradle then follow the libgdx Dependency management with Gradle guide.

Loading and customizing your game

The recommended way to use the grafixator API is to create your own custom class which inherits from GrafixatorGame. This makes it easy to add your own custom logic.

public class MyCoolGame extends GrafixatorGame {

    public MyCoolGame(GrafixatorConfiguration gConfig) {
    super(gConfig);
    }
}

Place your grafixator game (grafixator .xml file and tile sheet + optional spritesheet + backgrounds) in your assets/data file as you would normally for libgdx resources.

In your main class, define a local variable to the class you defined above (MyCoolGame) and load in your game as below:

public class MyGame extends ApplicationAdapter {
  SpriteBatch batch;
  MyCoolGame myCoolGame;
  private OrthographicCamera tileMapCamera;

    @Override
    public void create () {
    batch = new SpriteBatch();
        
    tileMapCamera = new OrthographicCamera();           
    tileMapCamera.setToOrtho( . .

    myCoolGame = new MyCoolGame(new GrafixatorConfiguration());
    myCoolGame.loadGrafixatorGame("data/myGrafixatorGame", batch);
     }
}

Customizing your game

With this setup, the choice of how to code your game is completely up to you.
You can:

Render your tilemap using the TMX Renderer, and ignore all the Grafixator methods.
Use the grafixator methods. You can customize them easily enough by Overriding them in your own custom class

For example, to add a sound affect to your player fire, override the fireBullet() method in your MyCoolGame class:

   @Override
   public boolean fireBullet() {
       Assets.fireSound.play();
       return super.fireBullet();
   }

Tip: To Override any of the more complex methods (e.g. renderSprites, updateSprites) access to the GrafixatorGame.java source is essential. If you have the Grafixator API checked out as a project, this is easy. If you are using the grafixtor.jar attach the grafixtor-source.jar as described above. Alternatively, view the source directly on GitHub: GrafixatorGame.java

Rendering

Render your tiledMap in your render() method as you would normally. The API allows you to specify after which Tiled Layer to render your sprites (images or animations).

  @Override
  public void render () {
     . . .
        
     myCoolGame.render(batch, tileMapCamera, 1);
     batch.begin();

Rendering your background

If you have included any ‘Parallax’ backgrounds in your game, then render them before you render your tilemap.

  @Override
  public void render () {
     . . .

	    batch.begin();
	    batch.setProjectionMatrix(tileMapCamera.combined);
	     myCoolGame.drawBackgrounds( batch,  tileMapCamera);

	    batch.end();

Updating your sprites

The update() method handles all the updating of your hero’s character movement, as well as any backgrounds. Update sprites method takes care of all sprites with properties (e.g. rotating, pickup, sprites with Box2D Lights).


   public void update() {
      . . .
      myCoolGame.updateSprites(tileMapCamera);
      myCoolGame.update(Gdx.graphics.getDeltaTime(), tileMapCamera);        
      . . .

Tip: All your sprites (GrafixatorSprites) are stored in the spriteList ArrayList in your myCoolGame class.

Handling collisions

To use the Grafixator built in collisions, add the line:

  myCoolGame.populateCollisionRectangles(true, true);

directly after loading in your game.
The first argument is for Box2D collisions. If ‘true’ Box2D collision rectangles are generated for all tiles in your ‘Collision layer’ and Box2d Shapes are generated if you have included any collision objects (paths, circles, rectangles, triangles). These are added to your Box2d World.
The second argument is for Rectangles. If ‘true’ all Rectangles are added to an ArrayList (collisionRectangles) which can be used for your own custom collision detection.

All collision rectangles are generated using basic contour tracing (to reduce the amount of box2d shapes or rectangles).

Box2d

To debug your Box2d world, simply set the debugBox2D property to true (of your custom game class).

  myCoolGame.debugBox2D=true;

Box2d Lights

If your game uses Box2d Lights, add the below 2 lines towards the end of your render method.

  @Override
  public void render () {
     . . .
     myCoolGame.rayHandler.setCombinedMatrix(tileMapCamera);
     myCoolGame.rayHandler.updateAndRender();
  }

Particle Effects

Using the Grafixator Particle Effects is easy. This is managed by the particleEffect manager.

public ParticleEffectManager particleEffectManager = ParticleEffectManager.getInstance();

  @Override
  public void render () {
      . . .
     particleEffectManager.renderParticleEffects(batch);
      . . .
  }

  public void update() {
     particleEffectManager.updateParticles(Gdx.app.getGraphics().getDeltaTime(), tileMapCamera);
      . . .
  }

To use your own Particle Effect engine, simply override any of the grafixator methods that use a particle effect. See Loading and customizing your game

Player Movement and Player Fire

The grafixator API has many methods for moving your player, depending on which game type you selected (standard, platform, jump etc). In the Grafixator Editor all movement is achieved via the keyboard (or the mouse for jumping, catapult), so you will need to implement your own method for receiving input (e.g. Input Processor or TouchPad)

To move your player simply call the method that corresponds to your chosen movement type:

  public void update() {
   // e.g. For Standard movement (left, right, up, down)
   myCoolGame.checkKeyPressesStandardGame(. . . );

   // or for SpaceShip movement (left, right, thrust).
   myCoolGame.checkKeyPressesSpaceShipGame(. . . );

   // or for Platformers (left, right, jump).
   myCoolGame.checkKeyPressesPlatformGame(. . . );

   // for player fire,  call fireBullet() method.
   myCoolGame.fireBullet();

   }

For handing a Catapult character you can use:

        gameCam.unproject(touchPoint.set(Gdx.input.getX(),Gdx.input.getY(), 0));
        
        if (Gdx.input.justTouched()) {
                myCoolGame.handleTouchDown(touchPoint.x, touchPoint.y, true);
        }  
        else if (Gdx.input.isTouched()) {
            myCoolGame.handleCatapultDrag(touchPoint.x, touchPoint.y);
        }
        if (!Gdx.input.isTouched() && myCoolGame.isPlayerBeingDragged) {
            myCoolGame.handleTouchDown(touchPoint.x, touchPoint.y, false);
        }

If your game contains bullets then render them in your render() method:

     myCoolGame.drawAndUpdateBullets(batch, tileMapCamera);

Camera Movement

To handle the camera movement call the handleCameraMovement method as below.

  public void update() {
   . . .
    mycoolGame.handleCameraMovement(tileMapCamera);
   . . .
  }

Contributing

If you have any improvements or bug fixes feel free to send us a pull request. Any platformer improvements, such as one-way platforms, wall jumping, moving platforms will be highly appreciated.