DOCSEARCHbyAlgolia
Submit Docs

Pan Docs

repository·master·Indexed 20 days ago

https://github.com/gbdev/pandocs

A comprehensive technical reference for the Game Boy, maintained in Markdown format. The repository includes the documentation source, a custom mdBook preprocessor (pandocs-preproc), and a custom renderer for generating single-page HTML versions. It also provides tools for reconstructing MediaWiki history into Git and instructions for local deployment via Docker, Rust, and Python.

Tokens
76.9K
Snippets
110
Records
324
Agent score
73%

What's inside Pan Docs

  1. Overview of Super Game Boy (SGB) Hardware and Features

    master

    The Super Game Boy (SGB) is an adapter cartridge that enables Game Boy games to be played on a SNES (Super Nintendo Entertainment System). It contains a Game Boy system on chip and uses an ICD2 bridge circuit to translate inputs and video signals between the SNES and the Game Boy.

    Key hardware characteristics include:

    • Display: The 160×144 pixel Game Boy screen is centered within the 256×224 pixel SNES screen, surrounded by a customizable border.
    • Clock Speed: The SGB is synchronized to the SNES CPU. On NTSC systems, the Game Boy CPU, video controller, timers, and sound frequencies run approximately 2.4% faster than on handheld systems. On PAL systems, they run approximately 1.48% faster.
    • Multiplayer: Supports up to four joypads connected to the SNES, allowing up to four players to play simultaneously on a single screen without link cables.

  2. Overview of the M161 Mapper

    master

    The M161 is a simple multi-cart mapper used in Mani's 4-in-1 cartridges. It allows for 8 separate 32 KiB ROM banks, but it is strictly limited to a single bankswitch per session. Once a bankswitch occurs, all subsequent writes to the bank register are ignored until the system is powered down.

    Key Constraints:

    • Bank Limit: 8 banks of 32 KiB each ($00-$07).
    • Bankswitch Limit: Only 1 bankswitch is permitted per session. This typically allows for 1 bank for a main menu and up to 7 different 32 KiB games.
    • SRAM Support: None. This mapper only supports titles that do not require SRAM.
    • Hardware Implementation: It is based on a 74HC161A flip-flop where the latching mechanism prevents further switches once triggered.

  3. Overview of the MMM01 Mapper

    master

    The MMM01 is a specialized mapper designed for multi-game compilation cartridges. It emulates MBC1 behavior for individual games while allowing multiple games to be stored on a single cartridge.

    Key Capabilities

    • Game Capacity: Supports up to 255x 32 KiB games plus a 32 KiB menu in an 8 MiB ROM.
    • Memory Limits: Maximum total cartridge size is 8 MiB ROM and 128 KiB RAM.
    • Modes:
      • Default: Max 512 KiB ROM with banked 8, 16, or 32 KiB RAM.
      • Multiplex Mode: Max 2 MiB ROM with unbanked 8 KiB RAM (rarely used commercially).

    Important Implementation Notes

    • Unmapped Mode: On startup, the MMM01 enters an "unmapped" mode where the last 32 KiB of the ROM is mapped to the 0000-7FFF address region. This region contains the cartridge menu program used for game selection.
    • ROM Header Placement: Because the menu occupies the end of the ROM, the correct Nintendo ROM header must be located at offset (size - 32 KiB) + $100 instead of the standard $0000 + $100.
    • RAM Safety: The MMM01 cannot completely block access to RAM. To prevent games without RAM from corrupting the save data of games that use RAM, it is recommended to assign all no-RAM games to the same single RAM bank.

  4. Access the Historical Archive of Pan Docs

    master

    The historical/ directory contains archived revisions and versions of the documentation. Files in this archive follow a specific naming schema to indicate their date and original filename:

    YEAR-MONTH-DAY-ORIGINAL_FILENAME

    Historically, the documentation has undergone several name changes. You may encounter files named:

    • GAMEBOY.TXT (earliest known version, circa 1995)
    • GBSPEC.TXT
    • PANDOCS.TXT (current naming convention)

  5. Reconstruct MediaWiki history to Markdown and Git

    master

    The mediawiki-to-markdown script reconstructs the MediaWiki history of Pan Docs articles into a Git repository. It processes an XML Mediawiki export (including revisions) to perform the following for every revision of every page:

    1. Markdown Conversion: Converts the document to Markdown using pandoc, creating a separate file for every article.
    2. Git History Reconstruction: Forges a git commit for every revision using the original author and timestamp from the MediaWiki revision.
    3. Contributor Mapping: Reformats usernames and adds email addresses to match GitHub accounts.
    4. Version Control: Executes git add and git commit to rebuild the complete historical timeline with correct contributors.

  7. Understand Object Selection and Drawing Priority

    master

    The Game Boy handles object priority in two distinct stages: Selection (which objects are considered for a scanline) and Drawing (which object appears on top when they overlap).

    Selection Priority

    The PPU scans OAM sequentially (from $FE00 to $FE9F). It selects the first 10 objects whose Y-position (determined by LCDC bit 2) overlaps the current scanline.

    Drawing Priority

    When opaque pixels from different objects overlap, the higher-priority object wins.

    • Non-CGB Mode: Priority is determined by the X coordinate (smaller X = higher priority). If X coordinates are identical, the object appearing earlier in OAM has higher priority.
    • CGB Mode: Priority is determined solely by the object's location in OAM (earlier object = higher priority).

    Interaction with "BG over OBJ"

    Object priority is resolved before the "BG over OBJ" attribute is checked. An object with higher priority will "mask" lower-priority objects even if the higher-priority object has "BG over OBJ" enabled. This allows for advanced visual effects where parts of an object are hidden behind the background while others remain visible.

  8. Calculate MBC internal RAM address during unmapped bank access

    master

    In most MBCs, selecting an unmapped RAM bank (an address that would be out of bounds for the external RAM) causes the MBC to wrap around the internal RAM address.

    To determine which internal RAM address is actually being accessed, use the following formula:

    ((address - external_ram_start_address) + (active_ram_bank * ram_bank_size)) % max_external_ram_size

  9. Understand the Pan Docs folder structure

    master

    The repository is organized as follows:

    • custom/: Custom files added to the build.
    • preproc/ & renderer/: Custom mdBook preprocessor and backend (Rust projects).
    • src/: Primary source directory. Contains Markdown files and images (imgs/). Any .md file listed in SUMMARY.md is rendered to HTML.
    • theme/: Overrides for default mdBook theme files.
    • book.toml: The mdBook configuration file.
    • requirements.txt: Python package requirements.
    • Cargo.toml / Cargo.lock: Root of a Cargo workspace containing preproc/ and renderer/.

  10. Serial interrupt (INT $58)

    master
    The Serial interrupt is requested upon the completion of a serial data transfer. Specifically, it is requested eight serial clock cycles after starting a transfer (by setting the SC bit 7 in $FF02). At this point, the incoming data is available in the SB register ($FF01).

  11. Handle OAM DMA bus conflicts and PPU timing

    master

    When performing OAM DMA, you must manage how the PPU (Picture Processing Unit) interacts with the transfer to avoid graphical glitches.

    PPU Timing and Modes

    • Mode 1 (VBlank): The safest time to execute DMA. Most programs run DMA during or immediately after the VBlank handler.
    • Mode 2 (OAM Scan): If DMA is active during Mode 2, most PPU revisions treat the objects being written as off-screen (hidden).
    • Mode 3 (Rendering): Executing DMA during Mode 3 allows for more than 40 objects on screen (by updating objects mid-frame), but it can cause graphical glitches. The PPU may read incorrect tile numbers or attributes if the DMA unit is writing to OAM at the exact moment the PPU fetches the object data.

    Best Practices for Mid-Frame Transfers

    If you must start a transfer during the frame (to show more than 40 objects), wait for Mode 0 first. This ensures the DMA transfer overlaps Mode 2 on the subsequent lines, making the objects invisible on those specific lines rather than causing random glitches in Mode 3.

  12. Understand Timer and Divider register interactions

    master

    The DIV register is the visible part of the system counter, which increments every M-cycle (unless the CPU is in STOP mode). Because the bits of the system counter are connected to a multiplexer and a falling-edge detector, certain register operations can trigger unexpected "Timer tick" or "DIV-APU event" pulses:

    • Resetting the system counter: Writing to DIV can reset the bit currently selected by the multiplexer, potentially sending a pulse early.
    • Changing the clock source: Changing the "Clock select" bits in TAC from a bit that is currently set to a bit that is currently unset will trigger a "Timer tick" pulse.
      • Example: If the system counter is $3FF0 and TAC is $FC, writing $05 or $06 to TAC triggers an instant pulse, whereas $04 or $07 does not.
    • Disabling the timer (Monochrome only): On monochrome consoles, disabling the timer while the currently selected bit is set will send a single "Timer tick". This behavior does not occur on Color models.
    • Enabling the timer (Color models): On Color models, writing to TAC to enable the timer (when it was previously disabled) while the selected bit is set may or may not send a "Timer tick"; behavior varies by specific hardware.