Nintendo never published how the NES worked. It wrote specifications for its licensed developers, but kept them private; everyone else had to find out for themselves. NESdev is the community that did. Over more than twenty-five years its members have taken the console apart instruction by instruction and, eventually, transistor by transistor, and written down what they found. The wiki they built introduces itself as “the source for all your NES programming needs”, and new NES games and emulators are written from it.
What makes it unusual is how much of the work is correction. The wiki keeps a page of “myths”: beliefs that came from early documents and emulators and turned out to be wrong. One is that an NTSC NES picture is 224 lines tall. It is 240 lines of picture, and “the PPU fetches and generates a signal for all 240 lines, even if TVs cut off the edges.”
Fast facts
- Earliest record: an NESdev mailing list whose archived postings begin on 22 January 1998.
- Where it lives: the NESdev Wiki, the NESdev forum, an IRC channel (#nesdev on EFnet) and a Discord server, all at nesdev.org.
- Covers: the 2A03 CPU and sound, the PPU, cartridge mappers, controllers and other input devices, the Famicom Disk System, file formats and emulator test programs.
- Licence: the wiki treats its content as public domain: “You can use the information from the wiki any way you want.”
- Sister wiki: SNESdev, for the Super NES, launched in 2022.
From text files to a wiki
The first NES documents were plain text files passed around the early emulation scene. Marat Fayzullin’s “NES.DOC” was the first to cover the machine’s internals. Fayzullin also wrote an early emulator, iNES, and his .nes file format for storing cartridge images is still the standard: a 16-byte header that begins with the letters “NES” and the MS-DOS end-of-file byte $1A, then gives the size of the program ROM in 16 KB units and of the graphics ROM in 8 KB units. The header’s mapper number, which tells an emulator what extra hardware the cartridge carried, began a numbering system that is still in use. A later extension, NES 2.0, added room for more mappers and larger ROMs.
Jeremy Chadwick, known as koitsu, expanded Fayzullin’s notes into his “Nintendo Entertainment System Documentation”, written, he explained, because at the time “there was only one piece of literature covering the internals” of the machine. His thanks list reads like a register of the early community, with names such as Kevin Horton, Loopy and Memblers. Memblers maintained the NESdev website, which collected these documents, NES programs and tools, alongside its message boards.
The documents grew sharper as people tested real hardware. Loopy’s “The Skinny on NES Scrolling” explained how the PPU’s scroll and address registers share internal state. In 2004 Brad Taylor released technical references for the 2A03 and the NTSC 2C02, and blargg an APU sound hardware reference. By June 2009 the site pointed visitors to a new NESdev Wiki, which gathered the documentation in one place. The old archive now opens with a warning: “The docs linked below are old and may contain inaccurate information.”
How the facts are found
The community also writes programs that test an emulator against the hardware. The wiki’s list names dozens, many by blargg, that check things like the timing of every official and unofficial 6502 instruction on the NES, the CPU’s behaviour during interrupts and its dummy reads. An emulator that passes them behaves like the hardware in those respects.
Some questions were settled by looking at the silicon itself. Quietust’s Visual 2C02, built on the core of the Visual 6502 project, is a transistor-level simulation of the NTSC PPU that “can be used to figure out exactly how the PPU operates under various circumstances”. The same care shows in details such as the MMC3 mapper, where NESdev records that the versions made by NEC and Sharp count scanlines differently and that some games were manufactured with both.
The wiki is also candid about the oddities of Ricoh’s 2A03. It notes that the chip “lacks the MOS6502’s decimal mode”, so the D flag can be set but does nothing (see 6502), and it documents the PPU’s faulty sprite-overflow flag and the APU’s channels in the detail an emulator needs.
Making new games
The community has always made software as well as documents. The old site’s list of programs runs from small demos to games, and it held MiniGame competitions for games of 1 KB and 4 KB: 37 games were entered in the 4 KB category of the 2003 contest. The wiki’s projects list includes Bokudono’s The Duel (1999), Sivak’s Battle Kid: Fortress of Peril (2010), a hard jump-and-shoot platform game, and many games released with their source code.
Hardware followed. Kevin Horton (kevtris) designed the CopyNES, a board fitted inside a front-loading NES to copy cartridges to a computer. RetroUSB’s PowerPak, a flash cartridge that uses an FPGA to imitate many different mappers, became a common way for homebrew developers to test their games on a real console; when official updates to its mapper files stopped in 2010, community members, Loopy among them, kept writing new ones.
The tools page lists the assemblers people use. Loopy wrote asm6 because the others “were either too finicky, had weird syntax, took too much work to set up, or too bug-ridden to be useful”; the cc65 package supplies an assembler, linker and C compiler; NESASM comes from the MagicKit assembler.
Keeping it running
A community site depends on whoever holds the keys. In 2021 the old nesdev.com site ran into months of problems, and its administrator could not be reached. The wiki’s editors moved it to nesdev.org using data scraped from the old site; the administrator then got in touch, and the full databases, including forum accounts and private messages, were recovered. The forum had lost 358 user accounts; 114 were restored from a backup. The editors promised daily backups and “multiple administrators who are active in the community so we can respond to issues in a timely fashion and not risk getting locked out of the servers”. The forum was fully back online by December 2021, and in May 2022 a sister SNESdev Wiki opened, organised the same way.
Sources
- NESdev.org, archive of the original NESdev site (web, secondary): the mailing list archive from 22 January 1998; the visitor counter since 1999; Memblers as contact; hosting on Parodius; the MiniGame Compos of 2002 to 2004; Brad Taylor’s 2A03 and 2C02 references (first release 23 April 2004); blargg’s APU reference (2004); loopy’s scrolling document; the June 2009 link to the new wiki; “The docs linked below are old and may contain inaccurate information”. https://www.nesdev.org/archive.html
- NESdev Wiki, “Nesdev Wiki” main page (web, secondary): the IRC channel, forum and Discord; news of the 2021 move to nesdev.org and the SNESdev Wiki in 2022. https://www.nesdev.org/wiki/Nesdev_Wiki
- NESdev Wiki, “Myths” (web, secondary): the 224-line and 240-line picture heights. https://www.nesdev.org/wiki/Myths
- NESdev Wiki, “INES” and “NES 2.0” (web, secondary): Fayzullin, the iNES emulator and header layout, and its extension. https://www.nesdev.org/wiki/INES
- NESdev Wiki, “Nestech.txt” (web, secondary): Jeremy Chadwick’s “Nintendo Entertainment System Documentation”, its reasons and thanks list. https://www.nesdev.org/wiki/Nestech.txt
- NESdev Wiki, “Emulator tests”, “Visual 2C02”, “CopyNES”, “PowerPak”, “Tools” and “Projects” (web, secondary). https://www.nesdev.org/wiki/Tools
- NESdev Wiki, “CPU” and “MMC3” (web, secondary): the missing decimal mode; NEC and Sharp MMC3 behaviour. https://www.nesdev.org/wiki/CPU
- NESdev Wiki, “Nesdev wiki:General disclaimer” (web, secondary): the public-domain statement. https://www.nesdev.org/wiki/Nesdev_wiki:General_disclaimer