Vision Riders Integrated Sprite System

The Vision Riders Integrated Sprite System specification is an overview of a 2d graphics and animation system for use in games and other computer applications. It is a general-purpose data system for animating and compositing graphics that can be implemented utilizing all, or only a portion of, the features described and explained in this document.

In the Integrated Sprite System, a sprite refers to complex 2d software pseudo-sprites made up of multiple elements spread across animated frames, and can include additional data such as collision boxes and simple scripting.

Table of Contents

1. Introduction
1. Abstract
2. Name
3. Overview
4. Implementation
5. Licenses
6. Versioning
2. Sprite Objects
1. Internal Management
2. Metadata
3. Frame Rate
4. Position and Orientation
3. Source Sheets
1. Supported Formats
2. Filenames and Locations
3. Slices
4. Elements
1. Graphic Elements
2. Attachment Points
3. Collision Detection Objects
5. Animation
1. Animation Groups
1. Naming
2. Nesting
3. Group Assignment
2. Animation Sequences
1. Naming
2. Management
3. Frame Rate
4. Default Animation Sequence
5. Setting Animation
6. Looping
7. Follow-Up Sequence
3. Frames
1. Label
2. Empty Frames
3. Hold Time
4. Elements
5. Triggers
6. Notes
7. Frame Interpolation
6. Definitions
7. File Structure
   1. Data Types
   2. File Header
   3. Chunk Headers
   4. File Metadata Information
   5. Additional File Metadata Information
   6. Source Textures
   7. Slices
   8. Element Names
   9. Animation Hierarchy
   10. Frame Data

Introduction

Sprites have a long history in computing. They originated as a hardware-powered solution to achieve movable raster graphics in a time when the simple act of copying pixels to the screen was a time-consuming process. While virtually no platform utilizes true sprites anymore, the term has come to refer to any individual 2d graphic that is part of a larger scene.

In the Integrated Sprite System, a "sprite" is the term used to refer to the overall object that encapsulates and holds the data covered by this document. The net result is an animated graphic displayed at a given location on screen in an application.

Abstract

This document specifies in detail the Vision Riders Integrated Sprite System. It defines the constitution and configuration of the data system, the format of its file structure, and how it is intended to be used.

Name

The full name of the data system defined in this specification is the Vision Riders Integrated Sprite System. An Integrated Sprite is an animated 2d graphic object that uses this system for its data storage, handling, and display.

Overview

In the Integrated Sprite System, a sprite is a two dimensional object that contains animation data and can be made up of many individual images, but is treated as a single entity. Instead of being just a series of static images, a sprite can have many individual elements working together to form a whole image on-screen. Elements include individual graphics taken from multiple source sheet images, as well as collision detection objects and attachment points for other sprites.

A sprite is made up of individual frames linearly arranged in animation sequences. These sequences can be further subdivided into nested animation groups, allowing an application to determine what sequence is played depending on the active group.

Furthermore, each frame can also contain a collection of triggers, which are scripting commands that can be passed to an application. These triggers can alert the application to such things as when to play sound effects in sync with footsteps, or when to display damage output during an attack.

Implementation

This document defines multiple standards designed to be useful across platforms and applications, for multiple kinds of uses.

How these standards are achieved and implemented, and to what degree, is up to the application, and the programmer.

Licenses

Vision Riders Entertainment, LLC owns and maintains the Integrated Sprite System specification. It is has made available for use by the public without guarantee or limitation. It is provided as-is, and Vision Riders Entertainment assumes no responsibility or liability for any errors or inaccuracies.

Derivative standards based on the Vision Riders Integrated Sprite System must not use the Vision Riders name without expressed, written consent.

Versioning

The Integrated Sprite System has a versioning system to that denotes a major version number and a minor version number. In written form, the numbers are given in the following form:

major.minor

A period is inserted between the major and minor version numbers. An Integrated Sprite System specification is both backwards and forwards compatible with all sibling specifications of the same major version number, although features added or slightly altered in later minor versions will obviously not be available or observed by application built on an older version. Specifications with later major version numbers may or may not be compatible with older or newer specifications.

A specification may also have a revision number, such as 2.3, revision 1. Revisions include clarifications and corrections to the specification, but no changes or additions. An application should always follow the latest revision of its chosen version.

Sprite Objects

Sprites have a long history in computing. They originated as a hardware-powered solution to achieve movable raster graphics in a time when the simple act of copying pixels to the screen was a time-consuming process. While virtually no platform utilizes true sprites anymore, the term has come to refer to any individual 2d graphic that is part of a larger scene.

In the Integrated Sprite System, a "sprite" is the term used to refer to the overall object that encapsulates and holds the data covered by this document. The net result is an animated graphic displayed at a given location on screen in an application.

Internal Management

Within an application, a sprite is expected to be responsible for internally selecting and positioning is elements and updating its animation data.

Metadata

