     ______________  ________   ____    __  ___
    / ______/ _____\/ ____/ /  / /\ \  / / / _ \
   / /_____/ /     / /___/ /  / /  \ \/ / / / \ \
  / ______/ /     / ____/ /  / /    \  / / /  / /
 / /     / /_____/ /___/ /__/ /     /  \/ /__/ /
/_/      \______/_____/\_____/     / /\_\_____/
                                  / /
  FCE Ultra Extended Debugger    /_/  version 1.0a
        by bbitmaster

This document originally written by bbitmaster and DahrkDaiz, and rewritten and
revised by Vystrix Nexoth.

--------------------------------

This document is divided into three sections:
	* Frequently-Asked Questions
	* General Usage Information
	* Credits

Please read the FAQ before asking me questions. That's why it's there.

##############################
# FREQUENTLY-ASKED QUESTIONS #
##############################

What is FCEUXD?
	FCEUXD is a NES emulator with several powerful debugging, hacking, and
	reverse-engineering tools.

How did FCEUXD get started?
	I don't really know much about the history of FCE Ultra (on which FCEUXD
	is based), but it goes something like this:

	A long time ago, there was an NES emulator named FCE (Family Computer
	Emulator) developed by a japanese person named Bero. And it was good.

	Then later, Xodnizel acquired the source and ported the program to
	Windows, and called it "FCE Ultra" (you can find a more detailed account
	of this in the FCE Ultra readme). And it was good.

	Then in 2002, Parasyte modified the then-current version (0.81.3, I
	believe) and added a Nesten-style debugger, along with several other
	features, and named it "FCEUD" (FCE Ultra Debugger). And it was good.

	And in January 2004, I (bbitmaster) began working on more features (as
	detailed in this document), and called it "FCEUXD" (FCE Ultra Extended
	Debugger).

	And it is good.

What new features are in FCEUXD?
	In addition to the Debugger and PPU Viewer from FCEUD, FCEUXD has a
	Trace Logger, a built-in Hex Editor, a Name Table Viewer and a Code/Data
	Logger.

What does the Trace Logger do?
	It logs every executed instruction either to a file or to the window.
	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.

What does the built-in Hex Editor do?
	Many things. It makes it easy to edit the game's RAM, PPU memory, and
	even its currently-loaded ROM data. You can also "freeze" parts of RAM
	(to prevent the game from modifying the data there), search for data,
	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.

What does the Code/Data Logger do?
	This is a very special feature I have planned; when finished, it should
	make it *much* easier to reverse-engineeer NES ROMs.
	The 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 stores this information in a .cdl file, which is
	essentially a mask that tells which bytes in the ROM are code and which
	are data. The file can then be used in conjunction with a suitable
	disassembler (which I plan to make) to disassemble only the actual game
	code, resulting in a much cleaner source code, with code and data
	properly separated.
	As of this release, the disassembler is not finished, and it may not be
	for a while. So, currently, the Code/Data Logger is useful only in that
	it can work in conjunction with the Trace Logger, so that it will only
	log code it has not already logged. In addition, it will let you save a
	"stripped" ROM file (see below), and finally, to distinguish between
	code and data bytes when working in the Hex Editor.

What is a "stripped" NES ROM file?
	This is a ROM formed only of the code and data that have been logged by
	the Code/Data Logger. For the most part, it is useless except for hack-
	ing and novelty purposes.

What is the deal with the pandas?
	Back in April 2004, FrenziedPanda stole a beta copy of FCEUXD from one
	of my beta-testers, and threatened to release it if I didn't give in to
	his demands. This has cost him his reputation among most of his friends.
	He is still lurking around, now under the name "BlueHawk".
	My advice to everyone is to avoid him.

Can you teach me ASM?
	Sorry, but no... I barely have enough time as it is, much of which is
	spent working on my projects.
	If you seriously would like to learn ASM, you should look around for
	some documents and tutorials; they are everywhere if you know how to use
	Google.

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, from which you can then
	edit it.

How do I add Game Genie codes?
	In the Game Genie Code decrypter/encrypter window, type the code into the
	Game Genie Code box and click "Add to Cheat List", which will add it to
	the Cheat Console cheat list. You can then enable/disable them by
	double-clicking the code in the box (a * means the code is active).

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 Decrypter/
	Encrypter 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
	Decrypter/Encrypter. Then enter the code as described above.

