* =imbricate= Makes Tilesheets For Games

  The =imbricate= produces tile sheets from a directory tree the
  leaves of which are PNG image files.  

  The PNG files can be of any size.  The =imbricate= tool will attempt
  to pack the tiles into a square tile sheet.

  Imbricate also produces an "index file" for the tilesheet, providing
  a name and a location of each individual image.  The index can be in
  Lisp or JSON formats.  

** Example

*** Running =imbricate=

 Suppose you have a bunch of separate directional pad (DPad) buttons:

 #+BEGIN_EXAMPLE

 $ tree
 .
 └── Dpad
     ├── DownLeft.png
     ├── Down.png
     ├── DownRight.png
     ├── Left.png
     ├── Right.png
     ├── UpLeft.png
     ├── UP.png
     └── UpRight.png


 #+END_EXAMPLE

 To create a single image that contains all of them, just do:

 #+BEGIN_EXAMPLE

 $ imbricate Dpad/ dpad

 Reading images from disk........
 Creating Layout........
 Constructing tilesheet........
 Writing to disk...
 ALL DONE

 #+END_EXAMPLE

 Now your working directory shoul look like:

 #+BEGIN_EXAMPLE

 $ tree 
 .
 ├── Dpad
 │   ├── DownLeft.png
 │   ├── Down.png
 │   ├── DownRight.png
 │   ├── Left.png
 │   ├── Right.png
 │   ├── UpLeft.png
 │   ├── UP.png
 │   └── UpRight.png
 ├── dpad.bad.txt
 ├── dpad-index.lisp
 └── dpad.png


 #+END_EXAMPLE

*** The Output

 The file =dpad.bad.txt= is hopefully empty. It contains information
 about processing errors that =imbricate= may have encountered.

 The file =dpad.png= is the resulting image - it should contain
 everything from the target directory.

 The file =dpad-index.lisp= is a list of plists. For the above
 example, it looks like this:

#+BEGIN_EXAMPLE

$ cat dpad-index.lisp 

((:|name| "Dpad.Down" :|x| 54 :|y| 108 :|width| 54 :|height| 54)
 (:|name| "Dpad.DownLeft" :|x| 0 :|y| 162 :|width| 54 :|height| 54)
 (:|name| "Dpad.DownRight" :|x| 54 :|y| 54 :|width| 54 :|height| 54)
 (:|name| "Dpad.Left" :|x| 108 :|y| 0 :|width| 54 :|height| 54)
 (:|name| "Dpad.Right" :|x| 0 :|y| 108 :|width| 54 :|height| 54)
 (:|name| "Dpad.UP" :|x| 54 :|y| 0 :|width| 54 :|height| 54)
 (:|name| "Dpad.UpLeft" :|x| 0 :|y| 54 :|width| 54 :|height| 54)
 (:|name| "Dpad.UpRight" :|x| 0 :|y| 0 :|width| 54 :|height| 54)) 

#+END_EXAMPLE

*** JSON Output

You can opt for JSON output instead of Lisp by passing the =-json=
option to =imbricate= after all the other arguments:

#+BEGIN_EXAMPLE

$ imbricate Dpad dpad -json

$ cat dpad-index.json   # this is after M-x json-pretty-print-buffer in emacs

[
  {
    "name": "Dpad.Down",
    "x": 54,
    "y": 108,
    "width": 54,
    "height": 54
  },
  {
    "name": "Dpad.DownLeft",
    "x": 0,
    "y": 162,
    "width": 54,
    "height": 54
  },
  {
    "name": "Dpad.DownRight",
    "x": 54,
    "y": 54,
    "width": 54,
    "height": 54
  },
  {
    "name": "Dpad.Left",
    "x": 108,
    "y": 0,
    "width": 54,
    "height": 54
  },
  {
    "name": "Dpad.Right",
    "x": 0,
    "y": 108,
    "width": 54,
    "height": 54
  },
  {
    "name": "Dpad.UP",
    "x": 54,
    "y": 0,
    "width": 54,
    "height": 54
  },
  {
    "name": "Dpad.UpLeft",
    "x": 0,
    "y": 54,
    "width": 54,
    "height": 54
  },
  {
    "name": "Dpad.UpRight",
    "x": 0,
    "y": 0,
    "width": 54,
    "height": 54
  }
]


#+END_EXAMPLE


** Building

Assuming that you have [[https://github.com/roswell/roswell][roswell]] installed:

: $ ros use sbcl 
: $ git clone https://github.com/cbeo/imbricate.git 
: $ cd imbricate.git
: $ ros build imbricate.ros

I copy the resulting executable to =~/.local/bin=, which is in my =PATH=.

: $ cp imbricate ~/.local/bin


** Caveats

I made this for my own use, but relased it thinking it might be useful for others.  

Presently, the tool only works with PNG files that have RGBA
format. (i.e each pixel takes up 4 bytes).