All tiles in stonesense use a single system to define them, using XML tags and

attributes. the tag that defines a sprite is diifferent for each type, but the
attributes are the same.

All sprites have the following format:

<tag attribute1="value1" attribute2="value2" ... >

<subtag attribute="val"/>
...
</tag>

where 'tag' is the identifier for the type of sprite in question, attribute is one
of the many possible sprite attributes, and val is a value for that attribute.

This is a list of possible sprite attributes, and associated values.

Attribue: sheetIndex, sprite, index

Valid Values: Any positive number
Default Value: "-1"
Description: This is the single most important attribute of any sprite. It referrs
to the the location of the sprite on the tileset, starting from 0 in the upper
left, and going down a row every 20 sprites.

Attribute: file
Valid Values: any valid image file
Default Value: "objects.png"
Description: describes which file (called "sprite sheet") the sprite can be found
in. Sprite sheet can be defined on an XML-file level too, this way all sprites
listen in the XML-file use the same file so it doesn't have to be set for every
sprite (local definitions will override the global ones).

Attribue: frames
Valid Values: any combinatio of the numbers 0-5
Default Value: "012345"
Description: This is used for animating a sprite, it is a list of frames that the
sprite can show up on, with a random offset per sprite. so a value of "024" would
mean that the sprite would show up every other frame.

Attribute: random_anim_offset
Valid values: "0", "1"
Default Value: "0"
Description: some sprites are better if hte animations on different tiles are out
of synch with each other, while others need to match. Setting this to "1" will add
a random number of frames to each tile.

Attribute: border_open_OR, border_floor_OR, border_wall_OR, border_ramp_OR,

border_upstair_OR, border_downstair_OR, border_dark_OR, border_light_OR
Valid Values: any combination of the numbers 0-8
Default Value: "12345678"
Description: this is a list of adjascent tiles, at least one of which must be
empty, or floor, etc, for this sprite to be shown. numbers refer to the following
tiles:
/\
/ \
/ \
/\ 1 /\
/ \ / \
/ 8 \/ 2 \
/\ /\ /\
 / \ / \ / \
/ 7 \/ \/ 3 \
\ /\ /\ /
\ / \ / \ /
\/ 6 \/ 4 \/
\ /\ /
\ / \ /
\/ 5 \/
\ /
\ /
\/

Attribute: border_open_NOR, border_floor_NOR, border_wall_NOR, border_ramp_NOR,

border_upstair_NOR, border_downstair_NOR
Valid Values: any combination of the numbers 0-8
Default Value: "0"
Description: similar to border_open_OR, et al, but this attribute lists neighbors
that must NOT contain an open space, etc. if any of the listed neighbors are open,
the sprite will not show, regardless of other circumstances.

Attribute: variations
Valid values: and positive number
Default Value: "0"
Description: This is used for giving random variation to sprites. If this number is
more than 0, a random number between 0 and this number-1 is added to the
sheetIndex. eg, if this attribute is 5 and sheetIndex is 21, then tiles will range
from 21-25

Attribute: color
Valid Values: "none", "xml", "inorganic", "material", "layer", "vein", "building",
"material_fore", "material_back", "layer_fore", "layer_back", "vein_fore",
"vein_back", "bodypart", "profession", "blood"
Default Value: "none"
Description: Sets how this sprite is colored.
"none" means the sprite is not colored
"xml" means the sprite color is specified using the red, green, and blue
sprite attributes shown later.
"named" means that a later specified color_name, which references a COLOR
from the DF raw files will be used.
"material" means that the sprite will be colored according to the material of
the sprite that shows up in DF. adding this to creatures results in chameleons.
"layer" means that the sprite will be colored according to the main rock
layer, which lies beneath all veins and constructions.
"vein" means that the sprite will be colored according to the mineral vein,
which lies beneath constructions, but is above the layer.
"building" means that the sprite will be colored according to the building
that is built on it. it's probably a bad idea to use this one outside of building
sprites.
"material_fore", "material_back", "layer_fore", "layer_back", "vein_fore",
and "vein_back" are currently waiting for DFhack to update it's features. they may
or may not work.
"bodypart" meanst that this sprite is colored according to a creature's body
part, specified later. adding this to a landscape sprite will result in the sprite
being colored only when a creature is on it.
"profession" means that the sprite will be colored according to the
creature's profesion.
"blood" means that the sprite will be colored according to whatever blood is
splattered onto it.
Attribute: bodypart
Valid Values: any valid body part
Default Value: none
Description: this will chose which bodypart of the creature to pull the color from.
only valid if color="bodyart"

