The media files of WorldForge use special "tags" that are part of the filename to describe various properties of the files. The tags ensure that all artists are using a coherent naming scheme for their files, making it easier for others to understand the filenames. The tags also make it possible to organize and process the media files with automated scripts and programs. Tags like the author tag also help to make the filenames unique.

This document concentrates on the tags used in pictures and textures, but tags like the author tag and orig tag can also be used for other media, such as sound and music.

What are filename tags?

A tag in a filename is a special word separated from other parts of the filename with underscores (no underscore is used at the start or end of the filename). A filename can contain one or more tags in addition to the base name of the file. Tags are combinations of letters and numbers, and they are separated by underscores "_". Spaces in the base filenames and layer names are also represented as underscores, so be careful to not include any official tags as words in the base name or layer name.

The tags do not have many restrictions on the order in which they appear in the filename, however the following rules should be followed:

So a filename has the following anatomy (square brackets[] indicate optional parts):

Base Filename_[Layer Tag with layer number]_[Layer name][Other tags]_[Animation frame tag].Extension


This is a town sketch by Hans. It has no other tags than the author tag.
A close-up of the third magical book. "_zoom_" is a tag, the "3" is just a part of the base filename.
Original of the trunk layer of the first oak. "trunk" is a layer name, "oak_1_mature" is the base filename. "_l6_" indicates that it is the sixth layer of oak_1_mature and "_orig_" indicates that it is the original (in this case a large Paint Shop Pro file, that can contain special adjustment layers and such).
The bump map for the third animation frame from a swamp water texture by J.A.

Author tags

Author tags are used to identify the author of a file. They also make the filenames unique, which is a requirement. Author tags can be your initials or a short nickname. The only requirement is that it should be unique (it should not be the same as an existing artist tag or some other tag). It should not be too long either, three letters would be best (although slightly longer are ok too). Author tags should always be placed last in the filename, except for animation frame numbers.


us Uta Szymanek
ta Tom Austin
hh Hans Häggström

(At least three letters are recommended for future author tags, to minimize the risk of collisions.)

Author tags will be stored in the team database. Be sure to use the same author tag as you specify in the team database, so that files stored in the media database can be properly credited.

Until the new team database comes up, the author tags are listed on the author tags page.

General tags

These tags apply to all kind of media.

This indicates that the picture is an original. It is in some easily editable source format, for example a layered image or 3D model, and has a high resolution.

Picture and sprite tags

The following tags are used for pictures and sprites.

A thumbnail (that is, scaled down for quick previewing) version of an image. Mostly for use on web pages.
Indicates that this is a close up, or detail picture of an item or creature. It could be 512 * 512 pixels for example, although the size is free. It could be displayed in the client when an item is examined, along with the long textual description. It could also be used in a web listing of items, as a book illustration in-game, or to represent an item in an editor. An item or creature normally has at most one representative detail picture; there is no need to create detail pictures for every animation frame or direction.
Inventory picture. This is a picture of an item or other thing that can be picked up and placed in the inventory. It should be roughly square. Currently uclient uses 50*50 pixel sized pictures in the backpack.
Shadow map for a sprite. It is used to create a shadow for a sprite in 2D isometrical clients. If no shadow map is available for a sprite, the client generates a temporary one by rotating or skewing the sprite. The shadow map should be an 8bpp greyscale png, with black = shadow and white = no shadow. The shadow should be sharp (the client will do eventual blurring), and the light source should be up to the right, at a 60 degrees angle.
xs, sm, m, l, xl
Indicates size. For example, fireball_xs_hh.png would be a very small fireball, whereas fireball_m_hh.png would be a normal sized fireball. The pictures aren't (necessarily) the same picture at different sizes, they can be different items too (like a small round table and a big dining room table). The tag standing for 'small' is names sm instead of s to avoid conflict with the 'south' tag.
one, two, few, some, many, lots
Used to indicate the size of piles. [It is a bit hard to place few/some and many/lots in relative order. Is this order generally acceptable?]
n, ne, e, se, s, sw, w, nw
Indicates the direction a sprite or animation frame is facing in. n is straight up on the screen, ne is up and right, etc.
_01, _02, _03, ...
Number of an animation frame (if located last in filename). This is only interpreted as a frame&enspnumber tag if it occurs last in the filename, so it is ok to use numbers in the base filename and layer name for other purposes. Animation frames start from one and continue as long as there are immediately following numbers. Leading zeroes should be used to make all the frame numbers for an animation equally long. This makes it easier to browse them in order in file listings, and simplifies scripting. So if an animation has more than nine frames but less than a hundred, the frame tags would be _01, _02, _03, etc. Extra leading zeroes can be used if desired.

