Sprites Resources

Resource options

The sprite resource options is a plethora of possibilites to tweak a sprites looks and behaviours, but all of them have default values. In most cases you will only need to use the basic options.

TODO: The frame cutter approach. Explain the 4 different cutters.

Each sprite CAN have the following properties:

my_sprite =
(
	type = sprite,

	imageX = filename,
	imageX_method = [single, grid, palette, alpha],

	// Options only if imageX_method is 'grid':
	imageX_pos = (x, y),
	imageX_size = (width, height),
	imageX_array = (width, height),
	imageX_array_skipframes = integer,
	imageX_spacing = (x, y),
	imageX_tcol = (col1, col2, col3 ... colX),

	// Options only if imageX_method is 'palette':
	imageX_pos = (x, y),

	// Options only if imageX_method is 'alpha':
	imageX_pos = (x, y),
	imageX_trans_limit = float,

	play_options = ([pingpong, nopingpong], [loop, noloop], [backward, forward]),
	play_speed = integer,
	show_on_finish = [blank, last_frame, first_frame],

	base_angle = float,

	rotation_hotspot = (
		[top_left, top_center, top_right, center_left, center, center_right, bottom_left, bottom_center, bottom_right],
		x-offset, y-offset),
	translation_hotspot = (
		[top_left, top_center, top_right, center_left, center, center_right, bottom_left, bottom_center, bottom_right],
		x-offset, y-offset),

	scale = (float, float),

	color = (float, float, float, float),
	alpha = float,

	frameX_speed = integer,
	frameX_offset = (x-offset, y-offset),
);

All properties are optional, except the imageX values and the type = sprite. Omitted properties will get a default value.

imageX: Filename of image to load.
This will add all frames it can find in the image, based on the imageX_method. Note that X starts on 1 (image1, image2, image3 etc). You can have as many imageX as you want. If image1 contains 10 frames, image2 contains 1 frame, and image3 contains 3 frames, the total animation size will be 14 frames.

Valid values: string - Any valid filename
Default value: NONE - MUST BE PRESENT AT LEAST ONCE
imageX_method: Method to cut image into frames.
This specifies how the image will be split into multiple frames. If you select single (or omit this option completely), the whole image is used as a single frame. See the Sprites Overview for more information on this topic.

Each method in the imageX_method has a set of options you can use to specify how each method cuts the image into into frames. See the options below.

Valid values: single, grid, palette, alpha - one of the 4 methods
Default value: single
(Grid method) imageX_pos: Position in image to start grid-cutting.
Valid values: (integer, integer) - x-position, y-position
Default value: (0, 0)
(Grid method) imageX_size: Size of each grid-tile.
Valid values: (integer, integer) - width, height
Default value: (1, 1)
(Grid method) imageX_array: Grid-size.
Valid values: (integer, integer) - width, height
Default value: None, MUST BE PRESENT.
(Grid method) imageX_array_skipframes: How many frames to skip at end of last gridline.
Valid values: integer - frames to skip
Default value: 0
(Grid method) imageX_spacing: Space between each grid-tile.
Valid values: (integer, integer) - x-spacing, y-spacing
Default value: (0, 0)
(Grid method) imageX_tcol: Transparency colours.
Valid values: (integer, integer, integer ... integer) - col1, col2, col3 ... colX
Default value: None
(Palette method) imageX_pos: Position in image to start palette-cutting.
Valid values:
Default value: (0, 0)
(Alpha method) imageX_pos: Position in image to start alpha-cutting.
Valid values:
Default value: (0, 0)
(Alpha method) imageX_trans_limit: Transparency limit.
Valid values:
Default value: 0.05
play_options: Sets the playback options for the animation.
pingpong/nopingpong: Set it to pingpong if you want the animation to play back to start once it has reached the end of the animation.
loop/noloop: Set it to loop if you want the animation to loop after it has reached end of of the animation.
forward/backward: Set it to backwards if you want the animation to play backwards - starts at last frame, and plays forward to first frame.

Valid values: nopingpong, pingpong, noloop, loop, backward, forward - any of the options
Default value: (nopingpong, loop, forward)
play_speed: Default frame delay.
This sets the delay between each frame. You can override separate frames using frameX_speed (see below). Value is in milliseconds.

Valid values: integer
Default value: 50
show_on_finish: What to show when animation is finished.
Specify what is shown when the animation is finished. Blank shows nothing, last_frame shows last frame in animation, first_frame shows first frame in animation. If you use looping, this option has no effect.

Valid values: blank, last_frame, first_frame - one of the 3 options
Default value: blank
base_angle: The angle of the sprite as drawn in the frame.
Example: If your sprite is drawn top-down pointing east, you set base_angle to 90. When you draw your sprite with an angle on 0 degrees, it will then be drawn pointing north. If you don't use rotation or a top-down perspective, just leave out this option.

Valid values: float
Default value: 0.0
rotation_hotspot: Hotspot/alignment for rotation operations.
TODO: Write more

Valid values: TODO
Default value: (center, 0, 0)
translation_hotspot: Hotspot/alignment for translation operations.
TODO: Write more

Valid values: TODO
Default value: (top_left, 0, 0)
scale: Scale.
Sets the x and y scale of the sprite. A value of 1.0 is the normal size, 2.0 is double the size, etc.

Valid values: (float, float)
Default value: (1.0, 1.0)
color: Color.
Sets the red, green and blue color components of the sprite.

Valid values: (float, float, float, float) - between 0.0 and 1.0
Default value: (1.0, 1.0, 1.0, 1.0)
alpha: Alpha (transparency).
Sets the transparency for the sprite.

Valid values: float - between 0.0 and 1.0
Default value: 1.0
frameX_speed: Override default speed for this specific frame.
Value is in milliseconds.

Valid values: integer
Default value: play_speed
frameX_offset: Offset to display this frame.
This let you set a position-offset on a frame, finetuning its position relative to the other frames.

Valid values: (integer, integer) - x-position, y-position
Default value: (0, 0)

Examples

Some examples:

my_simple_sprite =
(
	type = sprite,

	image1 = image_single1.tga,
	image2 = image_single2.tga,
	image3 = image_single3.tga,	
};

my_advanced_sprite =
(
	type = sprite,

	image1 = image1.tga,

	image2 = gridframes.tga,	
	image2_method = grid,
	image2_array = (10, 2),
	image2_size = (32, 32),

	image3 = alphaframes.tga,
	image3_method = alpha

	image4 = image2.tga,

	image5 = image3.tga,
	image5_method = grid,
	image5_size = (32, 32),

	alpha = 0.5,
	
	base_angle = 90,

	frame20_offset = (1, 1),
	frame20_speed = 100
};

As you can see, you can interchange any cutmethod in a sprite, it just adds the frames sequentially. This sprite consists of 1+20+?+1+1 frames (the ? depends on how many frames there were in the alphaframes.tga).

Since most options have a default value, you can safely remove those unless you want another value. I.e. in my_advanced_sprite/image1, we have omitted the image1_method = single, in image2 we omitted image2_pos = (0,0), in image5 we omitted image5_array = (1,1). Using the gridcutter to cut only one frame makes it possible to use a subsection of a surface.

Questions or comments, write to the ClanLib mailing list.