{"id":15069231,"url":"https://github.com/hexworks/zircon","last_synced_at":"2025-04-08T10:32:00.114Z","repository":{"id":37664855,"uuid":"94116947","full_name":"Hexworks/zircon","owner":"Hexworks","description":"Zircon is an extensible and user-friendly, multiplatform tile engine.","archived":false,"fork":false,"pushed_at":"2024-02-14T19:57:47.000Z","size":42728,"stargazers_count":765,"open_issues_count":43,"forks_count":139,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-04-01T09:24:29.877Z","etag":null,"topics":["game-development","java","jvm","kotlin","multiplatform","roguelike","scala","text-gui","zircon"],"latest_commit_sha":null,"homepage":"https://hexworks.org/projects/zircon/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Hexworks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null},"funding":{"patreon":"hexworks"}},"created_at":"2017-06-12T16:22:16.000Z","updated_at":"2025-03-30T14:33:45.000Z","dependencies_parsed_at":"2024-01-28T16:01:31.248Z","dependency_job_id":"749888b5-a2ce-4844-845a-ae10a62bd127","html_url":"https://github.com/Hexworks/zircon","commit_stats":{"total_commits":1162,"total_committers":32,"mean_commits":36.3125,"dds":0.2168674698795181,"last_synced_commit":"55a0ccc19a3f1b80aecd5f1fbe859db94ba9c0c6"},"previous_names":[],"tags_count":127,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hexworks%2Fzircon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hexworks%2Fzircon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hexworks%2Fzircon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hexworks%2Fzircon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Hexworks","download_url":"https://codeload.github.com/Hexworks/zircon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247823964,"owners_count":21002176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["game-development","java","jvm","kotlin","multiplatform","roguelike","scala","text-gui","zircon"],"created_at":"2024-09-25T01:41:13.488Z","updated_at":"2025-04-08T10:32:00.091Z","avatar_url":"https://github.com/Hexworks.png","language":"Kotlin","readme":"# Zircon - A user-friendly Tile Engine \u0026 Text GUI [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=Do%20you%20plan%20to%20make%20a%20roguelike%3F%20Look%20no%20further.%20Zircon%20is%20the%20right%20tool%20for%20the%20job.\u0026url=https://github.com/Hexworks/zircon\u0026hashtags=games,roguelikes)\n\n\u003cimg src=\"https://cdn.discordapp.com/attachments/205245036084985857/481213000540225550/full_example.gif\"  alt=\"Full Example\"/\u003e\n\nNeed info? Check the [Docs][zircon-docs]\n| or [Create an issue](https://github.com/Hexworks/zircon/issues/new)\n| Check [our project Board](https://github.com/Hexworks/zircon/projects/2)\n| [Ask us on Discord][discord]\n| Support us on [Patreon](https://www.patreon.com/hexworks)\n| [Javadoc / Kdoc](https://hexworks.github.io/zircon/)\n\n[![Circle CI](https://circleci.com/gh/Hexworks/zircon/tree/master.svg?style=shield)](https://circleci.com/gh/Hexworks/zircon/)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.hexworks.zircon/zircon.core/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.hexworks.zircon/zircon.core)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/sindresorhus/awesome)\n\n---\n\n## Table of Contents\n\n- [Getting Started](#getting-started)\n    - [Adding Zircon as a Maven Dependency](#adding-zircon-as-a-maven-dependency)\n    - [Basic Usage](#basic-usage)\n- [Best Practices](#best-practices)\n- [Features at a Glance](#features-at-a-glance)\n    - [Drawing](#drawing)\n    - [Input Handling](#input-handling)\n    - [Layering](#layering)\n    - [Text GUI Components](#text-gui-components)\n    - [Animations](#animations)\n    - [Shape and Box Drawing](#shape-and-box-drawing)\n    - [Fonts and Tilesets](#fonts-and-tilesets)\n    - [Road Map](#road-map)\n    - [License](#license)\n    - [Credits](#credits)\n    - [Thanks](#thanks)\n\n## Getting Started\n\nIf you want to start working with Zircon you can either add it to your project as a Maven dependency or you can try out\nthe skeleton projects\n([Java](https://github.com/Hexworks/zircon.skeleton.java), [Kotlin](https://github.com/Hexworks/zircon.skeleton.kotlin))\nwhich come with batteries included.\n\nThe official [documentation site][zircon-docs] contains a lot of information. The examples are also documented on the\n[Zircon Examples](https://hexworks.org/zircon/examples/) page *(under construction)*, and the best place to start is the\n[Zircon Crash Course](https://hexworks.org/zircon/docs/2018-07-18-a-zircon-crash-course).\n\nIf you like learning by doing check out the source of *Zircon* from [here](https://github.com/Hexworks/zircon) and you\ncan run the examples for yourself. If you are using *Java*\nstart [here](https://github.com/Hexworks/zircon/tree/master/zircon.jvm.examples/src/main/java/org/hexworks/zircon/examples)\n. Alternatively if you use *Kotlin* the code can be\nfound [here](https://github.com/Hexworks/zircon/tree/master/zircon.jvm.examples/src/main/kotlin/org/hexworks/zircon).\n\nIf you just want to peruse the *Zircon* API navigate [here][api]. Everything which is intended to be part of the public\nAPI is there.\n\nYou can find the *Javadoc* / *Kdoc* [here](https://hexworks.github.io/zircon/)\n\nIf you'd like to talk to us, join us on our [Discord Server][discord].\n\n### Adding Zircon as a Maven Dependency\n\nMaven:\n\n```xml\n\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.hexworks.zircon\u003c/groupId\u003e\n        \u003cartifactId\u003ezircon.core-jvm\u003c/artifactId\u003e\n        \u003cversion\u003e2021.1.0-RELEASE\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003c!-- use zircon.jvm.libgdx if you want to use LibGDX instead of Swing --\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.hexworks.zircon\u003c/groupId\u003e\n        \u003cartifactId\u003ezircon.jvm.swing\u003c/artifactId\u003e\n        \u003cversion\u003e2021.1.0-RELEASE\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\nGradle:\n\n```groovy\ndependencies {\n    implementation \"org.hexworks.zircon:zircon.core-jvm:2021.1.0-RELEASE\"\n    implementation \"org.hexworks.zircon:zircon.jvm.swing:2021.1.0-RELEASE\"\n}\n```\n\n### Basic Usage\n\nOnce you have the dependencies set up you can start using *Zircon* by creating a `TileGrid`:\n\n```java\npublic class Main {\n\n    public static void main(String[] args) {\n\n        // a TileGrid represents a 2D grid composed of Tiles\n        TileGrid tileGrid = SwingApplications.startTileGrid(\n                AppConfig.newBuilder()\n                        // The number of tiles horizontally, and vertically\n                        .withSize(60, 30)\n                        // You can choose from a wide array of CP437, True Type or Graphical tilesets\n                        // that are built into Zircon\n                        .withDefaultTileset(CP437TilesetResources.rexPaint16x16())\n                        .build());\n\n        // A Screen is an abstraction that lets you use text GUI Components\n        // You can have multiple Screens attached to the same TileGrid to be able to create multiple\n        // screens for your app.\n        Screen screen = Screen.create(tileGrid);\n\n        // Creating text GUI Components is super simple\n        Label label = Components.label()\n                .withText(\"Hello, Zircon!\")\n                .withAlignment(ComponentAlignments.alignmentWithin(tileGrid, ComponentAlignment.CENTER))\n                .build();\n\n        // Screens can hold GUI components\n        screen.addComponent(label);\n\n        // Displaying a screen will make it visible. It will also hide a previously shown Screen.\n        screen.display();\n\n        // Zircon comes with a plethora of built-in color themes\n        screen.setTheme(ColorThemes.arc());\n    }\n}\n```\n\nThe output of this example is:\n\n![Zircon Application](images/hello_zircon.png)\n\n*Congratulations!* Now you are a *Zircon* user.\n\n## Best Practices\n\nThe following are some guidelines that can help you if you get *stuck*:\n\nIf you want to build something (a `TileGraphics`, a `Component` or anything that is part of the public API) it is\nalmost sure that there is a `Builder` or a factory object for it. Each type that has a builder will have a\n`newBuilder` function you can call to create the corresponding builder: `Tile.newBuilder()`.\n\nIf there are multiple classes of objects that can be created there might also be a utility class, \nlike `Shapes` to create different `Shape` objects. Your IDE will help you with this.\n\nThese classes reside in the `org.hexworks.zircon.api` package. There are some classes that are grouped together into a\nsingle utility class, however. With `Components` for example, you can obtain `Builder`s for all `Component`s\nlike `Components.panel()` or `Components.checkBox()`. Likewise, you can use `DrawSurfaces` to obtain builders\nfor `TileGraphics` and `TileImage`.\n\nIf you want to work with external files like tilesets or REXPaint files check the same  package\n(`org.hexworks.zircon.api`), and look for classes that end with `*Resources`. There are a bunch of built-in tilesets\nfor example which you can choose from, but you can also load your own.\n\nThe rule of thumb is that if you need something external there is probably a `*Resources` class for it (like\nthe `CP437TilesetResources`).\n\nYou can use *anything* you can find in the [API][api] package, they are part of the public API, and safe to use.\nThe [internal][internal] package however is considered private to *Zircon* so keep in mind that they can change any\ntime.\n\nSome topics are explained in depth in the [documentation][zircon-docs].\n\nIf you want to see some example code take a look at the examples project [here][examples]. Most examples have\nidentical *Java* and *Kotlin* variants.\n\nIf all else fails read the javadocs. API classes are well documented.\n\nIf you have any problems that are not answered here feel free to ask us at the [Hexworks Discord server][discord].\n\n## Features at a Glance\n\n### Drawing\n\n\u003e You can find detailed documentation about drawing [here][drawing-docs].\n\nThe most basic operation *Zircon* supports is `draw`ing. You can draw individual `Tile`s or `TileGraphics` objects on\nyour `TileGrid`. a `TileGraphics` object is composed of `Tile`s. This is a powerful tool, and you can implement more\ncomplex features using simple `draw` operations. In fact the component system is implemented on top of drawing, layering\nand input handling features.\n\nIf you use REXPaint to design your programs, the good news is that you can import your `.xp` files as well. Read more\nabout it [here](https://hexworks.org/zircon/docs/2018-11-22-resource-handling#rexpaint-files).\n\nYou can also use `Modifier`s in your `Tile`s such as `blink`, `verticalFlip` or `glow`. For a full list, check\n[this](https://github.com/Hexworks/zircon/blob/master/zircon.core/src/commonMain/kotlin/org/hexworks/zircon/api/Modifiers.kt)\nfactory object.\n`Modifier`s can either change the texture (like the ones above) or the `Tile` itself:\n\n![Modifiers](images/gifs/modifiers.gif)\n\n### Input handling\n\n\u003e Read about input handling in the docs [here][input-docs].\n\nBoth the `TileGrid` and the `Screen` interfaces implement `UIEventSource` which means that you can listen for user\ninputs using them. This includes *keystrokes* and *mouse input* as well.\n\n### Layering\n\n\u003e Layering is detailed [here][layer-docs]. For a primer on `Screen`s go [here][screen-docs].\n\nBoth the `TileGrid` and the `Screen` interfaces implement `Layerable` which means that you can add `Layer`s on top of\nthem. Every `Layerable` can have an arbitrary amount of `Layer`s. `Layer`s are like `TileGraphics` objects, and you can\nalso have transparency in them which can be used to create fancy effects.\n`Component`s are also `Layer`s themselves. Take a look:\n\n![Layers](images/layers.png)\n\n### Text GUI Components\n\n\u003e You can read more about the Component System on the [documentation page][component-docs].\n\u003e Color themes are detailed [here][color-theme-docs].\n\n`Component`s are GUI controls which can be used for showing content to the user (`Label`s, `Paragraph`s, etc.), enabling\nthem to interact with your program (`Button`s, `Slider`s, etc.) or to hold other components (`Panel`s for example).\n\nThese components are rather simple, and you can expect them to work in a way you might be familiar with:\n\n- You can click on them (press and release are different events).\n- You can attach event listeners on them.\n- Zircon implements focus handling, so you can navigate between the components using the `[Tab]` key\n  (forwards) or the `[Shift]+[Tab]` keystroke (backwards).\n- Components can be hovered, and you can also apply color themes to them.\n\nWhat's more is that you can apply `ColorTheme`s to `Component`s. There are a bunch of built-in themes, and you can also\ncreate your own.\n\nTo see a full list of available `Component`s take a look at the\n[Components](https://github.com/Hexworks/zircon/blob/master/zircon.core/src/commonMain/kotlin/org/hexworks/zircon/api/Components.kt)\nfactory object or navigate to the [component docs page][component-docs].\n\nThis is an example of how components look in action:\n\n![All Components](images/gifs/all_components.gif)\n\n### Animations:\n\n\u003e Read more about Animations in the [docs][animation-docs].\n\nAnimations are supported out of the box. You can either create them programmatically, or statically using *Zircon's* own\nanimation format: `.zap` (Zircon Animation Package). More about that [here][animation-docs]. This is how an animation\nlooks like:\n\n![Animation Example](images/gifs/hexworks_skull.gif)\n\n### Shape and box drawing\n\n\u003e The shape documentation page can be found [here][shape-docs].\n\nYou can draw `Shape`s like rectangles and triangles by using one of the `ShapeFactory` implementations. What's supported\nout of the box is\n*triangle*, *rectangle* and *line*. The former two have filled versions as well. Check out the `Shapes` factory object\n[here](https://github.com/Hexworks/zircon/blob/efa5b6f317eda9c22834140588dcbdd47fb4a3ab/zircon.core/src/commonMain/kotlin/org/hexworks/zircon/api/Shapes.kt)\n.\n\n### Fonts and Tilesets\n\n\u003e The documentation page for tilesets is [here][tileset-docs].\n\nZircon comes with a bunch of built-in fonts tilesets. These come in 3 flavors:\n\n- CP437 tilesets *(More on using them \n  [here](https://hexworks.org/zircon/docs/2018-11-22-resource-handling#cp437-tilesets))*\n- True Type Fonts\n- and Graphical tilesets *(Usage info\n  [here](https://hexworks.org/zircon/docs/2018-11-22-resource-handling#graphical-tilesets))*\n\nZircon also comes with its own tileset format (`ztf`: Zircon Tileset Format) which is **very easy to use**. It is\ndetailed [here](https://hexworks.org/zircon/docs/2018-11-22-resource-handling#the-zircon-tileset-format).\n\n## Road Map\n\nIf you want to see a new feature feel free to [create a new Issue](https://github.com/Hexworks/zircon/issues/new) or\ndiscuss it with us on [Discord][discord]. Here are some features which are either under way or planned:\n\n- [x] [Scrollable Components](https://github.com/Hexworks/zircon/issues/25)\n- [x] [Menus](https://github.com/Hexworks/zircon/issues/135)\n- [x] [Table Component](https://github.com/Hexworks/zircon/issues/185)\n- [x] [Javadoc-style Documentation](https://github.com/Hexworks/zircon/issues/146)\n- [x] [Grid / Screen Filters](https://github.com/Hexworks/zircon/issues/271)\n- [ ] [Floating Components](https://github.com/Hexworks/zircon/issues/23)\n- [ ] [Drag'n Drop Support](https://github.com/Hexworks/zircon/issues/22)\n- [ ] [Custom Layout Support](https://github.com/Hexworks/zircon/issues/28)\n- [ ] [Component Themes](https://github.com/Hexworks/zircon/issues/29)\n- [ ] [Custom Component Support](https://github.com/Hexworks/zircon/issues/26)\n- [ ] [Tree Component](https://github.com/Hexworks/zircon/issues/184)\n- [ ] [Accordion Component](https://github.com/Hexworks/zircon/issues/27)\n- [ ] [Combo Box Component](https://github.com/Hexworks/zircon/issues/262)\n- [ ] [IntelliJ Plugin](https://github.com/Hexworks/zircon/issues/191)\n- [ ] [Console for Zircon](https://github.com/Hexworks/zircon/issues/183)\n\nIf you'd like to give any of these a shot feel free to *contribute*.\n\n## License\n\nZircon is made available under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0).\n\n## Credits\n\nZircon is created and maintained by Addamsson, Coldwarrl, G3ldrin, Milonoir, Seveen and many others.\n\n*We're open to suggestions, feel free to message us on [Discord][discord] or open an issue.*\n*Pull requests are also welcome!*\n\nZircon is powered by:\n\n\u003ca href=\"https://www.jetbrains.com/idea/\"\u003e\n    \u003cimg src=\"https://github.com/Hexworks/zircon/blob/master/images/idea_logo.png\" width=\"40\" height=\"40\"  alt=\"IDEA\"/\u003e\n\u003c/a\u003e\n\u003ca href=\"https://kotlinlang.org/\"\u003e\n    \u003cimg src=\"https://github.com/Hexworks/zircon/blob/master/images/kotlin_logo.png\" width=\"40\" height=\"40\"  alt=\"Kotlin\"/\u003e\n\u003c/a\u003e\n\u003ca href=\"https://www.yourkit.com/java/profiler/\"\u003e\n    \u003cimg src=\"https://github.com/Hexworks/zircon/blob/master/images/yklogo.png\" width=\"168\" height=\"40\"  alt=\"Yourkit\"/\u003e\n\u003c/a\u003e\n\n## Thanks\n\nThanks to the folks over at [Dwarf Fortress Tileset Repository](http://dwarffortresswiki.org/Tileset_repository) for\nletting us bundle their tilesets.\n\nThanks to *Kyzrati* who let us bundle the [REXPaint Tilesets](https://www.gridsagegames.com/rexpaint/) into Zircon!\n\nZircon comes bundled with the [Nethack Tileset](https://nethackwiki.com/wiki/Tileset).\n\nSome True Type fonts are used from [Google Fonts](https://fonts.google.com/).\n\nThanks to *VileR* for the [Oldschool Font Pack](https://int10h.org/oldschool-pc-fonts/) which we bundled into Zircon.\n\n\n[discord]:https://discord.gg/vSNgvBh\n[zircon-version]:2021.1.0-RELEASE\n[examples]:https://github.com/Hexworks/zircon/tree/master/zircon.jvm.examples/src/main\n[api]:https://github.com/Hexworks/zircon/tree/master/zircon.core/src/commonMain/kotlin/org/hexworks/zircon/api\n[internal]:https://github.com/Hexworks/zircon/tree/master/zircon.core/src/commonMain/kotlin/org/hexworks/zircon/internal\n[resource]:https://github.com/Hexworks/zircon/tree/master/zircon.core/src/commonMain/kotlin/org/hexworks/zircon/api/resource\n[zircon-docs]:https://hexworks.org/zircon/docs/\n[animation-docs]:https://hexworks.org/zircon/docs/2019-04-26-animation-support\n[color-theme-docs]:https://hexworks.org/zircon/docs/2018-11-20-working-with-color-themes\n[component-docs]:https://hexworks.org/zircon/docs/2018-11-15-the-component-system\n[crash-course]:https://hexworks.org/zircon/docs/2018-07-18-a-zircon-crash-course\n[design-docs]:https://hexworks.org/zircon/docs/2018-11-20-the-design-philosophy-behind-zircon\n[input-docs]:https://hexworks.org/zircon/docs/2018-11-21-input-handling\n[layer-docs]:https://hexworks.org/zircon/docs/2018-11-21-how-layers-work\n[logging-docs]:https://hexworks.org/zircon/docs/2019-03-27-logging\n[release-docs]:https://hexworks.org/zircon/docs/2019-01-11-release-process-and-versioning-scheme\n[screen-docs]:https://hexworks.org/zircon/docs/2018-08-18-a-primer-on-screens\n[shape-docs]:https://hexworks.org/zircon/docs/2018-11-21-shapes\n[drawing-docs]:https://hexworks.org/zircon/docs/2018-11-19-how-to-work-with-tile-graphics\n[tileset-docs]:https://hexworks.org/zircon/docs/2018-11-22-resource-handling\n\n\n","funding_links":["https://patreon.com/hexworks","https://www.patreon.com/hexworks"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexworks%2Fzircon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhexworks%2Fzircon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexworks%2Fzircon/lists"}