Gameloft BSprite Extractor

This directory contains the standalone Java extractor created to decode and reassemble the sprites from the game Diamond Rush (.f format).

The Original Challenge

Initially, the game files are not simple images. Gameloft compressed all resources to fit into old mobile devices with very limited memory (J2ME).

When we decompiled the a.java class from the game, we realized it is a highly optimized rendering engine. However, extracting just the pixels wasn't enough. The sprites suffered from being "badly cut" (like jigsaw puzzle pieces).

Why did the Sprites look "badly cut"?

The BSprite format does not store animation frames directly. It divides everything into:

1. Modules: Small pieces of base images (like a head, an arm, or 1/4 of a boulder).
2. Cutouts: Metadata that dictates which Module to use, and where it should be positioned on the screen (X and Y offsets) using flips and mirroring.
3. Frames: The combination of multiple Cutouts to form a single image (e.g., Character walking).

Extracting only the Modules resulted in a "jigsaw puzzle" effect.

How this Extractor Works

The SpriteExtractor.java documented here performs two main reading steps for each section of the .f file:

1. Header and Palette Parsing (parseSectionData)

It reads the dimension arrays (Modules), Frame and Cutout information, and decodes the Palettes. The same sprite can have multiple palettes. The red-shirt Explorer, for example, used Palette 1 (_p1.png), while Palette 0 was grayish. We support ARGB8888, RGB4444, A1R5G5B5, and RGB565 palettes!

2. Module Pixel Decompression (decodeModulePixels)

Decompresses the pixel packet using super old techniques that varied per file (RLE, 4-bits, 2-bits, 1-bit, or even 8-bits per pixel).

3. Frame Assembly

The most critical step that fixed the problem. The code reads how many cutouts a Frame needs, calculates the required canvas size (Bounding Box), iterates over the modules, applies colors, performs the original J2ME mathematical rotations (transform = FlipX | FlipY), and paints the perfectly aligned frame into a PNG image ready for modern games!

Usage

To extract the sprites, you will need the original Java game file (typically named dr240.jar). The script is programmed to read the .f files (like /0.f, /b1.f, /mm1.f) directly from inside the .jar.

1. Compile the extractor:

   javac SpriteExtractor.java

2. Run the extractor (by putting the .jar in the classpath):

   • On Linux/Mac:

     java -cp .:dr240.jar SpriteExtractor

   • On Windows:

     java -cp .;dr240.jar SpriteExtractor

The script will search through the .jar, find Gameloft's proprietary files, decode the image math, and save all the perfectly assembled animations as PNGs inside a folder named extracted_sprites/.