An Integrated Sprite file can contain optional metadata, doing such things as giving the sprite a meaningful name or listing the authors.

Frame Rate

While it is ultimately up to an application to determine the playback rate of a sprite, an Integrated Sprite data file contains frame rate information, in the form of an integer giving the number of frames per second for playback. Individual animation sequences may also contain frame rate information that overrides the master frame rate of the sprite.

A value of zero is valid for the frame rate, in which case it should not perform playback on its own as usual.

Position and Orientation

A sprite's elements are positioned in relation to itself, specifically in relation to its origin point, which is determined by the application. This origin point is considered to be coordinate (0, 0). The position of all a sprite's elements are given in relation to this origin point. Increasing the horizontal value refers to a point further to the right, while increasing the vertical value refers to a point further down.

A sprite's overall rotation, scale, and mirroring should be based around its origin point.

Source Sheets

A source sheet is an image where a sprite's raw graphic data is stored. It can also be refered to as a "sprite sheet", "texture sheet", or simply a "texture". These source sheets are not stored in an Integrated Sprite's data file.

A sprite can have multiple source sheets, up to 255, but most sprites should only need one. Multiple source sheets should only used when all of a sprite's graphics cannot fit in a single image small enough to be compatible with most graphics cards. (Many older graphics cards do not accept textures larger than 2048×2048 pixels.)

In general, the fewer source sheets the better. More textures usually means more draw calls to the GPU, which in turn leads to degraded performance at runtime.

Supported Formats

As source sheets are external to the data file, the image file formats supported are left up to the application. The use of PNG files is recommended if the application is not using its own format, as they are losslessly compressed and can include transparency.

Filenames and Locations

In an Integrated Sprite's data file, each source sheet's path and filename is listed. These paths are in relative relation to the data file's location.

The names of source sheet image files do not include the file extension. It is up to the application to provide them. This allows for production pipelines that convert image formats at compile time to use the same Integrated Sprite file without having to change it.

Slices

A slice is a defined rectangular area within a source sheet. Each sprite will usually have many such slices. These slices can be instanced as graphic elements within the frames of a sprite.

Each slices is defined by three values: the index of source sheet it uses, the upper-left coordinate of the slice, and the lower-right coordinate of the slice. These integer-based coordinates are measured in pixels in relation to the upper-left corner of the source sheet. Both coordinates are inclusive, that is, the pixel rows and columns they refer to are visible when instanced by graphic elements.

A slice whose lower-right coordinate is higher or further to the left than its upper-left coordinate is considered invalid.

When packing a source sheet, slices should be placed at least one pixel apart from each other in order to avoid them blurring into each other when the GPU filters the texture during drawing.

Elements

Elements are the building blocks of a sprite's appearance on the screen, as well as their behaviour in the application. There are three kinds of elements: graphic elements that use image data from the source sheets, attachment points that can be used to connect additional graphics and even other sprites, and collision detection objects.

All elements have a scope of a single frame. Thus they exist only once and in one place, although they may share properties with elements on other frames, to the point where they are effectively treated as the same entity.

Elements can also be given a name to identify them. This is most useful for attachment points and collision detection objects, but they may also be assigned to graphic elements as well.

Graphic Elements

A graphic element is an instance of a slice located in a given frame. Graphic elements can be positioned, rotated, scaled, mirrored (flipped), and made transparent.

Attachment Points

Attachment points are simple nodes that allow an application to combine multiple sprites using a simple parent-child relationship. They can be used for things such as keeping an equipped weapon in a character's hand.

Other sprites and graphics should be attached to an attachment point based on a given string matching the attachment point's name. If no attachment point with that name is present in a given frame, the attachment sprite should not be displayed. Otherwise, the attached sprite should be displayed with their origin point placed over the node.

Ideally, if there is more than one attachment point with the same name in a single frame, an attached sprite should be instanced on every attachment point.

Like graphic elements, attachment points can be positioned, rotated, scaled, mirrored (flipped), and made transparent. Any attached sprite should inherit both the parent sprite's scale and orientation, as well as the scale and orientation of the attachment point. If any animation commands need to be passed to the attached sprite, it should be done using trigger scripting in the frame.

Any elements that should appear over the attachment point should likewise appear over any object attached to the given attachment point.

Collision Detection Objects

Collision detection objects allow sprites to change their collision detection area and behaviour depending on the frame. This provides a simple solution for complex collision detection that is more flexible than a static bounding box. Collision detection objects may overlap, or even be located entirely within each other.

There are two types of collision detection objects: circles and rectangles. Circles have a position and a radius, while rectangles are defined by their position, size, and a rotation value.

Collision detection objects' element names allow for multiple kinds of collision detection data to be stored in the sprite. For example, you can have different collision detection objects for damage output boxes and hit boxes. The name can be used to tell the two apart.