Texture tags

These tags should be used for special texture maps, such as bump&enspmaps. A texture with none of the _alpha_, _bump, color_ or _reflect_ tags is assumed to be a pre-shaded texture (light coming from above and slightly from right) to be used with applications that do not support bump and reflectivity maps.

This is an alpha, or translucency bitmap for a picture or texture. Note that png includes transparency information, so it is not necessary to have a separate alpha map if png is used. The alpha map is normally 8 bpp gray&enspscale, with black being transparent and white solid [Or was it the other way?].
A Bump map for a picture or texture. It describes the height of the various parts of the bitmap. Normally 8 bpp gray&enspscale, with black = low and white = high areas. Bump map for fragment of a cobblestone pattern
This is a color picture intended to be used with a bump map. The only difference from a normal, untagged texture with the same name, is that this picture should not have any shading. No assumptions should be made about from what direction the light will come, the bump map is used for the shading. Color map for fragment of a cobblestone pattern
A Reflection map for a picture or texture. It describes the reflection of various parts of a bitmap. Normally 8 bpp gray&enspscale, with black = no reflection and white = 100% shiny. [Is this correct?]
025x025, 025x05_, ..., 3x2, 3x3
Indicates the approximate size in meters the texture is intended to be. Mainly used for material textures for building blocks. A leading zero indicates a decimal point, so 025x025 means that the texture depicts an area of about 0.25 * 0.25 meters. Sizes used are 025, 05, 1, 2, 3. Any combinations are acceptable, but the most used seem to be 2x2, 025x2 and 025x025 (a large square texture, a thin edge of the material, and a small endpoint of the material). [This tag might still be subject to change as building block graphics are tested in practice.]

Layer tags

l00, l01, l02, l03, ...
Some sprites can consist of many different layers. For example, a tree could have a layer with the trunk and branches, a few layers with leaves, and a layer with a snow cover. Not all layers have to be visible at the same time, in the above example the snow layer would be visible only in winter, and the leaf layers only in summer. The layers are stored as separate png images, not as layers in a layered file format (although such a format could be used to create the layers, and the original file could be stored in a layered format).

The layers are marked with the layer tag, an l (low case L) immediately followed by the layer number, with a leading zero if there is more than nine layers (so that the layers show up in the correct order in file listings and when processing with scripts). A layer with a larger number is in front of a layer with a smaller number. The numbering starts from zero.

Layers can have names in addition to the number, in this case the name should follow immediately after the layer tag. For example, an oak could consist of the following layers:

  1. oak_1_mature_l00_leaves_1_back_hh.png
  2. oak_1_mature_l01_leaves_2_back_hh.png
  3. oak_1_mature_l02_leaves_3_back_hh.png
  4. oak_1_mature_l03_trunk_lower_hh.png
  5. oak_1_mature_l04_ice_lower_hh.png
  6. oak_1_mature_l05_snow_lower_hh.png
  7. oak_1_mature_l06_trunk_upper_hh.png
  8. oak_1_mature_l07_ice_upper_hh.png
  9. oak_1_mature_l08_snow_upper_hh.png
  10. oak_1_mature_l09_acorns_hh.png
  11. oak_1_mature_l10_leaves_1_front_hh.png
  12. oak_1_mature_l11_leaves_2_front_hh.png
  13. oak_1_mature_l12_leaves_3_front_hh.png
