Welcome to gciso’s documentation!

IsoFile

class gciso.IsoFile(isoPath)[source]

The central class representing an .iso file. For information about many of it’s attributes, see here: http://hitmen.c02.at/files/yagcd/yagcd/chap13.html#sec13

Parameters:isoPath (str) – The path to the iso file.
gameCode
Type:bytes
makerCode
Type:bytes
diskId
Type:int
version
Type:int
gameName
Type:bytes
dolOffset

Offset to the main executable DOL (“start.dol”)

Type:int
dolSize

Size of the main executable DOL (“start.dol”)

Type:int
fstOffset

Offset to the file system table

Type:int
fstSize

Size of the file system table

Type:int
maxFstSize

Maximum size of the file system table (relevant for games with multiple disks)

Type:int
apploaderDate

Date (version) of the apploader (ASCII).

Type:bytes
apploaderEntryPoint
Type:int
apploaderCodeSize
Type:int
apploaderTrailerSize
Type:int
numFstEntries

The number of file system table entries (files and directories)

Type:int
stringTableOffset

The offset to the FST string table

Type:int
files

A dictionary with keys being paths to all files in the .iso and values being tuples of the form (offset, size) (offset and size of the file). See Notes for added system files!

Type:OrderedDict

Notes

A couple of files are added to the files attribute, that are not listed in the FST:

  • boot.bin - The header of the .iso file
  • bi2.bin - More disk information (containing dol/FST offsets etc.)
  • fst.bin - The file system table
  • start.dol - The main executable DOL. See DolFile and getDolFile()

IsoFile may also be used as a context manager:

with IsoFile("melee.iso") as isoFile:
    data = isoFile.readFile("opening.bnr", 0)
    with isoFile.open("opening.bnr") as bnrFile:
        print(bnrFile.read())

Also all files that take a file path may raise TypeError, if the given path is not of type bytes.

close()[source]

Closes the file

static fileInDir(filePath, dirPath)[source]
Parameters:
  • filePath (bytes) –
  • dirPath (bytes) –
Returns:

Whether the file filePath is inside the directory dirPath

Return type:

bool

fileOffset(path)[source]
Parameters:path (bytes) –
Returns:The offset of the file with the given path inside the .iso file.
Return type:int
fileSize(path)[source]
Parameters:path (bytes) –
Returns:The size of the file with the given path inside the .iso file.
Return type:bool
getBannerFile(path)[source]

Creates a BannerFile from the file with the given path

Parameters:path (bytes) –
Returns:
Return type:BannerFile
getDolFile(path=b'start.dol')[source]

Creates a DolFile from the file with the given path

Parameters:path (bytes) – If no path is given, the main executable DOL start.dol is used.
Returns:
Return type:DolFile
isDir(path)[source]
Parameters:path (bytes) –
Returns:Whether the given path belongs to a directory that exists inside the .iso and contains files.
Return type:bool
isFile(path)[source]
Parameters:path (bytes) –
Returns:Whether the given path belongs to a file that exists inside the .iso.
Return type:bool
listDir(path)[source]

Lists all files in a directory (including files in subdirectories, not including other directories).

Parameters:path (bytes) –
Yields:bytes – Filenames of the files in the directory. Relative to the directory being listed.
open(path)[source]
Parameters:path (bytes) –
Returns:A wrapper of the given file.
Return type:IsoInternalFileWrapper

Notes

See the notes of IsoFile and IsoInternalFileWrapper for examples.

readFile(path, offset, count=-1)[source]

Reads count bytes from offset inside the file with path path

Parameters:
  • path (bytes) –
  • offset (int) –
  • count (int) – If count is negative, none or omitted, read until end of file
Returns:

The data read

Return type:

bytes

Raises:
  • IndexError – If offset is negative or greater than the file size.
  • ValueError – If the read would go past the end of the file.
writeFile(path, offset, data)[source]

Writes data to the file with path path inside the .iso at offset offset.

Parameters:
  • path (bytes) –
  • offset (int) –
  • data (bytes) –
Returns:

The number of bytes written

Return type:

int

Raises:
  • IndexError – If offset is negative or greater than the file size.
  • TypeError – If path or data is not bytes
  • ValueError – If the write would go past the end of the file, since it cannot change size.

IsoInternalFileWrapper

class gciso.IsoInternalFileWrapper(isoFile, offset, size)[source]

Wraps a file inside the .iso. You probably don’t want to call this yourself. See IsoFile.open().

Parameters:
  • isoFile (IsoFile) –
  • offset (int) – Offset of the file inside the .iso file.
  • size (int) – Size of the file

Notes

This class may also be used as a context manager, similar to open from the standard library.:

with isoFile.open(b'PlSs.dat') as f:
    f.seek(0x1000)
    data = f.read(0x30)
close()[source]

Internally this is a NOP, but it exists to provide more compatibility with Python’s own file objects.

read(size=-1)[source]

Reads data starting from the current position.

Parameters:size (int) – How many bytes to read. If None, negative or ommited, read until end of file
Returns:The data read from the file
Return type:bytes

Notes

See IsoFile.readFile() for exceptions this function might raise.

seek(offset, whence=0)[source]

Moves the current position inside the file according to the given offset.

Parameters:
  • offset (int) – The offset
  • whence (int) – One of either 0, 1 or 2. See notes.