Unlike graphic elements and attachment points, a collision detection object's position in the display list is irrelevant, as they are not meant to be displayed. Regardless, it is recommended that they appear last in the collision display list.

How collision detection is handled using these objects is left up to the application and its needs.

Animation

The Integrated Sprite System allows for complex animation handling by using a tree structure of animation sequences nested inside animation groups.

Animation Groups

Each and every animation sequence belongs to an animation group. Groups provide an easy way for a sprite to change its apperance or behavior by simply changing the active group.

Groups contain animation sequences, and can contain other animation groups.

Naming

Each animation group has a user defined name. The name should be unique within the parent group.

Nesting

Animation groups are nested within each other in a tree.

There is always one, and only one, parentless group to act as the root of the tree. This root group is always name "Root". The root group itself is not defined in the data file (although its contents are), as it is assumed.

Group Assignment

A sprite has an active group used to determine which animation group to pull its sequences from upon request. Initially, the root animation group should be the active group, until set otherwise.

It is up to the application to determine whether the current animation should continue to play or not when the active group is changed.

Animation Sequences

An animation sequence is a collection of frames that are played in linear order. After the animation has completed through the final frame in the sequence, it will either loop back to the beginning frame, or to a specific loop point frame in the middle of the sequence, or it can jump to a new sequence altogether.

Naming

Each sequence has a user-assigned name in the form of a string. The sprite's current animation is set based on this name. The name does not have to be unique, but there should never be two or more animation sequences with the same name in the same animation group.

Management

Within an application's code, sprites should have their animation updated automatically without the need of additional input, so long as they are active.

Frame Rate

Each sequence has an 8-bit frame rate value that can be used to override the master frame rate of the sprite. If the value is FF (255 in decimal), the sequence uses the master frame rate. Otherwise, the value is an unsigned integer giving the number of frames per second to play.

A value of zero is valid, and indicates that playback should be handled by the application. For example, a simple climbing animation that the application can play backwards or forwards depending on whether the character is climbing up or down, and that pauses whenever the character stops moving.

Default Animation Sequence

A sprite may have a default animation sequence defined in the data file. The default sequence is to be set any time a given sequence cannot be found, and when the sprite is initially loaded and has not yet had another animation sequence set. The default sequence should be located in the root animation group, although this is not specifically required.

In the case that no animation sequence is specified as the default, then the sprite should not display if a given sequence cannot be found.

Setting Animation

While the way a specific animation sequence is set is ultimately up to the application, this section details the intention of the specification.

Switching animation should be a one-step process. There should be a function in the application used to set a sprite's animation that takes a string parameter. The function should look in the active group to see if there is an animation sequence with the given name. If there is, it should set that sequence as the active sequence and begin playback of it at the first frame. If not, the function should work its way up the tree, checking each animation group for a sequence of the given name. If none can be found, even after reaching the root animation group, the default animation sequence should be activated.

This process should be case insensitive for the 52 ASCII latin characters.

Whenever a new animation is set, it should begin playback at the first frame of the sequence. However, if the animation sequence found by the function described above happens to be the exact same sequence already playing, it should ignore the request and allow the sequence to continue playing from its current location as if nothing happened. This should be determined by the sequence's unique index, not its name. A separate function should be used if the application wants to play the same animation sequence already playing over from the beginning.

Looping Animation

Each animation sequence has a loop point. Once the final frame of the sequence is complete, the animation should loop back to the beginning and continue playing over again. The loop point may be the first frame, or any other frame within the sequence.

To force the sequence to stop instead of replaying, the loop point may be set to a point equal to or exceeding the final frame in the sequence. In this case, the should halt all playback until ordered otherwise by the application.

Follow-Up Sequence

There are cases where more complex effects are desired, or where animation should follow-through to other actions automatically. To accomplish this, each sequence has a string with the name of the animation to follow up with.

Normally this string will be empty, in which case normal looping or stoping playback is desired.

If the string has content, then as soon as the final frame of the sequence is complete, the sprite should call the animation function described in the section Setting Animation, passing the string as the parameter. This allows the follow-up animation sequence to be in a parent animation group.

Frames

In any medium, animation is split up into individual frames that play at a specific frame rate. Integrated Sprites are no different. In the Integrated Sprite System each frame serves as a collection of elements. These elements include graphics, collision data, and attachment points. In addition to elements, a frame can also have other properties such as scripting triggers.

Only one frame is ever displayed at a time in a sprite. By playing through frames in an animation sequence, the illusion of motion is created.

Label

Each frame may be given a meaningful name in the form of a label, but this is not required. The name is a helpful reference, but is not otherwise used by the standard.

Empty Frames

A frame can be completely empty and contain no element data.

Hold Time

A single frame can be extended to last over multiple frames worth of playback. This is referred to as hold time, named after the technique of "holding" in traditional 2d animation.

Each frame has a 16-bit unsigned integer value giving its duration. Normally this value is 1. A value of 2 means it should last for two frames worth of playback, a value of 3 means it should last for three frames worth of playback, and so on.

