Switch branches/tags
Nothing to show
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
..
Failed to load latest commit information.
tool
README

README

 ____ ____ ____  _____ _ _     _____ _____
|  _ ' _  |  _ \|_   _| | |   |  ___|  _  |
| | | | | | | | | | | | | |   | |__ | |_| |
| | | | | | | | | | | | | |   |  __||    _|
| | | | | | |_| | | | | | |___| |___| |\ \
|_| |_| |_|____/  |_| |_|_____|_____|_| \_\

mdtiler version 1.80
©2011, 2012, 2016, 2017, 2018 Sik

mdtiler is a command line tool to convert images into tiles that can be used
in Mega Drive software. It provides a quick build mode that will just convert
an entire bitmap into tiles and an advanced batch build mode that lets you
specify what tiles to convert, in what order and even lets you use multiple
files.

mdtiler is released under the GPL version 3 or later. Check the file LICENSE
for more details, or check http://www.gnu.org/licenses/gpl-3.0.txt

In order to build the current version of mdtiler you will need the following
libraries:

   - libpng (depends on zlib)

-----------------------------------------------------------------------------

Quick build is the simplest way to use mdtiler, but also it's really limited.
It takes a bitmap and converts all of it into tiles. To use this mode, you
need to use the -t or -s switches, depending in what order you want the tiles
to be stored.

To output tiles in the same order as tilemaps (left to right, then top to
bottom), call mdtiler as follows:

   mdtiler -t «in-file» «out-file»

To output tiles in the same order as sprites (top to bottom, then left to
right), call mdtiler as follows:

   mdtiler -s «in-file» «out-file»

It's also possible to specify the -1 switch to output 1bpp tiles instead of
4bpp tiles.

-----------------------------------------------------------------------------

Batch build is more complex but also provides the most flexibility. It lets
you process multiple images at the same time, and also lets you choose which
tiles to output and in which order. This is specially useful for sprite
mappings, and for compression since you can output multiple graphics as a
single blob file if you want. You will need to provide a "batch file"
(essentially a text file, see below) that tells mdtiler what to do.

To use batch build, call mdtiler as follows:

   mdtiler -b «batch-file»

Batch files consist of multiple commands, each command being in its own line
(blank lines are ignored), parsed from top to bottom, in order (i.e. settings
only apply to commands below them, not the ones above them).

If a # is found when the parser expects a token, it starts a comment and
everything in the line after that point is ignored. You can use this to
document what's going on.