How do I make Game Genie codes permanent?
	Using the Game Genie Code Decrypter/Encrypter, 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
	decrypter/encrypter 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.

What does the Name Table Viewer do?
	Besides showing the Name Tables, the Name Table Viewer will also display
	the state of the PPU's scroll registers upon any given scanline, and
	will let you view and change the game's mirroring mode.

#############################
# GENERAL USAGE INFORMATION #
#############################

Before I begin, I will be making two assumptions.

First, I will assume you are are least somewhat familiar with FCEUD. Even if
you're not at all familiar with it, most of its features-- such as setting read/
write breakpoints and stepping through code-- are fairly intuitive. There are
already tutorials available that explain these things, so I will not cover them
again here.

Second, I will assume you are competent enough to figure out most of FCEUXD
without needing a manual -- in fact, I assume this to the point where I doubt
you have even read this document before digging in and trying things out. :)
I'm not going so far as to assume you're a genius, but I do assume you are at
least competent enough to do things like figuring out how to open the hex
editor, switching to ROM File Editing mode and editing it, and using Edit->Find,
without needing to consult the manual to do these things.

But even with these basic assumptions, there are many little things which I feel
deserve some explanation and clarification; hence this document.

THE DEBUGGER

	The debugger is the same as FCEUD's debugger, but with a few improve-
	ments:

	The size of the debugger window has been increased so that it shows 25
	lines instead of just 20.
	When you hold the mouse over the left pane in the debugger, you can now
	see the ROM file address of the data loaded there. If you right-click in
	that pane, it will bring up the Hex Editor at that address so you can
	immediately begin editing. Left-clicking in that pane brings up Para-
	stye's inline assembler.
	Another addition to the debugger is the "Break on bad opcode" feature;
	this can help you figure out where your game is crashing.
	Middle-clicking on a byte will bring up the Game Genie Encoder at that
	address, so you can easily make Game Genie codes.

	INLINE ASSEMBLER

		The debugger now has an Inline Assembler which Parasyte designed
		himself. To activate it, left-click in the left pane of the
		debugger, beside the assembly display.
		To use it, type in some code and press Enter to add it to the
		patch list. If you make a mistake, press "Undo".
		Once the patch is set up the way you want it, press "Apply". Be
		aware that this cannot be undone unless you reload the ROM.
		Parasyte implemented this feature before I had the Hex Editor
		working, otherwise I would have implemented a way to undo it
		from there.
		Press "Save" to write to the ROM file on disk; note that this
		will also save any changes you may have done in the Hex Editor.

PPU VIEWER

	The PPU viewer is exactly the same as FCEUD's, with two minor bugs that
	have been fixed:

	* FCEUD's PPU viewer, when activated, would corrupt color #0 in the NES
	  palette.
	* Parasyte left a very obvious mistake in the source, which caused it to
	  run slower. We have reprogrammed him and he is now a happy, productive
	  biological unit.

CHEAT SEARCHER

	The Cheat Searcher works essentially as in FCEUD, so I won't cover its
	usage. The only new addition is that if you do not supply a name for a
	cheat, a default one will be provided based on its Address and Value.

THE TRACE LOGGER

	The Trace Logger is a very nice feature which logs each instruction as
	it is being executed; this log can be output either to a file or the
	window.
	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 a window, the only time it shows the log is if
	you snap the debugger or pause execution (with F2). The option to auto-
	matically update the log window will keep the window updating while the
	game runs; this is normally useless unless it is working with the Code/
	Data Logger to only show newly-executed instructions.

	The Trace Logger has extra options which work with the Code/Data Logger
	so that it only shows instructions executed for the first time, or those
	which access data for the first time. This can be quite useful for find-
	ing 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, 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. (Sorry if that's too vague... I trust that you can
	figure it out.)

	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).

