A short guide to Tiles creation
===============================

This document aims to give a simultaneously short and detailed explanation
about everything you need to know if you want to design tiles for Dungeon Crawl
Stone Soup. You can also find this text, and potentially a more up-to-date
version of it, at:
https://github.com/crawl/crawl/blob/master/crawl-ref/docs/develop/tiles_creation.txt


Table of Contents
=================
1. The Tools
2. Grabbing the source
3. Basic design principles
   3.1 Format and size
   3.2 Icons
   3.3 Proportions
   3.4 Perspective
   3.5 Colouring
   3.6 Outline
   3.7 Shading
   3.8 Transparency
4. Creating tiles
   4.1 Reuse existing tiles
   4.2 Pixel art tutorials
   4.3 Wielded weapons
   4.4 Semi-transparency
5. Modifying the code base
   5.1 Defining tiles
   5.2 Making Crawl use the tiles
   5.3 Artefact tiles
   5.4 Dynamic weapons
   5.5 Variant tiles
6. Compiling the game
7. Tiles priorities
8. Submitting your tiles
9. Reducing file size


1. The Tools
============

First, you'll need some image editing software such as Photoshop,
Paint.net (http://www.getpaint.net/download.html), Photoshop or the GIMP
(http://www.gimp.org/downloads/) as well as some basic knowledge of how to
use it.

While the fancier functions and filters can occasionally come in useful, the
simpler tools for drawing and selection will usually suffice. Before starting,
try to acquaint yourself with the different-sized "pencils" and erasers,
different-shaped selection tools, the paint bucket used for filling larger
areas, and the colour selection.

Also, while a drawing tablet is certainly useful, it is by no means required.


2. Grabbing the source
======================

You may want to download the source package or even the trunk version. Either
way, the source/rltiles/ directory contains all tiles used in the game, and
some more that are currently unused. While you can create new tiles without
having access to existing ones, it can be useful to have them around for
comparison.

You can download the latest source from the usual release site:
https://github.com/crawl/crawl

To download the development version, you'll need to install and use git.
See docs/develop/git/quickstart.txt for further instructions.

Also, you'll probably want to compile your tiles into the game to test your
creations. (You don't have to, though.)
It is recommended that you first try to get the game compiled without any
changes. See INSTALL.txt for instructions.

If you're going to change anything in the main code you might also want to
create a patch. See docs/patch_guide.txt for help with that.


3. Basic design principles
==========================

3.1 Format and size
-------------------

Stone Soup's tiles are basically png files in a format of 32x32 pixels. Larger
tiles such as for the pandemonium demons are possible, but require additional
coding and should be used sparingly. Also, the tab tiles are deliberately
smaller and have a size of 20x20 px.

Background tiles (walls and floor) should cover the entire square, whereas
foreground images can use the whole area but are usually smaller. Also keep
in mind that hiding the background often equals a loss of information, and
that especially for monsters we might also need to fit some status icons into
the tile.

In the inventory area, items and spells are getting displayed with a two-pixel
coloured border around them. Tiles may overlap this border, but it looks a bit
odd if they do, so it's better to keep their size at 28x28 pixels.

3.2 Icons
---------

Subtype icons for potions need to fit inside the label, so may be at most
14x15 pixels large. It seems prudent to apply the same size restrictions to
other subtype or brand icons.

For status effect icons, you need to take into account that we might need to
display several of them at the same time, so these icons should have a
customary size of up to 8x8 or 10x10 pixels, though they don't need to be
square, of course. Larger icons are of course possible, but should be used
sparingly as there's always the danger that they might not fit.

Icon tiles are always placed on top of the base tile, beginning at its top left
corner for icons smaller than 32x32 pixels, and then moved by an offset that
is hardcoded for the status effects, numbers etc.

3.3 Proportions
---------------

Humans and other creatures are proportioned more or less realistically, with
the entire body usually equaling about five times the height of its head. The
less humanoid the creature, the less important this becomes, but really
cartoonish monster tiles would stand out against the others.

The height of monsters is independent of monster size, i.e. a dragon, goblin
and curse toe may all fill their respective tiles. Similarly, the greater size
of pandemonium lords does not reflect their body size, but rather is supposed
to underline their being special monsters.

The same holds for items, which is why armour and weapon tiles usually come in
two varieties: a large version for the inventory display and a smaller one for
the player doll (and, in the case of weapons, monsters).

3.4 Perspective
---------------

Any item or monster should fit into the allocated space in its entirety, legs
and all. This restriction may only be loosened if the chopped portions are
never visible to the player, for example because they are always covered by
water or lava.

Ideally, both monsters and items should be depicted at a slight angle from the
front or side, so you can see both its face and profile.

3.5 Colouring
-------------

In theory, tiles can use any colour within the spectrum of visible colours.
However, very small gradients are almost unnoticeable and often end up making
the tile look blurry instead. It is thus generally recommended to pick two or,
rarely, three base colours and use large step shading between for further
differentiation.

Try to pick sensible colours that are easy to see even on dark background.
Also, for monsters take into account on which textures you'll usually be
encountering the tile (e.g. water for amphibious monsters), and try to choose
colours that are easy to make out against such background.

At the same time, try to avoid garish colours or contrasts, as they can be
quite distracting in a game.

3.6 Outline
-----------

All tiles that don't fill the entire square should get a black outline. You can
add it manually or tell Crawl to do it later when creating the tile maps. In
particular, this means that for non-outlined tiles there should be a border
of at least 1 pixel around the entire tile. Some of the larger tiles currently
don't have this and they look a bit chopped because of this.

3.7 Shading
-----------

Item and monster tiles should always include a shadow on the ground, which you
can draw using standard black.

The imaginary light source is always above and in front of the depicted object,
so that most of it is properly lighted and the shadow falls (for animals) in
direction of its tail or backside. For creatures directly facing the player as
well as inanimate items and features the default light source origin is in
front of it and to the upper left, so that the resulting shadow falls slightly
behind the tile and to its lower right. Similarly, parts to the lower right are
usually shaded darker than those on the upper left. Try to think of the
depicted feature or monster as a three-dimensional object and use shading to
add depth to the tile. As a general rule, the further back something is, the
darker it should be coloured. You can use contrast to make things in front
stand out a bit more.

Icons may use shading to make them look more 3dimensional, but they don't have
to, and they don't get a shadow of their own.

3.8 Transparency
----------------

Foreground tiles should have a transparent background, so they can be properly
drawn on top of the background tile, but if your image software doesn't support
png files with transparent background you can also submit a png or bmp with the
background coloured differently from the rest of the tile, so we can easily
make it transparent later-on.


4. Creating tiles
=================

4.1 Reuse existing tiles
------------------------

Whenever you're faced with the task of creating a new tile, consider whether
you can reuse an existing tile, either because it is currently not seeing use
(check out the rltiles/UNUSED directory for this) or because it can easily be
tweaked by adding details or changing its colour. Flipping or rotating (part
of) a tile can make a huge difference already, and sometimes a combination of
parts taken from different existing tiles can be used to great effect.

For human monsters, usually uniques, in addition the in-game doll editor
(reachable via the '-' command) can be used to create good-looking tiles. If
you do this, please use non-standard equipment for your player doll, so the
odds of the player running into a look-alike are low.

4.2 Pixel art tutorials
-----------------------

We really recommend the following tutorials to anyone interested in tiles
design:

  * http://www.derekyu.com/?page_id=219
    A well-written introduction to the techniques of pixel art.

  * http://gamesprites.wikicomplete.info/tutorial:sprite-art-101-basic-depth
    A simple little tutorial on shading and depth perception.

  * http://gas13.ru/v3/tutorials/sywtbapa_almighty_grass_tile.php
    A detailed explanation of how to create the perfect pixels. Several
    chapters dealing with scenery and sprite design. Also covers the elusive
    difference between art and _good_ art. Made me go back and redo all my
    tiles designs. (jpeg)

4.3 Wielded weapons
-------------------

Humanoid monsters, in particular uniques, will usually be facing to the left
with their right hand outstretched so they can be displayed wielding their
current weapon, which is added into the tile dynamically.
(For this to look good, the hand needs to be or at least include a rectangle of
2x3 pixels, which can be a bit tricky sometimes.)

If the monster is a spellcaster or has a predefined weapon it is guaranteed to
wield you can ignore this step and get by without a weapon or add a static one.
Even for melee-centric monsters this is not necessary, but displaying the
wielded weapon is a really nice perk to playing the tiles version and should be
used whenever possible.

4.4 Semi-transparency
---------------------

For some features or monsters you might need part or the entirety of the tile
to be see-though semi-transparent. Examples include clouds and some monsters.

I usually do this by means of the eraser, set the size to the maximum possible
and the opacity to around 34%, and then "erase" the entire area I want to be
semi-transparent, having previously selected it.

5. Modifying the code base
==========================

If you are uncomfortable with changing the code or compiling the game, you can
simply submit your creations and leave the rest to us. :)

5.1 Defining tiles
------------------

Tiles are assumed to have been placed within the rltiles/ directory structure.
You can use a relative path for the tile definition, or you can use the %sdir
command to change the current default relative path.

More information about rltiles (including syntax reference) can be found here:
http://crawl.develz.org/wiki/doku.php?id=dcss:help:rltiles

The definition files are as follows:
  * dc-corpse.txt: Define corpse tiles that are created automatically based on
                   the corresponding monster tiles.
  * dc-demon.txt:  Define tiles used for the pandemonium lords.
  * dc-dngn.txt:   Define wall, floor and dungeon feature tiles. All tiles
                   defined herein are collapsed into dngn.png and dngn.html.
  * dc-gui.txt:    Includes some other files, whose tiles are included in
                   gui.png and gui.html.
  * dc-item.txt:   Define mundane item tiles.
  * dc-main.txt:   Includes some other files, whose tiles are included in
                   main.png and main.html.
  * dc-misc.txt:   Define tiles for clouds, special effects and status icons.
  * dc-mon.txt:    Define monster tiles excepting pandemonium lords.
  * dc-player.txt: Define player doll and equipment tiles. All tiles defined
                   here and in included files form player.png and player.html.
  * dc-spells.txt: Define spell tiles.
  * dc-unrand.txt: Auto-generated file defining artefact tiles.

Remember that new monsters may also need a new corpse tile if they don't share
their genus with an already existing monster, in which case you'll need to
declare the same monster tile in both dc-mon.txt and dc-corpse.txt.

If you are unsure how to add your tile, you can simply check how similar tiles
are defined, and add yours below, following their example.

Use the %rim property to control whether Crawl needs to draw a black outline
around your tile or whether it already has one. To change the rim property for
your tile, use e.g.:
   %rim 1
   new_tile NEW_TILE
   %rim 0

5.2 Making Crawl use the tiles
------------------------------

If your tile doesn't replace an existing one, you might have to modify the
code, which is to say tilepick.cc.

Jewellery, potions, scrolls and staves use a hard-coded item order, so you
really shouldn't have to change anything in the code.

For all others search the file, as necessary, for:
  * tileidx_armour_base
  * tileidx_cloud
  * tileidx_corpse
  * tileidx_feature
  * tileidx_misc
  * tileidx_missile
  * tileidx_monster_base
  * tileidx_rune
  * tileidx_player (transformations, only)
  * tileidx_shop
  * tileidx_spell
  * tileidx_trap
  * tileidx_weapon_base

There's probably a TODO comment next to the monster, item, feature or spell in
question. If not, you will need to add a case/return statement similar to the
others at the end of the switch loop. This is likely because the object is
completely new, in which case you're probably the one to add it, so you should
know the required enum. If you don't know, you can try to find out or simply
submit the tile and leave the code modifications to the devteam. :)

For the tile enum, use the same (uppercase) definition as defined in the
dc-xxxx.txt file, while copying the prefix from the other tiles.

5.3 Artefact tiles
------------------

New randart weapons and armour items need not only a tile for the item
itself but also a smaller variant for the player doll to wield or wear.
To define the new artefact tiles, you'll need to modify two files:
source/art-data.txt, and rltiles/dc-player.txt, with the details nicely
described in art-data.txt.

If you have perl installed, run "perl art-data.pl" from source/util. If you
made any mistakes in modifying the two files the script will complain.

If an artefact doesn't get a special equipment tile the base type's tile
will be used instead.

For the base items you'll need to modify dc-item.txt or dc-unrand.txt as well
as tilepick.cc, as defined above. For the doll equipment, however, this is
handled by the perl script and won't be necessary.

5.4 Dynamic weapons
-------------------

For humanoid monsters' tiles you may want to add a line in get_weapon_offset()
of tilemcache.cc to allow it to be drawn with a wielded weapon.

The best course of action is probably to start out with adding the monster to
the first list of monsters with an offset of 0 along either axis, then compile
to check how it looks. You can use the wizmode &m command to create the monster
and, if it happens to be unarmed, use 'x' to target the monster, then use the
&g command to give it a weapon from your inventory. If the monster refuses to
take your weapon this might be because it is incapable of using weapons, in
which case you can skip this entire step, or because it can only use weapons it
was created with, in which case you'll need to make sure it does get a weapon
in mon-gear.cc and repeat the &m command until you get a version of it wielding
something. Once you've got this set up, you can just save and restore without
taking any further steps until you are satisfied with the result.

If the weapon doesn't appear to be held in the monster's hand, add a new case
block just for your monster and take a guess at the number of pixels the weapon
needs to move the left/right and up/down to fit. You'll probably have to
recompile a couple of times, tweaking the offset values each time, until you
get it right.

5.5 Variant tiles
-----------------

Tileset variants can be used in three different ways:
  1. Once chosen, they are fixed.
     - This is the case for all wall and floor tiles.
  2. Every time the screen is redrawn, one variant is chosen at random.
     - This applies to pretty much all features that don't fit the above
       requirement.
  3. Variants are picked in order, every time the screen is redrawn.
     - This is currently only used in very specific, hardcoded circumstances.

If your tile is one more variant of a tile that already has several versions,
you shouldn't need to take any further steps, and the tile should already be
picked randomly from time to time. The same applies to animated feature tiles.
For either of these, you might want to add %weight tags to make your new tiles
appear more or less commonly than the already existing ones.

If you are animating something other than a feature that used to be static,
more code will be necessary, but this is something that is probably better left
to the devteam. Monster variants, in particular, are entirely hardcoded.
By default, only the first tile out of set of monster tiles will be chosen.
Special cases have been added to pick an appropriate one according by colour
or other properties.


6. Compiling the game
=====================

When compiling the game after adding tiles not yet in the repository, you may
need to delete or rename the relevant tile section's png file, i.e. main.png
(for items), player.png (for player, doll equipment, and monsters), dngn.png
(for dungeon features) or gui.png (for spells), for the changes to take
effect. The first step during the compilation will be to rebuild this file,
so you can check right away whether your new tile was added correctly.

If you've changed the number of tiles included in main.png, you'll need to also
update player.png (by deleting it and recompiling) because otherwise all
monster and player tiles will be misdisplayed, and drawing some tiles could
even cause a crash.

Changes in dc-xxxx.txt automatically cause the relevant image files to be
recreated, as will changes to tiles included in the git repository.

See INSTALL.txt for compilation instructions. It is recommended that you first
try to get the game compiled without any changes. If you face any problems,
don't hesitate to make posts in the official Tavern 2.0 forums at
https://tavern.dcss.io/.


7. Tiles priorities
====================

While better replacements for current tiles may be received positively, there
are hundreds of missing or lacking tiles specifically desired by the DevTeam
that will most likely attract more attention. Check out the following link to
see such:

https://github.com/crawl/crawl/wiki/Art-Requests

(Should this link be invalid, check this document's online version:
 https://github.com/crawl/crawl/blob/master/crawl-ref/docs/develop/tiles_creation.txt)

Also, if you have any further suggestions, feel free to suggest their addition
to said link.


8. Submitting your tiles
========================

To submit new tiles, please submit a pull request to our github
(https://github.com/crawl/crawl/pulls), contact us in #crawl-dev, or contact one
of our tiles developers.

Please note that, unless you specify otherwise, tiles you submit to Crawl will
be released under the CC0 license, which is similar to placing them in the
public domain. See https://creativecommons.org/publicdomain/zero/1.0/ for more
information.

9. Reducing file size
=====================

(Committer only.)  When actually putting the tiles into version control,
please minimize their file sizes. Editors usually want to save quickly,
often producing files 3-4 times as big as they could be without any loss of
quality. There are two separate steps, and there are two different programs
which excel at them. I found that the best effects can be obtained with
running them in sequence:
  optipng -o4 -i0 -fix image.png
  advpng -z4 image.png

optipng: optimizations higher than -o4 touch only areas that will be
re-done by advpng anyway; -i0 disables interlacing which does no good here
and stops advpng from working; -fix allows to ignore junk PhotoShop adds.

advpng can be found in package "advancecomp".

Thanks a lot for your support!

The Dungeon Crawl DevTeam