Returns:

The current position after seeking.

Return type:

int

Raises:

ValueError – If whence is not in {0, 1, 2}

Notes

If whence is 0, the offset will be interpreted relative to the start of the file.

If whence is 1, the offset will be interpreted relative to the current position.

If whence is 2, the offset will be interpreted relative to the end of the file. Usually in this case offset is negative.

You may also seek before or after the end of the file, though write and read operations will most likely fail.

tell()[source]
Returns:The current position inside the file
Return type:int
write()[source]

Writes data to the current position.

Parameters:data (bytes) –
Returns:The number of bytes written
Return type:int

Notes

See IsoFile.writeFile() for exceptions this function might raise.

DolFile

class gciso.DolFile(data)[source]

Represents a DOL executable file. You probably don’t want to instance this class yourself, but rather call IsoFile.getDolFile(). See here for some more information about the attributes of this class: http://hitmen.c02.at/files/yagcd/yagcd/chap14.html#sec14.2 The DOL file is loaded into memory by the Apploader, section by section. This may or may not include permutation or fragmentation (the sections stay contiguous, but there may be gaps between the sections after being loaded.)

Parameters:data (bytes or IsoInternalFileWrapper) – The file to be interpreted as a DOL file. See description of this class.
data

The DOL file as bytes

Type:bytes
bssMemAddress
Type:int
bssSize
Type:int
entryPoint
Type:int
bodyOffset

Offset to the the data after the header of the DOL

Type:int
textSections

The text sections of the DOL

Type:list of Section
dataSections

The data sections of the DOL

Type:list of Section
sections

Just a joined list of DolFile.textSections and DolFile.dataSections

Type:list of Section
sectionsDolOrder

DolFile.sections but sorted by DOL offset

Type:list of Section
sectionsMemOrder

DolFile.sections but sorted by memory address

Type:list of Section
class Section(index, sectionType, dolOffset, memAddress, size)[source]

A section in a DOL file. You probably never want to instantiate this class yourself.

Parameters:
  • index (int) – The index of the section
  • sectionType (DolFile.SectionType) – The type of the section
  • dolOffset (int) –
  • memAddress (int) –
  • size (int) –
index
Type:int
type
Type:DolFile.SectionType
dolOffset
Type:int
endDolOffset
Type:int
memAddress
Type:int
endMemAddress
Type:int
size
Type:int
isBefore(other)[source]
class SectionType[source]

The type of section in the DOL file.

DATA = 'data'
TEXT = 'text'
dolOffsetToMemAddress(dolOffset)[source]
Parameters:dolOffset (int) – An offset inside the DOL file.
Returns:The memory address the data pointed to by dolOffset is loaded to if it belongs to a DOL section. None otherwise.
Return type:int or None
getSectionByDolOffset(dolOffset)[source]
Parameters:dolOffset (int) – A offset inside the DOL file
Returns:The section dolOffset points to or None if that offset does not point to a DOL section.
Return type:Section or None
getSectionByMemAddress(memAddress)[source]
Parameters:memAddress (int) – Memory address
Returns:The section the memory address points to or None if that address does not point to a DOL section.
Return type:Section or None
isMappedContiguous(dolOffsetStart, dolOffsetEnd)[source]

This function determines whether a range of (contiguous) memory in the DOL file is loaded contiguously to memory.

Parameters:
  • dolOffsetStart (int) – The start of the data range inside the DOL
  • dolOffsetEnd (int) – The end of the data range (non-inclusive).
Returns:

Return type:

bool

Notes

dolOffsetEnd not being inclusive means that if isContiguous(0, 4) is True, then the byte at offset 4 not be 4 bytes after the byte at offset 0 in memory. (Only byte 0, 1, 2 and 3 are).

isMappedContiguousMem(memAddressStart, memAddressEnd)[source]

See isMappedContiguous(), but starting with memory. This essentially just maps the memory addresses to DOL offsets and then calls isMappedContiguous().

memAddressToDolOffset(memAddress)[source]
Parameters:memAddress (int) – Memory address
Returns:The offset inside the DOL of the data that is loaded to memAddress if it belongs to a DOL section. None otherwise.
Return type:int or None

BannerFile

class gciso.BannerFile(data)[source]

Represents a .bnr file. Mostly there is just one opening.bnr in an .iso. In PAL .isos there are multiple. You probably don’t want to instance this class yourself, but rather call IsoFile.getBannerFile().

Parameters:data (bytes or IsoInternalFileWrapper) – The file to interpret as a banner file. See the description of this class.
magicBytes
Type:bytes
pixelData

The pixel data of the image in RGB5A1 format.

Type:bytes
meta

For PAL isos meta may be a list with multiple MetaData objects

Type:MetaData or list of MetaData
class MetaData(data, offset=0)[source]

Contains metadata of a banner. See here for more information about the fields: http://hitmen.c02.at/files/yagcd/yagcd/chap14.html#sec14.1

gameName
Type:bytes
developerName
Type:bytes
fullGameTitle
Type:bytes
fullDeveloperName
Type:bytes
gameDescription
Type:bytes
getPILImage()[source]

PIL will be imported lazily by this function. So PIL or Pillow is only a requirement if you use this function.

Returns:
Return type:PIL.Image

Indices and tables