You are on page 1of 19

"The SNES9x savestate file format" v0.

by creaothceann

1. Content

1. Content
2. Disclaimer
3. Revisions
4. Conventions
5. Savestates
6. File blocks
7. Unstructured file blocks
8.
Structured file blocks
9. Variables

2. Disclaimer

The information herein is provided as-is for anything you want. I tried to make it as accurate
as possible, but that might not mean much. And specifications can change at any time, too.
Nevertheless this document should be helpful, unless the savestate file format was _completely_
revamped since the last revision.

3. Revisions

2007-10-09: initial version 0.1

no sub-structure details yet

4. Conventions

I'll be using the following data types:


Byte
Word
DWord
QWord
Int64
Boolean
Char

unsigned

8-bit integer: $00..$00000000000000FF

=
unsigned 16-bit integer: $00..$000000000000FFFF
Demo Version
- ExpertPDF Software Components
=
unsigned 32-bit integer: $00..$00000000FFFFFFFF
=
=
=
=

unsigned 64-bit integer: $00..$FFFFFFFFFFFFFFFF


signed 64-bit integer: -(2^63)..(2^63 - 1)
8-bit type: 'False' (no bit set), 'True' (any bit set)
8-bit type: ANSI/ASCII character

"Array[x] of y" simply means: "x variables of type y without any padding bytes between them".
The structures listed here also have no empty space between their variables.

5. Savestates

SNES9x savestates (also called "freeze files" or "snapshots") have the filename extension
'.00x', with 'x' being a decimal digit ('0'..'9'). The files are usually compressed with GZIP;
they can be decompressed with tools like WinRAR. The GZIP library (and hence SNES9x) can also
handle uncompressed files.
At the beginning of the file there's a file header:
Signature
Colon
Version
LineFeed

:
:
:
:

Array[8] of Char
Char
Array[4] of Char
Char

"Signature" must be the string '#!snes9x', "Colon" must be ':', and "LineFeed" should be the
ASCII character #10. "Version" should be the decimal number string '0001'; otherwise the file
format itself would be a newer one.
The rest of the savestate is structured into file blocks of variable size.

6. File blocks

In an uncompressed file they look like this:


Name
Separator1
Size

:
:
:

Array[3] of Char
Char
Array[6] of Char

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 1 / 19

Separator2
Data

:
:

Char
Array[Size] of Byte

"Name" identifies the file block type. "Separator1" and "Separator2" contain the ASCII character
#58 (colon ':'). "Size" is a decimal number string describing the number of bytes in the "Data"
part.
The standard file block order is like this:
block
block
block
block
block
block
block
block
block
block
block
block
block
block
block
block
block

01:
02:
03:
04:
05:
06:
07:
08:
09:
10:
11:
12:
13:
14:
15:
16:
17:

NAM
CPU
REG
PPU
DMA
VRA
RAM
SRA
FIL
APU
ARE
ARA
SOU
SA1
SAR
SP7
RTC

(if
(if
(if
(if
(if
(if
(if
(if

emulating
emulating
emulating
emulating
emulating
emulating
emulating
emulating

the
the
the
the
the
the
the
the

APU)
APU)
APU)
APU)
SA-1)
SA-1)
SPC7110)
SPC7110 RTC)

File readers should accept the blocks in any order though, even several blocks of the same type.

================================================================================================

7. Unstructured file blocks

The following block types are simple byte or char arrays:


7.1
7.2
7.3
7.4
7.5
7.6

ARA
FIL
NAM
RAM
SRA
VRA

(APU RAM)
(FillRAM)
(cartridge name)
(WRAM data)
(SRAM data)
(VRAM data)

Demo Version - ExpertPDF Software Components

Unstructured file blocks are just streamed to disk.

7.1 ARA
=
Array[65536] of Byte

The "audio processing unit" (APU) RAM, which stores BRR-encoded samples and the program to play
them.
Note that read accesses to $FFC0..$FFFF can return either RAM as normal, or they can access the
content of the 64-byte "IPL ROM" that is responsible for data communications after a reset.
SNES9x handles that by defining a variable called "ExtraRAM" (see the APU file block), which is
used when RAM is selected.

7.2 FIL
=
Array[$0000..$7FFF] of Byte

In the SNES9x code, "FillRAM" is a pointer to 32 KB of scratch memory. Whenever the 65c816 does
a write access to addresses $xx:0000..$xx:7FFF, the value is also written into this array. With
"FillRAM" the developers can access registers by address rather than by name.

