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
andgetDolFile()
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.-
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 pathParameters: path (bytes) – Returns: Return type: BannerFile
-
getDolFile
(path=b'start.dol')[source]¶ Creates a
DolFile
from the file with the given pathParameters: 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
andIsoInternalFileWrapper
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 bytesValueError
– 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.
-
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.
- isoFile (
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
-
sections
¶ Just a joined list of
DolFile.textSections
andDolFile.dataSections
Type: list of Section
-
sectionsDolOrder
¶ DolFile.sections
but sorted by DOL offsetType: list of Section
-
sectionsMemOrder
¶ DolFile.sections
but sorted by memory addressType: 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
-
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 callsisMappedContiguous()
.
-
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
objectsType: MetaData
or list ofMetaData
-
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
-
-