Hex Grid Renderer (HGR)is an Android app for creating hexagonal grids and exporting them to image files. It is intended as a utility for gamers who play tabletop games which use hex grids. It has a variety of options for modifying the grid, as described in more detail below. HGR is available in via Google Play for the low, low price of 0.0 Euros (that’s zero of your American dollars):

https://play.google.com/store/apps/details?id=net.wanderinghorse.android.hexish

It appears to be the only Android app of its kind available. HGR is my first Android app, but was not supposed to be. i was experimenting with some code for calculating hexagon geometries, wondering if i could use it to finally create “that game i’ve always wanted to do.” Somewhere along the way i kept adding features to help test it, and it kind of turned into a mini-app. So i went ahead and published it on Play, added some non-testing-related features (undo, load/save, and whatnot), and now it lives as a standalone app. And i still haven’t gotten around to working on that game.

Source Code: please see the source code page.

HGR Introduction

Hex Grid Renderer is a simple application for creating hexagon grids, intended for use by players of tabletop games which use hex maps. HGR appears to be the only app of its kind in the Google Market. HGR is BETA, and very possibly has some outstanding bugs (see further on down the page for the ones i know about). It is not terribly pretty, but what’s there seems to work. If i had had this app 20 years ago, i would have been a very happy gamer.

Features

• Easily create hexagon grids with only a few finger-taps.
• Customize the colors, labels, center dots, and border.
• Export hex grids as image files to other Android Activities via Intents. What does that mean? It means it can export your hex grids directly to GMail, GDrive, Dropbox, printer services, and others.
• Has undo (10 levels) and save/load support.
• It speaks English and German. If you want it in a language of your choice, get in touch and i will send you the information you need to translate it :). Contact info is at the bottom.

ACHTUNG: If your device force-closes this immediately or when changing map sizes, then it has too little memory. See the NOTES section below for why.

Permissions

HGR requires EXTERNAL STORAGE WRITE permissions in order to save its images to the SD card (see below) before handing them off to services like GMail, GDrive, or Dropbox. If there were a way to do this without a file, andnot risk an out-of-memory error by buffering the exported data in a byte array, the app would need no special permissions.

Storage Locations

HGR stores its own state in the Android-provide app-private space (which requires no special permissions). In order to export the hexes as PNG files it needs to write them somewhere where other apps can read them, which means putting them on the SD card.  It stores any exported data under:

<SDCARD>/app-data/net.wanderinghorse.android.hexish/

(Reminder to self: try out the WORLD_READABLE flag in private storage again, now that the file-loading problems are solved. With that working we once again won’t need special permissions to export PNGs.) HGR does not export via Android’s Media Manager because doing so forces the images into JPEG format (not sure why) and has atrocious results for these particular graphics (the labels are unreadable and the grids are fuzzy).

Device Compatibility

HGR is has been seen to work on API7 devices(Android 2.1.x). It is tested on several emulator configurations (with various Android versions), a Samsung Galaxy S2 phone, and an Asus TF300 tablet (both running ICS).

Notes and Caveats

• “No warranties,” and all that. It’s free for any purpose. The source code is available for download.
• When exporting an image, a copy is placed in your SD storage under under SDCARD/app-data/net.wanderinghorse.android.hexish/. (Trivia: “hexish” was the package name i used while experimenting and neglected to change it before releasing the app. Changing it now would force me to upload HGR as a whole new app.)
• If HGR suddenly crashes at startup (after it worked before), try the “Clear Data” option in the app control center to remove its persistent state. This “shouldn’t happen”, but just in case it does. i have never seen this happen, but can conceive of a couple cases where it might (e.g. the app getting killed by a power-off or the OS at exactly the wrong microsecond while HGR is writing its file).

Mini-HowTO

HGR is trivially simple to use and can be mastered in under 10 minutes. It uses a series of menus and popups to prompt for options relating to the configuration of the grid and other actions like loading/saving grids and exporting PNG images. Note that the UI is very primitive because my Android skills are primitive. As my experience with Android improves, HGR will be a good place to try out new ideas. i.e. the plan is to update the UI incrementally as i figure out what the Android UI API can and cannot do for me. HGR manages a small handful of basic drawing components, each of which has its own menu area (in version 20120709 this was changed from a set of menus to a preferences-style list):

• Grid: (v20120709+) Modify the grid size and orientation (tall- vs. wide-grain).
• Hexes: modify the hexagon colors, sizes, etc. In versions older than 20120709 this menu also holds the Grid options.
• Dots: center-dots can have their size and color changed.
• Labels: text markings on the hexes. They can be formatted to display the row/column numbers in a variety of ways.
• Border: a simple border around the edge of the grid. It can be colored and its size changed.
• Background: the color can be modified. TODO: use an image as a pen.

Known Problems

• If the app starts up with a blank black area, use Hexes==>Radius to set the radius. It sometimes gets set to 0 and i do not know where it is happening. (This might be a side-effect only i am seeing, as a result of using test builds on my devices which leave older app state lying around.)
• Export to G+ fails mysteriously. i have no idea why (maybe it doesn’t like PNG format?). GDrive, GMail, and Dropbox exports are known to work, as well as a couple lesser-known apps i’ve tried.
• If it crashes after changing radii or dimensions, or toggling on buffering, then the problem is almost certainly that the rendered grid takes up too much memory and Android is killing the app. Workaround: scale it back a notch. The memory hog is the drawing/scrolling parts, not the actual hex data (which has low, constant memory costs, independent of the number of hexes in the grid).
• It is not yet possible to remove entries from the list of saved grids without removing all saved data (via deinstallation or the the “Clear Data” option in the app control panel). However, it is not expected that anyone will save 50 different grid configurations. (Even if they did, it’s only about 30kb of storage (in one file), but it would be a hassle to navigate using the current UI.)

Reporting Problems, Feature Requests, etc.

Please send problem reports directly to me (sgbeal at googlemail).

Notable TODOs

While HGR is essentially feature-complete, there are a couple more notable TODOs (in no particular order)…

• Change the font size for the hex labels. i haven’t yet figured out how to do this (Android appears to consider font control to be solely domain of the OS).
• Add stroke styles to the hexes and border pens. The first alpha version had this, but i have never added the JSON support for it, so it was removed. (It’s not hard, it just needs an hour or two of attention.)
• Saving/Loading:
  • Export/import saved data (JSON, not images), either via SD or Intents.
  • Allow selection of a previous profile to overwrite. Overwriting is currently automatic if one re-uses a name (and there is no warning when this happens).
  • Provide a way to remove individual saved profiles. A ListView of checkboxes would be ideal.

i think that’s about it.