Elements

Each frame contains a collection of elements, listed in a specific order. Elements later in the list are to be displayed above those that came before. There are three kinds of elements: graphic elements, attachment points, and collision detection objects.

Triggers

Frames may contain a string of triggers. Triggers are scripting commands to be passed to the application as soon as the frame is activated. Their function and use is up to the application.

Notes

Additionally, frames may contain a string of comments. These comments are most useful during production, and can be stripped when exporting the Integrated Sprite file.

Interpolation

This version of the Vision Riders Integrated Sprite standard does not contain any complex specifications for interpolation of element positions between frames. However, you may choose to linearly interpolate the positions and orientations of an element, based an element on the following frame with the same name, so long as these two elements are the only ones with that name in both frames.

Further specifications regarding interpolation may be added in a future version of this standard.

File Structure

This section will describe the actual format of the Integrated Sprite file and how data is stored and arranged. The data is structured into chunks. Every chunk begins with a four byte ASCII identifier, except for the header, which has an eight byte ASCII value identifying the file as an Integrated Sprite.

Integrated sprite files should use ".sprite" or ".isprite" as their file extension.

Data Types

In order to properly read and understand an Integrated Sprite file, you need to know how the format stores its data. The file structure itself is built around standard 8-bit bytes, however most data requires more than a single byte to properly hold.

When multiple bytes are used, the data is always encoding in little-endian, with the exception of strings. Bytes are encoded with the standard most significant bit first.

A great deal of the data is encoding in 8-bit, 16-bit, or 32-bit signed or unsigned integers, but the following data types will also be encountered.

Type	Bytes	Description
Boolean	1	A value of 0 is false. A value of 1 is true. Any other value is invalid. Booleans are packed with multiple, similar booleans in a single byte when possible. Within this documentation, the bits within a byte of booleans are numbered using LSB 0. This means that the least significant ("right-most") bit is zero.
Coordinate	6	Coordinates are given in (x, y) pairs, each coordinate value is a total of 6 bytes, with a 3 byte fixed-point decimal value for each axis. The horizontal x axis always comes first. The coordinate system is built around a central origin point for the integrated sprite, which is coordinate (0,0). Increasing the axis values refers to points further to the right and down.
Date and Time	8	A value specifying a point in time. Only used in the optional file information data chunk. This value is always in UTC. Byte Purpose 1 The day, from 1 to 31. 2 The month, from 1 to 12. 3 A 16-bit unsigned integer in little endian format. This value is the year, given as the number of years since 1 BCE. (There is no year 0, so an integral value of 1,992 is 1992 CE.) 4 5 The hour, from 0 to 23. 6 The minute, from 0 to 59. 7 The second, from 0 to 59. 8 The centisecond, from 0 to 99. It is acceptable for this specific value to always be set to zero. This format was chosen instead of a simple nanosecond or millisecond counter because it is easier to parse across systems and programming languages. In this pre-seperated format, it's easy to just pull out just what you need and ignore the other bytes.
Fixed-Point Number	3	Instead of using a 32-bit single-precision floating point format, values that need to be stored with sub-pixel precision use a 24-bit fixed point format. The first two bytes comprise a signed 16-bit integer in little-endian format. The third byte is the binary-coded decimal as an unsigned 8-bit integer. Valid values of the decimal integer range from 0 to 255, giving an adequete range of sub-pixel locations for the vast majority of uses.
Texture Coordinate	4	Coordinates that refer to source textures do not have need of sub-pixel locations, so they do not include the sub-pixel binary-coded decimal value. Furthermore, because they are always positive values, both coordinates are unsigned. Texture cordinates are given in (x, y) pairs of unsigned 16-bit integers, each in little endian format. The horizontal x axis always comes first. The coordinate system is built around the upper-left coordinate of a texture. Increasing the axis values refers to points further to the right and down. Value (0, 0) refers to the upper-rightmost pixel in the texture.
Texture ID	1	An unsigned 8-bit value identifying a source texture. It is zero-based, so the first texture will be texture 0, the second will be texture 1, and so on. The Integrated Sprite format thus supports up to 255 textures for use by a single sprite (and using this many is not recommended).
String	2+	Strings in Integrated Sprite files are never null-terminated. Instead, they begin with a 16-bit unsigned integer in little-endian giving the length of the string in bytes. The string content immediantly follows. The string content is always encoded in ASCII-compatible UTF-8. A 65,535 character string is the longest possible (assuming only ASCII characters are used in the string). A string length of zero is perfectly valid, in which case no characters follow the 16-bit length value. When attempting to read a string, if the given length is longer than the rest of the chunk's given length, it is considered invalid. You may attempt to read up to the end of the chunk, or you may ignore it.

File Header

The file header contains information about the file, its format, and its contents. It has a fixed size of 24 bytes and is always the first block in the file.

