How to Work With TileGraphics

This document will help you understand how to compose Tiles into in-memory graphics objects called TileGraphics

A TileGraphics is a two dimensional in-memory image composed of Tiles. When you create one it is held in memory but you can draw a TileGraphics onto any DrawSurface (like a TileGrid, a Screen or another TileGraphics).

You can also create Layers from TileGraphics objects. Click here to see how Layers work.


A TileGraphics can be created by either using the DrawSurfaces helper or the toTileGraphics factory method on a Shape.

You can read more about Shapes here.

Let’s see an example:

import org.hexworks.zircon.api.*;
import org.hexworks.zircon.api.application.AppConfig;
import org.hexworks.zircon.api.color.ANSITileColor;
import org.hexworks.zircon.api.grid.TileGrid;
import org.hexworks.zircon.api.resource.TilesetResource;

public class CreatingTileGraphicsFromShapes {

    private static final TilesetResource TILESET = CP437TilesetResources.rexPaint16x16();

    public static void main(String[] args) {

        AppConfig config = AppConfigs.newConfig()

        TileGrid tileGrid = SwingApplications.startTileGrid(

        final TileGraphics background = DrawSurfaces.tileGraphicsBuilder()
                .withSize(tileGrid.getSize()) // you can fetch the size of a TileGrid like this

        final TileGraphics rectangle = Shapes.buildRectangle(


        // the default position is (0x0) which is the top left corner


The result of running this code snippet should look like this:

Creating Tile Graphics From Shapes

Note that the above example uses the Shapes helper class. You can read more about shapes here.

How TileGraphics works

As you can see in the above example the easiest way to create aTileGraphics is to use the DrawSurfaces helper. Every TileGraphics must have a Size but it has no Position.

When you draw a TileGraphics on a DrawSurface the original image will stay the same and only the DrawSurface will change which means that draw is a copy operation. After drawing a TileGraphics you won’t be able to tell about a Tile that it belongs to your image. If you need this kind of information look at how layers work.

You can draw TileGraphics objects onto each other (as you can see in the example above). Keep in mind that there is a special empty Tile which is accessible from the Tiles class like this: Tiles.empty().

EMPTY Tiles will not be copied over to the DrawSurface when you call draw so you can create flattened layers this way (the same happens in the example above).

When you draw a TileGraphics onto a DrawSurface you also need to supply a Position. This will be the Position on the DrawSurface from which the copying will start. If a TileGraphics is bigger than the target DrawSurface then the characters which are out of bounds will be ignored.