Awesome
Zircon - A user-friendly Tile Engine & Text GUI
<img src="https://cdn.discordapp.com/attachments/205245036084985857/481213000540225550/full_example.gif" alt="Full Example"/>Need info? Check the Docs | or Create an issue | Check our project Board | Ask us on Discord | Support us on Patreon | Javadoc / Kdoc
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.
You can find the Javadoc / Kdoc here
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>2021.1.0-RELEASE</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>2021.1.0-RELEASE</version>
</dependency>
</dependencies>
Gradle:
dependencies {
implementation "org.hexworks.zircon:zircon.core-jvm:2021.1.0-RELEASE"
implementation "org.hexworks.zircon:zircon.jvm.swing:2021.1.0-RELEASE"
}
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(60, 30)
// You can choose from a wide array of CP437, True Type or Graphical tilesets
// that are built into Zircon
.withDefaultTileset(CP437TilesetResources.rexPaint16x16())
.build());
// A Screen is an abstraction that 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!")
.withAlignment(ComponentAlignments.alignmentWithin(tileGrid, ComponentAlignment.CENTER))
.build();
// Screens can hold GUI components
screen.addComponent(label);
// Displaying a screen will make it visible. It will also hide a previously shown Screen.
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 that can help you if you get stuck:
If you want to build something (a TileGraphics
, a Component
or anything that is part of the public API) it is
almost sure that there is a Builder
or a factory object for it. Each type that has a builder will have a
newBuilder
function you can call to create the corresponding builder: Tile.newBuilder()
.
If there are multiple classes of objects that can be created there might also be a 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 that 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 that 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 that 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:
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 keystrokes and mouse input as well.
Layering
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:
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]
keystroke (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:
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 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:
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:
- Scrollable Components
- Menus
- Table Component
- Javadoc-style Documentation
- Grid / Screen Filters
- Floating Components
- Drag'n Drop Support
- Custom Layout Support
- Component Themes
- Custom Component Support
- Tree Component
- Accordion Component
- Combo Box Component
- IntelliJ Plugin
- Console for Zircon
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, Seveen and many others.
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:
<a href="https://www.jetbrains.com/idea/"> <img src="https://github.com/Hexworks/zircon/blob/master/images/idea_logo.png" width="40" height="40" alt="IDEA"/> </a> <a href="https://kotlinlang.org/"> <img src="https://github.com/Hexworks/zircon/blob/master/images/kotlin_logo.png" width="40" height="40" alt="Kotlin"/> </a> <a href="https://www.yourkit.com/java/profiler/"> <img src="https://github.com/Hexworks/zircon/blob/master/images/yklogo.png" width="168" height="40" alt="Yourkit"/> </a>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.