Offset	Purpose	Bytes	Details
0	Magic Number Identifier	8	The string ISPRITE, in full caps, followed by a single space, encoding in standard ASCII characters. Identifies the file as an Integrated Sprite. This translates to 49 53 50 52 49 54 45 20 in hexadecimal. If this value is not present, do not continue trying to read the file.
8	File Size	4	A 32-bit unsigned integer giving the total file size, in bytes, not including this field or the magic number identifier.
12	Major Version Number	1	8-bit unsigned integer giving the major version number of the standard in use by the file.
13	Minor Version Number	1	8-bit unsigned integer giving the minor version number of the standard in use by the file.
14	Flags	1	This byte contains boolean flags giving information about the file's contents and makeup. BIT Purpose 0 When set to true, indicates that the file breaks or extends the standard in some way. To be used in files that add features not included in the standard. (Files that encode extra information in an extended metadata chunk should not set this bit just for that, so long as they follow the name/value string pair encoding to do it.) 1 "Work file" flag. Indicates that this is a work file, and not neccissarily a final output sprite. There's no real difference in a work file, so this is primarily for internal use by production applications to indicate that this file has not had its source sheet textures packed. All other bits must be set to zero.
15	Non-Standard Identifier	3	Three bytes set aside for use by non-standard files. Should be used as a three-letter ASCII identifier to signal the reader as to what sort of extension is being used. Files that follow the standard should fill these three bytes with zero.
18	Frame Rate	1	An 8-bit unsigned integer giving the master frame rate of animation playback for this sprite. The frame rate is given in frames per second.
19	Reserved	7	Seven bytes set aside as reserved characters for possible use in future revisions of the standard. These bytes should always be set to zero. Non-standard files should never use this reserved space either. If they need additional data, they should create a new chunk for it.

Chunk Headers

After the file headers come individual chunks of data. Each chunk has its own header. As chunks do not always have a set order, these identifiers are important for reading and ordering the data.

Offset	Purpose	Bytes	Details
0	Chunk Identifier	4	A four byte ASCII string, identifying what kind of data the chunk holds.
4	Chunk Size	4	A 32-bit unsigned integer giving the total size of the chunk (after this field), in bytes.

If the reader encounters an unrecognized chunk, it should be bypassed and ignored.

File Metadata Information

The file information chunk contains information about the file itself, specifically about its origin.

This chunk is optional, and may be safely omited or ignored.

If present, this should be the first chunk in the file, after the file header. This makes grabbing the tags a more trivial affair. (After checking that the file has the "ISPRITE " identifier and the file information chunk is present, all you have to do is jump to byte 56, read the 16-bit string length value, then read the string.)

Offset	Purpose	Bytes	Details
0	Chunk Identifier	4	Chunk ID "META". 4D 45 54 41
4	Chunk Size	4	A 32-bit unsigned integer giving the total size of the chunk (after this field), in bytes.
8	Creation Date	8	The date and time that the Integrated Sprite was first created.
16	Save Date	8	The date and time that the Integrated Sprite file was most recently saved.
24	Work Time	8	The total number of milliseconds that this file has been worked on, in a 64-bit unsigned integer. There is no standard way of calculating this, so it is up to the application to determine. May be set to zero and ignored.
32	Tags	2+	A string giving any descriptive tags or keywords applied to the file. Tags should be separated by commas.
	Title	2+	A string giving the name or title of the Integrated Sprite.
	Project	2+	A string giving the name of the project or application that this Integrated Sprite is a part of.
	Author	2+	A string giving the name of the author (or authors) of the file's contents.
	Company	2+	A string giving the name of the company that owns the rights to the file.
	Contact	2+	A string giving contact information, usually in the form of an email address.
	URL	2+	A string giving an internet hyperlink, generally for the inclusion of a project/personal/company homepage. The "http://" at the beginning may be omitted or included.
	Copyright	2+	A string giving a copyright field.
	Comments	2+	A string giving any comments given by the author(s).
	Originating Program Name	2+	A string giving the name of the program used to originally create the Integrated Sprite. Future programs are not to modify or strip this value for any reason, so long as the file metadata information chunk is present and is to be included.
	Program Name	2+	A string giving the name of the program most recently used to work on or save the Integrated Sprite's data file. If blank, it is assumed to be the same as the originating program.

Additional File Metadata Information

This chunk supplements the normal file information chunk by allowing for extra metadata fields not specified in the standard file information chunk. It is provided for convenience, even though it is not likely to see much use.

As such, like the normal file information chunk, this is an optional chunk. The header will be as follows.

Offset	Purpose	Bytes	Details
0	Chunk Identifier	4	Chunk ID "MET+". 4D 45 54 2B
4	Chunk Size	4	A 32-bit unsigned integer giving the total size of the chunk (after this field), in bytes.

