Research: Decoding Field Animation Structure

[Jugales]

Hi guys, I'm posting my research on field effects in hopes that we can be understand their structure. Below are my notes, originally posted on Github. If you have any information about these animations and their structure, please let me know.

What are field elements?
Field elements are sprites, overlays, and underlays which display in the world depending on current game/entity states. We could call them graphical field effects but that would be confused with commonly known monster abilities with "field effects".

Examples
Basic examples of field elements are the grass animation when walking through grass, sandy footprints when walking on sand, and circles when walking on puddles. This also includes the surf and fly buddy sprites, fishing (water) animations, and trainer hiding panels.

Attached are the (currently known) field elements for Emerald and Fire Red, with the internal index of each element above the spritesheet. Skipped indexes are known to be broken or empty.

BPRE (some palettes incorrect)

BPEE (some palettes incorrect)

As you can see, the table of field elements is very similar between games. Some field elements are exactly the same between games, possibly due to Nintendo reusing engine assets.

Field Element Structure

There is a table which holds a reference to each of these field elements:

BPRE 1.0: 0x3A0010

BPEE 1.0: 0x5059F8

Structure Examples Based On:

Emerald (BPEE 1.0)

Field Element #4 (grass animation)

Get the Field Element Header Offset

offset = [tableStart] + (elementIndex * 4)

Example: offset = 0x5059F8 + (4 * 4)

After going to the offset, you will see a pointer. This is the pointer to the field element header.

## Read the Field element Header

Go the pointer found at the end of the step above.

The structure of the field element header is following:

| Field | Index | Datatype
| :--- | :---: | :---: |
| ??? Flag | 0 | Short |
| Palette Flag ? | 2 | Short |
| OAM Pointer? | 4 | Pointer |
| Animation Pointer? | 8 | Pointer |
| Bitmap Pointer | 12 | Pointer |

Quick Notes About Palettes (incomplete, needs research)
The default is the overworld hero sprite palette.
There is a table for field-specific palettes at 0x3A5340. There are 2 listing with structure:
[palette pointer][field palette key][filler; 2 bytes]

Known Palette Keys -
0xFFFF = 0x35b968 - main overworld (hero) palette (this seems to rarely be the wrong palette?)
0x1004 = 0x398fa8 - primary field palette read from table at 0x3A5340
0x1005 = 0x398fc8 - secondary field palette read from table at 0x3A5340
There seems to be more somewhere ... But where and how do we find them?

What Needs Research
- Palette read dynamically from the ROM (currently static)
- (Width and Data Size) OR (Width and Height) to determine spritesheet size. A tilemap would also work, but I have found no evidence of those.
- frame count OR each frame data size (so we can correctly split the sheet)
- animation frame interval (this might be static for all animations and done through ASM)

 

[Anon822]

...

Are you perhaps not aware of the decompilation projects? Reading the game's source code is a great way to figure out things.

For example let's look at this "Field Element Structure" you describe:
According to the firered 1.0 symbol map, the offset 0x3A0010 contains gFieldEffectObjectTemplatePointers. With a text search in pokefirered we can find its definition:

const struct SpriteTemplate *const gFieldEffectObjectTemplatePointers[]

So the "Field element header" is actually the SpriteTemplate structure, defined here.

 

[Jugales]

Are you perhaps not aware of the decompilation projects? Reading the game's source code is a great way to figure out things.

For example let's look at this "Field Element Structure" you describe:
According to the firered 1.0 symbol map, the offset 0x3A0010 contains gFieldEffectObjectTemplatePointers. With a text search in pokefirered we can find its definition:

const struct SpriteTemplate *const gFieldEffectObjectTemplatePointers[]

So the "Field element header" is actually the SpriteTemplate structure, defined here.

Awesome tip! I did some digging through the C code, and found what is happening.

There is a "palette tag" system. I write right about the two primary palettes, in the decomp they have constants FLDEFF_PAL_TAG_GENERAL_0 and FLDEFF_PAL_TAG_GENERAL_1. They have tag values of 0x1004 and 0x1005 as the OP mentions.

However, there is snag with palette tag 0xFFFF. It means the palette is determined programmatically based on the current overworld sprite palettes in reserve. For the tree disguises, the palette IDs are set in the code here in the decomp field_effect_helpers.c:

Manually supplying the palette numbers in my tool to align with overworld palettes fixed the issue. I guess I'll just have to make palette non-editable since they're shared resources.

I still have a few things to look into, like frame layout (size) and animations, but certainly heading in the right direction.

Thanks again for the help!