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:
...
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.
blah blah
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.