Ascii Hexagonal Grid Pretty Printer

Ascii Hexagonal Grid Pretty Printer is a Java based tool that can output a hexagonal grid to the commandline. This enables a visual inspection of the state of a hex grid which can be usefull for eg. debugging hexagonal grid states.

The tool supports flat and pointed hexes, 2 lines of text, a custom filler char as well as different hex sizes.

1. Usage

Add the following dependency (requires that the library has been built and deployed):

repositories {
    mavenLocal()
}

dependencies {
    implementation 'dk.ilios.asciihexgrid:asciihexgrid:1.0`
}

Build a hex grid like this:

AsciiBoard board = new AsciiBoard(0, 2, 0, 1, new SmallFlatAsciiHexPrinter());
board.addHex("HX1","-B-", '#', 0, 0);
board.addHex("HX2","-W-", '+', 1, 0);
board.addHex("HX3","-W-", '-', 2, 0);
board.addHex("HX3","-B-", '•', 2, 1);
board.prettyPrint(true);

output will look like this:

| = = = = = = = = = = = = |
|    _ _                  |
|  /# # #\                |
| /# HX1 #\ _ _           |
| \# -A- #/+ + +\         |
|  \#_#_#/+ HX2 +\ _ _    |
|        \+ -B- +/- - -\  |
|         \+_+_+/- HX3 -\ |
|               \- -C- -/ |
|                \-_-_-/  |
|                /• • •\  |
|               /• HX4 •\ |
|               \• -D- •/ |
|                \•_•_•/  |
|                         |
| = = = = = = = = = = = = |

2. Coordinate system

The hex grids uses a trapezoidal/axial coordinate system. The axis' look a little different depending on flat or pointed orientation.

Flat orientation:

          _ _
        /     \
   _ _ /(0,-1) \ _ _
 /     \  -R   /     \
/(-1,0) \ _ _ /(1,-1) \
\  -Q   /     \       /
 \ _ _ / (0,0) \ _ _ /
 /     \       /     \
/(-1,1) \ _ _ / (1,0) \
\       /     \  +Q   /
 \ _ _ / (0,1) \ _ _ /
       \  +R   /
        \ _ _ /

Pointy orientation:

       / \     / \
     /     \ /     \
    | -1,-1 |  1,-1 |
    |   -R  |       |
   / \     / \     / \
 /     \ /     \ /     \
| -1,0  |  0,0  |  1,0  |
|  -Q   |       |   +Q  |
 \     / \     / \     /
   \ /     \ /     \ /
    | -1,1  |  0,1  |
    |       |   +R  |
     \     / \     /
       \ /     \ /

Negative coordinates are currently not supported, ie. (0,0) is the top-left corner. If you hex grid have negative coordinates, they can be shifted correctly by the following algorithm (pseducode):

int adjustQ = hexes.getMinQ();
int adjustR = hexes.getMinR();
board.addHex("HX1","-A-", hex.getQ() - adjustQ, hex.getR() - adjust);

3. Examples

Currently, 4 types of hexes are supported: Small/large flat and small/large pointed. Examples can be seen below:

Small flat:

   _ _
 /• • •\
/• HX1 •\ _ _
\• -B- •/- - -\
 \•_•_•/- HX2 -\ _ _
       \- -W- -/- - -\
        \-_-_-/- HX3 -\
              \- -W- -/
               \-_-_-/
               /• • •\
              /• HX4 •\
              \• -B- •/
               \•_•_•/

Large flat:

   _ _ _ _
  / • • • \
 /• • • • •\
/•   HX1   •\_ _ _ _
\•   -B-   •/ - - - \
 \• • • • •/- - - - -\
  \_•_•_•_/-   HX2   -\_ _ _ _
          \-   -W-   -/ - - - \
           \- - - - -/- - - - -\
            \_-_-_-_/-   HX3   -\
                    \-   -W-   -/
                     \- - - - -/
                      \_-_-_-_/
                      / • • • \
                     /• • • • •\
                    /•   HX4   •\
                    \•   -B-   •/
                     \• • • • •/
                      \_•_•_•_/

Small pointy:

   /•\     /-\     /-\
 /• • •\ /- - -\ /- - -\
|• HX1 •|- HX2 -|- HX3 -|
|• -B- •|- -W- -|- -W- -|
 \• • •/ \- - -/ \- - -/•\
   \•/     \-/     \-/• • •\
                    |• HX4 •|
                    |• -B- •|
                     \• • •/
                       \•/

Large pointy:

     /•\         /-\         /-\
   /• • •\     /- - -\     /- - -\
 /• • • • •\ /- - - - -\ /- - - - -\
|•   HX1   •|-   HX2   -|-   HX3   -|
|•   -B-   •|-   -W-   -|-   -W-   -|
|• • • • • •|- - - - - -|- - - - - -|
 \• • • • •/ \- - - - -/ \- - - - -/•\
   \• • •/     \- - -/     \- - -/• • •\
     \•/         \-/         \-/• • • • •\
                              |•   HX4   •|
                              |•   -B-   •|
                              |• • • • • •|
                               \• • • • •/
                                 \• • •/
                                   \•/

4. Build

For building and publishing the library. Run

> ./gradlew publishToMavenLocal

from the command line. The jar can now be found in ~/.m2/repository/dk/ilios/asciihexgrid and can be included using the mavenLocal() repository.

5. Credit

For an incredible useful and thorough guide on all things hexagonal grid related, see this excellent blog post by Red Blob Games:

http://www.redblobgames.com/grids/hexagons/