Trunk layer of an oak
Snow layer of an oak
Leaf layers of an oak
(Note that the upper and lower trunk layers are merged here for simplicity, and not all mentioned layers are displayed)

Sometimes characters or items may pass behind some of the layers but in front of others. For example, the tents that Uta has made have a front and back section, and a character that walks into a tent passes behind the front layer but in front of the back layer. Also, the oak described above has the trunk (and the ice and snow layers for it) split up in two parts, one upper and one lower. This is because the upper part has some low-hanging branches, and it is possible for a character to pass in front of the trunk, but under the over&ensphanging branches and leafs.

[A way to implement this could be to specify a depth-offset for each layer in some separate file (I seem to remember that we currently use some special file to specify the media used for a specific item. These offsets could maybe be stored there, along with information such as anchor point of the picture. Eventually this would probably be stored in the media database somehow?). The offset could be given in meters, and would specify how much each layer is displaced from the anchor point of the picture along a line that goes straight towards the camera.]

In the future different filtering effects could be applied to individual layers (like turning the hue of a leaf layer of a tree towards yellow or red in autumn).

This tag indicates that a picture that consist of many layers has been merged together to one picture. This is useful for clients that don't yet support layers, or for showing the item on webpages or such. When merging, the most typical combination of layers can be used. For the oak above, the snow and ice layers are left out, creating a normal oak with leaves and acorns, with a file name of oak_1_mature_merged_hh.png. thumbnail of merged oak

Environment and season tags

These tags are used to represent various environment effects. Some of them are only meaningful in layer names, and could be used as normal words in the base filename.

This tag can be used in a layer name to indicate that the layer should be used for items that are covered with a (thin) layer of ice. The ice could look like translucent white frost, for example. ice covered boulder
This tag can be used in a layer name to indicate that the layer should be used for snow covered items. The snow is relatively thick and mainly clings on vertical surfaces. Like idyllic Christmas postcards. The snow layer should always be on top of the ice layer. snow covered boulder

In a normal cold winter with snow, both the ice and snow layers could be drawn. On a chilly late autumn day, the ice layer could be drawn. In spring, when things begin to thaw, the ice layer would probably disappear first. The ice (and snow) layers can also be used in other situations, like freezing spells.

Not all items need ice and snow layers, they are mostly relevant for items that are likely to be outdoor longer times, like trees, stones, ground tiles, statues and so on. Small items, like swords or bowls, usually don't need special ice or snow layers.

If it occurs in the layer name, it indicates that the layer is a layer of moss and other small forest vegetation. Can be useful on stones and boulders, and on statues and other artificial constructs to provide an optional overgrown look. moss covered boulder

Growth tags

These tags can be used for growing vegetation or other things that change appearance when they grow. They are not official, just recommendations.

A growing plant, tree, etc. This tag can be followed by a number, indicating the growing stage. For example, birch_growing_1_hh.png would be a very young birch sapling, while birch_growing_4_hh.png might be almost mature. A growing frogleaf plant
A fully grown plant, tree, etc. Only useful if there also exists growth or death pictures for the item. Normally the mature tag has no following numbers, if there is many mature stages of an item they should preferably be classed either as growth or death stages. A mature frogleaf plant
A withering plant, tree or other thing. This tag can also be followed by a number, indicating the death stage. So tulip_dying_1_hh.png might be a slightly past prime, while tulip_dying_3_hh.png could be a few decaying leaves lying on the ground. A dying frogleaf plant

Other tags

These tags are also used sometimes.

red, blue, yellow, green, ..., lred, lblue, ..., dred, dblue, ...
Used to indicate the color of something. Prefix "l" (lower case L) for light and "d" for dark. Note that runtime filtering that can change the hue/saturation/light/transparency is planned for the future, so it is not necessary to create pictures of every item separately for all possible colors.
ff, sf
First floor and second floor respectively. Can optionally be used for wall sprites to indicate the floor they are designed to be used on.

Hans Häggström hans.haggstrom at