CODE/DATA LOGGER

	This is probably the most interesting feature of FCEUXD. It keeps track
	of every byte in the ROM and records whether it's code (is executed)
	or data (is read). In the future, I hope to combine this with a suitable
	disassembler that will disassemble only bytes marked as "code", in order
	to generate near-perfect source code (provided you play through the game
	several times, very thoroughly, to ensure everything gets logged). In
	order to get that feature to work, I need to get the Address Label
	Logger working, in order to create all the labels.

	But right now, it is very useful for finding specific code and data by
	using it with the Trace Logger (see above for instructions on doing
	this). Furthermore, while it is running, the Hex Editor will color-code
	bytes depending on whether they were logged as code or data. And it can
	also be used to create a stripped NES ROM (see below).

	Some notes: when you open another .cdl file, it does not clear the cur-
	rent log; instead, it combines it with the information in the file.
	This can be useful if you're trying to obtain a complete log, as multi-
	ple people can play through the game and keep code/data logs, and then
	the results can be combined.
	But if you would like to actually clear the code/data log, press the
	"Reset Log" button.

	A "stripped" NES ROM is one in which everything that was not logged by
	the code/data logger is removed. This may be just a novelty feature,
	however it can be useful because you can view the ROM in a Hex Editor,
	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.

	To do so, follow these steps:

	1. Open the Code/Data Logger, and press Start to begin logging.
	2. Perform a soft and a hard reset (F10 and F11) 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
	   (F10, F11) again while logging.
	4. Play through whatever levels you want present in the demo. 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, then if someone plays the stripped ROM and
	   attempts to perform that move, the game may very well crash or glitch
	   up.
	5. Save the stripped NES ROM.
	6. Rejoice, for it is done.

	CDL log files are just a mask of the PRG-ROM; that is, they are the
	same size as the PRG-ROM, and each byte represents the corresponding
	byte of the PRG-ROM.
	The format of each byte is like so (in binary):

		xPdcAADC

		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.

	CDL files make possible a number of things never before done.
	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 cor-
	ruptor that only corrupts data (by checking the 'D' bit).
	In any case, the Code/Data Logger opens many new possibilities for dis-
	covering useful things in games.

	Another interesting possibility (which isn't supported yet) 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.
	I might add this sometime, if I get any requests to do so.

HEX EDITOR

	The built-in Hex Editor is such a huge, powerful feature that it's hard
	to know here to begin describing it. Basically, it lets you tinker with
	any part of a game's RAM or ROM while it is running.

	The Hex Editor lets you edit three major areas:

	1. NES MEMORY
	This allows you to directly edit all of the NES's address space ($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.

	2. PPU MEMORY
	This allows you to directly view and write to PPU memory (VRAM).
	'Nuff said.

	3. THE ROM FILE
	This is possibly the coolest part of FCEUXD: it 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).
	If you have the Code/Data Logger running, then bytes that were logged as
	code will be colored yellow, while bytes logged as data will be colored
	blue. Bytes that have been logged as code *and* data will be colored
	green.

	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 repre-
	sents.
	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+Z (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.

GAME GENIE CODE ENCRYPTER/DECRYPTER

	This will take an NES address space PRG address ($8000-$FFFF), a comp-
	arison 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.

	For information on creating Game Genie codes or making them permanent,
	refer to the FAQ, above.

NAME TABLE VIEWER

	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).

	Note that the Name Table Viewer will display the name tables using what-
	ever 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 statusbar is
	displayed.

	Also note that the same applies to the Scroll Lines: they display the
	state of the PPU scroll registers when the "Display on Scanline" scan-
	line is reached. So for example if said scanline is within the game's
	statusbar, 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.

###########
# CREDITS #
###########

This is by no means an exhausive list; numerous people have contributed to
FCEUXD. I really hope no one important was forgotten here.

THE MAIN CREW:

	BBitmaster -- He, along with the help of many others, brought you FCEUXD
	Parasyte -- He created FCEUD, and added some nice features to FCEUXD
	Xodnizel -- He created FCEU
	Bero -- He created the original: FCE

EXTREMELY HELPFUL PEOPLE:

	DahrkDaiz
		Besides being a great lead beta tester, he offered many ideas,
		and was a great encouragement to keep bbit working on FCEUXD.
	Disch
		For being a strong supporter of the project, and for giving bbit
		the exact equation necessary to get the scroll lines to work in
		the Name Table Viewer.
	Vystrix Nexoth
		For using his excellent writing skills to create this nice read-
		me from some ugly drafts written by bbitmaster, and for leaving
		you wondering whether he (who typed this) said that himself or
		whether he just re-typed what bbit himself said.

THE BETA TESTERS:
	DahrkDaiz
	Disch
	drag
	Gavin
	Lenophis
	TFG
	Dan
	solid-tbone
	matrixz
	Vagla

And finally, *no* thanks to FrenziedPanda (a.k.a. BlueHawk, a.k.a. zooka), for
threatening the very existence of FCEUXD.
Remember, kids! The only good panda is a dead one.

###############
# THE END...? #
###############

Nah.