After the chunk header, the following is repeated for each metadata field, until the end of the chunk is reached.

Purpose	Details
Field Name	The name string of the field.
Field Value	The value string of the field.

Source Textures

This chunk lists the textures used by the Integrated Sprite.

Offset	Purpose	Bytes	Details
0	Chunk Identifier	4	Chunk ID "TEX ". 54 45 58 20
4	Chunk Size	4	A 32-bit unsigned integer giving the total size of the chunk (after this field), in bytes.
8	Texture Count	1	An 8-bit unsigned integer giving the total number of textures. Zero is an acceptable value, in which case this sprite has no displayable graphics of its own.
9	Stride	1	The number of bytes used by each texture, prior to its filename string (thus, not counting the string). In this version of the standard, it is always 1. Future versions of the standard may have more information for each texture, requiring a larger stride.

After this, textures are listed in order one after the other, starting at byte offset 10 of the chunk with texture 0. The following is repeated for each texture.

Offset	Purpose	Bytes	Details
0	Flags	1	Boolean flags related to this texture and its display. Bit Purpose 0 If set to true, this texture is meant to be filtered using nearest neighbor interpolation. This is useful for sprites that use pixel art. If not set, the texture should be filtered with whatever smoothing interpolation is desired on the part of the application. All other bits should be set to zero.
1	Filename	2+	A string giving the path (relative to the sprite file) and filename of the image file to load for the source texture. The directory separator should always be a forward slash "/", and two periods ".." should denote a parent directory. Remember that the file extension will not be included here and must be supplied by the application. See the section on source sheets for more information.

For maximum forward and backwards compatibility, make sure to advance by the stride amount each texture before attempting to read the filename, not just by the number of bytes used in this version. The above values (other than the filename string) are guarunteed to be at the given offsets for all minor versions and revisions of this major version of the standard.

Slices

This chunk lists all the sprite's slices.

Offset	Purpose	Bytes	Details
0	Chunk Identifier	4	Chunk ID "SLIC". 53 4C 49 43
4	Chunk Size	4	A 32-bit unsigned integer giving the total size of the chunk (after this field), in bytes.
8	Slice Count	4	A 32-bit unsigned integer giving the total number of slices. Zero is an acceptable value, in which case this sprite has no displayable graphics of its own.
12	Stride	1	The number of bytes used by each slice. In this version of the standard, the stride is always 10 (hexadecimal 0A). Future versions of the standard may have more information for each slice, requiring a larger stride.

After this, slices are listed in order one after the other, starting at byte offset 13 of the chunk, with slice 0. The following 10 bytes are repeated for each slice.

Offset	Purpose	Bytes	Details
0	Texture ID	1	An 8-bit unsigned integer value. Defines which texture this slice is from.
1	Flags	1	BIT Purpose 0 If set to 1, then the slice has been rotated 90° clockwise in the texture in order to fit or save space, and must be rotated back (90° counter-clockwise) to be displayed correctly. All other bits should be set to zero.
2	Upper-Left Coordinate	4	A texture coordinate. This is the inclusive upper-left corner coordinate of the slice.
6	Width	2	A 16-bit unsigned integer value giving the width of the slice, in pixels. Zero is not a valid value.
8	Height	2	A 16-bit unsigned integer value giving the height of the slice, in pixels. Zero is not a valid value.

For maximum forward and backwards compatibility, make sure to advance by the stride amount each slice, not just by the number of bytes used in this version. The above values are guarunteed to be at the given offsets for all minor versions and revisions of this major version of the standard.

Element Names

Gives all the unique names used by this sprite's elements. Because elements share names across frames, the names are stored in this chunk by themselves instead of repeating them over and over again throughout the file.

Offset	Purpose	Bytes	Details
0	Chunk Identifier	4	Chunk ID "NAME". 4E 41 4D 45
4	Chunk Size	4	A 32-bit unsigned integer giving the total size of the chunk (after this field), in bytes.
8	Name Count	2	A 16-bit unsigned integer giving the total number of unique names in use across all frames.

After this, starting at offset byte 10 of the chunk, the names are given one by one in order, starting with point 0.

Purpose	Details
Name	The name of all elements in the sprite that use this ID.

Animation Hierarchy

This gives the hierarchy tree of animation groups and animation sequences. Note that the actual contents of each frame are not defined here, but can be found in the frame data chunk.

The chunk begins with the following header.

Offset	Purpose	Bytes	Details
0	Chunk Identifier	4	Chunk ID "TIER". 54 49 45 52
4	Chunk Size	4	A 32-bit unsigned integer giving the total size of the chunk (after this field), in bytes.

 

After the chunk header, the chunk begins listing groups and sequences, one after the other.

Animation groups have the following data.

Offset	Purpose	Bytes	Details
0	Group Marker	1	The ASCII letter "G" denotes that this is an animation group. A hexidecimal value of 47, a decimal value of 71.
1	Name	2+	A string giving the name of this animation group.