Attribute: red, green, blue, alpha

Valid Values: "0"-"255"
Default: "255"
Description: sets the color to tint the sprite by manually. only valid if
color="xml"

Attribute: color_name
Valid Values: names of a COLOR from the DF raw file "descriptor_color_standard.txt"
(eg. "DARK_INDIGO"). only valid if color="named"
Default: pure white (255, 255, 255)
Description: gets the tinting color from the DF raws' color descriptions

Attribute: halftile
Valid Values: "chop", "yes", "no", "both"
Default Value: "chop"
Description: tiles can be chopped in half to reveal what's behind them.
"chop" means that the built-in auto-chopping method is used.
"yes" means that this sprite is considered a half sprite, and will only show
up when the tile is chopped in half.
"no" means that this is a full sprite, and will be hidden when the tile is
chopped.
"both" means that the sprite will always be shown, regardless of the tile
state.

Attribute: tileborder
Valid Values: "none", "left", "right", "bottom"
Description: similar to the need* attriibutes, but specifically for tile borders,
for simplicity.

Attribute: snow_min
Valid Values: any positive integer
Default Value: "0"
Description: the sprite will only be shown is the snow is this amount or more.
typical snow values are 0-100

Attriibute: snow_max
Valid Values: any number
Default Value: "-1"
Description: this tiile will only show up if the snow amound is less than or equal
to this number. -1 means no limit.

Attribute: blood_min
Valid Values: any positive integer
Default Value: "0"
Description: similar to snow_min

Attriibute: blood_max
Valid Values: any number
Default Value: "-1"
Description: similar to snow_max

Attribute: mud_min
Valid Values: any positive integer
Default Value: "0"
Description: similar to snow_min

Attriibute: mud_max
Valid Values: any number
Default Value: "-1"
Description: similar to snow_max

Attribute: offsetx
Valid Values: any reasonable number
Default Value: 0
Description: the sprite, when drawn, is shifted to the right by this amount.

Attribute: offsety
Valid Values: any reasonable number
Default Value: 0
Description: the sprite, when drawn, is shifted down by this amount.

Attribute: outline
Valid Values: "0", "1"
Default Value: "1"
Description: if this is set to 0, then the tile will not get the anti-escher
outlines.

Attribute: blood_sprite
Valid Values: "0", "1"
Default Value: "0"
Description: if this is set to 1, then the tile will be offset according to the
surrounding blood.
Useful for adding blood pools. This over-rides 'variations' so they cannot be used
together.

Additional sprites can be layered on top using the subsprite tag, like so:

Attriibute: zoom
Valid Values: any number
Default Value: "0"
Description: Sets the scale of the sprite, in the form of 2^x. this means 0 is
normal sized, -1 is half sized, 1 is double, 2 is quadruple, etc.

<floors>
<floor sheetindex="1">
blah blah
<subsprite sheetIndex="2" color="material"/>
</floor>
</floors>

you can add as many subsprites as you need.

Remember that most of these can be applied to any and all sprites, so you can have
dwarves leann against a wall if they are standing next to one, or have a willow
tree that is leaning over the edge of a cliff, that gets snowed over in winter.

however, some of them don't fit well in some situations, like making a rock floor
colored by skin tone, or a dorf's clothing being colored according to the rock he's
standing on, but the option is there.