FCEU allows for outputting Video/Audio into .avi files or capturing audio only into .wav files. This can be used to capture one's playing or for dumping movie files (.fm2) to .avi files.
-
-
-
Capturing a Movie File (.fm2) to Video/Audio (AVI)
-
-
-Pause the emulator by navigating to NES > Emulation Speed > pause or pressing the pause hotkey (the pause key by default).
-
-For a faster capture increase emulation speed (you can capture at any emulation speed and FCEUX will still output a 60 (or 50) fps video file).
-
-Select "Replay Movie" from the File > Movie Menu and select the movie file
-
-If you intend to capture beyond the final frame of the movie file, make sure "Pause after Playback" (Config Menu) is not checked.
-
-Select "Record AVI" in the File > AVI/Wav menu.
-
-Select a file location and the video codec you wish to use.
-
-Unpause the emulator.
-
-When capturing is complete, pause the emulator and select "Stop AVI" in the File Menu.
-
-
-
Capture Audio only
-
-
To capture audio only, navigate to File > AVI/Wav > Record WAV. Pick a filename and destination for FCEUX to begin capturing the audio to a .wav file (raw .pcm). To stop WAV recording, select File > AVI/Wav > Stop WAV.
FCEU allows for outputting Video/Audio into .avi files or capturing audio only into .wav files. This can be used to capture one's playing or for dumping movie files (.fm2) to .avi files.
+
+
+
Capturing a Movie File (.fm2) to Video/Audio (AVI)
+
+
-Pause the emulator by navigating to NES > Emulation Speed > pause or pressing the pause hotkey (the pause key by default).
+
-For a faster capture increase emulation speed (you can capture at any emulation speed and FCEUX will still output a 60 (or 50) fps video file).
+
-Select "Replay Movie" from the File > Movie Menu and select the movie file
+
-If you intend to capture beyond the final frame of the movie file, make sure "Pause after Playback" (Config Menu) is not checked.
+
-Select "Record AVI" in the File > AVI/Wav menu.
+
-Select a file location and the video codec you wish to use.
+
-Unpause the emulator.
+
-When capturing is complete, pause the emulator and select "Stop AVI" in the File Menu.
+
+
+
Capture Audio only
+
+
To capture audio only, navigate to File > AVI/Wav > Record WAV. Pick a filename and destination for FCEUX to begin capturing the audio to a .wav file (raw .pcm). To stop WAV recording, select File > AVI/Wav > Stop WAV.
The default configuration for an auto fire key is the alteration of on/off/on/off every frame. For most games this works nicely, but there are situations where this doesn't work properly. For example, Double Dragon 2 and Teenage Mutant Ninja Turtles run at 30fps (screen updates every other frame). To use autofire in these types of games, you would want to set the autofire pattern to 2 on / 2 off. In a situation where a players weapon on fires every 4th frame, you can set the autofire pattern to 1 on / 3 off.
-
-
Autofire Offset
-
-
The default is for certain frames to have the on setting and others to have the off setting. For instance, "on" might be lined up with a movie file's even numbers. But a situation may need the autofire pattern to have "on" on the odd numbers instead. In this case the autofire offset should be set to 1. This will delay the normal "on" fire by 1 frame. If an autofire pattern is set to 2 on / 2 off, an autofire offset of 2 might be necessary.
-
-
Alternate A and B
-
-
Alternate A and B is for a specific case where both the A and B autofire buttons are pressed simultaneously. With alternate A and B, the fire pattern will be A,B,A,B rather than A+B, off, A+B, off.
-
-
-
Note: All autofire patterns read the Lag Counter (see display) and skip over any frames where input is not polled. This means that in a laggy area, the autofire pattern will not be affected.
The default configuration for an auto fire key is the alteration of on/off/on/off every frame. For most games this works nicely, but there are situations where this doesn't work properly. For example, Double Dragon 2 and Teenage Mutant Ninja Turtles run at 30fps (screen updates every other frame). To use autofire in these types of games, you would want to set the autofire pattern to 2 on / 2 off. In a situation where a players weapon on fires every 4th frame, you can set the autofire pattern to 1 on / 3 off.
+
+
Autofire Offset
+
+
The default is for certain frames to have the on setting and others to have the off setting. For instance, "on" might be lined up with a movie file's even numbers. But a situation may need the autofire pattern to have "on" on the odd numbers instead. In this case the autofire offset should be set to 1. This will delay the normal "on" fire by 1 frame. If an autofire pattern is set to 2 on / 2 off, an autofire offset of 2 might be necessary.
+
+
Alternate A and B
+
+
Alternate A and B is for a specific case where both the A and B autofire buttons are pressed simultaneously. With alternate A and B, the fire pattern will be A,B,A,B rather than A+B, off, A+B, off.
+
+
+
Note: All autofire patterns read the Lag Counter (see display) and skip over any frames where input is not polled. This means that in a laggy area, the autofire pattern will not be affected.
FCE Ultra allows cheating by the periodic "patching" of arbitrary addresses in the 6502's memory space with arbitrary values, as well as read substitution. "Read substitution" is the method that would be used on a real NES/Famicom, such as done by the Game Genie and Pro Action Replay. It is required to support GG and PAR codes, but since it is relatively slow when done in emulation, it is not the preferred method when a RAM patch will suffice. Also, in FCE Ultra, read substitution will not work properly with zero-page addressing modes(instructions that operate on RAM at $0000 through $00FF).
-
-
The RAM patches are all applied a short time before the emulated vertical blanking period. This detail shouldn't concern most people, though. However, this does mean that cheating with games that use bank-switched RAM may be problematic. Fortunately, such games are not very common (in relation to the total number of NES and Famicom games).
-
-
The cheat search comes with its own set of tools for finding addresses in memory to use for making cheats (or for monitoring the addresses in the memory watch window)
-
-
Cheat Files
-
-
By default cheat files (.cht) are stored in the "cheats" subdirectory under the base FCEUX. The files are in a simple plain-text format. Each line represents a one-byte memory patch. The format is as follows(text in brackets [] represents optional parameters):
A colon(:) near the beginning of the line is used to disable the cheat. "S" denotes a cheat that is a read-substitute-style cheat(such as with Game Genie cheats), and a "C" denotes that the cheat has a compare value.
-
-
Note: When a game is loaded, FCEUX will load any accompanying saved .cht file automatically.
The cheat search interface consists of several components: a list of addresses and associated data for a search, several command buttons, and the search parameters.
-
-
All addresses listed in the cheat search windows are in unsigned 16-bit hexadecimal format and all values in these windows are in an unsigned 8-bit decimal format(the range for values is 0 through 255).
-
-
Active Cheats
-
-
The Active cheats window on the left contains the list of cheats for the currently loaded game. Existing cheats can be selected, edited, and updated using the "Update" button.
-
-
Each entry in the list can be named. If you didn't provide a name, it will be automatically named using this format:
-
For simple "Substitute" type of cheats: * Address:Value
-
For "Compare" type of cheats: * Address?Compare:Value
-
-
The "Address" is the location in the 6502's address space. The * denotes that the current cheat is active (double clicking will toggle on/off). "Value" is the value (in hex) that is written to the addresses on each update. "Compare" it the value that must be at the address, or else the Value won't be written there. This allows making cheats more safe.
-
-
You can Add, Delete, and Update cheats in the Active Cheats window with the boxes below.
-
You can use "Add from CHT file..." button to load cheats from an existing file (in case the file name does not match the ROM name, so it didn't load automatically). Alternatively, you can drag and drop any .cht file into the FCEUX window.
-
-
There is also a right-click menu with the options Toggle selected Cheats, Poke Cheat Value and Goto in Hex Editor, and Delete selected Cheats.
-
-
Toggle Cheats is like Double Clicking, it enables or disables the cheat code. You can select many cheats in the list and toggle them all at once.
-
Poke Cheat Value is like turning the cheat on, but in this case there's no off switch. If the code is on when you use this, then when the code is turned off, it will revert to the value last used. Good for one time life refills, if you want that sort of thing.
-
Goto in Hex Editor opens the Hex Editor window, and puts the cursor on the address shown. It's somewhat similar to how Bookmarks work in the Hex Editor.
-
-
To create a new cheat, you have to find an address, for this use the cheat search portion of the window.
-
-
-
Cheat Search
-
-
The cheat search is used to find a specific value in the games RAM by process of elimination.
-
-
The possibilities window is in the format of Address:Original Value:Current Value
-
The address is the location in the 6502's address space, the original value is the value that was stored at this address when the search was reset, and the current value is the value that is currently stored at that address. Selecting an item in this list will automatically cause the "Address" field in the cheat information box on the right side of the window to be updated with the selected address.
-
-
The "Reset" button resets the search process; all valid addresses are displayed in the possibilities window and the data values at those addresses noted in both the left and right columns. The number of possibilities is displayed at the top. Resetting will set it to 2048 or 10240 depending on if the game uses "On cartridge ram" ($6000-$7FFF). (See NES RAM)
-
-
The left column is the "previous value" and the right column is the "current value"
-
-
The "Known Value", "Equal", "Not Equal", Greater than" and Less than" buttons perform a search based on the search parameter and removes any non-matching addresses from the address list. It then sets the "previous value" column to the contents of the "current value"
-
-
"Known Value" will search for all addresses that match the value in the box to the right (the value is in hex).
-
-
"Equal" will search for all addresses that have the same value now as the last search (or since reset was pressed, if there has not yet been a search).
-
-
"Not equal" will search for all addresses that have changed sine the last search (or since reset was pressed, if there has not yet been a search).
-
If the checkbox next to it is checked it will looks for values that have changed by the value in the number box to the right. For instance, if it is checked and the number is 5, it will search for all values that are +- 5 from the previous value.
-
-
"Greater than" functions like "Not equal" except it only searches for values that have increased since the last search.
-
-
"Less than" functions like "Not equal" except it only searches for values that have decreased since the last search.
-
-
Using the Results
-
-
Any value in the possibilities list can be sent to memory watch by double clicking it.
-
Highlighting it and hitting the "Add" button under the Active cheats window will automatically activate it as a cheat with the value set to its current value.
-
-
Example
-
-
Here is an example of cheat search in action.
-
-
Let's say I am playing Mega man 3 and I want to find Mega man's energy level in the game's ram. I will start by opening the ROM and selecting a level. At this point, I know Mega man's energy address is active. So I will pause the game and open the cheat search and hit the reset button. The game uses SRAM so the possibilities window will say 10240 "possibilities".
-
Next I will frame advance (or briefly unpause) the game. At this point I know Mega man's energy level is still the same as it was. So I click the "equal" button. Next I want to take damage. I know for sure now that the energy level has decreased so after the "ouch" animation, I click the "Less than button". This will cut the possibilities down significantly. Next I will advance some more and click the "Equal" button since I know the value is still the previous value. I will repeat this cycle until I am down to 1 or just a few values. From there I can double click the values to send them to memory watch to monitor them more closely to weed them out. (Note: Mega man's energy is located in $00A2).
-
-
Context Menu
-
-
Right-clicking in the active cheats list brings up the context menu.
-
-
Toggle Cheat - does the same thing as double clicking
-
-
Poke cheat value - has a different affect that normal freezing, this makes a one time write of that value as opposed to freezing it temporarily to that value and having it restored later. It has the same affect as typing in values in the Hex Editor.
-
-
Goto In Hex Editor - Opens the Hex editor dialog to the position of the selected RAM value.
FCE Ultra allows cheating by the periodic "patching" of arbitrary addresses in the 6502's memory space with arbitrary values, as well as read substitution. "Read substitution" is the method that would be used on a real NES/Famicom, such as done by the Game Genie and Pro Action Replay. It is required to support GG and PAR codes, but since it is relatively slow when done in emulation, it is not the preferred method when a RAM patch will suffice. Also, in FCE Ultra, read substitution will not work properly with zero-page addressing modes(instructions that operate on RAM at $0000 through $00FF).
+
+
The RAM patches are all applied a short time before the emulated vertical blanking period. This detail shouldn't concern most people, though. However, this does mean that cheating with games that use bank-switched RAM may be problematic. Fortunately, such games are not very common (in relation to the total number of NES and Famicom games).
+
+
The cheat search comes with its own set of tools for finding addresses in memory to use for making cheats (or for monitoring the addresses in the memory watch window)
+
+
Cheat Files
+
+
By default cheat files (.cht) are stored in the "cheats" subdirectory under the base FCEUX. The files are in a simple plain-text format. Each line represents a one-byte memory patch. The format is as follows(text in brackets [] represents optional parameters):
A colon(:) near the beginning of the line is used to disable the cheat. "S" denotes a cheat that is a read-substitute-style cheat(such as with Game Genie cheats), and a "C" denotes that the cheat has a compare value.
+
+
Note: When a game is loaded, FCEUX will load any accompanying saved .cht file automatically.
The cheat search interface consists of several components: a list of addresses and associated data for a search, several command buttons, and the search parameters.
+
+
All addresses listed in the cheat search windows are in unsigned 16-bit hexadecimal format and all values in these windows are in an unsigned 8-bit decimal format(the range for values is 0 through 255).
+
+
Active Cheats
+
+
The Active cheats window on the left contains the list of cheats for the currently loaded game. Existing cheats can be selected, edited, and updated using the "Update" button.
+
+
Each entry in the list can be named. If you didn't provide a name, it will be automatically named using this format:
+
For simple "Substitute" type of cheats: * Address:Value
+
For "Compare" type of cheats: * Address?Compare:Value
+
+
The "Address" is the location in the 6502's address space. The * denotes that the current cheat is active (double clicking will toggle on/off). "Value" is the value (in hex) that is written to the addresses on each update. "Compare" it the value that must be at the address, or else the Value won't be written there. This allows making cheats more safe.
+
+
You can Add, Delete, and Update cheats in the Active Cheats window with the boxes below.
+
You can use "Add from CHT file..." button to load cheats from an existing file (in case the file name does not match the ROM name, so it didn't load automatically). Alternatively, you can drag and drop any .cht file into the FCEUX window.
+
+
There is also a right-click menu with the options Toggle selected Cheats, Poke Cheat Value and Goto in Hex Editor, and Delete selected Cheats.
+
+
Toggle Cheats is like Double Clicking, it enables or disables the cheat code. You can select many cheats in the list and toggle them all at once.
+
Poke Cheat Value is like turning the cheat on, but in this case there's no off switch. If the code is on when you use this, then when the code is turned off, it will revert to the value last used. Good for one time life refills, if you want that sort of thing.
+
Goto in Hex Editor opens the Hex Editor window, and puts the cursor on the address shown. It's somewhat similar to how Bookmarks work in the Hex Editor.
+
+
To create a new cheat, you have to find an address, for this use the cheat search portion of the window.
+
+
+
Cheat Search
+
+
The cheat search is used to find a specific value in the games RAM by process of elimination.
+
+
The possibilities window is in the format of Address:Original Value:Current Value
+
The address is the location in the 6502's address space, the original value is the value that was stored at this address when the search was reset, and the current value is the value that is currently stored at that address. Selecting an item in this list will automatically cause the "Address" field in the cheat information box on the right side of the window to be updated with the selected address.
+
+
The "Reset" button resets the search process; all valid addresses are displayed in the possibilities window and the data values at those addresses noted in both the left and right columns. The number of possibilities is displayed at the top. Resetting will set it to 2048 or 10240 depending on if the game uses "On cartridge ram" ($6000-$7FFF). (See NES RAM)
+
+
The left column is the "previous value" and the right column is the "current value"
+
+
The "Known Value", "Equal", "Not Equal", Greater than" and Less than" buttons perform a search based on the search parameter and removes any non-matching addresses from the address list. It then sets the "previous value" column to the contents of the "current value"
+
+
"Known Value" will search for all addresses that match the value in the box to the right (the value is in hex).
+
+
"Equal" will search for all addresses that have the same value now as the last search (or since reset was pressed, if there has not yet been a search).
+
+
"Not equal" will search for all addresses that have changed sine the last search (or since reset was pressed, if there has not yet been a search).
+
If the checkbox next to it is checked it will looks for values that have changed by the value in the number box to the right. For instance, if it is checked and the number is 5, it will search for all values that are +- 5 from the previous value.
+
+
"Greater than" functions like "Not equal" except it only searches for values that have increased since the last search.
+
+
"Less than" functions like "Not equal" except it only searches for values that have decreased since the last search.
+
+
Using the Results
+
+
Any value in the possibilities list can be sent to memory watch by double clicking it.
+
Highlighting it and hitting the "Add" button under the Active cheats window will automatically activate it as a cheat with the value set to its current value.
+
+
Example
+
+
Here is an example of cheat search in action.
+
+
Let's say I am playing Mega man 3 and I want to find Mega man's energy level in the game's ram. I will start by opening the ROM and selecting a level. At this point, I know Mega man's energy address is active. So I will pause the game and open the cheat search and hit the reset button. The game uses SRAM so the possibilities window will say 10240 "possibilities".
+
Next I will frame advance (or briefly unpause) the game. At this point I know Mega man's energy level is still the same as it was. So I click the "equal" button. Next I want to take damage. I know for sure now that the energy level has decreased so after the "ouch" animation, I click the "Less than button". This will cut the possibilities down significantly. Next I will advance some more and click the "Equal" button since I know the value is still the previous value. I will repeat this cycle until I am down to 1 or just a few values. From there I can double click the values to send them to memory watch to monitor them more closely to weed them out. (Note: Mega man's energy is located in $00A2).
+
+
Context Menu
+
+
Right-clicking in the active cheats list brings up the context menu.
+
+
Toggle Cheat - does the same thing as double clicking
+
+
Poke cheat value - has a different affect that normal freezing, this makes a one time write of that value as opposed to freezing it temporarily to that value and having it restored later. It has the same affect as typing in values in the Hex Editor.
+
+
Goto In Hex Editor - Opens the Hex editor dialog to the position of the selected RAM value.
The Code/Data Logger makes it much easier to reverse-engineer NES ROMs. The basic idea behind it is that a normal NES disassembler cannot distinguish between code (which is executed) and data (which is read). The Code/Data Logger keeps track of what is executed and what is read while the game is played, and then you can save this information into a .cdl file, which is essentially a mask that tells which bytes in the ROM are code and which are data. The file can be used in conjunction with a suitable disassembler to disassemble only the actual game code, resulting in a much cleaner source code where code and data are properly separated.
-
-
Using the Code/Data Logger
-
-
The Code/Data Logger keeps track of every byte in the ROM and records whether it's code (is executed) or data (is read).
-
You can combine this logging feature with other tools to make them much more powerful:
-
-
combine with Debugger to see which branches of the game code were executed and which weren't yet
-
combine with Trace Logger to let it log the code selectively
-
combine with PPU Viewer to let it only display graphics that was drawn on screen at least once
-
combine with Hex Editor to enable smart coloring of bytes (so you can observe which bytes are used by the game and how/when they are used)
-
combine with (an external) Tile Viewer to see which graphics was used during certain play session, and which was not
-
combine with (an external) ROM Corruptor to make it only corrupt data, but not code
-
combine with (an external) Disassembler to help it separate code from data
+
Code/Data Logger
+
+
+
Introduction
+
+
The Code/Data Logger makes it much easier to reverse-engineer NES ROMs. The basic idea behind it is that a normal NES disassembler cannot distinguish between code (which is executed) and data (which is read). The Code/Data Logger keeps track of what is executed and what is read while the game is played, and then you can save this information into a .cdl file, which is essentially a mask that tells which bytes in the ROM are code and which are data. The file can be used in conjunction with a suitable disassembler to disassemble only the actual game code, resulting in a much cleaner source code where code and data are properly separated.
+
+
Using the Code/Data Logger
+
+
The Code/Data Logger keeps track of every byte in the ROM and records whether it's code (is executed) or data (is read).
+
You can combine this logging feature with other tools to make them much more powerful:
+
+
combine with Debugger to see which branches of the game code were executed and which weren't yet
+
combine with Trace Logger to let it log the code selectively
+
combine with PPU Viewer to let it only display graphics that was drawn on screen at least once
+
combine with Hex Editor to enable smart coloring of bytes (so you can observe which bytes are used by the game and how/when they are used)
+
combine with (an external) Tile Viewer to see which graphics was used during certain play session, and which was not
+
combine with (an external) ROM Corruptor to make it only corrupt data, but not code
+
combine with (an external) Disassembler to help it separate code from data
-
-
See, it is very useful for finding certain types of data or code branches. It also makes debugging work more visual, since you can always see which lines of the disassembled code were executed and which weren't.
-
-
Furthermore, while the Code/Data Logger is running, the Hex Editor will color-code ROM bytes depending on whether they were logged as code or data:
-
-
For PRG ROM:
-
Dark-yellow - the byte is code
-
Blue - the byte is data
-
Cyan - the byte is PCM audio data
-
Green - the byte is both code and data
-
-
For CHR ROM:
-
Yellow - the byte was rendered
-
Light-blue - the byte was read programmatically
-
Light-green - the byte was both rendered and read programmatically
-
-
The Code/Data Logger can also be used to generate a stripped NES ROM.
-
"Stripped" NES ROM is a ROM in which everything that was not logged by the Code/Data Logger is removed. It can be useful in many ways, for example, you can view the ROM in an external Hex Editor or a Tile Viewer, and you'll see only the parts that were used while playing. Furthermore, you could use it to create a demo ROM by only playing through the parts you would like others to see.
-
Example of such usage:
-
1. Open the Code/Data Logger, and press Start to begin logging.
-
2. Perform a soft and a hard reset while logging, in order to capture the ROM's startup sequence. If you don't do so, you can distribute a save-state file so they will start from within the game.
-
3. If the game has Save-RAM (e.g. Zelda), you will need to capture the game's Save-RAM initialization routines; you can try to do so by deleting the game's *.sav file and then perform a soft and hard reset again while logging.
-
4. Play through whatever levels you want present in the demo ROM. Be sure to perform every move, get every item, etc., so that the code and data necessary for those things are logged. If, for example, you fail to perform some special move, and then someone plays the stripped ROM and attempts to perform that move, the game may very well crash or glitch up, because there are zeros in the stripped ROM instead of the code responsible for handling this special move.
-
5. Save the stripped NES ROM.
-
-
Alternatively, you can save Unused Data (a ROM which is the opposite to the Stripped ROM). For example, you can play through the game, then save Unused Data ROM and watch it in a Tile Viewer to find unused graphics (possibly stumble upon secrets and easter eggs).
-
-
Note: When you "Load" another .cdl file, it does not clear the current log; instead, it combines ("arithmetical OR") it with the information in the file. This can be useful if you're trying to obtain a complete log of certain game, as multiple people can play through the game and keep own code/data logs, and then the results can be combined into an all-encompassing log. But if you would like to actually clear the code/data log, press the "Reset Log" button.
-
-
-
-
CDL files are just a mask of the ROM; that is, they are of the same size as the ROM, and each byte represents the corresponding byte of the ROM. The format of each byte is like so (in binary):
-
-
For PRG ROM:
-
-
-
x
-
-
P
-
-
d
-
-
c
-
-
A
-
-
A
-
-
D
-
-
C
-
-
+
+
See, it is very useful for finding certain types of data or code branches. It also makes debugging work more visual, since you can always see which lines of the disassembled code were executed and which weren't.
+
+
Furthermore, while the Code/Data Logger is running, the Hex Editor will color-code ROM bytes depending on whether they were logged as code or data:
+
+
For PRG ROM:
+
Dark-yellow - the byte is code
+
Blue - the byte is data
+
Cyan - the byte is PCM audio data
+
Green - the byte is both code and data
+
+
For CHR ROM:
+
Yellow - the byte was rendered
+
Light-blue - the byte was read programmatically
+
Light-green - the byte was both rendered and read programmatically
+
+
The Code/Data Logger can also be used to generate a stripped NES ROM.
+
"Stripped" NES ROM is a ROM in which everything that was not logged by the Code/Data Logger is removed. It can be useful in many ways, for example, you can view the ROM in an external Hex Editor or a Tile Viewer, and you'll see only the parts that were used while playing. Furthermore, you could use it to create a demo ROM by only playing through the parts you would like others to see.
+
Example of such usage:
+
1. Open the Code/Data Logger, and press Start to begin logging.
+
2. Perform a soft and a hard reset while logging, in order to capture the ROM's startup sequence. If you don't do so, you can distribute a save-state file so they will start from within the game.
+
3. If the game has Save-RAM (e.g. Zelda), you will need to capture the game's Save-RAM initialization routines; you can try to do so by deleting the game's *.sav file and then perform a soft and hard reset again while logging.
+
4. Play through whatever levels you want present in the demo ROM. Be sure to perform every move, get every item, etc., so that the code and data necessary for those things are logged. If, for example, you fail to perform some special move, and then someone plays the stripped ROM and attempts to perform that move, the game may very well crash or glitch up, because there are zeros in the stripped ROM instead of the code responsible for handling this special move.
+
5. Save the stripped NES ROM.
+
+
Alternatively, you can save Unused Data (a ROM which is the opposite to the Stripped ROM). For example, you can play through the game, then save Unused Data ROM and watch it in a Tile Viewer to find unused graphics (possibly stumble upon secrets and easter eggs).
+
+
Note: When you "Load" another .cdl file, it does not clear the current log; instead, it combines ("arithmetical OR") it with the information in the file. This can be useful if you're trying to obtain a complete log of certain game, as multiple people can play through the game and keep own code/data logs, and then the results can be combined into an all-encompassing log. But if you would like to actually clear the code/data log, press the "Reset Log" button.
+
+
+
+
CDL files are just a mask of the ROM; that is, they are of the same size as the ROM, and each byte represents the corresponding byte of the ROM. The format of each byte is like so (in binary):
+
+
For PRG ROM:
+
+
+
+
+
x
+
+
+
P
+
+
+
d
+
+
+
c
+
+
+
A
+
+
+
A
+
+
+
D
+
+
+
C
+
+
-
-
C = Whether it was accessed as code.
-
D = Whether it was accessed as data.
-
AA = Into which ROM bank it was mapped when last accessed:
-
00 = $8000-$9FFF 01 = $A000-$BFFF
-
10 = $C000-$DFFF 11 = $E000-$FFFF
-
c = Whether indirectly accessed as code.
-
(e.g. as the destination of a JMP ($nnnn) instruction)
-
d = Whether indirectly accessed as data.
-
(e.g. as the destination of an LDA ($nn),Y instruction)
-
P = If logged as PCM audio data.
-
x = unused.
-
-
For CHR ROM:
-
-
-
x
-
-
x
-
-
x
-
-
x
-
-
x
-
-
x
-
-
R
-
-
D
-
-
+
+
C = Whether it was accessed as code.
+
D = Whether it was accessed as data.
+
AA = Into which ROM bank it was mapped when last accessed:
+
00 = $8000-$9FFF01 = $A000-$BFFF
+
10 = $C000-$DFFF11 = $E000-$FFFF
+
c = Whether indirectly accessed as code.
+
(e.g. as the destination of a JMP ($nnnn) instruction)
+
d = Whether indirectly accessed as data.
+
(e.g. as the destination of an LDA ($nn),Y instruction)
+
P = If logged as PCM audio data.
+
x = unused.
+
+
For CHR ROM:
+
+
+
+
+
x
+
+
+
x
+
+
+
x
+
+
+
x
+
+
+
x
+
+
+
x
+
+
+
R
+
+
+
D
+
+
-
-
D = Whether it was drawn on screen (rendered by PPU at runtime)
-
R = Whether it was read programmatically using port $2007
-
(e.g. Argus_(J).nes checks if the bankswitching works by reading the same byte of CHR data before and after switching)
-
x = unused.
-
-
-
-
-
CDL files make possible a number of things never done before. First, a PCM data ripper could be created that scans for data that has the 'P' bit set, in order to find/rip/play every PCM sample in a ROM. Also, it is possible for someone to make a more intelligent ROM corruptor that only corrupts data (by checking the 'D' bit). In any case, the Code/Data Logger opens many new possibilities for discovering useful things in games. Another interesting possibility would be to use the Code/Data Logger on an NSF file to create a stripped NSF. Such an NSF would contain nothing but the relevant subroutines and data required by each tune played; this would be helpful to NSF rippers by removing irrelevant information. Thus, an NSF ripper could create a stripped NSF by listening to each track while the Code/Data Logger operates on it, and then saving the stripped NSF. It should be noted that this capability, though tested and working on private builds, is detrimental to the process of fixing broken NSF files. For this reason, data logging is allowed for NSF files, but stripping NSF files of unused data is disabled.
-
-
The Code/Data Logger becomes the most useful when you need to restore a full source code of a game using e.g. IDA or another disassembler. There you can write a custom IDC script that uses a CDL file and calls MakeCode()/MakeData() functions to help the disassembler distinguish code from data. Making full and working/reassemblable disassembly becomes really easy this way.
-
-
-
-
-
+
+
D = Whether it was drawn on screen (rendered by PPU at runtime)
+
R = Whether it was read programmatically using port $2007
+
(e.g. Argus_(J).nes checks if the bankswitching works by reading the same byte of CHR data before and after switching)
+
x = unused.
+
+
+
+
+
CDL files make possible a number of things never done before. First, a PCM data ripper could be created that scans for data that has the 'P' bit set, in order to find/rip/play every PCM sample in a ROM. Also, it is possible for someone to make a more intelligent ROM corruptor that only corrupts data (by checking the 'D' bit). In any case, the Code/Data Logger opens many new possibilities for discovering useful things in games. Another interesting possibility would be to use the Code/Data Logger on an NSF file to create a stripped NSF. Such an NSF would contain nothing but the relevant subroutines and data required by each tune played; this would be helpful to NSF rippers by removing irrelevant information. Thus, an NSF ripper could create a stripped NSF by listening to each track while the Code/Data Logger operates on it, and then saving the stripped NSF. It should be noted that this capability, though tested and working on private builds, is detrimental to the process of fixing broken NSF files. For this reason, data logging is allowed for NSF files, but stripping NSF files of unused data is disabled.
+
+
The Code/Data Logger becomes the most useful when you need to restore a full source code of a game using e.g. IDA or another disassembler. There you can write a custom IDC script that uses a CDL file and calls MakeCode()/MakeData() functions to help the disassembler distinguish code from data. Making full and working/reassemblable disassembly becomes really easy this way.
Plays specified ROM (ROM name must always be put last in command line arguments)
-
-
fceux path\rom.nes (or rom.zip)
-
-
fceux smb.nes
-
fceux c:\fceux\roms\smb.zip
-
-
-
Play Movie File
-
Plays a specified movie (.fm2) file. A valid ROM must be specified or movie will not be played.
-
-
fcuex -playmovie path\movie.fm2 romname
-
-
fceux -playmovie smb.fm2 smb.nes
-
-
-
Read-only Status
-
Specifies whether a movie will be in "read-only" or "read & write" mode. (Note: a specified movie is not required to be used in conjunction with this command). 1 specifies read only status, 0 specifies read & write.
Plays specified ROM (ROM name must always be put last in command line arguments)
+
+
fceux path\rom.nes (or rom.zip)
+
+
fceux smb.nes
+
fceux c:\fceux\roms\smb.zip
+
+
+
Play Movie File
+
Plays a specified movie (.fm2) file. A valid ROM must be specified or movie will not be played.
+
+
fcuex -playmovie path\movie.fm2 romname
+
+
fceux -playmovie smb.fm2 smb.nes
+
+
+
Read-only Status
+
Specifies whether a movie will be in "read-only" or "read & write" mode. (Note: a specified movie is not required to be used in conjunction with this command). 1 specifies read only status, 0 specifies read & write.
Lua is a scripting language. It is used in games like Farcry and World of Warcraft (and many other games and applications!). Even though you can find all kinds of tutorials online, let me help you with the basics.
-
-
I will assume you are at least somewhat familiar with the basics of programming. So basic stuff like arrays, variables, strings, loops and if-then-else and branching are not explained here.
-
-
A hello world EmuLua program looks like this:
-
-
while (true) do
-
gui.text(50,50,"Hello world!");
-
emu.frameadvance();
-
end;
-
-
When you load the script, the emulator will sort of go into pause mode and hand controls over to Lua (you!). Hence you are responsible for frameadvancing the emulator.
-
IF YOU DO NOT CALL emu.frameadvance AT THE CYCLE OF THE MAIN LOOP YOU WILL FREEZE THE EMULATOR! There. You have been warned. Don't worry though, you'll make this mistake at least once. Just force-quit the application and try again :)
-
-
Syntax
-
-
Now then. Just like any other language, Lua has a few quirks you should be aware of.
-
-
First of all, if's require a then and end. After a couple of days intensive Lua coding, I still make this mistake myself, but the Lua interpreter will prompt you of such errors on load, so don't worry too much about it. So:
-
-
if (something) then
-
dostuff
-
end;
-
-
Lua uses nil instead of null.
-
-
There are only two values that evaluate to "false", these are "nil" and "false". ANYTHING else will evaluate to true, even 0 or the empty string.
-
-
Comments are denoted by two consecutive dashes; --. Anything after it on the same line is a comment and ignored by Lua. There is no /* */ type of commenting in Lua.
-
-
Variables have a local and global scope. You explicitly make a variable local by declaring it with the "local" keyword.
-
-
somethingglobal; -- accessible by any function or flow
-
local something; -- only known to the same or deeper scope as where it was declared
-
-
Note that variables declared in for loops (see below) are always considered local.
-
-
Arrays are called tables in Lua. To be more precise, Lua uses associative arrays.
-
-
Do not rely on the table.length() when your table can contain nil values, this function stops when it encounters a nil value, thus possibly cutting your table short.
-
-
One experienced programmers will have to get used to is the table offset; tables start at index 1, not 0. That's just the way it is, deal with it.
-
-
There are a few ways to create a table:
-
-
local tbl1 = {}; -- empty table
-
local tbl2 = {"a","b","c","d"}; -- table with 5 strings
-
local tbl3 = {a=1,b=2,c=3}; -- associative table with 3 numbers
-
local tbl4 = {"a",b=2,c="x","d"=5}; -- associative table with mixed content
-
-
Note that you can mix up the data in one table, as shown by tbl4.
-
-
You can refer to table values in a few equivalent manners, using the examples above:
-
-
tbl1[1] -- = nil because tbl1 is empty
-
tbl2[2] -- = "b"
-
tbl3["a"] -- = 1
-
tbl4.b -- = 2
-
tbl2.3 -- = "c"
-
-
When the argument of a function is just a table, the parantheses "()" are optional. So for instance:
-
-
processTable({a=2,b=3});
-
-
Is equivalent to
-
-
processTable{a=2,b=3};
-
-
Another notation that's equivalent is
-
-
filehandle.read(filehandle, 5);
-
filehandle:read(5);
-
-
When using the colon notation ":" Lua will call the function adding the self-reference to the front of the parameterstack.
-
-
Functions behave like objects and are declared in the follow manner:
-
-
function doSomething(somevalue, anothervalue)
-
dostuffhere
-
end;
-
-
So no curly braces "{}" !
-
-
Some flow control:
-
-
for i=0,15 do
-
-- do stuff here, i runs from 0 to 15 (inclusive!)
-
end;
-
-
for key,value in pairs(table) do
-
-- do stuff here. pairs will iterate through the table, splitting the keys and values
-
end;
-
-
while (somethingistrue) do
-
-
end;
-
-
if (somethingistrue) then
-
-
end;
-
-
if (somethingistrue) then
-
-
else
-
-
end;
-
-
if (somethingistrue) then
-
-
elseif (somethingelseistrue) then
-
-
end;
-
-
For comparison, you only have to remember that the exclamationmark is not used. Not equal "!=" is written like tilde-equals "~=" and if (!something) then ... is written with "not " in front of it; if (not something) then...
-
-
For easy reference to the standard libraries look on the bottom half of this page: http://www.lua.org/manual/5.1/
-
-
Lua in FCEUX
-
-
Now then, let's get to the emulator specifics!
-
-
To load a Lua script in FCEU first load a rom (Lua can only do things after each frame cycle so load a rom first). Go to file, at the bottom choose Run Lua Script and select and load the file.
-
-
When Lua starts, the emulator pauses and hands control over to Lua. Lua (that's you!) decides when the next frame is processed. That's why it's very common to write an endless while loop, exiting the main loop of a script will exit the script and hand control back to the emulator. This also happens when a script unexpectingly crashes.
-
-
A bare script looks like this:
-
-
while (true) do
-
emu.frameadvance();
-
end;
-
-
And is about equal to not running Lua at all. The frameadvance function is the same called internally, so no loss of speed there!
-
-
Bitwise operators:
-
-
Lua does not have bitwise operators, so we supply some for you. These are common bitwise operators, nothing fancy.
-
-
AND(a,b);
-
OR(a,b);
-
XOR(a,b);
-
BIT(n); -- returns a number with only bit n set (1)
-
-
The emulator specific Lua is equal to the one of snes9x, with some platform specific changes (few buttons, for instance).
The following is a quick reference, you can go to the snes9x reference for more details.
-
-
To paint stuff on screen, use the gui table. This contains a few predefined functions to manipulate the main window. For any coordinate, 0,0 is the top-left pixel of the window. You have to prevent out-of-bound errors yourself for now. If a color can be passed on, it is a string. HTML-syntax is supported ("#34053D"), as well as a FEW colors ("red", "green", "blue" ...).
-
-
gui.text(x, y, str); -- Print a line to the window, you can use \n for a return but it will only work once
-
gui.pixel(x, y, color); -- plot a pixel at the given coordinate
-
gui.line(x1, y1, x2, y2, color); -- plot a line from x1,y1 to x2,y2
-
gui.box(x1, y1, x2, y2, color); -- draw a square from x1,y1 to x2,y2
-
gui.popup(str); -- pops up a messagebox informing the user of something. Real handy when debugging!
-
gui.getpixel(x,y); -- return the values of the pixel at given position. Returns three numbers of the emulator image before paiting is applied.
-
gui.gdscreenshot(); -- Takes a screen shot of the image and returns it in the form of a string which can be imported by the gd library using the gd.createFromGdStr() function
-
(for more gd functions see DeHackED's reference: http://dehacked.2y.net/snes9x-lua.html)
-
-
PAINTING IS ALWAYS ONE FRAME BEHIND! This is because the painting is done at the creation of the next frame, not while Lua is running.
-
-
Emulator control:
-
-
emu.frameadvance(); -- advances emulation ONE frame
-
emu.pause(); -- same as pressing the pause button
-
emu.speedmode(strMode); -- Supported are "normal","turbo","nothrottle","maximum". But know that except for "normal", all other modes will run as "turbo" for now.
-
emu.wait(); -- skips the emulation of the next frame, in case your script needs to wait for something
-
-
Memory control:
-
-
memory.readbyte(adr); -- read one byte from given address and return it. Besides decimal values Lua also allows the hex notation 0x00FA. In FCEUX reading is done BEFORE the cheats are applied!
-
memory.writebyte(adr, value); -- write one byte to the RAM of the NES. writing is done AFTER the hexeditor receives its values, so if you are freezing an address by Lua, it will not show in the hex editor (but it will in the game :)
-
memory.readbytesigned(adr); -- same as readbyte, except this returns a signed value, rather then an unsigned value.
-
memory.register(adr, function); -- binds a function to an address. The function will be called when an address changes. NOTE THAT THIS IS EXPENSIVE (eg.: slow)! Only one function allowed per address.
-
-
Input control:
-
-
You can read and write input by using the joypad table. A input table has the following (case sensitive) keys, where nil denotes they are not to be pressed: up down left right start select A B
-
-
joypad.read(playern); -- get the input table for the player who's input you want to read (a number!)
-
joypad.write(playern, inputtable); -- set the input for player n. Note that this will overwrite any input from the user, and only when this is used.
-
-
Savestates:
-
-
You can load and save to the predefined savestates 1 ... 9 or create new "anonymous" savestates. You must first create a savestate object, which is your handle to a savestate. Then you can pass this handle on to savestate.load or save to do so.
-
-
savestate.create(n); -- n is optional. When supplied, it will create a savestate for slot n, otherwise a new (anonymous) savestate object is created. Note that this does not yet save or load anything!
-
savestate.load(state); -- load the given savestate
-
savestate.save(state); -- save the given savestate
Lua is a scripting language. It is used in games like Farcry and World of Warcraft (and many other games and applications!). Even though you can find all kinds of tutorials online, let me help you with the basics.
+
+
I will assume you are at least somewhat familiar with the basics of programming. So basic stuff like arrays, variables, strings, loops and if-then-else and branching are not explained here.
+
+
A hello world EmuLua program looks like this:
+
+
while (true) do
+
gui.text(50,50,"Hello world!");
+
emu.frameadvance();
+
end;
+
+
When you load the script, the emulator will sort of go into pause mode and hand controls over to Lua (you!). Hence you are responsible for frameadvancing the emulator.
+
IF YOU DO NOT CALL emu.frameadvance AT THE CYCLE OF THE MAIN LOOP YOU WILL FREEZE THE EMULATOR! There. You have been warned. Don't worry though, you'll make this mistake at least once. Just force-quit the application and try again :)
+
+
Syntax
+
+
Now then. Just like any other language, Lua has a few quirks you should be aware of.
+
+
First of all, if's require a then and end. After a couple of days intensive Lua coding, I still make this mistake myself, but the Lua interpreter will prompt you of such errors on load, so don't worry too much about it. So:
+
+
if (something) then
+
dostuff
+
end;
+
+
Lua uses nil instead of null.
+
+
There are only two values that evaluate to "false", these are "nil" and "false". ANYTHING else will evaluate to true, even 0 or the empty string.
+
+
Comments are denoted by two consecutive dashes; --. Anything after it on the same line is a comment and ignored by Lua. There is no /* */ type of commenting in Lua.
+
+
Variables have a local and global scope. You explicitly make a variable local by declaring it with the "local" keyword.
+
+
somethingglobal; -- accessible by any function or flow
+
local something; -- only known to the same or deeper scope as where it was declared
+
+
Note that variables declared in for loops (see below) are always considered local.
+
+
Arrays are called tables in Lua. To be more precise, Lua uses associative arrays.
+
+
Do not rely on the table.length() when your table can contain nil values, this function stops when it encounters a nil value, thus possibly cutting your table short.
+
+
One experienced programmers will have to get used to is the table offset; tables start at index 1, not 0. That's just the way it is, deal with it.
+
+
There are a few ways to create a table:
+
+
local tbl1 = {}; -- empty table
+
local tbl2 = {"a","b","c","d"}; -- table with 5 strings
+
local tbl3 = {a=1,b=2,c=3}; -- associative table with 3 numbers
+
local tbl4 = {"a",b=2,c="x","d"=5}; -- associative table with mixed content
+
+
Note that you can mix up the data in one table, as shown by tbl4.
+
+
You can refer to table values in a few equivalent manners, using the examples above:
+
+
tbl1[1] -- = nil because tbl1 is empty
+
tbl2[2] -- = "b"
+
tbl3["a"] -- = 1
+
tbl4.b -- = 2
+
tbl2.3 -- = "c"
+
+
When the argument of a function is just a table, the parantheses "()" are optional. So for instance:
+
+
processTable({a=2,b=3});
+
+
Is equivalent to
+
+
processTable{a=2,b=3};
+
+
Another notation that's equivalent is
+
+
filehandle.read(filehandle, 5);
+
filehandle:read(5);
+
+
When using the colon notation ":" Lua will call the function adding the self-reference to the front of the parameterstack.
+
+
Functions behave like objects and are declared in the follow manner:
+
+
function doSomething(somevalue, anothervalue)
+
dostuffhere
+
end;
+
+
So no curly braces "{}" !
+
+
Some flow control:
+
+
for i=0,15 do
+
-- do stuff here, i runs from 0 to 15 (inclusive!)
+
end;
+
+
for key,value in pairs(table) do
+
-- do stuff here. pairs will iterate through the table, splitting the keys and values
+
end;
+
+
while (somethingistrue) do
+
+
end;
+
+
if (somethingistrue) then
+
+
end;
+
+
if (somethingistrue) then
+
+
else
+
+
end;
+
+
if (somethingistrue) then
+
+
elseif (somethingelseistrue) then
+
+
end;
+
+
For comparison, you only have to remember that the exclamationmark is not used. Not equal "!=" is written like tilde-equals "~=" and if (!something) then ... is written with "not " in front of it; if (not something) then...
+
+
For easy reference to the standard libraries look on the bottom half of this page: http://www.lua.org/manual/5.1/
+
+
Lua in FCEUX
+
+
Now then, let's get to the emulator specifics!
+
+
To load a Lua script in FCEU first load a rom (Lua can only do things after each frame cycle so load a rom first). Go to file, at the bottom choose Run Lua Script and select and load the file.
+
+
When Lua starts, the emulator pauses and hands control over to Lua. Lua (that's you!) decides when the next frame is processed. That's why it's very common to write an endless while loop, exiting the main loop of a script will exit the script and hand control back to the emulator. This also happens when a script unexpectingly crashes.
+
+
A bare script looks like this:
+
+
while (true) do
+
emu.frameadvance();
+
end;
+
+
And is about equal to not running Lua at all. The frameadvance function is the same called internally, so no loss of speed there!
+
+
Bitwise operators:
+
+
Lua does not have bitwise operators, so we supply some for you. These are common bitwise operators, nothing fancy.
+
+
AND(a,b);
+
OR(a,b);
+
XOR(a,b);
+
BIT(n); -- returns a number with only bit n set (1)
+
+
The emulator specific Lua is equal to the one of snes9x, with some platform specific changes (few buttons, for instance).
The following is a quick reference, you can go to the snes9x reference for more details.
+
+
To paint stuff on screen, use the gui table. This contains a few predefined functions to manipulate the main window. For any coordinate, 0,0 is the top-left pixel of the window. You have to prevent out-of-bound errors yourself for now. If a color can be passed on, it is a string. HTML-syntax is supported ("#34053D"), as well as a FEW colors ("red", "green", "blue" ...).
+
+
gui.text(x, y, str); -- Print a line to the window, you can use \n for a return but it will only work once
+
gui.pixel(x, y, color); -- plot a pixel at the given coordinate
+
gui.line(x1, y1, x2, y2, color); -- plot a line from x1,y1 to x2,y2
+
gui.box(x1, y1, x2, y2, color); -- draw a square from x1,y1 to x2,y2
+
gui.popup(str); -- pops up a messagebox informing the user of something. Real handy when debugging!
+
gui.getpixel(x,y); -- return the values of the pixel at given position. Returns three numbers of the emulator image before paiting is applied.
+
gui.gdscreenshot(); -- Takes a screen shot of the image and returns it in the form of a string which can be imported by the gd library using the gd.createFromGdStr() function
+
(for more gd functions see DeHackED's reference: http://dehacked.2y.net/snes9x-lua.html)
+
+
PAINTING IS ALWAYS ONE FRAME BEHIND! This is because the painting is done at the creation of the next frame, not while Lua is running.
+
+
Emulator control:
+
+
emu.frameadvance(); -- advances emulation ONE frame
+
emu.pause(); -- same as pressing the pause button
+
emu.speedmode(strMode); -- Supported are "normal","turbo","nothrottle","maximum". But know that except for "normal", all other modes will run as "turbo" for now.
+
emu.wait(); -- skips the emulation of the next frame, in case your script needs to wait for something
+
+
Memory control:
+
+
memory.readbyte(adr); -- read one byte from given address and return it. Besides decimal values Lua also allows the hex notation 0x00FA. In FCEUX reading is done BEFORE the cheats are applied!
+
memory.writebyte(adr, value); -- write one byte to the RAM of the NES. writing is done AFTER the hexeditor receives its values, so if you are freezing an address by Lua, it will not show in the hex editor (but it will in the game :)
+
memory.readbytesigned(adr); -- same as readbyte, except this returns a signed value, rather then an unsigned value.
+
memory.register(adr, function); -- binds a function to an address. The function will be called when an address changes. NOTE THAT THIS IS EXPENSIVE (eg.: slow)! Only one function allowed per address.
+
+
Input control:
+
+
You can read and write input by using the joypad table. A input table has the following (case sensitive) keys, where nil denotes they are not to be pressed: up down left right start select A B
+
+
joypad.read(playern); -- get the input table for the player who's input you want to read (a number!)
+
joypad.write(playern, inputtable); -- set the input for player n. Note that this will overwrite any input from the user, and only when this is used.
+
+
Savestates:
+
+
You can load and save to the predefined savestates 1 ... 9 or create new "anonymous" savestates. You must first create a savestate object, which is your handle to a savestate. Then you can pass this handle on to savestate.load or save to do so.
+
+
savestate.create(n); -- n is optional. When supplied, it will create a savestate for slot n, otherwise a new (anonymous) savestate object is created. Note that this does not yet save or load anything!
+
savestate.load(state); -- load the given savestate
+
savestate.save(state); -- save the given savestate
FCEUX includes a context menu that allows commonly used menu functions for various situations. There are some functions that appear only here.
-
-
This page describes all the possible menu items in each possible context situation.
-
-
No game loaded.
-
-
Appears when no game is loaded.
-
-
Open ROM
-
Same as the File > Open ROM option
-
-
Last ROM used
-
Opens the most recently used file from the Recent Files Menu
-
-
Help
-
Brings up the Getting Started chapter in the help document.
-
-
-
Game Loaded
-
-
Appears when a game is loaded, but not a movie (.fm2).
-
-
Play Movie...
-
Same as the File > Movie > Play Movie menu item.
-
-
Record Movie...
-
Same as the File > Movie > Record Movie menu item.
-
-
Undo savestate
-
If this option is enabled it means the last savestate saved over-wrote a previous savestate file. This option restores the previous savestate file.
-
-
Redo savestate
-
If this option is in the menu, it means that Undo savestate was recently used to restore a previous savestate. This reverts that change.
-
-
Rewind to last auto-save
-
Auto-save must be enabled for this menu item to be accessible. Same as the Load last auto-save Hotkey Item. It loads the last auto-savestate. Auto-savestates are created once about every 4 seconds, so this typically has the effect of rewinding emulation.
-
-
Screenshot
-
Same as File > Screenshot.
-
-
Close ROM
-
Same as File > Close
-
-
-
Movie loaded - Read-only
-
-
Appears when a movie is loaded and Read-only mode is set.
-
-
Toggle to read+write
-
Sets Read status to Read+Write.
-
-
Play Movie from Beginning
-
Same as File > Movie > Play from Beginning. Turns Read status to Read-Only and plays the movie from frame 1.
-
-
Stop Movie Replay
-
Same as File > Movie > Stop Movie.
-
-
View comments and subtitles
-
Opens up the Metadata dialog. Same as the Metadata button on the Play movie dialog.
-
-
Undo savestate
-
If this option is enabled it means the last savestate saved over-wrote a previous savestate file. This option restores the previous savestate file.
-
-
Redo savestate
-
If this option is in the menu, it means that Undo savestate was recently used to restore a previous savestate. This reverts that change.
-
-
Rewind to last auto-save
-
Auto-save must be enabled for this menu item to be accessible. Same as the Load last auto-save Hotkey Item. It loads the last auto-savestate. Auto-savestates are created once about every 4 seconds, so this typically has the effect of rewinding emulation.
-
-
Help
-
Opens the Movie recording chapter of the help document.
-
-
-
Movie loaded - Read + Write
-
-
Toggle to Read-only
-
Sets Read status to Read-Only.
-
-
Play Movie From Beginning
-
Same as File > Movie > Play from Beginning. Turns Read status to Read-Only and plays the movie from frame 1.
-
-
Stop Movie Recording
-
Same as File > Movie > Stop Movie.
-
-
View comments and subtitles
-
Opens up the Metadata dialog. Same as the Metadata button on the Play movie dialog.
-
-
Make backup
-
Generates a backup .fm2. Uses the same file naming system as the auto-movie backup. (See movie options for details).
-
-
Undo savestate
-
If this option is enabled it means the last savestate saved over-wrote a previous savestate file. This option restores the previous savestate file.
-
-
Redo savestate
-
If this option is in the menu, it means that Undo savestate was recently used to restore a previous savestate. This reverts that change.
-
-
Undo loadstate
-
If this option is enabled it was because the Loadstate function was called sometime while the game was loaded. This function restores the game state to where it was before loadstate was called.
-
-
Redo loadstate
-
If Undo loadstate was called, this option is available. It reverts the change and restores the game back to the point it was when loadstate was called.
-
-
Help
-
Opens the Movie recording chapter of the help document.
-
-
Additional items may also appear related to these situations:
-
-
Lua
-
-
Load last Lua
-
If there is at least 1 filename in the Recent Lua Files menu this calls the most recently used Lua script file. Has the same effect as the File > Lua > Reload Lua Script menu item.
-
-
Stop Lua
-
If a Lua script is currently loaded this option is available. Same as File > Lua > Stop Lua Script.
-
-
Hide Menu
-
-
Unhide menu
-
If the main FCEUX menu is hidden this option is available. Restores the main menu.
-
-
Subtitles
-
-
If a movie is loaded and has subtitles:
-
-
a toggle subtitles option will be in the menu
-
a Dump to SRT file option will be available. This dumps the subtitles to a standard subtitle file compatible with A/V containers such as .mkv
+
Context Menu
+
+
FCEUX includes a context menu that allows commonly used menu functions for various situations. There are some functions that appear only here.
+
+
This page describes all the possible menu items in each possible context situation.
+
+
No game loaded.
+
+
Appears when no game is loaded.
+
+
Open ROM
+
Same as the File > Open ROM option
+
+
Last ROM used
+
Opens the most recently used file from the Recent Files Menu
+
+
Help
+
Brings up the Getting Started chapter in the help document.
+
+
+
Game Loaded
+
+
Appears when a game is loaded, but not a movie (.fm2).
+
+
Play Movie...
+
Same as the File > Movie > Play Movie menu item.
+
+
Record Movie...
+
Same as the File > Movie > Record Movie menu item.
+
+
Undo savestate
+
If this option is enabled it means the last savestate saved over-wrote a previous savestate file. This option restores the previous savestate file.
+
+
Redo savestate
+
If this option is in the menu, it means that Undo savestate was recently used to restore a previous savestate. This reverts that change.
+
+
Rewind to last auto-save
+
Auto-save must be enabled for this menu item to be accessible. Same as the Load last auto-save Hotkey Item. It loads the last auto-savestate. Auto-savestates are created once about every 4 seconds, so this typically has the effect of rewinding emulation.
+
+
Screenshot
+
Same as File > Screenshot.
+
+
Close ROM
+
Same as File > Close
+
+
+
Movie loaded - Read-only
+
+
Appears when a movie is loaded and Read-only mode is set.
+
+
Toggle to read+write
+
Sets Read status to Read+Write.
+
+
Play Movie from Beginning
+
Same as File > Movie > Play from Beginning. Turns Read status to Read-Only and plays the movie from frame 1.
+
+
Stop Movie Replay
+
Same as File > Movie > Stop Movie.
+
+
View comments and subtitles
+
Opens up the Metadata dialog. Same as the Metadata button on the Play movie dialog.
+
+
Undo savestate
+
If this option is enabled it means the last savestate saved over-wrote a previous savestate file. This option restores the previous savestate file.
+
+
Redo savestate
+
If this option is in the menu, it means that Undo savestate was recently used to restore a previous savestate. This reverts that change.
+
+
Rewind to last auto-save
+
Auto-save must be enabled for this menu item to be accessible. Same as the Load last auto-save Hotkey Item. It loads the last auto-savestate. Auto-savestates are created once about every 4 seconds, so this typically has the effect of rewinding emulation.
+
+
Help
+
Opens the Movie recording chapter of the help document.
+
+
+
Movie loaded - Read + Write
+
+
Toggle to Read-only
+
Sets Read status to Read-Only.
+
+
Play Movie From Beginning
+
Same as File > Movie > Play from Beginning. Turns Read status to Read-Only and plays the movie from frame 1.
+
+
Stop Movie Recording
+
Same as File > Movie > Stop Movie.
+
+
View comments and subtitles
+
Opens up the Metadata dialog. Same as the Metadata button on the Play movie dialog.
+
+
Make backup
+
Generates a backup .fm2. Uses the same file naming system as the auto-movie backup. (See movie options for details).
+
+
Undo savestate
+
If this option is enabled it means the last savestate saved over-wrote a previous savestate file. This option restores the previous savestate file.
+
+
Redo savestate
+
If this option is in the menu, it means that Undo savestate was recently used to restore a previous savestate. This reverts that change.
+
+
Undo loadstate
+
If this option is enabled it was because the Loadstate function was called sometime while the game was loaded. This function restores the game state to where it was before loadstate was called.
+
+
Redo loadstate
+
If Undo loadstate was called, this option is available. It reverts the change and restores the game back to the point it was when loadstate was called.
+
+
Help
+
Opens the Movie recording chapter of the help document.
+
+
Additional items may also appear related to these situations:
+
+
Lua
+
+
Load last Lua
+
If there is at least 1 filename in the Recent Lua Files menu this calls the most recently used Lua script file. Has the same effect as the File > Lua > Reload Lua Script menu item.
+
+
Stop Lua
+
If a Lua script is currently loaded this option is available. Same as File > Lua > Stop Lua Script.
+
+
Hide Menu
+
+
Unhide menu
+
If the main FCEUX menu is hidden this option is available. Restores the main menu.
+
+
Subtitles
+
+
If a movie is loaded and has subtitles:
+
+
a toggle subtitles option will be in the menu
+
a Dump to SRT file option will be available. This dumps the subtitles to a standard subtitle file compatible with A/V containers such as .mkv
FCEUX uses a new movie file format (.fm2). In order to use movie files frame previous FCE Ultra versions (.fcm) you will need to convert to .fm2 first.
-
-
Using .fcm Convert
-
-
To use it simply highlight it. Then select the .fcm you wish to convert (or shift+click to select multiple .fcm files). Then click Open to have the select files converted. All files selected will have a matching .fm2 file copied into the same folder.
FCEUX uses a new movie file format (.fm2). In order to use movie files frame previous FCE Ultra versions (.fcm) you will need to convert to .fm2 first.
+
+
Using .fcm Convert
+
+
To use it simply highlight it. Then select the .fcm you wish to convert (or shift+click to select multiple .fcm files). Then click Open to have the select files converted. All files selected will have a matching .fm2 file copied into the same folder.
There are some options that can only be done by directly editing the config (fceux.cfg) file. All of those options are documented here.
-
The .cfg file is a text file and can be opened by any text editor (just as wordpad).
-
-
-
Emulator background Color when Graphics Background is disabled
-
-
gNoBGFillColor
-
-
When you disable the backgrounds (Config > Display > Graphics: GB), the default color is black. You can change that color by modifying this value. By default it is 255 (black).
-
-
-
Debugger
-
-
debuggerFontSize 15
-
-
This value determines the size of the "Courier" font used by Debugger and Trace Logger. By default it is 15.
-
-
-
Hex Editor
-
-
hexeditorFontSize 15
-
-
This value determines the size of the "Courier" font used by Hex Editor. By default it is 15.
-
-
-
HexRowHeightBorder 0
-
-
This value determines the number of pixels between each row of values in the Hex Editor. By default it is 0.
-
-
-
HexBackColorR 255
-
HexBackColorG 255
-
HexBackColorB 255
-
-
HexForeColorR 0
-
HexForeColorG 0
-
HexForeColorB 0
-
-
HexFreezeColorR 0
-
HexFreezeColorG 0
-
HexFreezeColorB 255
-
-
These values allows are the Hex Editor color scheme values (RGB). The background color is 255,255,255 (white) by default. The foreground color (text) is 0,0,0 (black) by default. When an address is frozen it is 0,0,255 (blue) by default.
There are some options that can only be done by directly editing the config (fceux.cfg) file. All of those options are documented here.
+
The .cfg file is a text file and can be opened by any text editor (just as wordpad).
+
+
+
Emulator background Color when Graphics Background is disabled
+
+
gNoBGFillColor
+
+
When you disable the backgrounds (Config > Display > Graphics: GB), the default color is black. You can change that color by modifying this value. By default it is 255 (black).
+
+
+
Debugger
+
+
debuggerFontSize 15
+
+
This value determines the size of the "Courier" font used by Debugger and Trace Logger. By default it is 15.
+
+
+
Hex Editor
+
+
hexeditorFontSize 15
+
+
This value determines the size of the "Courier" font used by Hex Editor. By default it is 15.
+
+
+
HexRowHeightBorder 0
+
+
This value determines the number of pixels between each row of values in the Hex Editor. By default it is 0.
+
+
+
HexBackColorR 255
+
HexBackColorG 255
+
HexBackColorB 255
+
+
HexForeColorR 0
+
HexForeColorG 0
+
HexForeColorB 0
+
+
HexFreezeColorR 0
+
HexFreezeColorG 0
+
HexFreezeColorB 255
+
+
These values allows are the Hex Editor color scheme values (RGB). The background color is 255,255,255 (white) by default. The foreground color (text) is 0,0,0 (black) by default. When an address is frozen it is 0,0,255 (blue) by default.
The debugger is a tool for inspecting and manipulating machine instructions and their execution. The debugger window has several components:
-
-
Execution - a small set of controls for controlling the execution of code.
-
CPU State - display of registers, flags, the stack, cycles and instructions counters, and also the PPU state.
-
Memory disassembly - displays a disassembly of the bytes currently accessible by the CPU data bus.
-
Breakpoints - a list of breakpoints for debugging.
-
Bookmarks - a list of bookmarked addresses for quick navigation.
-
Other - buttons for controlling symbolic debugging, rom patching, etc.
+
Debugger
+
+
+
Introduction
+
+
The debugger is a tool for inspecting and manipulating machine instructions and their execution. The debugger window has several components:
+
+
Execution - a small set of controls for controlling the execution of code.
+
CPU State - display of registers, flags, the stack, cycles and instructions counters, and also the PPU state.
+
Memory disassembly - displays a disassembly of the bytes currently accessible by the CPU data bus.
+
Breakpoints - a list of breakpoints for debugging.
+
Bookmarks - a list of bookmarked addresses for quick navigation.
+
Other - buttons for controlling symbolic debugging, rom patching, etc.
-
-
-
Execution and CPU State
-
-
Execution is controlled by the set of buttons at the top-middle of the window. These allow you to break (pause) execution and inspect the current state of the NES.
-
-
When an NES ROM is opened, it will be normally be running right away (unless you manually pause the emulator before loading). Most of the debugger window does not update while the game is running. To begin debugging you may click one of the buttons that will break (pause) execution, such as "Step Into".
-
-
-
Run - runs the program continuously until the next breakpoint is hit, or the emulator is paused manually. The same effect can be achieved by pressing the Pause hotkey which will unpause emulator when it's paused.
-
Step Into - runs one instruction and then breaks.
-
Step Out - attempt to run until the current subroutine ends with an RTS; in some cases will behave the same as Run.
-
Step Over - runs one instruction, unless it is a JSR instruction, which will run until its RTS.
-
Run Line - runs one scanline before breaking.
-
128 Lines - runs 128 scanlines before breaking.
+
+
+
Execution and CPU State
+
+
Execution is controlled by the set of buttons at the top-middle of the window. These allow you to break (pause) execution and inspect the current state of the NES.
+
+
When an NES ROM is opened, it will be normally be running right away (unless you manually pause the emulator before loading). Most of the debugger window does not update while the game is running. To begin debugging you may click one of the buttons that will break (pause) execution, such as "Step Into".
+
+
+
Run - runs the program continuously until the next breakpoint is hit, or the emulator is paused manually. The same effect can be achieved by pressing the Pause hotkey which will unpause emulator when it's paused.
+
Step Into - runs one instruction and then breaks.
+
Step Out - attempt to run until the current subroutine ends with an RTS; in some cases will behave the same as Run.
+
Step Over - runs one instruction, unless it is a JSR instruction, which will run until its RTS.
+
Run Line - runs one scanline before breaking.
+
128 Lines - runs 128 scanlines before breaking.
-
-
The Pause hotkey will break execution or resume it. The Frame Advance hotkey will run the emulator for one frame and then break.
-
-
When execution is paused, the disassembly view will begin with the memory near the current program counter location (PC). The ">" mark shows the line which will be executed next. You can scroll the disassembly up or down (using scrollbar or mouse wheel) to observe the code. Then you can click "Seek PC" to return to the program counter at any time.
-
-
You can also use "Seek To" button that will navigate to the specified address. Either type a hexadecimal address to the text field or simply left-click on any address in the Disassembly window.
-
-
-
-
HINT: When entering the address manually, these convenient strings may be used instead of the hexadecimal memory address:
-
NES special addresses:
-
-
NMI/VBL - non-maskable interrupt vector (at FFFA)
-
RST - reset vector (at FFFC)
-
IRQ - interrupt vector (at FFFE)
-
-
FDS special addresses:
-
-
NMI1 - non-maskable interrupt vector (at DFF6)
-
NMI2 - non-maskable interrupt vector (at DFF8)
-
NMI3 - non-maskable interrupt vector (at DFFA)
-
RST - reset vector (at DFFC)
-
IRQ - interrupt vector (at DFFE)
-
-
NSF special addresses:
-
-
LOAD - NSF LOAD address
-
INIT - NSF INIT address
-
PLAY - NSF PLAY address
-
-
-
+
+
The Pause hotkey will break execution or resume it. The Frame Advance hotkey will run the emulator for one frame and then break.
+
+
When execution is paused, the disassembly view will begin with the memory near the current program counter location (PC). The ">" mark shows the line which will be executed next. You can scroll the disassembly up or down (using scrollbar or mouse wheel) to observe the code. Then you can click "Seek PC" to return to the program counter at any time.
+
+
You can also use "Seek To" button that will navigate to the specified address. Either type a hexadecimal address to the text field or simply left-click on any address in the Disassembly window.
+
+
+
+
+
+
HINT: When entering the address manually, these convenient strings may be used instead of the hexadecimal memory address:
+
NES special addresses:
+
+
NMI/VBL - non-maskable interrupt vector (at FFFA)
+
RST - reset vector (at FFFC)
+
IRQ - interrupt vector (at FFFE)
+
+
FDS special addresses:
+
+
NMI1 - non-maskable interrupt vector (at DFF6)
+
NMI2 - non-maskable interrupt vector (at DFF8)
+
NMI3 - non-maskable interrupt vector (at DFFA)
+
RST - reset vector (at DFFC)
+
IRQ - interrupt vector (at DFFE)
+
+
NSF special addresses:
+
+
LOAD - NSF LOAD address
+
INIT - NSF INIT address
+
PLAY - NSF PLAY address
+
+
+
-
-
While execution is broken (emulation is paused), the program counter (PC) can be edited, as well as the three registers A/X/Y, and the status flags. Normally they should be left as-is, but changing them at runtime can be useful for more advanced debugging.
-
-
The contents of memory starting at the stack pointer (somewhere in the range $0100-01FF) is displayed in the Stack frame below the A/X/Y registers.
-
-
The current PPU memory address, sprite memory address, scanline, and rendering pixel are displayed below the stack and status flags. Examples of Scanline number: -1 means Prerender time, 240 is Idle scanline, 0-239 are visible scanlines, 241-260/310 are VBlank scanlines.
-
-
To the right from the PPU section there's Cycles counter and Instructions counter that keep counting while the game is running. You can use the information for keeping statistics, for code profiling or writing PPU-synchronized code (e.g. raster effects). You can also make the debugger break automatically based on the counters values. The "Reset counters" button resets both counters to 0. You can also access the counters via Lua.
-
-
-
Disassembly
-
-
This large frame takes up the left side of the debugger window. It displays the current contents of memory accessible by the CPU with an automatic disassembly of that data into assembly instructions. The following memory ranges may contain useful data for inspection:
-
-
0000-00FF - zero page (RAM)
-
0100-01FF - stack (RAM)
-
0200-07FF - RAM
-
4018-FFFF - mapper controlled (ROM or RAM, may be bankswitched)
+
+
While execution is broken (emulation is paused), the program counter (PC) can be edited, as well as the three registers A/X/Y, and the status flags. Normally they should be left as-is, but changing them at runtime can be useful for more advanced debugging.
+
+
The contents of memory starting at the stack pointer (somewhere in the range $0100-01FF) is displayed in the Stack frame below the A/X/Y registers.
+
+
The current PPU memory address, sprite memory address, scanline, and rendering pixel are displayed below the stack and status flags. Examples of Scanline number: -1 means Prerender time, 240 is Idle scanline, 0-239 are visible scanlines, 241-260/310 are VBlank scanlines.
+
+
To the right from the PPU section there's Cycles counter and Instructions counter that keep counting while the game is running. You can use the information for keeping statistics, for code profiling or writing PPU-synchronized code (e.g. raster effects). You can also make the debugger break automatically based on the counters values. The "Reset counters" button resets both counters to 0. You can also access the counters via Lua.
+
+
+
Disassembly
+
+
This large frame takes up the left side of the debugger window. It displays the current contents of memory accessible by the CPU with an automatic disassembly of that data into assembly instructions. The following memory ranges may contain useful data for inspection:
+
+
0000-00FF - zero page (RAM)
+
0100-01FF - stack (RAM)
+
0200-07FF - RAM
+
4018-FFFF - mapper controlled (ROM or RAM, may be bankswitched)
-
-
Memory contents are displayed in this form:
-
-
0F:C0A8:24 1F BIT $001F = #$80
-
bb:mmmm:dd dd dd iiiiiiiiiiiii...
-
-
-
bb - 16k iNES bank, designates which 16k bank from the iNES file is mapped here. Note that the number may be not the same as the actual hardware bank of the mapper.
-
mmmm - physical address on the NES CPU data bus.
-
dd - data bytes belonging to the instruction beginning at this address.
-
iiii - assembly description of the instruction, possibly with symbolic decoration.
+
+
Memory contents are displayed in this form:
+
+
0F:C0A8:24 1F BIT $001F = #$80
+
bb:mmmm:dd dd dd iiiiiiiiiiiii...
+
+
+
bb - 16k iNES bank, designates which 16k bank from the iNES file is mapped here. Note that the number may be not the same as the actual hardware bank of the mapper.
+
mmmm - physical address on the NES CPU data bus.
+
dd - data bytes belonging to the instruction beginning at this address.
+
iiii - assembly description of the instruction, possibly with symbolic decoration.
-
-
When debugging an NSF program, the bank designation will be a 4k NSF bank instead of the 16k iNES bank.
-
-
A single instruction may be one to three bytes, and will all appear on the line before the assembly code description of that instruction. An instruction with "= #$xx" at the end conveniently indicates the value currently in memory at the address referenced by the instruction.
-
-
Hovering the mouse over the disassembly will display at the bottom of the window more detailed information about the location of this code in the iNES file.
-
-
There is narrow column to the left of the Disassembly window. Left clicking on this column will open the Inline Assembler, which allows you to patch the ROM at runtime. Right clicking on this column will open the Hex Editor, which allows you to directly edit the ROM. Middle-clicking on this column will bring up the Game Genie Encoder at that address, so you can easily make Game Genie codes.
-
Also, when Code/Data Logger is running, this small column displays whether the respective line of the disassembled memory was executed ("c") or it was read as Data ("d"), or it wasn't logged yet (empty space). This way you can easily distinguish which branches of the game code were executed and which weren't.
-
-
-
Symbolic Debugging
-
-
FCEUX allows you to label any address of RAM or ROM with a human-readable symbolic name.
-
For example, when you've figured out that at the address $C022 there's a subroutine which refills player HP, you can right-click the address and type a name like "AddHealthpoints". You can also add a comment, which will be seen while browsing the code near this address. From now on, the address will be substituted by the name everywhere - in all instructions referencing this address, in Hex Editor window, in the log produced by Trace Logger. E.g., JSR $C022 will look like JSR AddHealthpoints.
-
-
When entering the name, you can use any symbols except #. It's also recommended to avoid whitespaces in names.
-
To rename an address, just right-click the name.
-
-
The data for Symbolic Debugging is stored in NL files in the same folder as the ROM. You can edit the files in any text editor (to reload all NL files of the currently active ROM file press the "Reload Symbols" button), but it's more convenient to use right-clicks.
-
-
You can enable and disable symbolic debugging by clicking the checkbox "Symbolic debug" in the lower right corner. In general, there's no need to disable this feature. If you need to see the actual address which got substituted by a name, you can simply left-click the name and watch its address in the "Seek To" text field. This also works when clicking a name in the Trace Logger window.
-
-
-
Breakpoints
-
-
Breakpoints will automatically break execution when chosen conditions are met. To create a breakpoint, click the Add button in the Breakpoints frame in the upper right corner of the debugger.
-
-
Each breakpoint has an address range to watch. Use only the left address field if you wish to watch a single byte address. When entering the address of a breakpoint, you can also use the aforementioned convenient strings (such as IRQ) instead of hexadecimal memory addresses.
-
-
Check one or more of the options to watch for Read, Write, or Execute at the given address. Note that fetching of code from an address will not break as a Read; so use the Execute box for this case. Breakpoints can be given a name that will appear in the breakpoints list. The condition field can be used to break only on particular conditions; see "Conditional Breakpoints" below.
-
-
Double click on a breakpoint in the Breakpoints list to quickly disable or enable this breakpoint. So you don't have to delete breakpoints to stop them from causing the debugger to halt the game.
-
-
A special kind of breakpoints with the "Forbid" option will prevent any breakpoints from occurring within the specified memory address range. This can be enabled and disabled like other breakpoints.
-
-
A quicker way to add PC breakpoints is to double click on any address in the Disassembly when you want to set the breakpoint to that address. Example: when you need to quickly advance emulation to a given line of code, double-click on the address part of the line, and the "Add Execute breakpoint here" dialog will appear, just click "OK" and then hit "Run", Debugger will break at this line of code.
-
-
There is also an option to Break on Bad Opcodes, which will halt execution if a bad instruction opcode is reached.
-
-
Finally, you can make the debugger break after executing a certain number of instructions or CPU cycles.
-
-
More advanced breakpoints conditions and full automation may be achieved through Lua script breakpoints. See the Lua reference for more information.
-
-
Breakpoints are listed in the following form:
-
-
aaaa EmRWXF nnnn cccc
-
or
-
aaaa-aaaa EmRWXF nnnn cccc
-
-
-
aaaa - address of breakpoint
-
E - enabled
-
m - memory area: C = CPU, P = PPU, S = sprite
-
R - read
-
W - write
-
X - execute
-
F - Forbid
-
nnnn - (optional) name of breakpoint
-
nnnn - (optional) condition of breakpoint
+
+
When debugging an NSF program, the bank designation will be a 4k NSF bank instead of the 16k iNES bank.
+
+
A single instruction may be one to three bytes, and will all appear on the line before the assembly code description of that instruction. An instruction with "= #$xx" at the end conveniently indicates the value currently in memory at the address referenced by the instruction.
+
+
Hovering the mouse over the disassembly will display at the bottom of the window more detailed information about the location of this code in the iNES file.
+
+
There is narrow column to the left of the Disassembly window. Left clicking on this column will open the Inline Assembler, which allows you to patch the ROM at runtime. Right clicking on this column will open the Hex Editor, which allows you to directly edit the ROM. Middle-clicking on this column will bring up the Game Genie Encoder at that address, so you can easily make Game Genie codes.
+
Also, when Code/Data Logger is running, this small column displays whether the respective line of the disassembled memory was executed ("c") or it was read as Data ("d"), or it wasn't logged yet (empty space). This way you can easily distinguish which branches of the game code were executed and which weren't.
+
+
+
Symbolic Debugging
+
+
FCEUX allows you to label any address of RAM or ROM with a human-readable symbolic name.
+
For example, when you've figured out that at the address $C022 there's a subroutine which refills player HP, you can right-click the address and type a name like "AddHealthpoints". You can also add a comment, which will be seen while browsing the code near this address. From now on, the address will be substituted by the name everywhere - in all instructions referencing this address, in Hex Editor window, in the log produced by Trace Logger. E.g., JSR $C022 will look like JSR AddHealthpoints.
+
+
When entering the name, you can use any symbols except #. It's also recommended to avoid whitespaces in names.
+
To rename an address, just right-click the name.
+
+
The data for Symbolic Debugging is stored in NL files in the same folder as the ROM. You can edit the files in any text editor (to reload all NL files of the currently active ROM file press the "Reload Symbols" button), but it's more convenient to use right-clicks.
+
+
You can enable and disable symbolic debugging by clicking the checkbox "Symbolic debug" in the lower right corner. In general, there's no need to disable this feature. If you need to see the actual address which got substituted by a name, you can simply left-click the name and watch its address in the "Seek To" text field. This also works when clicking a name in the Trace Logger window.
+
+
+
Breakpoints
+
+
Breakpoints will automatically break execution when chosen conditions are met. To create a breakpoint, click the Add button in the Breakpoints frame in the upper right corner of the debugger.
+
+
Each breakpoint has an address range to watch. Use only the left address field if you wish to watch a single byte address. When entering the address of a breakpoint, you can also use the aforementioned convenient strings (such as IRQ) instead of hexadecimal memory addresses.
+
+
Check one or more of the options to watch for Read, Write, or Execute at the given address. Note that fetching of code from an address will not break as a Read; so use the Execute box for this case. Breakpoints can be given a name that will appear in the breakpoints list. The condition field can be used to break only on particular conditions; see "Conditional Breakpoints" below.
+
+
Double click on a breakpoint in the Breakpoints list to quickly disable or enable this breakpoint. So you don't have to delete breakpoints to stop them from causing the debugger to halt the game.
+
+
A special kind of breakpoints with the "Forbid" option will prevent any breakpoints from occurring within the specified memory address range. This can be enabled and disabled like other breakpoints.
+
+
A quicker way to add PC breakpoints is to double click on any address in the Disassembly when you want to set the breakpoint to that address. Example: when you need to quickly advance emulation to a given line of code, double-click on the address part of the line, and the "Add Execute breakpoint here" dialog will appear, just click "OK" and then hit "Run", Debugger will break at this line of code.
+
+
There is also an option to Break on Bad Opcodes, which will halt execution if a bad instruction opcode is reached.
+
+
Finally, you can make the debugger break after executing a certain number of instructions or CPU cycles.
+
+
More advanced breakpoints conditions and full automation may be achieved through Lua script breakpoints. See the Lua reference for more information.
+
+
Breakpoints are listed in the following form:
+
+
aaaa EmRWXF nnnn cccc
+
or
+
aaaa-aaaa EmRWXF nnnn cccc
+
+
+
aaaa - address of breakpoint
+
E - enabled
+
m - memory area: C = CPU, P = PPU, S = sprite
+
R - read
+
W - write
+
X - execute
+
F - Forbid
+
nnnn - (optional) name of breakpoint
+
nnnn - (optional) condition of breakpoint
-
-
-
Conditional Breakpoints
-
-
Breakpoints may also have a conditional statement that causes them to execute only if that statement evaluates to true. The conditional breakpoint grammar has this form:
-
-
-
Connect -> Compare { ('||' | '&&') Compare }
-
Compare -> Sum { ('==' | '!=' | '<=' | '>=' | '<' | '>') Sum }
-
Sum -> Product { ('+' | '-') Product }
-
Product -> Primitive { ('*' | '/') Primitive }
-
Primitive -> Number | Address | Register | Flag | PC Bank | Data Bank | '(' Connect ')'
Breakpoints may also have a conditional statement that causes them to execute only if that statement evaluates to true. The conditional breakpoint grammar has this form:
+
+
+
Connect -> Compare { ('||' | '&&') Compare }
+
Compare -> Sum { ('==' | '!=' | '<=' | '>=' | '<' | '>') Sum }
+
Sum -> Product { ('+' | '-') Product }
+
Product -> Primitive { ('*' | '/') Primitive }
+
Primitive -> Number | Address | Register | Flag | PC Bank | Data Bank | '(' Connect ')'
The parser is very strict. All numbers are hexadecimal. Always prefix a number with # for an immediate value, or $ for a memory address. If a memory address needs to be calculated use $[] with the calculation inside the brackets.
-
-
Registers A/X/Y are 8-bit unsigned values. Register P is the 16-bit program counter.
-
Flags evaluate to 1 if set, 0 if clear. (U is the unused bit of the status register, and D is the unused decimal flag.)
-
For instructions that read or write a single byte (e.g. LDA, STY, PHA, ASL abs), condition R evaluates to the value that will be read by the instruction, and condition W evaluates to the value that will be written.
-
-
Connecting operators || or && combine boolean terms. Parentheses dictate order of operations.
-
-
Example conditions:
-
-
Break only if register A is less than value at memory address $0005:
-
A < $0005
-
-
Break only if the value at the indirect address is not equal to FF:
-
#FF != $[$10+($11*#100)]
-
-
Break only if flag N is clear or A is not equal to 00:
-
(N==#0 || A!=#0)
-
-
Break only when accessing a data from bank 2 (the condiition is relevant when using with Read/Write-type breakpoints):
-
T==#2
-
-
-
Bookmarks
-
-
A list of bookmarked addresses can be kept in the Address Bookmarks frame to make memory navigation easier. Simply type a hexadecimal address (or a convenient string, such as "NMI") and click "Add" to add it to your bookmarks. Alternatively, just left-click any address in the Disassembly window, and the address will appear in the Bookmark Add field, so you don't have to type it.
-
Next time you wish to go to this address just double click on the bookmark.
-
You can also name bookmarks.
-
When you exit the emulator, bookmarks are saved in a .deb file named after the ROM of the debugged game. Next time you return to debugging the game, the list of bookmarks will be automatically loaded from the file.
-
-
-
Inline Assembler
-
-
Open the inline assembler by left-clicking in the empty column to the left of the memory view.
-
-
The starting memory address is displayed in the PC field at the top of the inline assembler window. Type a line of assembly to add in the empty field just below this, and hit enter. The assembled code of your patch will appear below as you enter each line.
-
-
Click Apply to apply your patch to the ROM in memory. Click Undo to remove the last assembled line. After applying a patch, clicking Save will allow you to save this patch directly to the ROM file.
-
-
-
Other
-
-
If the ".DEB files" checkbox in the lower right corner of the debugger window is checked, the emulator will automatically save debug settings such as breakpoints and bookmarks in a .deb file alongside the NES ROM, and load these settings next time you open the ROM.
-
-
There is a "Rom Patcher" button that may be used to apply a small patch to a ROM, although Hex Editor is more convenient in general.
-
-
The "ROM offsets" option will display ROM offsets instead of CPU addresses in the Disassembly window.
-
-
The "Restore Original Window Size" button will restore the original size of the debugger window if you resized it manually.
-
-
The "Auto-open" checkbox causes the debugger window to open automatically whenever an NES ROM is opened.
-
-
-
-
-
+
+
The parser is very strict. All numbers are hexadecimal. Always prefix a number with # for an immediate value, or $ for a memory address. If a memory address needs to be calculated use $[] with the calculation inside the brackets.
+
+
Registers A/X/Y are 8-bit unsigned values. Register P is the 16-bit program counter.
+
Flags evaluate to 1 if set, 0 if clear.
+
+
Connecting operators || or && combine boolean terms. Parentheses dictate order of operations.
+
+
Example conditions:
+
+
Break only if register A is less than value at memory address $0005:
+
A < $0005
+
+
Break only if the value at the indirect address is not equal to FF:
+
#FF != $[$10+($11*#100)]
+
+
Break only if flag N is clear or A is not equal to 00:
+
(N==#0 || A!=#0)
+
+
Break only when accessing a data from bank 2 (the condiition is relevant when using with Read/Write-type breakpoints):
+
T==#2
+
+
+
Bookmarks
+
+
A list of bookmarked addresses can be kept in the Address Bookmarks frame to make memory navigation easier. Simply type a hexadecimal address (or a convenient string, such as "NMI") and click "Add" to add it to your bookmarks. Alternatively, just left-click any address in the Disassembly window, and the address will appear in the Bookmark Add field, so you don't have to type it.
+
Next time you wish to go to this address just double click on the bookmark.
+
You can also name bookmarks.
+
When you exit the emulator, bookmarks are saved in a .deb file named after the ROM of the debugged game. Next time you return to debugging the game, the list of bookmarks will be automatically loaded from the file.
+
+
+
Inline Assembler
+
+
Open the inline assembler by left-clicking in the empty column to the left of the memory view.
+
+
The starting memory address is displayed in the PC field at the top of the inline assembler window. Type a line of assembly to add in the empty field just below this, and hit enter. The assembled code of your patch will appear below as you enter each line.
+
+
Click Apply to apply your patch to the ROM in memory. Click Undo to remove the last assembled line. After applying a patch, clicking Save will allow you to save this patch directly to the ROM file.
+
+
+
Other
+
+
If the ".DEB files" checkbox in the lower right corner of the debugger window is checked, the emulator will automatically save debug settings such as breakpoints and bookmarks in a .deb file alongside the NES ROM, and load these settings next time you open the ROM.
+
+
There is a "Rom Patcher" button that may be used to apply a small patch to a ROM, although Hex Editor is more convenient in general.
+
+
The "ROM offsets" option will display ROM offsets instead of CPU addresses in the Disassembly window.
+
+
The "Restore Original Window Size" button will restore the original size of the debugger window if you resized it manually.
+
+
The "Auto-open" checkbox causes the debugger window to open automatically whenever an NES ROM is opened.
This menu sets a default directory override for various files relating to FCEU.
-
-
Base Directory
-
sets the default directory FCEU will use. It will be the folder that FCEU creates all the sub folders (unless they are also overridden).
-
-
-
ROMS
-
where FCEU will look for ROMS by default. (What folder will appear when selecting the Files > Open...)
-
-
-
Battery Saves
-
where .sav files will stored and opened from. These files contain the battery backed SRAM used in some games (such as Dragon Warrior).
-
-
-
Save States
-
where .fcs (savestate) files will be stored.
-
-
-
FDS BIOS ROM
-
where FCEU can find disksys.rom. disksys.rom is a required file in order to load FDS (Famicom Disk System) games. If not specified, FCEUX will default to the base directory.
-
-
-
Screenshots
-
where screen captures (.png) files will be saved.
-
-
-
Save Screenshots as "<filebase>-<x>.png"
-
sets how the .png files will be named. Left unchecked, the file names will simply be 0.png, 1.png etc. Checked adds the ROM name into the file as well (such as Double Dragon 2 (U)-0.png)
-
-
-
Cheats
-
where .cht files will be stored. .cht files store the active cheats set up in Cheat Search.
-
-
-
Movies
-
where .fm2 files will be saved/loaded. These files are the input files used in movie recording.
-
-
-
Memory Watch
-
where memory watch files are saved/loaded. These are used by memory watch.
-
-
-
Input Presets
-
where input presets will be saved/loaded. These are used in the presets section on the input config window.
-
-
-
Lua Scripts
-
where Lua scripts will be saved/loaded. These are used when using the Lua Scripting tool.
-
-
-
AVI Output
-
overrides which directory FCEUX will default to when saving a .avi file.
This menu sets a default directory override for various files relating to FCEU.
+
+
Base Directory
+
sets the default directory FCEU will use. It will be the folder that FCEU creates all the sub folders (unless they are also overridden).
+
+
+
ROMS
+
where FCEU will look for ROMS by default. (What folder will appear when selecting the Files > Open...)
+
+
+
Battery Saves
+
where .sav files will stored and opened from. These files contain the battery backed SRAM used in some games (such as Dragon Warrior).
+
+
+
Save States
+
where .fcs (savestate) files will be stored.
+
+
+
FDS BIOS ROM
+
where FCEU can find disksys.rom. disksys.rom is a required file in order to load FDS (Famicom Disk System) games. If not specified, FCEUX will default to the base directory.
+
+
+
Screenshots
+
where screen captures (.png) files will be saved.
+
+
+
Save Screenshots as "<filebase>-<x>.png"
+
sets how the .png files will be named. Left unchecked, the file names will simply be 0.png, 1.png etc. Checked adds the ROM name into the file as well (such as Double Dragon 2 (U)-0.png)
+
+
+
Cheats
+
where .cht files will be stored. .cht files store the active cheats set up in Cheat Search.
+
+
+
Movies
+
where .fm2 files will be saved/loaded. These files are the input files used in movie recording.
+
+
+
Memory Watch
+
where memory watch files are saved/loaded. These are used by memory watch.
+
+
+
Input Presets
+
where input presets will be saved/loaded. These are used in the presets section on the input config window.
+
+
+
Lua Scripts
+
where Lua scripts will be saved/loaded. These are used when using the Lua Scripting tool.
+
+
+
AVI Output
+
overrides which directory FCEUX will default to when saving a .avi file.
FCEUX was started in 2006 by zeromus and rheiny (sp) as an attempt to merge various branches of FCE Ultra into a unified emulator. Additional authors joined the project, including mz, adelikat, nitsujrehtona, maximus, CaH4e3, qFox, punkrockguy318, Sebastian Porst, AnS, feos, and rainwarrior.
-
-
FCEUX contains all features and enhancements from FCE, FCE Ultra, FCEU rerecording, FCEUXD, and FCEUXDSP as well as many new mappers from FCEU-mm.
Look at the Side Bar navigation for changelog information on FCEUX 2.1 and newer.
-
-
FCEUX 2.0.3 - Released November 02, 2008 (see changelog)
-
-
FCEUX 2.0.2 - Released August 14, 2008 (see changelog)
-
-
FCEUX 2.0.1 - Released August 04, 2008 (see changelog)
-
-
FCEUX 2.0.0 - Released August 02, 2008 (see changelog)
-
-
FCE / FCEUltra
-
-
Bero originally wrote a Nintendo Entertainment System/Famicom emulator that was referred to as FCE. This name was apparently meant only to serve as a temporary name, but its usage remained. Xodnizel originally ported it to Linux SVGAlib, and made a few improvements. This code base was abandoned, and work began anew, under DOS, with the original FCE source code. At the end of November, 1998, FCE Ultra Beta 1 was released.
-
-
FCE Ultra remained DOS-only until version 0.18, when it was ported to Linux SVGAlib, and released as a statically-linked executable. The first MS Windows port was released as version 0.25.
-
-
The source code of 0.40 was released on November 12, 2000. It retained the simple license of FCE for a long time, which stated that "This software is freeware. You can use it non-commercially." Almost two years later, in June 2002, 0.80 was released, and FCE Ultra was re-licensed under the GNU GPL.
-
-
It has been tested (and runs) under DOS, Linux SVGAlib, Linux X, Mac OS X, and Windows. A native GUI is provided for the Windows port, and the other ports use a command-line interface. The SDL port should run on any modern UNIX-like operating system (such as FreeBSD, Solaris or IRIX) with no code changes. It has also been ported to the GP2X, PlayStation Portable as PSPFceUltra, the Nintendo GameCube and Pepper Pad.
-
-
FCE Ultra was created by Xodnizel. Development appeared to stop and the homepage and forums for the emulator were taken down. The last version before this was v0.98.13-pre, released in September 2004 as source-only. The last binary release was v0.98.12 in August 2004.
-
-
However, it was resurrected again in March of 2006 by Anthony Giorgio and Mark Doliner.
-
-
There is also a graphical frontend for FCE Ultra. GFCE Ultra is written in Python and uses the GTK2 user interface library. Because is it written in Python and with portability in mind, it can be run on any UNIX-like platform and any processor architecture that is supported by Python.
-
-
-
FCEU Rerecording
-
-
The "rerecording" version of FCE Ultra was implemented to FCE Ultra 0.98.10 with movie recording support. This was done by blip, and was implemented for the purpose of creating Tool-Assisted Speedruns.
-
-
The rerecording branch continued with 0.98.12, adding movie support features, such as "bullet proof" recording. In 2006, FCEU 0.98.16 was implemented by nitsuja and luke. Various tools such as read-only toggling, increased hotkey mapping, and memory watch were added.
-
-
In 2008, FCEU rerecording was picked up again by mz, maximus, adelikat, and nitsujrehtona with various updates named FCEU.0.98.17 - 0.98.28
In 2002, Parasyte modified the then-current version (0.81.3) of FCE Ultra and added a Nesten-style debugger, along with several other features, and named it "FCEUD" (FCE Ultra Debugger).
-
-
FCEUXD
-
In January 2004, bbitmaster began working on more features and called it "FCEUXD" (FCE Ultra Extended Debugger).
-
It is a branch of FCE Ultra that contains many extended debugging features compared to the original FCE Ultra code such as a trace logger, a built-in hex editor, a name table viewer, code/data logger, inline assembler, and Game Genie decoder/encoder in addition to the debugger and PPU viewer from FCEUD. The last version made was FCEUXD 1.0a.
-
-
FCEUXDSP
-
FCEUXDSP stands for FCEUXD "SP" version and is a branch of FCEUXD 1.0a.
-
It was created in 2006 by sp. The project extends the debugging tools even further compared to FCEUXD by adding new tools, functions, and usability of debugging tools.
-
-
The last version of FCEUXDSP was 1.07 which adds a feature known as the RAM Filter. This has since been removed, due to functional redundancy.
FCEU "mappers modified" is an unofficial build of FCEU Ultra by CaH4e3, which supports a lot of new mappers including some obscure mappers such as one for unlicensed NES ROM's.
-
-
FCEUX supports mappers from older versions of FCEU-mm.
FCEUX was started in 2006 by zeromus and rheiny (sp) as an attempt to merge various branches of FCE Ultra into a unified emulator. Additional authors joined the project, including mz, adelikat, nitsujrehtona, maximus, CaH4e3, qFox, punkrockguy318, Sebastian Porst, AnS, feos, and rainwarrior.
+
+
FCEUX contains all features and enhancements from FCE, FCE Ultra, FCEU rerecording, FCEUXD, and FCEUXDSP as well as many new mappers from FCEU-mm.
Look at the Side Bar navigation for changelog information on FCEUX 2.1 and newer.
+
+
FCEUX 2.0.3 - Released November 02, 2008 (see changelog)
+
+
FCEUX 2.0.2 - Released August 14, 2008 (see changelog)
+
+
FCEUX 2.0.1 - Released August 04, 2008 (see changelog)
+
+
FCEUX 2.0.0 - Released August 02, 2008 (see changelog)
+
+
FCE / FCEUltra
+
+
Bero originally wrote a Nintendo Entertainment System/Famicom emulator that was referred to as FCE. This name was apparently meant only to serve as a temporary name, but its usage remained. Xodnizel originally ported it to Linux SVGAlib, and made a few improvements. This code base was abandoned, and work began anew, under DOS, with the original FCE source code. At the end of November, 1998, FCE Ultra Beta 1 was released.
+
+
FCE Ultra remained DOS-only until version 0.18, when it was ported to Linux SVGAlib, and released as a statically-linked executable. The first MS Windows port was released as version 0.25.
+
+
The source code of 0.40 was released on November 12, 2000. It retained the simple license of FCE for a long time, which stated that "This software is freeware. You can use it non-commercially." Almost two years later, in June 2002, 0.80 was released, and FCE Ultra was re-licensed under the GNU GPL.
+
+
It has been tested (and runs) under DOS, Linux SVGAlib, Linux X, Mac OS X, and Windows. A native GUI is provided for the Windows port, and the other ports use a command-line interface. The SDL port should run on any modern UNIX-like operating system (such as FreeBSD, Solaris or IRIX) with no code changes. It has also been ported to the GP2X, PlayStation Portable as PSPFceUltra, the Nintendo GameCube and Pepper Pad.
+
+
FCE Ultra was created by Xodnizel. Development appeared to stop and the homepage and forums for the emulator were taken down. The last version before this was v0.98.13-pre, released in September 2004 as source-only. The last binary release was v0.98.12 in August 2004.
+
+
However, it was resurrected again in March of 2006 by Anthony Giorgio and Mark Doliner.
+
+
There is also a graphical frontend for FCE Ultra. GFCE Ultra is written in Python and uses the GTK2 user interface library. Because is it written in Python and with portability in mind, it can be run on any UNIX-like platform and any processor architecture that is supported by Python.
+
+
+
FCEU Rerecording
+
+
The "rerecording" version of FCE Ultra was implemented to FCE Ultra 0.98.10 with movie recording support. This was done by blip, and was implemented for the purpose of creating Tool-Assisted Speedruns.
+
+
The rerecording branch continued with 0.98.12, adding movie support features, such as "bullet proof" recording. In 2006, FCEU 0.98.16 was implemented by nitsuja and luke. Various tools such as read-only toggling, increased hotkey mapping, and memory watch were added.
+
+
In 2008, FCEU rerecording was picked up again by mz, maximus, adelikat, and nitsujrehtona with various updates named FCEU.0.98.17 - 0.98.28
In 2002, Parasyte modified the then-current version (0.81.3) of FCE Ultra and added a Nesten-style debugger, along with several other features, and named it "FCEUD" (FCE Ultra Debugger).
+
+
FCEUXD
+
In January 2004, bbitmaster began working on more features and called it "FCEUXD" (FCE Ultra Extended Debugger).
+
It is a branch of FCE Ultra that contains many extended debugging features compared to the original FCE Ultra code such as a trace logger, a built-in hex editor, a name table viewer, code/data logger, inline assembler, and Game Genie decoder/encoder in addition to the debugger and PPU viewer from FCEUD. The last version made was FCEUXD 1.0a.
+
+
FCEUXDSP
+
FCEUXDSP stands for FCEUXD "SP" version and is a branch of FCEUXD 1.0a.
+
It was created in 2006 by sp. The project extends the debugging tools even further compared to FCEUXD by adding new tools, functions, and usability of debugging tools.
+
+
The last version of FCEUXDSP was 1.07 which adds a feature known as the RAM Filter. This has since been removed, due to functional redundancy.
FCEU "mappers modified" is an unofficial build of FCEU Ultra by CaH4e3, which supports a lot of new mappers including some obscure mappers such as one for unlicensed NES ROM's.
+
+
FCEUX supports mappers from older versions of FCEU-mm.
Various toggle boxes related to the FCEUX main window.
-
-
-
Load "File Open" dialog when FCEUX starts.
-
-
If enabled, FCEUX will ask for a ROM to open upon FCEUX start up.
-
-
-
Automatically hide menu on game load.
-
-
If enabled, the FCEU Menu will be hidden while a ROM is loaded. To unhide it, press the ESC key.
-
-
-
Ask confirmation on exit attempt.
-
-
If enabled, FCEUX will ask you before closing the window. (It may also say some other things...)
-
-
-
Disable screen saver while game is loaded.
-
-
This is enabled by default. If a game is running, the windows screen saver will not turn on.
-
-
-
Enable right-click context menu.
-
-
This is enabled by default. This allows you to right-click on the emulator to get context menus. The context menu gives many common options for a given situation and has a few options not available otherwise.
-
-
-
Switch fullscreen by double-click
-
-
If enabled, you may switch between fullscreen mode and windowed mode by a double-click on the emulator.
If enabled, dialog windows in FCEUX will use classic Visual Theme (a la Windows98 interface).
-
-
-
Single Instance Mode
-
-
If enabled, starting a second copy of FCEUX with a path to a game will make FCEUX load the file into the first window, then exit. This will ensure that only one instance of FCEUX is running in your OS.
Various toggle boxes related to the FCEUX main window.
+
+
+
Load "File Open" dialog when FCEUX starts.
+
+
If enabled, FCEUX will ask for a ROM to open upon FCEUX start up.
+
+
+
Automatically hide menu on game load.
+
+
If enabled, the FCEU Menu will be hidden while a ROM is loaded. To unhide it, press the ESC key.
+
+
+
Ask confirmation on exit attempt.
+
+
If enabled, FCEUX will ask you before closing the window. (It may also say some other things...)
+
+
+
Disable screen saver while game is loaded.
+
+
This is enabled by default. If a game is running, the windows screen saver will not turn on.
+
+
+
Enable right-click context menu.
+
+
This is enabled by default. This allows you to right-click on the emulator to get context menus. The context menu gives many common options for a given situation and has a few options not available otherwise.
+
+
+
Switch fullscreen by double-click
+
+
If enabled, you may switch between fullscreen mode and windowed mode by a double-click on the emulator.
If enabled, dialog windows in FCEUX will use classic Visual Theme (a la Windows98 interface).
+
+
+
Single Instance Mode
+
+
If enabled, starting a second copy of FCEUX with a path to a game will make FCEUX load the file into the first window, then exit. This will ensure that only one instance of FCEUX is running in your OS.
This will take an NES address space PRG address ($8000-$FFFF), a comparison value (for 8-letter GG codes; refer to a Game Genie code FAQ for an explanation of what this does), and a Value that replaces the addressed byte.
-
-
Filling in the Address and Value fields will produce a 6-letter code; if you also fill out the Compare field, it will produce an 8-letter code. The code so produced will appear in the Game Genie Code box immediately; you can then click "Add to Cheat List" to activate it.
-
-
To decrypt a Game Genie code, enter it into the Game Genie Code box, and the Address and Value fields will be automatically filled in, as will the Compare field if it was an 8-letter code.
-
-
Adding Game Genie codes
-
-
In the Game Genie Code Decoder/Encoder window, type the code into the Game Genie Code box and click "Add to Cheat List", which will add it to the Cheat Search cheat list. You can then enable/disable them by double-clicking the code in the box (a * means the code is active).
-
-
-
Making Game Genie codes permanent
-
-
Using the Game Genie Code Decoder/Encoder, enter in your code in the "Game Genie Code" box, and under "Possible Affected ROM File Addresses", a list of possible matches (usually from 1 to 5) is displayed. Using the built-in Hex Editor, go to the first listed address in the ROM, and change its value to the value given in the "Value" box (of the GG code Decoder/Encoder window). If the desired effect isn't achieved, undo the change (Ctrl+Z) and try the next address. Repeat until the desired effect is achieved, and then save the ROM.
-
-
-
How do I make my own Game Genie codes?
-
-
First of all, you must:
-
-
* have a decent amount of ASM knowledge;
-
* know how to use the debugger;
-
* understand NES PRG-ROM bank switching.
-
-
Once you've found a part of PRG-ROM you want to change to create a code effect, snap the Debugger (if it's not so already) and find the code's location in the PRG-ROM's address space ($8000-$FFFF) (you'll want the debugger snapped so the game won't swap banks out from under you). Then, using the built-in Hex Editor, view the NES memory and go to the PRG-ROM address you wish to modify, then right-click the byte and choose "Create Game Genie Code at this Address". The Game Genie Code Decoder/Encoder will appear, with the Address and Compare boxes filled in (the Compare box represents the address's original value). Enter the new value into the "Value" box.
-
-
An alternative way to enter the code is to locate the desired address in the debugger, and then middle-click on it, which will summon the GG Code Decoder/Encoder. Then enter the code as described above.
This will take an NES address space PRG address ($8000-$FFFF), a comparison value (for 8-letter GG codes; refer to a Game Genie code FAQ for an explanation of what this does), and a Value that replaces the addressed byte.
+
+
Filling in the Address and Value fields will produce a 6-letter code; if you also fill out the Compare field, it will produce an 8-letter code. The code so produced will appear in the Game Genie Code box immediately; you can then click "Add to Cheat List" to activate it.
+
+
To decrypt a Game Genie code, enter it into the Game Genie Code box, and the Address and Value fields will be automatically filled in, as will the Compare field if it was an 8-letter code.
+
+
Adding Game Genie codes
+
+
In the Game Genie Code Decoder/Encoder window, type the code into the Game Genie Code box and click "Add to Cheat List", which will add it to the Cheat Search cheat list. You can then enable/disable them by double-clicking the code in the box (a * means the code is active).
+
+
+
Making Game Genie codes permanent
+
+
Using the Game Genie Code Decoder/Encoder, enter in your code in the "Game Genie Code" box, and under "Possible Affected ROM File Addresses", a list of possible matches (usually from 1 to 5) is displayed. Using the built-in Hex Editor, go to the first listed address in the ROM, and change its value to the value given in the "Value" box (of the GG code Decoder/Encoder window). If the desired effect isn't achieved, undo the change (Ctrl+Z) and try the next address. Repeat until the desired effect is achieved, and then save the ROM.
+
+
+
How do I make my own Game Genie codes?
+
+
First of all, you must:
+
+
* have a decent amount of ASM knowledge;
+
* know how to use the debugger;
+
* understand NES PRG-ROM bank switching.
+
+
Once you've found a part of PRG-ROM you want to change to create a code effect, snap the Debugger (if it's not so already) and find the code's location in the PRG-ROM's address space ($8000-$FFFF) (you'll want the debugger snapped so the game won't swap banks out from under you). Then, using the built-in Hex Editor, view the NES memory and go to the PRG-ROM address you wish to modify, then right-click the byte and choose "Create Game Genie Code at this Address". The Game Genie Code Decoder/Encoder will appear, with the Address and Compare boxes filled in (the Compare box represents the address's original value). Enter the new value into the "Value" box.
+
+
An alternative way to enter the code is to locate the desired address in the debugger, and then middle-click on it, which will summon the GG Code Decoder/Encoder. Then enter the code as described above.
FCEUX supports the iNES, FDS(raw and with a header), UNIF, and NSF file formats. FDS ROM images in the iNES format are not supported; it would be silly to do so and storing them in that format is nonsensical.
-
-
FCEUX supports loading ROM/disk images from some types of compressed files. FCEUX can load data from both PKZIP-format files and gzip-format files. Only the "deflate" algorithm is supported, but this is the most widely used algorithm for these formats.
-
-
Playing from compressed (.zip) files
-
-
FCEUX is compatible with all compression types compatible with 7z. Compatible types include .7z, .zip, .rar, and .tar.
-
-
If an archive file is opened, it will be scanned for the followings extensions: .nes, .fds, .nsf, .unf, .nez, .unif. If more than one valid type is detected, a dialog box will open up with a list of available choices.
-
-
Automatic IPS Patching (Playing Hacked Games)
-
-
FCEUX supports automatic IPS patching.
-
-
Place the IPS file in the same directory as the file to load, and name it [filename.extension].ips.
-
-
Examples: Boat.nes - Boat.nes.ips
-
Boat.zip - Boat.zip.ips
-
Boat.nes.gz - Boat.nes.gz.ips
-
Boat - Boat.ips
-
-
-
(Some operating systems and environments will hide file extensions. Keep this in mind if you are having trouble.)
-
-
Patching is supported for all supported formats (iNES, FDS, UNIF, and NSF), but it will probably only be useful for the iNES and FDS formats. UNIF files can't be patched well with the IPS format because they are chunk-based with no fixed offsets.
FCEUX supports the iNES, FDS(raw and with a header), UNIF, and NSF file formats. FDS ROM images in the iNES format are not supported; it would be silly to do so and storing them in that format is nonsensical.
+
+
FCEUX supports loading ROM/disk images from some types of compressed files. FCEUX can load data from both PKZIP-format files and gzip-format files. Only the "deflate" algorithm is supported, but this is the most widely used algorithm for these formats.
+
+
Playing from compressed (.zip) files
+
+
FCEUX is compatible with all compression types compatible with 7z. Compatible types include .7z, .zip, .rar, and .tar.
+
+
If an archive file is opened, it will be scanned for the followings extensions: .nes, .fds, .nsf, .unf, .nez, .unif. If more than one valid type is detected, a dialog box will open up with a list of available choices.
+
+
Automatic IPS Patching (Playing Hacked Games)
+
+
FCEUX supports automatic IPS patching.
+
+
Place the IPS file in the same directory as the file to load, and name it [filename.extension].ips.
+
+
Examples:Boat.nes - Boat.nes.ips
+
Boat.zip - Boat.zip.ips
+
Boat.nes.gz - Boat.nes.gz.ips
+
Boat - Boat.ips
+
+
+
(Some operating systems and environments will hide file extensions. Keep this in mind if you are having trouble.)
+
+
Patching is supported for all supported formats (iNES, FDS, UNIF, and NSF), but it will probably only be useful for the iNES and FDS formats. UNIF files can't be patched well with the IPS format because they are chunk-based with no fixed offsets.
The most basic function of FCEUX is to play Nintendo Entertainment System (NES) and Famicom Disk System (FDS) games.
-
-
To play a game, simply open a ROM by selecting "Open" in the File Menu (or press Ctrl+O). (See Game Compatibility for information regarding file types that are compatible with FCEU.)
-
-
To get set up properly, you may need to configure any of the following:
In emulation, a savestate (alternatively called freeze state or game freeze) is a snapshot of all of an emulated device's state information at a given moment. This makes it possible to pause emulation, and restart it later, even in another instance of the emulator, or to test the emulated machines reaction to different series of inputs using the saved state as a common starting point.
-
-
To make a savestate press shift + F1-F10 to save to a save slot (0-9). Or select a save slot with the number keys (0-9) and select the quick save command (Default hotkey is "I")
-
-
To load a savestate press F1-F10. Or select a save slot with the number keys (0-9) and loadstate by navigating to File > Savestate > Loadstate or by pressing the loadstate hotkey (Default hotkey is "P").
-
-
To save a state to a specific file, go to "Save state as..." in the FCEUX File menu.
-
-
To load a specific savestate file, go to the "Load state from..." in the FCEUX File menu.
-
-
-
Undo Savestate / Loadstate
-
-
If you load a state by accident, you can right-click and select "Undo Loadstate" to restore the emulator back to the state it was in before the loadstate. Upon using undo loadstate, a redo loadstate will appear as an option.
-
-
If you make a savestate, it will overwrite the existing savestate for that slot. You have the option to undo this and restore the previous savestate file by right-clicking and selecting undo savestate. Once you undo, you will have the option to redo savestate to restore the savestate that you made. You can also map a hotkey to this function, by default it's mapped to Ctrl+Z.
The most basic function of FCEUX is to play Nintendo Entertainment System (NES) and Famicom Disk System (FDS) games.
+
+
To play a game, simply open a ROM by selecting "Open" in the File Menu (or press Ctrl+O). (See Game Compatibility for information regarding file types that are compatible with FCEU.)
+
+
To get set up properly, you may need to configure any of the following:
In emulation, a savestate (alternatively called freeze state or game freeze) is a snapshot of all of an emulated device's state information at a given moment. This makes it possible to pause emulation, and restart it later, even in another instance of the emulator, or to test the emulated machines reaction to different series of inputs using the saved state as a common starting point.
+
+
To make a savestate press shift + F1-F10 to save to a save slot (0-9). Or select a save slot with the number keys (0-9) and select the quick save command (Default hotkey is "I")
+
+
To load a savestate press F1-F10. Or select a save slot with the number keys (0-9) and loadstate by navigating to File > Savestate > Loadstate or by pressing the loadstate hotkey (Default hotkey is "P").
+
+
To save a state to a specific file, go to "Save state as..." in the FCEUX File menu.
+
+
To load a specific savestate file, go to the "Load state from..." in the FCEUX File menu.
+
+
+
Undo Savestate / Loadstate
+
+
If you load a state by accident, you can right-click and select "Undo Loadstate" to restore the emulator back to the state it was in before the loadstate. Upon using undo loadstate, a redo loadstate will appear as an option.
+
+
If you make a savestate, it will overwrite the existing savestate for that slot. You have the option to undo this and restore the previous savestate file by right-clicking and selecting undo savestate. Once you undo, you will have the option to redo savestate to restore the savestate that you made. You can also map a hotkey to this function, by default it's mapped to Ctrl+Z.
The Hex Editor is a very powerful memory viewing/editing tool, it obsoletes the Memory Viewer tool from the FCE Ultra and FCEU Rerecording branches.
-
-
It can do a wide range of things. It allows you to view the entire RAM & ROM contents in a resizable dialog window. It makes it easy to edit the game's RAM, PPU memory, and even its currently-loaded ROM data by simply typing in values in the editor. You can also "freeze" parts of RAM (to prevent the game from modifying the data there), search for data (Ctrl+F), and even copy and paste data to/from the clipboard. Furthermore, table files are supported, so you can edit a game's text in real-time and see the result immediately.
-
-
Basically, it lets you tinker with any part of a game's RAM or ROM while it is running.
-
-
Using the Hex Editor
-
-
The Hex Editor lets you edit three major areas:
-
-
1. NES MEMORY
-
This allows you to directly edit all of the NES address space (System Bus - $0000-$FFFF). While you can easily modify RAM, or write directly to registers by typing in data, you cannot modify ROM data ($8000-$FFFF) itself. This is because most mappers have registers which are located in this space; so writing there can trigger mapper operations that may cause the game to crash or glitch if you don't know what you're doing. If you want to edit the ROM itself, right-click on the offset and select "Go here in ROM file"; that will take you directly to where you need to be so you can start editing. You can also freeze RAM by clicking on it with the middle mouse button, or by using the right-click menu. This works by adding it directly to the Cheat List, which you can see from the Cheat Console. Finally, the right-click menu can be used to quickly add a read or write breakpoint to the debugger. When adding a breakpoint to the range of ROM addresses ($8000-$FFFF), the Hex Editor also takes into account the number of the bank in which the byte is located.
-
-
2. PPU MEMORY
-
This allows you to directly view and write to PPU memory (VRAM).
-
-
3. OAM MEMORY
-
This allows you to directly view and write to OAM memory (sprite RAM).
-
-
4. THE ROM FILE
-
This allows you to edit the ROM file in real time, i.e. while the game is running. If you make a mistake, press Ctrl+Z or Edit->Undo to undo your change (then load a save-state if the game crashed).
-
-
The Hex Editor also has support for table files (*.tbl) to map bytes to text. Each line consists of four characters of the form "xx=y", where "xx" is the hex value, and "y" is the character that that value represents. I have also added an extension to represent the Return key: xx=ret whereby pressing the Return key will enter that value into the ROM. You can copy/paste data or text by selecting it and using Ctrl+C (to copy) and Ctrl+V (to paste). Plus, there is an Edit->Find feature that you can use to search for data. This feature should be fairly intuitive, so I won't bother to explain it.
-
-
When you're done editing, remember to save the ROM file (File->Save) or your changes will be lost when you close the ROM.
-
-
Why can't I edit NES memory beyond $8000?
-
-
NES memory from $8000-$FFFF is where the game's PRG-ROM code is mapped. Whenever you type in a value in the NES memory editor, it effectively writes that value to that address. Many games use mappers, which are usually accessed by writing to $8000-$FFFF (which is read-only)... and if *you* were to do so, it may trigger a bankswitch, which could easily make the game crash. In any event, doing so will not modify the ROM itself. What you *can* do, though, is edit the PRG-ROM itself by right-clicking on the offset you wish to edit, and selecting "Go here in the ROM file", which should take you to that spot in the ROM instead, where you can change the data at instead.
-
-
Highlighting
-
-
The Hex Editor highlights certain bytes with different colors to help you distinguish different data.
-
Usually all bytes are colored black.
-
Bookmarked RAM addresses are highlighted by green color.
-
Freezed RAM addresses are highlighted by blue color.
-
Modified ROM bytes are highlighted by red color.
-
If you have the Code/Data Logger running, bytes that were logged will be colored:
-
For PRG ROM segment:
-
Dark-yellow - the byte is code
-
Blue - the byte is data
-
Cyan - the byte is PCM audio data
-
Green - the byte is both code and data
-
For CHR ROM segment:
-
Yellow - the byte was rendered
-
Light-blue - the byte was read programmatically
-
Light-green - the byte was both rendered and read programmatically
-
-
Highlight Activity
-
-
This feature of the Hex Editor can draw your attention to bytes that changed their value since the last frame, or since the last update of Hex Editor window (if "Fade when paused" option is enabled).
-
If you don't need this feature, you can switch it off in the "Highlighting" submenu.
-
You can customize this feature by changing "fading period".
-
IMPORTANT NOTE: this feature does not track the actual changes of RAM. It works by simply comparing current values to previously displayed values of the same addresses. That's why the feature works with RAM/PPU/OAM/ROM as well.
The Hex Editor is a very powerful memory viewing/editing tool, it obsoletes the Memory Viewer tool from the FCE Ultra and FCEU Rerecording branches.
+
+
It can do a wide range of things. It allows you to view the entire RAM & ROM contents in a resizable dialog window. It makes it easy to edit the game's RAM, PPU memory, and even its currently-loaded ROM data by simply typing in values in the editor. You can also "freeze" parts of RAM (to prevent the game from modifying the data there), search for data (Ctrl+F), and even copy and paste data to/from the clipboard. Furthermore, table files are supported, so you can edit a game's text in real-time and see the result immediately.
+
+
Basically, it lets you tinker with any part of a game's RAM or ROM while it is running.
+
+
Using the Hex Editor
+
+
The Hex Editor lets you edit three major areas:
+
+
1. NES MEMORY
+
This allows you to directly edit all of the NES address space (System Bus - $0000-$FFFF). While you can easily modify RAM, or write directly to registers by typing in data, you cannot modify ROM data ($8000-$FFFF) itself. This is because most mappers have registers which are located in this space; so writing there can trigger mapper operations that may cause the game to crash or glitch if you don't know what you're doing. If you want to edit the ROM itself, right-click on the offset and select "Go here in ROM file"; that will take you directly to where you need to be so you can start editing. You can also freeze RAM by clicking on it with the middle mouse button, or by using the right-click menu. This works by adding it directly to the Cheat List, which you can see from the Cheat Console. Finally, the right-click menu can be used to quickly add a read or write breakpoint to the debugger. When adding a breakpoint to the range of ROM addresses ($8000-$FFFF), the Hex Editor also takes into account the number of the bank in which the byte is located.
+
+
2. PPU MEMORY
+
This allows you to directly view and write to PPU memory (VRAM).
+
+
3. THE ROM FILE
+
This allows you to edit the ROM file in real time, i.e. while the game is running. If you make a mistake, press Ctrl+Z or Edit->Undo to undo your change (then load a save-state if the game crashed).
+
+
The Hex Editor also has support for table files (*.tbl) to map bytes to text. Each line consists of four characters of the form "xx=y", where "xx" is the hex value, and "y" is the character that that value represents. I have also added an extension to represent the Return key: xx=ret whereby pressing the Return key will enter that value into the ROM. You can copy/paste data or text by selecting it and using Ctrl+C (to copy) and Ctrl+V (to paste). Plus, there is an Edit->Find feature that you can use to search for data. This feature should be fairly intuitive, so I won't bother to explain it.
+
+
When you're done editing, remember to save the ROM file (File->Save) or your changes will be lost when you close the ROM.
+
+
Why can't I edit NES memory beyond $8000?
+
+
NES memory from $8000-$FFFF is where the game's PRG-ROM code is mapped. Whenever you type in a value in the NES memory editor, it effectively writes that value to that address. Many games use mappers, which are usually accessed by writing to $8000-$FFFF (which is read-only)... and if *you* were to do so, it may trigger a bankswitch, which could easily make the game crash. In any event, doing so will not modify the ROM itself. What you *can* do, though, is edit the PRG-ROM itself by right-clicking on the offset you wish to edit, and selecting "Go here in the ROM file", which should take you to that spot in the ROM instead, where you can change the data at instead.
+
+
Highlighting
+
+
The Hex Editor highlights certain bytes with different colors to help you distinguish different data.
+
Usually all bytes are colored black.
+
Bookmarked RAM addresses are highlighted by green color.
+
Freezed RAM addresses are highlighted by blue color.
+
Modified ROM bytes are highlighted by red color.
+
If you have the Code/Data Logger running, bytes that were logged will be colored:
+
For PRG ROM segment:
+
Dark-yellow - the byte is code
+
Blue - the byte is data
+
Cyan - the byte is PCM audio data
+
Green - the byte is both code and data
+
For CHR ROM segment:
+
Yellow - the byte was rendered
+
Light-blue - the byte was read programmatically
+
Light-green - the byte was both rendered and read programmatically
+
+
Highlight Activity
+
+
This feature of the Hex Editor can draw your attention to bytes that changed their value since the last frame, or since the last update of Hex Editor window (if "Fade when paused" option is enabled).
+
If you don't need this feature, you can switch it off in the "Highlighting" submenu.
+
You can customize this feature by changing "fading period".
+
IMPORTANT NOTE: this feature does not track the actual changes of RAM. It works by simply comparing current values to previously displayed values of the same addresses. That's why the feature works with RAM/PPU/ROM as well.
On the pull down menus, you can select the device you want to be emulated on input ports 1 and 2 (game pad, zapper, pad, paddle). Note: you can't change this setting while a movie is being played or recorded.
-
If you check the box labeled "Attach four-score(implies four gamepads)", you won't be able to select any of these options, because the four-score allows to use 2 extra controllers.
-
The device currently being emulated on each port is listed above the drop down list; loading certain games will override your settings, but only temporarily.
-
-
To bind these controls to specific keys/joystick controls use the "configure" the device listed above each drop-down list.
-
-
Zapper / Arkanoid Paddle
-
-
Most Zapper NES games expect the Zapper to be plugged into port 2. and most VS Unisystem games expect the Zapper to be plugged into port 1.
-
-
The left mouse button is the emulated trigger button for the Zapper. The right mouse button is also emulated as the trigger, but as long as you have the right mouse button held down, no color detection will take place, which is effectively like pulling the trigger while the Zapper is pointed away from the television screen. Note that you must hold the right button down for a short time to have the desired effect.
-
-
The Arkanoid Paddle emulates the same way the zapper.
-
-
Power Pad A / B
-
-
Emulates the NES Power pad. The 12 pad buttons can be routed via the configure button. FCEUX allows up to 2 Power Pads to be emulated at once (Power Pad A and B).
-
-
Famicom Controllers
-
-
You can also select the input device to be emulated on the Famicom Expansion port. If you select a device for the Famicom Expansion Port, you should probably have emulated game pads on the emulated NES-style input ports.
-
-
In addition to the traditional famicom controller, FCEUX can emulate the Famicom version of the Arkanoid controller, the "Space Shadow" gun, the Famicom 4-player adapter, the Family Keyboard, the HyperShot controller, the Mahjong controller, the Oeka Kids tablet, the Quiz King buzzers, the Family Trainer, and the Barcode World barcode reader.
-
-
Replace Port 2 Start With Microphone
-
-
Checking this box will replace the Start button used by controller 2 with the microphone option found on the famicom. Pressing the Microphone button is like blowing or yelling into it on the console equipment. The Port 2 controller used for the Famicom included a microphone and a volume control in place of the Start and Select buttons. This option isn't automatically detected, so it has to be manually enabled by the user. Movie files may also enable and use this feature. Both Famicom Cartridges and Famicom Disks have made use of this feature, such as both the cartridge and disk version of Zelda 1, Hikari Shinwa, and Takeshi no Chosenjo. Games other than those listed here use this feature.
-
-
Input Presets
-
-
This feature allow you to set the current input configuration to one of three presets. This gives you the option to quickly change from one input configuration to another (such as toggling between 1 or 2 controllers and/or toggling from controller 2 being bound to controller 1 or having its own controls).
-
-
To assign the current input configuration to a preset press the down arrow next to one of the presets. To assign the preset as the current input configuration press the up arrow or use the hotkey assigned to that specific preset. Preset hotkeys can be assigned in the Map Hotkeys menu.
-
-
Disable left+right/up+down
-
-
By default FCEUX allows you to press both the left and right controls at the same time (or up and down). To disable this feature uncheck the checkbox on the left.
-
-
Auto-Hold
-
-
Clicking the auto hold button will allow you to assign a hotkey to the auto-hold feature.
-
Clicking the clear button will allow you to assign a hotkey to the clear auto-holds feature.
-
-
To use this feature, close the input config window and return to the FCEUX main window. Hold down the auto-hold hotkey and press one of your controller inputs. This will add it as one of the auto-hold assignments. The game will keep auto-hold assigned buttons held be default. Pressing one of these keys will release the button for the duration that it is held.
-
-
To turn off all auto-hold assignments press the clear auto-holds hotkey.
On the pull down menus, you can select the device you want to be emulated on input ports 1 and 2 (game pad, zapper, pad, paddle). Note: you can't change this setting while a movie is being played or recorded.
+
If you check the box labeled "Attach four-score(implies four gamepads)", you won't be able to select any of these options, because the four-score allows to use 2 extra controllers.
+
The device currently being emulated on each port is listed above the drop down list; loading certain games will override your settings, but only temporarily.
+
+
To bind these controls to specific keys/joystick controls use the "configure" the device listed above each drop-down list.
+
+
Zapper / Arkanoid Paddle
+
+
Most Zapper NES games expect the Zapper to be plugged into port 2. and most VS Unisystem games expect the Zapper to be plugged into port 1.
+
+
The left mouse button is the emulated trigger button for the Zapper. The right mouse button is also emulated as the trigger, but as long as you have the right mouse button held down, no color detection will take place, which is effectively like pulling the trigger while the Zapper is pointed away from the television screen. Note that you must hold the right button down for a short time to have the desired effect.
+
+
The Arkanoid Paddle emulates the same way the zapper.
+
+
Power Pad A / B
+
+
Emulates the NES Power pad. The 12 pad buttons can be routed via the configure button. FCEUX allows up to 2 Power Pads to be emulated at once (Power Pad A and B).
+
+
Famicom Controllers
+
+
You can also select the input device to be emulated on the Famicom Expansion port. If you select a device for the Famicom Expansion Port, you should probably have emulated game pads on the emulated NES-style input ports.
+
+
In addition to the traditional famicom controller, FCEUX can emulate the Famicom version of the Arkanoid controller, the "Space Shadow" gun, the Famicom 4-player adapter, the Family Keyboard, the HyperShot controller, the Mahjong controller, the Oeka Kids tablet, the Quiz King buzzers, the Family Trainer, and the Barcode World barcode reader.
+
+
Replace Port 2 Start With Microphone
+
+
Checking this box will replace the Start button used by controller 2 with the microphone option found on the famicom. Pressing the Microphone button is like blowing or yelling into it on the console equipment. The Port 2 controller used for the Famicom included a microphone and a volume control in place of the Start and Select buttons. This option isn't automatically detected, so it has to be manually enabled by the user. Movie files may also enable and use this feature. Both Famicom Cartridges and Famicom Disks have made use of this feature, such as both the cartridge and disk version of Zelda 1, Hikari Shinwa, and Takeshi no Chosenjo. Games other than those listed here use this feature.
+
+
Input Presets
+
+
This feature allow you to set the current input configuration to one of three presets. This gives you the option to quickly change from one input configuration to another (such as toggling between 1 or 2 controllers and/or toggling from controller 2 being bound to controller 1 or having its own controls).
+
+
To assign the current input configuration to a preset press the down arrow next to one of the presets. To assign the preset as the current input configuration press the up arrow or use the hotkey assigned to that specific preset. Preset hotkeys can be assigned in the Map Hotkeys menu.
+
+
Disable left+right/up+down
+
+
By default FCEUX allows you to press both the left and right controls at the same time (or up and down). To disable this feature uncheck the checkbox on the left.
+
+
Auto-Hold
+
+
Clicking the auto hold button will allow you to assign a hotkey to the auto-hold feature.
+
Clicking the clear button will allow you to assign a hotkey to the clear auto-holds feature.
+
+
To use this feature, close the input config window and return to the FCEUX main window. Hold down the auto-hold hotkey and press one of your controller inputs. This will add it as one of the auto-hold assignments. The game will keep auto-hold assigned buttons held be default. Pressing one of these keys will release the button for the duration that it is held.
+
+
To turn off all auto-hold assignments press the clear auto-holds hotkey.
LuaBot employs a new concept in FCEUX Tool creation. It is an external lua script that creates the Basic bot GUI. The GUI then uses lua scripting to perform botting tasks.
-
-
To run it you must have lua scripting enabled (see Getting Started). LuaBot is included in the lua pack under /luaScripts. to get started run luabot_framework.lua.
-
-
What is Lua Bot?
-
LuaBot is...well, a bot. It uses a combination of probability, scripting and RAM monitoring to play games. Specifically basic bot is used to create portions of Tool Assisted Speedrun. It is most powerful for finding solutions in highly random situations, or highly improbably events (such as manipulating a critical hit in an RPG). Basic bot comes with a rather powerful scripting language in order to be "programmed" to handle these specific situations. LuaBot in its most extreme application can even be "taught" to play video games!
-
-
-
How to Use Lua Bot
-
-
LuaBot is a trial and error script that exhausts the input-search-space by simply trying to push buttons.
-
-
You can program it to limit this searchspace, as it can become exponentially large. You can press eight possible buttons at any frame, each on or off. That's 2 raised to the 8, or 256 possible combinations in that one frame. There are 60 frames in one second, so you have 256 raised to the power of 60. Write a three. Now start writing 144 zeroes after it. It's not a small number.
-
-
Anyways, the bot has two parts. The frontend, which we'll call BeeBee, and the Lua part, which we call LuaBot.
-
-
You start the bot by opening the LuaBot_front.lua script file. Make sure the LuaBot_backend.lua file is in the same directory.
-
-
BeeBee
-
-
BeeBee (who received it's name from BasicBot, its predecessor) just writes it's contents into the LuaBot framework and produces a big Lua script for you.
-
All you need to do is enter Lua code for the specific functions and the code will generate the script.
-
-
You can also save and load the contents of the front-end. That way you can easily manage your bot scripts, without actually having to look into the LuaBot code.
-
-
BeeBee is only a pasting mechanism. It does not compile Lua or warn for errors.
-
-
LuaBot
-
-
LuaBot is a generic trial-and-error script that serves as a bot framework. It will set inputs as you program them for a number of frames (called an attempt). When the isAttemptEnd() says the attempt ends, a new attempt is started. All the attempts fall under one segment. At the end of a segment (denoted by the isSegmentEnd() function), the best attempt is kept (judged by the score and tie functions) and the next segment is started. The bot is capable of rolling back if a segment runs into a dead end. This allows you to backtrack and restart a previous segment.
-
-
The bot evaluates a true or false by checking to see whether the return value of a function is bigger then a certain value. It does this for EVERY function that returns something and every function that returns something must return a number (or Lua _will_ complain). For absolute true or false you can return "yes" and "no", "maxvalue" and "minvalue" or "pressed" and "released". Read variable info for more information.
-
-
The script takes a number of variables and functions into account. Some variables become important to prevent desyncing over segments.
-
-
- maxvalue
-
The maximum value (exclusive) of the random evaluation. If a value is higher than rand(minvalue, maxvalue), it evaluates as true, else false. By default this is set to 100.
-
-
- minvalue
-
The lowest value (inclusive) of the random evaluation. If a value is lower than rand(minvalue, maxvalue), it evaluates to false, else true. By default this is set to 0.
-
-
- yes / no
-
- pressed / released
-
These map to the minvalue/maxvalue.
-
-
- loopcounter
-
The number of times a frameadvance has been called by the main botloop.
-
-
- key1 key2 key3 key4
-
The input table of players 1-4. The keys are: A B up down left right select start. Set any to 1 if you want them to be set and to nil if you don't want them set.
-
Note that these get cleared right before onInputStart is called. This variable is saved in a pseudo-movie table if the attempt is better then the previous one and used for playback when moving to the next segment.
-
-
- lastkey1 lastkey2 lastkey3 lastkey4
-
The inputs that were given to FCEU on the PREVIOUS frame. This holds for segments as well (at the beginning of a new segment, the lastkeys of the previous segment are set). This also goes for the start. If you use key1-4 in onStart, the first segment will have those keys as lastkey.
-
-
- frame
-
The number of frames of the current attempt. Starts at 1.
-
-
- attempt
-
The number of attempts in the current segment. Starts at 1.
-
-
- segment
-
The segment the bot is currently running. Note that rolledback segments are deducted from this number.
-
-
- okattempts
-
The number of attempts that have been deemed ok. This is a statistical variable. It might tell you how well your bot is doing (combined with the number of failed attempts).
-
-
- failattempts
-
The number of attempts in the current segment that have been deemed bad. This is a statistical variable. It might tell you how well your bot is doing (combined with the number of approved attempts).
-
-
- segments
-
This is the big table that holds everything together. Don't mess with it.
-
-
- maxframes
-
You can set maxframes and check it in the isAttemptEnd function to simply limit a attempt by this many frames. You can also just ignore this and do something else instead.
-
-
- maxattempts
-
Same as maxframes, except for attempts in a segment.
-
-
- maxsegments
-
Same as maxframes, except for segments in a run.
-
-
- playingbest
-
Will be set to true when the bot is playing back it's best attempt to advance to the next segment. Not really used by other functions.
-
-
- keyrecording1-4
-
A simple table with the pressed keys for playback.
-
-
- X Y Z P Q
-
Some "static" variables. These allow you to easily set them onStart and use them in various functions to return the same number. Like a global variable. The P and Q numbers used to denote a random number between 0 and P or Q, but they don't right now.
-
-
- vars
-
This is your variable table. It's contents is saved at the end of an attempt and will be loaded at the beginning of a segment. On rollback, this table is also kept. Put any variable you want to keep across segments in this table.
-
-
-
Ok. That's it for the variables. Now for functions. There are basically three types of functions. The functions that determine whether a button is pressed (8 for each player), to determine whether an attempt/segment/run has ended or was ok and functions for certain events. This number is not evaluated by the random-eval function.
-
-
- getScore
-
This returns how "well" the current attempt is. At the end of a segment, the best scoring good attempt will be used to continue to the next segment. In case of a tie, see the tie functions. This number is not evaluated by the random-eval function!
-
-
- getTie1-4
-
If the score ends in a tie, that is, two attempts score equally well (have an equal number of points for instance), you can use these functions to break that tie. Like, which attempt has the most health or is the fastest or whatever. This number is not evaluated by the random-eval function!
-
-
- isRunEnd
-
Return whether the bot should stop running. If the returned number is bigger then the random number rand(minvalue-maxvalue), the bot will stop.
-
-
- mustRollBack
-
Returns whether the bot should rollback the current attempt. In such case, the previous segment is loaded and the current segment is completely discarded. If the returned number is bigger then the random number rand(minvalue-maxvalue), the segment will rollback one segment.
-
-
- isSegmentEnd
-
If the returned number is bigger then the random number rand(minvalue-maxvalue), the bot will stop the current segment, play back the best recorded attempt and start a new segment. Mostly done when a certain number of attempts is reached, but possibly you know when have the best possible attempt and can move on.
-
-
- isAttemptEnd
-
If the returned number is bigger then the random number rand(minvalue-maxvalue), the attempt will stop and a new attempt will be started. Some examples when this function should return yes is when you reached a certain goal, a number of frames or when you died (in which case the bot should try again :).
-
-
- isAttemptOk
-
If the returned number is bigger then the random number rand(minvalue-maxvalue), the current attempt (which has just ended) is deemed ok. Only attempts that are deemed ok are up for being saved. For instance, when the player died in the current attempt, you should return no.
-
-
- pressKeyX (pressKeyA1, pressKeyStart4, etc...)
-
These functions determine whether a button should be pressed in the next frame. If the returned number is bigger then the random number rand(minvalue-maxvalue), the button is pressed, otherwise it is not. To absolutely press a button, simply return yes or no. To use some odds, return a number between minvalue and maxvalue. For instance, using the default settings, if you return 50, there is a 50% chance the button will be pressed.
-
-
- onStart
-
Maybe a little misleading, but the onStart function is called BEFORE the main botloop starts. You can do some non-generic startup stuff here like press start at the title screen and get the game started. Returns nothing.
-
-
- onFinish
-
The opposite to onStart, this function is called when the main botloop exits. You can cleanup, or write stuff or whatever.
-
-
- onSegmentStart
-
When a new segment is started, this is called. After initializing variables and such, but before onAttemptStart is called. Returns nothing.
-
-
- onSegmentEnd
-
When isSegmentEnd evaluates to true, this function is called. Returns nothing.
-
-
- onAttemptStart
-
Called at the start of a new attempt, after onSegmentStart (in case of a new segment) but before onInputStart. Returns nothing.
-
-
- onAttemptEnd(wasOk)
-
Called at the end of an attempt. The only function to have a parameter (note: case sensitive). The parameter wasOk will return (boolean) whether isAttemptOk evaluated to true or false. Returns nothing.
-
-
- onInputStart
-
In a frame, this is the first place where the key1-4 variables are cleared. This is called before all the input (pressKeyX) functions are called. Returns nothing.
-
-
- onInputEnd
-
This is called immediately after the input (pressKeyX) functions have been called. Returns nothing.
LuaBot employs a new concept in FCEUX Tool creation. It is an external lua script that creates the Basic bot GUI. The GUI then uses lua scripting to perform botting tasks.
+
+
To run it you must have lua scripting enabled (see Getting Started). LuaBot is included in the lua pack under /luaScripts. to get started run luabot_framework.lua.
+
+
What is Lua Bot?
+
LuaBot is...well, a bot. It uses a combination of probability, scripting and RAM monitoring to play games. Specifically basic bot is used to create portions of Tool Assisted Speedrun. It is most powerful for finding solutions in highly random situations, or highly improbably events (such as manipulating a critical hit in an RPG). Basic bot comes with a rather powerful scripting language in order to be "programmed" to handle these specific situations. LuaBot in its most extreme application can even be "taught" to play video games!
+
+
+
How to Use Lua Bot
+
+
LuaBot is a trial and error script that exhausts the input-search-space by simply trying to push buttons.
+
+
You can program it to limit this searchspace, as it can become exponentially large. You can press eight possible buttons at any frame, each on or off. That's 2 raised to the 8, or 256 possible combinations in that one frame. There are 60 frames in one second, so you have 256 raised to the power of 60. Write a three. Now start writing 144 zeroes after it. It's not a small number.
+
+
Anyways, the bot has two parts. The frontend, which we'll call BeeBee, and the Lua part, which we call LuaBot.
+
+
You start the bot by opening the LuaBot_front.lua script file. Make sure the LuaBot_backend.lua file is in the same directory.
+
+
BeeBee
+
+
BeeBee (who received it's name from BasicBot, its predecessor) just writes it's contents into the LuaBot framework and produces a big Lua script for you.
+
All you need to do is enter Lua code for the specific functions and the code will generate the script.
+
+
You can also save and load the contents of the front-end. That way you can easily manage your bot scripts, without actually having to look into the LuaBot code.
+
+
BeeBee is only a pasting mechanism. It does not compile Lua or warn for errors.
+
+
LuaBot
+
+
LuaBot is a generic trial-and-error script that serves as a bot framework. It will set inputs as you program them for a number of frames (called an attempt). When the isAttemptEnd() says the attempt ends, a new attempt is started. All the attempts fall under one segment. At the end of a segment (denoted by the isSegmentEnd() function), the best attempt is kept (judged by the score and tie functions) and the next segment is started. The bot is capable of rolling back if a segment runs into a dead end. This allows you to backtrack and restart a previous segment.
+
+
The bot evaluates a true or false by checking to see whether the return value of a function is bigger then a certain value. It does this for EVERY function that returns something and every function that returns something must return a number (or Lua _will_ complain). For absolute true or false you can return "yes" and "no", "maxvalue" and "minvalue" or "pressed" and "released". Read variable info for more information.
+
+
The script takes a number of variables and functions into account. Some variables become important to prevent desyncing over segments.
+
+
- maxvalue
+
The maximum value (exclusive) of the random evaluation. If a value is higher than rand(minvalue, maxvalue), it evaluates as true, else false. By default this is set to 100.
+
+
- minvalue
+
The lowest value (inclusive) of the random evaluation. If a value is lower than rand(minvalue, maxvalue), it evaluates to false, else true. By default this is set to 0.
+
+
- yes / no
+
- pressed / released
+
These map to the minvalue/maxvalue.
+
+
- loopcounter
+
The number of times a frameadvance has been called by the main botloop.
+
+
- key1 key2 key3 key4
+
The input table of players 1-4. The keys are: A B up down left right select start. Set any to 1 if you want them to be set and to nil if you don't want them set.
+
Note that these get cleared right before onInputStart is called. This variable is saved in a pseudo-movie table if the attempt is better then the previous one and used for playback when moving to the next segment.
+
+
- lastkey1 lastkey2 lastkey3 lastkey4
+
The inputs that were given to FCEU on the PREVIOUS frame. This holds for segments as well (at the beginning of a new segment, the lastkeys of the previous segment are set). This also goes for the start. If you use key1-4 in onStart, the first segment will have those keys as lastkey.
+
+
- frame
+
The number of frames of the current attempt. Starts at 1.
+
+
- attempt
+
The number of attempts in the current segment. Starts at 1.
+
+
- segment
+
The segment the bot is currently running. Note that rolledback segments are deducted from this number.
+
+
- okattempts
+
The number of attempts that have been deemed ok. This is a statistical variable. It might tell you how well your bot is doing (combined with the number of failed attempts).
+
+
- failattempts
+
The number of attempts in the current segment that have been deemed bad. This is a statistical variable. It might tell you how well your bot is doing (combined with the number of approved attempts).
+
+
- segments
+
This is the big table that holds everything together. Don't mess with it.
+
+
- maxframes
+
You can set maxframes and check it in the isAttemptEnd function to simply limit a attempt by this many frames. You can also just ignore this and do something else instead.
+
+
- maxattempts
+
Same as maxframes, except for attempts in a segment.
+
+
- maxsegments
+
Same as maxframes, except for segments in a run.
+
+
- playingbest
+
Will be set to true when the bot is playing back it's best attempt to advance to the next segment. Not really used by other functions.
+
+
- keyrecording1-4
+
A simple table with the pressed keys for playback.
+
+
- X Y Z P Q
+
Some "static" variables. These allow you to easily set them onStart and use them in various functions to return the same number. Like a global variable. The P and Q numbers used to denote a random number between 0 and P or Q, but they don't right now.
+
+
- vars
+
This is your variable table. It's contents is saved at the end of an attempt and will be loaded at the beginning of a segment. On rollback, this table is also kept. Put any variable you want to keep across segments in this table.
+
+
+
Ok. That's it for the variables. Now for functions. There are basically three types of functions. The functions that determine whether a button is pressed (8 for each player), to determine whether an attempt/segment/run has ended or was ok and functions for certain events. This number is not evaluated by the random-eval function.
+
+
- getScore
+
This returns how "well" the current attempt is. At the end of a segment, the best scoring good attempt will be used to continue to the next segment. In case of a tie, see the tie functions. This number is not evaluated by the random-eval function!
+
+
- getTie1-4
+
If the score ends in a tie, that is, two attempts score equally well (have an equal number of points for instance), you can use these functions to break that tie. Like, which attempt has the most health or is the fastest or whatever. This number is not evaluated by the random-eval function!
+
+
- isRunEnd
+
Return whether the bot should stop running. If the returned number is bigger then the random number rand(minvalue-maxvalue), the bot will stop.
+
+
- mustRollBack
+
Returns whether the bot should rollback the current attempt. In such case, the previous segment is loaded and the current segment is completely discarded. If the returned number is bigger then the random number rand(minvalue-maxvalue), the segment will rollback one segment.
+
+
- isSegmentEnd
+
If the returned number is bigger then the random number rand(minvalue-maxvalue), the bot will stop the current segment, play back the best recorded attempt and start a new segment. Mostly done when a certain number of attempts is reached, but possibly you know when have the best possible attempt and can move on.
+
+
- isAttemptEnd
+
If the returned number is bigger then the random number rand(minvalue-maxvalue), the attempt will stop and a new attempt will be started. Some examples when this function should return yes is when you reached a certain goal, a number of frames or when you died (in which case the bot should try again :).
+
+
- isAttemptOk
+
If the returned number is bigger then the random number rand(minvalue-maxvalue), the current attempt (which has just ended) is deemed ok. Only attempts that are deemed ok are up for being saved. For instance, when the player died in the current attempt, you should return no.
+
+
- pressKeyX (pressKeyA1, pressKeyStart4, etc...)
+
These functions determine whether a button should be pressed in the next frame. If the returned number is bigger then the random number rand(minvalue-maxvalue), the button is pressed, otherwise it is not. To absolutely press a button, simply return yes or no. To use some odds, return a number between minvalue and maxvalue. For instance, using the default settings, if you return 50, there is a 50% chance the button will be pressed.
+
+
- onStart
+
Maybe a little misleading, but the onStart function is called BEFORE the main botloop starts. You can do some non-generic startup stuff here like press start at the title screen and get the game started. Returns nothing.
+
+
- onFinish
+
The opposite to onStart, this function is called when the main botloop exits. You can cleanup, or write stuff or whatever.
+
+
- onSegmentStart
+
When a new segment is started, this is called. After initializing variables and such, but before onAttemptStart is called. Returns nothing.
+
+
- onSegmentEnd
+
When isSegmentEnd evaluates to true, this function is called. Returns nothing.
+
+
- onAttemptStart
+
Called at the start of a new attempt, after onSegmentStart (in case of a new segment) but before onInputStart. Returns nothing.
+
+
- onAttemptEnd(wasOk)
+
Called at the end of an attempt. The only function to have a parameter (note: case sensitive). The parameter wasOk will return (boolean) whether isAttemptOk evaluated to true or false. Returns nothing.
+
+
- onInputStart
+
In a frame, this is the first place where the key1-4 variables are cleared. This is called before all the input (pressKeyX) functions are called. Returns nothing.
+
+
- onInputEnd
+
This is called immediately after the input (pressKeyX) functions have been called. Returns nothing.
The following functions are available in FCEUX, in addition to standard LUA capabilities:
-
-
-
Emu library
-
-
emu.poweron()
-
-
Executes a power cycle.
-
-
emu.softreset()
-
-
Executes a (soft) reset.
-
-
emu.speedmode(string mode)
-
-
Set the emulator to given speed. The mode argument can be one of these:
-
- "normal"
-
- "nothrottle" (same as turbo on fceux)
-
- "turbo"
-
- "maximum"
-
-
emu.frameadvance()
-
-
Advance the emulator by one frame. It's like pressing the frame advance button once.
-
-
Most scripts use this function in their main game loop to advance frames. Note that you can also register functions by various methods that run "dead", returning control to the emulator and letting the emulator advance the frame. For most people, using frame advance in an endless while loop is easier to comprehend so I suggest starting with that. This makes more sense when creating bots. Once you move to creating auxillary libraries, try the register() methods.
-
-
emu.pause()
-
-
Pauses the emulator.
-
-
emu.unpause()
-
-
Unpauses the emulator.
-
-
emu.exec_count(int count, function func)
-
-
Calls given function, restricting its working time to given number of lua cycles. Using this method you can ensure that some heavy operation (like Lua bot) won't freeze FCEUX.
-
-
emu.exec_time(int time, function func)
-
-
Windows-only. Calls given function, restricting its working time to given number of milliseconds (approximate). Using this method you can ensure that some heavy operation (like Lua bot) won't freeze FCEUX.
Toggles the drawing of the sprites and background planes. Set to false or nil to disable a pane, anything else will draw them.
-
-
emu.message(string message)
-
-
Displays given message on screen in the standard messages position. Use gui.text() when you need to position text.
-
-
int emu.framecount()
-
-
Returns the framecount value. The frame counter runs without a movie running so this always returns a value.
-
-
int emu.lagcount()
-
-
Returns the number of lag frames encountered. Lag frames are frames where the game did not poll for input because it missed the vblank. This happens when it has to compute too much within the frame boundary. This returns the number indicated on the lag counter.
-
-
bool emu.lagged()
-
-
Returns true if currently in a lagframe, false otherwise.
-
-
emu.setlagflag(bool value)
-
-
Sets current value of lag flag.
-
Some games poll input even in lag frames, so standard way of detecting lag (used by FCEUX and other emulators) does not work for those games, and you have to determine lag frames manually.
-
First, find RAM addresses that help you distinguish between lag and non-lag frames (e.g. an in-game frame counter that only increments in non-lag frames). Then register memory hooks that will change lag flag when needed.
-
-
bool emu.emulating()
-
-
Returns true if emulation has started, or false otherwise. Certain operations such as using savestates are invalid to attempt before emulation has started. You probably won't need to use this function unless you want to make your script extra-robust to being started too early.
-
-
bool emu.paused()
-
-
Returns true if emulator is paused, false otherwise.
-
-
bool emu.readonly()
-
Alias: movie.readonly
-
-
Returns whether the emulator is in read-only state.
-
-
While this variable only applies to movies, it is stored as a global variable and can be modified even without a movie loaded. Hence, it is in the emu library rather than the movie library.
-
-
emu.setreadonly(bool state)
-
Alias: movie.setreadonly
-
-
Sets the read-only status to read-only if argument is true and read+write if false.
-
Note: This might result in an error if the medium of the movie file is not writeable (such as in an archive file).
-
-
While this variable only applies to movies, it is stored as a global variable and can be modified even without a movie loaded. Hence, it is in the emu library rather than the movie library.
-
-
emu.getdir()
-
-
Returns the path of fceux.exe as a string.
-
-
emu.loadrom(string filename)
-
-
Loads the ROM from the directory relative to the lua script or from the absolute path. Hence, the filename parameter can be absolute or relative path.
-
-
If the ROM can't be loaded, loads the most recent one.
-
-
emu.registerbefore(function func)
-
-
Registers a callback function to run immediately before each frame gets emulated. This runs after the next frame's input is known but before it's used, so this is your only chance to set the next frame's input using the next frame's would-be input. For example, if you want to make a script that filters or modifies ongoing user input, such as making the game think "left" is pressed whenever you press "right", you can do it easily with this.
-
-
Note that this is not quite the same as code that's placed before a call to emu.frameadvance. This callback runs a little later than that. Also, you cannot safely assume that this will only be called once per frame. Depending on the emulator's options, every frame may be simulated multiple times and your callback will be called once per simulation. If for some reason you need to use this callback to keep track of a stateful linear progression of things across frames then you may need to key your calculations to the results of emu.framecount.
-
-
Like other callback-registering functions provided by FCEUX, there is only one registered callback at a time per registering function per script. If you register two callbacks, the second one will replace the first, and the call to emu.registerbefore will return the old callback. You may register nil instead of a function to clear a previously-registered callback. If a script returns while it still has registered callbacks, FCEUX will keep it alive to call those callbacks when appropriate, until either the script is stopped by the user or all of the callbacks are de-registered.
-
-
emu.registerafter(function func)
-
-
Registers a callback function to run immediately after each frame gets emulated. It runs at a similar time as (and slightly before) gui.register callbacks, except unlike with gui.register it doesn't also get called again whenever the screen gets redrawn. Similar caveats as those mentioned in emu.registerbefore apply.
-
-
emu.registerexit(function func)
-
-
Registers a callback function that runs when the script stops. Whether the script stops on its own or the user tells it to stop, or even if the script crashes or the user tries to close the emulator, FCEUX will try to run whatever Lua code you put in here first. So if you want to make sure some code runs that cleans up some external resources or saves your progress to a file or just says some last words, you could put it here. (Of course, a forceful termination of the application or a crash from inside the registered exit function will still prevent the code from running.)
-
-
Suppose you write a script that registers an exit function and then enters an infinite loop. If the user clicks "Stop" your script will be forcefully stopped, but then it will start running its exit function. If your exit function enters an infinite loop too, then the user will have to click "Stop" a second time to really stop your script. That would be annoying. So try to avoid doing too much inside the exit function.
-
-
Note that restarting a script counts as stopping it and then starting it again, so doing so (either by clicking "Restart" or by editing the script while it is running) will trigger the callback. Note also that returning from a script generally does NOT count as stopping (because your script is still running or waiting to run its callback functions and thus does not stop... see here for more information), even if the exit callback is the only one you have registered.
-
-
bool emu.addgamegenie(string str)
-
-
Adds a Game Genie code to the Cheats menu. Returns false and an error message if the code can't be decoded. Returns false if the code couldn't be added. Returns true if the code already existed, or if it was added.
-
-
Usage: emu.addgamegenie("NUTANT")
-
-
Note that the Cheats Dialog Box won't show the code unless you close and reopen it.
-
-
bool emu.delgamegenie(string str)
-
-
Removes a Game Genie code from the Cheats menu. Returns false and an error message if the code can't be decoded. Returns false if the code couldn't be deleted. Returns true if the code didn't exist, or if it was deleted.
-
-
Usage: emu.delgamegenie("NUTANT")
-
-
Note that the Cheats Dialog Box won't show the code unless you close and reopen it.
-
-
emu.print(string str)
-
-
Puts a message into the Output Console area of the Lua Script control window. Useful for displaying usage instructions to the user when a script gets run.
-
-
emu.getscreenpixel(int x, int y, bool getemuscreen)
-
-
Returns the separate RGB components of the given screen pixel, and the palette. Can be 0-255 by 0-239, but NTSC only displays 0-255 x 8-231 of it. If getemuscreen is false, this gets background colors from either the screen pixel or the LUA pixels set, but LUA data may not match the information used to put the data to the screen. If getemuscreen is true, this gets background colors from anything behind an LUA screen element.
-
-
Usage is local r,g,b,palette = emu.getscreenpixel(5, 5, false) to retrieve the current red/green/blue colors and palette value of the pixel at 5x5.
-
-
Palette value can be 0-63, or 254 if there was an error.
-
-
You can avoid getting LUA data by putting the data into a function, and feeding the function name to emu.registerbefore.
-
-
-
FCEU library
-
-
The FCEU library is the same as the emu library. It is left in for backwards compatibility. However, the emu library is preferred.
-
-
-
ROM Library
-
-
rom.getfilename()
-
-
Get the base filename of the ROM loaded.
-
-
rom.gethash(string type)
-
-
Get a hash of the ROM loaded, for verification. If type is "md5", returns a hex string of the MD5 hash. If type is "base64", returns a base64 string of the MD5 hash, just like the movie romChecksum value.
-
-
rom.readbyte(int address)
-
rom.readbyteunsigned(int address)
-
-
Get an unsigned byte from the actual ROM file at the given address.
-
-
This includes the header! It's the same as opening the file in a hex-editor.
-
-
rom.readbytesigned(int address)
-
-
Get a signed byte from the actual ROM file at the given address. Returns a byte that is signed.
-
-
This includes the header! It's the same as opening the file in a hex-editor.
-
-
rom.writebyte()
-
-
Write the value to the ROM at the given address. The value is modded with 256 before writing (so writing 257 will actually write 1). Negative values allowed.
-
-
Editing the header is not available.
-
-
Memory Library
-
-
memory.readbyte(int address)
-
memory.readbyteunsigned(int address)
-
-
Get an unsigned byte from the RAM at the given address. Returns a byte regardless of emulator. The byte will always be positive.
-
-
memory.readbyterange(int address, int length)
-
-
Get a length bytes starting at the given address and return it as a string. Convert to table to access the individual bytes.
-
-
memory.readbytesigned(int address)
-
-
Get a signed byte from the RAM at the given address. Returns a byte regardless of emulator. The most significant bit will serve as the sign.
Get an unsigned word from the RAM at the given address. Returns a 16-bit value regardless of emulator. The value will always be positive.
-
If you only provide a single parameter (addressLow), the function treats it as address of little-endian word. if you provide two parameters, the function reads the low byte from addressLow and the high byte from addressHigh, so you can use it in games which like to store their variables in separate form (a lot of NES games do).
The same as above, except the returned value is signed, i.e. its most significant bit will serve as the sign.
-
-
memory.writebyte(int address, int value)
-
-
Write the value to the RAM at the given address. The value is modded with 256 before writing (so writing 257 will actually write 1). Negative values allowed.
-
-
int memory.getregister(cpuregistername)
-
-
Returns the current value of the given hardware register.
-
For example, memory.getregister("pc") will return the main CPU's current Program Counter.
-
-
Valid registers are: "a", "x", "y", "s", "p", and "pc".
-
-
memory.setregister(string cpuregistername, int value)
-
-
Sets the current value of the given hardware register.
-
For example, memory.setregister("pc",0x200) will change the main CPU's current Program Counter to 0x200.
-
-
Valid registers are: "a", "x", "y", "s", "p", and "pc".
-
-
You had better know exactly what you're doing or you're probably just going to crash the game if you try to use this function. That applies to the other memory.write functions as well, but to a lesser extent.
-
-
-
memory.register(int address, [int size,] function func)
-
memory.registerwrite(int address, [int size,] function func)
-
-
Registers a function to be called immediately whenever the given memory address range is written to.
-
-
address is the address in CPU address space (0x0000 - 0xFFFF).
-
-
size is the number of bytes to "watch". For example, if size is 100 and address is 0x0200, then you will register the function across all 100 bytes from 0x0200 to 0x0263. A write to any of those bytes will trigger the function. Having callbacks on a large range of memory addresses can be expensive, so try to use the smallest range that's necessary for whatever it is you're trying to do. If you don't specify any size then it defaults to 1.
-
-
The callback function will receive three arguments (address, size, value) indicating what write operation triggered the callback. If you don't care about that extra information then you can ignore it and define your callback function to not take any arguments. Since 6502 writes are always single byte, the "size" argument will always be 1.
-
-
You may use a memory.write function from inside the callback to change the value that just got written. However, keep in mind that doing so will trigger your callback again, so you must have a "base case" such as checking to make sure that the value is not already what you want it to be before writing it. Another, more drastic option is to de-register the current callback before performing the write.
-
-
If func is nil that means to de-register any memory write callbacks that the current script has already registered on the given range of bytes.
-
-
memory.registerexec(int address, [int size,] function func)
-
memory.registerrun(int address, [int size,] function func)
-
memory.registerexecute(int address, [int size,] function func)
-
-
Registers a function to be called immediately whenever the emulated system runs code located in the given memory address range.
-
-
Since "address" is the address in CPU address space (0x0000 - 0xFFFF), this doesn't take ROM banking into account, so the callback will be called for any bank, and in some cases you'll have to check current bank in your callback function.
-
-
The information about memory.register applies to this function as well. The callback will receive the same three arguments, though the "value" argument will always be 0.
-
-
-
-
Example of custom breakpoint:
-
-
function CounterBreak()
-
ObjCtr = memory.getregister("y")
-
if ObjCtr > 0x16 then
-
gui.text(1, 9, string.format("%02X",ObjCtr))
-
emu.pause() -- or debugger.hitbreakpoint()
-
end
-
end
-
memory.registerexecute(0x863C, CounterBreak);
-
-
+
Lua Functions
+
+
The following functions are available in FCEUX, in addition to standard LUA capabilities:
+
+
+
Emu library
+
+
emu.poweron()
+
+
Executes a power cycle.
+
+
emu.softreset()
+
+
Executes a (soft) reset.
+
+
emu.speedmode(string mode)
+
+
Set the emulator to given speed. The mode argument can be one of these:
+
- "normal"
+
- "nothrottle" (same as turbo on fceux)
+
- "turbo"
+
- "maximum"
+
+
emu.frameadvance()
+
+
Advance the emulator by one frame. It's like pressing the frame advance button once.
+
+
Most scripts use this function in their main game loop to advance frames. Note that you can also register functions by various methods that run "dead", returning control to the emulator and letting the emulator advance the frame. For most people, using frame advance in an endless while loop is easier to comprehend so I suggest starting with that. This makes more sense when creating bots. Once you move to creating auxillary libraries, try the register() methods.
+
+
emu.pause()
+
+
Pauses the emulator.
+
+
emu.unpause()
+
+
Unpauses the emulator.
+
+
emu.exec_count(int count, function func)
+
+
Calls given function, restricting its working time to given number of lua cycles. Using this method you can ensure that some heavy operation (like Lua bot) won't freeze FCEUX.
+
+
emu.exec_time(int time, function func)
+
+
Windows-only. Calls given function, restricting its working time to given number of milliseconds (approximate). Using this method you can ensure that some heavy operation (like Lua bot) won't freeze FCEUX.
Toggles the drawing of the sprites and background planes. Set to false or nil to disable a pane, anything else will draw them.
+
+
emu.message(string message)
+
+
Displays given message on screen in the standard messages position. Use gui.text() when you need to position text.
+
+
int emu.framecount()
+
+
Returns the framecount value. The frame counter runs without a movie running so this always returns a value.
+
+
int emu.lagcount()
+
+
Returns the number of lag frames encountered. Lag frames are frames where the game did not poll for input because it missed the vblank. This happens when it has to compute too much within the frame boundary. This returns the number indicated on the lag counter.
+
+
bool emu.lagged()
+
+
Returns true if currently in a lagframe, false otherwise.
+
+
emu.setlagflag(bool value)
+
+
Sets current value of lag flag.
+
Some games poll input even in lag frames, so standard way of detecting lag (used by FCEUX and other emulators) does not work for those games, and you have to determine lag frames manually.
+
First, find RAM addresses that help you distinguish between lag and non-lag frames (e.g. an in-game frame counter that only increments in non-lag frames). Then register memory hooks that will change lag flag when needed.
+
+
bool emu.emulating()
+
+
Returns true if emulation has started, or false otherwise. Certain operations such as using savestates are invalid to attempt before emulation has started. You probably won't need to use this function unless you want to make your script extra-robust to being started too early.
+
+
bool emu.paused()
+
+
Returns true if emulator is paused, false otherwise.
+
+
bool emu.readonly()
+
Alias: movie.readonly
+
+
Returns whether the emulator is in read-only state.
+
+
While this variable only applies to movies, it is stored as a global variable and can be modified even without a movie loaded. Hence, it is in the emu library rather than the movie library.
+
+
emu.setreadonly(bool state)
+
Alias: movie.setreadonly
+
+
Sets the read-only status to read-only if argument is true and read+write if false.
+
Note: This might result in an error if the medium of the movie file is not writeable (such as in an archive file).
+
+
While this variable only applies to movies, it is stored as a global variable and can be modified even without a movie loaded. Hence, it is in the emu library rather than the movie library.
+
+
emu.getdir()
+
+
Returns the path of fceux.exe as a string.
+
+
emu.loadrom(string filename)
+
+
Loads the ROM from the directory relative to the lua script or from the absolute path. Hence, the filename parameter can be absolute or relative path.
+
+
If the ROM can't e loaded, loads the most recent one.
+
+
emu.registerbefore(function func)
+
+
Registers a callback function to run immediately before each frame gets emulated. This runs after the next frame's input is known but before it's used, so this is your only chance to set the next frame's input using the next frame's would-be input. For example, if you want to make a script that filters or modifies ongoing user input, such as making the game think "left" is pressed whenever you press "right", you can do it easily with this.
+
+
Note that this is not quite the same as code that's placed before a call to emu.frameadvance. This callback runs a little later than that. Also, you cannot safely assume that this will only be called once per frame. Depending on the emulator's options, every frame may be simulated multiple times and your callback will be called once per simulation. If for some reason you need to use this callback to keep track of a stateful linear progression of things across frames then you may need to key your calculations to the results of emu.framecount.
+
+
Like other callback-registering functions provided by FCEUX, there is only one registered callback at a time per registering function per script. If you register two callbacks, the second one will replace the first, and the call to emu.registerbefore will return the old callback. You may register nil instead of a function to clear a previously-registered callback. If a script returns while it still has registered callbacks, FCEUX will keep it alive to call those callbacks when appropriate, until either the script is stopped by the user or all of the callbacks are de-registered.
+
+
emu.registerafter(function func)
+
+
Registers a callback function to run immediately after each frame gets emulated. It runs at a similar time as (and slightly before) gui.register callbacks, except unlike with gui.register it doesn't also get called again whenever the screen gets redrawn. Similar caveats as those mentioned in emu.registerbefore apply.
+
+
emu.registerexit(function func)
+
+
Registers a callback function that runs when the script stops. Whether the script stops on its own or the user tells it to stop, or even if the script crashes or the user tries to close the emulator, FCEUX will try to run whatever Lua code you put in here first. So if you want to make sure some code runs that cleans up some external resources or saves your progress to a file or just says some last words, you could put it here. (Of course, a forceful termination of the application or a crash from inside the registered exit function will still prevent the code from running.)
+
+
Suppose you write a script that registers an exit function and then enters an infinite loop. If the user clicks "Stop" your script will be forcefully stopped, but then it will start running its exit function. If your exit function enters an infinite loop too, then the user will have to click "Stop" a second time to really stop your script. That would be annoying. So try to avoid doing too much inside the exit function.
+
+
Note that restarting a script counts as stopping it and then starting it again, so doing so (either by clicking "Restart" or by editing the script while it is running) will trigger the callback. Note also that returning from a script generally does NOT count as stopping (because your script is still running or waiting to run its callback functions and thus does not stop... see here for more information), even if the exit callback is the only one you have registered.
+
+
bool emu.addgamegenie(string str)
+
+
Adds a Game Genie code to the Cheats menu. Returns false and an error message if the code can't be decoded. Returns false if the code couldn't be added. Returns true if the code already existed, or if it was added.
+
+
Usage: emu.addgamegenie("NUTANT")
+
+
Note that the Cheats Dialog Box won't show the code unless you close and reopen it.
+
+
bool emu.delgamegenie(string str)
+
+
Removes a Game Genie code from the Cheats menu. Returns false and an error message if the code can't be decoded. Returns false if the code couldn't be deleted. Returns true if the code didn't exist, or if it was deleted.
+
+
Usage: emu.delgamegenie("NUTANT")
+
+
Note that the Cheats Dialog Box won't show the code unless you close and reopen it.
+
+
emu.print(string str)
+
+
Puts a message into the Output Console area of the Lua Script control window. Useful for displaying usage instructions to the user when a script gets run.
+
+
emu.getscreenpixel(int x, int y, bool getemuscreen)
+
+
Returns the separate RGB components of the given screen pixel, and the palette. Can be 0-255 by 0-239, but NTSC only displays 0-255 x 8-231 of it. If getemuscreen is false, this gets background colors from either the screen pixel or the LUA pixels set, but LUA data may not match the information used to put the data to the screen. If getemuscreen is true, this gets background colors from anything behind an LUA screen element.
+
+
Usage is local r,g,b,palette = emu.getscreenpixel(5, 5, false) to retrieve the current red/green/blue colors and palette value of the pixel at 5x5.
+
+
Palette value can be 0-63, or 254 if there was an error.
+
+
You can avoid getting LUA data by putting the data into a function, and feeding the function name to emu.registerbefore.
+
+
+
FCEU library
+
+
The FCEU library is the same as the emu library. It is left in for backwards compatibility. However, the emu library is preferred.
+
+
+
ROM Library
+
+
rom.readbyte(int address)
+
rom.readbyteunsigned(int address)
+
+
Get an unsigned byte from the actual ROM file at the given address.
+
+
This includes the header! It's the same as opening the file in a hex-editor.
+
+
rom.readbytesigned(int address)
+
+
Get a signed byte from the actual ROM file at the given address. Returns a byte that is signed.
+
+
This includes the header! It's the same as opening the file in a hex-editor.
+
+
rom.writebyte()
+
+
Write the value to the ROM at the given address. The value is modded with 256 before writing (so writing 257 will actually write 1). Negative values allowed.
+
+
Editing the header is not available.
+
+
Memory Library
+
+
memory.readbyte(int address)
+
memory.readbyteunsigned(int address)
+
+
Get an unsigned byte from the RAM at the given address. Returns a byte regardless of emulator. The byte will always be positive.
+
+
memory.readbyterange(int address, int length)
+
+
Get a length bytes starting at the given address and return it as a string. Convert to table to access the individual bytes.
+
+
memory.readbytesigned(int address)
+
+
Get a signed byte from the RAM at the given address. Returns a byte regardless of emulator. The most significant bit will serve as the sign.
Get an unsigned word from the RAM at the given address. Returns a 16-bit value regardless of emulator. The value will always be positive.
+
If you only provide a single parameter (addressLow), the function treats it as address of little-endian word. if you provide two parameters, the function reads the low byte from addressLow and the high byte from addressHigh, so you can use it in games which like to store their variables in separate form (a lot of NES games do).
The same as above, except the returned value is signed, i.e. its most significant bit will serve as the sign.
+
+
memory.writebyte(int address, int value)
+
+
Write the value to the RAM at the given address. The value is modded with 256 before writing (so writing 257 will actually write 1). Negative values allowed.
+
+
int memory.getregister(cpuregistername)
+
+
Returns the current value of the given hardware register.
+
For example, memory.getregister("pc") will return the main CPU's current Program Counter.
+
+
Valid registers are: "a", "x", "y", "s", "p", and "pc".
+
+
memory.setregister(string cpuregistername, int value)
+
+
Sets the current value of the given hardware register.
+
For example, memory.setregister("pc",0x200) will change the main CPU's current Program Counter to 0x200.
+
+
Valid registers are: "a", "x", "y", "s", "p", and "pc".
+
+
You had better know exactly what you're doing or you're probably just going to crash the game if you try to use this function. That applies to the other memory.write functions as well, but to a lesser extent.
+
+
memory.register(int address, [int size,] function func)
+
memory.registerwrite(int address, [int size,] function func)
+
+
Registers a function to be called immediately whenever the given memory address range is written to.
+
+
address is the address in CPU address space (0x0000 - 0xFFFF).
+
+
size is the number of bytes to "watch". For example, if size is 100 and address is 0x0200, then you will register the function across all 100 bytes from 0x0200 to 0x0263. A write to any of those bytes will trigger the function. Having callbacks on a large range of memory addresses can be expensive, so try to use the smallest range that's necessary for whatever it is you're trying to do. If you don't specify any size then it defaults to 1.
+
+
The callback function will receive two arguments, (address, size) indicating what write operation triggered the callback. If you don't care about that extra information then you can ignore it and define your callback function to not take any arguments. The value that was written is NOT passed into the callback function, but you can easily use any of the memory.read functions to retrieve it.
+
+
You may use a memory.write function from inside the callback to change the value that just got written. However, keep in mind that doing so will trigger your callback again, so you must have a "base case" such as checking to make sure that the value is not already what you want it to be before writing it. Another, more drastic option is to de-register the current callback before performing the write.
+
+
If func is nil that means to de-register any memory write callbacks that the current script has already registered on the given range of bytes.
+
+
memory.registerexec(int address, [int size,] function func)
+
memory.registerrun(int address, [int size,] function func)
+
memory.registerexecute(int address, [int size,] function func)
+
+
Registers a function to be called immediately whenever the emulated system runs code located in the given memory address range.
+
+
Since "address" is the address in CPU address space (0x0000 - 0xFFFF), this doesn't take ROM banking into account, so the callback will be called for any bank, and in some cases you'll have to check current bank in your callback function.
+
+
The information about memory.register applies to this function as well.
+
+
+
+
+
+
Example of custom breakpoint:
+
+
function CounterBreak()
+
ObjCtr = memory.getregister("y")
+
if ObjCtr > 0x16 then
+
gui.text(1, 9, string.format("%02X",ObjCtr))
+
emu.pause() -- or debugger.hitbreakpoint()
+
end
+
end
+
memory.registerexecute(0x863C, CounterBreak);
+
+
-
-
-
Debugger Library
-
-
debugger.hitbreakpoint()
-
-
Simulates a breakpoint hit, pauses emulation and brings up the Debugger window. Use this function in your handlers of custom breakpoints.
-
-
int debugger.getcyclescount()
-
-
Returns an integer value representing the number of CPU cycles elapsed since the poweron or since the last reset of the cycles counter.
-
-
int debugger.getinstructionscount()
-
-
Returns an integer value representing the number of CPU instructions executed since the poweron or since the last reset of the instructions counter.
-
-
debugger.resetcyclescount()
-
-
Resets the cycles counter.
-
-
debugger.resetinstructionscount()
-
-
Resets the instructions counter.
-
-
-
Joypad Library
-
-
table joypad.get(int player)
-
table joypad.read(int player)
-
-
Returns a table of every game button, where each entry is true if that button is currently held (as of the last time the emulation checked), or false if it is not held. This takes keyboard inputs, not Lua. The table keys look like this (case sensitive):
-
-
up, down, left, right, A, B, start, select
-
-
Where a Lua truthvalue true means that the button is set, false means the button is unset. Note that only "false" and "nil" are considered a false value by Lua. Anything else is true, even the number 0.
-
-
joypad.read left in for backwards compatibility with older versions of FCEU/FCEUX.
-
-
table joypad.getimmediate(int player)
-
table joypad.readimmediate(int player)
-
-
Returns a table of every game button, where each entry is true if that button is held at the moment of calling the function, or false if it is not held. This function polls keyboard input immediately, allowing Lua to interact with user even when emulator is paused.
-
-
As of FCEUX 2.2.0, the function only works in Windows. In Linux this function will return nil.
-
-
table joypad.getdown(int player)
-
table joypad.readdown(int player)
-
-
Returns a table of only the game buttons that are currently held. Each entry is true if that button is currently held (as of the last time the emulation checked), or nil if it is not held.
-
-
table joypad.getup(int player)
-
table joypad.readup(int player)
-
-
Returns a table of only the game buttons that are not currently held. Each entry is nil if that button is currently held (as of the last time the emulation checked), or false if it is not held.
-
-
joypad.set(int player, table input)
-
joypad.write(int player, table input)
-
-
Set the inputs for the given player. Table keys look like this (case sensitive):
-
-
up, down, left, right, A, B, start, select
-
-
There are 4 possible values: true, false, nil, and "invert".
-
true - Forces the button on
-
false - Forces the button off
-
nil - User's button press goes through unchanged
-
"invert"- Reverses the user's button press
-
-
Any string works in place of "invert". It is suggested as a convention to use "invert" for readability, but strings like "inv", "Weird switchy mechanism", "", or "true or false" works as well as "invert".
-
-
nil and "invert" exists so the script can control individual buttons of the controller without entirely blocking the user from having any control. Perhaps there is a process which can be automated by the script, like an optimal firing pattern, but the user still needs some manual control, such as moving the character around.
-
-
joypad.write left in for backwards compatibility with older versions of FCEU/FCEUX.
-
-
-
Zapper Library
-
-
table zapper.read()
-
-
Returns the zapper data
-
When no movie is loaded this input is the same as the internal mouse input (which is used to generate zapper input, as well as the arkanoid paddle).
-
-
When a movie is playing, it returns the zapper data in the movie code.
-
-
The return table consists of 3 values: x, y, and fire. x and y are the x,y coordinates of the zapper target in terms of pixels. fire represents the zapper firing. 0 = not firing, 1 = firing
-
-
zapper.set(table input)
-
-
Sets the zapper input state.
-
-
Taple entries (nil or -1 to leave unaffected):
-
x - Forces the X position
-
y - Forces the Y position
-
fire - Forces trigger (true/1 on, false/0 off)
-
-
-
Note: The zapper is always controller 2 on the NES so there is no player argument to these functions.
-
-
-
Input Library
-
-
table input.get()
-
table input.read()
-
-
Reads input from keyboard and mouse. Returns pressed keys and the position of mouse in pixels on game screen. The function returns a table with at least two properties; table.xmouse and table.ymouse. Additionally any of these keys will be set to true if they were held at the time of executing this function:
Requests input from the user using a multiple-option message box. See gui.popup for complete usage and returns.
-
-
-
Savestate Library
-
-
object savestate.object(int slot = nil)
-
-
Create a new savestate object. Optionally you can save the current state to one of the predefined slots(1-10) using the range 1-9 for slots 1-9, and 10 for 0, QWERTY style. Using no number will create an "anonymous" savestate.
-
Note that this does not actually save the current state! You need to create this value and pass it on to the load and save functions in order to save it.
-
-
Anonymous savestates are temporary, memory only states. You can make them persistent by calling memory.persistent(state). Persistent anonymous states are deleted from disk once the script exits.
-
-
object savestate.create(int slot = nil)
-
-
savestate.create is identical to savestate.object, except for the numbering for predefined slots(1-10, 1 refers to slot 0, 2-10 refer to 1-9). It's being left in for compatibility with older scripts, and potentially for platforms with different internal predefined slot numbering.
-
-
savestate.save(object savestate)
-
-
Save the current state object to the given savestate. The argument is the result of savestate.create(). You can load this state back up by calling savestate.load(savestate) on the same object.
-
-
savestate.load(object savestate)
-
-
Load the the given state. The argument is the result of savestate.create() and has been passed to savestate.save() at least once.
-
-
If this savestate is not persistent and not one of the predefined states, the state will be deleted after loading.
-
-
savestate.persist(object savestate)
-
-
Set the given savestate to be persistent. It will not be deleted when you load this state but at the exit of this script instead, unless it's one of the predefined states. If it is one of the predefined savestates it will be saved as a file on disk.
-
-
savestate.registersave(function func)
-
-
Registers a callback function that runs whenever the user saves a state. This won't actually be called when the script itself makes a savestate, so none of those endless loops due to a misplaced savestate.save.
-
-
As with other callback-registering functions provided by FCEUX, there is only one registered callback at a time per registering function per script. Upon registering a second callback, the first is kicked out to make room for the second. In this case, it will return the first function instead of nil, letting you know what was kicked out. Registering nil will clear the previously-registered callback.
-
-
savestate.registerload(function func)
-
-
Registers a callback function that runs whenever the user loads a previously saved state. It's not called when the script itself loads a previous state, so don't worry about your script interrupting itself just because it's loading something.
-
-
The state's data is loaded before this function runs, so you can read the RAM immediately after the user loads a state, or check the new framecount. Particularly useful if you want to update lua's display right away instead of showing junk from before the loadstate.
-
-
savestate.loadscriptdata(int location)
-
-
Accuracy not yet confirmed.
-
-
Intended Function, according to snes9x LUA documentation:
-
Returns the data associated with the given savestate (data that was earlier returned by a registered save callback) without actually loading the rest of that savestate or calling any callbacks. location should be a save slot number.
Loads and plays a movie from the directory relative to the Lua script or from the absolute path. If read_only is true, the movie will be loaded in read-only mode. The default is read+write.
-
-
A pauseframe can be specified, which controls which frame will auto-pause the movie. By default, this is off. A true value is returned if the movie loaded correctly.
Starts recording a movie, using the filename, relative to the Lua script.
-
-
An optional save_type can be specified. If set to 0 (default), it will record from a power on state, and automatically do so. This is the recommended setting for creating movies. This can also be set to 1 for savestate or 2 for saveram movies.
-
-
A third parameter specifies an author string. If included, it will be recorded into the movie file.
-
-
bool movie.active()
-
-
Returns true if a movie is currently loaded and false otherwise. (This should be used to guard against Lua errors when attempting to retrieve movie information).
-
-
int movie.framecount()
-
-
Returns the current frame count. (Has the same affect as emu.framecount)
-
-
string movie.mode()
-
-
Returns the current state of movie playback. Returns one of the following:
-
-
- "record"
-
- "playback"
-
- "finished"
-
- "taseditor"
-
- nil
-
-
movie.rerecordcounting(bool counting)
-
-
Turn the rerecord counter on or off. Allows you to do some brute forcing without inflating the rerecord count.
-
-
movie.stop()
-
movie.close()
-
-
Stops movie playback. If no movie is loaded, it throws a Lua error.
-
-
int movie.length()
-
-
Returns the total number of frames of the current movie. Throws a Lua error if no movie is loaded.
-
-
string movie.name()
-
string movie.getname()
-
-
Returns the filename of the current movie with path. Throws a Lua error if no movie is loaded.
-
-
movie.getfilename()
-
-
Returns the filename of the current movie with no path. Throws a Lua error if no movie is loaded.
-
-
movie.rerecordcount()
-
-
Returns the rerecord count of the current movie. Throws a Lua error if no movie is loaded.
-
-
movie.replay()
-
movie.playbeginning()
-
-
Performs the Play from Beginning function. Movie mode is switched to read-only and the movie loaded will begin playback from frame 1.
-
-
If no movie is loaded, no error is thrown and no message appears on screen.
-
-
bool movie.readonly()
-
bool movie.getreadonly()
-
Alias: emu.getreadonly
-
-
FCEUX keeps the read-only status even without a movie loaded.
-
-
Returns whether the emulator is in read-only state.
-
-
While this variable only applies to movies, it is stored as a global variable and can be modified even without a movie loaded. Hence, it is in the emu library rather than the movie library.
-
-
movie.setreadonly(bool state)
-
Alias: emu.setreadonly
-
-
FCEUX keeps the read-only status even without a movie loaded.
-
-
Sets the read-only status to read-only if argument is true and read+write if false.
-
Note: This might result in an error if the medium of the movie file is not writeable (such as in an archive file).
-
-
While this variable only applies to movies, it is stored as a global variable and can be modified even without a movie loaded. Hence, it is in the emu library rather than the movie library.
-
-
bool movie.recording()
-
-
Returns true if there is a movie loaded and in record mode.
-
-
bool movie.playing()
-
-
Returns true if there is a movie loaded and in play mode.
-
-
bool movie.ispoweron()
-
-
Returns true if the movie recording or loaded started from 'Start'.
-
Returns false if the movie uses a save state.
-
Opposite of movie.isfromsavestate()
-
-
bool movie.isfromsavestate()
-
-
Returns true if the movie recording or loaded started from 'Now'.
-
Returns false if the movie was recorded from a reset.
-
Opposite of movie.ispoweron()
-
-
string movie.name()
-
-
If a movie is loaded it returns the name of the movie, else it throws an error.
-
-
bool movie.readonly()
-
-
Returns the state of read-only. True if in playback mode, false if in record mode.
-
-
-
GUI Library
-
-
gui.pixel(int x, int y, type color)
-
gui.drawpixel(int x, int y, type color)
-
gui.setpixel(int x, int y, type color)
-
gui.writepixel(int x, int y, type color)
-
-
Draw one pixel of a given color at the given position on the screen. See drawing notes and color notes at the bottom of the page.
-
-
gui.getpixel(int x, int y)
-
-
Returns the separate RGBA components of the given pixel set by gui.pixel. This only gets LUA pixels set, not background colors.
-
-
Usage is local r,g,b,a = gui.getpixel(5, 5) to retrieve the current red/green/blue/alpha values of the LUA pixel at 5x5.
-
-
See emu.getscreenpixel() for an emulator screen variant.
-
-
gui.line(int x1, int y1, int x2, int y2 [, color [, skipfirst]])
-
gui.drawline(int x1, int y1, int x2, int y2 [, color [, skipfirst]])
-
-
Draws a line between the two points. The x1,y1 coordinate specifies one end of the line segment, and the x2,y2 coordinate specifies the other end. If skipfirst is true then this function will not draw anything at the pixel x1,y1, otherwise it will. skipfirst is optional and defaults to false. The default color for the line is solid white, but you may optionally override that using a color of your choice. See also drawing notes and color notes at the bottom of the page.
-
-
gui.box(int x1, int y1, int x2, int y2 [, fillcolor [, outlinecolor]]))
-
gui.drawbox(int x1, int y1, int x2, int y2 [, fillcolor [, outlinecolor]]))
-
gui.rect(int x1, int y1, int x2, int y2 [, fillcolor [, outlinecolor]]))
-
gui.drawrect(int x1, int y1, int x2, int y2 [, fillcolor [, outlinecolor]]))
-
-
Draws a rectangle between the given coordinates of the emulator screen for one frame. The x1,y1 coordinate specifies any corner of the rectangle (preferably the top-left corner), and the x2,y2 coordinate specifies the opposite corner.
-
-
The default color for the box is transparent white with a solid white outline, but you may optionally override those using colors of your choice. Also see drawing notes and color notes.
-
-
gui.text(int x, int y, string str [, textcolor [, backcolor]])
-
gui.drawtext(int x, int y, string str [, textcolor [, backcolor]])
-
-
Draws a given string at the given position. textcolor and backcolor are optional. See 'on colors' at the end of this page for information. Using nil as the input or not including an optional field will make it use the default.
-
-
gui.parsecolor(color)
-
-
Returns the separate RGBA components of the given color.
-
For example, you can say local r,g,b,a = gui.parsecolor('orange') to retrieve the red/green/blue values of the preset color orange. (You could also omit the a in cases like this.) This uses the same conversion method that FCEUX uses internally to support the different representations of colors that the GUI library uses. Overriding this function will not change how FCEUX interprets color values, however.
-
-
gui.savescreenshot()
-
Makes a screenshot of the FCEUX emulated screen, and saves it to the appropriate folder. Performs identically to pressing the Screenshot hotkey.
-
-
gui.savescreenshotas(string name)
-
Makes a screenshot of the FCEUX emulated screen, and saves it to the appropriate folder. However, this one receives a file name for the screenshot.
-
-
string gui.gdscreenshot(bool getemuscreen)
-
-
Takes a screen shot of the image and returns it in the form of a string which can be imported by the gd library using the gd.createFromGdStr() function.
-
-
This function is provided so as to allow FCEUX to not carry a copy of the gd library itself. If you want raw RGB32 access, skip the first 11 bytes (header) and then read pixels as Alpha (always 0), Red, Green, Blue, left to right then top to bottom, range is 0-255 for all colors.
-
-
If getemuscreen is false, this gets background colors from either the screen pixel or the LUA pixels set, but LUA data may not match the information used to put the data to the screen. If getemuscreen is true, this gets background colors from anything behind an LUA screen element.
-
-
Warning: Storing screen shots in memory is not recommended. Memory usage will blow up pretty quick. One screen shot string eats around 230 KB of RAM.
Draws an image on the screen. gdimage must be in truecolor gd string format.
-
-
Transparency is fully supported. Also, if alphamul is specified then it will modulate the transparency of the image even if it's originally fully opaque. (alphamul=1.0 is normal, alphamul=0.5 is doubly transparent, alphamul=3.0 is triply opaque, etc.)
-
-
dx,dy determines the top-left corner of where the image should draw. If they are omitted, the image will draw starting at the top-left corner of the screen.
-
-
gui.gdoverlay is an actual drawing function (like gui.box and friends) and thus must be called every frame, preferably inside a gui.register'd function, if you want it to appear as a persistent image onscreen.
-
-
Here is an example that loads a PNG from file, converts it to gd string format, and draws it once on the screen:
-
local gdstr = gd.createFromPng("myimage.png"):gdStr()
-
gui.gdoverlay(gdstr)
-
-
gui.opacity(int alpha)
-
-
Scales the transparency of subsequent draw calls. An alpha of 0.0 means completely transparent, and an alpha of 1.0 means completely unchanged (opaque). Non-integer values are supported and meaningful, as are values greater than 1.0. It is not necessary to use this function (or the less-recommended gui.transparency) to perform drawing with transparency, because you can provide an alpha value in the color argument of each draw call. However, it can sometimes be convenient to be able to globally modify the drawing transparency.
-
-
gui.transparency(int trans)
-
-
Scales the transparency of subsequent draw calls. Exactly the same as gui.opacity, except the range is different: A trans of 4.0 means completely transparent, and a trans of 0.0 means completely unchanged (opaque).
-
-
function gui.register(function func)
-
-
Register a function to be called between a frame being prepared for displaying on your screen and it actually happening. Used when that 1 frame delay for rendering is not acceptable.
Brings up a modal popup dialog box (everything stops until the user dismisses it). The box displays the message tostring(msg). This function returns the name of the button the user clicked on (as a string).
-
-
type determines which buttons are on the dialog box, and it can be one of the following: 'ok', 'yesno', 'yesnocancel', 'okcancel', 'abortretryignore'.
-
type defaults to 'ok' for gui.popup, or to 'yesno' for input.popup.
-
-
icon indicates the purpose of the dialog box (or more specifically it dictates which title and icon is displayed in the box), and it can be one of the following: 'message', 'question', 'warning', 'error'.
-
icon defaults to 'message' for gui.popup, or to 'question' for input.popup.
-
-
Try to avoid using this function much if at all, because modal dialog boxes can be irritating.
-
-
Linux users might want to install xmessage to perform the work. Otherwise the dialog will appear on the shell and that's less noticeable.
-
-
-
Sound Library
-
-
table sound.get()
-
-
Returns current state of PSG channels in big array.
-
-
table:
-
{
-
rp2a03:
-
{
-
square1:
-
{
-
volume, -- 0.0-1.0
-
frequency, -- in hertz
-
midikey, -- 0-127
-
duty, -- 0:12.5% 1:25% 2:50% 3:75%
-
regs: -- raw register values
-
{
-
frequency -- raw freq register value
-
}
-
},
-
square2:
-
{
-
volume, -- 0.0-1.0
-
frequency, -- in hertz
-
midikey, -- 0-127
-
duty, -- 0:12.5% 1:25% 2:50% 3:75%
-
regs: -- raw register values
-
{
-
frequency -- raw freq register value
-
}
-
},
-
triangle:
-
{
-
volume, -- 0.0-1.0
-
frequency, -- in hertz (correct?)
-
midikey, -- 0-127 (correct?)
-
regs: -- raw register values
-
{
-
frequency -- raw freq register value
-
}
-
},
-
noise:
-
{
-
volume, -- 0.0-1.0
-
short, -- true or false
-
frequency, -- in hertz (correct?)
-
midikey, -- 0-127 (correct?)
-
regs: -- raw register values
-
{
-
frequency -- raw freq register value
-
}
-
},
-
dpcm:
-
{
-
volume, -- 0.0-1.0
-
frequency, -- in hertz (correct?)
-
midikey, -- 0-127 (correct?)
-
dmcaddress, -- start position of the sample
-
dmcsize, -- size of the sample, in bytes
-
dmcloop, -- true:looped sample, false:oneshot
-
dmcseed, -- InitialRawDALatch
-
regs: -- raw register values
-
{
-
frequency -- raw freq register value
-
}
-
}
-
}
-
}
-
-
-
TAS Editor Library
-
-
taseditor.registerauto(function func)
-
taseditor.registermanual(function func)
-
bool taseditor.engaged()
-
bool taseditor.markedframe(int frame)
-
int taseditor.getmarker(int frame)
-
int taseditor.setmarker(int frame)
-
taseditor.clearmarker(int frame)
-
string taseditor.getnote(int index)
-
taseditor.setnote(int index, string newtext)
-
int taseditor.getcurrentbranch()
-
string taseditor.getrecordermode()
-
int taseditor.getsuperimpose()
-
int taseditor.getlostplayback()
-
int taseditor.getplaybacktarget()
-
taseditor.setplayback(int frame)
-
taseditor.stopseeking()
-
taseditor.getselection()
-
taseditor.setselection()
-
int taseditor.getinput(int frame, int joypad)
-
taseditor.submitinputchange(int frame, int joypad, int input)
-
taseditor.submitinsertframes(int frame, int number)
-
taseditor.submitdeleteframes(int frame, int number)
-
int taseditor.applyinputchanges([string name])
-
taseditor.clearinputchanges()
-
-
For full description of these functions refer to TAS Editor Manual.
-
-
-
Bitwise Operations
-
-
The following bit functions were added to FCEUX internally to compensate for Lua's lack of them. But it also supports all operations from LuaBitOp module, since it is also embedded in FCEUX.
-
-
int AND(int n1, int n2, ..., int nn)
-
-
Binary logical AND of all the given integers.
-
-
int OR(int n1, int n2, ..., int nn)
-
-
Binary logical OR of all the given integers.
-
-
int XOR(int n1, int n2, ..., int nn)
-
-
Binary logical XOR of all the given integers.
-
-
int BIT(int n1, int n2, ..., int nn)
-
-
Returns an integer with the given bits turned on. Parameters should be smaller than 31.
-
-
Appendix
-
-
On drawing
-
-
A general warning about drawing is that it is always one frame behind unless you use gui.register. This is because you tell the emulator to paint something but it will actually paint it when generating the image for the next frame. So you see your painting, except it will be on the image of the next frame. You can prevent this with gui.register because it gives you a quick chance to paint before blitting.
-
-
Dimensions & color depths you can paint in:
-
--320x239, 8bit color (confirm?)
-
256x224, 8bit color (confirm?)
-
-
On colors
-
-
Colors can be of a few types.
-
Int: use the a formula to compose the color as a number (depends on color depth)
-
String: Can either be a HTML colors, simple colors, or internal palette colors.
-
HTML string: "#rrggbb" ("#228844") or #rrggbbaa if alpha is supported.
Array: Example: {255,112,48,96} means {red=255, green=112, blue=48, alpha=96}
-
Table: Example: {r=255,g=112,b=48,a=96} means {red=255, green=112, blue=48, alpha=96}
-
Palette: Example: "P00" for Palette 00. "P3F" for palette 3F. P40-P7F are for LUA.
-
-
For transparancy use "clear".
-
+
+
+
Debugger Library
+
+
debugger.hitbreakpoint()
+
+
Simulates a breakpoint hit, pauses emulation and brings up the Debugger window. Use this function in your handlers of custom breakpoints.
+
+
int debugger.getcyclescount()
+
+
Returns an integer value representing the number of CPU cycles elapsed since the poweron or since the last reset of the cycles counter.
+
+
int debugger.getinstructionscount()
+
+
Returns an integer value representing the number of CPU instructions executed since the poweron or since the last reset of the instructions counter.
+
+
debugger.resetcyclescount()
+
+
Resets the cycles counter.
+
+
debugger.resetinstructionscount()
+
+
Resets the instructions counter.
+
+
+
Joypad Library
+
+
table joypad.get(int player)
+
table joypad.read(int player)
+
+
Returns a table of every game button, where each entry is true if that button is currently held (as of the last time the emulation checked), or false if it is not held. This takes keyboard inputs, not Lua. The table keys look like this (case sensitive):
+
+
up, down, left, right, A, B, start, select
+
+
Where a Lua truthvalue true means that the button is set, false means the button is unset. Note that only "false" and "nil" are considered a false value by Lua. Anything else is true, even the number 0.
+
+
joypad.read left in for backwards compatibility with older versions of FCEU/FCEUX.
+
+
table joypad.getimmediate(int player)
+
table joypad.readimmediate(int player)
+
+
Returns a table of every game button, where each entry is true if that button is held at the moment of calling the function, or false if it is not held. This function polls keyboard input immediately, allowing Lua to interact with user even when emulator is paused.
+
+
As of FCEUX 2.2.0, the function only works in Windows. In Linux this function will return nil.
+
+
table joypad.getdown(int player)
+
table joypad.readdown(int player)
+
+
Returns a table of only the game buttons that are currently held. Each entry is true if that button is currently held (as of the last time the emulation checked), or nil if it is not held.
+
+
table joypad.getup(int player)
+
table joypad.readup(int player)
+
+
Returns a table of only the game buttons that are not currently held. Each entry is nil if that button is currently held (as of the last time the emulation checked), or false if it is not held.
+
+
joypad.set(int player, table input)
+
joypad.write(int player, table input)
+
+
Set the inputs for the given player. Table keys look like this (case sensitive):
+
+
up, down, left, right, A, B, start, select
+
+
There are 4 possible values: true, false, nil, and "invert".
+
true - Forces the button on
+
false - Forces the button off
+
nil - User's button press goes through unchanged
+
"invert"- Reverses the user's button press
+
+
Any string works in place of "invert". It is suggested as a convention to use "invert" for readability, but strings like "inv", "Weird switchy mechanism", "", or "true or false" works as well as "invert".
+
+
nil and "invert" exists so the script can control individual buttons of the controller without entirely blocking the user from having any control. Perhaps there is a process which can be automated by the script, like an optimal firing pattern, but the user still needs some manual control, such as moving the character around.
+
+
joypad.write left in for backwards compatibility with older versions of FCEU/FCEUX.
+
+
+
Zapper Library
+
+
table zapper.read()
+
+
Returns the zapper data
+
When no movie is loaded this input is the same as the internal mouse input (which is used to generate zapper input, as well as the arkanoid paddle).
+
+
When a movie is playing, it returns the zapper data in the movie code.
+
+
The return table consists of 3 values: x, y, and fire. x and y are the x,y coordinates of the zapper target in terms of pixels. fire represents the zapper firing. 0 = not firing, 1 = firing
+
+
+
Note: The zapper is always controller 2 on the NES so there is no player argument to this function.
+
+
+
Input Library
+
+
table input.get()
+
table input.read()
+
+
Reads input from keyboard and mouse. Returns pressed keys and the position of mouse in pixels on game screen. The function returns a table with at least two properties; table.xmouse and table.ymouse. Additionally any of these keys will be set to true if they were held at the time of executing this function:
Requests input from the user using a multiple-option message box. See gui.popup for complete usage and returns.
+
+
+
Savestate Library
+
+
object savestate.object(int slot = nil)
+
+
Create a new savestate object. Optionally you can save the current state to one of the predefined slots(1-10) using the range 1-9 for slots 1-9, and 10 for 0, QWERTY style. Using no number will create an "anonymous" savestate.
+
Note that this does not actually save the current state! You need to create this value and pass it on to the load and save functions in order to save it.
+
+
Anonymous savestates are temporary, memory only states. You can make them persistent by calling memory.persistent(state). Persistent anonymous states are deleted from disk once the script exits.
+
+
object savestate.create(int slot = nil)
+
+
savestate.create is identical to savestate.object, except for the numbering for predefined slots(1-10, 1 refers to slot 0, 2-10 refer to 1-9). It's being left in for compatibility with older scripts, and potentially for platforms with different internal predefined slot numbering.
+
+
savestate.save(object savestate)
+
+
Save the current state object to the given savestate. The argument is the result of savestate.create(). You can load this state back up by calling savestate.load(savestate) on the same object.
+
+
savestate.load(object savestate)
+
+
Load the the given state. The argument is the result of savestate.create() and has been passed to savestate.save() at least once.
+
+
If this savestate is not persistent and not one of the predefined states, the state will be deleted after loading.
+
+
savestate.persist(object savestate)
+
+
Set the given savestate to be persistent. It will not be deleted when you load this state but at the exit of this script instead, unless it's one of the predefined states. If it is one of the predefined savestates it will be saved as a file on disk.
+
+
savestate.registersave(function func)
+
+
Registers a callback function that runs whenever the user saves a state. This won't actually be called when the script itself makes a savestate, so none of those endless loops due to a misplaced savestate.save.
+
+
As with other callback-registering functions provided by FCEUX, there is only one registered callback at a time per registering function per script. Upon registering a second callback, the first is kicked out to make room for the second. In this case, it will return the first function instead of nil, letting you know what was kicked out. Registering nil will clear the previously-registered callback.
+
+
savestate.registerload(function func)
+
+
Registers a callback function that runs whenever the user loads a previously saved state. It's not called when the script itself loads a previous state, so don't worry about your script interrupting itself just because it's loading something.
+
+
The state's data is loaded before this function runs, so you can read the RAM immediately after the user loads a state, or check the new framecount. Particularly useful if you want to update lua's display right away instead of showing junk from before the loadstate.
+
+
savestate.loadscriptdata(int location)
+
+
Accuracy not yet confirmed.
+
+
Intended Function, according to snes9x LUA documentation:
+
Returns the data associated with the given savestate (data that was earlier returned by a registered save callback) without actually loading the rest of that savestate or calling any callbacks. location should be a save slot number.
+
+
+
Movie Library
+
+
bool movie.active()
+
+
Returns true if a movie is currently loaded and false otherwise. (This should be used to guard against Lua errors when attempting to retrieve movie information).
+
+
int movie.framecount()
+
+
Returns the current frame count. (Has the same affect as emu.framecount)
+
+
string movie.mode()
+
+
Returns the current state of movie playback. Returns one of the following:
+
+
- "record"
+
- "playback"
+
- "finished"
+
- "taseditor"
+
- nil
+
+
movie.rerecordcounting(bool counting)
+
+
Turn the rerecord counter on or off. Allows you to do some brute forcing without inflating the rerecord count.
+
+
movie.stop()
+
movie.close()
+
+
Stops movie playback. If no movie is loaded, it throws a Lua error.
+
+
int movie.length()
+
+
Returns the total number of frames of the current movie. Throws a Lua error if no movie is loaded.
+
+
string movie.name()
+
string movie.getname()
+
+
Returns the filename of the current movie with path. Throws a Lua error if no movie is loaded.
+
+
movie.getfilename()
+
+
Returns the filename of the current movie with no path. Throws a Lua error if no movie is loaded.
+
+
movie.rerecordcount()
+
+
Returns the rerecord count of the current movie. Throws a Lua error if no movie is loaded.
+
+
movie.replay()
+
movie.playbeginning()
+
+
Performs the Play from Beginning function. Movie mode is switched to read-only and the movie loaded will begin playback from frame 1.
+
+
If no movie is loaded, no error is thrown and no message appears on screen.
+
+
bool movie.readonly()
+
bool movie.getreadonly()
+
Alias: emu.getreadonly
+
+
FCEUX keeps the read-only status even without a movie loaded.
+
+
Returns whether the emulator is in read-only state.
+
+
While this variable only applies to movies, it is stored as a global variable and can be modified even without a movie loaded. Hence, it is in the emu library rather than the movie library.
+
+
movie.setreadonly(bool state)
+
Alias: emu.setreadonly
+
+
FCEUX keeps the read-only status even without a movie loaded.
+
+
Sets the read-only status to read-only if argument is true and read+write if false.
+
Note: This might result in an error if the medium of the movie file is not writeable (such as in an archive file).
+
+
While this variable only applies to movies, it is stored as a global variable and can be modified even without a movie loaded. Hence, it is in the emu library rather than the movie library.
+
+
bool movie.recording()
+
+
Returns true if there is a movie loaded and in record mode.
+
+
bool movie.playing()
+
+
Returns true if there is a movie loaded and in play mode.
+
+
bool movie.ispoweron()
+
+
Returns true if the movie recording or loaded started from 'Start'.
+
Returns false if the movie uses a save state.
+
Opposite of movie.isfromsavestate()
+
+
bool movie.isfromsavestate()
+
+
Returns true if the movie recording or loaded started from 'Now'.
+
Returns false if the movie was recorded from a reset.
+
Opposite of movie.ispoweron()
+
+
string movie.name()
+
+
If a movie is loaded it returns the name of the movie, else it throws an error.
+
+
bool movie.readonly()
+
+
Returns the state of read-only. True if in playback mode, false if in record mode.
+
+
+
GUI Library
+
+
gui.pixel(int x, int y, type color)
+
gui.drawpixel(int x, int y, type color)
+
gui.setpixel(int x, int y, type color)
+
gui.writepixel(int x, int y, type color)
+
+
Draw one pixel of a given color at the given position on the screen. See drawing notes and color notes at the bottom of the page.
+
+
gui.getpixel(int x, int y)
+
+
Returns the separate RGBA components of the given pixel set by gui.pixel. This only gets LUA pixels set, not background colors.
+
+
Usage is local r,g,b,a = gui.getpixel(5, 5) to retrieve the current red/green/blue/alpha values of the LUA pixel at 5x5.
+
+
See emu.getscreenpixel() for an emulator screen variant.
+
+
gui.line(int x1, int y1, int x2, int y2 [, color [, skipfirst]])
+
gui.drawline(int x1, int y1, int x2, int y2 [, color [, skipfirst]])
+
+
Draws a line between the two points. The x1,y1 coordinate specifies one end of the line segment, and the x2,y2 coordinate specifies the other end. If skipfirst is true then this function will not draw anything at the pixel x1,y1, otherwise it will. skipfirst is optional and defaults to false. The default color for the line is solid white, but you may optionally override that using a color of your choice. See also drawing notes and color notes at the bottom of the page.
+
+
gui.box(int x1, int y1, int x2, int y2 [, fillcolor [, outlinecolor]]))
+
gui.drawbox(int x1, int y1, int x2, int y2 [, fillcolor [, outlinecolor]]))
+
gui.rect(int x1, int y1, int x2, int y2 [, fillcolor [, outlinecolor]]))
+
gui.drawrect(int x1, int y1, int x2, int y2 [, fillcolor [, outlinecolor]]))
+
+
Draws a rectangle between the given coordinates of the emulator screen for one frame. The x1,y1 coordinate specifies any corner of the rectangle (preferably the top-left corner), and the x2,y2 coordinate specifies the opposite corner.
+
+
The default color for the box is transparent white with a solid white outline, but you may optionally override those using colors of your choice. Also see drawing notes and color notes.
+
+
gui.text(int x, int y, string str [, textcolor [, backcolor]])
+
gui.drawtext(int x, int y, string str [, textcolor [, backcolor]])
+
+
Draws a given string at the given position. textcolor and backcolor are optional. See 'on colors' at the end of this page for information. Using nil as the input or not including an optional field will make it use the default.
+
+
gui.parsecolor(color)
+
+
Returns the separate RGBA components of the given color.
+
For example, you can say local r,g,b,a = gui.parsecolor('orange') to retrieve the red/green/blue values of the preset color orange. (You could also omit the a in cases like this.) This uses the same conversion method that FCEUX uses internally to support the different representations of colors that the GUI library uses. Overriding this function will not change how FCEUX interprets color values, however.
+
+
gui.savescreenshot()
+
Makes a screenshot of the FCEUX emulated screen, and saves it to the appropriate folder. Performs identically to pressing the Screenshot hotkey.
+
+
gui.savescreenshotas(string name)
+
Makes a screenshot of the FCEUX emulated screen, and saves it to the appropriate folder. However, this one receives a file name for the screenshot.
+
+
string gui.gdscreenshot()
+
+
Takes a screen shot of the image and returns it in the form of a string which can be imported by the gd library using the gd.createFromGdStr() function.
+
+
This function is provided so as to allow FCEUX to not carry a copy of the gd library itself. If you want raw RGB32 access, skip the first 11 bytes (header) and then read pixels as Alpha (always 0), Red, Green, Blue, left to right then top to bottom, range is 0-255 for all colors.
+
+
Warning: Storing screen shots in memory is not recommended. Memory usage will blow up pretty quick. One screen shot string eats around 230 KB of RAM.
Draws an image on the screen. gdimage must be in truecolor gd string format.
+
+
Transparency is fully supported. Also, if alphamul is specified then it will modulate the transparency of the image even if it's originally fully opaque. (alphamul=1.0 is normal, alphamul=0.5 is doubly transparent, alphamul=3.0 is triply opaque, etc.)
+
+
dx,dy determines the top-left corner of where the image should draw. If they are omitted, the image will draw starting at the top-left corner of the screen.
+
+
gui.gdoverlay is an actual drawing function (like gui.box and friends) and thus must be called every frame, preferably inside a gui.register'd function, if you want it to appear as a persistent image onscreen.
+
+
Here is an example that loads a PNG from file, converts it to gd string format, and draws it once on the screen:
+
local gdstr = gd.createFromPng("myimage.png"):gdStr()
+
gui.gdoverlay(gdstr)
+
+
gui.opacity(int alpha)
+
+
Scales the transparency of subsequent draw calls. An alpha of 0.0 means completely transparent, and an alpha of 1.0 means completely unchanged (opaque). Non-integer values are supported and meaningful, as are values greater than 1.0. It is not necessary to use this function (or the less-recommended gui.transparency) to perform drawing with transparency, because you can provide an alpha value in the color argument of each draw call. However, it can sometimes be convenient to be able to globally modify the drawing transparency.
+
+
gui.transparency(int trans)
+
+
Scales the transparency of subsequent draw calls. Exactly the same as gui.opacity, except the range is different: A trans of 4.0 means completely transparent, and a trans of 0.0 means completely unchanged (opaque).
+
+
function gui.register(function func)
+
+
Register a function to be called between a frame being prepared for displaying on your screen and it actually happening. Used when that 1 frame delay for rendering is not acceptable.
Brings up a modal popup dialog box (everything stops until the user dismisses it). The box displays the message tostring(msg). This function returns the name of the button the user clicked on (as a string).
+
+
type determines which buttons are on the dialog box, and it can be one of the following: 'ok', 'yesno', 'yesnocancel', 'okcancel', 'abortretryignore'.
+
type defaults to 'ok' for gui.popup, or to 'yesno' for input.popup.
+
+
icon indicates the purpose of the dialog box (or more specifically it dictates which title and icon is displayed in the box), and it can be one of the following: 'message', 'question', 'warning', 'error'.
+
icon defaults to 'message' for gui.popup, or to 'question' for input.popup.
+
+
Try to avoid using this function much if at all, because modal dialog boxes can be irritating.
+
+
Linux users might want to install xmessage to perform the work. Otherwise the dialog will appear on the shell and that's less noticeable.
+
+
+
Sound Library
+
+
table sound.get()
+
+
Returns current state of PSG channels in big array.
+
+
table:
+
{
+
rp2a03:
+
{
+
square1:
+
{
+
volume, -- 0.0-1.0
+
frequency, -- in hertz
+
midikey, -- 0-127
+
duty, -- 0:12.5% 1:25% 2:50% 3:75%
+
regs: -- raw register values
+
{
+
frequency -- raw freq register value
+
}
+
},
+
square2:
+
{
+
volume, -- 0.0-1.0
+
frequency, -- in hertz
+
midikey, -- 0-127
+
duty, -- 0:12.5% 1:25% 2:50% 3:75%
+
regs: -- raw register values
+
{
+
frequency -- raw freq register value
+
}
+
},
+
triangle:
+
{
+
volume, -- 0.0-1.0
+
frequency, -- in hertz (correct?)
+
midikey, -- 0-127 (correct?)
+
regs: -- raw register values
+
{
+
frequency -- raw freq register value
+
}
+
},
+
noise:
+
{
+
volume, -- 0.0-1.0
+
short, -- true or false
+
frequency, -- in hertz (correct?)
+
midikey, -- 0-127 (correct?)
+
regs: -- raw register values
+
{
+
frequency -- raw freq register value
+
}
+
},
+
dpcm:
+
{
+
volume, -- 0.0-1.0
+
frequency, -- in hertz (correct?)
+
midikey, -- 0-127 (correct?)
+
dmcaddress, -- start position of the sample
+
dmcsize, -- size of the sample, in bytes
+
dmcloop, -- true:looped sample, false:oneshot
+
dmcseed, -- InitialRawDALatch
+
regs: -- raw register values
+
{
+
frequency -- raw freq register value
+
}
+
}
+
}
+
}
+
+
+
TAS Editor Library
+
+
taseditor.registerauto(function func)
+
taseditor.registermanual(function func)
+
bool taseditor.engaged()
+
bool taseditor.markedframe(int frame)
+
int taseditor.getmarker(int frame)
+
int taseditor.setmarker(int frame)
+
taseditor.clearmarker(int frame)
+
string taseditor.getnote(int index)
+
taseditor.setnote(int index, string newtext)
+
int taseditor.getcurrentbranch()
+
string taseditor.getrecordermode()
+
int taseditor.getsuperimpose()
+
int taseditor.getlostplayback()
+
int taseditor.getplaybacktarget()
+
taseditor.setplayback(int frame)
+
taseditor.stopseeking()
+
taseditor.getselection()
+
taseditor.setselection()
+
int taseditor.getinput(int frame, int joypad)
+
taseditor.submitinputchange(int frame, int joypad, int input)
+
taseditor.submitinsertframes(int frame, int number)
+
taseditor.submitdeleteframes(int frame, int number)
+
int taseditor.applyinputchanges([string name])
+
taseditor.clearinputchanges()
+
+
For full description of these functions refer to TAS Editor Manual.
+
+
+
Bitwise Operations
+
+
The following bit functions were added to FCEUX internally to compensate for Lua's lack of them. But it also supports all operations from LuaBitOp module, since it is also embedded in FCEUX.
+
+
int AND(int n1, int n2, ..., int nn)
+
+
Binary logical AND of all the given integers.
+
+
int OR(int n1, int n2, ..., int nn)
+
+
Binary logical OR of all the given integers.
+
+
int XOR(int n1, int n2, ..., int nn)
+
+
Binary logical XOR of all the given integers.
+
+
int BIT(int n1, int n2, ..., int nn)
+
+
Returns an integer with the given bits turned on. Parameters should be smaller than 31.
+
+
Appendix
+
+
On drawing
+
+
A general warning about drawing is that it is always one frame behind unless you use gui.register. This is because you tell the emulator to paint something but it will actually paint it when generating the image for the next frame. So you see your painting, except it will be on the image of the next frame. You can prevent this with gui.register because it gives you a quick chance to paint before blitting.
+
+
Dimensions & color depths you can paint in:
+
--320x239, 8bit color (confirm?)
+
256x224, 8bit color (confirm?)
+
+
On colors
+
+
Colors can be of a few types.
+
Int: use the a formula to compose the color as a number (depends on color depth)
+
String: Can either be a HTML colors, simple colors, or internal palette colors.
+
HTML string: "#rrggbb" ("#228844") or #rrggbbaa if alpha is supported.
Lua is built into FCEUX as of 2.1.2, and luapack DLL files are no longer needed in this and later versions.
-
-
To run lua scripts in older versions of FCEUX, you will need the lua pack which can be found here. The .dll files must be unzipped in the same folder as fceux.exe.
-
-
Core Lua Documentation
-
-
If you have never programmed, you will probably want to start by learning the basic of Lua, which is too broad for the scope of this help file. Try searching on the Internet for "Lua tutorial". As of this writing, it's official homepage is http://www.lua.org/
-
-
If you are familiar with any programming language you will probably not have too much difficulty adjusting to the syntax and structure of Lua. You will probably also find useful information on the Internet.
-
-
GUI Frontend
-
-
To use a Lua script, you need to create one in a text editor. The name of the file created should end in .lua to indicate that it is a Lua script.
-
-
To run a Lua script, choose "Run Lua Script" ***from where*** In the dialog that pops up, click "Browse" and find the file you wish to run. This will insert the path of this file into the dialog. You can then click on "Run" to run the script or "Cancel" to return to FCEUX without running the script.
-
-
To end a Lua script, choose "Stop Lua Script" ***from where***.
-
-
FCEUX Lua Basics
-
-
Your script will be constructed according to the rules of Lua, but you will use FCEUX-specific functions to interact with the emulator. For example, one of the most often-used functions is emu.frameadvance() which will tell the emulator to advance exactly one frame, which is the basic unit of time on an NES.
-
-
In general, your script will probably want to be run until you tell it to stop, so it will look something like this:
-
-
emu.speedmode("normal") -- Set the speed of the emulator
-
-
-- Declare and set variables or functions if needed
-
-
while true do
-
-- Execute instructions for FCEUX
-
emu.frameadvance() -- This essentially tells FCEUX to keep running
-
end
-
-
The way instructions are sent to FCEUX is through a set of specially defined functions (and variables) which are called an API, the specification of which follows.
Lua is built into FCEUX as of 2.1.2, and luapack DLL files are no longer needed in this and later versions.
+
+
To run lua scripts in older versions of FCEUX, you will need the lua pack which can be found here. The .dll files must be unzipped in the same folder as fceux.exe.
+
+
Core Lua Documentation
+
+
If you have never programmed, you will probably want to start by learning the basic of Lua, which is too broad for the scope of this help file. Try searching on the Internet for "Lua tutorial". As of this writing, it's official homepage is http://www.lua.org/
+
+
If you are familiar with any programming language you will probably not have too much difficulty adjusting to the syntax and structure of Lua. You will probably also find useful information on the Internet.
+
+
GUI Frontend
+
+
To use a Lua script, you need to create one in a text editor. The name of the file created should end in .lua to indicate that it is a Lua script.
+
+
To run a Lua script, choose "Run Lua Script" ***from where*** In the dialog that pops up, click "Browse" and find the file you wish to run. This will insert the path of this file into the dialog. You can then click on "Run" to run the script or "Cancel" to return to FCEUX without running the script.
+
+
To end a Lua script, choose "Stop Lua Script" ***from where***.
+
+
FCEUX Lua Basics
+
+
Your script will be constructed according to the rules of Lua, but you will use FCEUX-specific functions to interact with the emulator. For example, one of the most often-used functions is emu.frameadvance() which will tell the emulator to advance exactly one frame, which is the basic unit of time on an NES.
+
+
In general, your script will probably want to be run until you tell it to stop, so it will look something like this:
+
+
emu.speedmode("normal") -- Set the speed of the emulator
+
+
-- Declare and set variables or functions if needed
+
+
while true do
+
-- Execute instructions for FCEUX
+
emu.frameadvance() -- This essentially tells FCEUX to keep running
+
end
+
+
The way instructions are sent to FCEUX is through a set of specially defined functions (and variables) which are called an API, the specification of which follows.
The following Lua libraries are integrated into FCEUX win32-executable (statically linked) and are available for using in your scripts. You can also use any other Lua library by placing its .dll files into FCEUX folder.
-
-
-
IUP library
-
-
IUP (Portable User Interface) is a toolkit for building graphical user interfaces.
IM is a toolkit for Digital Imaging. The main goal of the library is to provide a simple API and abstraction of images for applications.
-
File formats supported: TIFF, BMP, PNG, JPEG, GIF and AVI. Image representation includes scientific data types. About a hundred Image Processing operations are available.
The library contains functions to support both vector and image applications, and the visualization surface can be either a window or a more abstract surface, such as Image, Clipboard, Metafile, PS, and so on.
LuaSocket is a Lua extension library that is composed by two parts: a C core that provides support for the TCP and UDP transport layers, and a set of Lua modules that add support for the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and downloading files) protocols and other functionality commonly needed by applications that deal with the Internet.
The following Lua libraries are integrated into FCEUX win32-executable (statically linked) and are available for using in your scripts. You can also use any other Lua library by placing its .dll files into FCEUX folder.
+
+
+
IUP library
+
+
IUP (Portable User Interface) is a toolkit for building graphical user interfaces.
IM is a toolkit for Digital Imaging. The main goal of the library is to provide a simple API and abstraction of images for applications.
+
File formats supported: TIFF, BMP, PNG, JPEG, GIF and AVI. Image representation includes scientific data types. About a hundred Image Processing operations are available.
The library contains functions to support both vector and image applications, and the visualization surface can be either a window or a more abstract surface, such as Image, Clipboard, Metafile, PS, and so on.
LuaSocket is a Lua extension library that is composed by two parts: a C core that provides support for the TCP and UDP transport layers, and a set of Lua modules that add support for the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and downloading files) protocols and other functionality commonly needed by applications that deal with the Internet.
Lua is a scripting language similar to Perl or Python. It allows for logical evaluation equivalent to languages like C but in a much more dynamic way that eliminates much of the need to compile programs and worry about low level resource management like deleting objects. In the context of FCEUX, Lua allows for direct control of the emulator through this logical construct.
-
-
What this means to a non-"programmer" is that you can essentially automate certain tasks in FCEUX, such as holding controller inputs, displaying additional graphical information and saving/loading savestates.
-
-
A bit of previous programming knowledge will be useful in taking advantage of this feature, but it is certainly not a requirement. Lua is specifically written with the intention of being easier than most languages for anyone to understand and use.
Lua is a scripting language similar to Perl or Python. It allows for logical evaluation equivalent to languages like C but in a much more dynamic way that eliminates much of the need to compile programs and worry about low level resource management like deleting objects. In the context of FCEUX, Lua allows for direct control of the emulator through this logical construct.
+
+
What this means to a non-"programmer" is that you can essentially automate certain tasks in FCEUX, such as holding controller inputs, displaying additional graphical information and saving/loading savestates.
+
+
A bit of previous programming knowledge will be useful in taking advantage of this feature, but it is certainly not a requirement. Lua is specifically written with the intention of being easier than most languages for anyone to understand and use.
The map hotkeys dialog allows you to assign hotkeys to various FCEUX commands.
-
-
To assign or remove a hotkey assignment, double click on the name of the hotkey in the list box. Then press the key combination you wish to assign it. To clear the assignment, press the clear button.
-
-
The filter pull down menu allows you to only see hotkey listings in various categories (the list shows all hotkey assignments by default).
-
-
The Restore defaults button will change all hotkeys to their default values.
The map hotkeys dialog allows you to assign hotkeys to various FCEUX commands.
+
+
To assign or remove a hotkey assignment, double click on the name of the hotkey in the list box. Then press the key combination you wish to assign it. To clear the assignment, press the clear button.
+
+
The filter pull down menu allows you to only see hotkey listings in various categories (the list shows all hotkey assignments by default).
+
+
The Restore defaults button will change all hotkeys to their default values.
Memory watch is a tool designed to values of specific known memory values in the game's RAM. Memory watch does not find values. To find useful values to monitor, see Cheats, Ram filter, Hex Editor, and Debugger.
-
-
-
Inserting Values
-
-
To display a ram value, simply type its address into one of the address fields. The name field allows you to put a brief description of the value.
-
-
-
Prefixes
-
-
You must put in the hexi-decimal value of the address, but the value will be displayed will be decimal by default.
-
-
To display the value in hex, use a prefix of "x" (such as x00FD).
-
-
Use the prefix "!" to display a 2 byte value.
-
-
Use a prefix of "X" to watch a 2 byte value in hex.
-
-
-
Saving/Loading Watch files
-
-
You can save your addresses into watch files, as well as loading previous files using the standard save,load,new options in the File menu.
-
-
FCEUX uses the /memw folder by default but you can specify a new default folder in the Directory Override menu.
-
-
-
Options Menu
-
-
If you select Load on Start up, Memory watch will load up automatically when FCEU is started.
-
-
If you select Load Last File on Start up, the most recent file in the Recent folder will be loaded when memory watch is loaded.
-
-
If you select Collapse to 1 Column (or press the right arrow button on the bottom left of the dialog), the memory watch dialog is reduced to just 1 column.
-
-
Frozen Memory Addresses
-
-
If one of the watched addresses is frozen by the cheats dialog or the hex editor, it will display blue in the memory watch dialog.
-
-
-
Memory Change Monitor
-
-
The bottom of the memory watch dialog displays a memory change monitoring section. This monitors the 1st two values of each memory watch column. Rather than monitoring the value itself, this monitors the value's behavior.
-
-
The address being monitored is under the address column.
-
-
The Formula drop down box shows which criteria the change monitoring is using.
-
-
The count value displays how many times the value has changed based on the criteria.
-
-
Reset will reset the count to 0.
-
-
-
Usage Example:
-
-
As an example of the memory change monitoring, Let's say we are recording a movie of the game Super C and want to keep track of when the game lags.
-
The ram address 001C functions as a "lag flag". It will remain 0, then change to a positive value on a frame that the game lags.
-
-
We could put 001C in one of the 1st two memory watch edit boxes. Then set the corresponding formula in the memory change monitoring to "> then" (greater than). Now the count will show us how many lag frames occur in the movie.
Memory watch is a tool designed to values of specific known memory values in the game's RAM. Memory watch does not find values. To find useful values to monitor, see Cheats, Ram filter, Hex Editor, and Debugger.
+
+
+
Inserting Values
+
+
To display a ram value, simply type its address into one of the address fields. The name field allows you to put a brief description of the value.
+
+
+
Prefixes
+
+
You must put in the hexi-decimal value of the address, but the value will be displayed will be decimal by default.
+
+
To display the value in hex, use a prefix of "x" (such as x00FD).
+
+
Use the prefix "!" to display a 2 byte value.
+
+
Use a prefix of "X" to watch a 2 byte value in hex.
+
+
+
Saving/Loading Watch files
+
+
You can save your addresses into watch files, as well as loading previous files using the standard save,load,new options in the File menu.
+
+
FCEUX uses the /memw folder by default but you can specify a new default folder in the Directory Override menu.
+
+
+
Options Menu
+
+
If you select Load on Start up, Memory watch will load up automatically when FCEU is started.
+
+
If you select Load Last File on Start up, the most recent file in the Recent folder will be loaded when memory watch is loaded.
+
+
If you select Collapse to 1 Column (or press the right arrow button on the bottom left of the dialog), the memory watch dialog is reduced to just 1 column.
+
+
Frozen Memory Addresses
+
+
If one of the watched addresses is frozen by the cheats dialog or the hex editor, it will display blue in the memory watch dialog.
+
+
+
Memory Change Monitor
+
+
The bottom of the memory watch dialog displays a memory change monitoring section. This monitors the 1st two values of each memory watch column. Rather than monitoring the value itself, this monitors the value's behavior.
+
+
The address being monitored is under the address column.
+
+
The Formula drop down box shows which criteria the change monitoring is using.
+
+
The count value displays how many times the value has changed based on the criteria.
+
+
Reset will reset the count to 0.
+
+
+
Usage Example:
+
+
As an example of the memory change monitoring, Let's say we are recording a movie of the game Super C and want to keep track of when the game lags.
+
The ram address 001C functions as a "lag flag". It will remain 0, then change to a positive value on a frame that the game lags.
+
+
We could put 001C in one of the 1st two memory watch edit boxes. Then set the corresponding formula in the memory change monitoring to "> then" (greater than). Now the count will show us how many lag frames occur in the movie.
The movie option dialog has various settings related to movie making.
-
-
Always suggest Read-Only replay
-
-
If checked, FCEUX will automatically check "Open Read-Only" checkbox when showing "Play Movie" dialog. If unchecked, the "Open Read-Only" checkbox state will depend on current movie status.
-
-
-
Pause After Movie Playback
-
-
If checked, FCEUX will automatically pause emulation when reaching the last frame of a movie file.
-
-
-
Close After Movie Playback
-
-
If checked, FCEUX will close the movie after replaying its last frame. If unchecked, when reaching the last frame the movie will switch to "MOVIE_FINISHED" state, still allowing you to load its savestates.
-
-
-
Bind savestates to movies
-
-
Affects the savestate naming system when a movie is loaded. If checked, the movie name will be appended to a savestate filename.
-
-
-
Display movie subtitles
-
-
Toggles whether or not movie subtitles (imbedded into the .fm2 file, see .fm2 documentation) will be displayed on screen.
-
-
-
Put movie subtitles in AVI
-
-
Toggles whether or not movie subtitles will be recorded into a .avi file.
-
-
-
Automatically backup movies
-
-
If checked, the auto-movie backup is toggled on. Whenever a movie is loaded then set into record mode (by loading a savestate while in read-write mode), a backup copy of the .fm2 is saved before changing the file.
-
-
Movie backups will be created only once each time a movie is loaded into FCEUX. Movie backups are appended with a backup number and the .bak file extension.
-
-
-
Load full savestate-movies
-
-
If checked, FCEUX will not truncate movie immediately when you load its savestate in Recording mode (thus behaving similar to VBA-rr and Snes9x emulators). If unchecked, the movie will always shrink to the frame of the savestate you loaded.
The movie option dialog has various settings related to movie making.
+
+
Always suggest Read-Only replay
+
+
If checked, FCEUX will automatically check "Open Read-Only" checkbox when showing "Play Movie" dialog. If unchecked, the "Open Read-Only" checkbox state will depend on current movie status.
+
+
+
Pause After Movie Playback
+
+
If checked, FCEUX will automatically pause emulation when reaching the last frame of a movie file.
+
+
+
Close After Movie Playback
+
+
If checked, FCEUX will close the movie after replaying its last frame. If unchecked, when reaching the last frame the movie will switch to "MOVIE_FINISHED" state, still allowing you to load its savestates.
+
+
+
Bind savestates to movies
+
+
Affects the savestate naming system when a movie is loaded. If checked, the movie name will be appended to a savestate filename.
+
+
+
Display movie subtitles
+
+
Toggles whether or not movie subtitles (imbedded into the .fm2 file, see .fm2 documentation) will be displayed on screen.
+
+
+
Put movie subtitles in AVI
+
+
Toggles whether or not movie subtitles will be recorded into a .avi file.
+
+
+
Automatically backup movies
+
+
If checked, the auto-movie backup is toggled on. Whenever a movie is loaded then set into record mode (by loading a savestate while in read-write mode), a backup copy of the .fm2 is saved before changing the file.
+
+
Movie backups will be created only once each time a movie is loaded into FCEUX. Movie backups are appended with a backup number and the .bak file extension.
+
+
+
Load full savestate-movies
+
+
If checked, FCEUX will not truncate movie immediately when you load its savestate in Recording mode (thus behaving similar to VBA-rr and Snes9x emulators). If unchecked, the movie will always shrink to the frame of the savestate you loaded.
A movie file is a file which contains data needed to reconstruct actions in a game. In most emulators, the movie files consist of simply the buttons that were pressed during the game. Because the emulation is completely predictable (deterministic), it will always play back the same way.
-
-
Unless the movie starts from the console power-on or from reset, the movie file might also contain a savestate that loads the beginning point of the game. Movie files don’t contain any sound or image data. Such data is not needed, because the emulator can reconstruct it during movie playback.
-
-
Movie files in FCEUX are .fm2 files. The file format is unique to FCEUX and not compatible with other movie recording versions of FCE Ultra. Movie files from other versions (.fcm) can be converted to .fm2 for playback with the .fcm to .fm2 converter.
-
-
Movie features in FCEUX are designed specifically for making Tool-assisted Speedruns. For more information visit TASVideos.
-
-
Recording Movies
-
-
To record a movie, open a ROM. Then simply select "Record Movie" in the File > Movie Menu. You will be prompted to name the file and to select where to record from. Selecting "Start" will begin the recording from a Power-on (Hard Reset). If you select "Now", a savestate will be made at your current location in the game, and the movie will begin recording from there. If you select browse, you will be prompted to find a preexisting savestate file to begin recording from.
-
-
-
Savestates, Slowdown, and Frame Advance
-
-
At anytime while recording, you can make a *savestate. This is a snapshot of the game's current memory contents. Once a savestate is made, it can be loaded with the *loadstate command. This will return the movie back to the spot in the game where the savestate was made. This can be used to undo mistakes or to test different strategies for a particular segment.
-
-
(The default key for making a savestate is "I" and the default key for loading a state is "P". Both of these can be assigned under the Map Hotkeys Menu). Both can also be access through the File > Savestate Menu
-
-
Tool Assisted movies take advantage of slowing the emulator down in order to increase precision of the movie making process. Navigating to NES > Emulation Speed > Slow down or pressing the "-" key will slow down emulation. NES > Emulation Speed > Speed up or the "=" will speed it up. (These can be re-mapped in the Map Hotkeys Menu).
-
-
Even greater precision can be made using the frame advance key. Pressing the frame advance key will pause emulation and advance it a single frame (1/60th of a second NTSC ). By holding down input and pressing the frame advance key, it will record that input for that particular frame.
All savestates made during movie recording contain the movie information up to the frame of the savestate. When a savestate is loaded, the movie file in the savestate is also loaded. This is referred to as "Bullet Proof Rerecording" because it prevents possible desyncs and lost data from improper/out of order savestate loading.
-
-
-
Playing Back Movies
-
-
To play back a recorded movie, open the ROM. Then select "Replay Movie" in the File Menu. A movie dialog box will open where you can select the movie file.
-
-
You can also select whether the movie is in Read-only mode. If a movie is in read-only mode, the movie file can not be altered in any way. If you make a savestate while playing the movie and load that state, the playback will simply "rewind" to that state. If the movie is not in read-only, however, loading a state will set the movie to record mode and begin recording from that savestate.
-
-
You can also select "Pause movie at frame" x. If selected, the movie will automatically pause when reaching the frame selected (the default is the last frame of the movie).
-
-
-
Read only
-
-
You can select read-only when playing a movie. You can also toggle the read-only status by navigating to File > Movie > Read only.
-
In read-only mode a movie can not be edited. Loading a savestate will take the movie to that point in the movie and stay in playback mode.
-
-
In read-write status, loading a state will change a movie from playback mode to record mode.
-
-
-
Resuming Recording
-
-
You can resume recording a previous movie by playing back the movie, setting the record status to read+write, and then loading a state.
-
-
-
Play Movie from Beginning
-
-
At any point while recording or playing back a movie, you can navigate to File > Movie > Play Movie from Beginning. This will set the movie to read only status and reset playback to frame 0.
-
-
Frame Counter
-
-
The Frame counter displays what frame the movie is currently on. If the movie is playing in read-only mode, it will also display the total number of frames in the movie. The default key for toggling the Frame Counter display is the "." (period) key. (This can be re-mapped in the Map Hotkeys Menu).
-
-
-
Frame Advance
-
-
The frame advance key ("backlash" key by default. Re-mappable under the Map Hotkeys Menu) will advance the game by a single frame and then pause the game. If the hotkey is held down, it will auto advance quickly through the game.
-
-
This is a critical tool when perfecting input in movie recording.
-
-
Metadata
-
-
When you record a new movie via the record movie dialog there is an author field. This sends the info to the .fm2 file in the form of comment Author [author name] (see .fm2).
-
-
Any line in the .fm2 that starts with "comment" is known as metadata. You can include any number of comments manually by editing the .fm2 file with any text editor.
-
-
On the replay movie dialog, clicking the metadata button will display all metadata in a separate dialog box (If a movie is currently loaded you can also access the meta-data by right-clicking and selecting Metadata in the context menu).
-
-
-
Subtitles
-
-
FCEUX now supports subtitles in the .fm2 file format. Subtitles will be displayed on the screen automatically as a movie plays. You can turn on/off subtitles by navigating to Config > Movie Options > Display movie subtitles (see Movie options).
A movie file is a file which contains data needed to reconstruct actions in a game. In most emulators, the movie files consist of simply the buttons that were pressed during the game. Because the emulation is completely predictable (deterministic), it will always play back the same way.
+
+
Unless the movie starts from the console power-on or from reset, the movie file might also contain a savestate that loads the beginning point of the game. Movie files don’t contain any sound or image data. Such data is not needed, because the emulator can reconstruct it during movie playback.
+
+
Movie files in FCEUX are .fm2 files. The file format is unique to FCEUX and not compatible with other movie recording versions of FCE Ultra. Movie files from other versions (.fcm) can be converted to .fm2 for playback with the .fcm to .fm2 converter.
+
+
Movie features in FCEUX are designed specifically for making Tool-assisted Speedruns. For more information visit TASVideos.
+
+
Recording Movies
+
+
To record a movie, open a ROM. Then simply select "Record Movie" in the File > Movie Menu. You will be prompted to name the file and to select where to record from. Selecting "Start" will begin the recording from a Power-on (Hard Reset). If you select "Now", a savestate will be made at your current location in the game, and the movie will begin recording from there. If you select browse, you will be prompted to find a preexisting savestate file to begin recording from.
+
+
+
Savestates, Slowdown, and Frame Advance
+
+
At anytime while recording, you can make a *savestate. This is a snapshot of the game's current memory contents. Once a savestate is made, it can be loaded with the *loadstate command. This will return the movie back to the spot in the game where the savestate was made. This can be used to undo mistakes or to test different strategies for a particular segment.
+
+
(The default key for making a savestate is "I" and the default key for loading a state is "P". Both of these can be assigned under the Map Hotkeys Menu). Both can also be access through the File > Savestate Menu
+
+
Tool Assisted movies take advantage of slowing the emulator down in order to increase precision of the movie making process. Navigating to NES > Emulation Speed > Slow down or pressing the "-" key will slow down emulation. NES > Emulation Speed > Speed up or the "=" will speed it up. (These can be re-mapped in the Map Hotkeys Menu).
+
+
Even greater precision can be made using the frame advance key. Pressing the frame advance key will pause emulation and advance it a single frame (1/60th of a second NTSC ). By holding down input and pressing the frame advance key, it will record that input for that particular frame.
All savestates made during movie recording contain the movie information up to the frame of the savestate. When a savestate is loaded, the movie file in the savestate is also loaded. This is referred to as "Bullet Proof Rerecording" because it prevents possible desyncs and lost data from improper/out of order savestate loading.
+
+
+
Playing Back Movies
+
+
To play back a recorded movie, open the ROM. Then select "Replay Movie" in the File Menu. A movie dialog box will open where you can select the movie file.
+
+
You can also select whether the movie is in Read-only mode. If a movie is in read-only mode, the movie file can not be altered in any way. If you make a savestate while playing the movie and load that state, the playback will simply "rewind" to that state. If the movie is not in read-only, however, loading a state will set the movie to record mode and begin recording from that savestate.
+
+
You can also select "Pause movie at frame" x. If selected, the movie will automatically pause when reaching the frame selected (the default is the last frame of the movie).
+
+
+
Read only
+
+
You can select read-only when playing a movie. You can also toggle the read-only status by navigating to File > Movie > Read only.
+
In read-only mode a movie can not be edited. Loading a savestate will take the movie to that point in the movie and stay in playback mode.
+
+
In read-write status, loading a state will change a movie from playback mode to record mode.
+
+
+
Resuming Recording
+
+
You can resume recording a previous movie by playing back the movie, setting the record status to read+write, and then loading a state.
+
+
+
Play Movie from Beginning
+
+
At any point while recording or playing back a movie, you can navigate to File > Movie > Play Movie from Beginning. This will set the movie to read only status and reset playback to frame 0.
+
+
Frame Counter
+
+
The Frame counter displays what frame the movie is currently on. If the movie is playing in read-only mode, it will also display the total number of frames in the movie. The default key for toggling the Frame Counter display is the "." (period) key. (This can be re-mapped in the Map Hotkeys Menu).
+
+
+
Frame Advance
+
+
The frame advance key ("backlash" key by default. Re-mappable under the Map Hotkeys Menu) will advance the game by a single frame and then pause the game. If the hotkey is held down, it will auto advance quickly through the game.
+
+
This is a critical tool when perfecting input in movie recording.
+
+
Metadata
+
+
When you record a new movie via the record movie dialog there is an author field. This sends the info to the .fm2 file in the form of comment Author [author name] (see .fm2).
+
+
Any line in the .fm2 that starts with "comment" is known as metadata. You can include any number of comments manually by editing the .fm2 file with any text editor.
+
+
On the replay movie dialog, clicking the metadata button will display all metadata in a separate dialog box (If a movie is currently loaded you can also access the meta-data by right-clicking and selecting Metadata in the context menu).
+
+
+
Subtitles
+
+
FCEUX now supports subtitles in the .fm2 file format. Subtitles will be displayed on the screen automatically as a movie plays. You can turn on/off subtitles by navigating to Config > Movie Options > Display movie subtitles (see Movie options).
Emulates the inserting of a coin in an arcade-style game.
-
-
-
Emulation Speed Sub Menu
-
-
Speed Up
-
Speeds up emulation (emulation speed ranges from 1% to 6400%)
-
-
Slow Down
-
Slows down emulation
-
-
Slowest Speed
-
Sets emulation to 1% speed
-
-
Normal Speed
-
Sets emulation speed to 100%
-
-
Turbo
-
Toggles turbo mode. In turbo mode, emulation is set its fastest settings.
-
-
Set Custom Speed
-
Allows you to define emulation speed by entering the number of percents (1-1000, default is 100%)
-
-
Set FrameAdvance Delay
-
Here you can fine-tune the working of the Frame Advance key. This setting defines the delay between the moment you press Frame Advance and the moment it starts continuous emulation
-
-
Set custom speed for FrameAdvance
-
Here you can fine-tune the working of the Frame Advance key. This setting defines the speed of continuous emulation while you're holding Frame Advance. If you leave it 0 (zero), the emulation speed will be the same as the current emulation speed (from 1% to 6400%), but if you enter a number from 1 to 1000, the current emulation speed will be ignored when holding Frame Advance.
Emulates the inserting of a coin in an arcade-style game.
+
+
+
Emulation Speed Sub Menu
+
+
Speed Up
+
Speeds up emulation (emulation speed ranges from 1% to 6400%)
+
+
Slow Down
+
Slows down emulation
+
+
Slowest Speed
+
Sets emulation to 1% speed
+
+
Normal Speed
+
Sets emulation speed to 100%
+
+
Turbo
+
Toggles turbo mode. In turbo mode, emulation is set its fastest settings.
+
+
Set Custom Speed
+
Allows you to define emulation speed by entering the number of percents (1-1000, default is 100%)
+
+
Set FrameAdvance Delay
+
Here you can fine-tune the working of the Frame Advance key. This setting defines the delay between the moment you press Frame Advance and the moment it starts continuous emulation
+
+
Set custom speed for FrameAdvance
+
Here you can fine-tune the working of the Frame Advance key. This setting defines the speed of continuous emulation while you're holding Frame Advance. If you leave it 0 (zero), the emulation speed will be the same as the current emulation speed (from 1% to 6400%), but if you enter a number from 1 to 1000, the current emulation speed will be ignored when holding Frame Advance.
This guide gives a map of the addresses in the NES cpu and explains each portion in detail.
-
-
It also provides information for the basic layout of ram values in typical NES games. This info can be used to quickly map and find useful values in the game's ram.
-
-
Contents
-
-
Memory Map
-
Gives a diagram of the 2A03 CPU memory map .
-
-
2C02 PPU memory map
-
Gives more detailed info about each section of the Memory map diagram
-
-
Game Ram Details
-
On board RAM Map ($000-$07FF) Map (gives specific info on the how NES games typically layout their ram values)
2A03 CPU is a 6502-compatible CPU without the decimal mode (CLD and SED do nothing). It has an on-die sound generator, very limited DMA capability, and an input device controller that can be accessed through the 2A03 registers.
-
-
-
6502 CPU Memory Map
-
Address Range Size in bytes Notes (Page size = 256bytes)
-
(Hexadecimal)
-
-
$0000 - $07FF 2048 Game Ram
-
-
($0000 - $00FF) 256 Zero Page - Special Zero Page addressing modes give faster memory read/write access
-
($0100 - $01FF) 256 Stack memory
-
($0200 - $07FF) 1536 RAM
-
-
-
$0800 - $0FFF 2048 Mirror of $0000-$07FF
-
-
($0800 - $08FF) 256 Zero Page
-
($0900 - $09FF) 256 Stack
-
($0A00 - $0FFF) 1024 Ram
-
-
-
$1000 - $17FF 2048 bytes Mirror of $0000-$07FF
-
-
($1000 - $10FF) 256 Zero Page
-
$1100 - $11FF 256 Stack
-
$1200 - $17FF 1024 RAM
-
-
-
$1800 - $1FFF 2048 bytes Mirror of $0000-$07FF
-
-
($1800 - $18FF) 256 Zero Page
-
($1900 - $19FF) 256 Stack
-
($1A00 - $1FFF) 1024 RAM
-
-
-
$2000 - $2007 8 bytes Input / Output registers
-
$2008 - $3FFF 8184 bytes Mirror of $2000-$2007 (mulitple times)
-
-
-
$4000 - $401F 32 bytes Input / Output registers
-
$4020 - $5FFF 8160 bytes Expansion ROM - Used with Nintendo's MMC5 to expand the capabilities of VRAM.
-
-
-
$6000 - $7FFF 8192 bytes SRAM - Save Ram used to save data between game plays.
The NES PPU has enough RAM for two nametables (0 and 3); it brings some PPU nametable address lines to the cart edge so that the cart can decide whether to map 0 onto 2 and 1 onto 3 (vertical mirroring as in Super Mario Brothers and Contra) or 0 onto 1 and 2 onto 3 (horizontal mirroring as in Kid Icarus and Ikari), all screens to either 0 or 3 (as in many Rare games such as Battletoads and Jeopardy!), or all screens to RAM on the cartridge (as in Gauntlet). Split-screen games that scroll in all four directions (such as Super Mario Brothers 3 and Kirby's Adventure) often use vertical or one-screen mirroring (with a small amount of screen corruption at the sides due to tiles wrapping around the sides) and stick the status bar in some random unused area of the screen.
-
-
-
Game RAM Details
-
Mapping RAM/Finding Ram
-
Written by: adelikat
-
-
This guide is written specifically for finding useful values for TAS movie making.
-
It does not tell you how to use specific tools to find values. For that refer to Hex editor, Cheat Search, and RAM filter.
-
-
Most games use the basic on board ram. The address range of this ram is $0000-$07FF. This translates to 2048 possible ram values.
-
-
Pages
-
-
This ram is broken down into 8 pages. A "page" is a block of 256 ram values.
-
-
I will refer to these values as such:
-
Block 0 $00xx ($0000-$00FF)
-
Block 1 $01xx ($0100-$01FF)
-
Block 2 $02xx ($0200-$02FF)
-
Block 3 $03xx ($0300-$03FF)
-
Block 4 $04xx ($0400-$04FF)
-
Block 5 $05xx ($0500-$05FF)
-
Block 6 $06xx ($0600-$06FF)
-
Block 7 $07xx ($0700-$07FF)
-
-
Each block will be organized will similar data. For instance, all sprite data will be in the same block. Enemy/Player statistics (energy, coordinates, speed, etc.) will be in another. For instance, if you find the main character's HP and it is located in block 3, you know that the remaining stats for the character are also in that block. This can significantly cut down time when trying to find related values.
-
-
There are always the following blocks:
-
-
Sprite DataBlock 2
-
-
I've yet to see map a game that does not use this block solely for sprite data. It will contain the "ID" numbers for all the items currently on the screen. Simply put, this data is precisely the data you see on the screen. For making TAS movies this is not useful data. If you are using cheat search and have narrowed it down your search to a few values, you can immediately discard any $02xx values.
-
-
In games with a lot of sprite data, I've seen blocks 1 & 3 also reserved for sprite data.
-
-
Music & Sound FXBlock 1 or 7, generally
-
-
This one has more deviation, but almost all games reserve an entire block for memory allocated to the game's Music and Sound FX. Again, for TAS purposes these values are not *useful. By finding even 1 of these values, you can eliminate that block from your search possibilities. Finding which block is reserved for music is often quite simple with the Hex editor. Watching the ram values with the game playing, you can see which addresses "move to the beat".
-
-
*Actually they can come in handy for "dancing to the beat"
-
-
Player & Enemy Stats Blocks 1,3,4,5 generally (any or all of these)
-
-
This is your "sweet spot" for movie making, as often you will be wanting to track the players speed or coordinates, enemy energy, or enemy coordinates.
-
-
These values rarely (if at all) reside outside blocks 1, 3, 4, or 5. This knowledge already reduces your search possibilities in half!
-
-
Rows
-
-
Each block is broken down into 16 "rows" of addresses. For example, in block 3, the first row is $030x ($0300-$030F).
-
-
Each row of 16* will contain similar data. For instance all x coordinates will generally be in the same row. So xxx0 might be the main characters x position. xxxx1 would be "enemy 1" (1st enemy loaded onto the screen), and so on.
-
-
The y coordinates would be in another row, x subpixel values in yet another row, etc.
-
-
*Super Mario Bros. 2 (U) is a rare example that uses rows of 10
-
-
Columns
-
-
A column would be all the values of a block that share the same last digit. So a column would be 16 addresses such as $0300, $0310, $0320, etc.
-
-
For enemy/player stats, columns usually refer to the same player or enemy.
-
-
So for example, if a player's energy was stored in $0300. The remaining row will be other player/enemy's energy.
-
-
If the next row ($031x) is x positions. $0310 would be the player's x position. The remaining positions of that row would correspond to the other player/enemy x positions in line with the hp values of the previous row.
-
-
Example
-
-
These distinctions are easier to see in a visual example. This is the enemy/player stats as they are mapped in the game Teenage Mutant Ninja Turtles.
-
-
Block 4
-
P W1 W2 W3 E1 E2 E3 E4 E5 E6 E7 E8 X X X X
-
Sprite ID: 040x: 09 00 00 00 00 9E 9E 9E 9E 00 00 00 00 00 00 00
E1 = "Enemy slot 1" which will be the first enemy on the screen loaded into memory. The 2nd will be placed in "Enemy slot 2". When enemy 1 is removed from memory (killed or goes off screen), the next enemy will be loaded into that slot. Enemy's always take the lowest available slot when loaded. Note: usually enemy slots are in reverse order. So the first addresses is usually the last enemy slot loaded into memory. TMNT is an exception.
-
-
All object (player, weapon, enemy) characteristics reside in block 4.
-
Each row is a different characteristic of each object on the screen (040x refers to a sprite ID of an object)
-
Each column corresponds to a specific object on the screen. (All 04x0 's refer to the player).
This guide gives a map of the addresses in the NES cpu and explains each portion in detail.
+
+
It also provides information for the basic layout of ram values in typical NES games. This info can be used to quickly map and find useful values in the game's ram.
+
+
Contents
+
+
Memory Map
+
Gives a diagram of the 2A03 CPU memory map .
+
+
2C02 PPU memory map
+
Gives more detailed info about each section of the Memory map diagram
+
+
Game Ram Details
+
On board RAM Map ($000-$07FF) Map (gives specific info on the how NES games typically layout their ram values)
2A03 CPU is a 6502-compatible CPU without the decimal mode (CLD and SED do nothing). It has an on-die sound generator, very limited DMA capability, and an input device controller that can be accessed through the 2A03 registers.
+
+
+
6502 CPU Memory Map
+
Address Range Size in bytesNotes (Page size = 256bytes)
+
(Hexadecimal)
+
+
$0000 - $07FF2048Game Ram
+
+
($0000 - $00FF)256 Zero Page - Special Zero Page addressing modes give faster memory read/write access
+
($0100 - $01FF)256 Stack memory
+
($0200 - $07FF)1536 RAM
+
+
+
$0800 - $0FFF 2048 Mirror of $0000-$07FF
+
+
($0800 - $08FF)256 Zero Page
+
($0900 - $09FF) 256 Stack
+
($0A00 - $0FFF)1024Ram
+
+
+
$1000 - $17FF2048 bytesMirror of $0000-$07FF
+
+
($1000 - $10FF)256Zero Page
+
$1100 - $11FF256Stack
+
$1200 - $17FF 1024RAM
+
+
+
$1800 - $1FFF 2048 bytes Mirror of $0000-$07FF
+
+
($1800 - $18FF)256Zero Page
+
($1900 - $19FF)256Stack
+
($1A00 - $1FFF) 1024RAM
+
+
+
$2000 - $2007 8 bytes Input / Output registers
+
$2008 - $3FFF 8184 bytes Mirror of $2000-$2007 (mulitple times)
+
+
+
$4000 - $401F 32 bytes Input / Output registers
+
$4020 - $5FFF 8160 bytes Expansion ROM - Used with Nintendo's MMC5 to expand the capabilities of VRAM.
+
+
+
$6000 - $7FFF 8192 bytes SRAM - Save Ram used to save data between game plays.
The NES PPU has enough RAM for two nametables (0 and 3); it brings some PPU nametable address lines to the cart edge so that the cart can decide whether to map 0 onto 2 and 1 onto 3 (vertical mirroring as in Super Mario Brothers and Contra) or 0 onto 1 and 2 onto 3 (horizontal mirroring as in Kid Icarus and Ikari), all screens to either 0 or 3 (as in many Rare games such as Battletoads and Jeopardy!), or all screens to RAM on the cartridge (as in Gauntlet). Split-screen games that scroll in all four directions (such as Super Mario Brothers 3 and Kirby's Adventure) often use vertical or one-screen mirroring (with a small amount of screen corruption at the sides due to tiles wrapping around the sides) and stick the status bar in some random unused area of the screen.
+
+
+
Game RAM Details
+
Mapping RAM/Finding Ram
+
Written by: adelikat
+
+
This guide is written specifically for finding useful values for TAS movie making.
+
It does not tell you how to use specific tools to find values. For that refer to Hex editor, Cheat Search, and RAM filter.
+
+
Most games use the basic on board ram. The address range of this ram is $0000-$07FF. This translates to 2048 possible ram values.
+
+
Pages
+
+
This ram is broken down into 8 pages. A "page" is a block of 256 ram values.
+
+
I will refer to these values as such:
+
Block 0$00xx($0000-$00FF)
+
Block 1$01xx($0100-$01FF)
+
Block 2$02xx($0200-$02FF)
+
Block 3$03xx($0300-$03FF)
+
Block 4$04xx($0400-$04FF)
+
Block 5$05xx($0500-$05FF)
+
Block 6$06xx($0600-$06FF)
+
Block 7$07xx($0700-$07FF)
+
+
Each block will be organized will similar data. For instance, all sprite data will be in the same block. Enemy/Player statistics (energy, coordinates, speed, etc.) will be in another. For instance, if you find the main character's HP and it is located in block 3, you know that the remaining stats for the character are also in that block. This can significantly cut down time when trying to find related values.
+
+
There are always the following blocks:
+
+
Sprite DataBlock 2
+
+
I've yet to see map a game that does not use this block solely for sprite data. It will contain the "ID" numbers for all the items currently on the screen. Simply put, this data is precisely the data you see on the screen. For making TAS movies this is not useful data. If you are using cheat search and have narrowed it down your search to a few values, you can immediately discard any $02xx values.
+
+
In games with a lot of sprite data, I've seen blocks 1 & 3 also reserved for sprite data.
+
+
Music & Sound FXBlock 1 or 7, generally
+
+
This one has more deviation, but almost all games reserve an entire block for memory allocated to the game's Music and Sound FX. Again, for TAS purposes these values are not *useful. By finding even 1 of these values, you can eliminate that block from your search possibilities. Finding which block is reserved for music is often quite simple with the Hex editor. Watching the ram values with the game playing, you can see which addresses "move to the beat".
+
+
*Actually they can come in handy for "dancing to the beat"
+
+
Player & Enemy StatsBlocks 1,3,4,5 generally (any or all of these)
+
+
This is your "sweet spot" for movie making, as often you will be wanting to track the players speed or coordinates, enemy energy, or enemy coordinates.
+
+
These values rarely (if at all) reside outside blocks 1, 3, 4, or 5. This knowledge already reduces your search possibilities in half!
+
+
Rows
+
+
Each block is broken down into 16 "rows" of addresses. For example, in block 3, the first row is $030x ($0300-$030F).
+
+
Each row of 16* will contain similar data. For instance all x coordinates will generally be in the same row. So xxx0 might be the main characters x position. xxxx1 would be "enemy 1" (1st enemy loaded onto the screen), and so on.
+
+
The y coordinates would be in another row, x subpixel values in yet another row, etc.
+
+
*Super Mario Bros. 2 (U) is a rare example that uses rows of 10
+
+
Columns
+
+
A column would be all the values of a block that share the same last digit. So a column would be 16 addresses such as $0300, $0310, $0320, etc.
+
+
For enemy/player stats, columns usually refer to the same player or enemy.
+
+
So for example, if a player's energy was stored in $0300. The remaining row will be other player/enemy's energy.
+
+
If the next row ($031x) is x positions. $0310 would be the player's x position. The remaining positions of that row would correspond to the other player/enemy x positions in line with the hp values of the previous row.
+
+
Example
+
+
These distinctions are easier to see in a visual example. This is the enemy/player stats as they are mapped in the game Teenage Mutant Ninja Turtles.
+
+
Block 4
+
P W1 W2 W3 E1 E2 E3 E4 E5 E6 E7 E8 X X X X
+
Sprite ID: 040x: 09 00 00 00 00 9E 9E 9E 9E 00 00 00 00 00 00 00
E1 = "Enemy slot 1" which will be the first enemy on the screen loaded into memory. The 2nd will be placed in "Enemy slot 2". When enemy 1 is removed from memory (killed or goes off screen), the next enemy will be loaded into that slot. Enemy's always take the lowest available slot when loaded. Note: usually enemy slots are in reverse order. So the first addresses is usually the last enemy slot loaded into memory. TMNT is an exception.
+
+
All object (player, weapon, enemy) characteristics reside in block 4.
+
Each row is a different characteristic of each object on the screen (040x refers to a sprite ID of an object)
+
Each column corresponds to a specific object on the screen. (All 04x0 's refer to the player).
All results were obtained by studying prior information available (from nestech 1.00, and postings on NESDev from miscellanious people), and through a series of experiments conducted by me. Results acquired by individuals prior to my reverse-engineering have been double checked, and final results have been confirmed. Credit is due to those individual(s) who contributed miscellanious information in regards to NES sound channel hardware. Such individuals are:
-
-
Goroh
-
Memblers
-
FluBBa
-
Izumi
-
Chibi-Tech
-
Quietust
-
SnowBro
-
-
Kentaro Ishihara (Ki) is responsible for posting (on the NESdev mailing list) differrences in the 2 square wave channels, including the operation of 2A03 hardware publically undocumented (until now) such as the frame IRQ counter, and it's ties with sound hardware. Goroh had originally discovered some of this information, and Ki confirmed it.
-
-
A special thanks goes out to Matthew Conte, for his expertise on pseudo-random number generation (amoung other things), which allowed for the full reverse engineering of the NES's noise channel to take place. Without his help, I would still be trying to find a needle in a haystack, as far as the noise's method of pseudo-random number generation goes. Additionally, his previous findings / reverse engineering work on the NES's sound hardware really got the ball of NES sound emulation rolling. If it weren't for Matt's original work, this document wouldn't exist.
-
-
-
****************
-
* Introduction *
-
****************
-
The 2A03 (NES's integrated CPU) has 4 internal channels to it that have the ability to generate semi-analog sound, for musical playback purposes. These channels are 2 square wave channels, one triangle wave channel, and a noise generation channel. This document will go into full detail on every aspect of the operation and timing of the mentioned sound channels.
-
-
-
*******************
-
* Channel details *
-
*******************
-
Each channel has different characteristics to it that make up it's operation.
-
-
The square channel(s) have the ability to generate a square wave frequency in the range of 54.6 Hz to 12.4 KHz. It's key features are frequency sweep abilities, and output duty cycle adjustment.
-
-
The triangle wave channel has the ability to generate an output triangle wave with a resolution of 4-bits (16 steps), in the range of 27.3 Hz to 55.9 KHz. The key features this channel has is it's analog triangle wave output, and it's linear counter, which can be set to automatically disable the channel's sound after a certain period of time has gone by.
-
-
The noise channel is used for producing random frequencys, which results in a "noisey" sounding output. Output frequencys can range anywhere from 29.3 Hz to 447 KHz. It's key feature is it's pseudo- random number generator, which generates the random output frequencys heard by the channel.
-
-
-
*****************
-
* Frame counter *
-
*****************
-
The 2A03 has an internal frame counter. The purpose of it is to generate the various low frequency signals (60, 120, 240 Hz, and 48, 96, 192 Hz) required to clock several of the sound hardware's counters. It also has the ability to generate IRQ's.
-
-
The smallest unit of timing the frame counter operates around is 240Hz; all other frequencies are generated by multiples of this base frequency. A clock divider of 14915 (clocked at twice the CPU speed) is used to get 240Hz (this was the actual measured ratio).
-
-
-
+---------------+
-
|$4017 operation|
-
+---------------+
-
Writes to register $4017 control operation of both the clock divider, and the frame counter.
-
-
- Any write to $4017 resets both the frame counter, and the clock divider. Sometimes, games will write to this register in order to synchronize the sound hardware's internal timing, to the sound routine's timing (usually tied into the NMI code). The frame IRQ is slightly longer than the PPU's, so you can see why games would desire this syncronization.
-
-
- bit 7 of $4017 controls the frame counter's divide rate. Every time the counter cycles (reaches terminal count (0)), a frame IRQ will be generated, if enabled by clearing bit 6 of $4017. $4015.6 holds the status of the frame counter IRQ; it will be set if the frame counter is responsible for the interrupt.
-
-
$4017.7 divider frame IRQ freq.
-
------- ------- ---------------
-
0 4 60
-
1 5 48
-
-
On 2A03 reset, both bits of $4017 (6 & 7) will be cleared, enabling frame IRQ's off the hop. The reason why the existence of frame IRQ's are generally unknown is because the 6502's maskable interrupt is disabled on reset, and this blocks out the frame IRQ's. Most games don't use any IRQ-generating hardware in general, therefore they don't bother enabling maskable interrupts.
-
-
Note that the IRQ line will be held down by the frame counter until it is acknowledged (by reading $4015). Before this, the 6502 will generate an IRQ *every* time interrupts are enabled (either by CLI or RTI), since the IRQ design on the 6502 is level-triggered, and not edge. If you've written a program that does not read $4015 in the IRQ handler, and you execute CLI, the processor will immediately go into a infinite IRQ call-return loop.
-
-
-
+-----------------------+
-
|Frame counter operation|
-
+-----------------------+
-
Depending on the status of $4017.7, the frame counter will follow 2 different count sequences. These sequences determine when sound hardware counters will be clocked. The sequences are initialized immediately following any write to $4017.
-
-
$4017.7 sequence
-
------- --------
-
0 4, 0,1,2,3, 0,1,2,3,..., etc.
-
1 0,1,2,3,4, 0,1,2,3,4,..., etc.
-
-
During count sequences 0..3, the linear (triangle) and envelope decay (square & noise) counters recieve a clock for each count. This means that both these counters are clocked once immediately after $4017.7 is written with a value of 1.
-
-
Count sequences 1 & 3 clock (update) the frequency sweep (square), and length (all channels) counters. Even though the length counter's smallest unit of time counting is a frame, it seems that it is actually being clocked twice per frame. That said, you can consider the length counters to contain an extra stage to divide this clock signal by 2.
-
-
No aforementioned sound hardware counters are clocked on count sequence #4. You should now see how this causes the 96, and 192 Hz signals to be generated when $4017.7=1.
-
-
The rest of the document will describe the operation of the sound channels using the $4017.7=0 frequencies (60, 120, and 240 Hz). For $4017.7=1 operation, replace those frequencies with 48, 96, and 192 Hz (respectively).
-
-
-
************************
-
* Sound hardware delay *
-
************************
-
After resetting the 2A03, the first time any sound channel(s) length counter contains a non-zero value (channel is enabled), there will be a 2048 CPU clock cycle delay before any of the sound hardware is clocked. After the 2K clock cycles go by, the NES sound hardware will be clocked normally. This phenomenon only occurs prior to a system reset, and only occurs during the first 2048 CPU clocks after the activation of any of the 4 basic sound channels.
-
-
The information in regards to this delay is only provided to keep this document accurate with all information that is currently known about the 2A03's sound hardware. I haven't done much tests on the behaviour of this delay (mainly because I don't care, as I view it as a inconvenience anyway), so this information should be taken with a grain of salt.
-
-
-
************************
-
* Register Assignments *
-
************************
-
The sound hardware internal to the 2A03 has been designated these special memory addresses in the CPU's memory map.
-
-
$4000-$4003 Square wave 1
-
$4004-$4007 Square wave 2 (identical to the first, except for upward frequency sweeps (see "sweep unit" section))
-
$4008-$400B Triangle
-
$400C-$400F Noise
-
$4015 Channel enable / length/frame counter status
-
$4017 frame counter control
-
-
Note that $4015 (and $4017, but is unrelated to sound hardware) are the only R/W registers. All others are write only (attempt to read them will most likely return the last byte on the bus (usually 040H), due to heavy capacitance on the NES's data bus). Reading a "write only" register, will have no effect on the specific register, or channel.
-
-
Every sound channel has 4 registers affiliated with it. The description of the register sets are as follows:
0-2 3 MS bits of wavelength (unused on noise channel)
-
3-7 length counter load register
-
-
-
+--------------------------------+
-
| length counter status register |
-
+--------------------------------+
-
-
$4015(read)
-
-----------
-
0 square wave channel 1
-
1 square wave channel 2
-
2 triangle wave channel
-
3 noise channel
-
4 DMC (see "DMC.TXT" for details)
-
5-6 unused
-
7 IRQ status of DMC (see "DMC.TXT" for details)
-
-
-
+-------------------------+
-
| channel enable register |
-
+-------------------------+
-
-
$4015(write)
-
------------
-
0 square wave channel 1
-
1 square wave channel 2
-
2 triangle wave channel
-
3 noise channel
-
4 DMC channel (see "DMC.TXT" for details)
-
5-7 unused
-
-
-
************************
-
* Channel architecture *
-
************************
-
This section will describe the internal components making up each individual channel. Each component will then be described in full detail.
-
-
Device Triangle Noise Square
-
------ -------- ------ ------
-
triangle step generatorX
-
linear counterX
-
programmable timerX X X
-
length counterX X X
-
4-bit DACX X X
-
volume/envelope decay unit X X
-
sweep unit X
-
duty cycle generator X
-
wavelength converter X
-
random number generator X
-
-
-
+-------------------------+
-
| Triangle step generator |
-
+-------------------------+
-
This is a 5-bit, single direction counter, and it is only used in the triangle channel. Each of the 4 LSB outputs of the counter lead to one input on a corresponding mutually exclusive XNOR gate. The 4 XNOR gates have been strobed together, which results in the inverted representation of the 4 LSB of the counter appearing on the outputs of the gates when the strobe is 0, and a non-inverting action taking place when the strobe is 1. The strobe is naturally connected to the MSB of the counter, which effectively produces on the output of the XNOR gates a count sequence which reflects the scenario of a near- ideal triangle step generator (D,E,F,F,E,D,...,2,1,0,0,1,2,...). At this point, the outputs of the XNOR gates will be fed into the input of a 4-bit DAC.
-
-
This 5-bit counter will be halted whenever the Triangle channel's length or linear counter contains a count of 0. This results in a "latching" behaviour; the counter will NOT be reset to any definite state.
-
-
On system reset, this counter is loaded with 0.
-
-
The counter's clock input is connected directly to the terminal count output pin of the 11-bit programmable timer in the triangle channel. As a result of the 5-bit triangle step generator, the output triangle wave frequency will be 32 times less than the frequency of the triangle channel's programmable timer is set to generate.
-
-
-
+----------------+
-
| Linear counter |
-
+----------------+
-
The linear counter is only found in the triangle channel. It is a 7-bit presettable down counter, with a decoded output condition of 0 available (not exactly the same as terminal count). Here's the bit assignments:
-
-
$4008 bits
-
----------
-
0-6 bits 0-6 of the linear counter load register (NOT the linear counter itself)
-
7 linear counter start
-
-
The counter is clocked at 240 Hz (1/4 framerate), and the calculated length in frames is 0.25*N, where N is the 7-bit loaded value. The counter is always being clocked, except when 0 appears on the output of the counter. At this point, the linear counter & triangle step counter clocks signals are disabled, which results in both counters latching their current state (the linear counter will stay at 0, and the triangle step counter will stop, and the channel will be silenced due to this).
-
-
The linear counter has 2 modes: load, and count. When the linear counter is in load mode, it essentially becomes transparent (i.e. whatever value is currently in, or being written to $4008, will appear on the output of the counter). Because of this, no count action can occur in load mode. When the mode changes from load to count, the counter will now latch the value currently in it, and start counting down from there. In the count mode, the current value of $4008 is ignored by the counter (but still retained in $4008). Described below is how the mode of the linear counter is set:
-
-
-
Writes to $400B
-
---------------
-
cur mode
-
--- ----
-
1 load
-
0 load (on next linear counter clock), count
-
-
Cur is the current state of the MSB of $4008.
-
-
-
Writes to $4008
-
---------------
-
old new mode
-
--- --- ----
-
0 X count
-
1 0 no change (during the CPU write cycle), count
-
1 1 no change
-
-
Old and new represent the state(s) of the MSB of $4008. Old is the value being replaced in the MSB of $4008 on the write, and new is the value replacing the old one.
-
-
"no change" indicates that the mode of the linear counter will not change from the last.
-
-
Note that writes to $400B when $4008.7=0 only loads the linear counter with the value in $4008 on the next *linear* counter clock (and NOT at the end of the CPU write cycle). This is a correction from older versions of this doc.
-
-
-
+--------------------+
-
| Programmable timer |
-
+--------------------+
-
The programmable timer is a 11-bit presettable down counter, and is found in the square, triangle, and noise channel(s). The bit assignments are as follows:
-
-
$4002(sq1)/$4006(sq2)/$400A(Tri) bits
-
-------------------------------------
-
0-7 represent bits 0-7 of the 11-bit wavelength
-
-
$4003(sq1)/$4007(sq2)/$400B(Tri) bits
-
-------------------------------------
-
0-2 represent bits 8-A of the 11-bit wavelength
-
-
Note that on the noise channel, the 11 bits are not available directly. See the wavelength converter section, for more details.
-
-
The counter has automatic syncronous reloading upon terminal count (count=0), therefore the counter will count for N+1 (N is the 11-bit loaded value) clock cycles before arriving at terminal count, and reloading. This counter will typically be clocked at the 2A03's internal 6502 speed (1.79 MHz), and produces an output frequency of 1.79 MHz/(N+1). The terminal count's output spike length is typically no longer than half a CPU clock. The TC signal will then be fed to the appropriate device for the particular sound channel (for square, this terminal count spike will lead to the duty cycle generator. For the triangle, the spike will be fed to the triangle step generator. For noise, this signal will go to the random number generator unit).
-
-
-
+----------------+
-
| Length counter |
-
+----------------+
-
The length counter is found in all sound channels. It is essentially a 7-bit down counter, and is conditionally clocked at a frequency of 60 Hz.
-
-
When the length counter arrives at a count of 0, the counter will be stopped (stay on 0), and the appropriate channel will be silenced.
-
-
The length counter clock disable bit, found in all the channels, can also be used to halt the count sequence of the length counter for the appropriate channel, by writing a 1 out to it. A 0 condition will permit counting (unless of course, the counter's current count = 0). Location(s) of the length counter clock disable bit:
-
-
$4000(sq1)/$4004(sq2)/$400C(noise) bits
-
---------------------------------------
-
5 length counter clock disable
-
-
$4008(tri) bits
-
---------------
-
7 length counter clock disable
-
-
To load the length counter with a specified count, a write must be made out to the length register. Location(s) of the length register:
The 5-bit length value written, determines what 7-bit value the length counter will start counting from. A conversion table here will show how the values are translated.
-
-
+-----------------------+
-
| bit3=0 |
-
+-------+---------------+
-
| |frames |
-
|bits +-------+-------+
-
|4-6 |bit7=0 |bit7=1 |
-
+-------+-------+-------+
-
|0 |05 |06 |
-
|1 |0A |0C |
-
|2 |14 |18 |
-
|3 |28 |30 |
-
|4 |50 |60 |
-
|5 |1E |24 |
-
|6 |07 |08 |
-
|7 |0D |10 |
-
+-------+-------+-------+
-
-
+---------------+
-
| bit3=1 |
-
+-------+-------+
-
|bits | |
-
|4-7 |frames |
-
+-------+-------+
-
|0 |7F |
-
|1 |01 |
-
|2 |02 |
-
|3 |03 |
-
|4 |04 |
-
|5 |05 |
-
|6 |06 |
-
|7 |07 |
-
|8 |08 |
-
|9 |09 |
-
|A |0A |
-
|B |0B |
-
|C |0C |
-
|D |0D |
-
|E |0E |
-
|F |0F |
-
+-------+-------+
-
-
The length counter's real-time status for each channel can be attained. A 0 is returned for a zero count status in the length counter (channel's sound is disabled), and 1 for a non-zero status. Here's the bit description of the length counter status register:
-
-
$4015(read)
-
-----------
-
0 length counter status of square wave channel 1
-
1 length counter status of square wave channel 2
-
2 length counter status of triangle wave channel
-
3 length counter status of noise channel
-
4 length counter status of DMC (see "DMC.TXT" for details)
-
5 unknown
-
6 frame IRQ status
-
7 IRQ status of DMC (see "DMC.TXT" for details)
-
-
Writing a 0 to the channel enable register will force the length counters to always contain a count equal to 0, which renders that specific channel disabled (as if it doesn't exist). Writing a 1 to the channel enable register disables the forced length counter value of 0, but will not change the count itself (it will still be whatever it was prior to the writing of 1).
-
-
Bit description of the channel enable register:
-
-
$4015(write)
-
------------
-
0 enable square wave channel 1
-
1 enable square wave channel 2
-
2 enable triangle wave channel
-
3 enable noise channel
-
4 enable DMC channel (see "DMC.TXT" for details)
-
5-7 unknown
-
-
Note that all 5 used bits in this register will be set to 0 upon system reset.
-
-
-
+-----------+
-
| 4-bit DAC |
-
+-----------+
-
This is just a standard 4-bit DAC with 16 steps of output voltage resolution, and is used by all 4 sound channels. On the 2A03, square wave 1 & 2 are mixed together, and are available via pin 1. Triangle & noise are available on pin 2.
-
-
These analog outputs require a negative current source, to attain linear symmetry on the various output voltage levels generated by the channel(s) (moreover, to get the sound to be audible). Instead of current sources, the NES uses external 100 ohm pull-down resistors. This results in the output waveforms having some linear asymmetry (i.e., as the desired output voltage increases on a linear scale, the actual outputted voltage increases less and less each step).
-
-
The side effect of this is that the DMC's 7-bit DAC port ($4011) is able to indirectly control the volume (somewhat) of both triangle & noise channels. While I have not measured the voltage asymmetery, others on the NESdev messageboards have posted their findings. The conclusion is that when $4011 is 0, triangle & noise volume outputs are at maximum. When $4011 = 7F, the triangle & noise channel outputs operate at only 57% total volume.
-
-
The odd thing is that a few games actually take advantage of this "volume" feature, and write values to $4011 in order to regulate the amplitude of the triangle wave channel's output.
-
-
-
+------------------------------+
-
| Volume / envelope decay unit |
-
+------------------------------+
-
The volume / envelope decay hardware is found only in the square wave and noise channels.
-
-
$4000(sq1)/$4004(sq2)/$400C(noise)
-
----------------------------------
-
0-3 volume / envelope decay rate
-
4 envelope decay disable
-
5 envelope decay looping enable
-
-
When the envelope decay disable bit (bit 4) is set (1), the current volume value (bits 0-3) is sent directly to the channel's DAC. However, depending on certain conditions, this 4-bit volume value will be ignored, and a value of 0 will be sent to the DAC instead. This means that while the channel is enabled (producing sound), the output of the channel (what you'll hear from the DAC) will either be the 4-bit volume value, or 0. This also means that a 4-bit volume value of 0 will result in no audible sound. These conditions are as follows:
-
-
- When hardware in the channel wants to disable it's sound output (like the length counter, or sweep unit (square channels only)).
-
-
- On the negative portion of the output frequency signal coming from the duty cycle / random number generator hardware (square wave channel / noise channel).
-
-
When the envelope decay disable bit is cleared, bits 0-3 now control the envelope decay rate, and an internal 4-bit down counter (hereon the envelope decay counter) now controls the channel's volume level. "Envelope decay" is used to describe the action of the channel's audio output volume starting from a certain value, and decreasing by 1 at a fixed (linear) rate (which produces a "fade-out" sounding effect). This fixed decrement rate is controlled by the envelope decay rate (bits 0-3). The calculated decrement rate is 240Hz/(N+1), where N is any value between $0-$F.
-
-
When the channel's envelope decay counter reaches a value of 0, depending on the status of the envelope decay looping enable bit (bit 5, which is shared with the length counter's clock disable bit), 2 different things will happen:
-
-
bit 5 action
-
----- ------
-
0 The envelope decay count will stay at 0 (channel silenced).
-
1 The envelope decay count will wrap-around to $F (upon the next clock cycle). The envelope decay counter will then continue to count down normally.
-
-
Only a write out to $4003/$4007/$400F will reset the current envelope decay counter to a known state (to $F, the maximum volume level) for the appropriate channel's envelope decay hardware. Otherwise, the envelope decay counter is always counting down (by 1) at the frequency currently contained in the volume / envelope decay rate bits (even when envelope decays are disabled (setting bit 4)), except when the envelope decay counter contains a value of 0, and envelope decay looping (bit 5) is disabled (0).
-
-
-
+------------+
-
| Sweep unit |
-
+------------+
-
The sweep unit is only found in the square wave channels. The controls for the sweep unit have been mapped in at $4001 for square 1, and $4005 for square 2.
-
-
The controls
-
------------
-
Bit 7 when this bit is set (1), sweeping is active. This results in real-time increasing or decreasing of the the current wavelength value (the audible frequency will decrease or increase, respectively). The wavelength value in $4002/3 ($4006/7) is constantly read & updated by the sweep. Modifying the contents of $4002/3 will be immediately audible, and will result in the sweep now starting from this new wavelength value.
-
-
Bits 6-4 These 3 bits represent the sweep refresh rate, or the frequency at which $4002/3 is updated with the new calculated wavelength. The refresh rate frequency is 120Hz/(N+1), where N is the value written, between 0 and 7.
-
-
Bit 3 This bit controls the sweep mode. When this bit is set (1), sweeps will decrease the current wavelength value, as a 0 will increase the current wavelength.
-
-
Bits 2-0 These bits control the right shift amount of the new calculated sweep update wavelength. Code that shows how the sweep unit calculates a new sweep wavelength is as follows:
-
-
bit 3
-
-----
-
0 New = Wavelength + (Wavelength >> N)
-
1 New = Wavelength - (Wavelength >> N) (minus an additional 1, if using square wave channel 1)
-
-
where N is the the shift right value, between 0-7.
-
-
Note that in decrease mode, for subtracting the 2 values:
-
1's compliment (NOT) is being used for square wave channel 1
-
2's compliment (NEG) is being used for square wave channel 2
-
-
This information is currently the only known difference between the 2 square wave channels.
-
-
On each sweep refresh clock, the Wavelength register will be updated with the New value, but only if all 3 of these conditions are met:
-
-
- bit 7 is set (sweeping enabled)
-
- the shift value (which is N in the formula) does not equal to 0
-
- the channel's length counter contains a non-zero value
-
-
Notes
-
-----
-
There are certain conditions that will cause the sweep unit to silence the channel, and halt the sweep refresh clock (which effectively stops sweep action, if any). Note that these conditions pertain regardless of any sweep refresh rate values, or if sweeping is enabled/disabled (via bit 7).
-
-
- an 11-bit wavelength value less than $008 will cause this condition
-
- if the sweep unit is currently set to increase mode, the New calculated wavelength value will always be tested to see if a carry (bit $B) was generated or not (if sweeping is enabled, this carry will be examined before the Wavelength register is updated) from the shift addition calculation. If carry equals 1, the channel is silenced, and sweep action is halted.
-
-
-
+----------------------+
-
| Duty cycle generator |
-
+----------------------+
-
The duty cycle generator takes the fequency produced from the 11-bit programmable timer, and uses a 4 bit counter to produce 4 types of duty cycles. The output frequency is then 1/16 that of the programmable timer. The duty cycle hardware is only found in the square wave channels. The bit assignments are as follows:
-
-
$4000(sq1)/$4004(sq2)
-
---------------------
-
6-7 Duty cycle type
-
-
duty (positive/negative)
-
val in clock cycles
-
--- ---------------
-
00 2/14
-
01 4/12
-
10 8/ 8
-
11 12/ 4
-
-
Where val represents bits 6-7 of $4000/$4004.
-
-
This counter is reset when the length counter of the same channel is written to (via $4003/$4007).
-
-
The output frequency at this point will now be fed to the volume/envelope decay hardware.
-
-
-
+----------------------+
-
| Wavelength converter |
-
+----------------------+
-
The wavelength converter is only used in the noise channel. It is used to convert a given 4-bit value to an 11-bit wavelength, which then is sent to the noise's own programmable timer. Here is the bit descriptions:
-
-
$400E bits
-
----------
-
0-3 The 4-bit value to be converted
-
-
Below is a conversion chart that shows what 4-bit value will represent the 11-bit wavelength to be fed to the channel's programmable timer:
-
-
value octave scale CPU clock cycles (11-bit wavelength+1)
Octave and scale information is provided for the music enthusiast programmer who is more familiar with notes than clock cycles.
-
-
-
+-------------------------+
-
| Random number generator |
-
+-------------------------+
-
The noise channel has a 1-bit pseudo-random number generator. It's based on a 15-bit shift register, and an exclusive or gate. The generator can produce two types of random number sequences: long, and short. The long sequence generates 32,767-bit long number patterns. The short sequence generates 93-bit long number patterns. The 93-bit mode will generally produce higher sounding playback frequencys on the channel. Here is the bit that controls the mode:
-
-
$400E bits
-
----------
-
7 mode
-
-
If mode=0, then 32,767-bit long number sequences will be produced (32K mode), otherwise 93-bit long number sequences will be produced (93-bit mode).
-
-
The following diagram shows where the XOR taps are taken off the shift register to produce the 1-bit pseudo-random number sequences for each mode.
-
-
mode <-----
-
---- EDCBA9876543210
-
32K **
-
93-bit * *
-
-
The current result of the XOR will be transferred into bit position 0 of the SR, upon the next shift cycle. The 1-bit random number output is taken from pin E, is inverted, then is sent to the volume/envelope decay hardware for the noise channel. The shift register is shifted upon recieving 2 clock pulses from the programmable timer (the shift frequency will be half that of the frequency from the programmable timer (one octave lower)).
-
-
On system reset, this shift register is loaded with a value of 1.
-
-
-
RP2A03E quirk
-
-------------
-
I have been informed that revisions of the 2A03 before "F" actually lacked support for the 93-bit looped noise playback mode. While the Famicom's 2A03 went through 4 revisions (E..H), I think that only one was ever used for the front loading NES: "G". Other differences between 2A03 revisions are unknown.
All results were obtained by studying prior information available (from nestech 1.00, and postings on NESDev from miscellanious people), and through a series of experiments conducted by me. Results acquired by individuals prior to my reverse-engineering have been double checked, and final results have been confirmed. Credit is due to those individual(s) who contributed miscellanious information in regards to NES sound channel hardware. Such individuals are:
+
+
Goroh
+
Memblers
+
FluBBa
+
Izumi
+
Chibi-Tech
+
Quietust
+
SnowBro
+
+
Kentaro Ishihara (Ki) is responsible for posting (on the NESdev mailing list) differrences in the 2 square wave channels, including the operation of 2A03 hardware publically undocumented (until now) such as the frame IRQ counter, and it's ties with sound hardware. Goroh had originally discovered some of this information, and Ki confirmed it.
+
+
A special thanks goes out to Matthew Conte, for his expertise on pseudo-random number generation (amoung other things), which allowed for the full reverse engineering of the NES's noise channel to take place. Without his help, I would still be trying to find a needle in a haystack, as far as the noise's method of pseudo-random number generation goes. Additionally, his previous findings / reverse engineering work on the NES's sound hardware really got the ball of NES sound emulation rolling. If it weren't for Matt's original work, this document wouldn't exist.
+
+
+
****************
+
* Introduction *
+
****************
+
The 2A03 (NES's integrated CPU) has 4 internal channels to it that have the ability to generate semi-analog sound, for musical playback purposes. These channels are 2 square wave channels, one triangle wave channel, and a noise generation channel. This document will go into full detail on every aspect of the operation and timing of the mentioned sound channels.
+
+
+
*******************
+
* Channel details *
+
*******************
+
Each channel has different characteristics to it that make up it's operation.
+
+
The square channel(s) have the ability to generate a square wave frequency in the range of 54.6 Hz to 12.4 KHz. It's key features are frequency sweep abilities, and output duty cycle adjustment.
+
+
The triangle wave channel has the ability to generate an output triangle wave with a resolution of 4-bits (16 steps), in the range of 27.3 Hz to 55.9 KHz. The key features this channel has is it's analog triangle wave output, and it's linear counter, which can be set to automatically disable the channel's sound after a certain period of time has gone by.
+
+
The noise channel is used for producing random frequencys, which results in a "noisey" sounding output. Output frequencys can range anywhere from 29.3 Hz to 447 KHz. It's key feature is it's pseudo- random number generator, which generates the random output frequencys heard by the channel.
+
+
+
*****************
+
* Frame counter *
+
*****************
+
The 2A03 has an internal frame counter. The purpose of it is to generate the various low frequency signals (60, 120, 240 Hz, and 48, 96, 192 Hz) required to clock several of the sound hardware's counters. It also has the ability to generate IRQ's.
+
+
The smallest unit of timing the frame counter operates around is 240Hz; all other frequencies are generated by multiples of this base frequency. A clock divider of 14915 (clocked at twice the CPU speed) is used to get 240Hz (this was the actual measured ratio).
+
+
+
+---------------+
+
|$4017 operation|
+
+---------------+
+
Writes to register $4017 control operation of both the clock divider, and the frame counter.
+
+
- Any write to $4017 resets both the frame counter, and the clock divider. Sometimes, games will write to this register in order to synchronize the sound hardware's internal timing, to the sound routine's timing (usually tied into the NMI code). The frame IRQ is slightly longer than the PPU's, so you can see why games would desire this syncronization.
+
+
- bit 7 of $4017 controls the frame counter's divide rate. Every time the counter cycles (reaches terminal count (0)), a frame IRQ will be generated, if enabled by clearing bit 6 of $4017. $4015.6 holds the status of the frame counter IRQ; it will be set if the frame counter is responsible for the interrupt.
+
+
$4017.7 divider frame IRQ freq.
+
------- ------- ---------------
+
0 4 60
+
1 5 48
+
+
On 2A03 reset, both bits of $4017 (6 & 7) will be cleared, enabling frame IRQ's off the hop. The reason why the existence of frame IRQ's are generally unknown is because the 6502's maskable interrupt is disabled on reset, and this blocks out the frame IRQ's. Most games don't use any IRQ-generating hardware in general, therefore they don't bother enabling maskable interrupts.
+
+
Note that the IRQ line will be held down by the frame counter until it is acknowledged (by reading $4015). Before this, the 6502 will generate an IRQ *every* time interrupts are enabled (either by CLI or RTI), since the IRQ design on the 6502 is level-triggered, and not edge. If you've written a program that does not read $4015 in the IRQ handler, and you execute CLI, the processor will immediately go into a infinite IRQ call-return loop.
+
+
+
+-----------------------+
+
|Frame counter operation|
+
+-----------------------+
+
Depending on the status of $4017.7, the frame counter will follow 2 different count sequences. These sequences determine when sound hardware counters will be clocked. The sequences are initialized immediately following any write to $4017.
+
+
$4017.7 sequence
+
------- --------
+
0 4, 0,1,2,3, 0,1,2,3,..., etc.
+
1 0,1,2,3,4, 0,1,2,3,4,..., etc.
+
+
During count sequences 0..3, the linear (triangle) and envelope decay (square & noise) counters recieve a clock for each count. This means that both these counters are clocked once immediately after $4017.7 is written with a value of 1.
+
+
Count sequences 1 & 3 clock (update) the frequency sweep (square), and length (all channels) counters. Even though the length counter's smallest unit of time counting is a frame, it seems that it is actually being clocked twice per frame. That said, you can consider the length counters to contain an extra stage to divide this clock signal by 2.
+
+
No aforementioned sound hardware counters are clocked on count sequence #4. You should now see how this causes the 96, and 192 Hz signals to be generated when $4017.7=1.
+
+
The rest of the document will describe the operation of the sound channels using the $4017.7=0 frequencies (60, 120, and 240 Hz). For $4017.7=1 operation, replace those frequencies with 48, 96, and 192 Hz (respectively).
+
+
+
************************
+
* Sound hardware delay *
+
************************
+
After resetting the 2A03, the first time any sound channel(s) length counter contains a non-zero value (channel is enabled), there will be a 2048 CPU clock cycle delay before any of the sound hardware is clocked. After the 2K clock cycles go by, the NES sound hardware will be clocked normally. This phenomenon only occurs prior to a system reset, and only occurs during the first 2048 CPU clocks after the activation of any of the 4 basic sound channels.
+
+
The information in regards to this delay is only provided to keep this document accurate with all information that is currently known about the 2A03's sound hardware. I haven't done much tests on the behaviour of this delay (mainly because I don't care, as I view it as a inconvenience anyway), so this information should be taken with a grain of salt.
+
+
+
************************
+
* Register Assignments *
+
************************
+
The sound hardware internal to the 2A03 has been designated these special memory addresses in the CPU's memory map.
+
+
$4000-$4003Square wave 1
+
$4004-$4007Square wave 2 (identical to the first, except for upward frequency sweeps (see "sweep unit" section))
+
$4008-$400BTriangle
+
$400C-$400FNoise
+
$4015Channel enable / length/frame counter status
+
$4017frame counter control
+
+
Note that $4015 (and $4017, but is unrelated to sound hardware) are the only R/W registers. All others are write only (attempt to read them will most likely return the last byte on the bus (usually 040H), due to heavy capacitance on the NES's data bus). Reading a "write only" register, will have no effect on the specific register, or channel.
+
+
Every sound channel has 4 registers affiliated with it. The description of the register sets are as follows:
0-23 MS bits of wavelength (unused on noise channel)
+
3-7length counter load register
+
+
+
+--------------------------------+
+
| length counter status register |
+
+--------------------------------+
+
+
$4015(read)
+
-----------
+
0square wave channel 1
+
1square wave channel 2
+
2triangle wave channel
+
3noise channel
+
4DMC (see "DMC.TXT" for details)
+
5-6unused
+
7IRQ status of DMC (see "DMC.TXT" for details)
+
+
+
+-------------------------+
+
| channel enable register |
+
+-------------------------+
+
+
$4015(write)
+
------------
+
0square wave channel 1
+
1square wave channel 2
+
2triangle wave channel
+
3noise channel
+
4DMC channel (see "DMC.TXT" for details)
+
5-7unused
+
+
+
************************
+
* Channel architecture *
+
************************
+
This section will describe the internal components making up each individual channel. Each component will then be described in full detail.
+
+
Device Triangle Noise Square
+
------ -------- ------ ------
+
triangle step generatorX
+
linear counterX
+
programmable timerX X X
+
length counterX X X
+
4-bit DACX X X
+
volume/envelope decay unit X X
+
sweep unit X
+
duty cycle generator X
+
wavelength converter X
+
random number generator X
+
+
+
+-------------------------+
+
| Triangle step generator |
+
+-------------------------+
+
This is a 5-bit, single direction counter, and it is only used in the triangle channel. Each of the 4 LSB outputs of the counter lead to one input on a corresponding mutually exclusive XNOR gate. The 4 XNOR gates have been strobed together, which results in the inverted representation of the 4 LSB of the counter appearing on the outputs of the gates when the strobe is 0, and a non-inverting action taking place when the strobe is 1. The strobe is naturally connected to the MSB of the counter, which effectively produces on the output of the XNOR gates a count sequence which reflects the scenario of a near- ideal triangle step generator (D,E,F,F,E,D,...,2,1,0,0,1,2,...). At this point, the outputs of the XNOR gates will be fed into the input of a 4-bit DAC.
+
+
This 5-bit counter will be halted whenever the Triangle channel's length or linear counter contains a count of 0. This results in a "latching" behaviour; the counter will NOT be reset to any definite state.
+
+
On system reset, this counter is loaded with 0.
+
+
The counter's clock input is connected directly to the terminal count output pin of the 11-bit programmable timer in the triangle channel. As a result of the 5-bit triangle step generator, the output triangle wave frequency will be 32 times less than the frequency of the triangle channel's programmable timer is set to generate.
+
+
+
+----------------+
+
| Linear counter |
+
+----------------+
+
The linear counter is only found in the triangle channel. It is a 7-bit presettable down counter, with a decoded output condition of 0 available (not exactly the same as terminal count). Here's the bit assignments:
+
+
$4008 bits
+
----------
+
0-6bits 0-6 of the linear counter load register (NOT the linear counter itself)
+
7linear counter start
+
+
The counter is clocked at 240 Hz (1/4 framerate), and the calculated length in frames is 0.25*N, where N is the 7-bit loaded value. The counter is always being clocked, except when 0 appears on the output of the counter. At this point, the linear counter & triangle step counter clocks signals are disabled, which results in both counters latching their current state (the linear counter will stay at 0, and the triangle step counter will stop, and the channel will be silenced due to this).
+
+
The linear counter has 2 modes: load, and count. When the linear counter is in load mode, it essentially becomes transparent (i.e. whatever value is currently in, or being written to $4008, will appear on the output of the counter). Because of this, no count action can occur in load mode. When the mode changes from load to count, the counter will now latch the value currently in it, and start counting down from there. In the count mode, the current value of $4008 is ignored by the counter (but still retained in $4008). Described below is how the mode of the linear counter is set:
+
+
+
Writes to $400B
+
---------------
+
curmode
+
-------
+
1load
+
0load (on next linear counter clock), count
+
+
Cur is the current state of the MSB of $4008.
+
+
+
Writes to $4008
+
---------------
+
oldnewmode
+
----------
+
0Xcount
+
10no change (during the CPU write cycle), count
+
11no change
+
+
Old and new represent the state(s) of the MSB of $4008. Old is the value being replaced in the MSB of $4008 on the write, and new is the value replacing the old one.
+
+
"no change" indicates that the mode of the linear counter will not change from the last.
+
+
Note that writes to $400B when $4008.7=0 only loads the linear counter with the value in $4008 on the next *linear* counter clock (and NOT at the end of the CPU write cycle). This is a correction from older versions of this doc.
+
+
+
+--------------------+
+
| Programmable timer |
+
+--------------------+
+
The programmable timer is a 11-bit presettable down counter, and is found in the square, triangle, and noise channel(s). The bit assignments are as follows:
+
+
$4002(sq1)/$4006(sq2)/$400A(Tri) bits
+
-------------------------------------
+
0-7represent bits 0-7 of the 11-bit wavelength
+
+
$4003(sq1)/$4007(sq2)/$400B(Tri) bits
+
-------------------------------------
+
0-2represent bits 8-A of the 11-bit wavelength
+
+
Note that on the noise channel, the 11 bits are not available directly. See the wavelength converter section, for more details.
+
+
The counter has automatic syncronous reloading upon terminal count (count=0), therefore the counter will count for N+1 (N is the 11-bit loaded value) clock cycles before arriving at terminal count, and reloading. This counter will typically be clocked at the 2A03's internal 6502 speed (1.79 MHz), and produces an output frequency of 1.79 MHz/(N+1). The terminal count's output spike length is typically no longer than half a CPU clock. The TC signal will then be fed to the appropriate device for the particular sound channel (for square, this terminal count spike will lead to the duty cycle generator. For the triangle, the spike will be fed to the triangle step generator. For noise, this signal will go to the random number generator unit).
+
+
+
+----------------+
+
| Length counter |
+
+----------------+
+
The length counter is found in all sound channels. It is essentially a 7-bit down counter, and is conditionally clocked at a frequency of 60 Hz.
+
+
When the length counter arrives at a count of 0, the counter will be stopped (stay on 0), and the appropriate channel will be silenced.
+
+
The length counter clock disable bit, found in all the channels, can also be used to halt the count sequence of the length counter for the appropriate channel, by writing a 1 out to it. A 0 condition will permit counting (unless of course, the counter's current count = 0). Location(s) of the length counter clock disable bit:
+
+
$4000(sq1)/$4004(sq2)/$400C(noise) bits
+
---------------------------------------
+
5length counter clock disable
+
+
$4008(tri) bits
+
---------------
+
7length counter clock disable
+
+
To load the length counter with a specified count, a write must be made out to the length register. Location(s) of the length register:
The 5-bit length value written, determines what 7-bit value the length counter will start counting from. A conversion table here will show how the values are translated.
+
+
+-----------------------+
+
|bit3=0|
+
+-------+---------------+
+
||frames|
+
|bits+-------+-------+
+
|4-6|bit7=0|bit7=1|
+
+-------+-------+-------+
+
|0|05|06|
+
|1|0A|0C|
+
|2|14|18|
+
|3|28|30|
+
|4|50|60|
+
|5|1E|24|
+
|6|07|08|
+
|7|0D|10|
+
+-------+-------+-------+
+
+
+---------------+
+
|bit3=1|
+
+-------+-------+
+
|bits||
+
|4-7|frames|
+
+-------+-------+
+
|0|7F|
+
|1|01|
+
|2|02|
+
|3|03|
+
|4|04|
+
|5|05|
+
|6|06|
+
|7|07|
+
|8|08|
+
|9|09|
+
|A|0A|
+
|B|0B|
+
|C|0C|
+
|D|0D|
+
|E|0E|
+
|F|0F|
+
+-------+-------+
+
+
The length counter's real-time status for each channel can be attained. A 0 is returned for a zero count status in the length counter (channel's sound is disabled), and 1 for a non-zero status. Here's the bit description of the length counter status register:
+
+
$4015(read)
+
-----------
+
0length counter status of square wave channel 1
+
1length counter status of square wave channel 2
+
2length counter status of triangle wave channel
+
3length counter status of noise channel
+
4length counter status of DMC (see "DMC.TXT" for details)
+
5unknown
+
6frame IRQ status
+
7IRQ status of DMC (see "DMC.TXT" for details)
+
+
Writing a 0 to the channel enable register will force the length counters to always contain a count equal to 0, which renders that specific channel disabled (as if it doesn't exist). Writing a 1 to the channel enable register disables the forced length counter value of 0, but will not change the count itself (it will still be whatever it was prior to the writing of 1).
+
+
Bit description of the channel enable register:
+
+
$4015(write)
+
------------
+
0enable square wave channel 1
+
1enable square wave channel 2
+
2enable triangle wave channel
+
3enable noise channel
+
4enable DMC channel (see "DMC.TXT" for details)
+
5-7unknown
+
+
Note that all 5 used bits in this register will be set to 0 upon system reset.
+
+
+
+-----------+
+
| 4-bit DAC |
+
+-----------+
+
This is just a standard 4-bit DAC with 16 steps of output voltage resolution, and is used by all 4 sound channels. On the 2A03, square wave 1 & 2 are mixed together, and are available via pin 1. Triangle & noise are available on pin 2.
+
+
These analog outputs require a negative current source, to attain linear symmetry on the various output voltage levels generated by the channel(s) (moreover, to get the sound to be audible). Instead of current sources, the NES uses external 100 ohm pull-down resistors. This results in the output waveforms having some linear asymmetry (i.e., as the desired output voltage increases on a linear scale, the actual outputted voltage increases less and less each step).
+
+
The side effect of this is that the DMC's 7-bit DAC port ($4011) is able to indirectly control the volume (somewhat) of both triangle & noise channels. While I have not measured the voltage asymmetery, others on the NESdev messageboards have posted their findings. The conclusion is that when $4011 is 0, triangle & noise volume outputs are at maximum. When $4011 = 7F, the triangle & noise channel outputs operate at only 57% total volume.
+
+
The odd thing is that a few games actually take advantage of this "volume" feature, and write values to $4011 in order to regulate the amplitude of the triangle wave channel's output.
+
+
+
+------------------------------+
+
| Volume / envelope decay unit |
+
+------------------------------+
+
The volume / envelope decay hardware is found only in the square wave and noise channels.
+
+
$4000(sq1)/$4004(sq2)/$400C(noise)
+
----------------------------------
+
0-3volume / envelope decay rate
+
4envelope decay disable
+
5envelope decay looping enable
+
+
When the envelope decay disable bit (bit 4) is set (1), the current volume value (bits 0-3) is sent directly to the channel's DAC. However, depending on certain conditions, this 4-bit volume value will be ignored, and a value of 0 will be sent to the DAC instead. This means that while the channel is enabled (producing sound), the output of the channel (what you'll hear from the DAC) will either be the 4-bit volume value, or 0. This also means that a 4-bit volume value of 0 will result in no audible sound. These conditions are as follows:
+
+
- When hardware in the channel wants to disable it's sound output (like the length counter, or sweep unit (square channels only)).
+
+
- On the negative portion of the output frequency signal coming from the duty cycle / random number generator hardware (square wave channel / noise channel).
+
+
When the envelope decay disable bit is cleared, bits 0-3 now control the envelope decay rate, and an internal 4-bit down counter (hereon the envelope decay counter) now controls the channel's volume level. "Envelope decay" is used to describe the action of the channel's audio output volume starting from a certain value, and decreasing by 1 at a fixed (linear) rate (which produces a "fade-out" sounding effect). This fixed decrement rate is controlled by the envelope decay rate (bits 0-3). The calculated decrement rate is 240Hz/(N+1), where N is any value between $0-$F.
+
+
When the channel's envelope decay counter reaches a value of 0, depending on the status of the envelope decay looping enable bit (bit 5, which is shared with the length counter's clock disable bit), 2 different things will happen:
+
+
bit 5action
+
-----------
+
0The envelope decay count will stay at 0 (channel silenced).
+
1The envelope decay count will wrap-around to $F (upon the next clock cycle). The envelope decay counter will then continue to count down normally.
+
+
Only a write out to $4003/$4007/$400F will reset the current envelope decay counter to a known state (to $F, the maximum volume level) for the appropriate channel's envelope decay hardware. Otherwise, the envelope decay counter is always counting down (by 1) at the frequency currently contained in the volume / envelope decay rate bits (even when envelope decays are disabled (setting bit 4)), except when the envelope decay counter contains a value of 0, and envelope decay looping (bit 5) is disabled (0).
+
+
+
+------------+
+
| Sweep unit |
+
+------------+
+
The sweep unit is only found in the square wave channels. The controls for the sweep unit have been mapped in at $4001 for square 1, and $4005 for square 2.
+
+
The controls
+
------------
+
Bit 7 when this bit is set (1), sweeping is active. This results in real-time increasing or decreasing of the the current wavelength value (the audible frequency will decrease or increase, respectively). The wavelength value in $4002/3 ($4006/7) is constantly read & updated by the sweep. Modifying the contents of $4002/3 will be immediately audible, and will result in the sweep now starting from this new wavelength value.
+
+
Bits 6-4These 3 bits represent the sweep refresh rate, or the frequency at which $4002/3 is updated with the new calculated wavelength. The refresh rate frequency is 120Hz/(N+1), where N is the value written, between 0 and 7.
+
+
Bit 3 This bit controls the sweep mode. When this bit is set (1), sweeps will decrease the current wavelength value, as a 0 will increase the current wavelength.
+
+
Bits 2-0These bits control the right shift amount of the new calculated sweep update wavelength. Code that shows how the sweep unit calculates a new sweep wavelength is as follows:
+
+
bit 3
+
-----
+
0New = Wavelength + (Wavelength >> N)
+
1New = Wavelength - (Wavelength >> N) (minus an additional 1, if using square wave channel 1)
+
+
where N is the the shift right value, between 0-7.
+
+
Note that in decrease mode, for subtracting the 2 values:
+
1's compliment (NOT) is being used for square wave channel 1
+
2's compliment (NEG) is being used for square wave channel 2
+
+
This information is currently the only known difference between the 2 square wave channels.
+
+
On each sweep refresh clock, the Wavelength register will be updated with the New value, but only if all 3 of these conditions are met:
+
+
- bit 7 is set (sweeping enabled)
+
- the shift value (which is N in the formula) does not equal to 0
+
- the channel's length counter contains a non-zero value
+
+
Notes
+
-----
+
There are certain conditions that will cause the sweep unit to silence the channel, and halt the sweep refresh clock (which effectively stops sweep action, if any). Note that these conditions pertain regardless of any sweep refresh rate values, or if sweeping is enabled/disabled (via bit 7).
+
+
- an 11-bit wavelength value less than $008 will cause this condition
+
- if the sweep unit is currently set to increase mode, the New calculated wavelength value will always be tested to see if a carry (bit $B) was generated or not (if sweeping is enabled, this carry will be examined before the Wavelength register is updated) from the shift addition calculation. If carry equals 1, the channel is silenced, and sweep action is halted.
+
+
+
+----------------------+
+
| Duty cycle generator |
+
+----------------------+
+
The duty cycle generator takes the fequency produced from the 11-bit programmable timer, and uses a 4 bit counter to produce 4 types of duty cycles. The output frequency is then 1/16 that of the programmable timer. The duty cycle hardware is only found in the square wave channels. The bit assignments are as follows:
+
+
$4000(sq1)/$4004(sq2)
+
---------------------
+
6-7Duty cycle type
+
+
duty (positive/negative)
+
valin clock cycles
+
------------------
+
00 2/14
+
01 4/12
+
10 8/ 8
+
1112/ 4
+
+
Where val represents bits 6-7 of $4000/$4004.
+
+
This counter is reset when the length counter of the same channel is written to (via $4003/$4007).
+
+
The output frequency at this point will now be fed to the volume/envelope decay hardware.
+
+
+
+----------------------+
+
| Wavelength converter |
+
+----------------------+
+
The wavelength converter is only used in the noise channel. It is used to convert a given 4-bit value to an 11-bit wavelength, which then is sent to the noise's own programmable timer. Here is the bit descriptions:
+
+
$400E bits
+
----------
+
0-3The 4-bit value to be converted
+
+
Below is a conversion chart that shows what 4-bit value will represent the 11-bit wavelength to be fed to the channel's programmable timer:
Octave and scale information is provided for the music enthusiast programmer who is more familiar with notes than clock cycles.
+
+
+
+-------------------------+
+
| Random number generator |
+
+-------------------------+
+
The noise channel has a 1-bit pseudo-random number generator. It's based on a 15-bit shift register, and an exclusive or gate. The generator can produce two types of random number sequences: long, and short. The long sequence generates 32,767-bit long number patterns. The short sequence generates 93-bit long number patterns. The 93-bit mode will generally produce higher sounding playback frequencys on the channel. Here is the bit that controls the mode:
+
+
$400E bits
+
----------
+
7mode
+
+
If mode=0, then 32,767-bit long number sequences will be produced (32K mode), otherwise 93-bit long number sequences will be produced (93-bit mode).
+
+
The following diagram shows where the XOR taps are taken off the shift register to produce the 1-bit pseudo-random number sequences for each mode.
+
+
mode <-----
+
----EDCBA9876543210
+
32K**
+
93-bit* *
+
+
The current result of the XOR will be transferred into bit position 0 of the SR, upon the next shift cycle. The 1-bit random number output is taken from pin E, is inverted, then is sent to the volume/envelope decay hardware for the noise channel. The shift register is shifted upon recieving 2 clock pulses from the programmable timer (the shift frequency will be half that of the frequency from the programmable timer (one octave lower)).
+
+
On system reset, this shift register is loaded with a value of 1.
+
+
+
RP2A03E quirk
+
-------------
+
I have been informed that revisions of the 2A03 before "F" actually lacked support for the 93-bit looped noise playback mode. While the Famicom's 2A03 went through 4 revisions (E..H), I think that only one was ever used for the front loading NES: "G". Other differences between 2A03 revisions are unknown.
FCEUX implements Symbolic Debugger which uses "NameList" files to store the data about labels and comments. The needed files are created automatically when user right-clicks an address in Disassembly and enters a symbolic name or a comment for it. The files are stored in the same folder as the debugged ROM, and they inherit the name of the ROM.
-
These files are simple ASCII text files. You can edit them in any text editor like Notepad.
-
-
When reverse-engineering a game for which you don't have a source, you can reconstruct the logic incrementally, by adding labels/comments while debugging (right-clicking addresses).
-
-
But if you want to debug your own homebrew game, you can setup your workflow to automatically export all names and comments when building the game using your favourite assembler (e.g. ca65 or ASM6). This way you can use FCEUX as a Source-Level Debugger.
-
-
Example: for the ROM called "NES Test Cart (PD).nes" the NL files will be named "NES Test Cart (PD).nes.0.nl", "NES Test Cart (PD).nes.ram.nl", etc.
-
-
Example of contents of a NL file:
-
-
$C000#NewName1#Comment1
-
$C002##Comment2
-
$C004#NewName2#
-
$C006#NewName3#MultilineComment-Part1
-
\MultilineComment-Part2
-
\MultilineComment-Part3
-
$C008/10#NewName4#
-
-
Every line contains two # characters which separate the three parts of one line:
-
* The first part (starting with a $ character) is the address to be renamed. Optionally you can add a "/number" part which marks the offsets as a beginning of an array of the given size (the size must be specified in hex form).
-
* The second (optional) part is the new name of that address. Whenever the line of that address is shown in the disassembly window, an extra line saying "NewName1: " is shown above it. Instructions referencing this address, for example JSR $C000 are also changed to JSR NewName1 (in that example).
-
* The third (optional) part is the comment that's also added above the disassembly line the comment refers to. It works exactly like the additional name line, only the prefix of that line is different. Comment lines start with "; ". Multi-lines comments are possible. Lines in an NL file starting with the \ character are just appended to the comment of the preceding line. Multi-line comments are also shown in multiple lines in the disassembly window.
-
-
In the example above, the first line contains all three parts. Using this NL file, all references to the address $C000 are replaced with NewName1, and whenever line $C000 is shown in the disassembly window (or Trace Logger window) an additional comment is also visible right above the actual disassembled line. The second example line defines only a comment while the third line defines only a name. Following that, there's a multi-line comment definition for address $C006. The last line defines an array called NewName4 of size 0x10 (= 16) bytes starting at offset $C008. FCEUX will regard the line like there are 16 lines describing 16 adjacent addresses with names like NewName4[0], NewName4[1], ... NewName4[F].
-
-
NL files must follow a specific naming convention to account for bank swapping. Each bank needs its own NL file with a hexadecimal number of the bank.
-
For instance, an NES file named "mygame.nes" that has 4 banks (i.e. ROM size = 64k) would have these NL files:
-
-
mygame.nes.ram.nl
-
mygame.nes.0.nl
-
mygame.nes.1.nl
-
mygame.nes.2.nl
-
mygame.nes.3.nl
-
-
All NL files must be in the same directory as the ROM file itself.
-
-
RAM can also be given its own NL file. In the *.ram.nl file you can name and comment RAM addresses (system bus range of 0x0000 - 0x7FFF) instead of ROM addresses. In this case, you might use a line such as:
FCEUX implements Symbolic Debugger which uses "NameList" files to store the data about labels and comments. The needed files are created automatically when user right-clicks an address in Disassembly and enters a symbolic name or a comment for it. The files are stored in the same folder as the debugged ROM, and they inherit the name of the ROM.
+
These files are simple ASCII text files. You can edit them in any text editor like Notepad.
+
+
When reverse-engineering a game for which you don't have a source, you can reconstruct the logic incrementally, by adding labels/comments while debugging (right-clicking addresses).
+
+
But if you want to debug your own homebrew game, you can setup your workflow to automatically export all names and comments when building the game using your favourite assembler (e.g. ca65 or ASM6). This way you can use FCEUX as a Source-Level Debugger.
+
+
Example: for the ROM called "NES Test Cart (PD).nes" the NL files will be named "NES Test Cart (PD).nes.0.nl", "NES Test Cart (PD).nes.ram.nl", etc.
+
+
Example of contents of a NL file:
+
+
$C000#NewName1#Comment1
+
$C002##Comment2
+
$C004#NewName2#
+
$C006#NewName3#MultilineComment-Part1
+
\MultilineComment-Part2
+
\MultilineComment-Part3
+
$C008/10#NewName4#
+
+
Every line contains two # characters which separate the three parts of one line:
+
* The first part (starting with a $ character) is the address to be renamed. Optionally you can add a "/number" part which marks the offsets as a beginning of an array of the given size (the size must be specified in hex form).
+
* The second (optional) part is the new name of that address. Whenever the line of that address is shown in the disassembly window, an extra line saying "NewName1: " is shown above it. Instructions referencing this address, for example JSR $C000 are also changed to JSR NewName1 (in that example).
+
* The third (optional) part is the comment that's also added above the disassembly line the comment refers to. It works exactly like the additional name line, only the prefix of that line is different. Comment lines start with "; ". Multi-lines comments are possible. Lines in an NL file starting with the \ character are just appended to the comment of the preceding line. Multi-line comments are also shown in multiple lines in the disassembly window.
+
+
In the example above, the first line contains all three parts. Using this NL file, all references to the address $C000 are replaced with NewName1, and whenever line $C000 is shown in the disassembly window (or Trace Logger window) an additional comment is also visible right above the actual disassembled line. The second example line defines only a comment while the third line defines only a name. Following that, there's a multi-line comment definition for address $C006. The last line defines an array called NewName4 of size 0x10 (= 16) bytes starting at offset $C008. FCEUX will regard the line like there are 16 lines describing 16 adjacent addresses with names like NewName4[0], NewName4[1], ... NewName4[F].
+
+
NL files must follow a specific naming convention to account for bank swapping. Each bank needs its own NL file with a hexadecimal number of the bank.
+
For instance, an NES file named "mygame.nes" that has 4 banks (i.e. ROM size = 64k) would have these NL files:
+
+
mygame.nes.ram.nl
+
mygame.nes.0.nl
+
mygame.nes.1.nl
+
mygame.nes.2.nl
+
mygame.nes.3.nl
+
+
All NL files must be in the same directory as the ROM file itself.
+
+
RAM can also be given its own NL file. In the *.ram.nl file you can name and comment RAM addresses (system bus range of 0x0000 - 0x7FFF) instead of ROM addresses. In this case, you might use a line such as:
This displays the name tables as they exist in PPU memory. Furthermore, it shows you the game's current mirroring, and the current state of the PPU's scroll registers (if the option for this is set). It also lets you change the mirroring on the fly (which will break most games).
-
-
-
Using the Name Table Viewer
-
-
Note that the Name Table Viewer will display the name tables using whatever CHR is present at the time the "Display on Scanline" scanline is reached. So for example if it does not correctly display a game's status bar, try setting it to update on a scanline in which the status bar is displayed.
-
-
The same applies to the Scroll Lines: they display the state of the PPU scroll registers when the "Display on Scanline" scanline is reached. So for example if said scanline is within the game's status bar, it will not display level scrolling because the horizontal scroll is always zero at the time that scanline is drawn. To display the level scrolling, set it to update on a scanline in which the level is displayed.
-
-
Display on scanline
-
This will show what it looks like when the NES has finished drawing that many scanlines to screen including any PPU data scroll line movement
-
-
Getting Tile Addresses
-
Placing the mouse cursor over the name table image will display the tile address of a given tile.
This displays the name tables as they exist in PPU memory. Furthermore, it shows you the game's current mirroring, and the current state of the PPU's scroll registers (if the option for this is set). It also lets you change the mirroring on the fly (which will break most games).
+
+
+
Using the Name Table Viewer
+
+
Note that the Name Table Viewer will display the name tables using whatever CHR is present at the time the "Display on Scanline" scanline is reached. So for example if it does not correctly display a game's status bar, try setting it to update on a scanline in which the status bar is displayed.
+
+
The same applies to the Scroll Lines: they display the state of the PPU scroll registers when the "Display on Scanline" scanline is reached. So for example if said scanline is within the game's status bar, it will not display level scrolling because the horizontal scroll is always zero at the time that scanline is drawn. To display the level scrolling, set it to update on a scanline in which the level is displayed.
+
+
Display on scanline
+
This will show what it looks like when the NES has finished drawing that many scanlines to screen including any PPU data scroll line movement
+
+
Getting Tile Addresses
+
Placing the mouse cursor over the name table image will display the tile address of a given tile.
FCEUX is a cross platform, NTSC and PAL Famicom/NES and Dendy emulator that is an evolution of the original FCE Ultra emulator. Over time FCE Ultra had separated into many separate branches.
-
-
The concept behind FCEUX is to merge elements from FCEU Ultra, FCEU rerecording, FCEUXD, FCEUXDSP, FCEUXDSP CE, and FCEU-mm into a single branch of FCEU. As the X implies, it is an all-encompassing version of the FCEU emulator that provides the best of all worlds for the general player, the ROM-hacking community, and the Tool-Assisted Speedrun Community.
FCEUX is a cross platform, NTSC and PAL Famicom/NES and Dendy emulator that is an evolution of the original FCE Ultra emulator. Over time FCE Ultra had separated into many separate branches.
+
+
The concept behind FCEUX is to merge elements from FCEU Ultra, FCEU rerecording, FCEUXD, FCEUXDSP, FCEUXDSP CE, and FCEU-mm into a single branch of FCEU. As the X implies, it is an all-encompassing version of the FCEU emulator that provides the best of all worlds for the general player, the ROM-hacking community, and the Tool-Assisted Speedrun Community.
Many users of FCEUX do not investigate the luaScripts folder, or, for that matter, ignore lua scripting altogether. The purpose of this text is to let users know that knowing how to create lua scripts is not a requirement in using them. Indeed, there are several scripts that, if you just load them, will explain themselves enough that you don't need to know how to program at all in order to use them. Besides, they shouldn't need to be re-programmed anyway if you are to use them, for if they needed programming experience just to be used, their existence is largely defeated by that very fact!
-
-
FCEUX itself is a program that you load. Our amazing programmers did all the work already so you don't need to program up your own FCEUX to run it, do you? The same can be said of these scripts.
-
-
So, open the luaScripts folder and actually take the time to look at some of these scripts. You may use a text-editing program to open these if you so wish.
-
-
-
General Purpose scripts:
-
These may be used with any game freely. Else, the "General" part of General Purpose doesn't apply.
-
-
-
Mutlitrack2.lua - Tracks future input that FCEUX promptly loses on state-load, for TAS
-
Subtitler.lua - For easier use of FCEUX's built-in subtitles for .fm2 files
-
Rewinder.lua - A way to rewind backwards by pressing a button
-
Sprites.lua - Sprite debugging highlights all sprites on screen, with mouse hover to inspect.
+
(written by FatRatKnight)
+
+
Overview of Included Scripts
+
+
Many users of FCEUX do not investigate the luaScripts folder, or, for that matter, ignore lua scripting altogether. The purpose of this text is to let users know that knowing how to create lua scripts is not a requirement in using them. Indeed, there are several scripts that, if you just load them, will explain themselves enough that you don't need to know how to program at all in order to use them. Besides, they shouldn't need to be re-programmed anyway if you are to use them, for if they needed programming experience just to be used, their existence is largely defeated by that very fact!
+
+
FCEUX itself is a program that you load. Our amazing programmers did all the work already so you don't need to program up your own FCEUX to run it, do you? The same can be said of these scripts.
+
+
So, open the luaScripts folder and actually take the time to look at some of these scripts. You may use a text-editing program to open these if you so wish.
+
+
+
General Purpose scripts:
+
These may be used with any game freely. Else, the "General" part of General Purpose doesn't apply.
+
+
+
Mutlitrack2.lua-Tracks future input that FCEUX promptly loses on state-load, for TAS
+
Subtitler.lua-For easier use of FCEUX's built-in subtitles for .fm2 files
+
Rewinder.lua-A way to rewind backwards by pressing a button
-
-
-
Game Specific scripts:
-
These scripts are built specifically for certain games. Attempting to run them while you've loaded another ROM will likely cause undesired results. The meaning of "undesired results" in this case are things like crashing the game, causing it to glitch in other ways, or having nonsense numbers and pixels show up.
-
-
-
BugsBunnyBirthdayBlowout.lua
-
Excitingbike.lua
-
Excitingbike-speedometeronly.lua
-
Galaxian.lua
-
Gradius-BulletHell.lua
-
Machrider.lua
-
MegamanII-LaserEyes.lua
-
PunchOutChallenge.lua
-
PunchOutStats.lua
-
PunchOutTraining.lua
-
SMB2U.lua
-
SMB3-RainbowRiding.lua
-
SMB-AreaScrambler.lua
-
SMB-CompetitionRecorder.lua
-
SMB-HitBoxes.lua
-
SMB-Jetpack.lua
-
SMB-Lives&HPDisplay.lua
-
SMB-Mouse.lua
-
SMB-Snow.lua
-
TeenageMutantNinjaTurtles.lua
-
tetris.lua
+
+
+
Game Specific scripts:
+
These scripts are built specifically for certain games. Attempting to run them while you've loaded another ROM will likely cause undesired results. The meaning of "undesired results" in this case are things like crashing the game, causing it to glitch in other ways, or having nonsense numbers and pixels show up.
+
+
+
BugsBunnyBirthdayBlowout.lua
+
Excitingbike.lua
+
Excitingbike-speedometeronly.lua
+
Galaxian.lua
+
Gradius-BulletHell.lua
+
Machrider.lua
+
MegamanII-LaserEyes.lua
+
PunchOutChallenge.lua
+
PunchOutStats.lua
+
PunchOutTraining.lua
+
SMB2U.lua
+
SMB3-RainbowRiding.lua
+
SMB-AreaScrambler.lua
+
SMB-CompetitionRecorder.lua
+
SMB-HitBoxes.lua
+
SMB-Jetpack.lua
+
SMB-Lives&HPDisplay.lua
+
SMB-Mouse.lua
+
SMB-Snow.lua
+
TeenageMutantNinjaTurtles.lua
+
tetris.lua
-
-
-
-
Auxiliary Functions scripts:
-
These scripts exist to make the life of programmers easier. As such, if you don't program, you may skip over these scripts. These should not be run by themselves, for they themselves probably don't have any programming to do any work usefully. It's like giving yourself a clip of bullets with no gun to use.
-
-
-
FRKfunctions.lua - To aid with input.get, display, and registers
-
x_functions.lua
-
shapedefs.lua - Contains a few shape-drawing functions
+
+
+
+
Auxiliary Functions scripts:
+
These scripts exist to make the life of programmers easier. As such, if you don't program, you may skip over these scripts. These should not be run by themselves, for they themselves probably don't have any programming to do any work usefully. It's like giving yourself a clip of bullets with no gun to use.
+
+
+
FRKfunctions.lua-To aid with input.get, display, and registers
+
x_functions.lua
+
shapedefs.lua-Contains a few shape-drawing functions
This document describes the low-level operation and technical details of the 2C02, the NES's PPU. In general, it contains important information in regards to PPU timing, which no NES coder/emulator author should be without. This document assumes that you already understand the basics of how the PPU works, like how the playfield/object images are generated, and the behaviour of scroll/address counters during playfield rendering.
-
-
Alot of the concepts behind how the PPU works described here have been extracted from Nintendo's patent documentation (U.S.#4,824,106). With block diagrams of the PPU's architecture (and even some schematics), these papers will definetely aid in the comprehension of this complex device.
-
-
Since the first release, this document has been given a major overhaul. Most sections of the document have been reworked, and new information has been added just about everywhere. If you've read the old version of this document before, I recommend that you read this new one in it's entirity; there's new information even in sections which may look like they haven't changed much.
-
-
Topics discussed hereon are as follows.
-
-
- Video signal generation
-
- PPU base timing
-
- Miscellanious PPU info
-
- PPU memory access cycles
-
- Frame rendering details
-
- Scanline rendering details
-
- In-range object evaluation
-
- Details of playfield render pipeline
-
- Details of object pattern fetch & render
-
- Extra cycle frames
-
- The MMC3's scanline counter
-
- PPU pixel priority quirk
-
- Graphical enhancements
-
-
-
+-------+
-
|History|
-
+-------+
-
On the weekend of Sept. 25th, Y2K, I setup an experiment with my NTSC NES MB & my PC so's I could RE the PPU's timing. What I did was (using a PC interface) analyse the changes that occur on the PPU's address and data pins on every rising & falling edge of the PPU's clock. I was not planning on removing the PPU from the motherboard (yet), so basically I just kept everything intact (minus the stuff I added onto the MB so I could monitor the PPU's signals), and popped in a game, so that it would initialize the PPU for me (I used DK classics, since it was only taking somthing like 4 frames before it was turning on the background/sprites).
-
-
The only change I made was taking out the 21 MHz clock generator circuitry. To replace the clock signal, I connected a port controlled latch to the NES's main clock line instead. Now, by writing a 0 or a 1 out to an PC ISA port of my choice (I was using $104), I was able to control the 21 MHz clockline of the NES. After I would create a rise or a fall on the NES's clock line, I would then read in the data that appeared on the PPU's address and data pins, which included monitoring what PPU registers the game read/wrote to (& the data that was read/written).
-
-
-
+-----------------------+
-
|Video signal generation|
-
+-----------------------+
-
A 21.48 MHz clock signal is fed into the PPU. This is the NES's main clock line, which is shared by the CPU.
-
-
Inside the PPU, the 21.48 MHz signal is used to clock a three-stage Johnson counter. The complimentery outputs of both master and slave portions of each stage are used to form 12 mutually exclusive output phases- all 3.58 MHz each (the NTSC colorburst). These 12 different phases form the basis of all color generation for the PPU's composite video output.
-
-
Naturally, when the user programs the lower 4-bits of a palette register, they are essentially selecting any 1 of 12 phases to be routed to the PPU's video out pin (this corresponds to chrominance (tint/hue) video information) when the appropriate pixel indexes it. Other chrominance combinations (0 & 13) are simply hardwired to a 1 or 0 to generate grayscale pixels.
-
-
Bits 4 & 5 of a palette entry selects 1 of 4 linear DC voltage offsets to apply to the selected chrominance signal (this corresponds to luminance (brightness) video information) for a pixel.
-
-
Chrominance values 14 & 15 yield a black pixel color, regardless of any luminance value setting.
-
-
Luminance value 0, mixed with chrominance value 13 yield a "blacker than black" pixel color. This super black pixel has an output voltage level close to the vertical/horizontal syncronization pulses. Because of this, some video monitors will display warped/distorted screens for games which use this color for black (Game Genie is the best example of this). Essentially what is happening is the video monitor's horizontal timing is compromised by what it thinks are extra syncronization pulses in the scanline. This is not damaging to the monitors which are effected by it, but use of the super black color should be avoided, due to the graphical distortion it causes.
-
-
The amplitude of the selected chrominance signal (via the 4 lower bits of a palette register) remain constant regardless of bits 4 or 5. Thus it is not possible to adjust the saturation level of a particular color.
-
-
-
+---------------+
-
|PPU base timing|
-
+---------------+
-
Other than the 3-stage Johnson counter, the 21.48 MHz signal is not used directly by any other PPU hardware. Instead, the signal is divided by 4 to get 5.37 MHz, and is used as the smallest unit of timing in the PPU. All following references to PPU clock cycle (abbr. "cc") timing in this document will be in respect to this timing base, unless otherwise indicated.
-
-
- Pixels are rendered at the same rate as the base PPU clock. In other words, 1 clock cycle= 1 pixel.
-
-
- 341 PPU cc's make up the time of a typical scanline (or 341/3 CPU cc's).
-
-
- One frame consists of 262 scanlines. This equals 341*262 PPU cc's per frame (divide by 3 for # of CPU cc's).
-
-
-
+------------------------+
-
|PPU memory access cycles|
-
+------------------------+
-
All PPU memory access cycles are 2 clocks long, and can be made back-to-back (typically done during rendering). Here's how the access breaks down:
-
-
At the beginning of the access cycle, PPU address lines 8..13 are updated with the target address. This data remains here until the next time an access cycle occurs.
-
-
The lower 8-bits of the PPU address lines are multiplexed with the data bus, to reduce the PPU's pin count. On the first clock cycle of the access, A0..A7 are put on the PPU's data bus, and the ALE (address latch enable) line is activated for the first half of the cycle. This loads the lower 8-bit address into an external 8-bit transparent latch strobed by ALE (74LS373 is used).
-
-
On the second clock cycle, the /RD (or /WR) line is activated, and stays active for the entire cycle. Appropriate data is driven onto the bus during this time.
-
-
-
+----------------------+
-
|Miscellanious PPU info|
-
+----------------------+
-
- Sprite DMA is 1536 clock cycles long (512 CPU cc's). 256 individual transfers are made from CPU memory to a temp register inside the CPU, then from the CPU's temp reg, to $2004.
-
-
- The PPU makes NO external access to the PPU bus, unless the playfield or objects are enabled during a scanline outside vblank. This means that the PPU's address and data busses are dead while in this state.
-
-
- palette RAM is accessed internally during playfield rendering (i.e., the palette address/data is never put on the PPU bus during this time). Additionally, when the programmer accesses palette RAM via $2006/7, the palette address accessed actually does show up on the PPU address bus, but the PPU's /RD & /WR flags are not activated. This is required; to prevent writing over name table data falling under the approprite mirrored area (since the name table RAM's address decoder simply consists of an inverter connected to the A13 line- effectively decoding all addresses in $2000-$3FFF).
-
-
- the VINT impulse (NMI) and bit $2002.7 are set simultaniously. Reading $2002 will reset bit 7, but it seems that the VINT flag goes down on it's own. Because of this, when the PPU generates a VINT, it doesn't require any acknowledgement whatsoever; it will continue firing off VINTs, regardless of inservice to $2002. The only way to stop VINTs is to clear $2000.7.
-
-
- Because the PPU cannot make a read from PPU memory immediately upon request (via $2007), there is an internal buffer, which acts as a 1-stage data pipeline. As a read is requested, the contents of the read buffer are returned to the NES's CPU. After this, at the PPU's earliest convience (according to PPU read cycle timings), the PPU will fetch the requested data from the PPU memory, and throw it in the read buffer. Writes to PPU mem via $2007 are pipelined as well, but it is unknown to me if the PPU uses this same buffer (this could be easily tested by writing somthing to $2007, and seeing if the same value is returned immediately after reading).
-
-
-
+-----------------------+
-
|Frame rendering details|
-
+-----------------------+
-
The following describes the PPU's status during all 262 scanlines of a frame. Any scanlines where work is done (like image rendering), consists of the steps which will be described in the next section.
-
-
0..19: Starting at the instant the VINT flag is pulled down (when a NMI is generated), 20 scanlines make up the period of time on the PPU which I like to call the VINT period. During this time, the PPU makes no access to it's external memory (i.e. name / pattern tables, etc.).
-
-
20: After 20 scanlines worth of time go by (since the VINT flag was set), the PPU starts to render scanlines. This first scanline is a dummy one; although it will access it's external memory in the same sequence it would for drawing a valid scanline, no on-screen pixels are rendered during this time, making the fetched background data immaterial. Both horizontal *and* vertical scroll counters are updated (presumably) at cc offset 256 in this scanline. Other than that, the operation of this scanline is identical to any other. The primary reason this scanline exists is to start the object render pipeline, since it takes 256 cc's worth of time to determine which objects are in range or not for any particular scanline.
-
-
21..260: after rendering 1 dummy scanline, the PPU starts to render the actual data to be displayed on the screen. This is done for 240 scanlines, of course.
-
-
261: after the very last rendered scanline finishes, the PPU does nothing for 1 scanline (i.e. the programmer gets screwed out of perfectly good VINT time). When this scanline finishes, the VINT flag is set, and the process of drawing lines starts all over again.
-
-
-
+--------------------------+
-
|Scanline rendering details|
-
+--------------------------+
-
Naturally, the PPU will fetch data from name, attribute, and pattern tables during a scanline to produce an image on the screen. This section details the PPU's doings during this time.
-
-
As explained before, external PPU memory can be accessed every 2 cc's. With 341 cc's per scanline, this gives the PPU enough time to make 170 memory accesses per scanline (and it uses all of them!). After the 170th fetch, the PPU does nothing for 1 clock cycle. Remember that a single pixel is rendered every clock cycle.
-
-
-
Memory fetch phase 1 thru 128
-
-----------------------------
-
1. Name table byte
-
2. Attribute table byte
-
3. Pattern table bitmap #0
-
4. Pattern table bitmap #1
-
-
This process is repeated 32 times (32 tiles in a scanline).
-
-
-
This is when the PPU retrieves the appropriate data from PPU memory for rendering the playfield. The first playfield tile fetched here is actually the 3rd to be drawn on the screen (the playfield data for the first 2 tiles to be rendered on this scanline are fetched at the end of the scanline prior to this one).
-
-
All valid on-screen pixel data arrives at the PPU's video out pin during this time (256 clocks). For determining the precise delay between when a tile's bitmap fetch phase starts (the whole 4 memory fetches), and when the first pixel of that tile's bitmap data hits the video out pin, the formula is (16-n) clock cycles, where n is the fine horizontal scroll offset (0..7 pixels). This information is relivant for understanding the exact timing operation of the "object 0 collision" flag.
-
-
Note that the PPU fetches an attribute table byte for every 8 sequential horizontal pixels it draws. This essentially limits the PPU's color area (the area of pixels which are forced to use the same 3-color palette) to only 8 horizontally sequential pixels.
-
-
It is also during this time that the PPU evaluates the "Y coordinate" entries of all 64 objects in object attribute RAM (OAM), to see if the objects are within range (to be drawn on the screen) for the *next* scanline (this is why Y-coordinate entries in the OAM must be programmed to a value 1 less than the scanline the object is to appear on). Each evaluation (presumably) takes 4 clock cycles, for a total of 256 (which is why it's done during on-screen pixel rendering).
-
-
-
In-range object evaluation
-
--------------------------
-
An 8-bit comparator is used to calculate the 9-bit difference between the current scanline (minus 21), and each Y-coordinate (plus 1) of every object entry in the OAM. Objects are considered in range if the comparator produces a difference in the range of 0..7 (if $2000.5 currently = 0), or 0..15 (if $2000.5 currently = 1).
-
-
(Note that a 9-bit comparison result is generated. This means that setting object scanline coordinates for ranges -1..-15 are actually interpreted as ranges 241..255. For this reason, objects with these ranges will never be considered to be part of any on-screen scanline range, and will not allow smooth object scrolling off the top of the screen.)
-
-
Tile index (8 bits), X-coordinate (8 bits), & attribute information (4 bits; vertical inversion is excluded) from the in-range OAM element, plus the associated 4-bit result of the range comparison accumulate in a part of the PPU called the "sprite temporary memory". Logical inversion is applied to the loaded 4-bit range comparison result, if the object's vertical inversion attribute bit is set.
-
-
Since object range evaluations occur sequentially through the OAM (starting from entry 0 to 63), the sprite temporary memory always fills in order from the highest priority in-range object, to lower ones. A 4-bit "in-range" counter is used to determine the number of found objects on the scanline (from 0 up to 8), and serves as an index pointer for placement of found object data into the 8-element sprite temporary memory. The counter is reset at the beginning of the object evaluation phase, and is post-incremented everytime an object is found in-range. This occurs until the counter equals 8, when found object data after this is discarded, and a flag (bit 5 of $2002) is raised, indicating that it is going to be dropping objects for the next scanline.
-
-
An additional memory bit associated with the sprite temporary memory is used to indicate that the primary object (#0) was found to be in range. This will be used later on to detect primary object-to-playfield pixel collisions.
-
-
-
Playfield render pipeline details
-
---------------------------------
-
As pattern table & palette select data is fetched, it is loaded into internal latches (the palette select data is selected from the fetched byte via a 2-bit 1-of-4 selector).
-
-
At the start of a new tile fetch phase (every 8 cc's), both latched pattern table bitmaps are loaded into the upper 8-bits of 2- 16-bit shift registers (which both shift right every clock cycle). The palette select data is also transfered into another latch during this time (which feeds the serial inputs of 2 8-bit right shift registers shifted every clock). The pixel data is fed into these extra shift registers in order to implement fine horizontal scrolling, since the periods when the PPU fetch tile data is fixed.
-
-
A single bit from each shift register is selected, to form the valid 4-bit playfield pixel for the current clock cycle. The bit selection offset is based on the fine horizontal scroll value (this selects bit positions 0..7 for all 4 shift registers). The selected 4-bit pixel data will then be fed into the multiplexer (described later) to be mixed with object data.
-
-
-
Memory fetch phase 129 thru 160
-
-------------------------------
-
1. Garbage name table byte
-
2. Garbage name table byte
-
3. Pattern table bitmap #0 for applicable object (for next scanline)
-
4. Pattern table bitmap #1 for applicable object (for next scanline)
-
-
This process is repeated 8 times.
-
-
-
This is the period of time when the PPU retrieves the appropriate pattern table data for the objects to be drawn on the *next* scanline. When less than 8 objects exist on the next scanline (as the in-range object evaluation counter indicates), dummy pattern table fetches take place for the remaining fetches. Internally, the fetched dummy-data is discarded, and replaced with completely transparent bitmap patterns).
-
-
Although the fetched name table data is thrown away, and the name table address is somewhat unpredictable, the address does seem to relate to the first name table tile to be fetched for the next scanline. This would seem to imply that PPU cc #256 is when the PPU's scroll/address counters have their horizontal scroll values automatically updated.
-
-
It should also be noted that because this fetch is required for objects on the next scanline, it is neccessary for a garbage scanline to exist prior to the very first scanline to be actually rendered, so that object attribute RAM entries can be evaluated, and the appropriate bitmap data retrieved.
-
-
As far as the wasted fetch phases here, well, what can I say. Either Nintendo's engineers were VERY lazy, and didn't want to add the small amount of extra circuitry to the PPU so that 16 object fetches could take place per scanline, or Nintendo couldn't spot the extra memory required to implement 16 object scanlines. Thing is though- between the object attribute mem, sprite temporary & buffer mem, and palette mem, that's already 2406 bits of RAM; I don't think it would've killed them to just add the 408 bits it would've took for an extra 8 objects, which would've made games with horrible OAM cycling (Double Dragon 2 w/ 2 players) look half-decent (hell, with 16 object scanlines, games would hardly even need OAM cycling).
-
-
-
Details of object pattern fetch & render
-
----------------------------------------
-
Where the PPU fetches pattern table data for an individual object is conditioned on the contents of the sprite temporary memory element, and $2000.5. If $2000.5 = 0, the tile index data is used as usual, and $2000.3 selects the pattern table to use. If $2000.5 = 1, the MSB of the range result value become the LSB of the indexed tile, and the LSB of the tile index value determines pattern table selection. The lower 3 bits of the range result value are always used as the fine vertical offset into the selected pattern.
-
-
Horizontal inversion (bit order reversing) is applied to fetched bitmaps, if indicated in the sprite temporary memory element.
-
-
The fetched pattern table data (which is 2 bytes), plus the associated 3 attribute bits (palette select & priority), and the x coordinate byte in sprite temporary memory are then loaded into a part of the PPU called the "sprite buffer memory" (the primary object present bit is also copied). This memory area again, is large enough to hold the contents for 8 sprites.
-
-
The composition of one sprite buffer element here is: 2 8-bit shift registers (the fetched pattern table data is loaded in here, where it will be serialized at the appropriate time), a 3-bit latch (which holds the color & priority data for an object), and an 8-bit down counter (this is where the x coordinate is loaded).
-
-
The counter is decremented every time the PPU renders a pixel (the first 256 cc's of a scanline; see "Memory fetch phase 1 thru 128" above). When the counter equals 0, the pattern table data in the shift registers will start to serialize (1 shift per clock). Before this time, or 8 clocks after, consider the outputs of the serializers for each stage to be 0 (transparency).
-
-
The streams of all 8 object serializers are prioritized, and ultimately only one stream (with palette select & priority information) is selected for output to the multiplexer (where object & playfield pixels are prioritized).
-
-
The data for the first sprite buffer entry (including the primary object present flag) has the first chance to enter the multiplexer, if it's output pixel is non-transparent (non-zero). Otherwise, priority is passed to the next serializer in the sprite buffer memory, and the test for non-transparency is made again (the primary object present status will always be passed to the multiplexer as false in this case). This is done until the last (8th) stage is reached, when the object data is passed through unconditionally. Keep in mind that this whole process occurs every clock cycle (hardware is used to determine priority instantly).
-
-
The multiplexer does 2 things: determines primary object collisions, and decides which pixel data to pass through to index the palette RAM- either the playfield's or the object's.
-
-
Primary object collisions occur when a non-transparent playfield pixel coincides with a non-transparent object pixel, while the primary object present status entering the multiplexer for the current clock cycle is true. This causes a flip-flop ($2002.6) to be set, and remains set (presumably) some time after the VINT occurence (prehaps up until scanline 20?).
-
-
The decision for selecting the data to pass through to the palette index is made rather easilly. The condition to use object (opposed to playfield) data is:
-
-
(OBJpri=foreground OR PFpixel=xparent) AND OBJpixel<>xparent
-
-
Since the PPU has 2 palettes; one for objects, and one for playfield, the appropriate palette will be selected depending on which pixel data is passed through.
-
-
After the palette look-up, the operation of events follows the aforementioned steps in the "video signal generation" section.
-
-
-
Memory fetch phase 161 thru 168
-
-------------------------------
-
1. Name table byte
-
2. Attribute table byte
-
3. Pattern table bitmap #0 (for next scanline)
-
4. Pattern table bitmap #1 (for next scanline)
-
-
This process is repeated 2 times.
-
-
-
It is during this time that the PPU fetches the appliciable playfield data for the first and second tiles to be rendered on the screen for the *next* scanline. These fetches initialize the internal playfield pixel pipelines (2- 16-bit shift registers) with valid bitmap data. The rest of tiles (3..32) are fetched at the beginning of the following scanline.
-
-
-
Memory fetch phase 169 thru 170
-
-------------------------------
-
1. Name table byte
-
2. Name table byte
-
-
-
I'm unclear of the reason why this particular access to memory is made. The name table address that is accessed 2 times in a row here, is also the same nametable address that points to the 3rd tile to be rendered on the screen (or basically, the first name table address that will be accessed when the PPU is fetching playfield data on the next scanline).
-
-
-
After memory access 170
-
-----------------------
-
The PPU simply rests for 1 cycle here (or the equivelant of half a memory access cycle) before repeating the whole pixel/scanline rendering process.
-
-
-
+------------------+
-
|Extra cycle frames|
-
+------------------+
-
Scanline 20 is the only scanline that has variable length. On every odd frame, this scanline is only 340 cycles (the dead cycle at the end is removed). This is done to cause a shift in the NTSC colorburst phase.
-
-
You see, a 3.58 MHz signal, the NTSC colorburst, is required to be modulated into a luminance carrying signal in order for color to be generated on an NTSC monitor. Since the PPU's video out consists of basically square waves (as opposed to sine waves, which would be preferred), it takes an entire colorburst cycle (1/3.58 MHz) for an NTSC monitor to identify the color of a PPU pixel accurately.
-
-
But now you remember that the PPU renders pixels at 5.37 MHz- 1.5x the rate of the colorburst. This means that if a single pixel resides on a scanline with a color different to those surrounding it, the pixel will probably be misrepresented on the screen, sometimes appearing faintly.
-
-
Well, to somewhat fix this problem, they added this extra pixel into every odd frame (shifting the colorburst phase over a bit), and changing the way the monitor interprets isolated colored pixels each frame. This is why when you play games with detailed background graphics, the background seems to flicker a bit. Once you start scrolling the screen however, it seems as if some pixels become invisible; this is how stationary PPU images would look without this cycle removed from odd frames.
-
-
Certain scroll rates expose this NTSC PPU color caveat regardless of the toggling phase shift. Some of Zelda 2's dungeon backgrounds are a good place to see this effect.
-
-
-
+---------------------------+
-
|The MMC3's scanline counter|
-
+---------------------------+
-
As most people know, the MMC3 bases it's scanline counter on PPU address line A13 (which is why IRQ's can be fired off manually by toggling A13 a bunch of times via $2006). What's not common knowledge is the number of times A13 is expected to toggle in a scanline (although if you've been paying close attention to the doc here, you should already know ;)
-
-
A13 was probably used for the IRQ counter (as opposed to using the PPU's /READ line) because this address line already needed to be connected to the MMC for bankswitching purposes (so in other words, to reduce the MMC3's pin count by 1). They also probably used this method of counting (as opposed to a CPU cycle counter) since A13 cycles (0 -> 1) exactly 42 times per scanline, whereas the CPU count of cycles per scanline is not an exact integer (113.67). Having said that, I guess Nintendo wanted to provide an "easy-to-use" method of generating special image effects, without making programmers have to figure out how many clock cycles to program an IRQ counter with (a pretty lame excuse for not providing an IRQ counter with CPU clock cycle precision (which would have been more useful and versatile)).
-
-
Regardless of any values PPU registers are programmed with, A13 will operate in a predictable fashion during image rendering (and if you understand how PPU addressing works, you should understand that A13 is the *only* address line with fixed behaviour during image rendering).
-
-
-
+------------------------+
-
|PPU pixel priority quirk|
-
+------------------------+
-
Object data is prioritized between itself, then prioritized between the playfield. There are some odd side effects to this scheme of rendering, however. For instance, imagine a low priority object pixel with foreground priority, a high priority object pixel with background priority, and a playfield pixel all coinciding (all non-transparent).
-
-
Ideally, the playfield is considered to be the middle layer between background and foreground priority objects. This means that the playfield pixel should hide the background priority object pixel (regardless of object priority), and the foreground priority object should appear atop the PF pixel.
-
-
However, because of the way the PPU renders (as just described), OBJ priority is evaluated first, and therefore the background object pixel wins, which means that you'll only be seeing the PF pixel after this mess.
-
-
A good game to demonstrate this behaviour is Megaman 2. Go into airman's stage. First, jump into the energy bar, just to confirm that megaman's sprite is of a higher priority than the energy bar's. Now, get to the second half of the stage, where the clouds cover the energy bar. The energy bar will be ontop of the clouds, but megaman will be behind them. Now, look what happens when you jump into the energy bar here... you see the clouds where megaman underlaps the energy bar.
-
-
-
+----------------------+
-
|Graphical enhancements|
-
+----------------------+
-
Since an NES cartridge has access to the PPU bus, any number of on-cart hardware schemes can be used to enhance the graphic capabilities of the NES. After all, the PPU's playfield pipeline is very simple: it fetches 272 playfield pixels per scanline (as 34*2 byte fetches, in real-time), and outputs 256 of them to the screen (with the 0..7 pixel offset determined by the fine X scroll register), along with object data combined with it.
-
-
Essentially, you can bypass the PPU's simple scrolling system, implement a custom one on your cart (fetching bitmap data in your own fashion), and feed the PPU bitmap data in your own order.
-
-
The possibilities of this are endless (like sporting multiple playfields, or even playfield rotation/scaling), but of course what it comes down to is the amount of cartridge hardware required.
-
-
Generally, playfield rotation/scaling can be done quite easily- it only requires a few sets of 16-bit registers and adders (the 16 bits are broken up into 8.8 fixed point values). But this kind of implementation is more suited for an integrated circuit, since this would require dozens of discrete logic chips.
-
-
Multiple playfields are another thing which could be easily done. The caveat here is that pixel pipelines (i.e., shift registers) and a multiplexer would have to be implemented on the cart (not to mention exclusive name table RAM) in order to process the playfield bitmaps from multiple sources. The access to the CHR-ROM/RAM would also have to increased- but as it stands, the CHR-ROM/RAM bandwidth is 1.34 MHz, a rather low frequency. With a memory device capable of a 10.74 MHz bandwith, you could have 8 playfields to work with. Generally, this would be very useful for displaying multiple huge objects on the screen- without ever having to worry about annoying flicker.
-
-
The only restriction to doing any of this is that:
-
-
- every 8 sequential horizontal pixels sent to the PPU must share the same palette select value. Because of this, hardware would have to be implemented to decide which palette select value to feed the PPU between 8 horizontally sequential pixels, if they do not all share the same palette select value. The on-screen results of this may not be too flattering sometimes, but this is a small price to pay to do some neat graphical tricks on the NES.
-
-
-only the playfield palette can be used. As usual, this pretty much limits your randomly accessable colors to about 12+1.
-
-
It's a damn shame that Nintendo never created a MMC which would enhance graphics on the NES in useful ways as mentioned above. The MMC5 was the only device that came close, and it's only selling features were the single-tile color area, and the vertical split screen mode (which I don't think any game ever used). Considering the amount of pins (100) the MMC5 had, and number of gates they put in it just for the EXRAM (which was 1K bytes), they could've put some really useful graphics hardware inside there instead.
-
-
Prehaps the infamous Color Dreams "Hellraiser" cart was the closest the NES ever came to seeing such sophisticated graphics. The cart was never released, but from what I've read, it was going to use some sort of frame buffer, and a Z80 CPU to do the graphical rendering. It had been rumored that the game had 3D graphics (or at least 2.5D) in it. If so (and the game was actually good), prehaps it would have raised a few eyebrows in the industry, and inspired Nintendo to develop a new MMC chip with similar capabilities, in order to keep the NES in it's profit margin for another few years (and allow it to compete somewhat with the more advanced systems of the time).
This document describes the low-level operation and technical details of the 2C02, the NES's PPU. In general, it contains important information in regards to PPU timing, which no NES coder/emulator author should be without. This document assumes that you already understand the basics of how the PPU works, like how the playfield/object images are generated, and the behaviour of scroll/address counters during playfield rendering.
+
+
Alot of the concepts behind how the PPU works described here have been extracted from Nintendo's patent documentation (U.S.#4,824,106). With block diagrams of the PPU's architecture (and even some schematics), these papers will definetely aid in the comprehension of this complex device.
+
+
Since the first release, this document has been given a major overhaul. Most sections of the document have been reworked, and new information has been added just about everywhere. If you've read the old version of this document before, I recommend that you read this new one in it's entirity; there's new information even in sections which may look like they haven't changed much.
+
+
Topics discussed hereon are as follows.
+
+
- Video signal generation
+
- PPU base timing
+
- Miscellanious PPU info
+
- PPU memory access cycles
+
- Frame rendering details
+
- Scanline rendering details
+
- In-range object evaluation
+
- Details of playfield render pipeline
+
- Details of object pattern fetch & render
+
- Extra cycle frames
+
- The MMC3's scanline counter
+
- PPU pixel priority quirk
+
- Graphical enhancements
+
+
+
+-------+
+
|History|
+
+-------+
+
On the weekend of Sept. 25th, Y2K, I setup an experiment with my NTSC NES MB & my PC so's I could RE the PPU's timing. What I did was (using a PC interface) analyse the changes that occur on the PPU's address and data pins on every rising & falling edge of the PPU's clock. I was not planning on removing the PPU from the motherboard (yet), so basically I just kept everything intact (minus the stuff I added onto the MB so I could monitor the PPU's signals), and popped in a game, so that it would initialize the PPU for me (I used DK classics, since it was only taking somthing like 4 frames before it was turning on the background/sprites).
+
+
The only change I made was taking out the 21 MHz clock generator circuitry. To replace the clock signal, I connected a port controlled latch to the NES's main clock line instead. Now, by writing a 0 or a 1 out to an PC ISA port of my choice (I was using $104), I was able to control the 21 MHz clockline of the NES. After I would create a rise or a fall on the NES's clock line, I would then read in the data that appeared on the PPU's address and data pins, which included monitoring what PPU registers the game read/wrote to (& the data that was read/written).
+
+
+
+-----------------------+
+
|Video signal generation|
+
+-----------------------+
+
A 21.48 MHz clock signal is fed into the PPU. This is the NES's main clock line, which is shared by the CPU.
+
+
Inside the PPU, the 21.48 MHz signal is used to clock a three-stage Johnson counter. The complimentery outputs of both master and slave portions of each stage are used to form 12 mutually exclusive output phases- all 3.58 MHz each (the NTSC colorburst). These 12 different phases form the basis of all color generation for the PPU's composite video output.
+
+
Naturally, when the user programs the lower 4-bits of a palette register, they are essentially selecting any 1 of 12 phases to be routed to the PPU's video out pin (this corresponds to chrominance (tint/hue) video information) when the appropriate pixel indexes it. Other chrominance combinations (0 & 13) are simply hardwired to a 1 or 0 to generate grayscale pixels.
+
+
Bits 4 & 5 of a palette entry selects 1 of 4 linear DC voltage offsets to apply to the selected chrominance signal (this corresponds to luminance (brightness) video information) for a pixel.
+
+
Chrominance values 14 & 15 yield a black pixel color, regardless of any luminance value setting.
+
+
Luminance value 0, mixed with chrominance value 13 yield a "blacker than black" pixel color. This super black pixel has an output voltage level close to the vertical/horizontal syncronization pulses. Because of this, some video monitors will display warped/distorted screens for games which use this color for black (Game Genie is the best example of this). Essentially what is happening is the video monitor's horizontal timing is compromised by what it thinks are extra syncronization pulses in the scanline. This is not damaging to the monitors which are effected by it, but use of the super black color should be avoided, due to the graphical distortion it causes.
+
+
The amplitude of the selected chrominance signal (via the 4 lower bits of a palette register) remain constant regardless of bits 4 or 5. Thus it is not possible to adjust the saturation level of a particular color.
+
+
+
+---------------+
+
|PPU base timing|
+
+---------------+
+
Other than the 3-stage Johnson counter, the 21.48 MHz signal is not used directly by any other PPU hardware. Instead, the signal is divided by 4 to get 5.37 MHz, and is used as the smallest unit of timing in the PPU. All following references to PPU clock cycle (abbr. "cc") timing in this document will be in respect to this timing base, unless otherwise indicated.
+
+
- Pixels are rendered at the same rate as the base PPU clock. In other words, 1 clock cycle= 1 pixel.
+
+
- 341 PPU cc's make up the time of a typical scanline (or 341/3 CPU cc's).
+
+
- One frame consists of 262 scanlines. This equals 341*262 PPU cc's per frame (divide by 3 for # of CPU cc's).
+
+
+
+------------------------+
+
|PPU memory access cycles|
+
+------------------------+
+
All PPU memory access cycles are 2 clocks long, and can be made back-to-back (typically done during rendering). Here's how the access breaks down:
+
+
At the beginning of the access cycle, PPU address lines 8..13 are updated with the target address. This data remains here until the next time an access cycle occurs.
+
+
The lower 8-bits of the PPU address lines are multiplexed with the data bus, to reduce the PPU's pin count. On the first clock cycle of the access, A0..A7 are put on the PPU's data bus, and the ALE (address latch enable) line is activated for the first half of the cycle. This loads the lower 8-bit address into an external 8-bit transparent latch strobed by ALE (74LS373 is used).
+
+
On the second clock cycle, the /RD (or /WR) line is activated, and stays active for the entire cycle. Appropriate data is driven onto the bus during this time.
+
+
+
+----------------------+
+
|Miscellanious PPU info|
+
+----------------------+
+
- Sprite DMA is 1536 clock cycles long (512 CPU cc's). 256 individual transfers are made from CPU memory to a temp register inside the CPU, then from the CPU's temp reg, to $2004.
+
+
- The PPU makes NO external access to the PPU bus, unless the playfield or objects are enabled during a scanline outside vblank. This means that the PPU's address and data busses are dead while in this state.
+
+
- palette RAM is accessed internally during playfield rendering (i.e., the palette address/data is never put on the PPU bus during this time). Additionally, when the programmer accesses palette RAM via $2006/7, the palette address accessed actually does show up on the PPU address bus, but the PPU's /RD & /WR flags are not activated. This is required; to prevent writing over name table data falling under the approprite mirrored area (since the name table RAM's address decoder simply consists of an inverter connected to the A13 line- effectively decoding all addresses in $2000-$3FFF).
+
+
- the VINT impulse (NMI) and bit $2002.7 are set simultaniously. Reading $2002 will reset bit 7, but it seems that the VINT flag goes down on it's own. Because of this, when the PPU generates a VINT, it doesn't require any acknowledgement whatsoever; it will continue firing off VINTs, regardless of inservice to $2002. The only way to stop VINTs is to clear $2000.7.
+
+
- Because the PPU cannot make a read from PPU memory immediately upon request (via $2007), there is an internal buffer, which acts as a 1-stage data pipeline. As a read is requested, the contents of the read buffer are returned to the NES's CPU. After this, at the PPU's earliest convience (according to PPU read cycle timings), the PPU will fetch the requested data from the PPU memory, and throw it in the read buffer. Writes to PPU mem via $2007 are pipelined as well, but it is unknown to me if the PPU uses this same buffer (this could be easily tested by writing somthing to $2007, and seeing if the same value is returned immediately after reading).
+
+
+
+-----------------------+
+
|Frame rendering details|
+
+-----------------------+
+
The following describes the PPU's status during all 262 scanlines of a frame. Any scanlines where work is done (like image rendering), consists of the steps which will be described in the next section.
+
+
0..19:Starting at the instant the VINT flag is pulled down (when a NMI is generated), 20 scanlines make up the period of time on the PPU which I like to call the VINT period. During this time, the PPU makes no access to it's external memory (i.e. name / pattern tables, etc.).
+
+
20:After 20 scanlines worth of time go by (since the VINT flag was set), the PPU starts to render scanlines. This first scanline is a dummy one; although it will access it's external memory in the same sequence it would for drawing a valid scanline, no on-screen pixels are rendered during this time, making the fetched background data immaterial. Both horizontal *and* vertical scroll counters are updated (presumably) at cc offset 256 in this scanline. Other than that, the operation of this scanline is identical to any other. The primary reason this scanline exists is to start the object render pipeline, since it takes 256 cc's worth of time to determine which objects are in range or not for any particular scanline.
+
+
21..260: after rendering 1 dummy scanline, the PPU starts to render the actual data to be displayed on the screen. This is done for 240 scanlines, of course.
+
+
261:after the very last rendered scanline finishes, the PPU does nothing for 1 scanline (i.e. the programmer gets screwed out of perfectly good VINT time). When this scanline finishes, the VINT flag is set, and the process of drawing lines starts all over again.
+
+
+
+--------------------------+
+
|Scanline rendering details|
+
+--------------------------+
+
Naturally, the PPU will fetch data from name, attribute, and pattern tables during a scanline to produce an image on the screen. This section details the PPU's doings during this time.
+
+
As explained before, external PPU memory can be accessed every 2 cc's. With 341 cc's per scanline, this gives the PPU enough time to make 170 memory accesses per scanline (and it uses all of them!). After the 170th fetch, the PPU does nothing for 1 clock cycle. Remember that a single pixel is rendered every clock cycle.
+
+
+
Memory fetch phase 1 thru 128
+
-----------------------------
+
1. Name table byte
+
2. Attribute table byte
+
3. Pattern table bitmap #0
+
4. Pattern table bitmap #1
+
+
This process is repeated 32 times (32 tiles in a scanline).
+
+
+
This is when the PPU retrieves the appropriate data from PPU memory for rendering the playfield. The first playfield tile fetched here is actually the 3rd to be drawn on the screen (the playfield data for the first 2 tiles to be rendered on this scanline are fetched at the end of the scanline prior to this one).
+
+
All valid on-screen pixel data arrives at the PPU's video out pin during this time (256 clocks). For determining the precise delay between when a tile's bitmap fetch phase starts (the whole 4 memory fetches), and when the first pixel of that tile's bitmap data hits the video out pin, the formula is (16-n) clock cycles, where n is the fine horizontal scroll offset (0..7 pixels). This information is relivant for understanding the exact timing operation of the "object 0 collision" flag.
+
+
Note that the PPU fetches an attribute table byte for every 8 sequential horizontal pixels it draws. This essentially limits the PPU's color area (the area of pixels which are forced to use the same 3-color palette) to only 8 horizontally sequential pixels.
+
+
It is also during this time that the PPU evaluates the "Y coordinate" entries of all 64 objects in object attribute RAM (OAM), to see if the objects are within range (to be drawn on the screen) for the *next* scanline (this is why Y-coordinate entries in the OAM must be programmed to a value 1 less than the scanline the object is to appear on). Each evaluation (presumably) takes 4 clock cycles, for a total of 256 (which is why it's done during on-screen pixel rendering).
+
+
+
In-range object evaluation
+
--------------------------
+
An 8-bit comparator is used to calculate the 9-bit difference between the current scanline (minus 21), and each Y-coordinate (plus 1) of every object entry in the OAM. Objects are considered in range if the comparator produces a difference in the range of 0..7 (if $2000.5 currently = 0), or 0..15 (if $2000.5 currently = 1).
+
+
(Note that a 9-bit comparison result is generated. This means that setting object scanline coordinates for ranges -1..-15 are actually interpreted as ranges 241..255. For this reason, objects with these ranges will never be considered to be part of any on-screen scanline range, and will not allow smooth object scrolling off the top of the screen.)
+
+
Tile index (8 bits), X-coordinate (8 bits), & attribute information (4 bits; vertical inversion is excluded) from the in-range OAM element, plus the associated 4-bit result of the range comparison accumulate in a part of the PPU called the "sprite temporary memory". Logical inversion is applied to the loaded 4-bit range comparison result, if the object's vertical inversion attribute bit is set.
+
+
Since object range evaluations occur sequentially through the OAM (starting from entry 0 to 63), the sprite temporary memory always fills in order from the highest priority in-range object, to lower ones. A 4-bit "in-range" counter is used to determine the number of found objects on the scanline (from 0 up to 8), and serves as an index pointer for placement of found object data into the 8-element sprite temporary memory. The counter is reset at the beginning of the object evaluation phase, and is post-incremented everytime an object is found in-range. This occurs until the counter equals 8, when found object data after this is discarded, and a flag (bit 5 of $2002) is raised, indicating that it is going to be dropping objects for the next scanline.
+
+
An additional memory bit associated with the sprite temporary memory is used to indicate that the primary object (#0) was found to be in range. This will be used later on to detect primary object-to-playfield pixel collisions.
+
+
+
Playfield render pipeline details
+
---------------------------------
+
As pattern table & palette select data is fetched, it is loaded into internal latches (the palette select data is selected from the fetched byte via a 2-bit 1-of-4 selector).
+
+
At the start of a new tile fetch phase (every 8 cc's), both latched pattern table bitmaps are loaded into the upper 8-bits of 2- 16-bit shift registers (which both shift right every clock cycle). The palette select data is also transfered into another latch during this time (which feeds the serial inputs of 2 8-bit right shift registers shifted every clock). The pixel data is fed into these extra shift registers in order to implement fine horizontal scrolling, since the periods when the PPU fetch tile data is fixed.
+
+
A single bit from each shift register is selected, to form the valid 4-bit playfield pixel for the current clock cycle. The bit selection offset is based on the fine horizontal scroll value (this selects bit positions 0..7 for all 4 shift registers). The selected 4-bit pixel data will then be fed into the multiplexer (described later) to be mixed with object data.
+
+
+
Memory fetch phase 129 thru 160
+
-------------------------------
+
1. Garbage name table byte
+
2. Garbage name table byte
+
3. Pattern table bitmap #0 for applicable object (for next scanline)
+
4. Pattern table bitmap #1 for applicable object (for next scanline)
+
+
This process is repeated 8 times.
+
+
+
This is the period of time when the PPU retrieves the appropriate pattern table data for the objects to be drawn on the *next* scanline. When less than 8 objects exist on the next scanline (as the in-range object evaluation counter indicates), dummy pattern table fetches take place for the remaining fetches. Internally, the fetched dummy-data is discarded, and replaced with completely transparent bitmap patterns).
+
+
Although the fetched name table data is thrown away, and the name table address is somewhat unpredictable, the address does seem to relate to the first name table tile to be fetched for the next scanline. This would seem to imply that PPU cc #256 is when the PPU's scroll/address counters have their horizontal scroll values automatically updated.
+
+
It should also be noted that because this fetch is required for objects on the next scanline, it is neccessary for a garbage scanline to exist prior to the very first scanline to be actually rendered, so that object attribute RAM entries can be evaluated, and the appropriate bitmap data retrieved.
+
+
As far as the wasted fetch phases here, well, what can I say. Either Nintendo's engineers were VERY lazy, and didn't want to add the small amount of extra circuitry to the PPU so that 16 object fetches could take place per scanline, or Nintendo couldn't spot the extra memory required to implement 16 object scanlines. Thing is though- between the object attribute mem, sprite temporary & buffer mem, and palette mem, that's already 2406 bits of RAM; I don't think it would've killed them to just add the 408 bits it would've took for an extra 8 objects, which would've made games with horrible OAM cycling (Double Dragon 2 w/ 2 players) look half-decent (hell, with 16 object scanlines, games would hardly even need OAM cycling).
+
+
+
Details of object pattern fetch & render
+
----------------------------------------
+
Where the PPU fetches pattern table data for an individual object is conditioned on the contents of the sprite temporary memory element, and $2000.5. If $2000.5 = 0, the tile index data is used as usual, and $2000.3 selects the pattern table to use. If $2000.5 = 1, the MSB of the range result value become the LSB of the indexed tile, and the LSB of the tile index value determines pattern table selection. The lower 3 bits of the range result value are always used as the fine vertical offset into the selected pattern.
+
+
Horizontal inversion (bit order reversing) is applied to fetched bitmaps, if indicated in the sprite temporary memory element.
+
+
The fetched pattern table data (which is 2 bytes), plus the associated 3 attribute bits (palette select & priority), and the x coordinate byte in sprite temporary memory are then loaded into a part of the PPU called the "sprite buffer memory" (the primary object present bit is also copied). This memory area again, is large enough to hold the contents for 8 sprites.
+
+
The composition of one sprite buffer element here is: 2 8-bit shift registers (the fetched pattern table data is loaded in here, where it will be serialized at the appropriate time), a 3-bit latch (which holds the color & priority data for an object), and an 8-bit down counter (this is where the x coordinate is loaded).
+
+
The counter is decremented every time the PPU renders a pixel (the first 256 cc's of a scanline; see "Memory fetch phase 1 thru 128" above). When the counter equals 0, the pattern table data in the shift registers will start to serialize (1 shift per clock). Before this time, or 8 clocks after, consider the outputs of the serializers for each stage to be 0 (transparency).
+
+
The streams of all 8 object serializers are prioritized, and ultimately only one stream (with palette select & priority information) is selected for output to the multiplexer (where object & playfield pixels are prioritized).
+
+
The data for the first sprite buffer entry (including the primary object present flag) has the first chance to enter the multiplexer, if it's output pixel is non-transparent (non-zero). Otherwise, priority is passed to the next serializer in the sprite buffer memory, and the test for non-transparency is made again (the primary object present status will always be passed to the multiplexer as false in this case). This is done until the last (8th) stage is reached, when the object data is passed through unconditionally. Keep in mind that this whole process occurs every clock cycle (hardware is used to determine priority instantly).
+
+
The multiplexer does 2 things: determines primary object collisions, and decides which pixel data to pass through to index the palette RAM- either the playfield's or the object's.
+
+
Primary object collisions occur when a non-transparent playfield pixel coincides with a non-transparent object pixel, while the primary object present status entering the multiplexer for the current clock cycle is true. This causes a flip-flop ($2002.6) to be set, and remains set (presumably) some time after the VINT occurence (prehaps up until scanline 20?).
+
+
The decision for selecting the data to pass through to the palette index is made rather easilly. The condition to use object (opposed to playfield) data is:
+
+
(OBJpri=foreground OR PFpixel=xparent) AND OBJpixel<>xparent
+
+
Since the PPU has 2 palettes; one for objects, and one for playfield, the appropriate palette will be selected depending on which pixel data is passed through.
+
+
After the palette look-up, the operation of events follows the aforementioned steps in the "video signal generation" section.
+
+
+
Memory fetch phase 161 thru 168
+
-------------------------------
+
1. Name table byte
+
2. Attribute table byte
+
3. Pattern table bitmap #0 (for next scanline)
+
4. Pattern table bitmap #1 (for next scanline)
+
+
This process is repeated 2 times.
+
+
+
It is during this time that the PPU fetches the appliciable playfield data for the first and second tiles to be rendered on the screen for the *next* scanline. These fetches initialize the internal playfield pixel pipelines (2- 16-bit shift registers) with valid bitmap data. The rest of tiles (3..32) are fetched at the beginning of the following scanline.
+
+
+
Memory fetch phase 169 thru 170
+
-------------------------------
+
1. Name table byte
+
2. Name table byte
+
+
+
I'm unclear of the reason why this particular access to memory is made. The name table address that is accessed 2 times in a row here, is also the same nametable address that points to the 3rd tile to be rendered on the screen (or basically, the first name table address that will be accessed when the PPU is fetching playfield data on the next scanline).
+
+
+
After memory access 170
+
-----------------------
+
The PPU simply rests for 1 cycle here (or the equivelant of half a memory access cycle) before repeating the whole pixel/scanline rendering process.
+
+
+
+------------------+
+
|Extra cycle frames|
+
+------------------+
+
Scanline 20 is the only scanline that has variable length. On every odd frame, this scanline is only 340 cycles (the dead cycle at the end is removed). This is done to cause a shift in the NTSC colorburst phase.
+
+
You see, a 3.58 MHz signal, the NTSC colorburst, is required to be modulated into a luminance carrying signal in order for color to be generated on an NTSC monitor. Since the PPU's video out consists of basically square waves (as opposed to sine waves, which would be preferred), it takes an entire colorburst cycle (1/3.58 MHz) for an NTSC monitor to identify the color of a PPU pixel accurately.
+
+
But now you remember that the PPU renders pixels at 5.37 MHz- 1.5x the rate of the colorburst. This means that if a single pixel resides on a scanline with a color different to those surrounding it, the pixel will probably be misrepresented on the screen, sometimes appearing faintly.
+
+
Well, to somewhat fix this problem, they added this extra pixel into every odd frame (shifting the colorburst phase over a bit), and changing the way the monitor interprets isolated colored pixels each frame. This is why when you play games with detailed background graphics, the background seems to flicker a bit. Once you start scrolling the screen however, it seems as if some pixels become invisible; this is how stationary PPU images would look without this cycle removed from odd frames.
+
+
Certain scroll rates expose this NTSC PPU color caveat regardless of the toggling phase shift. Some of Zelda 2's dungeon backgrounds are a good place to see this effect.
+
+
+
+---------------------------+
+
|The MMC3's scanline counter|
+
+---------------------------+
+
As most people know, the MMC3 bases it's scanline counter on PPU address line A13 (which is why IRQ's can be fired off manually by toggling A13 a bunch of times via $2006). What's not common knowledge is the number of times A13 is expected to toggle in a scanline (although if you've been paying close attention to the doc here, you should already know ;)
+
+
A13 was probably used for the IRQ counter (as opposed to using the PPU's /READ line) because this address line already needed to be connected to the MMC for bankswitching purposes (so in other words, to reduce the MMC3's pin count by 1). They also probably used this method of counting (as opposed to a CPU cycle counter) since A13 cycles (0 -> 1) exactly 42 times per scanline, whereas the CPU count of cycles per scanline is not an exact integer (113.67). Having said that, I guess Nintendo wanted to provide an "easy-to-use" method of generating special image effects, without making programmers have to figure out how many clock cycles to program an IRQ counter with (a pretty lame excuse for not providing an IRQ counter with CPU clock cycle precision (which would have been more useful and versatile)).
+
+
Regardless of any values PPU registers are programmed with, A13 will operate in a predictable fashion during image rendering (and if you understand how PPU addressing works, you should understand that A13 is the *only* address line with fixed behaviour during image rendering).
+
+
+
+------------------------+
+
|PPU pixel priority quirk|
+
+------------------------+
+
Object data is prioritized between itself, then prioritized between the playfield. There are some odd side effects to this scheme of rendering, however. For instance, imagine a low priority object pixel with foreground priority, a high priority object pixel with background priority, and a playfield pixel all coinciding (all non-transparent).
+
+
Ideally, the playfield is considered to be the middle layer between background and foreground priority objects. This means that the playfield pixel should hide the background priority object pixel (regardless of object priority), and the foreground priority object should appear atop the PF pixel.
+
+
However, because of the way the PPU renders (as just described), OBJ priority is evaluated first, and therefore the background object pixel wins, which means that you'll only be seeing the PF pixel after this mess.
+
+
A good game to demonstrate this behaviour is Megaman 2. Go into airman's stage. First, jump into the energy bar, just to confirm that megaman's sprite is of a higher priority than the energy bar's. Now, get to the second half of the stage, where the clouds cover the energy bar. The energy bar will be ontop of the clouds, but megaman will be behind them. Now, look what happens when you jump into the energy bar here... you see the clouds where megaman underlaps the energy bar.
+
+
+
+----------------------+
+
|Graphical enhancements|
+
+----------------------+
+
Since an NES cartridge has access to the PPU bus, any number of on-cart hardware schemes can be used to enhance the graphic capabilities of the NES. After all, the PPU's playfield pipeline is very simple: it fetches 272 playfield pixels per scanline (as 34*2 byte fetches, in real-time), and outputs 256 of them to the screen (with the 0..7 pixel offset determined by the fine X scroll register), along with object data combined with it.
+
+
Essentially, you can bypass the PPU's simple scrolling system, implement a custom one on your cart (fetching bitmap data in your own fashion), and feed the PPU bitmap data in your own order.
+
+
The possibilities of this are endless (like sporting multiple playfields, or even playfield rotation/scaling), but of course what it comes down to is the amount of cartridge hardware required.
+
+
Generally, playfield rotation/scaling can be done quite easily- it only requires a few sets of 16-bit registers and adders (the 16 bits are broken up into 8.8 fixed point values). But this kind of implementation is more suited for an integrated circuit, since this would require dozens of discrete logic chips.
+
+
Multiple playfields are another thing which could be easily done. The caveat here is that pixel pipelines (i.e., shift registers) and a multiplexer would have to be implemented on the cart (not to mention exclusive name table RAM) in order to process the playfield bitmaps from multiple sources. The access to the CHR-ROM/RAM would also have to increased- but as it stands, the CHR-ROM/RAM bandwidth is 1.34 MHz, a rather low frequency. With a memory device capable of a 10.74 MHz bandwith, you could have 8 playfields to work with. Generally, this would be very useful for displaying multiple huge objects on the screen- without ever having to worry about annoying flicker.
+
+
The only restriction to doing any of this is that:
+
+
- every 8 sequential horizontal pixels sent to the PPU must share the same palette select value. Because of this, hardware would have to be implemented to decide which palette select value to feed the PPU between 8 horizontally sequential pixels, if they do not all share the same palette select value. The on-screen results of this may not be too flattering sometimes, but this is a small price to pay to do some neat graphical tricks on the NES.
+
+
-only the playfield palette can be used. As usual, this pretty much limits your randomly accessable colors to about 12+1.
+
+
It's a damn shame that Nintendo never created a MMC which would enhance graphics on the NES in useful ways as mentioned above. The MMC5 was the only device that came close, and it's only selling features were the single-tile color area, and the vertical split screen mode (which I don't think any game ever used). Considering the amount of pins (100) the MMC5 had, and number of gates they put in it just for the EXRAM (which was 1K bytes), they could've put some really useful graphics hardware inside there instead.
+
+
Prehaps the infamous Color Dreams "Hellraiser" cart was the closest the NES ever came to seeing such sophisticated graphics. The cart was never released, but from what I've read, it was going to use some sort of frame buffer, and a Z80 CPU to do the graphical rendering. It had been rumored that the game had 3D graphics (or at least 2.5D) in it. If so (and the game was actually good), prehaps it would have raised a few eyebrows in the industry, and inspired Nintendo to develop a new MMC chip with similar capabilities, in order to keep the NES in it's profit margin for another few years (and allow it to compete somewhat with the more advanced systems of the time).
The NES architecture includes a 6502 CPU as well as a custom video controller known as a PPU (Picture Processing Unit). The PPU's video memory is separated from the main CPU memory and can be read/written via special ports (see PPU Memory).
-
-
The PPU viewer will only display the contents of the current PPU memory. It does not alter game data in any way.
-
-
-
Using PPU Viewer
-
-
Show on Scanline
-
This options makes it show what the PPU looks like when the screen is drawing that particular scanline. It is useful for games like SMB, that swap pattern tables mid-frame (e.g. for status bar stuff).
-
-
Right clicking on one of the PPU panels will change the palette it is shown with, cycling though pattern palettes, then sprite ones, then a ninth fixed grey palette (useful for inspecting CHR if all the palettes are currently black).
-
-
Putting the mouse cursor over a tile will display the tile address. Moving cursor over palette color will give palette address.
-
-
When Code/Data Logger is running, you can also use the "Mask unused graphics" feature. Alternatively, you can only mask tiles that were used (drawn or otherwise accessed) and emphasize the tiles that weren't used (e.g. in order to find secret sprites).
-
Note: this feature only works with games that use CHR ROM, because Code/Data Logger only logs accesses to CHR ROM.
The NES architecture includes a 6502 CPU as well as a custom video controller known as a PPU (Picture Processing Unit). The PPU's video memory is separated from the main CPU memory and can be read/written via special ports (see PPU Memory).
+
+
The PPU viewer will only display the contents of the current PPU memory. It does not alter game data in any way.
+
+
+
Using PPU Viewer
+
+
Show on Scanline
+
This options makes it show what the PPU looks like when the screen is drawing that particular scanline. It is useful for games like SMB, that swap pattern tables mid-frame (e.g. for status bar stuff).
+
+
Right clicking on one of the PPU panels will change the palette it is shown with, cycling though pattern palettes and then sprite ones.
+
Putting the mouse cursor over a tile will display the tile address. Moving cursor over palette color will give palette address.
+
+
When Code/Data Logger is running, you can also use the "Mask unused graphics" feature. Alternatively, you can only mask tiles that were used (drawn or otherwise accessed) and emphasize the tiles that weren't used (e.g. in order to find secret sprites).
+
Note: this feature only works with games that use CHR ROM, because Code/Data Logger only logs accesses to CHR ROM.
Settings related to the emulator's color palette choices.
-
-
-
NES Palette
-
-
Use Custom Palette
-
Check or uncheck this to switch between default palette and currently loaded custom palette.
-
-
Load Palette
-
Allows you to load a custom color palette (.pal) file to use for the current game loaded.
-
-
A note on on the format of external palettes; Palette files are expected to contain 64 8-bit RGB triplets (each in that order; red comes first in the triplet in the file, then green, then blue). Each 8-bit value represents brightness for that particular color. 0 is minimum, 255 is maximum.
-
-
Palettes can be set on a per-game basis. To do this, put a palette file in the same directory the game is in, and add the extension "pal". Examples:
-
-
File name: Palette file name:
-
BigBad.nes BigBad.pal
-
BigBad.zip BigBad.pal
-
BigBad.Better.nes BigBad.Better.pal
-
-
-
With so many ways to choose a palette, figuring out which one will be active may be difficult. Here's a list of what palettes will be used, in order from highest priority to least priority(if a condition doesn't exist for a higher priority palette, the emulator will continue down its list of palettes).
-
-
* NSF Palette(for NSFs only)
-
* Palette loaded from the "gameinfo" directory.
-
* NTSC Color Emulation(only for NTSC NES games).
-
* VS Unisystem palette(if the game is a VS Unisystem game and a palette is available).
-
* Custom global palette.
-
* Default NES palette.
-
-
Force Grayscale
-
Applies simple Grayscale filter, no matter what palette is currently used.
-
-
De-emphasis bit swap
-
Every PAL PPU has de-emphasis bits for green and red colors swapped. This option simulates that behavior.
-
-
-
NTSC Color Emulation
-
-
If enabled, FCEUX will simulate actual NTSC signal processing. The result should be the actual colors you would see if outputting to an actual NTSC television.
-
-
The Tint and Hue knobs can be used to make adjustments to the resulting color change.
Settings related to the emulator's color palette choices.
+
+
+
NES Palette
+
+
Use Custom Palette
+
Check or uncheck this to switch between default palette and currently loaded custom palette.
+
+
Load Palette
+
Allows you to load a custom color palette (.pal) file to use for the current game loaded.
+
+
A note on on the format of external palettes; Palette files are expected to contain 64 8-bit RGB triplets (each in that order; red comes first in the triplet in the file, then green, then blue). Each 8-bit value represents brightness for that particular color. 0 is minimum, 255 is maximum.
+
+
Palettes can be set on a per-game basis. To do this, put a palette file in the same directory the game is in, and add the extension "pal". Examples:
+
+
File name: Palette file name:
+
BigBad.nes BigBad.pal
+
BigBad.zip BigBad.pal
+
BigBad.Better.nes BigBad.Better.pal
+
+
+
With so many ways to choose a palette, figuring out which one will be active may be difficult. Here's a list of what palettes will be used, in order from highest priority to least priority(if a condition doesn't exist for a higher priority palette, the emulator will continue down its list of palettes).
+
+
* NSF Palette(for NSFs only)
+
* Palette loaded from the "gameinfo" directory.
+
* NTSC Color Emulation(only for NTSC NES games).
+
* VS Unisystem palette(if the game is a VS Unisystem game and a palette is available).
+
* Custom global palette.
+
* Default NES palette.
+
+
Force Grayscale
+
Applies simple Grayscale filter, no matter what palette is currently used.
+
+
De-emphasis bit swap
+
Every PAL PPU has de-emphasis bits for green and red colors swapped. This option simulates that behavior.
+
+
+
NTSC Color Emulation
+
+
If enabled, FCEUX will simulate actual NTSC signal processing. The result should be the actual colors you would see if outputting to an actual NTSC television.
+
+
The Tint and Hue knobs can be used to make adjustments to the resulting color change.
This is the default palette that FCEUX uses. It is the same palette used in FCEU.12 or earlier, and FCEUD/FCEUXD/FCEUXDSP.
-
-
FCEU-13-default_nitsuja.pal
-
-
This is the palette added to FCEU.13 rerecording by Nitsuja.
-
-
FCEU-15-nitsuja-new.pal
-
-
This is the palette added to FCEU.15 rerecording by Nitsuja. It is a slight adjustment to the FCEU.13 palette.
-
-
NESTOPIA_RGB.pal & NESTOPIA_YUV.pal
-
-
Default palettes of Nestopia.
-
-
BMF_final2.pal & BMF_final3.pal
-
-
These palettes were designed by BMF. He customized these by looking at snapshots of his television screen and attempting to replicate them as close as possible.
-
-
ASQ_realityA.pal & ASQ_realityB.pal
-
-
BMF palettes had some flaws. AspiringSquire tweaked BMF's palettes and came up with this. They fix issues mostly related to brightness.
-
-
SONY_CXA2025AS_US.pal
-
-
This palette is based on the CXA2025AS integrated circuit used in Sony TV-sets.
-
-
Unsaturated-V6.pal
-
-
This palette by FirebrandX offers a more realistic brightness/contrast scale of the original console. It was developed using a direct-capture device hooked up to the NES, then error-corrected to the current and final 6th version.
This is the default palette that FCEUX uses. It is the same palette used in FCEU.12 or earlier, and FCEUD/FCEUXD/FCEUXDSP.
+
+
FCEU-13-default_nitsuja.pal
+
+
This is the palette added to FCEU.13 rerecording by Nitsuja.
+
+
FCEU-15-nitsuja-new.pal
+
+
This is the palette added to FCEU.15 rerecording by Nitsuja. It is a slight adjustment to the FCEU.13 palette.
+
+
NESTOPIA_RGB.pal & NESTOPIA_YUV.pal
+
+
Default palettes of Nestopia.
+
+
BMF_final2.pal & BMF_final3.pal
+
+
These palettes were designed by BMF. He customized these by looking at snapshots of his television screen and attempting to replicate them as close as possible.
+
+
ASQ_realityA.pal & ASQ_realityB.pal
+
+
BMF palettes had some flaws. AspiringSquire tweaked BMF's palettes and came up with this. They fix issues mostly related to brightness.
+
+
SONY_CXA2025AS_US.pal
+
+
This palette is based on the CXA2025AS integrated circuit used in Sony TV-sets.
+
+
Unsaturated-V6.pal
+
+
This palette by FirebrandX offers a more realistic brightness/contrast scale of the original console. It was developed using a direct-capture device hooked up to the NES, then error-corrected to the current and final 6th version.
It is designed to filter RAM values just like in the Cheat Search dialog. However, it features many options that are lacking in the Cheat Search dialog. Among these are search undo, search preview, a modulus filter, a data size option, signed/unsigned/hex options, autosearch, and several more compare by options.
-
-
Documentation on this dialog can be found on TASVideos here.
-
-
Hotkeys
-
-
Hotkeys can be assigned to common search commands so they can be easily selected while in the main window.
It is designed to filter RAM values just like in the Cheat Search dialog. However, it features many options that are lacking in the Cheat Search dialog. Among these are search undo, search preview, a modulus filter, a data size option, signed/unsigned/hex options, autosearch, and several more compare by options.
+
+
Documentation on this dialog can be found on TASVideos here.
+
+
Hotkeys
+
+
Hotkeys can be assigned to common search commands so they can be easily selected while in the main window.
It is designed to filter ram values just like in the Cheat Search dialog. However, it features many options that are lacking in the Cheat Search dialog. Among these are search undo, search preview, a modulus filter, a data size option, signed/unsigned/hex options, autosearch, and several more compare by options.
-
-
Documentation on this dialog can be found on TASVideos here.
It is designed to filter ram values just like in the Cheat Search dialog. However, it features many options that are lacking in the Cheat Search dialog. Among these are search undo, search preview, a modulus filter, a data size option, signed/unsigned/hex options, autosearch, and several more compare by options.
+
+
Documentation on this dialog can be found on TASVideos here.
ROM Hacking is the process of modifying a video game ROM image to alter the game's graphics, dialogue, levels, gameplay, or other gameplay elements. This is usually done by technically-inclined video game fans to breathe new life into a cherished old game, as a creative outlet, or to make essentially new unofficial games using an old game as a foundation.
-
-
ROM hacking is generally accomplished through use of a hex editor (a program for editing non-textual data) and various specialized tools such as tile editors, and game-specific tools which are generally used for editing levels, items, and the like, although more advanced tools such as assemblers and debuggers are occasionally used. Once ready, they are usually distributed on the Internet for others to play on an emulator.
FCEUX provides a wealth of tools and resources to aid in hacking NES & FDS games. It features the most current and cutting edge tools debugging and hacking games as well as making the process quicker an easier.
ROM Hacking is the process of modifying a video game ROM image to alter the game's graphics, dialogue, levels, gameplay, or other gameplay elements. This is usually done by technically-inclined video game fans to breathe new life into a cherished old game, as a creative outlet, or to make essentially new unofficial games using an old game as a foundation.
+
+
ROM hacking is generally accomplished through use of a hex editor (a program for editing non-textual data) and various specialized tools such as tile editors, and game-specific tools which are generally used for editing levels, items, and the like, although more advanced tools such as assemblers and debuggers are occasionally used. Once ready, they are usually distributed on the Internet for others to play on an emulator.
FCEUX provides a wealth of tools and resources to aid in hacking NES & FDS games. It features the most current and cutting edge tools debugging and hacking games as well as making the process quicker an easier.
The sound enabled/disabled checkbox will turn on/off FCEUX's sound.
-
The force 8-bit sound checkbox will override the current sound configuration and use 8-bit sound instead.
-
-
You can select the sound quality in the sound quality pull down menu.
-
-
Rate sets the audio sample rate.
-
-
-
Mute frame advance
-
-
If checked, no sound will be produce when frame advance is pressed.
-
-
Mute Turbo
-
-
If checked, the sound processing will be bypassed when emulation is in turbo mode
-
-
Swap Duty Cycles
-
-
If checked, replicates the behavior of some famiclones that have duty cycles swapped for square channels.
-
-
Buffering
-
-
On older machines, increased buffering may be necessary. If the sound is glitchy or crackling, increasing the buffing time may resolve the issue. Lower buffering settings can reduce sound latency.
-
-
Volume Control
-
-
Sets the sound volume of the master sound or individual sound channels.
-
-
Master
-
-
Sets the Master volume level. You can also set volume levels using the sound volume up, volume down, mute, and volume normal hotkeys under map hotkeys menu.
-
-
Triangle/Square 1/Square 2/Noise/PCM
-
-
Sets the volume to each individual sound channel.
-
-
Note: When using low quality sound, the amount of channel control is greatly limited. Some sound channels are disabled.
-
-
Restore Defaults
-
-
Restores the master and individual sound channel volumes to their default location.
The sound enabled/disabled checkbox will turn on/off FCEUX's sound.
+
The force 8-bit sound checkbox will override the current sound configuration and use 8-bit sound instead.
+
+
You can select the sound quality in the sound quality pull down menu.
+
+
Rate sets the audio sample rate.
+
+
+
Mute frame advance
+
+
If checked, no sound will be produce when frame advance is pressed.
+
+
Mute Turbo
+
+
If checked, the sound processing will be bypassed when emulation is in turbo mode
+
+
Swap Duty Cycles
+
+
If checked, replicates the behavior of some famiclones that have duty cycles swapped for square channels.
+
+
Buffering
+
+
On older machines, increased buffering may be necessary. If the sound is glitchy or crackling, increasing the buffing time may resolve the issue. Lower buffering settings can reduce sound latency.
+
+
Volume Control
+
+
Sets the sound volume of the master sound or individual sound channels.
+
+
Master
+
+
Sets the Master volume level. You can also set volume levels using the sound volume up, volume down, mute, and volume normal hotkeys under map hotkeys menu.
+
+
Triangle/Square 1/Square 2/Noise/PCM
+
+
Sets the volume to each individual sound channel.
+
+
Note: When using low quality sound, the amount of channel control is greatly limited. Some sound channels are disabled.
+
+
Restore Defaults
+
+
Restores the master and individual sound channel volumes to their default location.
TAS Editor is an overhaul in the logic of creating TAS movies (see Tool Assisted Speedruns). It is a powerful new design that takes movie making from a "recording" concept to a "creating an input file" way of thinking.
-
-
In the 2.2.0 release the TAS Editor was completely redesigned and rewritten, incorporating new experimental ideas.
TAS Editor is an overhaul in the logic of creating TAS movies (see Tool Assisted Speedruns). It is a powerful new design that takes movie making from a "recording" concept to a "creating an input file" way of thinking.
+
+
In the 2.2.0 release the TAS Editor was completely redesigned and rewritten, incorporating new experimental ideas.
(written by Ugly Joe, author of the Text Hooker tool)
-
-
-
What is Text Hooker?
-
-
Here's a premise for you. Suppose you've pirated a bunch of Japanese NES roms and you load one of them up at random. Cool music. Cool title screen. You go to start a game, put in ???? at the name entry screen, and get to the actual game. Well, big surprise here, it's an RPG. You soon realize that you have no idea what people are saying, what shops are selling, or what your battle options are. It can be fun to trial-and-error for a while, but you're ultimately stuck in the first town. Time to load up a new ROM.
-
-
Well, being the aspiring Japanophile that I am, I have all kinds of translation tools and websites at my disposal. It's not impossible for me to figure out the kana for an item name, put it into a website somewhere, and figure out what it is. It's a slow process, but I can figure out short, simple strings of Japanese text. Sometimes, this is all I need to know to get by.
-
-
This is why I made the Text Hooker. What it allows you to do is highlight text boxes in the game and copy the kana right to the clipboard. I no longer have to look up stuff, I can just copy from the emulator, paste into the website, and go from there. While developing it, I took it a bit further by adding a (shoddy) translator right into the app, and added features such as word substitutions (so you only have to look up the word once and then the app will know what it is as soon as you copy it). What you end up with is kind of like a translator's notebook. It keeps commonly used words in a dictionary and helps you get through a Japanese game without having too much knowledge of the Japanese language.
-
-
-
What do I need to use to use it?
-
-
Some knowledge of the Japanese language
-
I really can't say how much you need to know, but I suppose the more you know the better. I could be wrong, but I think you need to know at least something about the language before you can start copy/pasting translations.
-
-
Know how to make a Japanese table file
-
I'm not going to explain how to do this since there are adequate tutorials already out there. You'll need to be able to do this per game in order for the Text Hooker to work.
-
-
Japanese font support
-
Okay, I have tested this thing on a Win98 installation with no Japanese font. It still works. However, I didn't test it for very long and I'm not sure how well translation websites are going to work without it. So, it might work without Japanese font support, but I'm not officially saying it does.
-
-
A Japanese ROM
-
Duh, you'll need a game to play. Find it yourself.
-
-
-
How do I use the Text Hooker?
-
-
First of all, you need to make your table file. The text hooker doesn't use Thingy tables, but uses a modified Thingy table instead. So, make your standard Thingy table file, but save it with a .tht extension (instead of .tbl). What you need to add to the table are the dakuten and handakuten marks (tenten and maru). The byte for the dakuten mark needs to be set to tenten and the byte for the handakuten mark needs to be set to tenten. Like:
-
-
DC=tenten
-
DD=maru
-
-
If you don't do this, the Text Hooker will fail miserabley when copying the text over from the game.
-
-
Once you have your table file ready, open up your rom in FCEUXDSP CE and open the text hooker window (Tools -> Text Hooker). Click on the "Load Table" button and open up your .tht file. Now you can really get ready to work.
-
-
Basic Usage
-
-
A warning
-
All information is saved in the table file. You have to save your table manually using the Save Table button. If you close the Text Hooker window or load a different table, your changes since the last save will be lost. You will not be prompted to save changes. Please remember to save!
-
-
Making Selections
-
The Selection Window is where you select the text in the game. It is basically the same view as the actual emulator window, but it updates less often and does not show sprites (text is not drawn with sprites, so they are not needed). To make a selection, click on a deselected tile and drag your mouse. To remove a selection, click on a selected tile and drag your mouse. It works a lot like a pen tool and an eraser tool in standard paint programs.
-
-
Once you have made a selection, you can save it for later use. This comes in handy since most RPGs will display their text boxes and battle menus in the same place throughout the entire game. To save a selection, type a name for the selection into the New Selection Name field and press the Save Selection button. Note that this selection will not be saved to your table file until you press the Save Table button.
-
-
You can also use the Clear Selection button to deselect all of the tiles in the selection window.
-
-
Please note that when you select text, you should not select the mostly blank rows that contains the dakuten and handakuten marks. You're essentially selecting every other row. Please see the UI image above for an example.
-
-
Translating Text
-
Once you've made a selection, press the big Snap button to copy the text into the Hooked Text window. Only the tiles that are defined in your table file will be copied over. All other tiles will be ignored. Once you have some Japanese text in your Hooked Text window, you have a few options. You can press the Excite.co.jp button to receive a really bad translation (better than Babelfish, but still bad) in the Translated Text window, or you can select all or part of the text in the Hooked Text window and copy/paste it into another translation tool or website. If you're translating a block of text (as opposed to item names or menus), you should probably use the Trim button to clean up the excess whitespace.
-
-
Please bear in mind that, due to the limitations of the NES, Japenese games use very little kanji. This means you'll have to look up the kana representation of what would normally be a kanji. Most translation tools will give you a hard time about this.
-
-
The word substitution feature can be used to process the selected text before it is sent to the Hooked Text window. By entering in Japanese-to-English definitions, you build up your word subs dictionary. If word subs are enabled and you press the snap button, the selected text is checked against your dictionary and any words that it finds are replaced by their definition.
-
-
This is useful for a few reason. One, many words written in katakana don't translate too well. You can use this to stop the translators from mangling them. Two, character names are often the same thing as words. For example, if your character's name is ??? (Sakura), the translator will likely translate it to “cherry blossom”. If you define ??? as Sakura, then you won't have to worry about that. Three, you only really need to translate menus and items once. Once you have them figured out, add them to your dictionary. This way, you can just select your menu (perhaps from a saved selection?) and press Snap -- instant menu translation! Four, I'm not positive about this, but if you know that a string of kana is going to always mean a particular kanji, you could put the kana in the Japanese side and the kanji in the English side. This would aid translators since it wouldn't have to try and figure it out itself. Note that I haven't tested that last one since I don't know enough kanji to put it to the test.
-
-
Again, please remember that your dictionary will not be saved unless you use the Save Table button.
-
-
Tweaking
-
Here are some other helpful features.
-
-
Pause Button: this is used to pause and unpause the emulator.
-
-
Scanline: this is used to determine on what scanline the Selection Window will be updated. Some games will switch their font tiles in and out of the PPU. If this happens, you may need to change the scanline to a bigger number in order to see the tiles you're looking for. For example, this happens a lot in the game Metal Slader Glory.
-
-
Update every x frames: this is used to determine how often the Selection Window is updated. The smaller the number, the slower the emulator will go.
-
-
Selection Window checkbox: this is used to determine whether or not the selection window should be updated. If you're not going to be needing the Text Hooker for a while, you should probably uncheck this box while you play.
-
-
Word Substitution checkbox: this is used to determine whether or not word substitution will be used.
-
-
(han)dakuten mark position checkbox: this is used to tell the text hooker where the dakuten and handakuten marks are located in relation to the kana. Most games will use Above, but some games that try to squeeze in as much text into a small area as possible will use Right.
-
Features > Text Hooker > Reference
-
Features > Text Hooker > Reference > Text Hooker Table file reference
-
I suppose this is the kind of thing that should be documented, so here it is. When I started to make this thing, I was just using Thingy tables. When I started to add other features, I knew I needed to save them somewhere. It seemed kind of dumb to me to store this information in separate files, so I decided I would append the other sections to the end of the table files. In the far off chance that there becomes some kind of archive for Text Hooker table files, I decided to use a different extension.
-
-
A .tht file is comprised of three parts (and possibly more in the future). The first part resembles a Thingy table, since it's more or less that same thing. You have a hex byte value, and equals sign, and the corresponding character after the equals sign. The biggest difference from Thingy tables is that the tenten and maru marks must be defined using the words tenten and maru.
-
-
The next section is the Selections storage. This section begins with a
-
-
[selections]
-
-
declaration. What follows are hashes for saved selections (name of selection, equals sign, hash). The hashes should be safe for viewing and saving in any text editor that is capable of viewing and saving Japanese text. These hashes are, admittedly, under tested. If anyone can find a situation in which the selection hashes are corrupted but the rest of the table file is not, please let me know.
-
-
Up next is the Word Substitution Dictionary. This section begins with a
-
-
[words]
-
-
declaration. These lines are formatted in a Japanese=English manner. You should be able to have Japanese or English on either or both sides. It's nothing more than a list of values used during a search and replace function.
(written by Ugly Joe, author of the Text Hooker tool)
+
+
+
What is Text Hooker?
+
+
Here's a premise for you. Suppose you've pirated a bunch of Japanese NES roms and you load one of them up at random. Cool music. Cool title screen. You go to start a game, put in ???? at the name entry screen, and get to the actual game. Well, big surprise here, it's an RPG. You soon realize that you have no idea what people are saying, what shops are selling, or what your battle options are. It can be fun to trial-and-error for a while, but you're ultimately stuck in the first town. Time to load up a new ROM.
+
+
Well, being the aspiring Japanophile that I am, I have all kinds of translation tools and websites at my disposal. It's not impossible for me to figure out the kana for an item name, put it into a website somewhere, and figure out what it is. It's a slow process, but I can figure out short, simple strings of Japanese text. Sometimes, this is all I need to know to get by.
+
+
This is why I made the Text Hooker. What it allows you to do is highlight text boxes in the game and copy the kana right to the clipboard. I no longer have to look up stuff, I can just copy from the emulator, paste into the website, and go from there. While developing it, I took it a bit further by adding a (shoddy) translator right into the app, and added features such as word substitutions (so you only have to look up the word once and then the app will know what it is as soon as you copy it). What you end up with is kind of like a translator's notebook. It keeps commonly used words in a dictionary and helps you get through a Japanese game without having too much knowledge of the Japanese language.
+
+
+
What do I need to use to use it?
+
+
Some knowledge of the Japanese language
+
I really can't say how much you need to know, but I suppose the more you know the better. I could be wrong, but I think you need to know at least something about the language before you can start copy/pasting translations.
+
+
Know how to make a Japanese table file
+
I'm not going to explain how to do this since there are adequate tutorials already out there. You'll need to be able to do this per game in order for the Text Hooker to work.
+
+
Japanese font support
+
Okay, I have tested this thing on a Win98 installation with no Japanese font. It still works. However, I didn't test it for very long and I'm not sure how well translation websites are going to work without it. So, it might work without Japanese font support, but I'm not officially saying it does.
+
+
A Japanese ROM
+
Duh, you'll need a game to play. Find it yourself.
+
+
+
How do I use the Text Hooker?
+
+
First of all, you need to make your table file. The text hooker doesn't use Thingy tables, but uses a modified Thingy table instead. So, make your standard Thingy table file, but save it with a .tht extension (instead of .tbl). What you need to add to the table are the dakuten and handakuten marks (tenten and maru). The byte for the dakuten mark needs to be set to tenten and the byte for the handakuten mark needs to be set to tenten. Like:
+
+
DC=tenten
+
DD=maru
+
+
If you don't do this, the Text Hooker will fail miserabley when copying the text over from the game.
+
+
Once you have your table file ready, open up your rom in FCEUXDSP CE and open the text hooker window (Tools -> Text Hooker). Click on the "Load Table" button and open up your .tht file. Now you can really get ready to work.
+
+
Basic Usage
+
+
A warning
+
All information is saved in the table file. You have to save your table manually using the Save Table button. If you close the Text Hooker window or load a different table, your changes since the last save will be lost. You will not be prompted to save changes. Please remember to save!
+
+
Making Selections
+
The Selection Window is where you select the text in the game. It is basically the same view as the actual emulator window, but it updates less often and does not show sprites (text is not drawn with sprites, so they are not needed). To make a selection, click on a deselected tile and drag your mouse. To remove a selection, click on a selected tile and drag your mouse. It works a lot like a pen tool and an eraser tool in standard paint programs.
+
+
Once you have made a selection, you can save it for later use. This comes in handy since most RPGs will display their text boxes and battle menus in the same place throughout the entire game. To save a selection, type a name for the selection into the New Selection Name field and press the Save Selection button. Note that this selection will not be saved to your table file until you press the Save Table button.
+
+
You can also use the Clear Selection button to deselect all of the tiles in the selection window.
+
+
Please note that when you select text, you should not select the mostly blank rows that contains the dakuten and handakuten marks. You're essentially selecting every other row. Please see the UI image above for an example.
+
+
Translating Text
+
Once you've made a selection, press the big Snap button to copy the text into the Hooked Text window. Only the tiles that are defined in your table file will be copied over. All other tiles will be ignored. Once you have some Japanese text in your Hooked Text window, you have a few options. You can press the Excite.co.jp button to receive a really bad translation (better than Babelfish, but still bad) in the Translated Text window, or you can select all or part of the text in the Hooked Text window and copy/paste it into another translation tool or website. If you're translating a block of text (as opposed to item names or menus), you should probably use the Trim button to clean up the excess whitespace.
+
+
Please bear in mind that, due to the limitations of the NES, Japenese games use very little kanji. This means you'll have to look up the kana representation of what would normally be a kanji. Most translation tools will give you a hard time about this.
+
+
The word substitution feature can be used to process the selected text before it is sent to the Hooked Text window. By entering in Japanese-to-English definitions, you build up your word subs dictionary. If word subs are enabled and you press the snap button, the selected text is checked against your dictionary and any words that it finds are replaced by their definition.
+
+
This is useful for a few reason. One, many words written in katakana don't translate too well. You can use this to stop the translators from mangling them. Two, character names are often the same thing as words. For example, if your character's name is ??? (Sakura), the translator will likely translate it to “cherry blossom”. If you define ??? as Sakura, then you won't have to worry about that. Three, you only really need to translate menus and items once. Once you have them figured out, add them to your dictionary. This way, you can just select your menu (perhaps from a saved selection?) and press Snap -- instant menu translation! Four, I'm not positive about this, but if you know that a string of kana is going to always mean a particular kanji, you could put the kana in the Japanese side and the kanji in the English side. This would aid translators since it wouldn't have to try and figure it out itself. Note that I haven't tested that last one since I don't know enough kanji to put it to the test.
+
+
Again, please remember that your dictionary will not be saved unless you use the Save Table button.
+
+
Tweaking
+
Here are some other helpful features.
+
+
Pause Button: this is used to pause and unpause the emulator.
+
+
Scanline: this is used to determine on what scanline the Selection Window will be updated. Some games will switch their font tiles in and out of the PPU. If this happens, you may need to change the scanline to a bigger number in order to see the tiles you're looking for. For example, this happens a lot in the game Metal Slader Glory.
+
+
Update every x frames: this is used to determine how often the Selection Window is updated. The smaller the number, the slower the emulator will go.
+
+
Selection Window checkbox: this is used to determine whether or not the selection window should be updated. If you're not going to be needing the Text Hooker for a while, you should probably uncheck this box while you play.
+
+
Word Substitution checkbox: this is used to determine whether or not word substitution will be used.
+
+
(han)dakuten mark position checkbox: this is used to tell the text hooker where the dakuten and handakuten marks are located in relation to the kana. Most games will use Above, but some games that try to squeeze in as much text into a small area as possible will use Right.
+
Features > Text Hooker > Reference
+
Features > Text Hooker > Reference > Text Hooker Table file reference
+
I suppose this is the kind of thing that should be documented, so here it is. When I started to make this thing, I was just using Thingy tables. When I started to add other features, I knew I needed to save them somewhere. It seemed kind of dumb to me to store this information in separate files, so I decided I would append the other sections to the end of the table files. In the far off chance that there becomes some kind of archive for Text Hooker table files, I decided to use a different extension.
+
+
A .tht file is comprised of three parts (and possibly more in the future). The first part resembles a Thingy table, since it's more or less that same thing. You have a hex byte value, and equals sign, and the corresponding character after the equals sign. The biggest difference from Thingy tables is that the tenten and maru marks must be defined using the words tenten and maru.
+
+
The next section is the Selections storage. This section begins with a
+
+
[selections]
+
+
declaration. What follows are hashes for saved selections (name of selection, equals sign, hash). The hashes should be safe for viewing and saving in any text editor that is capable of viewing and saving Japanese text. These hashes are, admittedly, under tested. If anyone can find a situation in which the selection hashes are corrupted but the rest of the table file is not, please let me know.
+
+
Up next is the Word Substitution Dictionary. This section begins with a
+
+
[words]
+
+
declaration. These lines are formatted in a Japanese=English manner. You should be able to have Japanese or English on either or both sides. It's nothing more than a list of values used during a search and replace function.
Disable Speed Throttling Used When Sound is Disabled
-
-
If checked, speed throttling will not be used while sound is disabled. (Speed throttling gives a performance boost while sound is off).
-
-
Set High Priority Thread
-
-
Sets processing priority. Enabling can help slower computers keep a steady 60fps (or 50fps) framerate.
-
-
Overclocking (old PPU only)
-
-
Overclocks the console by adding dummy scanlines to the usual PPU loop, causing CPU to run more cycles per frame. Can be done in two different ways: by adding Post-render scanlines and by adding Vblank scanlines. The method to be used depends on the game. Maximum value is 999.
-
-
Don't overclock 7-bit samples
-
-
Such samples are played by the game at the rate it wants, so by running extra cycles, it will generate extra samples. To prevent those from being sped up, this option allows to cancel all the dummy scanlines once a 7-bit sample starts. This hardly affects gameplay, since such samples cause heavy lag, preventing the game from actually operating, so disabling overclocking during them won't slow the game down.
Disable Speed Throttling Used When Sound is Disabled
+
+
If checked, speed throttling will not be used while sound is disabled. (Speed throttling gives a performance boost while sound is off).
+
+
Set High Priority Thread
+
+
Sets processing priority. Enabling can help slower computers keep a steady 60fps (or 50fps) framerate.
+
+
Overclocking (old PPU only)
+
+
Overclocks the console by adding dummy scanlines to the usual PPU loop, causing CPU to run more cycles per frame. Can be done in two different ways: by adding Post-render scanlines and by adding Vblank scanlines. The method to be used depends on the game. Maximum value is 999.
+
+
Don't overclock 7-bit samples
+
+
Such samples are played by the game at the rate it wants, so by running extra cycles, it will generate extra samples. To prevent those from being sped up, this option allows to cancel all the dummy scanlines once a 7-bit sample starts. This hardly affects gameplay, since such samples cause heavy lag, preventing the game from actually operating, so disabling overclocking during them won't slow the game down.
Explains the various toggle switch commands in the top two groups of commands under the Config Menu.
-
-
-
Hide Menu
-
-
Hides the Menu commands on the FCEUX main window. Press ESC to unhide the menu.
-
-
-
Region
-
-
Allows to choose between NTSC (224p@60fps), PAL and Dendy (240p@50fps) modes. For PAL, FCEUX will detect the proper choice when loading a ROM and set the flag accordingly (based on file name, where (E) is used by GoodTools to mark European ROMs). Dendy mode (sometimes also called Hybrid) is a modification of the NTSC one, it was used in some Famiclones and supports games released for the NTSC region, slowing them down to PAL speed.
-
Note: you can't change this setting while a movie is being played or recorded.
-
-
-
PPU (Sub-menu)
-
-
New PPU / Old PPU
-
As of FCEUX 2.1.2, FCEUX has a new PPU core. The new PPU has improved accuracy and greater game compatibility than the old PPU. However, some games may not work properly and there will be slight timing differences that would hurt movie compatibility. Also then New PPU is much slower than the Old PPU. Therefore, the old PPU is still the preferred setting.
-
Note: you can't change this setting while a movie is being played or recorded.
-
-
-
Enable (Sub-menu)
-
-
Run in Background
-
-
If enabled, FCEUX will continue to emulate when the window is not in focus. If disabled, the emulator will pause when out of focus.
-
-
-
Background Input
-
-
If enabled, FCEUX can continue to receive input while not in focus. (Useful for playing 2 FCEUX's simultaneously)
-
-
-
Auto-savestates
-
-
Enables the Auto-save feature. If enabled, FCEUX will make periodic savestates (once per every 256 frames) as you play or record a movie. You can right-click and select the "load last auto-save" in the context menu or press "Load Last Auto-save" hotkey to back up to the last auto-save savestate.
-
-
-
Frame Adv. - Skip Lag
-
-
This feature, if enabled, will cause the frame advance key (see movie recording) to skip over lag frames. It does this by reading the lag counter and skipping past any frames where input is not polled.
-
-
For instance, in a 30fps game (such as double dragon), frame advance will advance 2 frames instead of 1.
-
-
-
Backup Savestates
-
-
Enabled by default. This option allows for savestate & loadstate Undo (& redo). (see context menu)
-
-
-
Compress Savestates
-
-
Enabled by default. This option compresses non movie savestates.
-
-
-
Game Genie ROM
-
-
Allows the use of the game genie ROM. You must have a game genie ROM named gg.rom (it is safe to rename a game genie.nes file to gg.rom) and it must be in the FCEUX base directory (which is the folder fceux.exe is in unless you specified a different folder in the Directory Override Menu).
-
-
If enabled, FCEUX will open gg.rom first when you load a new game. Any codes applied in the game genie screen will be applied to the game just like on a real NES.
-
-
(Remember that enabling/disabling Game Genie emulation will not take effect until a new game is loaded)
If enabled, FCEUX will make a special savestate every time you close ROM, and will automatically load the savestate when you open this ROM next time, so you can continue from where you left the game. In addition, when this option is enabled, FCEUX automatically loads the last used ROM on startup.
-
-
-
Display (Sub-Menu)
-
-
Input Display
-
-
The input display will display 1-4 pictures of a NES controller at the bottom of the screen. When playing/recording a movie, these controllers will display the input that is captured in the file.
-
-
When input comes from a movie file rather than then user, it is displayed in a different color (silver)
-
-
The input display can also be toggled by hotkey. The default key for toggling the Input display is the "," (comma) key. (This can be re-mapped in the Map Hotkeys Menu).
-
-
-
Lag Counter
-
-
The lag counter will increment every time to the game fails to poll for user input. It will display in red on any frame that is currently lagging and will increment the lag counter by 1. These situations occur when the game is lagging (too much information to process), or the game is in a screen transition state (so not polling for user input). In a 30fps game (such as Double Dragon 2), it will increment every other frame.
-
-
The lag counter value is stored in savestates.
-
-
Displaying the lag counter can also be toggled by hotkey. The default key is the "/" (slash) key. (This can be re-mapped in the Map Hokeys Menu).
-
-
-
Frame Counter
-
-
Toggles the display of the frame counter. The frame counter will increment once per frame.
-
-
The frame counter display can also be toggled by hotkey. The default key is the "." (period) key. (This can be re-mapped in the Map Hotkeys Menu).
-
-
-
Rerecord Counter
-
-
Toggles the display of the number of Rerecords done when making a movie. The Rerecord counter will increment every time you load a savestate in Recording mode.
-
-
The rerecord counter display can also be toggled by hotkey. The default key is the "M" key. (This can be re-mapped in the Map Hotkeys Menu).
-
-
-
Movie status icon
-
-
Toggles the display of "pause", "play" or "record" icons in the lower right corner.
-
-
-
FPS
-
-
Toggles the display of average FPS counter in the upper right corner.
-
-
-
Graphics: BG
-
-
Turning this off will turn off the backgrounds in the game.
-
-
-
Graphics: OBJ
-
-
Turning this off will turn off the objects (sprites) in the game.
-
-
Note: You can set the default color when the Backgrounds are turned off. To do so, open fceux.cfg and change the value of the entry named: gNoBGFillColor
-
-
-
Save Config File
-
-
Saves current settings to fceux.cfg. Normally settings are not saved until FCEUX is closed.
Explains the various toggle switch commands in the top two groups of commands under the Config Menu.
+
+
+
Hide Menu
+
+
Hides the Menu commands on the FCEUX main window. Press ESC to unhide the menu.
+
+
+
Region
+
+
Allows to choose between NTSC (224p@60fps), PAL and Dendy (240p@50fps) modes. For PAL, FCEUX will detect the proper choice when loading a ROM and set the flag accordingly (based on file name, where (E) is used by GoodTools to mark European ROMs). Dendy mode (sometimes also called Hybrid) is a modification of the NTSC one, it was used in some Famiclones and supports games released for the NTSC region, slowing them down to PAL speed.
+
Note: you can't change this setting while a movie is being played or recorded.
+
+
+
PPU (Sub-menu)
+
+
New PPU / Old PPU
+
As of FCEUX 2.1.2, FCEUX has a new PPU core. The new PPU has improved accuracy and greater game compatibility than the old PPU. However, some games may not work properly and there will be slight timing differences that would hurt movie compatibility. Also then New PPU is much slower than the Old PPU. Therefore, the old PPU is still the preferred setting.
+
Note: you can't change this setting while a movie is being played or recorded.
+
+
+
Enable (Sub-menu)
+
+
Run in Background
+
+
If enabled, FCEUX will continue to emulate when the window is not in focus. If disabled, the emulator will pause when out of focus.
+
+
+
Background Input
+
+
If enabled, FCEUX can continue to receive input while not in focus. (Useful for playing 2 FCEUX's simultaneously)
+
+
+
Auto-savestates
+
+
Enables the Auto-save feature. If enabled, FCEUX will make periodic savestates (once per every 256 frames) as you play or record a movie. You can right-click and select the "load last auto-save" in the context menu or press "Load Last Auto-save" hotkey to back up to the last auto-save savestate.
+
+
+
Frame Adv. - Skip Lag
+
+
This feature, if enabled, will cause the frame advance key (see movie recording) to skip over lag frames. It does this by reading the lag counter and skipping past any frames where input is not polled.
+
+
For instance, in a 30fps game (such as double dragon), frame advance will advance 2 frames instead of 1.
+
+
+
Backup Savestates
+
+
Enabled by default. This option allows for savestate & loadstate Undo (& redo). (see context menu)
+
+
+
Compress Savestates
+
+
Enabled by default. This option compresses non movie savestates.
+
+
+
Game Genie ROM
+
+
Allows the use of the game genie ROM. You must have a game genie ROM named gg.rom (it is safe to rename a game genie.nes file to gg.rom) and it must be in the FCEUX base directory (which is the folder fceux.exe is in unless you specified a different folder in the Directory Override Menu).
+
+
If enabled, FCEUX will open gg.rom first when you load a new game. Any codes applied in the game genie screen will be applied to the game just like on a real NES.
+
+
(Remember that enabling/disabling Game Genie emulation will not take effect until a new game is loaded)
If enabled, FCEUX will make a special savestate every time you close ROM, and will automatically load the savestate when you open this ROM next time, so you can continue from where you left the game. In addition, when this option is enabled, FCEUX automatically loads the last used ROM on startup.
+
+
+
Display (Sub-Menu)
+
+
Input Display
+
+
The input display will display 1-4 pictures of a NES controller at the bottom of the screen. When playing/recording a movie, these controllers will display the input that is captured in the file.
+
+
When input comes from a movie file rather than then user, it is displayed in a different color (silver)
+
+
The input display can also be toggled by hotkey. The default key for toggling the Input display is the "," (comma) key. (This can be re-mapped in the Map Hotkeys Menu).
+
+
+
Lag Counter
+
+
The lag counter will increment every time to the game fails to poll for user input. It will display in red on any frame that is currently lagging and will increment the lag counter by 1. These situations occur when the game is lagging (too much information to process), or the game is in a screen transition state (so not polling for user input). In a 30fps game (such as Double Dragon 2), it will increment every other frame.
+
+
The lag counter value is stored in savestates.
+
+
Displaying the lag counter can also be toggled by hotkey. The default key is the "/" (slash) key. (This can be re-mapped in the Map Hokeys Menu).
+
+
+
Frame Counter
+
+
Toggles the display of the frame counter. The frame counter will increment once per frame.
+
+
The frame counter display can also be toggled by hotkey. The default key is the "." (period) key. (This can be re-mapped in the Map Hotkeys Menu).
+
+
+
Rerecord Counter
+
+
Toggles the display of the number of Rerecords done when making a movie. The Rerecord counter will increment every time you load a savestate in Recording mode.
+
+
The rerecord counter display can also be toggled by hotkey. The default key is the "M" key. (This can be re-mapped in the Map Hotkeys Menu).
+
+
+
Movie status icon
+
+
Toggles the display of "pause", "play" or "record" icons in the lower right corner.
+
+
+
FPS
+
+
Toggles the display of average FPS counter in the upper right corner.
+
+
+
Graphics: BG
+
+
Turning this off will turn off the backgrounds in the game.
+
+
+
Graphics: OBJ
+
+
Turning this off will turn off the objects (sprites) in the game.
+
+
Note: You can set the default color when the Backgrounds are turned off. To do so, open fceux.cfg and change the value of the entry named: gNoBGFillColor
+
+
+
Save Config File
+
+
Saves current settings to fceux.cfg. Normally settings are not saved until FCEUX is closed.
A tool-assisted speedrun (commonly abbreviated TAS) is a speedrun movie or performance produced with the use of tools such as slow motion and re-recording. The basic premise of these runs is that a "tool" (such as an emulator that provides the author with features that are unavailable in regular playing) is used in order to overcome human limitations such as skill and reflex.
-
-
Creating a tool-assisted speed run is the process of finding the ideal set of inputs to complete a given criterion - usually completing a game as fast as possible. No limits are imposed on the tools used for this search, but the result has to be a set of timed key-presses that, when played back on the actual console, achieves the target criterion. Traditionally, the only available tool for this was an emulator with re-recording - the ability to use savestate while recording key-presses. However, due to advances in the field, it is now often expected that frame-advance, stepping through emulation one frame at a time, is used. A tool-assisted speed run done without this technique may be criticised as "sloppy play". Before Frame Advance became common, playing in slow motion was a common technique, but Frame Advance has displaced this.
-
-
In essence, Tool Assistance allows one to overcome human limitations of skill and reflex in order to push a game to its limits. One important thing to remember is that TAS movies are not competing in terms of playing skill, nor do they claim to.
FCEUX provides a wealth of tools and resources for creating TAS Movies for NES & FDS games. It features the most current and cutting edge tools for optimizing movies and making the process of movie making quicker an easier.
To get started making a Tool Assisted Movie, simply begin recording a movie (see Movie Recording). The basic premise of TASing, however, is to use re-records to optimize the execution of a decided upon goal (usually to complete the game as fast as possible). Re-recording is the act of replacing an already recorded part (of a movie) with something else; also called undo.
-
-
In the making of emulator movies, re-recording is done by loading a savestate of earlier event in the movie and continuing playing from that point. The emulator will update the movie file to undo everything that was cancelled by the savestate loading, and continue recording from that point. The makers of tool-assisted speedruns use re-recording very extensively to reach perfection and to avoid mistakes.
-
* In single-segment non-assisted speedruns, re-recording is starting over from beginning. The recording of the failed playing is usually not preserved.
-
* In multi-segment non-assisted speedruns, re-recording is starting over from the beginning of current segment. The recording of the failed segment is not preserved.
-
* In tool-assisted speedruns, re-recording only undoes a small part of playing. The undone part will not be seen in the resulting movie. A tool-assisted movie may have been re-recorded anything between 50 and 200000 times, depending on the precision of the movie and the difficulty of the game. Often, the same small passage of the game (could be as small as fractions of second long) is attempted tens of times before continuing.
A tool-assisted speedrun (commonly abbreviated TAS) is a speedrun movie or performance produced with the use of tools such as slow motion and re-recording. The basic premise of these runs is that a "tool" (such as an emulator that provides the author with features that are unavailable in regular playing) is used in order to overcome human limitations such as skill and reflex.
+
+
Creating a tool-assisted speed run is the process of finding the ideal set of inputs to complete a given criterion - usually completing a game as fast as possible. No limits are imposed on the tools used for this search, but the result has to be a set of timed key-presses that, when played back on the actual console, achieves the target criterion. Traditionally, the only available tool for this was an emulator with re-recording - the ability to use savestate while recording key-presses. However, due to advances in the field, it is now often expected that frame-advance, stepping through emulation one frame at a time, is used. A tool-assisted speed run done without this technique may be criticised as "sloppy play". Before Frame Advance became common, playing in slow motion was a common technique, but Frame Advance has displaced this.
+
+
In essence, Tool Assistance allows one to overcome human limitations of skill and reflex in order to push a game to its limits. One important thing to remember is that TAS movies are not competing in terms of playing skill, nor do they claim to.
FCEUX provides a wealth of tools and resources for creating TAS Movies for NES & FDS games. It features the most current and cutting edge tools for optimizing movies and making the process of movie making quicker an easier.
To get started making a Tool Assisted Movie, simply begin recording a movie (see Movie Recording). The basic premise of TASing, however, is to use re-records to optimize the execution of a decided upon goal (usually to complete the game as fast as possible). Re-recording is the act of replacing an already recorded part (of a movie) with something else; also called undo.
+
+
In the making of emulator movies, re-recording is done by loading a savestate of earlier event in the movie and continuing playing from that point. The emulator will update the movie file to undo everything that was cancelled by the savestate loading, and continue recording from that point. The makers of tool-assisted speedruns use re-recording very extensively to reach perfection and to avoid mistakes.
+
* In single-segment non-assisted speedruns, re-recording is starting over from beginning. The recording of the failed playing is usually not preserved.
+
* In multi-segment non-assisted speedruns, re-recording is starting over from the beginning of current segment. The recording of the failed segment is not preserved.
+
* In tool-assisted speedruns, re-recording only undoes a small part of playing. The undone part will not be seen in the resulting movie. A tool-assisted movie may have been re-recorded anything between 50 and 200000 times, depending on the precision of the movie and the difficulty of the game. Often, the same small passage of the game (could be as small as fractions of second long) is attempted tens of times before continuing.
The Trace Logger logs every executed instruction and every byte of ROM accessed to the window, or a file if you prefer. Logging to a file is useful if you just want to dump everything that was executed and then search through it later. Logging to the window is useful when you wish to see the instructions that were executed prior to a breakpoint being hit. Both options produce the same data, but the desire to keep that data for a short amount of time or a long amount of time will determine which is best for you.
-
-
-
Using the Trace Logger
-
-
The Trace Logger is a very nice feature which logs each instruction as it is being executed. If you choose to log to the window, you can set how many lines it will retain before discarding old lines. The higher this setting, the more RAM it will consume, but the more lines you'll have available to work with.
-
-
Normally, when logging to window, the Tracer only shows the log if you pause emulator by Pause or Frame Advance hotkey, or by snapping the Debugger. But there is the option to automatically update the log window while the game runs - this is normally useless, unless it is working with the Code/Data Logger to only show newly-executed instructions.
-
-
When the code is logged to window, you can browse it using mouse wheel or vertical scrollbar. Double-clicking any address in this window will bring the Debugger window at this address. Right-clicking any address allows you to label the address (see Symbolic Debug).
-
-
You can customize the format of text output in the log:
-
-
whether to log registers state for every instruction, and where to put the data in every text line (to the left or to the right from the code disassembly)
-
whether to log current frame number, cycles counter, instructions counter
-
whether to log emulator messages (such as "State 1 loaded")
-
whether to log Breakpoint Hits (when you use debugger while tracing)
-
whether to apply Symbolic Debug names when logging. See Debugger section for details
+
Trace Logger
+
+
Introduction
+
+
The Trace Logger logs every executed instruction and every byte of ROM accessed to the window, or a file if you prefer. Logging to a file is useful if you just want to dump everything that was executed and then search through it later. Logging to the window is useful when you wish to see the instructions that were executed prior to a breakpoint being hit. Both options produce the same data, but the desire to keep that data for a short amount of time or a long amount of time will determine which is best for you.
+
+
+
Using the Trace Logger
+
+
The Trace Logger is a very nice feature which logs each instruction as it is being executed. If you choose to log to the window, you can set how many lines it will retain before discarding old lines. The higher this setting, the more RAM it will consume, but the more lines you'll have available to work with.
+
+
Normally, when logging to window, the Tracer only shows the log if you pause emulator by Pause or Frame Advance hotkey, or by snapping the Debugger. But there is the option to automatically update the log window while the game runs - this is normally useless, unless it is working with the Code/Data Logger to only show newly-executed instructions.
+
+
When the code is logged to window, you can browse it using mouse wheel or vertical scrollbar. Double-clicking any address in this window will bring the Debugger window at this address. Right-clicking any address allows you to label the address (see Symbolic Debug).
+
+
You can customize the format of text output in the log:
+
+
whether to log registers state for every instruction, and where to put the data in every text line (to the left or to the right from the code disassembly)
+
whether to log current frame number, cycles counter, instructions counter
+
whether to log emulator messages (such as "State 1 loaded")
+
whether to log Breakpoint Hits (when you use debugger while tracing)
+
whether to apply Symbolic Debug names when logging. See Debugger section for details
-
-
For nice visualization of JSRs nesting you can use Stack Pointer for lines tabbing. Since NES games mostly use stack for subroutine calls (and rarely store variables in the stack), this option will likely produce a more readable disassembly. With this option you may also want to put registers data to the left from disassembly text, so they won't be tabbed.
-
-
The Trace Logger has extra options which work with the Code/Data Logger so that Tracer only shows instructions executed for the first time, or those which access data for the first time. This can be quite useful for finding certain key routines or finding otherwise impossible-to-find data in almost any game. The best way to use this feature is in conjunction with the option to automatically update the window while logging. Then, as you play the game, you can watch new results appear at once. If you're searching for something specific, first try to get everything (EXCEPT what you're looking for) to execute, then watch closely as what you're looking for executes for the first time.
-
-
There are two ways to filter what the Code/Data Logger shows. The first filter lets you log only newly-executed code (so that an instruction is not logged again if it has already been logged). The second logs only instructions when they access data which hadn't been accessed before. Note that both filters can be used at once (which shows bytes that pass either filter).
-
-
-
-
+
+
For nice visualization of JSRs nesting you can use Stack Pointer for lines tabbing. Since NES games mostly use stack for subroutine calls (and rarely store variables in the stack), this option will likely produce a more readable disassembly. With this option you may also want to put registers data to the left from disassembly text, so they won't be tabbed.
+
+
The Trace Logger has extra options which work with the Code/Data Logger so that Tracer only shows instructions executed for the first time, or those which access data for the first time. This can be quite useful for finding certain key routines or finding otherwise impossible-to-find data in almost any game. The best way to use this feature is in conjunction with the option to automatically update the window while logging. Then, as you play the game, you can watch new results appear at once. If you're searching for something specific, first try to get everything (EXCEPT what you're looking for) to execute, then watch closely as what you're looking for executes for the first time.
+
+
There are two ways to filter what the Code/Data Logger shows. The first filter lets you log only newly-executed code (so that an instruction is not logged again if it has already been logged). The second logs only instructions when they access data which hadn't been accessed before. Note that both filters can be used at once (which shows bytes that pass either filter).
This section describes potential problems/question that could arise when using FCEUX.
-
-
Slow emulation / Sound crackle
-
-
FCEUX may not run well on slow CPUs.
-
Ensure that you're using the Old PPU, because the New PPU engine is very slow. Check Config -> PPU -> Old PPU.
-
-
-
Sound crackle
-
-
If you enable hardware acceleration and Vsync (Wait for VBlank), and your monitor has a framerate different from 60FPS, you may experience minor sound cracle. This is a known issue and will probably be resolved in a future release.
-
-
-
Emulated picture is blurred (similar to the bilinear filter)
-
-
Try choosing different options in the "DirectDraw" list in the Video config dialog.
-
-
-
Slow savestates when recording movies
-
-
On slower computers, savestates can be slow with long movies. A small speedup can be done by disabling Config -> Enable -> Backup savestates.
-
-
-
The colors in game X do not look right!
-
-
There's no such thing as a universally right palette for NES games.
-
FCEUX uses the color palette of the old FCEU / FCEUXD branches. Also FCEUX comes pre-packaged with several additional color palettes. For more information see Palette config and Palette options.
-
-
-
I converted a .fcm file to .fm2, but the .fm2 desyncs
-
-
Depending on what version of FCEU / Game your .fcm was made, there maybe a number of sync issues. In addition, the .fm2 conversion tool has had some issues on certain operating systems including Vista and Mac. you can try using an external program for movie conversion.
-
-
-
Can't find FDS Bios image when I attempt to load a .fds game!
-
-
FCEUX requires the FDS Bios to be named disksys.rom. It must be located in the root directory (where fceux.exe is stored) or in the folder of the FDS Directory override (see Directory overrides).
-
-
In addition, there are some bad versions of disksys.rom. The one FDS requires is 8192 bytes in size.
-
-
-
How can I use Netplay / Where can I get FCEU Server?
-
-
Currently, the Windows version of FCEUX is barely compatible with the FCEU-server code. This is a known issue and will probably be resolved in a future release.
-
-
-
I have a Game Genie rom, how can I use it with FCEUX?
-
-
While FCEUX has a Game Genie code converter, you can also use game genie codes with an old-school Game Genie ROM. It must be named gg.rom and must be placed in the root directory (where fceux.exe is stored). You must also check Config->Enable->Game Genie ROM in the main menu. Then the Game Genie ROM will activate every time you open a ROM, so you can enter GG codes letter-by-letter like they did in the past.
This section describes potential problems/question that could arise when using FCEUX.
+
+
Slow emulation / Sound crackle
+
+
FCEUX may not run well on slow CPUs.
+
Ensure that you're using the Old PPU, because the New PPU engine is very slow. Check Config -> PPU -> Old PPU.
+
+
+
Sound crackle
+
+
If you enable hardware acceleration and Vsync (Wait for VBlank), and your monitor has a framerate different from 60FPS, you may experience minor sound cracle. This is a known issue and will probably be resolved in a future release.
+
+
+
Emulated picture is blurred (similar to the bilinear filter)
+
+
Try choosing different options in the "DirectDraw" list in the Video config dialog.
+
+
+
Slow savestates when recording movies
+
+
On slower computers, savestates can be slow with long movies. A small speedup can be done by disabling Config -> Enable -> Backup savestates.
+
+
+
The colors in game X do not look right!
+
+
There's no such thing as a universally right palette for NES games.
+
FCEUX uses the color palette of the old FCEU / FCEUXD branches. Also FCEUX comes pre-packaged with several additional color palettes. For more information see Palette config and Palette options.
+
+
+
I converted a .fcm file to .fm2, but the .fm2 desyncs
+
+
Depending on what version of FCEU / Game your .fcm was made, there maybe a number of sync issues. In addition, the .fm2 conversion tool has had some issues on certain operating systems including Vista and Mac. you can try using an external program for movie conversion.
+
+
+
Can't find FDS Bios image when I attempt to load a .fds game!
+
+
FCEUX requires the FDS Bios to be named disksys.rom. It must be located in the root directory (where fceux.exe is stored) or in the folder of the FDS Directory override (see Directory overrides).
+
+
In addition, there are some bad versions of disksys.rom. The one FDS requires is 8192 bytes in size.
+
+
+
How can I use Netplay / Where can I get FCEU Server?
+
+
Currently, the Windows version of FCEUX is barely compatible with the FCEU-server code. This is a known issue and will probably be resolved in a future release.
+
+
+
I have a Game Genie rom, how can I use it with FCEUX?
+
+
While FCEUX has a Game Genie code converter, you can also use game genie codes with an old-school Game Genie ROM. It must be named gg.rom and must be placed in the root directory (where fceux.exe is stored). You must also check Config->Enable->Game Genie ROM in the main menu. Then the Game Genie ROM will activate every time you open a ROM, so you can enter GG codes letter-by-letter like they did in the past.
This window sets various graphics emulation options.
-
-
-
Full Screen Settings
-
-
Full Screen
-
Check this checkbox to enter full screen mode.
-
Alternatively, you can use a hotkey (Alt+Enter by default) or a double-click (if the "Switch fullscreen by double-click" option is enabled in GUI options).
-
-
Enter full screen mode after game is loaded
-
If checked, FCEUX will enter full screen mode when a game is loaded.
-
-
Hide mouse cursor
-
If checked, FCEUX will hide mouse cursor when in full screen mode.
-
-
Mode
-
Sets the image size during full screen mode. By default this is automatically set to match current display resolution. You can change the resolution by entering different values.
-
-
Special Scaler
-
Within this box is eight options: hq2x, Scale2x, NTSC 2x, hq3x, Scale3x, Prescale2x, Prescale3x, and Prescale4x.
-
- Scale2x/3x just attempts to render out the corners of the pixels to make them look a bit rounder. "2x" means two times bigger than 1x1 and "3x" means three times bigger than 1x1.
-
- Hq2x/3x does a much better job than scale2x/3x by smearing the pixels together with a slight blur. However, Hq2x/3x requires a faster computer for decent speed (at least 1 GHz and above). "2x" means two times bigger than 1x1 and "3x" means three times bigger than 1x1.
-
- NTSC 2x simulates visual artifacts that are produced by analog (composite) video sygnal that the real console generates.
-
- Prescale2x/3x/4x upscales the source picture using a pixel based (nearest neighbor) algorithm, that allows to change the level of interpolation, applied when using hardware acceleration.
-
-
Sync Method
-
If the emulator is running poorly, trying out these sync options can help make it run smoother (fix image tearing).
-
-
DirectDraw
-
If the image is blurry, here you can disable hardware acceleration.
-
-
-
Windowed Settings
-
-
Size Multiplier
-
Takes the image size and multiples the X and Y by a specific amount. You can also change these by clicking and dragging the border of the FCEUX window.
-
-
Force Integral Scaling Factors
-
If checked, FCEUX window can only be stretched by even amounts (1x, 2x, 3x, etc.). If unchecked, it can be stretched by any amount.
-
When you are resizing FCEUX window by dragging its borders, you can hold Shift to temporarily invert this option.
-
-
Force Aspect Ratio Correction
-
Checking this will only allow the correct aspect ratio while resizing the window.
-
-
Special Scaler
-
Within this box is eight options: hq2x, Scale2x, NTSC 2x, hq3x, Scale3x, Prescale2x, Prescale3x, and Prescale4x.
-
-
Sync Method
-
If the emulator is running poorly, trying out these sync options can help make it run smoother (fix image tearing).
-
-
DirectDraw
-
If Vsync doesn't work, here you can enable hardware acceleration.
-
-
-
-
-
The following options affect both Fullscreen and windowed mode.
-
-
-
Aspect ratio
-
-
Best Fit
-
This is checked by default, so FCEUX will automatically maintain correct aspect ratio for any size of the window. If you uncheck this, the image will be stretched to fill the whole window area.
-
-
BG color
-
When window size is wider or taller than image size, empty areas of the window are colored black by default. Checking this option will color these areas according to current "background" color of NES palette.
-
-
Square pixels
-
This is checked by default, so FCEUX will limit the max size of the image to make all pixels share the same width/height. If you uncheck this, the image will be stretched to fill the whole width or height of the window area.
-
-
TV Aspect
-
Check this if you want to change the image aspect ratio (e.g. to 4:3). You can enter different values in adjacent text fields.
-
-
-
Drawing Area
-
-
First Line
-
Sets the first scan line for NTSC and PAL Modes. This should be left on the default of 8 for NTSC and 0 for PAL.
-
-
Last Line
-
Sets the last scan line for NTSC and PAL Modes. This should be left on the default of 231 for NTSC and 239 for PAL.
-
-
Clip left and right sides (8 px on each)
-
If enabled, 8 pixels from each side of the windows will be removed. Some NES games show grapical artifacts on the sides of screen when scrolling (on real hardware too!), so you may hide those artifacts by checking the option.
-
-
-
Emulation
-
-
Allow more than 8 sprites per scanline
-
On real NES hardware, more than 8 sprites on the screen causes flickering. Enabling this option can reduce flickering by allowing more sprites to be visible at once. But if you prefer to stay "true" to NES hardware, this should not be checked, because some games rely on the limitation.
This window sets various graphics emulation options.
+
+
+
Full Screen Settings
+
+
Full Screen
+
Check this checkbox to enter full screen mode.
+
Alternatively, you can use a hotkey (Alt+Enter by default) or a double-click (if the "Switch fullscreen by double-click" option is enabled in GUI options).
+
+
Enter full screen mode after game is loaded
+
If checked, FCEUX will enter full screen mode when a game is loaded.
+
+
Hide mouse cursor
+
If checked, FCEUX will hide mouse cursor when in full screen mode.
+
+
Mode
+
Sets the image size during full screen mode. By default this is automatically set to match current display resolution. You can change the resolution by entering different values.
+
+
Special Scaler
+
Within this box is eight options: hq2x, Scale2x, NTSC 2x, hq3x, Scale3x, Prescale2x, Prescale3x, and Prescale4x.
+
- Scale2x/3x just attempts to render out the corners of the pixels to make them look a bit rounder. "2x" means two times bigger than 1x1 and "3x" means three times bigger than 1x1.
+
- Hq2x/3x does a much better job than scale2x/3x by smearing the pixels together with a slight blur. However, Hq2x/3x requires a faster computer for decent speed (at least 1 GHz and above). "2x" means two times bigger than 1x1 and "3x" means three times bigger than 1x1.
+
- NTSC 2x simulates visual artifacts that are produced by analog (composite) video sygnal that the real console generates.
+
- Prescale2x/3x/4x upscales the source picture using a pixel based (nearest neighbor) algorithm, that allows to change the level of interpolation, applied when using hardware acceleration.
+
+
Sync Method
+
If the emulator is running poorly, trying out these sync options can help make it run smoother (fix image tearing).
+
+
DirectDraw
+
If the image is blurry, here you can disable hardware acceleration.
+
+
+
Windowed Settings
+
+
Size Multiplier
+
Takes the image size and multiples the X and Y by a specific amount. You can also change these by clicking and dragging the border of the FCEUX window.
+
+
Force Integral Scaling Factors
+
If checked, FCEUX window can only be stretched by even amounts (1x, 2x, 3x, etc.). If unchecked, it can be stretched by any amount.
+
When you are resizing FCEUX window by dragging its borders, you can hold Shift to temporarily invert this option.
+
+
Force Aspect Ratio Correction
+
Checking this will only allow the correct aspect ratio while resizing the window.
+
+
Special Scaler
+
Within this box is eight options: hq2x, Scale2x, NTSC 2x, hq3x, Scale3x, Prescale2x, Prescale3x, and Prescale4x.
+
+
Sync Method
+
If the emulator is running poorly, trying out these sync options can help make it run smoother (fix image tearing).
+
+
DirectDraw
+
If Vsync doesn't work, here you can enable hardware acceleration.
+
+
+
+
+
The following options affect both Fullscreen and windowed mode.
+
+
+
Aspect ratio
+
+
Best Fit
+
This is checked by default, so FCEUX will automatically maintain correct aspect ratio for any size of the window. If you uncheck this, the image will be stretched to fill the whole window area.
+
+
BG color
+
When window size is wider or taller than image size, empty areas of the window are colored black by default. Checking this option will color these areas according to current "background" color of NES palette.
+
+
Square pixels
+
This is checked by default, so FCEUX will limit the max size of the image to make all pixels share the same width/height. If you uncheck this, the image will be stretched to fill the whole width or height of the window area.
+
+
TV Aspect
+
Check this if you want to change the image aspect ratio (e.g. to 4:3). You can enter different values in adjacent text fields.
+
+
+
Drawing Area
+
+
First Line
+
Sets the first scan line for NTSC and PAL Modes. This should be left on the default of 8 for NTSC and 0 for PAL.
+
+
Last Line
+
Sets the last scan line for NTSC and PAL Modes. This should be left on the default of 231 for NTSC and 239 for PAL.
+
+
Clip left and right sides (8 px on each)
+
If enabled, 8 pixels from each side of the windows will be removed. Some NES games show grapical artifacts on the sides of screen when scrolling (on real hardware too!), so you may hide those artifacts by checking the option.
+
+
+
Emulation
+
+
Allow more than 8 sprites per scanline
+
On real NES hardware, more than 8 sprites on the screen causes flickering. Enabling this option can reduce flickering by allowing more sprites to be visible at once. But if you prefer to stay "true" to NES hardware, this should not be checked, because some games rely on the limitation.
FCEUX has all the latest tools, enhancements, and features from FCEU 0.28 rerecording and FCEUXDSP 1.07 In addition, it has many new tools, bug fixes, and enhancements not seen in previous branches.
-
-
-
General
-
-
-A detailed Help Menu! No longer are you aimlessly searching the internet for long lost info on FCEU's options!
-New savestate file format. NOTE: Savestates from previous FCEU versions CAN NOT be used in FCEUX.
-
-Fully functional error handling (savestates from other movies cannot be loaded).
-
-Read-only toggling related bugs fixed.
-
-Savestate filenames include the name of the movie (if a movie was playing when made). This prevents loading wrong savestates. (This also means that savestate 0 is different when a movie is playing and when it is not).
-
-
7z Archive Support
-
-
-ROMs in any 7z compatible compressed format can be opened directly.
-
-If more than one valid ROM exists in an archive file, then a dialog box will open with a list of available ROM choices.
-
-
TAS Edit
-
-
-A brand new powerful movie making tool that revolutionizes the way TAS movies are made. See TAS edit.
-
-
-
New Tools
-
-
TAS Edit - a revolutionary new way of making TAS movies.
-
-
Input Presets - a system for quickly toggling different input configurations.
-
-
-
Tool Upgrades
-
-
Numerous enhancements have been made to various Tools/Options.
-
-
Memory Watch
-
-
-Resource management optimized so that memory watch now uses a minimal amount of CPU
-
-FCEUX remembers memory watch's last screen position (x,y)
-
-Tab-able Edit boxes
-
-Edit boxes now can hold 64 characters
-
-A Menu bar for all Memory watch functions
-
-Both "Save as" and "Save" options
-
-Hotkeys for New, Open, Save, Save As and Close
-
-A recent files Menu
-
-A "load on startup" option. If checked, memory watch will open automatically when FCEUX is opened
-
-A "load last file" option. If checked, memory watch will load the last file used
-
-
Cheat Search
-
-
-Now has a minimize button
-
-Cheat Search Menu from FCEUXDSP (a major overhaul compared to other FCEU branches)
-
-Possibilities update while playing/frame advancing a game
-
-Double clicking a value in the possibilities window sends the value directly to Memory Watch
-
-
RAM Filter
-
-
-Double clicking a value in the possibilities window sends the value directly to Memory Watch
-
-
-
Lua Scripting
-
-
-Uses the latest features of Lua Scripting from FCEU 0.28
-
-Many enhancements and new commands including dialog creation commands! Now scripts can create their own dialog's and GUI features.
-
-
Lua Basic Bot
-
-
-Basicbot removed (from the rerecording version of FCE Ultra). In its place is lua bot.
-
-
-
AVI Recording
-
-
-"Movie playback stopped" message recorded in AVI by default
-
-Turbo Toggle Hotkey. (Allows turbo to be left on for a faster AVI capture).
FCEUX has all the latest tools, enhancements, and features from FCEU 0.28 rerecording and FCEUXDSP 1.07 In addition, it has many new tools, bug fixes, and enhancements not seen in previous branches.
+
+
+
General
+
+
-A detailed Help Menu! No longer are you aimlessly searching the internet for long lost info on FCEU's options!
-New savestate file format. NOTE: Savestates from previous FCEU versions CAN NOT be used in FCEUX.
+
-Fully functional error handling (savestates from other movies cannot be loaded).
+
-Read-only toggling related bugs fixed.
+
-Savestate filenames include the name of the movie (if a movie was playing when made). This prevents loading wrong savestates. (This also means that savestate 0 is different when a movie is playing and when it is not).
+
+
7z Archive Support
+
+
-ROMs in any 7z compatible compressed format can be opened directly.
+
-If more than one valid ROM exists in an archive file, then a dialog box will open with a list of available ROM choices.
+
+
TAS Edit
+
+
-A brand new powerful movie making tool that revolutionizes the way TAS movies are made. See TAS edit.
+
+
+
New Tools
+
+
TAS Edit - a revolutionary new way of making TAS movies.
+
+
Input Presets - a system for quickly toggling different input configurations.
+
+
+
Tool Upgrades
+
+
Numerous enhancements have been made to various Tools/Options.
+
+
Memory Watch
+
+
-Resource management optimized so that memory watch now uses a minimal amount of CPU
+
-FCEUX remembers memory watch's last screen position (x,y)
+
-Tab-able Edit boxes
+
-Edit boxes now can hold 64 characters
+
-A Menu bar for all Memory watch functions
+
-Both "Save as" and "Save" options
+
-Hotkeys for New, Open, Save, Save As and Close
+
-A recent files Menu
+
-A "load on startup" option. If checked, memory watch will open automatically when FCEUX is opened
+
-A "load last file" option. If checked, memory watch will load the last file used
+
+
Cheat Search
+
+
-Now has a minimize button
+
-Cheat Search Menu from FCEUXDSP (a major overhaul compared to other FCEU branches)
+
-Possibilities update while playing/frame advancing a game
+
-Double clicking a value in the possibilities window sends the value directly to Memory Watch
+
+
RAM Filter
+
+
-Double clicking a value in the possibilities window sends the value directly to Memory Watch
+
+
+
Lua Scripting
+
+
-Uses the latest features of Lua Scripting from FCEU 0.28
+
-Many enhancements and new commands including dialog creation commands! Now scripts can create their own dialog's and GUI features.
+
+
Lua Basic Bot
+
+
-Basicbot removed (from the rerecording version of FCE Ultra). In its place is lua bot.
+
+
+
AVI Recording
+
+
-"Movie playback stopped" message recorded in AVI by default
+
-Turbo Toggle Hotkey. (Allows turbo to be left on for a faster AVI capture).
This release includes a large number of bug fixes, feature enhancements, and new features.
-
-
-
Fixed Crashing Bugs
-
-
* restore savestate error recovery functionality. Will prevent crashes after savestate error messages
-
* Fixed - Low speeds (1%) crash FCEUX
-
* fixes bug where palflag 1 in .fm2 files crashes fceux
-
* FCEUX no longer crashes when attempting to open a non movie file
-
* Buffer overflow (change vsprintf to vsnprintf)
-
-
Minor Bug fixes
-
-
* SRAM not wiped on power cycle (during movies)
-
* Moviefilenames without extension now automatically get fm2
-
* auto-fill .fcs extension in save state as dialog
-
* FCM>FM2 converter releases file handle
-
* fix a new bug in windows build which caused fourscore emulation to fail in some cases
-
* Player 3 no longer inputs when not used
-
* prints a special message when trying to open an FCM reminding user to convert.
-
* fixes bug where Avi recording with no sound messes up the format
-
* Fixed bug where Convert .fcm didn't do special characters
-
* fixed the (null) in the default lua directory listing
-
* Ctrl+X now works in the memory watch dialog
-
* Dialog window positions won't "disappear" (-32000 protection on all dialogs that remember x,y)
-
* fixed View Slots bug - will now always show the used slots
-
-
* added shift+L as default hotkey for reload lua script
-
* added input display to the FCEUX main menu
-
* change config filename from fceu98.cfg to fceux.cfg
-
-
New Features
-
-
* restore IPS patching capability which was lost when archive support was added
-
* restore ungzipping (and unzipping in sdl) capability which was lost when archive support was added
-
* re-enable an "author" text field in the record movie dialog
-
* re-enable support for old-format savestates. (Note: can not be loaded into a movie!)
-
-
* Added new toggle - frame adv. - lag skip (menu item + hotkey mapping + saved in config), will cause frame adv. to skip frames where input is not read
-
* Added support for loading movies from archives (just like ROM files). Note: Movies loaded from an archive file will be read-only.
-
* movie replay dialog displays fractions of a second on movie length
-
-
* Savestates now save the Lagcounter information.
-
* added a mute turbo option in sound config
-
-
* add an option to pick a constant color to draw in place of BG when BG rendering is disabled (look for gNoBGFillColor in config).
-
-
Mappers
-
-
* remove cnrom chr rom size limit for homebrew roms
-
* mmc5 - 64KB WRAM games now work correctly
-
* mmc5 - use of chr A regs for BG in sprite 8x8 mode is fixed
-
* upgrade to cah4e3's latest mapper 163&164 code to fix a crash in a game
-
-
-
Debugging Tools
-
-
* Debugger - restore snap functionality
-
* Debugger - add FORBID breakpoints - regions which block breakpoints from happening if they contain the PC
-
* Debugger - debugger window is now resizeable
-
* nametable viewer will display correct NT,CHR,ATTR data in more cases (specifically, including some exotic mmc5 cases).
-
-
Lua
-
-
* Savestates remember Lua painting
-
* add memory.readbyterange to emulua
-
-
SDL only
-
-
* SDL: fixed --input(1-4) options. input1 and 2 are regular inputs, input3 and 4 are famicom expansion inputs
-
* SDL fix configfile woes. configfile now goes to ~/.fceux/fceux.cfg
-
* SDL: fixed segfault when opening .fcm files
-
* SDL: Saner sound defaults for less choppy sound
-
* SDL: "--special" option fixed for special video scaling filters
-
* SDL: cleaned up the SConsruct
-
* SDL: fixed issue where fceu would lock up when file dialogs were opened during fullscreen
-
* SDL: fixed bug where fceux would close when file dialogs were closed
-
* SDL: File open dialog is now used to movie playback
-
* SDL: File open wrapper now takes a titlebar argument
This release includes a large number of bug fixes, feature enhancements, and new features.
+
+
+
Fixed Crashing Bugs
+
+
* restore savestate error recovery functionality. Will prevent crashes after savestate error messages
+
* Fixed - Low speeds (1%) crash FCEUX
+
* fixes bug where palflag 1 in .fm2 files crashes fceux
+
* FCEUX no longer crashes when attempting to open a non movie file
+
* Buffer overflow (change vsprintf to vsnprintf)
+
+
Minor Bug fixes
+
+
* SRAM not wiped on power cycle (during movies)
+
* Moviefilenames without extension now automatically get fm2
+
* auto-fill .fcs extension in save state as dialog
+
* FCM>FM2 converter releases file handle
+
* fix a new bug in windows build which caused fourscore emulation to fail in some cases
+
* Player 3 no longer inputs when not used
+
* prints a special message when trying to open an FCM reminding user to convert.
+
* fixes bug where Avi recording with no sound messes up the format
+
* Fixed bug where Convert .fcm didn't do special characters
+
* fixed the (null) in the default lua directory listing
+
* Ctrl+X now works in the memory watch dialog
+
* Dialog window positions won't "disappear" (-32000 protection on all dialogs that remember x,y)
+
* fixed View Slots bug - will now always show the used slots
+
+
* added shift+L as default hotkey for reload lua script
+
* added input display to the FCEUX main menu
+
* change config filename from fceu98.cfg to fceux.cfg
+
+
New Features
+
+
* restore IPS patching capability which was lost when archive support was added
+
* restore ungzipping (and unzipping in sdl) capability which was lost when archive support was added
+
* re-enable an "author" text field in the record movie dialog
+
* re-enable support for old-format savestates. (Note: can not be loaded into a movie!)
+
+
* Added new toggle - frame adv. - lag skip (menu item + hotkey mapping + saved in config), will cause frame adv. to skip frames where input is not read
+
* Added support for loading movies from archives (just like ROM files). Note: Movies loaded from an archive file will be read-only.
+
* movie replay dialog displays fractions of a second on movie length
+
+
* Savestates now save the Lagcounter information.
+
* added a mute turbo option in sound config
+
+
* add an option to pick a constant color to draw in place of BG when BG rendering is disabled (look for gNoBGFillColor in config).
+
+
Mappers
+
+
* remove cnrom chr rom size limit for homebrew roms
+
* mmc5 - 64KB WRAM games now work correctly
+
* mmc5 - use of chr A regs for BG in sprite 8x8 mode is fixed
+
* upgrade to cah4e3's latest mapper 163&164 code to fix a crash in a game
+
+
+
Debugging Tools
+
+
* Debugger - restore snap functionality
+
* Debugger - add FORBID breakpoints - regions which block breakpoints from happening if they contain the PC
+
* Debugger - debugger window is now resizeable
+
* nametable viewer will display correct NT,CHR,ATTR data in more cases (specifically, including some exotic mmc5 cases).
+
+
Lua
+
+
* Savestates remember Lua painting
+
* add memory.readbyterange to emulua
+
+
SDL only
+
+
* SDL: fixed --input(1-4) options. input1 and 2 are regular inputs, input3 and 4 are famicom expansion inputs
+
* SDL fix configfile woes. configfile now goes to ~/.fceux/fceux.cfg
+
* SDL: fixed segfault when opening .fcm files
+
* SDL: Saner sound defaults for less choppy sound
+
* SDL: "--special" option fixed for special video scaling filters
+
* SDL: cleaned up the SConsruct
+
* SDL: fixed issue where fceu would lock up when file dialogs were opened during fullscreen
+
* SDL: fixed bug where fceux would close when file dialogs were closed
+
* SDL: File open dialog is now used to movie playback
+
* SDL: File open wrapper now takes a titlebar argument
This release includes a multitude of new features, major fixes, and enhancements.
-
-
-
The 2.1 new release fixes some bugs of 2.1.0a, improves the accuracy of the sound core, and adds useability enhancements to the windows port.
-
-
Common - Bug fixes
-
-
Fixed reported issue 2746924 (md5_asciistr() doesn't produce correct string)
-
Made default save slot 0 instead of 1
-
-
-
Improved Sound core/PPU
-
-
Fixed the noise value, it seems that the noise logic was shifting the values to the left by 1 when reloading, but this doesn't work for PAL since one of the PAL reload value is odd, so fix the logic and used the old tables. Revert a stupid CPU ignore logic in PPU. Sorry about that.
-
Updated with the correct values for the noise and DMC table,
-
Fixed the CPU unofficial opcode ATX, ORing with correct constant $FF instead of $EE, as tested by blargg's. These fixes passes the IRQ flags test from blargg, and also one more opcode test from blargg's cpu.nes test.
-
Square 1 & square 2 volume controls no longer backwards
-
Length counters for APU now correct variables
-
-
-
NewPPU (still experimental, enabled by setting newppu 1 in the config file)
-
-
Added experimental $2004 reading support to play micro machines with (little) shakes, and fixed some timing in the new PPU.
-
Added palette reading cases for the new PPU.
-
-
-
Win32
-
-
Minor Bug fixes
-
-
Replay movie dialog - Stop movie at frame x feature - fixed off by 1 error on the stop frame number
-
Hex Editor - changed ROM values again dsiplay as red, saved in the config as RomFreezeColor
-
Fixed bug in memory watch that would make the first watch value drawn in the wrong place if watch file was full
-
Debugger - Step type functions now update other dialogs such as ppu, nametable, code/data, trace logger, etc.
-
"Disable screen saver" gui option now also diables the monitor powersave
-
Recent menus - no longer crash if item no longer exists, instead it ask the user if they want to remove the item from the list
-
Sound Config Dialog - When sound is off, all controls are grayed out
-
Memory Watch - fixed a regression made in 2.0.1 that broke the Save As menu item
-
Memory Watch - save menu item is grayed if file hasn't changed
-
-
-
-
GUI/Enhancements
-
-
Last save slot used is stored in the config file
-
Made fullscreen toggle (Alt+Enter) remappable
-
Hex editor - Reverted fixedFontHeight to 13 instead of 14. Gave the option of adjusting the height by modifying RowHeightBorder in the .cfg file
-
Hex Editor - allowed the user to customize the color scheme by use of RGB values stored in the .cfg file
-
Hex editor - freeze/unfreeze ram addresses now causes the colors to update immediately, but only with groups of addresses highlighted at once (single ones still don't yet update)
-
Hex Editor - Save Rom As... menu option enabled and implemented
-
Window caption shows the name of the ROM loaded
-
Recent Movie Menu added
-
Load Last Movie context menu item added
-
Save Movie As... context menu item (for when a movie is loaded in read+write mode)
-
Drag & Drop support for all files related to FCEUX including:
-
-
.fcm (autoconverts to .fm2 and begins movie playback)
-
Savestates
-
Palette files (.pal)
-
-
Commandline - -palette commandline option
-
Memory Watch - option to bind to main window, if checked it gives GENS dialog style control, where there is no extra task bar item, and it minimizes when FCEUX is minimized
-
-
-
SDL
-
-
-
added --subtitles
-
fixed Four Score movie playback
-
added --ripsubs for converting fm2 movie subtitles to an srt file
-
Lua is optional again, fixed the real issue
-
Lua is NO longer optional, so the SConscripts have been updated to reflect that change. This fixes the mysterious non-working input issue.
-
implemented saving/loading a savestate from a specific file on Alt+S/L
-
implemented starting an FM2 movie on Alt+R
-
added --pauseframe to pause movie playback on frame x
-
dropped UTFConverter.c from SDL build
-
added hotkey Q for toggling read-only/read+write movie playback
This release includes a multitude of new features, major fixes, and enhancements.
+
+
+
The 2.1 new release fixes some bugs of 2.1.0a, improves the accuracy of the sound core, and adds useability enhancements to the windows port.
+
+
Common - Bug fixes
+
+
Fixed reported issue 2746924 (md5_asciistr() doesn't produce correct string)
+
Made default save slot 0 instead of 1
+
+
+
Improved Sound core/PPU
+
+
Fixed the noise value, it seems that the noise logic was shifting the values to the left by 1 when reloading, but this doesn't work for PAL since one of the PAL reload value is odd, so fix the logic and used the old tables. Revert a stupid CPU ignore logic in PPU. Sorry about that.
+
Updated with the correct values for the noise and DMC table,
+
Fixed the CPU unofficial opcode ATX, ORing with correct constant $FF instead of $EE, as tested by blargg's. These fixes passes the IRQ flags test from blargg, and also one more opcode test from blargg's cpu.nes test.
+
Square 1 & square 2 volume controls no longer backwards
+
Length counters for APU now correct variables
+
+
+
NewPPU (still experimental, enabled by setting newppu 1 in the config file)
+
+
Added experimental $2004 reading support to play micro machines with (little) shakes, and fixed some timing in the new PPU.
+
Added palette reading cases for the new PPU.
+
+
+
Win32
+
+
Minor Bug fixes
+
+
Replay movie dialog - Stop movie at frame x feature - fixed off by 1 error on the stop frame number
+
Hex Editor - changed ROM values again dsiplay as red, saved in the config as RomFreezeColor
+
Fixed bug in memory watch that would make the first watch value drawn in the wrong place if watch file was full
+
Debugger - Step type functions now update other dialogs such as ppu, nametable, code/data, trace logger, etc.
+
"Disable screen saver" gui option now also diables the monitor powersave
+
Recent menus - no longer crash if item no longer exists, instead it ask the user if they want to remove the item from the list
+
Sound Config Dialog - When sound is off, all controls are grayed out
+
Memory Watch - fixed a regression made in 2.0.1 that broke the Save As menu item
+
Memory Watch - save menu item is grayed if file hasn't changed
+
+
+
+
GUI/Enhancements
+
+
Last save slot used is stored in the config file
+
Made fullscreen toggle (Alt+Enter) remappable
+
Hex editor - Reverted fixedFontHeight to 13 instead of 14. Gave the option of adjusting the height by modifying RowHeightBorder in the .cfg file
+
Hex Editor - allowed the user to customize the color scheme by use of RGB values stored in the .cfg file
+
Hex editor - freeze/unfreeze ram addresses now causes the colors to update immediately, but only with groups of addresses highlighted at once (single ones still don't yet update)
+
Hex Editor - Save Rom As... menu option enabled and implemented
+
Window caption shows the name of the ROM loaded
+
Recent Movie Menu added
+
Load Last Movie context menu item added
+
Save Movie As... context menu item (for when a movie is loaded in read+write mode)
+
Drag & Drop support for all files related to FCEUX including:
+
+
.fcm (autoconverts to .fm2 and begins movie playback)
+
Savestates
+
Palette files (.pal)
+
+
Commandline - -palette commandline option
+
Memory Watch - option to bind to main window, if checked it gives GENS dialog style control, where there is no extra task bar item, and it minimizes when FCEUX is minimized
+
+
+
SDL
+
+
+
added --subtitles
+
fixed Four Score movie playback
+
added --ripsubs for converting fm2 movie subtitles to an srt file
+
Lua is optional again, fixed the real issue
+
Lua is NO longer optional, so the SConscripts have been updated to reflect that change. This fixes the mysterious non-working input issue.
+
implemented saving/loading a savestate from a specific file on Alt+S/L
+
implemented starting an FM2 movie on Alt+R
+
added --pauseframe to pause movie playback on frame x
+
dropped UTFConverter.c from SDL build
+
added hotkey Q for toggling read-only/read+write movie playback
The 2.1.2 release fixes some bugs of 2.1.0a, increases game compatibility, launches a new PPU core, and adds usability enhancements to the windows port.
-
-
Common
-
-
New PPU is now functional! You can access it by changing the newPPU flag in the config file. Windows users can access it from Config > PPU > New PPU
-
Dragon Ball Z 3 now playable again
-
Fixed action 52 game that was broken in post-FCEUX 2.0.3 versions
-
Mapper 253 mostly implemented
-
Mapper 43 fixed bug
-
-
-
Win32
-
-
-
Imported NSF features from FCEUXDSP-NSF. Debugging tools are now compatible with NSF files.
-
Movies now record FDS disk swapping commands
-
Movie play dialog displays movie time based on ~60.1 (~50.1 PAL) instead of 60 & 50
-
Ram Watch and Ram Search dialogs imported from GENS rerecording
-
Ram Filter dialog removed (now redundant compared to both cheat search and ram search)
-
Lua script window ported from GENS
-
Fix for the directory overrides bug that caused overrides to reset
-
Debugger: .deb file saving/loading restored
-
"Save config file" menu item
-
"New PPU" menu item
-
-
-
Minor Bug fixes
-
-
-
Minor fixes to recent menus
-
Fixed a bug that prevented the Map Hotkeys dialog's X button from closing the dialog
-
Restored DPCM Logging when Code/Data Logger is active
-
Memory watch - Save Changes Prompt - clicking save will default to quicksave first and save as 2nd (instead of always defaulting to save as)
-
Made Trace Logger refresh adequately when using stepping options in the debugger.
-
-
-
Lua
-
-
joypad.set() fixed. True,False, and Nil now work properly for all buttons. In addition there is a new "invert" option.
The 2.1.2 release fixes some bugs of 2.1.0a, increases game compatibility, launches a new PPU core, and adds usability enhancements to the windows port.
+
+
Common
+
+
New PPU is now functional! You can access it by changing the newPPU flag in the config file. Windows users can access it from Config > PPU > New PPU
+
Dragon Ball Z 3 now playable again
+
Fixed action 52 game that was broken in post-FCEUX 2.0.3 versions
+
Mapper 253 mostly implemented
+
Mapper 43 fixed bug
+
+
+
Win32
+
+
+
Imported NSF features from FCEUXDSP-NSF. Debugging tools are now compatible with NSF files.
+
Movies now record FDS disk swapping commands
+
Movie play dialog displays movie time based on ~60.1 (~50.1 PAL) instead of 60 & 50
+
Ram Watch and Ram Search dialogs imported from GENS rerecording
+
Ram Filter dialog removed (now redundant compared to both cheat search and ram search)
+
Lua script window ported from GENS
+
Fix for the directory overrides bug that caused overrides to reset
+
Debugger: .deb file saving/loading restored
+
"Save config file" menu item
+
"New PPU" menu item
+
+
+
Minor Bug fixes
+
+
+
Minor fixes to recent menus
+
Fixed a bug that prevented the Map Hotkeys dialog's X button from closing the dialog
+
Restored DPCM Logging when Code/Data Logger is active
+
Memory watch - Save Changes Prompt - clicking save will default to quicksave first and save as 2nd (instead of always defaulting to save as)
+
Made Trace Logger refresh adequately when using stepping options in the debugger.
+
+
+
Lua
+
+
joypad.set() fixed. True,False, and Nil now work properly for all buttons. In addition there is a new "invert" option.
The 2.1.3 release fixes some bugs of 2.1.2, increases game compatibility, and adds usability enhancements to the windows port and adds a GUI to the SDL port.
-
-
Common
-
-
Fixed mappers 82, 25, 21, and 18. Games such as SD Kiji Blader, Ganbare Goemon Gaiden, and Ganbare Goemon Gaiden 2, Jajamaru Gekimadden are now playable
-
Fixes for mappers 253 & 226 - fixes games such as Fire Emblem (J) and Fire Emblem Gaiden (J)
-
Fix crashing on game loading for any battery backed ROMs with mappers from MapInitTab (fixes Esper Dream 2 - Aratanaru Tatakai (J)
-
FDS - show name of missing bios file in error message
-
NewPPU - fixed sprite hit before 255 and for non transparent hits only, thanks to dwedit for providing the fix
-
.fm2 file format header now has an FDS flag
-
-
-
SDL
-
-
-
A GUI! A graphic user interface (using GTK) with many basic menu options
-
ported to SDL 1.3; compatibility maintained with 1.2
-
unix netplay is now functional; gtk network gui created
-
now prints the name of the mapper on ROM load
-
fixed dpad/joyhat support
-
VS unisystem keys now configable
-
changed default hotkeys and keys to match Win32
-
disallow --inputcfg gamepad0 and gamepad5
-
-
-
Win32
-
-
-
Made savestate backups optional (config - enable - backup savestates)
-
Made savestate compression togglable (config - enable - compress savestates)
-
Cheats dialog - Pause while active checkbox
-
Cheats dialog - Toggling a cheat in the cheats list now updates the active cheats count
-
Debugger - added an auto-load feature
-
Debugger - Fix so it doesn't crash if unminimized with no game loaded
-
Closing minimized windows no longer moves them the next time they get opened
-
Lua console - added a menu
-
Lua console - filename updates when lua scripts are dragged to emulator or recent filenames invoked
-
Name Table Viewer - Fix for use with New PPU
-
Trace Logger - Trace logger now logs the values of the stack pointer register
-
If a .fm2 file is drag and dropped with no ROM load, the open ROM dialog will appear
-
disable movie messages menu item
-
Added more window positions bounds checks. Accounts for -32000 positions and less out-of-range too
New lua functions: gui.parsecolor(), joypad.getup(), joypad.getdown(), emu.emulating()
-
Change gui.line, gui.box, joypad.get to function consistently with other lua emulators such as GENS rerecording
-
fixed zapper.read() to read movie data if a movie is playing. Also changed the struct values to x,y,fire. This breaks lua scripts that used it previous, sorry
-
gui.text() now has out of bounds checking
-
Lua no longer unpauses the emulator when a script is loaded
The 2.1.3 release fixes some bugs of 2.1.2, increases game compatibility, and adds usability enhancements to the windows port and adds a GUI to the SDL port.
+
+
Common
+
+
Fixed mappers 82, 25, 21, and 18. Games such as SD Kiji Blader, Ganbare Goemon Gaiden, and Ganbare Goemon Gaiden 2, Jajamaru Gekimadden are now playable
+
Fixes for mappers 253 & 226 - fixes games such as Fire Emblem (J) and Fire Emblem Gaiden (J)
+
Fix crashing on game loading for any battery backed ROMs with mappers from MapInitTab (fixes Esper Dream 2 - Aratanaru Tatakai (J)
+
FDS - show name of missing bios file in error message
+
NewPPU - fixed sprite hit before 255 and for non transparent hits only, thanks to dwedit for providing the fix
+
.fm2 file format header now has an FDS flag
+
+
+
SDL
+
+
+
A GUI! A graphic user interface (using GTK) with many basic menu options
+
ported to SDL 1.3; compatibility maintained with 1.2
+
unix netplay is now functional; gtk network gui created
+
now prints the name of the mapper on ROM load
+
fixed dpad/joyhat support
+
VS unisystem keys now configable
+
changed default hotkeys and keys to match Win32
+
disallow --inputcfg gamepad0 and gamepad5
+
+
+
Win32
+
+
+
Made savestate backups optional (config - enable - backup savestates)
+
Made savestate compression togglable (config - enable - compress savestates)
+
Cheats dialog - Pause while active checkbox
+
Cheats dialog - Toggling a cheat in the cheats list now updates the active cheats count
+
Debugger - added an auto-load feature
+
Debugger - Fix so it doesn't crash if unminimized with no game loaded
+
Closing minimized windows no longer moves them the next time they get opened
+
Lua console - added a menu
+
Lua console - filename updates when lua scripts are dragged to emulator or recent filenames invoked
+
Name Table Viewer - Fix for use with New PPU
+
Trace Logger - Trace logger now logs the values of the stack pointer register
+
If a .fm2 file is drag and dropped with no ROM load, the open ROM dialog will appear
+
disable movie messages menu item
+
Added more window positions bounds checks. Accounts for -32000 positions and less out-of-range too
New lua functions: gui.parsecolor(), joypad.getup(), joypad.getdown(), emu.emulating()
+
Change gui.line, gui.box, joypad.get to function consistently with other lua emulators such as GENS rerecording
+
fixed zapper.read() to read movie data if a movie is playing. Also changed the struct values to x,y,fire. This breaks lua scripts that used it previous, sorry
+
gui.text() now has out of bounds checking
+
Lua no longer unpauses the emulator when a script is loaded
2.1.4 is a maintenance release that fixes these bugs in 2.1.4:
-
fix crash bug on .fcm convert
-
fix erroneous reporting of savestate past the end of movie error during read-only loadstates
-
-
Released 31 May 2010
-
-
-
The 2.1.4 release fixes many bugs and adds new features compared to 2.1.3. In addition it also fixes up the movie code significantly; fixing implementation problems, loading speed, adding new features, and fixing bugs.
-
-
Common
-
-
Added microphone support option. When enabled, Port 2 Start activates the Microphone
-
Prevent .zip files containing no recognized files from causing crash
-
Autohold - Added player 3 and 4 to autohold notification window, labeled controller input
-
mapper 19 savestate fix mirroring for "Dream Master (J)" corrected to "four-screen" by CRC check
-
Disable auto-savestates during turbo
-
Fixed so Gotcha! auto-enables the zapper
-
Autohold - Added player 3 and 4 to autohold notification window, labeled controller input
-
-
-
Movies
-
-
-
Fully implemented "bulletproof" read-only
-
Movie code now fully conforms to the Savestate section of the Laws of TAS
-
Fixed a potential desync that plays out an extra frame without an update to the frame count involving heavy lua use, joypad.get, and a loadstate
-
Movie support for microphone
-
Movies now have a "finished" mode. If a playback stops the movie isn't cleared from memory, and can be replayed or a state loaded Similar functionality as DeSmuME and GENS rerecording
-
New PPU flag in movie headers (doesn't change an emulators PPU state when loading a movie)
-
Much faster movie loading and movie-savestate loading
-
Made gamepad 2 off by default (so less movies should have unused player 2 data)
-
Implemented a "full savestate-movie load" mode similar to the implementation in VBA-rr and SNES9x-rr. In this mode loading a savestate in read+write doesn't truncate the movie to its frame count immediately. Instead it waits until input is recording into the movie (next frame). For win32 this feature is togglable in movie options and the context menu. For SDL this is off by default and a toggle will need to be added
-
Movie + loadstate errors are handled more gracefully now, with more informative error messages and the movie doesn't have to stop if backups are enabled
-
Fix PlayMovieFromBeginning when using a movie that starts from savestate
-
-
-
Lua
-
-
fix bug that caused zapper.read() to crash when movie playback ends
-
Win32 - Added option for palette selection as color for LUA colors. Included is a LUA script to display all choices with the value used to pick displayed color
-
-
-
New Lua functions
-
-
movie.ispoweron()
-
movie.isfromsavestate()
-
emu.addgamegenie()
-
emu.delgamegenie()
-
savestate.object() which is savestate.create() with intuitive numbering under windows
-
gui.getpixel() which gets any gui.pixel() set pixel colors, and possibly other functions
-
emu.getscreenpixel() which gets the RGB and Palette of any pixel on the screen
-
lua function movie.getfilename() which returns the current movie filename without the path included
-
-
-
Input Display
-
-
Input display updates on loadstate
-
Input display overhaul that uses different colors for different input contexts
-
Input display now shows both currently pressed buttons and buttons held the previous frame
-
-
-
Win32
-
-
Added NTSC 2x scalar option with some CFG config options of it's own Added Ram Search hotkeys for the first 6 search types in the list
-
Add Cheat buttons for Ram Search and Ram Watch
-
With special scaler in window mode, it's possible to resize to anything above the minimum.
-
Recording a new movie adds it to recent movies list
-
Replay dialog, when selecting a movie in a relative path (.\movies for example), the recent movies list stores an absolute path instead
-
Replay dialog shows PAL flag and New PPU flags
-
CDLogger - fixed bug preventing correct interrupt vectors from logging
-
Memwatch - ignore spaces at the beginnign of an address in the address boxes
-
Replay dialog - fix bug that was causing it to always report savestate movies as soft-reset
-
-
-
Debugger
-
-
-
Added conditional debugging option 'K', for bank PC is on
-
Fixed bug involving pausing emulation outside of the debugger, then trying to use the debugger commands, and having the CPU registers become corrupted
-
Made debugger able to break on and distinguish Stack reads/writes
-
-
-
Hex Editor
-
-
-
Added "Goto" command
-
Made the Hex Editor display the Frozen, Bookmarked, etc. status of the selected address, and made the Frozen color override the Bookmarked color.
-
-
-
Cheat Search
-
-
-
Made enabling/disabling cheats no longer deselect the selected cheat
-
Added context menu to Cheat Dialog Cheat Listbox, populated list with Toggle Cheat, Poke Cheat Value, and Goto In Hex Editor
-
Enabled multi-select for Cheat menu to allow multiple toggles and deletes
-
Made cheat menu's Pause When Active effect immediate
-
-
-
GUI
-
-
-
Added Tools - GUI option to partially disable visual themes, so the emulator can be made to look like it did in 2.1.1 and earlier releases. Drag & Drop - if dropping a .fcm with no ROM loaded, prompt for one (same functionality that was added to .fm2 files)
-
Added single-instance mode, which makes starting a second copy of FCEUX load the file into the first, then exit.Mode off by default, togglable under Config - GUI
2.1.4 is a maintenance release that fixes these bugs in 2.1.4:
+
fix crash bug on .fcm convert
+
fix erroneous reporting of savestate past the end of movie error during read-only loadstates
+
+
Released 31 May 2010
+
+
+
The 2.1.4 release fixes many bugs and adds new features compared to 2.1.3. In addition it also fixes up the movie code significantly; fixing implementation problems, loading speed, adding new features, and fixing bugs.
+
+
Common
+
+
Added microphone support option. When enabled, Port 2 Start activates the Microphone
+
Prevent .zip files containing no recognized files from causing crash
+
Autohold - Added player 3 and 4 to autohold notification window, labeled controller input
+
mapper 19 savestate fix mirroring for "Dream Master (J)" corrected to "four-screen" by CRC check
+
Disable auto-savestates during turbo
+
Fixed so Gotcha! auto-enables the zapper
+
Autohold - Added player 3 and 4 to autohold notification window, labeled controller input
+
+
+
Movies
+
+
+
Fully implemented "bulletproof" read-only
+
Movie code now fully conforms to the Savestate section of the Laws of TAS
+
Fixed a potential desync that plays out an extra frame without an update to the frame count involving heavy lua use, joypad.get, and a loadstate
+
Movie support for microphone
+
Movies now have a "finished" mode. If a playback stops the movie isn't cleared from memory, and can be replayed or a state loaded Similar functionality as DeSmuME and GENS rerecording
+
New PPU flag in movie headers (doesn't change an emulators PPU state when loading a movie)
+
Much faster movie loading and movie-savestate loading
+
Made gamepad 2 off by default (so less movies should have unused player 2 data)
+
Implemented a "full savestate-movie load" mode similar to the implementation in VBA-rr and SNES9x-rr. In this mode loading a savestate in read+write doesn't truncate the movie to its frame count immediately. Instead it waits until input is recording into the movie (next frame). For win32 this feature is togglable in movie options and the context menu. For SDL this is off by default and a toggle will need to be added
+
Movie + loadstate errors are handled more gracefully now, with more informative error messages and the movie doesn't have to stop if backups are enabled
+
Fix PlayMovieFromBeginning when using a movie that starts from savestate
+
+
+
Lua
+
+
fix bug that caused zapper.read() to crash when movie playback ends
+
Win32 - Added option for palette selection as color for LUA colors. Included is a LUA script to display all choices with the value used to pick displayed color
+
+
+
New Lua functions
+
+
movie.ispoweron()
+
movie.isfromsavestate()
+
emu.addgamegenie()
+
emu.delgamegenie()
+
savestate.object() which is savestate.create() with intuitive numbering under windows
+
gui.getpixel() which gets any gui.pixel() set pixel colors, and possibly other functions
+
emu.getscreenpixel() which gets the RGB and Palette of any pixel on the screen
+
lua function movie.getfilename() which returns the current movie filename without the path included
+
+
+
Input Display
+
+
Input display updates on loadstate
+
Input display overhaul that uses different colors for different input contexts
+
Input display now shows both currently pressed buttons and buttons held the previous frame
+
+
+
Win32
+
+
Added NTSC 2x scalar option with some CFG config options of it's own Added Ram Search hotkeys for the first 6 search types in the list
+
Add Cheat buttons for Ram Search and Ram Watch
+
With special scaler in window mode, it's possible to resize to anything above the minimum.
+
Recording a new movie adds it to recent movies list
+
Replay dialog, when selecting a movie in a relative path (.\movies for example), the recent movies list stores an absolute path instead
+
Replay dialog shows PAL flag and New PPU flags
+
CDLogger - fixed bug preventing correct interrupt vectors from logging
+
Memwatch - ignore spaces at the beginnign of an address in the address boxes
+
Replay dialog - fix bug that was causing it to always report savestate movies as soft-reset
+
+
+
Debugger
+
+
+
Added conditional debugging option 'K', for bank PC is on
+
Fixed bug involving pausing emulation outside of the debugger, then trying to use the debugger commands, and having the CPU registers become corrupted
+
Made debugger able to break on and distinguish Stack reads/writes
+
+
+
Hex Editor
+
+
+
Added "Goto" command
+
Made the Hex Editor display the Frozen, Bookmarked, etc. status of the selected address, and made the Frozen color override the Bookmarked color.
+
+
+
Cheat Search
+
+
+
Made enabling/disabling cheats no longer deselect the selected cheat
+
Added context menu to Cheat Dialog Cheat Listbox, populated list with Toggle Cheat, Poke Cheat Value, and Goto In Hex Editor
+
Enabled multi-select for Cheat menu to allow multiple toggles and deletes
+
Made cheat menu's Pause When Active effect immediate
+
+
+
GUI
+
+
+
Added Tools - GUI option to partially disable visual themes, so the emulator can be made to look like it did in 2.1.1 and earlier releases. Drag & Drop - if dropping a .fcm with no ROM loaded, prompt for one (same functionality that was added to .fm2 files)
+
Added single-instance mode, which makes starting a second copy of FCEUX load the file into the first, then exit.Mode off by default, togglable under Config - GUI
The 2.1.5 release fixes a lot of bugs and brings various improvements to the prior 2.1.4a release. In addition, the SDL port has improved signficantly; completely overhauling the GTK2 GUI, fixing many sound issues, and fixing a variety of bugs.
-
-
Common
-
-
Fixed compatibility issue with Young Indiana Jones Chronicles
-
Fixed bug in new PPU that made some intensify bits not get applied to output (fixed flashing siren screen in Werefolf)
-
Fix many segmentation faults related to file handling
-
-
-
Movies
-
-
-
Slight performance increase when loading movies
-
Fixed read-only loadstate error messages and logic
-
-
-
Lua
-
-
Lua socket added to built-in lua library
-
Fixed speed.mode() function so that normal turns off turbo
-
-
-
New Lua functions
-
-
gui.savescreenshotas()
-
sound.get()
-
-
-
Win32
-
-
Fixed bug where PPU toggling toggled the Game Genie as well
-
Fixed some minor GUI issues
-
Added avi capture commandline argument and related parameters
-
Fix input selection for Famicom Expansion port
-
-
-
Debugger
-
-
-
Fixed Ram Search to only display valid RAM addresses (0000-07FF and 6000-7FFF)
-
Fixed crash when re-opening debugging window
-
-
-
Hex Editor
-
-
-
Added a confirmation prompt before removing all bookmarks
-
-
-
Ram Watch / Ram Search
-
-
-
Fixed the multiple selection of watches
-
Added support for Multiple selection of addresses in RamWatch Fixed issue with restoration of the selection range in RamWatch
-
-
-
TasEdit
-
-
-
General cleanup
-
Fixed crash when truncating while turbo was enabled
-
Invalidate greenzone when re-recording earlier portions of a movie
The 2.1.5 release fixes a lot of bugs and brings various improvements to the prior 2.1.4a release. In addition, the SDL port has improved signficantly; completely overhauling the GTK2 GUI, fixing many sound issues, and fixing a variety of bugs.
+
+
Common
+
+
Fixed compatibility issue with Young Indiana Jones Chronicles
+
Fixed bug in new PPU that made some intensify bits not get applied to output (fixed flashing siren screen in Werefolf)
+
Fix many segmentation faults related to file handling
+
+
+
Movies
+
+
+
Slight performance increase when loading movies
+
Fixed read-only loadstate error messages and logic
+
+
+
Lua
+
+
Lua socket added to built-in lua library
+
Fixed speed.mode() function so that normal turns off turbo
+
+
+
New Lua functions
+
+
gui.savescreenshotas()
+
sound.get()
+
+
+
Win32
+
+
Fixed bug where PPU toggling toggled the Game Genie as well
+
Fixed some minor GUI issues
+
Added avi capture commandline argument and related parameters
+
Fix input selection for Famicom Expansion port
+
+
+
Debugger
+
+
+
Fixed Ram Search to only display valid RAM addresses (0000-07FF and 6000-7FFF)
+
Fixed crash when re-opening debugging window
+
+
+
Hex Editor
+
+
+
Added a confirmation prompt before removing all bookmarks
+
+
+
Ram Watch / Ram Search
+
+
+
Fixed the multiple selection of watches
+
Added support for Multiple selection of addresses in RamWatch Fixed issue with restoration of the selection range in RamWatch
+
+
+
TasEdit
+
+
+
General cleanup
+
Fixed crash when truncating while turbo was enabled
+
Invalidate greenzone when re-recording earlier portions of a movie
The 2.2.0 release fixes a lot of bugs and adds many new features to prior releases, increasing game compatibility and enhancing usability of both Windows and SDL ports. The Windows version also includes major improvement of debugging tools and introduces the new powerful toolset – TAS Editor v1.0 – created to boost efficiency and ease of Tool-Assisted Speedrunning.
-
-
Common
-
-
Fixed crash when using machine with no sound card
-
Fixed long savestate messages containing path
-
Soft reset and power switch messages
-
All onscreen messages are now logged to Message Log
-
Fixed wrong default palette entry
-
Fixed bug when loading UNIF games
-
Improved HUD text rendering wrapping
-
"Display FPS" option
-
-
-
Emulation
-
-
PAL/NTSC noise channel bug fixed
-
All latest mapper changes from fceu-mm
-
Also added mappers 176, 116, 156, 252, 28
-
Fixed mappers 242, 227, 115, 248, 12, 164, 15, 253, 23, 178, 90, 73 and many others
-
Straighten out bandai m159/m016 handling and add valid null-EEPROM emulation to get those games booting.
-
Add ability for CNROM games to choose whether they have bus conflicts (fixes Colorful Dragon (Unl) (Sachen), since it flakes out if bus conflicts are emulated)
-
Fixed bus conflict emulation, no kage no densetsu bug anymore
-
Fixed newppu bug which prevented metroid from booting, CHR RAM was not getting initialized to anything
-
Newppu - fix bug in scroll reg logic causing mis-scrolls in p'radikus conflict
-
-
-
Movies
-
-
Fixed old bug in "Play Movie From Beginning"
-
Fixed replay engine bug that doubles the last input of the movie
-
Fixed movie savestates logic, loading post-movie savestates from different timeline is not allowed in read-only
-
Fixed savestates filenaming bug when working with a movie
-
Added support for HUD recording in AVI dumping
-
Rerecords counter display
-
Config->Movie options->Always suggest Read-Only replay (for Replay dialog). No more accidental rewrites!
-
Removed "Lag Counter Reset" hotkey, as it was obsolete since FCEUX 2.0.2
-
-
-
Lua
-
-
Fixed lua drawing alpha blending
-
Auto-clearing previous frame drawings (same behaviour as other emulators)
-
New library: taseditor (Windows-only) - contains 24 functions, see taseditor.chm
-
-
-
New Lua functions:
-
-
emu.paused()
-
emu.setlagflag()
-
joypad.getimmediate()
-
-
-
New scripts:
-
-
BoulderDash_AmoebaAI.lua
-
ButtonCount.lua
-
CustomLagIndicator_RvT.lua
-
RBIBaseball.lua
-
SoundDisplay.lua
-
SoundDisplay2.lua
-
taseditor\InputDisplay_for_Selection.lua
-
taseditor\InvertSelection.lua
-
taseditor\RecordBackwards.lua
-
taseditor\ShowNotes.lua
-
taseditor\Swap1P2P.lua
-
taseditor\TrackNoise.lua
-
-
-
Win32
-
-
Total revamp of fulscreen support
-
Fixed graphic tearing with vertical sync enabled
-
Added "Maintain aspect ratio" option to Video config
-
Added "Hide mouse cursor" and "Use console BG color for empty areas" options to Video config
-
Added "Switch fullscreen by double-click" option to GUI config
-
Added "Force Grayscale" option to Palette config
-
Fixed crashes and bugs caused by 2.1.5 allowing hotkeys without ROM loaded
-
Lua console now gets proper file path when selecting a file from the recent menu
-
Fixed context menus to use rightclicks in context menus correctly
-
Reload hotkey now also supports removing invalid filenames in Recent ROMs
-
Replay dialog speedup, it doesn't search for movies in fceux root folder anymore
-
Support multibyte languages for opening files through drag&drop (except for Lua files)
-
Loading TAS Editor projects (*.fm3) by drag&drop
-
Fixed bug with Input Config not displaying some key names
-
Launch tools hotkeys shown in menu; general cleanup of menu/settings, changed some checkboxes to radiobuttons
-
Added "Clear" button to Message Log
-
-
-
TAS Editor
-
-
Completely rewritten tool with brand new architecture and design. Too many changes to enlist, see taseditor.chm
-
-
-
Debugger
-
-
General window layout cleanup; different font; ".DEB files" can be switched off; etc
-
Deleting a breakpoint/bookmark leaves selection in the list
-
Fixed mysterious out of bounds condition while editing breakpoints
-
Fixed RAM peek by a rightclick on left pane
-
Allow Frame Advancing when Debugger is in breakpoint state
-
Disabled breakpoints now don't impose slowdown
-
When a breakpoint is hit, it becomes highlighed (selected) in the breakpoints list
-
Show the number of breakpoints (enabled and total) above the breakpoints list
-
">" points at current line in disassembly
-
Improved stack display
-
Added "CPU cycles" and "Instructions" counters (cumulative and delta)
-
Added "Cycles counter exceeds N" and "Instructions counter exceeds N" type of breakpoints
-
Single click on any address copies this address to the "Seek To" field and "Bookmark Add" field
-
Double-click on any address prompts "Add Breakpoint here" dialog
-
"ROM offsets" option displays real ROM addresses in the Disassembly window
-
Fixed conditional breakpoints bug: the error message didn't appear when editing a breakpoint
-
Fixed and improved Symbolic debug (Names and Comments display)
-
Added Bookmarks naming
-
Cleaned up and vastly improved debugging documentation
-
-
-
Trace Logger
-
-
Added "Symbolic trace" option
-
"RTS" instructions now output the subroutine address/name
-
Added "Use Stack Pointer for code tabbing (nesting visualization)" option
-
Added "To the left from disassembly text" option for log format customization
-
Added "Log current Frame number" option
-
Added "Log emulator messages" option
-
Added "Log breakpoint hits" option
-
Fixed bug with trying to log to file without choosing a filename
-
Tracer now also updates its window when user pauses the game, not just when Debugger snaps
The 2.2.0 release fixes a lot of bugs and adds many new features to prior releases, increasing game compatibility and enhancing usability of both Windows and SDL ports. The Windows version also includes major improvement of debugging tools and introduces the new powerful toolset – TAS Editor v1.0 – created to boost efficiency and ease of Tool-Assisted Speedrunning.
+
+
Common
+
+
Fixed crash when using machine with no sound card
+
Fixed long savestate messages containing path
+
Soft reset and power switch messages
+
All onscreen messages are now logged to Message Log
+
Fixed wrong default palette entry
+
Fixed bug when loading UNIF games
+
Improved HUD text rendering wrapping
+
"Display FPS" option
+
+
+
Emulation
+
+
PAL/NTSC noise channel bug fixed
+
All latest mapper changes from fceu-mm
+
Also added mappers 176, 116, 156, 252, 28
+
Fixed mappers 242, 227, 115, 248, 12, 164, 15, 253, 23, 178, 90, 73 and many others
+
Straighten out bandai m159/m016 handling and add valid null-EEPROM emulation to get those games booting.
+
Add ability for CNROM games to choose whether they have bus conflicts (fixes Colorful Dragon (Unl) (Sachen), since it flakes out if bus conflicts are emulated)
+
Fixed bus conflict emulation, no kage no densetsu bug anymore
+
Fixed newppu bug which prevented metroid from booting, CHR RAM was not getting initialized to anything
+
Newppu - fix bug in scroll reg logic causing mis-scrolls in p'radikus conflict
+
+
+
Movies
+
+
Fixed old bug in "Play Movie From Beginning"
+
Fixed replay engine bug that doubles the last input of the movie
+
Fixed movie savestates logic, loading post-movie savestates from different timeline is not allowed in read-only
+
Fixed savestates filenaming bug when working with a movie
+
Added support for HUD recording in AVI dumping
+
Rerecords counter display
+
Config->Movie options->Always suggest Read-Only replay (for Replay dialog). No more accidental rewrites!
+
Removed "Lag Counter Reset" hotkey, as it was obsolete since FCEUX 2.0.2
+
+
+
Lua
+
+
Fixed lua drawing alpha blending
+
Auto-clearing previous frame drawings (same behaviour as other emulators)
+
New library: taseditor (Windows-only) - contains 24 functions, see taseditor.chm
+
+
+
New Lua functions:
+
+
emu.paused()
+
emu.setlagflag()
+
joypad.getimmediate()
+
+
+
New scripts:
+
+
BoulderDash_AmoebaAI.lua
+
ButtonCount.lua
+
CustomLagIndicator_RvT.lua
+
RBIBaseball.lua
+
SoundDisplay.lua
+
SoundDisplay2.lua
+
taseditor\InputDisplay_for_Selection.lua
+
taseditor\InvertSelection.lua
+
taseditor\RecordBackwards.lua
+
taseditor\ShowNotes.lua
+
taseditor\Swap1P2P.lua
+
taseditor\TrackNoise.lua
+
+
+
Win32
+
+
Total revamp of fulscreen support
+
Fixed graphic tearing with vertical sync enabled
+
Added "Maintain aspect ratio" option to Video config
+
Added "Hide mouse cursor" and "Use console BG color for empty areas" options to Video config
+
Added "Switch fullscreen by double-click" option to GUI config
+
Added "Force Grayscale" option to Palette config
+
Fixed crashes and bugs caused by 2.1.5 allowing hotkeys without ROM loaded
+
Lua console now gets proper file path when selecting a file from the recent menu
+
Fixed context menus to use rightclicks in context menus correctly
+
Reload hotkey now also supports removing invalid filenames in Recent ROMs
+
Replay dialog speedup, it doesn't search for movies in fceux root folder anymore
+
Support multibyte languages for opening files through drag&drop (except for Lua files)
+
Loading TAS Editor projects (*.fm3) by drag&drop
+
Fixed bug with Input Config not displaying some key names
+
Launch tools hotkeys shown in menu; general cleanup of menu/settings, changed some checkboxes to radiobuttons
+
Added "Clear" button to Message Log
+
+
+
TAS Editor
+
+
Completely rewritten tool with brand new architecture and design. Too many changes to enlist, see taseditor.chm
+
+
+
Debugger
+
+
General window layout cleanup; different font; ".DEB files" can be switched off; etc
+
Deleting a breakpoint/bookmark leaves selection in the list
+
Fixed mysterious out of bounds condition while editing breakpoints
+
Fixed RAM peek by a rightclick on left pane
+
Allow Frame Advancing when Debugger is in breakpoint state
+
Disabled breakpoints now don't impose slowdown
+
When a breakpoint is hit, it becomes highlighed (selected) in the breakpoints list
+
Show the number of breakpoints (enabled and total) above the breakpoints list
+
">" points at current line in disassembly
+
Improved stack display
+
Added "CPU cycles" and "Instructions" counters (cumulative and delta)
+
Added "Cycles counter exceeds N" and "Instructions counter exceeds N" type of breakpoints
+
Single click on any address copies this address to the "Seek To" field and "Bookmark Add" field
+
Double-click on any address prompts "Add Breakpoint here" dialog
+
"ROM offsets" option displays real ROM addresses in the Disassembly window
+
Fixed conditional breakpoints bug: the error message didn't appear when editing a breakpoint
+
Fixed and improved Symbolic debug (Names and Comments display)
+
Added Bookmarks naming
+
Cleaned up and vastly improved debugging documentation
+
+
+
Trace Logger
+
+
Added "Symbolic trace" option
+
"RTS" instructions now output the subroutine address/name
+
Added "Use Stack Pointer for code tabbing (nesting visualization)" option
+
Added "To the left from disassembly text" option for log format customization
+
Added "Log current Frame number" option
+
Added "Log emulator messages" option
+
Added "Log breakpoint hits" option
+
Fixed bug with trying to log to file without choosing a filename
+
Tracer now also updates its window when user pauses the game, not just when Debugger snaps
The 2.2.1 release fixes many bugs and adds a couple of new features. The most notable feature is "Auto-resume old play session", which is similar to "Suspending Play". Enable this option in the Config menu and now you can close ROMs or emulator anytime, next time the game state will be resumed from the closing point.
-
-
Common
-
-
Speed up HUD text drawing
-
-
-
Emulation
-
-
Finished mappers to boards conversion
-
Fixed mappers 99, 228, 18, 198, 24, 26, 69, 19
-
Mapper 115 - redesign according to the hardware tests
-
Fixed "you ling xing dong" by assigning to mapper 192
-
Fixed crash when four-screen bit is set after CRC check
-
UNIF: verbose/safe chunk loading, fixes some crashes
-
-
-
Lua
-
-
removed "shadow pixels" from gui.text()
-
-
-
New Lua functions:
-
-
gui.parsecolor()
-
-
-
New scripts:
-
-
JumpingFCEUXWindow.lua
-
-
-
Win32
-
-
Fixed "Enter New Input" dialog (Hotkeys mapping)
-
Fixed zapper and mouse positioning in fullscreen
-
Remodel "Video config" dialog
-
Added "TV Aspect (4:3)"
-
Holding Shift when resizing FCEUX window inverts "Force integral factors" meaning
-
Fixed window regions redrawing
-
Added the option to define custom emulation speed (NES->Emulation Speed->Set Custom Speed)
-
Now Frame Advance timings (initial delay and speed) can be tweaked by user
-
Added Config->Enable->Auto-resume old play session
-
Moved "Config->Game Genie" to "Config->Enable->Game Genie ROM"
-
Play movie dialog shows New PPU in red if the required setting does not match
-
Fixed NameTable Viewer crash when the corresponding nametable RAM is not available on the cart
-
The number of active cheats is displayed on screen when a ROM is loaded
-
PPU/PAL/Input type changing is disabled when a movie is playing
-
-
-
TAS Editor
-
-
Fixed keyboard accelerators when editing Notes
-
Fixed Greenzone saving while emulator is unpaused
-
Fixed drawing bugs when the Playback cursor moves more than once within one update
-
Changed "Compact save" dialog, added 4 options of Greenzone saving
-
Added "Config->Project file saving options"
-
Changed "Follow cursor" logic, now the Piano Roll doesn't follow Playback cursor while seeking
-
No "Autopause at the end of the Movie" when Recording
-
Fixed bug when adding new item to History Log
-
Fixed Bookmarks List height on Windows 7
-
-
-
Trace Logger
-
-
Fixed RAM-located code logging when CDLogger options are enabled
-
Fixed automatic window update when a breakpoint is hit
-
Fixed RTS padding
-
-
-
Code/Data Logger
-
-
Added current CDL filename field and default CDL naming
-
Added "Auto-save .CDL when closing ROMs" option
-
Added "Auto-load .CDL when opening the window" option
-
Added "Auto-resume logging when loading ROMs" option
-
Improved CHR logging, now it also logs the data when using Old PPU
-
-
-
Hex Editor
-
-
Show symbolic names in the window caption when "Symbolic debug" is enabled
-
Fixed crash when trying to save ROM to an invalid path
-
Fixed ROM coloring when using CDLogger data
-
-
-
RAM Search
-
-
Added "Search ROM" option
-
-
-
Cheats
-
-
Added "Add from CHT file..." button
-
Update the list of cheats when ROM is changed
-
-
-
SDL
-
-
Use desktop resolution for fullscreen by setting SDL.XResolution and SDL.YResolution to 0 (new default is 0)
-
Fixed bug where "quit" hotkey would do nothing in '--nogui' mode
-
Fixed fullscreen zapper issues
-
Display a message dialog on errors in addition to printing to stderr
The 2.2.1 release fixes many bugs and adds a couple of new features. The most notable feature is "Auto-resume old play session", which is similar to "Suspending Play". Enable this option in the Config menu and now you can close ROMs or emulator anytime, next time the game state will be resumed from the closing point.
+
+
Common
+
+
Speed up HUD text drawing
+
+
+
Emulation
+
+
Finished mappers to boards conversion
+
Fixed mappers 99, 228, 18, 198, 24, 26, 69, 19
+
Mapper 115 - redesign according to the hardware tests
+
Fixed "you ling xing dong" by assigning to mapper 192
+
Fixed crash when four-screen bit is set after CRC check
+
UNIF: verbose/safe chunk loading, fixes some crashes
+
+
+
Lua
+
+
removed "shadow pixels" from gui.text()
+
+
+
New Lua functions:
+
+
gui.parsecolor()
+
+
+
New scripts:
+
+
JumpingFCEUXWindow.lua
+
+
+
Win32
+
+
Fixed "Enter New Input" dialog (Hotkeys mapping)
+
Fixed zapper and mouse positioning in fullscreen
+
Remodel "Video config" dialog
+
Added "TV Aspect (4:3)"
+
Holding Shift when resizing FCEUX window inverts "Force integral factors" meaning
+
Fixed window regions redrawing
+
Added the option to define custom emulation speed (NES->Emulation Speed->Set Custom Speed)
+
Now Frame Advance timings (initial delay and speed) can be tweaked by user
+
Added Config->Enable->Auto-resume old play session
+
Moved "Config->Game Genie" to "Config->Enable->Game Genie ROM"
+
Play movie dialog shows New PPU in red if the required setting does not match
+
Fixed NameTable Viewer crash when the corresponding nametable RAM is not available on the cart
+
The number of active cheats is displayed on screen when a ROM is loaded
+
PPU/PAL/Input type changing is disabled when a movie is playing
+
+
+
TAS Editor
+
+
Fixed keyboard accelerators when editing Notes
+
Fixed Greenzone saving while emulator is unpaused
+
Fixed drawing bugs when the Playback cursor moves more than once within one update
+
Changed "Compact save" dialog, added 4 options of Greenzone saving
+
Added "Config->Project file saving options"
+
Changed "Follow cursor" logic, now the Piano Roll doesn't follow Playback cursor while seeking
+
No "Autopause at the end of the Movie" when Recording
+
Fixed bug when adding new item to History Log
+
Fixed Bookmarks List height on Windows 7
+
+
+
Trace Logger
+
+
Fixed RAM-located code logging when CDLogger options are enabled
+
Fixed automatic window update when a breakpoint is hit
+
Fixed RTS padding
+
+
+
Code/Data Logger
+
+
Added current CDL filename field and default CDL naming
+
Added "Auto-save .CDL when closing ROMs" option
+
Added "Auto-load .CDL when opening the window" option
+
Added "Auto-resume logging when loading ROMs" option
+
Improved CHR logging, now it also logs the data when using Old PPU
+
+
+
Hex Editor
+
+
Show symbolic names in the window caption when "Symbolic debug" is enabled
+
Fixed crash when trying to save ROM to an invalid path
+
Fixed ROM coloring when using CDLogger data
+
+
+
RAM Search
+
+
Added "Search ROM" option
+
+
+
Cheats
+
+
Added "Add from CHT file..." button
+
Update the list of cheats when ROM is changed
+
+
+
SDL
+
+
Use desktop resolution for fullscreen by setting SDL.XResolution and SDL.YResolution to 0 (new default is 0)
+
Fixed bug where "quit" hotkey would do nothing in '--nogui' mode
+
Fixed fullscreen zapper issues
+
Display a message dialog on errors in addition to printing to stderr
The 2.2.3 release fixes a number of emulation bugs, features overclocking (for lag reduction) and Dendy mode, and adds support for a bunch of new ROM dumps (mostly unlicensed). Reverse engineering tools and Lua scripting have got some updates, new input devices are supported, new palette files have beed added. The SDL port has been fixed and updated as well.
Fixed a bug with FDS flag being always set when converting a FCM
-
-
-
Video
-
-
Prescale filter for 2x, 3x and 4x resolutions
-
Made NTSC filter internal resolution closer to 4:3
-
-
-
Palette
-
-
Support 512 color palettes
-
Added external palettes: SONY_CXA2025AS_US.pal, RP2C03.pal (and its versions), Unsaturated-V6.pal
-
Option to swap deemphasis bits
-
-
-
Sound
-
-
Option to swap duty cycles
-
NSF can be set to Dendy mode
-
-
-
Input
-
-
Fix Mouse input implementation
-
Support for SNES mouse
-
PEC-586 russian keyboard support
-
-
-
Lua
-
-
Removed speed notification per script reload, if it remained 100%
-
Fixed lua drawings in NSF
-
Proper halo for lua font
-
Fixes to sound.get() region consistency and frequency/midikey detection for Noise and DPCM channels
-
-
-
New Lua functions:
-
-
emu.getpath()
-
emu.loadrom()
-
rom.writebyte()
-
gethash()
-
-
-
Win32
-
-
Added -dumpinput and -playinput functions
-
Support for SNES pad
-
Added onscreen messages when region changes
-
-
-
Debugger
-
-
Added debuggerPageSize config variable which lets you pick whether 8KB physical PRG pages are used, or 16KB (the original). It defaults to 14 (1<<14 == 16KB).
-
Set symbolic debugger name entry dialog text limits when creating a new label
-
Fixed new-PPU debug information (address and pixel)
-
Step Into hotkey
-
More granular accounting of scanline and dot
-
-
-
Trace Logger
-
-
Fixed incorrect display of resolved address for (FF,x)
-
-
-
Symbolic debugging
-
-
Optionally display register names
-
-
-
CDLogger
-
-
Fix crash when attempting to open file picked as target for Save Stripped ROM operation
-
-
-
PPU Viewer
-
-
8x16 sprite display mode
-
-
-
Hex Editor
-
-
Added option to dump entire 64k memory space
-
Don't forget to load the symbols, when hex editor is first launched before debugger
-
Show values for registers $4000-$4017
-
-
-
Cheats
-
-
mmc5 Akumajou Dracula crash fix
-
More RAM available in search
-
-
-
SDL
-
-
Added apply button to video config dialog
-
Added link to libgd project download page in readme
-
Noted optional libgd dependency in readme
-
SCons: Fixed logic for LOGO and CREATE_AVI options
-
Manpage updates
-
Added hotkeys for volume up/down
-
Menu toggling with the Alt key
-
Print error when opengl/scalers are both enabled
-
Fixed bug where lua open file gui would default to home directory
The 2.2.3 release fixes a number of emulation bugs, features overclocking (for lag reduction) and Dendy mode, and adds support for a bunch of new ROM dumps (mostly unlicensed). Reverse engineering tools and Lua scripting have got some updates, new input devices are supported, new palette files have beed added. The SDL port has been fixed and updated as well.
Fixed a bug with FDS flag being always set when converting a FCM
+
+
+
Video
+
+
Prescale filter for 2x, 3x and 4x resolutions
+
Made NTSC filter internal resolution closer to 4:3
+
+
+
Palette
+
+
Support 512 color palettes
+
Added external palettes: SONY_CXA2025AS_US.pal, RP2C03.pal (and its versions), Unsaturated-V6.pal
+
Option to swap deemphasis bits
+
+
+
Sound
+
+
Option to swap duty cycles
+
NSF can be set to Dendy mode
+
+
+
Input
+
+
Fix Mouse input implementation
+
Support for SNES mouse
+
PEC-586 russian keyboard support
+
+
+
Lua
+
+
Removed speed notification per script reload, if it remained 100%
+
Fixed lua drawings in NSF
+
Proper halo for lua font
+
Fixes to sound.get() region consistency and frequency/midikey detection for Noise and DPCM channels
+
+
+
New Lua functions:
+
+
emu.getpath()
+
emu.loadrom()
+
rom.writebyte()
+
gethash()
+
+
+
Win32
+
+
Added -dumpinput and -playinput functions
+
Support for SNES pad
+
Added onscreen messages when region changes
+
+
+
Debugger
+
+
Added debuggerPageSize config variable which lets you pick whether 8KB physical PRG pages are used, or 16KB (the original). It defaults to 14 (1<<14 == 16KB).
+
Set symbolic debugger name entry dialog text limits when creating a new label
+
Fixed new-PPU debug information (address and pixel)
+
Step Into hotkey
+
More granular accounting of scanline and dot
+
+
+
Trace Logger
+
+
Fixed incorrect display of resolved address for (FF,x)
+
+
+
Symbolic debugging
+
+
Optionally display register names
+
+
+
CDLogger
+
+
Fix crash when attempting to open file picked as target for Save Stripped ROM operation
+
+
+
PPU Viewer
+
+
8x16 sprite display mode
+
+
+
Hex Editor
+
+
Added option to dump entire 64k memory space
+
Don't forget to load the symbols, when hex editor is first launched before debugger
+
Show values for registers $4000-$4017
+
+
+
Cheats
+
+
mmc5 Akumajou Dracula crash fix
+
More RAM available in search
+
+
+
SDL
+
+
Added apply button to video config dialog
+
Added link to libgd project download page in readme
+
Noted optional libgd dependency in readme
+
SCons: Fixed logic for LOGO and CREATE_AVI options
+
Manpage updates
+
Added hotkeys for volume up/down
+
Menu toggling with the Alt key
+
Print error when opengl/scalers are both enabled
+
Fixed bug where lua open file gui would default to home directory
This differs from the previous FCE Ultra movie format (.fcm) in the following ways:
-
-
It is text based by default; allowing easy movie editing/splicing
-
An imbedded GUID so FCEUX can tell if a savestate belongs to a movie file
-
Movies recorded from Start (Power-on) no longer have a redundant savestate
-
Contains mouse input for recording the Zapper & Arkanoid Paddle
-
-
-
-
Format
-
-
FM2 consists of two parts: Header and Input Log.
-
The header is always in ASCII plain text format. It consists of several key-value pairs.
-
The input log section can be identified by it starting with a | (pipe).
-
The input log section can be either in ASCII plain text format or in binary format.
-
The input log section terminates at EOF, unless the length key is specified in header.
-
Newlines may be \r\n or \n.
-
-
-
Header
-
-
Key-value pairs consist of a key identifier, followed by a space separator, followed by the value text.
-
Value text is always terminated by a newline, which the value text does not include.
-
The value text is parsed differently depending on the type of the key.
-
The key-value pairs may be in any order, except that the first key must be version.
-
-
Integer keys (also used for booleans, with a 1 for true and 0 for false) must have a value that can be stored as int32:
-
-
- version (required) - the version of the movie file format; for now it is always 3
-
-
- emuVersion (required) - the version of the emulator used to produce the movie
-
-
- rerecordCount (optional) - the rerecord count
-
-
- palFlag (bool) (optional) - true if the movie uses PAL timing
-
-
- NewPPU (bool) (optional) - true if the movie uses New PPU
-
-
- FDS (bool) (optional) - true if movie was recorded on a Famicom Disk System (FDS) game
-
-
- fourscore (bool) - true if a fourscore was used. If fourscore is not used, then port0 and port1 are required
-
-
- port0 - indicates the type of input device attached to the port 0. Supported values are:
-
SI_NONE = 0
-
SI_GAMEPAD = 1
-
SI_ZAPPER = 2
-
-
- port1 - indicates the type of input device attached to the port 1. Supported values are:
-
SI_NONE = 0
-
SI_GAMEPAD = 1
-
SI_ZAPPER = 2
-
-
- port2 (required) - indicates the type of the FCExp port device which was attached. Supported values are:
-
SIFC_NONE = 0
-
-
- binary (bool) (optional) - true if input log is stored in binary format
-
-
- length (optional) - movie size (number of frames in the input log). If this key is specified and the number is >= 0, the input log ends after specified number of records, and any remaining data should not be parsed. This key is used in fm3 format to allow storing extra data after the end of input log
-
-
-
String keys have values that consist of the remainder of the key-value pair line. As a consequence, string values cannot contain newlines.
-
-
- romFilename (required) - the name of the file used to record the movie
-
-
- comment (optional) - simply a memo
-
-
by convention, the first token in the comment value is the subject of the comment
-
by convention, subsequent comments with the same subject should have their ordering preserved and may be used to approximate multi-line comments
-
by convention, the author of the movie should be stored in comment(s) with a subject of: author
-
-
Example:
-
-
comment author adelikat
-
-
-
- subtitle (optional) - a message that will be displayed on screen when movie is played back (unless Subtitles are turned off, see Movie options)
-
-
by convention, subtitles begin with the word "subtitle"
-
by convention, an integer value following the word "subtitle" indicates the frame that the subtitle will be displayed
-
by convention, any remaining text after the integer is considered to be the string displayed
-
-
Example:
-
-
subtitle 1000 Level Two
-
-
At frame 1000 the words "Level Two" will be displayed on the screen
-
-
- guid (required) - a unique identifier for a movie, generated when the movie is created, which is used when loading a savestate to make sure it belongs to the current movie
-
GUID keys have a value which is in the standard guide format: 452DE2C3-EF43-2FA9-77AC-0677FC51543B
-
-
- romChecksum (required) - the base64 of the hexified MD5 hash of the ROM which was used to record the movie
-
-
- savestate (optional) - a fcs savestate blob, in case a movie was recorded from savestate
-
Hex string keys (used for binary blobs) have a value that is like 0x0123456789ABCDEF...
-
-
-
Input log
-
-
The input log section consists of movie records either in the form of text lines or in the form of binary data.
-
-
-
Text format (default format):
-
-
Every frame of the movie is represented by line of text beginning and ending with a | (pipe).
-
The fields in the line are as follows, except when fourscore is used.
-
|commands|port0|port1|port2|
-
-
Field commands is a variable length decimal integer which is interpreted as a bit field corresponding to miscellaneous input states which are valid at the start of the frame. Current values for this are:
-
-
1 = Soft Reset
-
2 = Hard Reset (Power)
-
4 = FDS Disk Insert
-
8 = FDS Disk Select
-
16 = VS Insert Coin
-
-
-
The format of port0, port1, port2 depends on which types of devices were attached.
-
-
SI_GAMEPAD:
-
-
the field consists of eight characters which constitute a bit field
-
any character other than ' ' or '.' means that the button was pressed
-
by convention, the following mnemonics are used in a column to remind us of which button corresponds to which column: RLDUTSBA (Right, Left, Down, Up, sTart, Select, B, A)
-
-
-
SI_ZAPPER:
-
-
XXX YYY B Q Z
-
-
XXX: %03d, the x position of the mouse
-
YYY: %03d, the y position of the mouse
-
B: %1d, 1 if the mouse button is pressed; 0 if not
-
Q: %1d, an internal value used by the emulator's zapper code
-
Z: %d, a variable-length decimal integer; an internal value used by the emulator's zapper code
-
-
SI_NONE:
-
-
the field must be empty
-
-
-
If a fourscore is used, then port0 and port1 are irrelevant and ignored.
-
The input types must all be gamepads, and each input log record must be in the following format:
Every frame of the movie is represented by a record of a fixed length which can be determined by the devices on port0 and port1.
-
-
The first byte of each record stores "commands" bit field.
-
-
bit 0 = Soft Reset
-
bit 1 = Hard Reset (Power)
-
bit 2 = FDS Disk Insert
-
bit 3 = FDS Disk Select
-
bit 4 = VS Insert Coin
-
-
-
The remaining bytes in the record depend on which types of devices are attached to port0 and port1.
-
-
SI_GAMEPAD:
-
-
1 byte added to the size of record
-
bits of the byte represent the state of buttons (bit0 = A, bit1 = B, bit2 = Select, bit3 = sTart, bit4 = Up, bit5 = Down, bit6 = Left, bit7 = Right). If the bit is set, respective button is considered to be pressed, if the bit is clear, the button is not pressed
-
-
-
SI_ZAPPER:
-
-
12 bytes added to the size of record
-
1st byte - the x position of the mouse
-
2nd byte - the y position of the mouse
-
3rd byte - 1 if the mouse button is pressed; 0 if not
-
4th byte - an internal value used by the emulator's zapper code
-
bytes 5-12 (uint64) - an internal value used by the emulator's zapper code
-
-
-
SI_NONE:
-
-
0 bytes added to the size of record
-
-
-
If a fourscore is used, then port0 and port1 are irrelevant and ignored. 4 bytes are added to the size of record. The bits of the 1st byte represent the state of buttons of the 1st joypad (bit0 = A, bit1 = B, bit2 = Select, bit3 = sTart, bit4 = Up, bit5 = Down, bit6 = Left, bit7 = Right); bits of the 2nd byte represent the state of buttons of the 2nd joypad, and so on.
-
-
-
-
Notes:
-
-
A. All movies start from power-on, unless a savestate key-value is present.
This differs from the previous FCE Ultra movie format (.fcm) in the following ways:
+
+
It is text based by default; allowing easy movie editing/splicing
+
An imbedded GUID so FCEUX can tell if a savestate belongs to a movie file
+
Movies recorded from Start (Power-on) no longer have a redundant savestate
+
Contains mouse input for recording the Zapper & Arkanoid Paddle
+
+
+
+
Format
+
+
FM2 consists of two parts: Header and Input Log.
+
The header is always in ASCII plain text format. It consists of several key-value pairs.
+
The input log section can be identified by it starting with a | (pipe).
+
The input log section can be either in ASCII plain text format or in binary format.
+
The input log section terminates at EOF, unless the length key is specified in header.
+
Newlines may be \r\n or \n.
+
+
+
Header
+
+
Key-value pairs consist of a key identifier, followed by a space separator, followed by the value text.
+
Value text is always terminated by a newline, which the value text does not include.
+
The value text is parsed differently depending on the type of the key.
+
The key-value pairs may be in any order, except that the first key must be version.
+
+
Integer keys (also used for booleans, with a 1 for true and 0 for false) must have a value that can be stored as int32:
+
+
- version (required) - the version of the movie file format; for now it is always 3
+
+
- emuVersion (required) - the version of the emulator used to produce the movie
+
+
- rerecordCount (optional) - the rerecord count
+
+
- palFlag (bool) (optional) - true if the movie uses PAL timing
+
+
- NewPPU (bool) (optional) - true if the movie uses New PPU
+
+
- FDS (bool) (optional) - true if movie was recorded on a Famicom Disk System (FDS) game
+
+
- fourscore (bool) - true if a fourscore was used. If fourscore is not used, then port0 and port1 are required
+
+
- port0 - indicates the type of input device attached to the port 0. Supported values are:
+
SI_NONE = 0
+
SI_GAMEPAD = 1
+
SI_ZAPPER = 2
+
+
- port1 - indicates the type of input device attached to the port 1. Supported values are:
+
SI_NONE = 0
+
SI_GAMEPAD = 1
+
SI_ZAPPER = 2
+
+
- port2 (required) - indicates the type of the FCExp port device which was attached. Supported values are:
+
SIFC_NONE = 0
+
+
- binary (bool) (optional) - true if input log is stored in binary format
+
+
- length (optional) - movie size (number of frames in the input log). If this key is specified and the number is >= 0, the input log ends after specified number of records, and any remaining data should not be parsed. This key is used in fm3 format to allow storing extra data after the end of input log
+
+
+
String keys have values that consist of the remainder of the key-value pair line. As a consequence, string values cannot contain newlines.
+
+
- romFilename (required) - the name of the file used to record the movie
+
+
- comment (optional) - simply a memo
+
+
by convention, the first token in the comment value is the subject of the comment
+
by convention, subsequent comments with the same subject should have their ordering preserved and may be used to approximate multi-line comments
+
by convention, the author of the movie should be stored in comment(s) with a subject of: author
+
+
Example:
+
+
comment author adelikat
+
+
+
- subtitle (optional) - a message that will be displayed on screen when movie is played back (unless Subtitles are turned off, see Movie options)
+
+
by convention, subtitles begin with the word "subtitle"
+
by convention, an integer value following the word "subtitle" indicates the frame that the subtitle will be displayed
+
by convention, any remaining text after the integer is considered to be the string displayed
+
+
Example:
+
+
subtitle 1000 Level Two
+
+
At frame 1000 the words "Level Two" will be displayed on the screen
+
+
- guid (required) - a unique identifier for a movie, generated when the movie is created, which is used when loading a savestate to make sure it belongs to the current movie
+
GUID keys have a value which is in the standard guide format: 452DE2C3-EF43-2FA9-77AC-0677FC51543B
+
+
- romChecksum (required) - the base64 of the hexified MD5 hash of the ROM which was used to record the movie
+
+
- savestate (optional) - a fcs savestate blob, in case a movie was recorded from savestate
+
Hex string keys (used for binary blobs) have a value that is like 0x0123456789ABCDEF...
+
+
+
Input log
+
+
The input log section consists of movie records either in the form of text lines or in the form of binary data.
+
+
+
Text format (default format):
+
+
Every frame of the movie is represented by line of text beginning and ending with a | (pipe).
+
The fields in the line are as follows, except when fourscore is used.
+
|commands|port0|port1|port2|
+
+
Field commands is a variable length decimal integer which is interpreted as a bit field corresponding to miscellaneous input states which are valid at the start of the frame. Current values for this are:
+
+
1 = Soft Reset
+
2 = Hard Reset (Power)
+
4 = FDS Disk Insert
+
8 = FDS Disk Select
+
16 = VS Insert Coin
+
+
+
The format of port0, port1, port2 depends on which types of devices were attached.
+
+
SI_GAMEPAD:
+
+
the field consists of eight characters which constitute a bit field
+
any character other than ' ' or '.' means that the button was pressed
+
by convention, the following mnemonics are used in a column to remind us of which button corresponds to which column: RLDUTSBA (Right, Left, Down, Up, sTart, Select, B, A)
+
+
+
SI_ZAPPER:
+
+
XXX YYY B Q Z
+
+
XXX: %03d, the x position of the mouse
+
YYY: %03d, the y position of the mouse
+
B: %1d, 1 if the mouse button is pressed; 0 if not
+
Q: %1d, an internal value used by the emulator's zapper code
+
Z: %d, a variable-length decimal integer; an internal value used by the emulator's zapper code
+
+
SI_NONE:
+
+
the field must be empty
+
+
+
If a fourscore is used, then port0 and port1 are irrelevant and ignored.
+
The input types must all be gamepads, and each input log record must be in the following format:
Every frame of the movie is represented by a record of a fixed length which can be determined by the devices on port0 and port1.
+
+
The first byte of each record stores "commands" bit field.
+
+
bit 0 = Soft Reset
+
bit 1 = Hard Reset (Power)
+
bit 2 = FDS Disk Insert
+
bit 3 = FDS Disk Select
+
bit 4 = VS Insert Coin
+
+
+
The remaining bytes in the record depend on which types of devices are attached to port0 and port1.
+
+
SI_GAMEPAD:
+
+
1 byte added to the size of record
+
bits of the byte represent the state of buttons (bit0 = A, bit1 = B, bit2 = Select, bit3 = sTart, bit4 = Up, bit5 = Down, bit6 = Left, bit7 = Right). If the bit is set, respective button is considered to be pressed, if the bit is clear, the button is not pressed
+
+
+
SI_ZAPPER:
+
+
12 bytes added to the size of record
+
1st byte - the x position of the mouse
+
2nd byte - the y position of the mouse
+
3rd byte - 1 if the mouse button is pressed; 0 if not
+
4th byte - an internal value used by the emulator's zapper code
+
bytes 5-12 (uint64) - an internal value used by the emulator's zapper code
+
+
+
SI_NONE:
+
+
0 bytes added to the size of record
+
+
+
If a fourscore is used, then port0 and port1 are irrelevant and ignored. 4 bytes are added to the size of record. The bits of the 1st byte represent the state of buttons of the 1st joypad (bit0 = A, bit1 = B, bit2 = Select, bit3 = sTart, bit4 = Up, bit5 = Down, bit6 = Left, bit7 = Right); bits of the 2nd byte represent the state of buttons of the 2nd joypad, and so on.
+
+
+
+
Notes:
+
+
A. All movies start from power-on, unless a savestate key-value is present.
