Tileset Support

Using Tilesets

In order to use tilesets, you must use a Graphical build of Cata. Tiles are not currently available in the 0.C (Cooper) windows build, so you will need to go with 0.D (Danny). They can be found here, see the download section.

Tileset Editor

The easiest way to edit tilesets is by using Chase's Tileset Editor. You can find the download and instructions here: tileset editor forum post With it, you can create new tilesets and edit existing ones easily.

Finding the names of things

The primary purpose of a tileset is to tell the game what image represents an object. For instance, to tell the game what the player should look like, you assign images to the "player_male" and "player_female" names. But where can these names be found?

Finding the name of a specific object

Let's assume you want to find the name of the plastic bottle. You know the item is called "plastic bottle" because that's how it turns up in the game. Items are defined in "data/json/items/". Try searching this directory for the string "plastic bottle". You should find this piece of JSON:

   {
       "id": "bottle_plastic",
       "type": "CONTAINER",
       "symbol": ")",
       "color": "light_cyan",
       "name": "plastic bottle",
       "category": "other",
       "description": "A resealable plastic bottle, holds 500 ml of liquid.",
       "price": 8,
       "weight": 13,
       "volume": 2,
       "bashing": -2,
       "cutting": 0,
       "to_hit": 1,
       "material": "plastic",
       "contains": 2,
       "flags": ["RIGID", "WATERTIGHT", "SEALS"]
   },

The interesting bit is the "id" field. For the plastic bottle, the "id" is "bottle_plastic", and that's also exactly what you need to use as name in the tileset editor to assign an image to the plastic bottle.

http://i.imgur.com/8MUOZyV.png

It works the same way for monsters(only you'd look in data/json/monsters.json), terrain(data/json/terrain.json) and so on, and so forth. If the item you want to give a sprite to is part of a mod, you'd look in "data/mods/ModName".

Special names

There are several special names for things that aren't defined in any JSON. They shall be enumerated here.

• cursor: The sprite for the cursor
• explosion: The sprite of an explosion
• footstep: The sprite of a noise indicator
• animation_line: The sprite for a line
• animation_hit: The sprite for a hit animation
• highlight_item: The highlight, e.g. for containers with items in them

Defining a sprite for a group of objects

NOTE: This feature is available only in 0.D (Danny) of later versions of the game.

CataclysmDDA is a fast growing game. It is unlikely you will be able to create sprites for new objects as fast as they're added to the game. A way to compensate for this is to define a sprite for a whole group of objects, which will be used for all objects in that group that have no individual sprite defined.

This is achieved using a hierarchy of names. Every object can have an optional category and subcategory. For instance, a plastic bottle has the category "item" and the subcategory "CONTAINER". A moose has the category "monster" and subcategory "MAMMAL".

http://i.imgur.com/UgGa7Dr.png

You can then "capture" objects of a specific subcategory with the following pattern: "unknown_{CATEGORY}_{SUBCATEGORY}". For instance, to capture all mammals, you'd use the name "unknown_monster_MAMMAL". To capture all containers, you'd use the name "unknown_item_CONTAINER".

One level up, to capture whole categories(with all their subcategories), you'd use "unknown_monster" or "unknown_item". If both "unknown_monster_MAMMAL" and "unknown_monster" are defined, all mammals will be drawn as "unknown_monster_MAMMAL"(the more specific variant). Likewise, if "mon_moose" is defined, then that will be preferred to "unknown_monster_MAMMAL" for drawing moose.

At the highest level, we have the "unknown" identifier, which is used to draw anything that has nothing else defined. A "complete" tileset should never have any "unknown" tiles, since at least a fallback for "unknown_monster", "unknown_item" and so on should exist.

Tileset Internals

If you want to understand how the tileset is stored on disk, this section might help.

Note: Currently outdated, doesn't contain information about rotation, multitile, etc.

Tileset Location

Tilesets are located in "gfx/{NAME_OF_TILESET}/", for example you can find Deon's tileset in "gfx/DeonTileset/". In that directory, there must be a file called "tileset.txt" which CDDA will use to locate your tileset. Here is the template for that file:

       NAME: {NAME}
       VIEW: {DISPLAY_NAME}
       JSON: {PATH_TO_JSON}
       TILESET: {PATH_TO_PNG}

These are all the contents your tileset.txt needs. To adapt this file to your needs, simply replace the values after the :

• Replace {NAME} with the name of your tileset, e.g. "FunTileset"
• Replace {DISPLAY_NAME} with the first part of the name that should be displayed when selecting tilesets. For instance, using "Fun" as name for your tileset will result in "Fun Tileset" being displayed in the options menu for your tileset.
• Replace {PATH_TO_JSON} with the path to the .json defining your tileset, e.g. "gfx/FunTileset/tileset.json"
• Replace {PATH_TO_PNG) with the path to the .png containing the actual images of your tileset, e.g. "gfx/FunTileset/tileset.png"

The tileset.txt for our Fun Tileset would thus look like this:

       NAME: FunTileset
       VIEW: Fun
       JSON: gfx/FunTileset/tileset.json
       TILESET: gfx/FunTileset/tileset.png

The tileset is contained in the gfx/ directory. All sprites are contained in a single file, currently "gfx/tinytile.png". Since many sprites are contained in the same file, sprites must be identified by their position within the file. The position is specified as an index, that increases first from left to right, then from top to bottom. For example, the top-left sprite is at index "0", then the sprite right of that is at index "1" and so on.

Tileset JSON

http://i.imgur.com/nEm57Iq.png

In the above example, the human sprite would be specified with the index "32". This index can then be used to associate the sprite with an entity in the game. This is done in gfx/tile_config.json. For example, in that file the sprite for the male player entity is defined as follows:

       {
           "id":"player_male",
           "fg":32,
           "rotates":false
       },

Here, the id property refers to the entity that we're specifying. "fg" refers to the "foreground" sprite. You can create composite sprites by specifying both "fg" and "bg", for instance the "fg" being the bush, the "bg" being grass or something else the bush might be placed on.

Another important property in gfx/tile_config.json is the width and height of each sprite. This enables you to make tilesets with smaller or larger tiles.

   "tile_info":
   [
       {
           "height": 16,
           "width": 16
       }
   ]

By modifying gfx/tinytile.png and gfx/tile_config.json, you should now be able to roll your very own tilesets. Enjoy!