ws¶

Support for WonderSwan ROMs, split into banks.

ROMs are extracted and repacked as a set of bank_xx.bin files, one per 0x10000 byte bank, with xx being the bank number in hex. Images are handled as 8x8 tiles, either sequential or arranged by tile maps and sprites, in the 2bpp grayscale and 4bpp color formats.

hacktools.ws.extractRom(romfile, extractfolder, workfolder='')[source]¶

Extract a WonderSwan ROM to a folder, splitting it into banks.

Parameters:

romfile (str) – Path of the ROM file.
extractfolder (str) – Path of the folder to extract to.
workfolder (str) – Optional path of a work folder the extracted files are copied to.

Return type:

None

hacktools.ws.repackRom(romfile, rompatch, workfolder, patchfile='')[source]¶

Repack a WonderSwan ROM from the bank files in a folder.

The checksum in the last 2 bytes of the ROM is recalculated after the banks are joined.

Parameters:

romfile (str) – Path of the original ROM file.
rompatch (str) – Path of the output ROM file.
workfolder (str) – Path of the folder with the bank files.
patchfile (str) – Path of the xdelta patch to create, an ips patch is also created next to it. No patches are created if empty.

Return type:

None

hacktools.ws.memoryToBank(segment, address, rom0, rom1, rom2, sram=0, nbanks=64, justbank=False)[source]¶

Convert a segmented memory address to a linear ROM position.

The rom0, rom1, rom2 and sram values are the contents of the 0xc2, 0xc3, 0xc0 and 0xc1 bank registers.

Parameters:

segment (int) – Segment part of the address.
address (int) – Address part of the address.
rom0 (int) – Bank mapped in the rom0 slot.
rom1 (int) – Bank mapped in the rom1 slot.
rom2 (int) – High nibble of the banks mapped in the linear slots.
sram (int) – Bank mapped in the sram slot.
nbanks (int) – Total number of banks in the ROM.
justbank (bool) – Whether to return just the bank number, instead of the full position.

Returns:

The linear ROM position, or the bank number if justbank is True.

Return type:

int

hacktools.ws.readPointer(f, bankoff=0)[source]¶

Read a segmented pointer, stored as address followed by segment.

Parameters:

f (Stream) – Stream to read from.
bankoff (int) – Offset subtracted from the linear address.

Returns:

The linear address the pointer refers to.

Return type:

int

hacktools.ws.readTile(f, pixels, x, y, palette, hflip=False, vflip=False, bpp=2)[source]¶

Read a single 8x8 tile and draw it on an image.

Parameters:

f (Stream) – Stream to read from.
pixels – PIL pixel access object to draw on.
x (int) – X position to draw at.
y (int) – Y position to draw at.
palette (list) – Palette to use, as a list of RGBA tuples.
hflip (bool) – Whether the tile is flipped horizontally.
vflip (bool) – Whether the tile is flipped vertically.
bpp (int) – Bits per pixel, 2 or 4.

Return type:

None

hacktools.ws.writeTile(f, pixels, x, y, palette, bpp=2)[source]¶

Write a single 8x8 tile from an image.

Parameters:

f (Stream) – Stream to write to.
pixels – PIL pixel access object to read from.
x (int) – X position to read at.
y (int) – Y position to read at.
palette (list) – Palette to use, as a list of RGBA tuples.
bpp (int) – Bits per pixel, 2 or 4.

Return type:

None

hacktools.ws.bwpalette = [[(0, 0, 0, 255), (80, 80, 80, 255), (176, 176, 176, 255), (240, 240, 240, 255)]]¶: Default grayscale palette used for 2bpp images.

hacktools.ws.colpalette = [[(0, 0, 0, 255), (31, 31, 31, 255), (47, 47, 47, 255), (63, 63, 63, 255), (79, 79, 79, 255), (95, 95, 95, 255), (111, 111, 111, 255), (127, 127, 127, 255), (143, 143, 143, 255), (159, 159, 159, 255), (175, 175, 175, 255), (191, 191, 191, 255), (207, 207, 207, 255), (223, 223, 223, 255), (239, 239, 239, 255), (255, 255, 255, 255)]]¶: Default grayscale palette used for 4bpp images.

