{% if include.image %}
- ![Link to {{ include.title }}]()
+ ![Thumbnail of {{ include.title }}]()
{% else %}
- ![Link to {{ include.title }}]()
+
{% endif %}
diff --git a/_includes/recommended-sidebar.html b/_includes/recommended-sidebar.html
index 99dc27ac..e7c4f1de 100644
--- a/_includes/recommended-sidebar.html
+++ b/_includes/recommended-sidebar.html
@@ -15,7 +15,8 @@
{% endcomment %}
{% for recommend in related_topics %}
- {% for post in site.pages where_exp:"post","post.tags contains recommend and post.hidden != true" %}
+ {% assign related_posts = site.pages | where_exp:"post","post.tags contains recommend" | where_exp:"post","post.hidden != true" %}
+ {% for post in related_posts %}
{% if post.tags contains recommend and post.url != include.current_url %}
{% include_cached post-discovery/post-card.html post=post classes="" %}
@@ -30,7 +31,8 @@
This is for when the related topics are NOT an array
{% endcomment %}
- {% for post in site.pages where_exp:"post","post.tags contains related_topics and post.hidden != true" %}
+ {% assign related_posts = site.pages | where_exp:"post","post.tags contains related_topics" | where_exp:"post","post.hidden != true" %}
+ {% for post in related_posts %}
{% if post.tags contains related_topics and post.url != include.current_url %}
{% include_cached post-discovery/post-card.html post=post classes="" %}
diff --git a/categories/consoles/GameBoy.md b/categories/consoles/GameBoy.md
index 0424e5aa..e8df051e 100644
--- a/categories/consoles/GameBoy.md
+++ b/categories/consoles/GameBoy.md
@@ -1,189 +1,145 @@
---
-permalink: /gameboy
layout: post
-title: Nintendo Game Boy (DMG & GBC) Reversing
-recommend:
- - gameboy
- - gba
- - ds
-recommendTitle: All GameBoy Posts
-editlink: ../categories/consoles/GameBoy.md
+permalink: /gameboy
+title: Nintendo Game Boy Reverse Engineering
category: gameboy
-excerpt: Awesome list of Nintendo Game Boy Game Development and Reverse Engineering information
breadcrumbs:
- name: Home
url: /
- - name: Nintendo GameBoy
- url: /gameboy
-videocarousel:
- - title: The Ultimate Game Boy Talk
- image: https://img.youtube.com/vi/HyzD8pNlpwI/hqdefault.jpg
- youtube: HyzD8pNlpwI
- - title: The Game Boy, a hardware autopsy
- image: https://img.youtube.com/vi/RZUDEaLa5Nw/hqdefault.jpg
- youtube: RZUDEaLa5Nw
+ - name: Consoles
+ url: /consoles
+ - name: Nintendo Game Boy Reverse Engineering
+ url: #
+tags:
+ - gameboy
+ - introduction
+recommendTitle: All Game Boy Posts
+recommend:
+ - gameboy
+ - gba
+ - introduction
+ - ds
+editlink: ../categories/consoles/GameBoy.md
+excerpt: Hub page for Game Boy and Game Boy Color hardware, development, reverse engineering, and source code resources
+updatedAt: '2026-04-26'
redirect_from:
- /gameboy/hardware
- /ultimate-gameboy
-tags:
- - gameboy
+ - /gameboy/
---
# Introduction
-Welcome to our page dedicated to Game Boy reverse engineering! The Game Boy was a groundbreaking handheld gaming console that was released in 1989, and has since become an iconic symbol of the early days of portable gaming. If you're interested in learning more about the technical aspects of this console and how it works, you've come to the right place.
-
-On this page, we've compiled a list of links to other pages that cover various topics related to Game Boy reverse engineering. Whether you're interested in understanding the hardware architecture of the console, analyzing game code, or exploring the many mods and hacks that have been created by enthusiasts over the years, you'll find a wealth of resources and information on the pages we've linked to.
+The original Game Boy (DMG) and Game Boy Color (GBC) are good reverse-engineering targets because the software stack is still small enough to reason about directly, while the hardware is rich in cartridge mappers, boot-time behaviour, audio quirks, and late-1990s toolchains. They sit at a useful midpoint between 8-bit home consoles and later handhelds, so platform details are still visible instead of disappearing behind large SDKs and operating systems.
-So grab your Game Boy and get ready to dive into the exciting world of Game Boy reverse engineering!
+This page serves two roles. It groups the RetroReversing posts related to the Game Boy family, and it curates a set of external references that are worth keeping close while you work through ROMs, schematics, tools, or source code.
-## Original GameBoy Dot Matrix Game (DMG) Specs
-Main specs of the original GameBoy:
- * **CPU**: z80 - LR35902 (Opcodes: http://www.pastraiser.com/cpu/gameboy/gameboy_opcodes.html)
- * **RAM**: 8KB (32KB in Color)
-
-## Game Boy Exclusive Games (DMG & Color)
-When it comes to finding a game to reverse engineer, it can be helpful to look at games that are cross-platform to compare builds. But the most valuable reverse engineering projects tend to be the platform exclusives, as these are the games people can no longer play on modern consoles.
-
-{% include link-to-other-site.html url="https://en.wikipedia.org/wiki/Category:Game_Boy-only_games" description="Wikipedia has compiled an excellent list of games that have never been re-released and thus need a Game Boy to be able to play" image="/public/NintendoGameBoyThumb.png" title="List of Original DMG Game Boy exclusives" %}
-
-{% include link-to-other-site.html url="https://en.wikipedia.org/wiki/Category:Game_Boy_Color-only_games" description="Wikipedia has compiled an excellent list of games that have never been re-released and thus need a Game Boy Color to be able to play" image="/public/consoles/Nintendo Game Boy Color.png" title="List of Game Boy Color exclusives" %}
-
-## The Ultimate Game Boy Talk (hardware specs etc)
-The 8-bit Game Boy was sold between 1989 and 2003, but its architecture more closely resembles machines from the early 1980s, like the Commodore 64 or the NES.
-
-This talk attempts to communicate "everything about the Game Boy" to the listener, including its internals and quirks, as well as the tricks that have been used by games and modern demos, reviving once more the spirit of times when programmers counted clock cycles and hardware limitations were seen as a challenge.
-
-
-
----
-# Game Boy Technology
-
-## Game Boy Assembly Language (Z80-like)
-The Game Boy has a variant of the Zilog Z80 processor, well technically it is a CPU between the `i8080` and the Z80, it is not binary compatible with either but there are similarities. You need a assembler that can handle the Game Boy specific opcodes in order to write functional code for the Game Boy in assembly language.
-
-{% include link-to-other-site.html url="https://www.chibiakumas.com/z80/Gameboy.php" description="ChibiAkumas has an excellent page with tutorials and information to get started with Game Boy assembly language." image="https://www.chibiakumas.com/z80/AsmTitleStrip.jpg" title="gbZ80 Assembly programming for the Game Boy and Game Boy Color" %}
-
-## Game Boy Boot ROM (Bootstrapping)
-Every game produced for the Game Boy required a little piece of code known as the "bootloader" or boot code to initialise the state of the console. You don't have to know anything about this, but it can be fascinating to find out what the Game Boy does as soon as you hit that power button.
-
-{% include link-to-other-site.html url="https://realboyemulator.wordpress.com/2013/01/03/a-look-at-the-game-boy-bootstrap-let-the-fun-begin/" description="RealBoy has an excellent page that gives you an in-depth look at how the Game Boy's bootloader works" title="A Look At The Game Boy Bootstrap: Let The Fun Begin!" %}
-
----
-# Reverse Engineering Game Boy Games
-There have been a few very successful reverse engineering projects for the Game Boy, one of the most successful is the Pokemon disassembly which managed to reverse engineer the entire game into a rebuildable ROM!
-
-## Pokemon Red/Blue/Yellow
-The Pokemon Reverse Engineering Team (PRET) have managed to pull off a marvellous achievement, they have fully reverse engineered Pokemon Red and Blue back into retail-matching assembly code.
-{% include_cached link-to-other-post.html post="/pokemonredblue" description="For more information about the project check out this post." %}
-
-## Legend of Zelda Links Awakening
-In August 2016 the website KZone started a full disassembly of the classic Game Boy game Link's Awakening, along the way they have written some excellent in-depth articles about how the game works. Check it out!
-
-{% include link-to-other-site.html url="https://kemenaran.winosx.com/posts/category-disassembling-links-awakening/" description="Find out how Zelda Link's Awakening for Game Boy works at KZone!" image="https://kemenaran.winosx.com/images/zelda-links-awakening-sfx/LADX-move.gif" title="Disassembling Link's Awakening" %}
-
-## Looney Tunes: Carrot Crazy
-{% include link-to-other-site.html url="https://www.huderlem.com/blog/posts/carrot-crazy-1/" description="Find out how to reverse engineer Looney Tunes: Carrot Crazy for the GBC" image="https://www.huderlem.com/blog/posts/carrot-crazy-1/password-entry-screen.png" title="Reverse Engineering Carrot Crazy" %}
-
----
-# Game Boy Development
-
-## Game Boy Development Kit Hardware
-Special hardware was sold directly from Nintendo in order to make it easy for third party developers to get started making their own games for the new handheld.
-
-{% include_cached link-to-other-post.html post="/gameboy-development-kit-hardware" description="For more information about the development hardware used for Game Boy projects check out this post." %}
-
-## Game Boy Software Development Kit
-Along with the hardware, Nintendo also provided a fairly limited software development kit, which contained tools such as z80 assemblers and linkers.
-{% include_cached link-to-other-post.html post="/official-gameboy-software-dev-kit" description="For more information about the SDK used to make Game Boy games check out this post." %}
+## Quick Technical Reference
+The quick reference below is useful when choosing an emulator, debugger, or disassembly target:
+Property | Notes
+---|---
+CPU | Sharp LR35902, an 8-bit CPU with `i8080` and Z80 ancestry
+Display | `160x144` LCD with tile- and sprite-based graphics
+RAM | DMG has 8 KB work RAM and 8 KB VRAM; GBC expands the memory available to software
+Audio | Four hardware sound channels
+Cartridges | Commonly include ROM plus mapper hardware such as MBC controllers, battery-backed RAM, or RTC logic
---
# Hardware
+Understanding the platform before opening a ROM saves time. The Game Boy family is simple enough to study at board-level, but it still has enough cartridge and accessory variation that hardware context matters.
## Hardware Architecture
-We used to have a post on the hardware architecture of the Game Boy, but now we have replaced it for a link to the far superior page on **copetti.org**, it is a must read for any reverse engineer or beginner emulator developer.
-{% include link-to-other-site.html url="https://www.copetti.org/writings/consoles/game-boy/" description="This page on copetti.org has everything you need to know about the Game Boy Hardware, it is a must read!" image="/public/NintendoGameBoyThumb.png" title="Game boy Architecture - A Practical Analysis" %}
+If you want a broad architectural overview before going deeper, Copetti's write-up is one of the best starting points:
+{% include link-to-other-site.html url="https://www.copetti.org/writings/consoles/game-boy/" description="Rodrigo Copetti provides a practical architectural overview of the Game Boy, covering the CPU, memory layout, graphics pipeline, audio system, and cartridge hardware." image="/public/NintendoGameBoyThumb.png" title="Game Boy Architecture - A Practical Analysis" %}
+
+## Boot ROM
+The boot ROM is one of the first platform-specific code paths worth understanding. It establishes initial hardware state, checks cartridge header data, and controls the startup sequence:
+{% include link-to-other-site.html url="https://realboyemulator.wordpress.com/2013/01/03/a-look-at-the-game-boy-bootstrap-let-the-fun-begin/" description="A practical breakdown of the original Game Boy bootstrap process, useful when studying cartridge headers, reset state, and emulator accuracy." title="A Look At The Game Boy Bootstrap" %}
## Sharp LR35902 Microprocessor
-The CPU used in the original Game Boy was a custom Sharp LR35902, which is often considered similar to the Zilog Z80 but with some variations. While it was based on the Z80 architecture, it was not produced by Zilog.
+The Sharp LR35902 is close enough to Z80-family code to feel familiar, but different enough that you should treat it as its own target architecture. In practice it sits somewhere between the `i8080` and the Z80 and is not binary-compatible with either:
+{% include_cached link-to-other-post.html post="/z80" description="Background on the Z80 family and why the Game Boy CPU looks familiar while still requiring Game Boy specific handling." %}
-{% include_cached link-to-other-post.html post="/z80" description="For more information about the Z80-based CPU used in the Game Boy check out this post." %}
+## Schematics
+If you want to work from recreated board-level documentation, Gekkio's schematic set is a strong reference for the Pocket hardware revision:
+{% include link-to-other-site.html url="https://github.com/Gekkio/gb-schematics/blob/master/MGB-xCPU/schematic/MGB-xCPU.pdf" description="Recreated schematics for the Game Boy Pocket CPU board, useful for tracing signals and understanding hardware level behaviour." title="Game Boy Pocket Hardware Schematics" %}
-## Game Boy Pocket Hardware Schematics
-If you want to go really low level into the Game Boy hardware, you can view a re-creation of the Game Boy Circuit Schematics over on Github:
-[gb-schematics/MGB-xCPU.pdf at master · Gekkio/gb-schematics · GitHub](https://github.com/Gekkio/gb-schematics/blob/master/MGB-xCPU/schematic/MGB-xCPU.pdf)
+## The Ultimate Game Boy Talk
+This talk is still one of the best broad introductions to the hardware and the programming model, especially if you want one long-form overview before drilling into specific subsystems:
+
## The Game Boy, a hardware autopsy
+These two videos are worth keeping together because they focus more on the physical hardware itself than the higher-level architectural write-ups above:
-## The Mobile Adapter GB
-In Japan an adapter was released that allowed you to connect your GameBoy Color to a mobile phone called **The Mobile Adapter GB**. Only a few Japanese games supported this adapter, one of which was Pokemon Crystal.
-
-**TheXcellerator** has written an excellent article on not only how the adapter works but also how he managed to create an exploit to run custom code through the adapter!
-
-Here is the link: [Tetsuji: Remote Code Execution on a GameBoy Colour 22 Years Later :: TheXcellerator](https://xcellerator.github.io/posts/tetsuji/)
-
---
-## Super GameBoy
-The Super GameBoy was a Super Nintendo Cartridge that allowed you to play Original GameBoy (DMG) games on the big screen (TV Monitor). It did this by including all the hardware a normal GameBoy has (a z80 cpu etc) minus the screen and the buttons:
-
+# Development
+Understanding the official toolchain helps when you encounter build artifacts, linker conventions, or assembly layout in old projects.
----
-## Wide Boy 64
-Official device to play gameboy (including GBA) games on the N64, but was not sold to the general public. You had to be a game developer or press in order to buy one from Intelligent Systems.
-
+## Development Kit Hardware
+Nintendo sold dedicated development hardware for Game Boy projects, and the physical setup explains a lot about how teams built, tested, and flashed handheld software in the early 1990s:
+{% include_cached link-to-other-post.html post="/gameboy-development-kit-hardware" description="An overview of the official Game Boy development hardware and how it fit into commercial production workflows." %}
----
-## Game Boy Printer
-To go along with the Game Boy Camera Nintendo also releases a Game Boy Printer to print the photos you have taken, it also had integration with a couple of GB games such as Pokemon Yellow/Gold/Silver to print out Pokedex stickers [^2].
-
+## Software Development Kit
+Alongside the hardware, Nintendo also shipped a software development kit with assemblers, linkers, and related utilities:
+{% include_cached link-to-other-post.html post="/official-gameboy-software-dev-kit" description="Notes on the official Game Boy SDK, including the tools and file types that appear in retail era development setups." %}
----
-## GB Booster (for N64)
-Similar to the Super GameBoy but this is for the Nintendo 64 and not licenced by Nintendo, I first saw this for sale in issue X of the UK Nintendo Official Magazine.
-
-For more information:
-* [Chris Mcovell's page](http://www.chrismcovell.com/gbbooster.html)
-* [GameHacking.org Wiki Page](https://gamehacking.org/wiki/Game_Booster_(Nintendo_64))
+## Assembly Language
+The Game Boy CPU uses its own instruction set variant, so it helps to keep a Game Boy specific opcode reference nearby instead of assuming normal Z80 compatibility:
+{% include link-to-other-site.html url="https://www.chibiakumas.com/z80/Gameboy.php" description="A beginner friendly but detailed introduction to Game Boy assembly programming, with examples of the instruction set and platform specific quirks." image="https://www.chibiakumas.com/z80/AsmTitleStrip.jpg" title="Game Boy Assembly Programming" %}
---
-## Datel Game Booster for Sony Playstation
-Similar to the Super GameBoy but this is for the Sony Playstation!
-
+# Reverse Engineering
+If you want to begin with projects that already expose structure, build systems, or platform specific research, start with the material below.
-There was also one for PS2 that played Game Boy Color games called the **GameStudio**:
-
+## Pokemon Red and Blue
+The Pokemon Reverse Engineering Team (PRET) reconstructed Pokemon Red and Blue into retail matching assembly, making it one of the most useful Game Boy case studies for understanding large commercial codebases:
+{% include_cached link-to-other-post.html post="/pokemonredblue" description="Coverage of the PRET disassembly project and why it matters for rebuildable Game Boy reverse engineering." %}
+## Link's Awakening
+The Link's Awakening disassembly effort produced a steady stream of technical write-ups that are still useful when you want to see how a polished commercial Game Boy title is structured internally:
+{% include link-to-other-site.html url="https://kemenaran.winosx.com/posts/category-disassembling-links-awakening/" description="A long-running series on disassembling Link's Awakening, with practical explanations of systems, data formats, and game logic." image="https://kemenaran.winosx.com/images/zelda-links-awakening-sfx/LADX-move.gif" title="Disassembling Link's Awakening" %}
-## Dance Dance Revolution Controller for GBC
-Konami came out with a custom "controller" for Dance Dance Revolution that goes on top of the Game Boy Color and maps the buttons, quite cool but a very cheap accessory.
-
+## Looney Tunes Carrot Crazy
+If you want a more focused example of reversing a single Game Boy Color title, this write-up is a good smaller target:
+{% include link-to-other-site.html url="https://www.huderlem.com/blog/posts/carrot-crazy-1/" description="A practical reverse engineering walk-through for Looney Tunes Carrot Crazy on the Game Boy Color." image="https://www.huderlem.com/blog/posts/carrot-crazy-1/password-entry-screen.png" title="Reverse Engineering Carrot Crazy" %}
+## Exclusive Games as Research Targets
+Platform exclusives are often better long-term preservation targets because they are less likely to have cleaner ports or modern rereleases. These two category pages are simple discovery lists rather than technical references, but they are useful when you need candidate ROMs to investigate:
+{% include link-to-other-site.html url="https://en.wikipedia.org/wiki/Category:Game_Boy-only_games" description="A discovery list of original DMG exclusives that can help you find titles which still depend on original Game Boy hardware." image="/public/NintendoGameBoyThumb.png" title="Original Game Boy Exclusive Games" %}
----
-# Game Boy Source Code
+{% include link-to-other-site.html url="https://en.wikipedia.org/wiki/Category:Game_Boy_Color-only_games" description="A discovery list of Game Boy Color exclusives, useful when you want GBC specific software targets rather than DMG compatible games." image="/public/consoles/Nintendo Game Boy Color.png" title="Game Boy Color Exclusive Games" %}
-## Mr Do! For Original Game Boy
-The source code for the Game Boy classic `Mr Do!` has been kindly released by two of the original game developers and can provide an excellent reference for how retail Game Boy games were developed in 1990!
+---
+# Source Code
+Official or near-official source releases are especially valuable on Game Boy because they expose real memory layouts, tool conventions, and cartridge assumptions that decompilation alone can hide.
-{% include_cached link-to-other-post.html post="/mrdo" description="For more information about the source code check out this post." %}
+## Mr Do! for Original Game Boy
+The released source code for `Mr Do!` is a useful reference point for how a commercial Game Boy project was organised in 1990:
+{% include_cached link-to-other-post.html post="/mrdo" description="Coverage of the Mr Do! source release and the structure of a retail era Game Boy codebase." %}
---
-# Game Boy Games
+# Games
+Some game-specific anecdotes are worth keeping because they point to development constraints, unusual implementation tricks, or particularly good analysis material.
## Alien 3
+`Alien 3` is a useful reminder of how compressed licensed handheld schedules could be. Jas Austin has said the Game Boy version was written in about five weeks [^1].
The Game Boy game **Alien 3** was written in only 5 weeks by legendary game programmer **Jas Austin**:
`
+ * `# Game Modding and ROM Hacking`
+ * `# Homebrew Development`
+ * `# Reverse Engineering games`
+ Only add these if you have enough links/content to avoid thin sections.
+* **FAQ-style subheadings** - within an H1 section, use `###` question headings ("How long did it take…?", "What did the SDK look like?") to make the page skimmable; each answer should end in one or more links (internal or external).
+* **Primary-source quote blocks** - short `>` quotes are useful for provenance and “why this matters”, backed by a footnote when the quote is evidence.
+* **Embedded media (sparingly)** - a teardown / explanation video, tweet, or other primary-source embed can be worth keeping when it teaches a hardware concept or preserves development context; keep the surrounding text tight and technical.
+* **Preserve existing embeds** - when editing an existing category page, keep embedded videos, tweets, and similar source material unless the user explicitly asks to remove them. Reorganising is fine, deletion is not.
+* **Hands-on callouts** - include at least one concrete “try this” (emulator/debugger step, tool invocation, or a small workflow) when the console has established reversing tooling.
+
+If a console doesn’t have enough depth yet, prefer the simpler hub pattern (short intro + links + `# All Posts`) rather than forcing these extras.
+
+
+Remember the Markdown hygiene rules from `CONTRIBUTING.md`:
+
+* Use `---` before major section jumps (and when jumping back up the heading hierarchy).
+* No blank line between `---` and the next heading.
+* No blank line between a heading and its first paragraph.
+* Never use numbered lists; use `*` bullets introduced by a sentence ending in `:`.
+* Use tables when a list would exceed ~10 items.
+
+## Linking rules
+
+Internal links (to other RetroReversing pages):
+
+```liquid
+{% include_cached link-to-other-post.html post="/permalink" description="1 sentence on why this is relevant." %}
+```
+
+External links that stand alone as their own paragraph/line:
+
+```liquid
+{% include link-to-other-site.html
+ title="Resource title"
+ url="https://example.com"
+ description="1-2 sentences explaining what it is and why it matters." %}
+```
+
+Inline external links inside a sentence can be normal Markdown links; add a footnote only when the link is serving as evidence for a claim.
+
+## Youtube Rules
+If its a YouTube video always have an embed and mention the author and content of the video before it, e.g:
+```markdown
+[PothOnProgramming](https://www.youtube.com/watch?v=b5TjpTBW6yw) offers a technical breakdown of the 2D dot product and its critical applications in game design and engine logic. The video highlights several fundamental applications of the dot product used in game development and vector math.
+
+
+```
+
+## References
+If the page makes specific historical/technical claims (dates, counts, quotes), add footnotes and end with:
+`# References`
+Keep quotes short and make sure references back up the specific claim.
+
+## Creating a brand-new category
+If you add a new top-level category page:
+* Ensure the `category:` key exists in `_config.yml` under `category:` with `title` and `image`.
diff --git a/pages/consoles/gameboy/GameBoySDK.md b/pages/consoles/gameboy/GameBoySDK.md
index 8dc20c1e..c60750c5 100644
--- a/pages/consoles/gameboy/GameBoySDK.md
+++ b/pages/consoles/gameboy/GameBoySDK.md
@@ -20,6 +20,8 @@ breadcrumbs:
recommend:
- gameboy
- sdk
+redirect_from:
+ - /official-gameboy-software-dev-kit/
editlink: /consoles/gameboy/GameBoySDK.md
updatedAt: '2026-04-04'
---
diff --git a/pages/consoles/pokemonMini/OfficialPokeMiniSDK.md b/pages/consoles/pokemonMini/OfficialPokeMiniSDK.md
index 6c30f548..5cd0d313 100644
--- a/pages/consoles/pokemonMini/OfficialPokeMiniSDK.md
+++ b/pages/consoles/pokemonMini/OfficialPokeMiniSDK.md
@@ -18,6 +18,8 @@ breadcrumbs:
recommend:
- pokemonmini
- sdk
+redirect_from:
+- /official-pokemon-mini-sdk/
editlink: /consoles/pokemonMini/OfficialPokeMiniSDK.md
---
diff --git a/pages/consoles/snes/SNESSDK.md b/pages/consoles/snes/SNESSDK.md
index d9a227e7..34224e20 100644
--- a/pages/consoles/snes/SNESSDK.md
+++ b/pages/consoles/snes/SNESSDK.md
@@ -20,6 +20,8 @@ breadcrumbs:
recommend:
- sdk
- snes
+redirect_from:
+- /super-famicom-snes-sdk/
editlink: /consoles/snes/SNESSDK.md
updatedAt: '2021-07-03'
---
diff --git a/pages/consoles/vita/OfficialSonyVitaSDK.md b/pages/consoles/vita/OfficialSonyVitaSDK.md
index dbd5ee68..ff9b63d1 100644
--- a/pages/consoles/vita/OfficialSonyVitaSDK.md
+++ b/pages/consoles/vita/OfficialSonyVitaSDK.md
@@ -18,6 +18,8 @@ breadcrumbs:
recommend:
- sdk
- vita
+redirect_from:
+- /official-vita-sdk/
editlink: /consoles/vita/OfficialSonyVitaSDK.md
---
diff --git a/pages/consoles/vita/VitaFileFormats.md b/pages/consoles/vita/VitaFileFormats.md
index b3ae8707..05bd329b 100644
--- a/pages/consoles/vita/VitaFileFormats.md
+++ b/pages/consoles/vita/VitaFileFormats.md
@@ -18,13 +18,15 @@ breadcrumbs:
recommend:
- vita
- fileformats
+redirect_from:
+- /playstation-vita-file-formats/
editlink: /consoles/vita/VitaFileFormats.md
---
-When reverse engineering Playstation Vita games you will come across a number of different file formats, this post will explain all the file formats and how to use them.
+When reverse engineering PlayStation Vita games you will come across a number of different file formats, this post will explain all the file formats and how to use them.
# Package files
-Package files are ways to distribute the full games to be installed on Playstation Vita consoles, the contains all the assets and executables required to run the game.
+Package files are ways to distribute the full games to be installed on PlayStation Vita consoles, the contains all the assets and executables required to run the game.
## PKG - Official Sony Package Files
The games available on the Vita shop comes in an encrypted .PKG format along with a user-specific license. In order to disassemble/decompile or modify games they need to be decrypted [^2].
diff --git a/scripts/install-codex-skill.sh b/scripts/install-codex-skill.sh
index 13dd938e..7c11d99a 100755
--- a/scripts/install-codex-skill.sh
+++ b/scripts/install-codex-skill.sh
@@ -2,25 +2,44 @@
set -euo pipefail
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-src_dir="$repo_root/codex/skills/retroreversing-contributing"
+skills_src_root="$repo_root/codex/skills"
codex_home="${CODEX_HOME:-$HOME/.codex}"
-dest_dir="$codex_home/skills/retroreversing-contributing"
+skills_dest_root="$codex_home/skills"
-if [[ ! -d "$src_dir" ]]; then
- echo "Skill source directory not found: $src_dir" >&2
+if [[ ! -d "$skills_src_root" ]]; then
+ echo "Skills source directory not found: $skills_src_root" >&2
exit 1
fi
-mkdir -p "$dest_dir"
+mkdir -p "$skills_dest_root"
+
+installed_count=0
+
+for src_dir in "$skills_src_root"/*; do
+ [[ -d "$src_dir" ]] || continue
+ [[ -f "$src_dir/SKILL.md" ]] || continue
+
+ skill_name="$(basename "$src_dir")"
+ dest_dir="$skills_dest_root/$skill_name"
-if command -v rsync >/dev/null 2>&1; then
- rsync -a --delete "$src_dir/" "$dest_dir/"
-else
- rm -rf "$dest_dir"
mkdir -p "$dest_dir"
- cp -R "$src_dir/"* "$dest_dir/"
-fi
-echo "Installed Codex skill to: $dest_dir"
+ if command -v rsync >/dev/null 2>&1; then
+ rsync -a --delete "$src_dir/" "$dest_dir/"
+ else
+ rm -rf "$dest_dir"
+ mkdir -p "$dest_dir"
+ cp -R "$src_dir/." "$dest_dir/"
+ fi
+
+ echo "Installed Codex skill to: $dest_dir"
+ installed_count=$((installed_count + 1))
+done
+
+if [[ "$installed_count" -eq 0 ]]; then
+ echo "No skill directories containing SKILL.md were found in: $skills_src_root" >&2
+ exit 1
+fi
+echo "Installed $installed_count Codex skill(s) from: $skills_src_root"
## R-Type -The Game Boy classic **R-Type** was programmed by **Jas Austin** completely from Memory as he didn't have any code or assets from any other version of the game! +According to Jas Austin, the Game Boy version of `R-Type` was largely built from memory after arcade research trips rather than from shared code or art assets [^2]. + +He also described being hired after showing a one-week demo to B.I.T.S, which is a useful glimpse into how quickly Game Boy contract work could move in that era [^2]. +Fastest commercial game I've ever written? That would have been Alien3 on Game Boy. Done in about 5 weeks :) with @recluse_games #gamedev
— Jas Austin (@IamXERO) February 1, 2013
The company **B.I.T.S** obtained the license to develop the Game Boy version of the game but required a programmer to work on the title. **Jas Austin** heard about this through his agency and travelled to London to meet up, he impressed them so much that he was given a development kit and a deadline of a week to come up with a demo! He did such a good job he got a permanent job at **B.I.T.S** [^1]. -One cool easter egg he added to the game was an implementation of John Conway's game of Life!I agree, it's amazing some of the lengths we have to go to when we didn't have code or assets. For R-Type I did most of it from memory after visits to the Trocadero in London. And I didn't live in London.
— Jas Austin (@IamXERO) April 18, 2020
+Austin later mentioned hiding an implementation of John Conway's Game of Life inside the cartridge [^3], and also shared source graphics for the level 3 ship by Mark Jones [^4]. +I hid a version of John Conway's game of Life in R-Type on the Game Boy.
— Jas Austin (@IamXERO) April 5, 2021
## How Pokemon Gold & Silver Work (Tribute to Satoru Iwata) @@ -192,49 +148,92 @@ One cool easter egg he added to the game was an implementation of John Conway's --- -# Game Boy Homebrew -If you are interested in reverse engineering Gamy Boy Homebrew you will want to check out the tool **gbtoolsid** which can give an indication of what tool was used to make the rom (e.g GBDK, GBStudio etc): -[bbbbbr/gbtoolsid: A command line app for identifying tools used to build Game Boy ROMs](https://github.com/bbbbbr/gbtoolsid) +# Peripherals and Accessories +The wider Game Boy ecosystem matters for reverse engineering because several accessories introduce their own protocols, bootstrap behaviour, or unusual cartridge side hardware. -## Blem! Playstation Emulator for the GB -Blem! was a prank ROM for the Game Boy which pretended to load up a Playstation 1 emulator on the Game Boy. This is a reference to the Bleam! Playstation emulator released for Mac and Dreamcast. I doubt anyone really believed this prank but it was mentioned in the UK Magazine **GBX** issue 3 (Septermber 2001) when talking about Game Boy emulation for PC (NoCash) and Mac (Virtual Boy) [^11]. +## Mobile Adapter GB +Nintendo released a Japanese accessory called the Mobile Adapter GB which connected a Game Boy Color to a mobile phone. Only a small set of games used it, making it a good example of an obscure platform feature that remained dormant for years: +{% include link-to-other-site.html url="https://xcellerator.github.io/posts/tetsuji/" description="TheXcellerator explains how the Mobile Adapter GB works and how it was turned into a route for running custom code years after release." title="Tetsuji - Remote Code Execution on a Game Boy Colour 22 Years Later" %} +## Super Game Boy +The Super Game Boy is important because it effectively embeds Game Boy hardware inside a Super Nintendo cartridge, creating a hybrid environment with its own timing and presentation quirks: +{% include link-to-other-site.html url="https://www.youtube.com/watch?v=uaeLY441Fwc" description="A video overview of the Super Game Boy hardware and how Nintendo adapted the handheld for television output." title="Super Game Boy Overview" %} + + +## Wide Boy 64 +The **Wide Boy 64** was an official but non-retail device used by developers and press to run Game Boy and Game Boy Advance software through an N64 based setup: +{% include link-to-other-site.html url="https://www.youtube.com/watch?v=llIz6qjDfLc" description="An overview of the Wide Boy 64 and why it matters as a rare Nintendo evaluation and capture device." title="Wide Boy 64 Overview" %} + + +## Game Boy Printer +The Game Boy Printer is relevant because it exposes another side of the accessory protocol stack, and because several games shipped explicit printing features rather than treating it as a camera-only novelty. `Pokemon Yellow`, `Pokemon Gold`, and `Pokemon Silver` all used it for game-specific output such as Pokedex stickers [^5]. + +## GB Booster +The **GB Booster** was an unlicensed Nintendo 64 accessory in the same broad space as the Super Game Boy, but built outside Nintendo's official hardware ecosystem. Two short references are useful if you want to document it further: +* **[Chris McCovell](http://www.chrismcovell.com/gbbooster.html)** - Notes and photos covering the hardware and behaviour of the device. +* **[GameHacking.org Wiki](https://gamehacking.org/wiki/Game_Booster_(Nintendo_64))** - A general reference page for the accessory. + + +## Datel Game Booster and GameStudio +Datel also shipped PlayStation accessories for running Game Boy software, including the PlayStation Game Booster and the later `GameStudio` for PlayStation 2: + + + +## Dance Dance Revolution Controller for GBC +Konami's `Dance Dance Revolution` controller for the Game Boy Color is a useful example of how far the accessory ecosystem stretched beyond normal link cable peripherals: + --- -# Sound and Audio on the Game Boy +# Sound +The audio hardware is one of the most technically interesting parts of the platform, especially once you move beyond music drivers and start looking at the analogue side. -## Game Boy Color Audio Chip Reversing (AMP MGB) +## Game Boy Color Audio Chip Reversing +**Ken Shirriff's** reverse engineering of the Game Boy Color audio amplifier chip is one of the best examples of taking the handheld beyond emulator level understanding and into silicon level analysis. The chip contains three power op-amps for the speaker and headphone paths, so the article is useful if you want analogue details rather than just register level behaviour:Source graphics for Game Boy R-Type Lv3 ship. By Mark Jones... #ScreenshotSaturday24YearsAgo pic.twitter.com/RsKlc0rQOE
— Jas Austin (@IamXERO) April 25, 2015
-If you are interested in low-level hardware details about the Game Boy then this is a must read article: [Reverse-engineering the audio amplifier chip in the Nintendo Game Boy Color](http://www.righto.com/2020/05/reverse-engineering-audio-chip-in.html) +{% include link-to-other-site.html url="http://www.righto.com/2020/05/reverse-engineering-audio-chip-in.html" description="A transistor level analysis of the Game Boy Color audio amplifier chip, including die photos, schematic reconstruction, and analogue behaviour." title="Reverse Engineering the Audio Amplifier Chip in the Nintendo Game Boy Color" %} ## Synthic: Automatically generate gameboy music using machine learning This is a very interesting project that played a large set of gameboy games in a custom headless emulator and tracked the audio registers into a text format. They then trained a Machine Learning algorithm on that audio data and used it to generate completely new Game Boy Music! Check it out here: [jawline/Synthic: Automatically generate gameboy music using machine learning](https://github.com/jawline/Synthic) --- -# File Formats -{% include_cached link-to-other-post.html post="/game-boy-file-formats" description="For more about the game boy file formats information check out this post." %} +# Tools and File Formats +If you are tracing ROM headers, cartridge metadata, or patch formats, the material below is worth keeping close. + +## File Formats +Start here if you want a broader survey of Game Boy file structures before drilling into specific ROM hacks or tools: +{% include_cached link-to-other-post.html post="/game-boy-file-formats" description="An overview of Game Boy file formats, cartridge related structures, and common file handling topics." %} + +## gbtoolsid +When dealing with homebrew or unlabeled ROM sets, `gbtoolsid` is a practical first pass because it can often identify the toolchain used to build a Game Boy ROM: +{% include link-to-other-site.html url="https://github.com/bbbbbr/gbtoolsid" description="A command line utility for identifying which tools or engines were likely used to build a Game Boy ROM." title="gbtoolsid" %} ### DMG-palette-patcher [MrBlinky](https://github.com/MrBlinky/DMG-palette-patcher) has released a Python tool for patching Original Game Boy (DMG) ROMs to use specific color palettes when played on a Game Boy Color. The script works by modifying the ROM's header-specifically the license code and title checksum-to trick the Game Boy Color's boot ROM into automatically selecting one of 45 built-in color palettes, such as the classic grey theme, rather than the default blue-greenish hues. {% include link-to-other-site.html url="https://github.com/MrBlinky/DMG-palette-patcher" description="MrBlinky has released DMG-palette-patcher, a tool that modifies Game Boy ROM headers to trigger specific built-in color palettes on the Game Boy Color." title="DMG-palette-patcher by MrBlinky" %} -### gb-save-states: Save States for Original Game Boy Hardware -[mattcurrie](https://github.com/mattcurrie/gb-save-states) has a repository of patches that add save state functionality to Game Boy and Game Boy Color games running on original hardware. The project utilizes bsdiff patches to modify original ROM files, allowing users to save and load game states via specific button combinations on compatible flash cartridges. +## gb-save-states +`gb-save-states` is interesting because it applies patch based save state support to commercial games running on original hardware, which makes it a good example of practical ROM level instrumentation: +{% include link-to-other-site.html url="https://github.com/mattcurrie/gb-save-states" description="A collection of patches that add save state support to Game Boy and Game Boy Color titles on original hardware." title="gb-save-states" %} -{% include_cached link-to-other-site.html url="https://github.com/mattcurrie/gb-save-states" description="mattcurrie has released gb-save-states, a collection of patches to add save state support to Game Boy games when playing on original hardware." title="gb-save-states by mattcurrie" %} +## Blem! PlayStation Emulator for the GB +`Blem!` was a prank ROM that pretended to boot a PlayStation emulator on the Game Boy. The joke was a reference to the `Bleem!` PlayStation emulator, and it was notable enough to show up in `GBX` issue 3 in a short discussion of Game Boy emulation on PC and Mac [^6]. It is not technically important in the same way as the tools above, but it is a useful reminder that handheld homebrew culture also produced jokes, hoaxes, and magazine folklore around emulation. --- -# All Posts tagged with GameBoy - +# All PostsI reverse-engineered the audio chip in the #Nintendo Game Boy Color. It contains three power op-amps for the speaker and headphone channels. This 1998 chip is built from about 100 NPN and PNP transistors. Die photo from @johndmcmaster. Article & schematic:https://t.co/EhsVogAJPl pic.twitter.com/J6CYPsOdaz
— Ken Shirriff (@kenshirriff) May 2, 2020
+
{% include console.html %}
+
---
# References
-[^1]: [Terminator 2, R-Type, Altered Beast with Jas Austin - The Retro Hour EP320 - YouTube](https://www.youtube.com/watch?v=5ilnsca4jYc)
-[^2]: [Game Boy Printer - Bulbapedia, the community-driven Pokémon encyclopedia](https://bulbapedia.bulbagarden.net/wiki/Game_Boy_Printer)
-[^3]: GBX issue 3 (Septermber 2001) Page 11
+[^1]: [Jas Austin on Alien 3 for Game Boy taking about five weeks - Twitter/X](https://twitter.com/IamXERO/status/297359737287225345)
+[^2]: [Terminator 2, R-Type, Altered Beast with Jas Austin - The Retro Hour EP320 - YouTube](https://www.youtube.com/watch?v=5ilnsca4jYc)
+[^3]: [Jas Austin on hiding Conway's Game of Life inside R-Type - Twitter/X](https://twitter.com/IamXERO/status/1379131739415719941)
+[^4]: [Jas Austin sharing R-Type source graphics by Mark Jones - Twitter/X](https://twitter.com/IamXERO/status/591964228053016577)
+[^5]: [Game Boy Printer - Bulbapedia](https://bulbapedia.bulbagarden.net/wiki/Game_Boy_Printer)
+[^6]: GBX issue 3 (September 2001) page 11
diff --git a/categories/consoles/WiiU.md b/categories/consoles/WiiU.md
index eb98ff2e..677f0667 100644
--- a/categories/consoles/WiiU.md
+++ b/categories/consoles/WiiU.md
@@ -2,6 +2,7 @@
permalink: /wiiu
redirect_from:
- /wiiu/
+ - /wiiu
- /wiiU
- /wiiU/
title: Nintendo Wii U Reverse Engineering
diff --git a/codex/skills/retroreversing-category-pages/SKILL.md b/codex/skills/retroreversing-category-pages/SKILL.md
new file mode 100644
index 00000000..1da88b84
--- /dev/null
+++ b/codex/skills/retroreversing-category-pages/SKILL.md
@@ -0,0 +1,218 @@
+---
+name: "retroreversing-category-pages"
+description: "Use when creating or editing RetroReversing category hub pages under categories/** (consoles/tools/misc/companies). Enforces correct frontmatter, structure, and link patterns."
+---
+
+# RetroReversing Category Pages
+
+Category pages live in `categories/**` and publish to a top-level permalink like `/nes`, `/wiiu`, `/disassemblers`, or `/gdc`.
+
+They have two jobs:
+
+* act as the hub/index for a topic (usually a console/tool/company), linking to relevant RetroReversing posts
+* curate high-quality external sources so the page stands alone as a reference
+
+If you are not editing `categories/**`, use the broader `retroreversing-contributing` skill instead.
+
+## Identify the category page type
+
+Pick the smallest structure that fits:
+
+* **Hub (preferred for new pages):** short intro + organised internal links + a small curated external list.
+* **Reference list:** mostly tables of resources grouped by subtopic.
+* **Timeline/index:** lots of items grouped by year/event (example: `categories/misc/GDC.md`).
+
+## Editing Rules
+* When extending an older, very large page, avoid sweeping rewrites. Preserve stable headings and refactor incrementally.
+* Do not remove existing embedded content such as videos, tweets, or other primary-source embeds unless the user explicitly asks for their removal. These embeds often preserve useful technical or historical context. You may move or regroup them into more appropriate sections.
+
+## Frontmatter checklist (category pages)
+
+Follow `CONTRIBUTING.md` frontmatter rules and keep it minimal.
+
+Required/typical keys:
+
+* `layout: post`
+* `title:` no colons
+* `permalink:` no trailing `/` (example: `/wiiu`)
+* `category:` must match a key in `_config.yml` under `category:` (this drives the header icon), can be a list of multiple but start with just one or 2
+* `tags:` YAML list; include the main category tag and any broad qualifiers (e.g. `introduction`, `tools`)
+* `breadcrumbs:` Home -> Section -> Current
+* `editlink:` must point at the repo file relative to the GitHub `pages/` folder (category pages usually use `../categories/.../File.md`)
+
+Useful/optional keys:
+
+* `excerpt:` short, technical summary
+* `updatedAt:` `'YYYY-MM-DD'` (update only for meaningful content changes)
+* `recommendTitle:` e.g. `All WiiU Posts` (this titles the sidebar)
+* `recommend:` list of tags that should appear in the recommended sidebar
+* `redirect_from:` list of legacy permalinks you still want to support
+* `consoleimage:` for console hubs (used by search/cards in some views)
+* `image:` and `twitterimage:` only when you have a real hero image; otherwise omit
+
+## Minimal starter template
+
+Use this as a starting point for a new console hub page (adjust values; omit optional keys you do not need):
+
+```yaml
+---
+layout: post
+permalink: /wiiu
+title: Nintendo Wii U Reverse Engineering
+category: wiiu
+breadcrumbs:
+ - name: Home
+ url: /
+ - name: Consoles
+ url: /consoles
+ - name: Nintendo Wii U Reverse Engineering
+ url: #
+tags:
+ - wiiu
+ - introduction
+recommendTitle: All WiiU Posts
+recommend:
+ - wiiu
+ - wii
+ - introduction
+editlink: ../categories/consoles/WiiU.md
+excerpt: Awesome list of Nintendo Wii U reverse engineering and dev resources
+updatedAt: "2026-04-12"
+---
+```
+
+Recommended heading skeleton:
+
+```markdown
+# Introduction
+
+---
+# Hardware
+
+---
+# Reverse Engineering
+
+---
+# Games
+
+---
+# All Posts
+
+---
+# References
+```
+
+
+## Common H1 sections (recommended)
+
+Across existing category pages (especially `categories/consoles/*.md`), the most common H1 sections are:
+
+* `# Introduction`
+* `# Hardware`
+* `# Reverse Engineering`
+* `# Games`
+* `# All Posts` (usually renders the on-site list via `{% include console.html %}`)
+* `# References`
+
+Typical `# All Posts` section:
+
+```liquid
+# All Posts
+
+
+{% include console.html %}
+
+
+```
+
+Common optional H1 sections when the platform/topic needs them:
+
+* `# File Formats`
+* `# Emulation`
+* `# Development Kits (Hardware)`
+* `# Software Development Kits` / `# Software Development Kit`
+* `# Middleware`
+* `# Game Engines`
+* `# Tools`
+
+
+## Content structure (recommended)
+
+For hub-style pages, follow the newer pattern seen in `categories/consoles/WiiU.md`:
+
+* 2-4 sentence **intro** explaining why the category matters and how to use the page.
+* Use a small set of stable H1 sections separated by `---` (examples):
+ * `# Introduction`
+ * `# Hardware`
+ * `# Reverse Engineering`
+ * `# Middleware` (when platform-specific)
+ * `# Game Engines`
+ * `# Tools` (if the platform has unique toolchains)
+ * `# Games` (for debug-symbol lists, good starter targets, etc)
+* `# All Posts` near the end (this renders the internal listing for the category)
+* `# References` last when you have citations
+* Prefer short subsections that end in one or more links (internal or external), rather than long essay blocks.
+
+## Console hub extras (NES-style)
+
+`categories/consoles/Nes.md` is a good example of a *fully built-out* console hub. When a console category has enough material, these patterns work well:
+
+* **Lead-in before the first H1** - 2 short paragraphs that explain the two roles of the page (internal hub + curated external reference) and how the sections are organised.
+* **More specific H1 sections when justified** - beyond `# Introduction` / `# Hardware`, consider dedicated H1 blocks like:
+ * `# Game Software Development for the