Need help with zircon?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

Hexworks
529 Stars 98 Forks Apache License 2.0 1.1K Commits 37 Opened issues

Description

Zircon is an extensible and user-friendly, multiplatform tile engine.

Services available

!
?

Need anything else?

Contributors list

Zircon - A user-friendly Tile Engine & Text GUI Tweet

Full Example

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

Circle CI Maven Central License Awesome


Table of Contents

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:

    
        org.hexworks.zircon
        zircon.core-jvm
        2020.0.2-PREVIEW
    
    
    
        org.hexworks.zircon
        zircon.jvm.swing
        2020.0.2-PREVIEW
    

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:

Zircon Application

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
Builder
s for all
Component
s 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

draw
ing. You can draw individual
Tile
s or
TileGraphics
objects on your
TileGrid
. a
TileGraphics
object is composed of
Tile
s. 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

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

Modifiers

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

Screen
s go here.

Both the

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

Layers

Text GUI Components

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

Component
s are GUI controls which can be used for showing content to the user (
Label
s,
Paragraph
s, etc), enabling them to interact with your program (
Button
s,
Slider
s, etc) or to hold other components (
Panel
s 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

ColorTheme
s to
Component
s. There are a bunch of built-in themes, and you can also create your own.

To see a full list of available

Component
s 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:

All Components

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:

Animation Example

Shape and box drawing

The shape documentation page can be found here.

You can draw

Shape
s 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:

IDEA Kotlin Yourkit

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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.