hacktools.ws.extractImage(f, outfile, width, height, palette=None, bpp=2)[source]¶

Extract an image made of sequential tiles to png.

Parameters:

f (Stream) – Stream to read from, seeked to the tile data.
outfile (str) – Path of the png file to create.
width (int) – Width of the image.
height (int) – Height of the image.
palette (list | None) – Palette to use, as a list of RGBA tuples, or None for the default grayscale one.
bpp (int) – Bits per pixel, 2 or 4.

Return type:

None

hacktools.ws.repackImage(f, infile, width, height, palette=None, bpp=2)[source]¶

Repack a png into an image made of sequential tiles.

Parameters:

f (Stream) – Stream to write to, seeked to the tile data.
infile (str) – Path of the png file to pack.
width (int) – Width of the image.
height (int) – Height of the image.
palette (list | None) – Palette to use, as a list of RGBA tuples, or None for the default grayscale one.
bpp (int) – Bits per pixel, 2 or 4.

Return type:

None

hacktools.ws.extractTiledImage(f, outfile, width, height, palette=None, bpp=2)[source]¶

Extract an image made of tiles in 2x2 groups to png.

Within each group, tiles are ordered top to bottom, then left to right.

Parameters:

f (Stream) – Stream to read from, seeked to the tile data.
outfile (str) – Path of the png file to create.
width (int) – Width of the image.
height (int) – Height of the image.
palette (list | None) – Palette to use, as a list of RGBA tuples, or None for the default grayscale one.
bpp (int) – Bits per pixel, 2 or 4.

Return type:

None

hacktools.ws.repackTiledImage(f, infile, width, height, palette=None, bpp=2)[source]¶

Repack a png into an image made of tiles in 2x2 groups.

Within each group, tiles are ordered top to bottom, then left to right.

Parameters:

f (Stream) – Stream to write to, seeked to the tile data.
infile (str) – Path of the png file to pack.
width (int) – Width of the image.
height (int) – Height of the image.
palette (list | None) – Palette to use, as a list of RGBA tuples, or None for the default grayscale one.
bpp (int) – Bits per pixel, 2 or 4.

Return type:

None

class hacktools.ws.TileMap[source]¶

Structure of a tile map.

name¶: Path of the png file the map is extracted to.

offset¶: Offset of the map data.

width¶: Width of the map, in tiles.

height¶: Height of the map, in tiles.

map¶: List of tile entries.

bpp¶: Bits per pixel of the tiles.

class hacktools.ws.TileData(tile=0, pal=0, hflip=False, vflip=False)[source]¶

Structure of a single tile map entry.

Parameters:

tile (int)
pal (int)
hflip (bool)
vflip (bool)

tile¶: Index of the tile.

data¶: Raw map entry value.

pal¶: Palette of the tile.

bank¶: Bank of the tile.

hflip¶: Whether the tile is flipped horizontally.

vflip¶: Whether the tile is flipped vertically.

class hacktools.ws.SpriteData[source]¶

Structure of a single sprite entry.

tile¶: Index of the tile.

data¶: Raw sprite entry value.

pal¶: Palette of the tile.

hflip¶: Whether the tile is flipped horizontally.

vflip¶: Whether the tile is flipped vertically.

xpos¶: X position of the sprite.

ypos¶: Y position of the sprite.

hacktools.ws.readPalette(f, bpp=2, num=16)[source]¶

Read palettes from the current stream position.

2bpp palettes hold 4 grayscale nibbles, 4bpp ones hold 16 12-bit colors.

Parameters:

f (Stream) – Stream to read from.
bpp (int) – Bits per pixel, 2 or 4.
num (int) – Number of palettes to read.

Returns:

The list of palettes, each a list of RGBA tuples.

Return type:

list

hacktools.ws.writePalette(f, palettes, bpp=2)[source]¶

Write palettes to the current stream position.

Parameters:

f (Stream) – Stream to write to.
palettes (list) – List of palettes, each a list of RGBA tuples.
bpp (int) – Bits per pixel, 2 or 4.

Return type:

None

hacktools.ws.readMappedImage(f, outfile, mapstart=0, num=1, bpp=2, width=0, height=0)[source]¶

Read tile maps from a stream.

Each map starts with its width and height in tiles, when they’re not given, followed by one 16-bit entry per tile.

Parameters:

f (Stream) – Stream to read from.
outfile (str) – Path of the png file for the map, numbered suffixes are added when num is more than 1.
mapstart (int) – Offset of the map data.
num (int) – Number of maps to read.
bpp (int) – Bits per pixel of the tiles.
width (int) – Width of the maps, or 0 to read it from the data.
height (int) – Height of the maps, or 0 to read it from the data.

Returns:

The list of maps.

Return type:

list

hacktools.ws.readSprite(f, spritelen, outfile, spritestart=0, bpp=2, width=0, height=0, ignorepal=False)[source]¶

Read sprite data and convert it to a tile map.

The map size is computed from the sprite positions, and one map entry is created for the sprite found at each tile position.

Parameters:

f (Stream) – Stream to read from.
spritelen (int) – Number of sprites to read.
outfile (str) – Path of the png file for the map.
spritestart (int) – Offset of the sprite data.
bpp (int) – Bits per pixel of the tiles.
width (int) – Unused.
height (int) – Unused.
ignorepal (bool) – Whether to ignore the sprite palettes.

Returns:

A list holding the single converted map.

Return type:

list

hacktools.ws.extractMappedImage(f, outfile, tilestart, mapstart, num=1, readpal=False, bpp=2, forcewidth=0, forceheight=0)[source]¶

Extract a tile-mapped image to png.

Parameters:

f (Stream) – Stream to read from.
outfile (str) – Path of the png file to create, numbered suffixes are added when num is more than 1.
tilestart (int) – Offset of the tile data.
mapstart (int) – Offset of the map data.
num (int) – Number of maps to extract.
readpal (bool) – Whether to read the palettes from before the map data, instead of using the default grayscale ones.
bpp (int) – Bits per pixel of the tiles.
forcewidth (int) – Width of the maps, or 0 to read it from the data.
forceheight (int) – Height of the maps, or 0 to read it from the data.

Return type:

None

hacktools.ws.writeMappedImage(f, tilestart, maps, palettes, num=1, skipzero=False)[source]¶

Draw tile maps to png files.

For 4bpp images with custom palettes, the palettes are also drawn on the right side of the image.

Parameters:

f (Stream) – Stream to read the tile data from.
tilestart (int) – Offset of the tile data.
maps (list) – List of maps returned by readMappedImage().
palettes (list) – List of palettes, each a list of RGBA tuples.
num (int) – Number of maps to draw.
skipzero (bool) – Whether to skip tile 0.

Return type:

None

hacktools.ws.repackMappedImage(f, infile, tilestart, mapstart, num=1, readpal=False, writepal=False)[source]¶

Repack a png into a tile-mapped image.

Tiles are deduplicated, reusing already written tiles and their flipped versions, and the map data is updated accordingly.

Parameters:

f (Stream) – Stream to write to.
infile (str) – Path of the png file to pack, numbered suffixes are added when num is more than 1.
tilestart (int) – Offset of the tile data.
mapstart (int) – Offset of the map data.
num (int) – Number of maps to repack.
readpal (bool) – Whether to read the palettes from before the map data, instead of using the default grayscale ones.
writepal (bool) – Whether to pick the best palette for each tile and write it in the map data, instead of keeping the original one.

Return type:

None

hacktools.ws.repackMappedTiles(f, tilestart, mapdata, palettes)[source]¶

Repack the tiles of a single map from a png, keeping the map data.

Flipped tiles are skipped, since their unflipped version is written by another entry.

Parameters:

f (Stream) – Stream to write to.
tilestart (int) – Offset of the tile data.
mapdata (TileMap) – Map holding the tile entries.
palettes (list) – List of palettes, only the first one is used.

Return type:

None