Zircon - A user-friendly Tile Engine & Text GUI

Need info? Check the Docs | or Create an issue | Check our project Board | Ask us on Discord | Support us on Patreon

Getting Started
- Adding Zircon as a Maven Dependency
- Basic Usage
Best Practices
Features at a Glance

Getting Started

If you want to start working with Zircon you can either add it to your project as a Maven dependency or you can try out the skeleton projects (Java, Kotlin) which come with batteries included.

The official documentation site contains a lot of information. The examples are also documented on the Zircon Examples page (under construction), and the best place to start is the Zircon Crash Course.

If you like learning by doing check out the source of Zircon from here and you can run the examples for yourself. If you are using Java start here. Alternatively if you use Kotlin the code can be found here.

If you just want to peruse the Zircon API navigate here. Everything which is intended to be part of the public API is there.

If you'd like to talk to us, join us on our Discord Server.

Adding Zircon as a Maven Dependency

Maven:

<dependencies>
    <dependency>
        <groupId>org.hexworks.zircon</groupId>
        <artifactId>zircon.core-jvm</artifactId>
        <version>2020.0.2-PREVIEW</version>
    </dependency>
    <!-- use zircon.jvm.libgdx if you want to use LibGDX instead of Swing -->
    <dependency>
        <groupId>org.hexworks.zircon</groupId>
        <artifactId>zircon.jvm.swing</artifactId>
        <version>2020.0.2-PREVIEW</version>
    </dependency>
</dependencies>

Gradle:

dependencies {
    implementation "org.hexworks.zircon:zircon.core-jvm:2020.0.2-PREVIEW"
    implementation "org.hexworks.zircon:zircon.jvm.swing:2020.0.2-PREVIEW"
}

Basic Usage

Once you have the dependencies set up you can start using Zircon by creating a TileGrid:

public class Main {

    public static void main(String[] args) {

        // a TileGrid represents a 2D grid composed of Tiles
        TileGrid tileGrid = SwingApplications.startTileGrid(
                AppConfig.newBuilder()
                        // The number of tiles horizontally, and vertically
                        .withSize(Size.create(60, 30))
                        // You can choose from a wide array of CP437, True Type or Graphical tilesets
                        // which are built into Zircon
                        .withDefaultTileset(CP437TilesetResources.rexPaint16x16())
                        .build());

        // A Screen is an abstraction which lets you use text GUI Components
        // You can have multiple Screens attached to the same TileGrid to be able to create multiple
        // screens for your app.
        Screen screen = Screen.create(tileGrid);

        // Creating text GUI Components is super simple
        Label label = Components.label()
                .withText("Hello, Zircon!")
                .withPosition(Position.create(23, 10))
                .build();

        // Screens can hold GUI components
        screen.addComponent(label);

        screen.display();
        
        // Zircon comes with a plethora of built-in color themes
        screen.setTheme(ColorThemes.arc());
    }
}

The output of this example is:

Congratulations! Now you are a Zircon user.

Best Practices

The following are some guidelines which can help you if you get stuck:

If you want to build something (a TileGraphics, a Component or anything which is part of the public API) it is almost sure that there is a Builder or a factory object for it. The convention is that if you want to create a Tile you can use the factory functions defined on said class (Tile.create for example). If there are multiple classes of objects which can be created there might also be an utility class (like Shapes to create different Shape objects. Your IDE will help you with this.

These classes reside in the org.hexworks.zircon.api package. There are some classes which are grouped together into a single utility class however. With Components for example, you can obtain Builders for all Components like Components.panel() or Components.checkBox(). Likewise you can use DrawSurfaces to obtain builders for TileGraphics and TileImage.

If you want to work with external files like tilesets or REXPaint files check the same package (org.hexworks.zircon.api), and look for classes which end with *Resources. There are a bunch of built-in tilesets for example which you can choose from but you can also load your own. The rule of thumb is that if you need something external there is probably a *Resources class for it (like the CP437TilesetResources).

You can use anything you can find in the API package, they are part of the public API, and safe to use. The internal package however is considered private to Zircon so keep in mind that they can change any time.

Some topics are explained in depth in the documentation.

If you want to see some example code take a look at the examples project here. Most examples have identical Java and Kotlin variants.

If all else fails read the javadocs. API classes are well documented.

If you have any problems which are not answered here feel free to ask us at the Hexworks Discord server.

Features at a Glance

Drawing

You can find detailed documentation about drawing here.

The most basic operation Zircon supports is drawing. You can draw individual Tiles or TileGraphics objects on your TileGrid. a TileGraphics object is composed of Tiles. This is a powerful tool and you can implement more complex features using simple draw operations. In fact the component system is implemented on top of drawing, layering and input handling features.

If you use REXPaint to design your programs, the good news is that you can import your .xp files as well. Read more about it here.

You can also use Modifiers in your Tiles such as blink, verticalFlip or glow. For a full list, check this factory object. Modifiers can either change the texture (like the ones above) or the Tile itself:

Input handling

Read about input handling in the docs here.

Both the TileGrid and the Screen interfaces implement UIEventSource which means that you can listen for user inputs using them. This includes key strokes and mouse input as well.

Layering

Layering is detailed here. For a primer on Screens go here.

Both the TileGrid and the Screen interfaces implement Layerable which means that you can add Layers on top of them. Every Layerable can have an arbitrary amount of Layers. Layers are like TileGraphics objects and you can also have transparency in them which can be used to create fancy effects. Components are also Layers themselves. Take a look:

Text GUI Components

You can read more about the Component System on the documentation page. Color themes are detailed here.

Components are GUI controls which can be used for showing content to the user (Labels, Paragraphs, etc), enabling them to interact with your program (Buttons, Sliders, etc) or to hold other components (Panels for example).

These components are rather simple and you can expect them to work in a way you might be familiar with:

You can click on them (press and release are different events).
You can attach event listeners on them.
Zircon implements focus handling so you can navigate between the components using the [Tab] key (forwards) or the [Shift]+[Tab] key stroke (backwards).
Components can be hovered and you can also apply color themes to them.

What's more is that you can apply ColorThemes to Components. There are a bunch of built-in themes, and you can also create your own.

To see a full list of available Components take a look at the Components factory object or navigate to the component docs page.

This is an example of how components look in action:

Animations:

Read more about Animations in the docs.

Animations are supported out of the box. You can either create them programmatically, or statically using Zircon's own animation format: .zap (Zircon Animation Package). More about that here. This is how an animation looks like:

Shape and box drawing

The shape documentation page can be found here.

You can draw Shapes like rectangles and triangles by using one of the ShapeFactory implementations. What's supported out of the box is triangle, rectangle and line. The former two have filled versions as well. Check out the Shapes factory object here.

Fonts and Tilesets

The documentation page for tilesets is here.

Zircon comes with a bunch of built-in fonts tilesets. These come in 3 flavors:

CP437 tilesets (More on using them here)
True Type Fonts
and Graphical tilesets (Usage info here)

Zircon also comes with its own tileset format (ztf: Zircon Tileset Format) which is very easy to use. It is detailed here.

Road Map

If you want to see a new feature feel free to create a new Issue or discuss it with us on Discord. Here are some features which are either under way or planned:

If you'd like to give any of these a shot feel free to contribute.

License

Zircon is made available under the Apache 2.0 License.

Credits

Zircon is created and maintained by Addamsson, Coldwarrl, G3ldrin, Milonoir and Seveen

We're open to suggestions, feel free to message us on Discord or open an issue. Pull requests are also welcome!

Zircon is powered by:

Thanks

Thanks to the folks over at Dwarf Fortress Tileset Repository for letting us bundle their tilesets.

Thanks to Kyzrati who let us bundle the REXPaint Tilesets into Zircon!

Zircon comes bundled with the Nethack Tileset.

Some True Type fonts are used from Google Fonts.

Thanks to VileR for the Oldschool Font Pack which we bundled into Zircon.

MrBergin/zircon