How to use GfxCrunch (Animated Object Sprites)

From SkyTemple

XML is a markup language for data. GfxCrunch uses this data to create object sprites for EoS (not fully confirmed info).

Recommend export to a static sprite from SkyTemple and then editing the exported files to your liking.

XML uses tags to list this data in the format of:

<TagName> content here </TagName>

GfxCrunch uses the following folders and files to generate object sprites.

imgs Folder

This is a folder of all image sprites used in the animations. Images are labeled from 0000.png, 0001.png, 0002.png, etc. These images have to be indexed images and fit within GfxCrunch’s sizes (16 x 16 or multiples of that are safe starting points).

palette.pal

Contains the image palette. The indexes correspond with the color indexes of the sprites in the imgs folder. Must contain 16 colors, including a transparent color. To obtain this, it's recommend to import one of your images into SkyTemple as a static sprite, then export from SkyTemple.

frames.xml

Contains data for image frames.

A <FrameGroup> is made up of x amount of <Frame> images, if it needs to form a bigger sprite. If a sprite is going to be just one image (eg: one PNG from the imgs folder), each PNG that will be used for animations needs to be in its own <FrameGroup>. If not, this will cause memory issues and/or crashes when displaying the object in cutscenes.

See the definitions of the XML tags below.

<FrameGroup>

Indicates a group of frames. Multiple frames can be layered on top of each other or be aligned side-to-side to create a "bigger sprite."

<Frame>

Indicates a single image sprite.

<ImageIndex>

The image index of the frame. This correlates with the image number in the imgs folder.

<Unk0>

Unknown. Value seems to always be 0x0 (0 in hexadecimal).

<Offset>

Determines the image offset of the frame which will affect where it is positioned on-screen. Recommend to base offset values off of other frame offsets.

<Unk1>

Unknown. Value seems to always be 0xc (12 in hexadecimal).

<Unk15>

Correlates to each Frame in one FrameGroup, used for memory allocation and layering. If there are multiple Frames in a FrameGroup, increment this value in each entry.

Value needed to start with and/or increment depends on the resolution size of the sprite. Ideally:

  • 8x8 frame (smallest size) requires 0x1 (1 in decimal)
  • 16x32 frame requires 0x2 (2 in decimal)
  • 32x64 frame requires 0x8 (8 in decimal)
  • 32x32 frame requires 0x4 (4 in decimal)
  • 64x64 frame (largest size) requires 0x10 (16 in decimal)

The number is represented in hexadecimal, so 0x0 is 0... 0xc is 12, 0x10 is 16, etc.

For more information on why this is important, see the spriteinfo.xml section.

<Resolution>

Uses <Width> and <Height> tags. Signals how large the image is in pixels.

<VFlip> & <HFlip>

Determines whether to flip the frame image vertically or horizontally, respectively. 0 does not flip the image while 1 does. Typically 0.

animations.xml

Contains data for animations.

<AnimGroupTable>

Container for the AnimGroup.

<AnimGroup>

Group containing a list of all AnimSequenceIndexes associated with the sprite. Lists out animation sequence indexes from 0, 1, 2, all the way to 7. This number correlates to the SetAnimation scripting function. A more detailed explanation about this can be seen below.

<AnimSequenceTable>

Container for each AnimSequence entry.

<AnimSequence>

Indicates an animation sequence, which is made up of individual AnimFrames defined in sequential order. Each AnimSequence should have an index in the AnimGroupTable. Remember that there is a maximum of 8 allowed, numbered 0 - 7.

An AnimSequence can be made up of as little as one frame, to as many as needed, provided the total amount of frames defined in frames.xml fit the memory allocation constraints (explained in the spriteinfo.xml section).

<AnimFrame>

Indicates a single animation frame.

<Duration>

Determines the duration of the frame, in frames.

<MetaFrameGroupIndex>

Determines the meta-frame the AnimFrame uses. This correlates to the frame’s index in frames.xml, starting from 0.

<Sprite> & <Shadow>

Unknown. Presumably they determine the offset of the sprite and shadow, respectively.

imgsinfo.xml

This section is unfinished. You can help expanding it.

Typically this file is pretty empty, like shown. This may differ in newer versions of SkyTemple.

spriteinfo.xml

The most important tag here is <Unk6>. As noted from the XML comments:

"Nb of "blocks" the image takes up in tile memory. Affects where things like the relic fragment will be loaded. If too low, item not loaded and replaced with parts of character sprite."

This value comes from adding up the hexadecimal values of <Unk16> in frames.xml.

The maximum amount of "blocks" allowed for one sprite is 255 (0xFF in hexadecimal). Anything over this value will crash the game. As noted, anything lower may allow the game to run sub-optimally with glitched graphics.

offsets.xml

This section is unfinished. You can help expanding it.

Typically this file is pretty empty, like shown.

How to Use with SetAnimation()

This is the ExplorerScript function that lets you change the animation of an object, with an integer taken in as an argument. When using the function, it should be called as SetAnimation<entity ENTITY>(x), where x is the Animation ID defined below.

Depending on how many AnimationSequenceIndexes you have defined and which behavior you want, the argument will differ as follows:

  • 1 - 8 will cause a specific animation to loop, with 1 denoting Animation 0 and 8 denoting Animation 7.
  • 9 - 16 will play Animation 0 and then play the first frame of the signified animation, with 9 denoting Animation 0 and 16 denoting Animation 7.
  • 17 - 24 will play a specific animation without looping, with 17 denoting Animation 0 and 24 denoting Animation 7.

Example

For reference, here is a link to a sample folder: External Link to Google Drive

Retrieved from "https://wiki.skytemple.org/index.php?title=How_to_use_GfxCrunch_(Animated_Object_Sprites)&oldid=1041"