7.3 NAM
=
Array[?] of Char

A null-terminated string storing the filename of the cartridge ROM, as returned by the OS. The
block size is the length of the string plus the terminating byte (ASCII #0).
The string should not be treated as readable since there's no encoding. It's just used to detect
if the previously loaded ROM matches the currently loaded one.

7.4 RAM
=
Array[65536 * 2] of Byte

The "work RAM" (WRAM) data, usually accessed via banks $7E and $7F.

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 2 / 19

7.5 SRA
=
Array[65536] of Byte

The "Save RAM" (SRAM) data, used by cartridges.


SNES9x loads/saves only that much from/to savestates, but otherwise uses 128 KB in the rest of
the program. Maybe just an oversight, or the data for cartridges with larger SRAM chips is
stored elsewhere?

7.6 VRA
=
Array[65536] of Byte

The "video RAM" (VRAM) data, which the SNES stores in two RAM chips.
In this savestate block the even-numbered bytes (0, 2, 4, ...) are from the first memory chip;
the odd-numbered bytes are from the second one. This is also how most other emulators, e.g.
ZSNES, do it. (The exception is Super Sleuth, which stores the content of the two chips in two
separate arrays.)

================================================================================================

8. Structured file blocks

The following block types contain variables, like a Pascal "record" or a C/C++ "struct":
8.01
8.02
8.03
8.04
8.05
8.06
8.07
8.08
8.09
8.10
8.11

APU
ARE
CPU
DMA
PPU
REG
RTC
SA1
SAR
SP7
SOU

(APU status)
(APU registers)
(CPU status)
(DMA/HDMA channels)
(PPU status)
(CPU registers)
(SPC7110 RTC status)
(SA-1 status)
(SA-1 registers)
(SPC7110 status)
(sound data)

Variables consisting of multiple bytes must be stored in big-endian format. (Just for the
record, the x86/Windows platform is little-endian.)

Demo Version - ExpertPDF Software Components


8.1 APU

The status of the audio processing unit.


Cycles
ShowROM
Flags
KeyedChannels
OutPorts
DSP
ExtraRAM
Timer
TimerTarget
TimerEnabled
TimerValueWritten

:
:
:
:
:
:
:
:
:
:
:

DWord
Boolean
Byte
Byte
Array[ 4]
Array[128]
Array[ 64]
Array[ 3]
Array[ 3]
Array[ 3]
Array[ 3]

of
of
of
of
of
of
of

Byte
Byte
Byte
Word
Word
Boolean
Boolean

Multi-byte variables must be stored in big-endian format.

8.2 ARE

The "APU registers", i.e. the registers of the Sony "SPC700" audio processor.
P
YA
X
S
PC

:
:
:
:
:

Byte
Word
Byte
Byte
Word

Multi-byte variables must be stored in big-endian format.

8.3 CPU

The status of the main processor "Ricoh 5A22", which is based on WDC/GTE's "65c816" core.
Flags
BranchSkip

:
:

DWord
Boolean

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 3 / 19

NMIActive
IRQActive
WaitingForInterrupt
WhichEvent
Cycles
NextEvent
V_Counter
MemSpeed
MemSpeedx2
FastROMSpeed

:
:
:
:
:
:
:
:
:
:

Boolean
Boolean
Boolean
Byte
DWord
DWord
DWord
DWord
DWord
DWord

Multi-byte variables must be stored in big-endian format.

8.4 DMA

The "DMA" file block consists of 8 sub-structures, one for each DMA/HDMA channel. They look like
this:
TransferDirection
AAddressFixed
AAddressDecrement
TransferMode
ABank
AAddress
Address
BAddress
TransferBytes
HDMAIndirectAddressing
IndirectAddress
IndirectBank
Repeat
LineCount
FirstLine

:
:
:
:
:
:
:
:
:
:
:
:
:
:
:

Boolean
Boolean
Boolean
Byte
Byte
Word
Word
Byte
Word
Boolean
Word
Byte
Byte
Byte
Byte

Multi-byte variables must be stored in big-endian format.

8.5 PPU

The status of the two PPU (picture-processing unit) chips, and some joypad and mouse data.
BGMode
BG3Priority
Brightness
VMA
BG
CGFLIP
CGDATA
FirstSprite
OBJ
OAMPriorityRotation
OAMAddr
OAMFlip
OAMTileAddress
IRQVBeamPos
IRQHBeamPos
VBeamPosLatched
HBeamPosLatched
HBeamFlip
VBeamFlip
HVBeamCounterLatched
MatrixA
MatrixB
MatrixC
MatrixD
CentreX
CentreY
Joypad1ButtonReadPos
Joypad2ButtonReadPos
Joypad3ButtonReadPos
CGADD
FixedColourRed
FixedColourGreen
FixedColourBlue
SavedOAMAddr
ScreenHeight
WRAM
ForcedBlanking
OBJNameSelect
OBJSizeSelect
OBJNameBase
OAMReadFlip
VTimerEnabled

:
Byte
Demo Version
- ExpertPDF Software Components
:
Boolean
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:

Byte
1 "VMA" structure
4 "BG" structures
Boolean
Array[256] of Word
Byte
128 "OBJ" structures
Boolean
Word
Boolean
Word
Word
Word
Word
Word
Byte
Byte
Boolean
Word
Word
Word
Word
Word
Word
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Word
Word
DWord
Boolean
Word
Byte
Word
Boolean
Boolean

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 4 / 19

HTimerEnabled
HTimerPosition
Mosaic
Mode7HFlip
Mode7VFlip
Mode7Repeat
Window1Left
Window1Right
Window2Left
Window2Right
ClipWindowOverlapLogic
ClipWindow1Enable
ClipWindow2Enable
ClipWindow1Inside
ClipWindow2Inside
CGFLIPRead
Need16x8Mulitply
BGMosaic
OAMData
Need16x8Mulitply_2
MouseSpeed

:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:

Boolean
Word
Byte
Boolean
Boolean
Boolean
Byte
Byte
Byte
Byte
Array[6] of Byte
Array[6] of Boolean
Array[6] of Boolean
Array[6] of Boolean
Array[6] of Boolean
Boolean
Boolean
Array[4] of Boolean
Array[544] of Byte
Boolean
Array[2] of Byte

Multi-byte variables must be stored in big-endian format.

8.6 REG

The registers of the 65c816.


PB
DB
P
A
D
S
X
Y
PC

:
:
:
:
:
:
:
:
:

Byte
Byte
Word
Word
Word
Word
Word
Word
Word

Multi-byte variables must be stored in big-endian format.

8.7 RTC

The status of the SPC7110's real-time clock.

Demo Version - ExpertPDF Software Components

reg
index
control
init
last_used

:
:
:
:
:

Array[16] of Byte
Word
Byte
Boolean
DWord

Multi-byte variables must be stored in big-endian format.

8.8 SA1

The status of the SA-1, which is another "65c816" clocked at 10 MHz.


Flags
NMIActive
IRQActive
WaitingForInterrupt
op1
op2
arithmetic_op
sum
overflow

:
:
:
:
:
:
:
:
:

DWord
Boolean
Boolean
Boolean
Word
Word
DWord
Int64
Boolean

Multi-byte variables must be stored in big-endian format.

8.9 SAR

The SA-1 processor registers.


PB
DB
P
A
D
S

:
:
:
:
:
:

Byte
Byte
Word
Word
Word
Word

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 5 / 19

X
Y
PC

:
:
:

Word
Word
Word

Multi-byte variables must be stored in big-endian format.

8.10 SP7

The status of the "SPC7110", which is a data decompression chip.


reg4800
reg4801
reg4802
reg4803
reg4804
reg4805
reg4806
reg4807
reg4808
reg4809
reg480A
reg480B
reg480C
reg4811
reg4812
reg4813
reg4814
reg4815
reg4816
reg4817
reg4818
reg4820
reg4821
reg4822
reg4823
reg4824
reg4825
reg4826
reg4827
reg4828
reg4829
reg482A
reg482B
reg482C
reg482D
reg482E
reg482F
reg4830
reg4831
reg4832
reg4833
reg4834
reg4840
reg4841
reg4842
AlignBy
written
offset_add
DataRomOffset
DataRomSize
bank50Internal
bank50

:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:

Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
DWord
DWord
DWord
Array[65536] of Byte

Demo Version - ExpertPDF Software Components

Multi-byte variables must be stored in big-endian format.

8.11 SOU

The status of the APU's DSP. On the SNES, these settings are accessed by the SPC700 by writing
to address $00F2 (selects a DSP address) and reading/writing $00F3 (reads/writes a DSP register
value).
master_volume_left
master_volume_right
echo_volume_left
echo_volume_right
echo_enable
echo_feedback
echo_ptr
echo_buffer_size
echo_write_enabled
echo_channel_enable
pitch_mod

:
:
:
:
:
:
:
:
:
:
:

Word
Word
Word
Word
DWord
DWord
DWord
DWord
DWord
DWord
DWord

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 6 / 19

dummy
channel

:
:

Array[3] of DWord
8 "SoundChn" structures

Multi-byte variables must be stored in big-endian format.

================================================================================================

9. Variables

9.1 [APU] Cycles

9.1 [APU] ShowROM

9.1 [APU] Flags

9.1 [APU] KeyedChannels

9.1 [APU] OutPorts

9.1 [APU] DSP

Demo Version - ExpertPDF Software Components

9.1 [APU] ExtraRAM

9.1 [APU] Timer

9.1 [APU] TimerTarget

9.1 [APU] TimerEnabled

9.1 [APU] TimerValueWritten

9.2 [ARE] P

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 7 / 19

9.2 [ARE] YA

9.2 [ARE] X

9.2 [ARE] S

9.2 [ARE] PC

9.3 [CPU] Flags

9.3 [CPU] BranchSkip

9.3 [CPU] NMIActive

9.3 [CPU] IRQActive

9.3 [CPU] WaitingForInterrupt

Demo Version - ExpertPDF Software Components

9.3 [CPU] WhichEvent

9.3 [CPU] Cycles

9.3 [CPU] NextEvent

9.3 [CPU] V_Counter

9.3 [CPU] MemSpeed

9.3 [CPU] MemSpeedx2

9.3 [CPU] FastROMSpeed

9.4 [DMA] TransferDirection

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 8 / 19

9.4 [DMA] AAddressFixed

9.4 [DMA] AAddressDecrement

9.4 [DMA] TransferMode

9.4 [DMA] ABank

9.4 [DMA] AAddress

9.4 [DMA] Address

9.4 [DMA] BAddress

9.4 [DMA] TransferBytes

9.4 [DMA] HDMAIndirectAddressing

Demo Version - ExpertPDF Software Components

9.4 [DMA] IndirectAddress

9.4 [DMA] IndirectBank

9.4 [DMA] Repeat

9.4 [DMA] LineCount

9.4 [DMA] FirstLine

9.5 [PPU] BGMode

9.5 [PPU] BG3Priority

9.5 [PPU] Brightness

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 9 / 19

9.5 [PPU] VMA

9.5 [PPU] BG

9.5 [PPU] CGFLIP

9.5 [PPU] CGDATA

9.5 [PPU] FirstSprite

9.5 [PPU] OBJ

9.5 [PPU] OAMPriorityRotation

9.5 [PPU] OAMAddr

9.5 [PPU] OAMFlip

Demo Version - ExpertPDF Software Components

9.5 [PPU] OAMTileAddress

9.5 [PPU] IRQVBeamPos

9.5 [PPU] IRQHBeamPos

9.5 [PPU] VBeamPosLatched

9.5 [PPU] HBeamPosLatched

9.5 [PPU] HBeamFlip

9.5 [PPU] VBeamFlip

9.5 [PPU] HVBeamCounterLatched

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 10 / 19

9.5 [PPU] MatrixA

9.5 [PPU] MatrixB

9.5 [PPU] MatrixC

9.5 [PPU] MatrixD

9.5 [PPU] CentreX

9.5 [PPU] CentreY

9.5 [PPU] Joypad1ButtonReadPos

9.5 [PPU] Joypad2ButtonReadPos

9.5 [PPU] Joypad3ButtonReadPos

Demo Version - ExpertPDF Software Components

9.5 [PPU] CGADD

9.5 [PPU] FixedColourRed

9.5 [PPU] FixedColourGreen

9.5 [PPU] FixedColourBlue

9.5 [PPU] SavedOAMAddr

9.5 [PPU] ScreenHeight

9.5 [PPU] WRAM

9.5 [PPU] ForcedBlanking

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 11 / 19

9.5 [PPU] OBJNameSelect

9.5 [PPU] OBJSizeSelect

9.5 [PPU] OBJNameBase

9.5 [PPU] OAMReadFlip

9.5 [PPU] VTimerEnabled

9.5 [PPU] HTimerEnabled

9.5 [PPU] HTimerPosition

9.5 [PPU] Mosaic

9.5 [PPU] Mode7HFlip

Demo Version - ExpertPDF Software Components


9.5 [PPU] Mode7VFlip

9.5 [PPU] Mode7Repeat

9.5 [PPU] Window1Left

9.5 [PPU] Window1Right

9.5 [PPU] Window2Left

9.5 [PPU] Window2Right

9.5 [PPU] ClipWindowOverlapLogic

9.5 [PPU] ClipWindow1Enable

9.5 [PPU] ClipWindow2Enable

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 12 / 19

9.5 [PPU] ClipWindow1Inside

9.5 [PPU] ClipWindow2Inside

9.5 [PPU] CGFLIPRead

9.5 [PPU] Need16x8Mulitply

9.5 [PPU] BGMosaic

9.5 [PPU] OAMData

9.5 [PPU] Need16x8Mulitply_2

9.5 [PPU] MouseSpeed

9.6 [REG] PB

Demo Version - ExpertPDF Software Components

9.6 [REG] DB

9.6 [REG] P

9.6 [REG] A

9.6 [REG] D

9.6 [REG] S

9.6 [REG] X

9.6 [REG] Y

9.6 [REG] PC

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 13 / 19

9.7 [RTC] reg

9.7 [RTC] index

9.7 [RTC] control

9.7 [RTC] init

9.7 [RTC] last_used

9.8 [SA1] Flags

9.8 [SA1] NMIActive

9.8 [SA1] IRQActive

9.8 [SA1] WaitingForInterrupt

Demo Version - ExpertPDF Software Components

9.8 [SA1] op1

9.8 [SA1] op2

9.8 [SA1] arithmetic_op

9.8 [SA1] sum

9.8 [SA1] overflow

9.9 [SAR] PB

9.9 [SAR] DB

9.9 [SAR] P

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 14 / 19

9.9 [SAR] A

9.9 [SAR] D

9.9 [SAR] S

9.9 [SAR] X

9.9 [SAR] Y

9.9 [SAR] PC

9.10 [SP7] reg4800

9.10 [SP7] reg4801

9.10 [SP7] reg4802

Demo Version - ExpertPDF Software Components

9.10 [SP7] reg4803

9.10 [SP7] reg4804

9.10 [SP7] reg4805

9.10 [SP7] reg4806

9.10 [SP7] reg4807

9.10 [SP7] reg4808

9.10 [SP7] reg4809

9.10 [SP7] reg480A

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 15 / 19

9.10 [SP7] reg480B

9.10 [SP7] reg480C

9.10 [SP7] reg4811

9.10 [SP7] reg4812

9.10 [SP7] reg4813

9.10 [SP7] reg4814

9.10 [SP7] reg4815

9.10 [SP7] reg4816

9.10 [SP7] reg4817

Demo Version - ExpertPDF Software Components


9.10 [SP7] reg4818

9.10 [SP7] reg4820

9.10 [SP7] reg4821

9.10 [SP7] reg4822

9.10 [SP7] reg4823

9.10 [SP7] reg4824

9.10 [SP7] reg4825

9.10 [SP7] reg4826

9.10 [SP7] reg4827

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 16 / 19

9.10 [SP7] reg4828

9.10 [SP7] reg4829

9.10 [SP7] reg482A

9.10 [SP7] reg482B

9.10 [SP7] reg482C

9.10 [SP7] reg482D

9.10 [SP7] reg482E

9.10 [SP7] reg482F

9.10 [SP7] reg4830

Demo Version - ExpertPDF Software Components

9.10 [SP7] reg4831

9.10 [SP7] reg4832

9.10 [SP7] reg4833

9.10 [SP7] reg4834

9.10 [SP7] reg4840

9.10 [SP7] reg4841

9.10 [SP7] reg4842

9.10 [SP7] AlignBy

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 17 / 19

9.10 [SP7] written

9.10 [SP7] offset_add

9.10 [SP7] DataRomOffset

9.10 [SP7] DataRomSize

9.10 [SP7] bank50Internal

9.10 [SP7] bank50

9.11 [SOU] master_volume_left

9.11 [SOU] master_volume_right

9.11 [SOU] echo_volume_left

Demo Version - ExpertPDF Software Components

9.11 [SOU] echo_volume_right

9.11 [SOU] echo_enable

9.11 [SOU] echo_feedback

9.11 [SOU] echo_ptr

9.11 [SOU] echo_buffer_size

9.11 [SOU] echo_write_enabled

9.11 [SOU] echo_channel_enable

9.11 [SOU] pitch_mod

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 18 / 19

9.11 [SOU] dummy

9.11 [SOU] channel

Demo Version - ExpertPDF Software Components

0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF

Sample footer: http://vsnes.aep-emu.de/SNES9x savestate file format.htm. You can change color, font and other options

Page 19 / 19

You might also like