Any animation sequences that follow are to be placed directly in this animation group, as are any animation groups.

Animation sequences have the following data.

Offset	Purpose	Bytes	Details
0	Sequence Marker	1	The ASCII letter "S" denotes that this is an animation sequence. A hexidecimal value of 53, a decimal value of 83.
1	Frame Count	4	A 32-bit unsigned integer giving the number of frames in this animation sequence.
5	Loop Point	4	A 32-bit unsigned integer defining the frame number of the sequence's loop point. If this is set to the maximum value FFFFFFFF, then the animation should stop upon reaching the end. Otherwise, playback should return to this given frame once the final frame is complete. Note that this value refers to the loop point frame's location in the sequence. This is not the frame ID of the loop point frame. This value is ignored if a follow-up sequence is defined.
9	Name	2+	A string giving the name of this animation sequence.
	Follow-Up Sequence	2+	A string giving the name of the animation sequence to play when this sequence is complete. If an empty string is given, then there is no follow-up sequence, and this sequence should either stop or loop as definined in the loop point value preceeding it.
	Frame IDs	4 each	Frame IDs are given as 32-bit unsigned integers. They are listed one after the other.

Animation groups in the tree are closed with a closing marker. When they are encountered, move one group back up the hierarchy tree.

Purpose	Bytes	Details
Closing Marker	1	The ASCII letter "C" denotes that the most recently declared animation group is now fully defined. A hexidecimal value of 53, a decimal value of 83.

Provided that the file was encoded correctly, the chunk should end with all the declared animation groups closed out, and the reader back in the root animation group.

Frame Data

This is where the bulk of the data in the file is liable to be. All the frames and their content are defined in this chunk. Which frame belongs to which sequence is not contained here, but can be found in the animation hierarchy data where animation sequences are defined.

Offset	Purpose	Bytes	Details
0	Chunk Identifier	4	Chunk ID "FRAM". 46 52 41 4D
4	Chunk Size	4	A 32-bit unsigned integer giving the total size of the chunk (after this field), in bytes.
8	Frame Count	4	A 32-bit unsigned integer giving the total number of frames across all animation sequences.
12	Maximum Element Count	2	A 16-bit unsigned integer giving the highest element count in a single frame. No frame in this file should have more than this number of elements. Not used internally, but can be used by an application to decide how much memory to allocate in order to store and manipulate the frame data for this sprite.

After this, starting at offset 14, the frames are listed in order one after the other, starting with frame 0.

Each frame begins with the following data.

Offset	Purpose	Bytes	Details
0	Frame Marker	1	The ASCII character "F", denoting the start of frame data. A hexadecimal value of 46, a decimal value of 70.
1	Size	4	A 32-bit unsigned integer giving the total size, in bytes, of this frame's data in the file (not including these four bytes).
5	Element Count	2	A 16-bit unsigned integer giving the total number of elements in this frame.
7	Hold Time	2	A 16-bit unsigned value giving the number of frames to hold this individual frame for. The normal value for this field is 1. A value of zero is invalid, and the frame should default to a duration value of 1 if zero is encountered.
9	Flags	1	Boolean flags for this frame. Bit Purpose 0 If set, indicates that this is a loop point. When playback of the last frame in a sequence is complete, it should return to this frame. Otherwise, the first frame of a sequence is the loop point. All other bits are unused and should be set to zero.
10	Frame Label	2+	A string giving the frame an optional label.
	Triggers	2+	A string listing any scripting commands for the frame, to be passed to the application whenever this frame is activated during an animation sequence.
	Notes	2+	A string giving any comments or notes from the author.

Each element in the frame is then listed in a specific order. Elements listed first are to appear below those listed later. The exact data format of each element depends on what kind of element it is, but they always begin with the following four bytes.

Offset	Purpose	Bytes	Details
0	Element Marker	1	A value, generally in the form of an ASCII character, giving the element type.
1	Name	2	A 16-bit unsigned integer giving the index of this element's name in the element name table. If an element has no given name (that is, its name is intended to be an empty string), this value may be set to the maximum value of FFFF.
3	Size	1	An 8-bit unsigned integer giving the size, in bytes, of the remaining element data after this point.

Graphic Elements

Graphic elements come in two varieties, simple and expanded. The only difference is how they are stored in the file. Simple graphic elements don't use things like rotation and scaling, so they don't take up extra space by including those values.

Both simple and expanded graphic elements begin with the following data.