The available commands are as follows (where «» specify parameters):

   input «filename»
   
      Specify input file. All following tiles will be read from this image.
      You need to specify an input file before you can output tiles.
      
      You must enclose the filename inside quotes if it has spaces (e.g.
      "this name has spaces"). Quotes are optional if there aren't spaces
      (e.g. thisisaname or "thisisaname").
   
   output «filename»
   
      Specify output file. All following tiles will be written to this file.
      You need to specify an output file before you can output tiles.
      
      You must enclose the filename inside quotes if it has spaces (e.g.
      "this name has spaces"). Quotes are optional if there aren't spaces
      (e.g. thisisaname or "thisisaname").
   
   output2 «filename»
   
      Secondary output file, used by the map command (see below). The tilemap
      will be written to this file.
   
   palette «color1» «color2» «color3» ... «color16»
   
      TRUE COLOR BITMAPS ONLY: tells mdtiler which palette to use. 16 colors
      have to be specified, as hexadecimal values in the same format the VDP
      wants (e.g. AAA would be light gray, E00 would be blue, 08E would be
      orange, etc.).
      
      For performance reasons, the palette is applied only when the bitmap is
      loaded (i.e. when the "input" command is issued). If you want to apply
      a new palette make sure that the bitmap is loaded again after this.
      
      This command does nothing for paletted bitmaps, in which case mdtiler
      will use the color indices directly.
   
   remappal «group» -> «palette»
   
      PALETTED BITMAPS ONLY: tells mdtiler how to remap the colors to each
      palette. The upper four bits of the color index are used as the «group»
      (i.e. colors 0-15 are group 0, colors 16-31 are group 1, etc.). This
      command lets you decide how each group maps to each VDP palette
      (palettes 0-3 for low priority, palettes 0-4 for high priority).
      
      The default mappings are
      
          0 -> 0      1 -> 1      2 -> 2      3 -> 3
          4 -> 4      5 -> 5      6 -> 6      7 -> 7
          8 -> 0      9 -> 1     10 -> 2     11 -> 3
         12 -> 4     13 -> 5     14 -> 6     15 -> 7
      
      And yes, that's literally -> in the command.
   
   tiles «x» «y» «width» «height»
   
      Reads a block of tiles from the input image and converts them into the
      output file. The parameters «x» and «y» specify the coordinates of the
      top-left corner, while the parameters «width» and «height» specify the
      dimensions of the block. They're always measured in tiles.
      
      If you just want to read individual tiles, you can just pass 1 as
      both width and height.
   
   map «x» «y» «width» «height»
   
      Takes a block of tiles and generates a tilemap. The tiles will be
      written to the main output file (see output) and the tilemap itself
      will be written to the secondary output file (see output2). This tool
      will look for redundant tiles (flipping, same but other palette, etc.)
      
      The tilemap consists of a word for each tile, starting from $0000. Each
      word can include flipping, palette and priority flags. To have mdtiler
      proces palette and priority, you must use an 8bpp PNG (256 colors) then
      arrange colors as follows:
      
         - Every 16 colors is a different palette row
         - The first 64 colors are low priority
         - The next 64 colors are high priority
   
   sprite «x» «y» «width» «height»
   
      Makes a sprite entry for a sprite mapping. The tiles will be written
      to the main output file (see output), while the entry will be written
      to the secondary output file (see output2). Call this command for
      every sprite needed in the mapping, then "sprite end" (see below) to
      finish the mapping.
      
      Each entry in the mapping consists of four words:
      
         - X offset in pixels (relative to origin)
         - Y offset in pixels (relative to origin)
         - Tile ID + flags (same format as VDP)
         - Sprite size (same format as VDP)
      
      Only works when layout = sprite and for sizes from 1×1 to 4×4.
      Currently it can't detect repeated sprites (it won't optimize those)
      or different palettes (everything uses the same palette).
   
   sprite end
   
      Writes the sentinel value to the secondary output file (see output2)
      indicating the end of the sprite mappings. The sprite tile IDs return
      back to the initial offset value here too (if they aren't continuous,
      see below).
      
      The sentinel entry is a single word with value $8000.
   
   origin «x» «y»
   
      Changes the origin coordinates for sprite commands. These coordinates
      are given in pixels (*not* tiles) and should point to the pixel in the
      metasprite to be used as origin (i.e. these coordinates are substracted
      from the sprites' own).
   
   offset «offset»
   
      Sets the first tile ID that will be generated by following map and
      sprite commands. If not called then it'll be 0 by default.
   
   offset continuous
   
      Turns on "continuous" mode. Each map command will increment the offset
      by the number of tiles it generated. This allows consecutive map
      commands to be issued all with consecutive tile IDs (without having to
      know how many tiles to offset ahead of time).
   
   offset restarting
   
      The opposite of the above. The offset value will not be changed after
      each map command and every map will be using the same base tile ID.
   
   layout tilemap
   
      Since now on, all groups of tiles will be output following tilemap
      ordering (i.e. left-to-right, then top-to-bottom). This is the default
      setting.
   
   layout sprite
   
      Since now on, all groups of tiles will be output following sprite
      ordering (i.e. same order used for sprites in the Mega Drive).
   
   format 4bpp
   
      All following tiles will be output in 4BPP format (4 bits per pixel,
      same as Mega Drive hardware). This is the default setting.
   
   format 1bpp
   
      All following tiles will be output in 1BPP format (1 bit per pixel).

-----------------------------------------------------------------------------

List of all switches:

   -b or --batch ..... Batch build
   -t or --tilemap ... Quick build (tilemap ordering)
   -s or --sprite .... Quick build (sprite ordering)
   
   -4 or --4bpp ...... Output 4bpp tiles in quick build (default)
   -1 or --1bpp ...... Output 1bpp tiles in quick build
   
   -h or --help ...... Print program usage to stdout
   -v or --version ... Print program version to stdout