Offset	Purpose	Bytes	Details
0	Graphic Element Marker	1	The ASCII letter "G" denotes that this is a graphic element, with full "expanded" data. A hexadecimal value of 47, a decimal value of 71. The ASCII lowercase letter "g" denotes that this is a graphic element, with only the most basic data included. A hexadecimal value of 67, a decimal value of 103.
1	Name	2	A 16-bit unsigned integer giving the index of this element's name in the element name table. If an element has no given name (that is, its name is intended to be an empty string), this value may be set to the maximum value of FFFF.
3	Size	1	The size of a fully encoded graphic element is 30 bytes, so this value must be set to 26 (1A in hexadecimal). The size of basic graphic element is 13 bytes, so this value must be set to 9.
4	Slice ID	2	The index of the slice being instanced for this graphic element.
6	Position	6	A coordinate giving this element's position in relation to the sprite's origin point.
12	Mirroring	1	Elements can be mirrored on either axis. Bit zero is the horizontal mirroring flag, while bit one is the vertical mirroring flag. You can check them individually, or just group them together by checking the integral value.

Simple graphic element data ends here, while the full expanded data goes on to include the following.

Offset	Purpose	Bytes	Details
13	Origin Point	6	A coordinate giving this element's origin point in relation to the upper-left corner of the slice. The element will be rotated and sized in relation to this origin point.
19	Rotation	3	A 24-bit fixed-point value giving this element's rotation, in degrees. 360 degrees is one full rotation. Higher values rotate clockwise, lower values rotate counterclockwise.
22	Scaling	6	A pair of 24-bit fixed point values giving the scaling of this element on each axis. The x-axis coordinate is given first, followed by the y-axis coordinate. A value of 1 is normal scale, while a value of 2 is double scale, and so on. A value of 0 with a decimal value of 128 is half size.
28	Opacity	2	A 16-bit unsigned integer giving the opacity value. At max value (hexidecimal FFFF), the element is fully opaque, while at zero it is fully transparent.

For simple graphic elements that don't contain the above fields, use the following values as defaults in their place.

Field	Value
Origin Point	The center of the element. To achieve this, divide the slice's width and height by half. (Alternatively, this can be ignored as it is only needed if the application wants to make manual changes to the animation.)
Rotation	Rotation should be set to zero (none).
Scaling	Scale on both axes should be 1 (normal scale).
Opacity	Opacity should be set to full (fully opaque).

Attachment Points

Attachment points are similar to graphic elements in how their data is stored.

Offset	Purpose	Bytes	Details
0	Attachment Point Element Marker	1	The ASCII letter "A" denotes that this is an attachment point. A hexadecimal value of 41, and a decimal value of 65.
1	Name	2	A 16-bit unsigned integer giving the index of this element's name in the element name table. If an element has no given name (that is, its name is intended to be an empty string), this value may be set to the maximum value of FFFF.
3	Size	1	An attachment point is 25 bytes in size, so this value must be set to 21 (15 in hexadecimal).
4	Attachment Point ID	2	A 16-bit unsigned integer giving the index value of the attachment point.
6	Position	6	See explanations above for graphic elements.
12	Mirroring	2
14	Rotation	3
17	Scaling	6
23	Opacity	2

Note that attachment points do not have origin points. Sprites or other graphics attached to the attachment point should use their own origin point to place and orient themselves in relation to the attachment point.

Collision Detection Objects

Collision detection objects are the most different of the elements.

Offset	Purpose	Bytes	Details
0	Collision Detection Element Marker	1	The ASCII letter "C" denotes that this is a collision detection object element. A hexadecimal value of 43, a decimal value of 67.
1	Name	2	A 16-bit unsigned integer giving the index of this element's name in the element name table. If an element has no given name (that is, its name is intended to be an empty string), this value may be set to the maximum value of FFFF.
3	Size	1	Rectangles are 24 bytes long. This value must be set to 20 for them (14 in hexadecimal). Circles are 17 bytes long. This value must be set to 13 for them (0D in hexadecimal).
5	Collision Detection Type Marker	1	Two kinds of collision detection objects are used in the Integrated Sprite standard: rectangles and circles. Bounding rectangles are denoted by the ASCII lower case letter "r". A hexadecimal value of 72, a decimal value of 114. Bounding circles are denoted by the ASCII lower case letter "c". A hexadecimal value of 63, a decimal value of 99.
6	Collision ID	2	A 16-bit unsigned value giving the index of this collision detection object.

Rectangles have the following additional fields.

Offset	Purpose	Bytes	Details
8	Upper-Left Corner Coordinate	6	The inclusive coordinate of the rectangle's upper-left corner, in relation to the sprite's origin point.
14	Width	3	A 24-bit fixed-point value giving the width of the rectangle, in pixels.
17	Height	3	A 24-bit fixed-point value giving the height of the rectangle, in pixels.
21	Rotation	3	A 24-bit fixed point value fiving the rotation of the rectangle, in degrees. Higher values rotate the rectangle clockwise. This rotation centers around the upper-left coordinate.

Circles have the following additional fields.

Offset	Purpose	Bytes	Details
8	Position	6	The position of the bounding circle, in relation to the sprite's origin point.
14	Radius	3	A 24-bit fixed-point value giving the bounding circle's radius.