This essay offers an account for of the Sport Boy’s capabilities, discussing the pros and cons of the on hand development tools, and providing a couple of guidelines to write down more efficient code.

Written by ISSOtmstart in fresh window with support from tobiasvlstart in fresh window, some updates by bbbbbrstart in fresh window.

---

Prior to now few years as retro gaming has grown in popularity, programming for older platforms has moreover gained traction. A typical platform is the Sport Boy, both for its nostalgia and (relative) ease to program for.

When somebody wants to build their hang sport, one of the most first complications they’ll come across is picking the tools they’ll use. There fresh foremost choices are:

• RGBDS (Rednex Sport Boy Construction Machine) and the Sport Boy’s Assembly language (ASM)
• GBDK-2020 (Sport Boy Construction Equipment) and the C language
• ZGB (an engine built on GBDK-2020) and the C language
• GB Studio (a high-tail-and-drop sport creator with scripting)

The cause of this document is to assemble some insights and enable you to build the upper quite loads of whereas you are starting a fresh challenge. I will moreover provide some “upright practice” guidelines, both for C and ASM, whereas you will hang already made up your solutions or are already using this kind of.

The customary Sport Boy, codenamed the DMG, has a 1 MHz CPU [the CPU is actually clocked at 4 MHz, but every instruction takes up a multiple of 4 clocks, so it’s often simplified to a 1 MHz CPU]. On condition that an instruction takes roughly 2 to three cycles, this offers the CPU a skill of 333,000~500,000 instructions per 2d. Its LCD boasts 60 fps [it’s actually 59.73 fps], which rounds as much as between 50,000 and 80,000 instructions per physique. With out be aware no longer so worthy, eh? It moreover has 8 kB of RAM, and 8 kB of video RAM ; a 160×144 px LCD (thus a shrimp wider than or no longer it is gigantic), 4 colours, and 4-channel audio.

The Wide Sport Boy provides a couple of minor things, akin to a customizable conceal border, and a few uncouth color. It is moreover a shrimp quicker than the DMG.

The Sport Boy Coloration can [if you tell it to] liberate further functionality, akin to more fleshed-out color, a double-velocity CPU, twice the video RAM and four cases the RAM! (With caveats, obviously.)

The gathering of programming language is main and can hang a surely mountainous quit on a challenge. It determines how worthy work is engrossing, what’s going to be likely, and the contrivance immediate it would fetch a contrivance to lunge.

# Assembly (ASM)

Most video games and programs for the Sport Boy written in ASM will use RGBDS or WLA-DX.

Strengths:

• No longer too unparalleled to learn.
• Extraordinarily unparalleled and flexible.
• When properly written it permits for optimum velocity and efficiency on the restricted sources of the Sport Boy hardware.

Weaknesses:

• It takes a diversified roughly work to write down optimized ASM code.
• It is rather verbose and sometimes unhurried.
• Will require more time and learning to win up and running compared with C.
• Code would possibly perhaps presumably well no longer be with out ache shared with ports of a sport on diversified platforms.

# C

C will basically be feeble with the SDCC compiler and GBDK-2020 or ZGB, despite the indisputable truth that it can moreover be feeble on it’s hang with out a framework or with a diversified compiler/dev equipment (akin to z88dkstart in fresh window).

Strengths:

• Permits for getting up and running quicker than with ASM, especially when constructing on top of GBDK-2020 and ZGB.
• The language abstractions build it moderately easy to put into effect solutions and algorithms.
• C source debugging is on hand by contrivance of Emulicious with the VSCode debug adapter, making it more uncomplicated to ticket complications if they arise.
• ASM will be incorporated in projects with C, either standalone or inline for velocity main components.

Weaknesses:

• The SDCC C compiler would possibly perhaps presumably well well no longer persistently generate code that runs as immediate as skilled, hand-optimized assembly. It has matured rather a lot within the 20 years for the reason that customary GBDK, but bugs mild turns up infrequently. On a platform with a gradual CPU akin to the Sport Boy this would possibly perhaps be a bid.
• It’s more uncomplicated to write down inefficient code in C with out realizing it. The Sport Boy’s CPU is most efficient in a position to performing 8-bit addition or subtraction, or 16-bit addition. Using INT32s is moderately taxing on the CPU (it wants to build two consecutive 16-bit provides, and add the lift). Scrutinize the guidelines underneath to guide clear of such blunders.
• There is overhead due to the C being a stack-oriented language, whereas the Sport Boy’s CPU is terribly built for a register-oriented strategy. This most notably makes passing feature arguments rather a lot slower, although SDCC has some optimizations for this.

# Non-Programming Language risk

Using a GUI in its put- If you don’t are attempting to learn a programming language in screech to build Sport Boy video games, then GB Studio is an risk. Scrutinize the GB Studio allotment for more main aspects.

# RGBDSstart in fresh window with ASM

RGBDS is an actively maintained suite of programs that enable constructing a ROM using ASM (assembly). It contains three programs that cancel diversified phases of the compilation, as properly as a program that converts PNG images to the Sport Boy’s tile format. RGBDS is on hand for Linux, Home windows and MacOS.

Strengths:

• Very an educated community with rather quite a bit of history.
• In-built toughen for ROM banking.
• Works rather properly with BGB for debugging.

Weaknesses:

• Gives a restricted amount of built-in code and functionality (does no longer consist of a mountainous API cherish GBDK-2020 does).

# WLA-DXstart in fresh window with ASM

WLA-DX is moreover infrequently feeble when writing in ASM, largely due to the its greater struct toughen than RGBDS.

# GBDK-2020start in fresh window with C

GBDK-2020 is a development equipment and toolchain built around the SDCC C compiler which allows you to write down programs in C and scheme ROMs. It comprises an API for interfacing with the Sport Boy. GBDK-2020 is a modernized model of the customary GBDKstart in fresh window. It is on hand for Linux, Home windows and MacOS.

Strengths:

• Versatile and extensible.
• Comprehensive API that covers most hardware components.
• Many sample projects and start source video games are on hand that show guidelines on how to use the API, hardware, and structure video games.
• C source debugging is on hand with Emulicious.

Weaknesses:

• Takes care of some facets of the hardware with out requiring the developer to galvanize them (akin to OAM DMA at some stage in VBLANK), so or no longer it is no longer persistently evident to inexperienced persons what the hardware is doing on the help of the scenes, or guidelines on how to repair them when one thing goes scary.
• ROM banking would possibly perhaps presumably well well require more administration in code than RGBDS.

# ZGBstart in fresh window with C & GBDK-2020

ZGB is a shrimp engine for the Sport Boy built on top of GBDK-2020 and written in C. Strengths:

• The frequent graphics, sound and event structure are all pre-written, so it’s quicker and more uncomplicated to start writing a sport.
• Several start source video games built with it are on hand as examples.

Weaknesses:

• The engine appropriate has the fundamentals and customised code would possibly perhaps presumably well want to be wanted for overall sport components (akin to transferring platforms, and so on.).
• Even more of the hardware configuration and processing is taken care of on the help of the scenes than with GBDK, so much less experienced users can hang peril when complications arise.

# GB Studiostart in fresh window

GB Studio is a high-tail-and-drop sport creator for the Sport Boy that does no longer require info of programming languages. Video games are built using a graphical interface to script graphics, sound and actions. It is miles on hand for Linux, Home windows and MacOS.

Strengths:

• Very easy for inexperienced persons to start constructing video games at once. The entire lot is built-in and requires minimal info and figuring out of the Sport Boy hardware.
• Has been feeble to model mountainous and extensive projects.
• Very active community for support and toughen.

Weaknesses:

• It’s video games will are inclined to be slower than both ASM and C.
• There is a restricted design of instructions to script with and a few artificially smaller restrictions on palettes, sprites, background tiles and diversified hardware components (due to the how GB Studio manages them).
• Video games would possibly perhaps presumably well well be more constrained or require workarounds to build things if they don’t with out ache match internal the on hand scripting, graphics and sound tools. (Though it is likely for developed users to build a “engine eject” and add more functionality using C and ASM.)

Factual emulators and debugging tools are tremendously priceless for making an strive out and monitoring down complications. The next Sport Boy emulators provide supreme accuracy and consist of a bunch of diversified components.

• BGBstart in fresh window has a convenient (ASM) debugger, despite the indisputable truth that its minimal interface will be confusing at the start. It is miles on hand for Home windows most efficient, but runs almost flawlessly with Wine.

• Emuliciousstart in fresh window comprises unparalleled tools akin to a profiler and source-stage debugging for ASM and C by contrivance of a VS Code debug adapterstart in fresh window. It runs on Linux, Home windows, MacOS and any diversified working methods that supports Java SE.

• Identical Boystart in fresh window is user qualified and has a gigantic risk of unparalleled (ASM) debugging components. It runs on Home windows and MacOS.

• Gambattestart in fresh window lacks a debugger and would possibly perhaps presumably well well be compiled from source, but is packaged both in RetroArchstart in fresh window (Linux, Home windows and Mac) and BizHawkstart in fresh window (Home windows-most efficient).

• Purists pick to moreover lunge their video games on hardware, which is likely thanks to flashcarts. My personal recommendation is krikzz’s cartsstart in fresh window, namely the Everdrive GB X5start in fresh window.

Aspect conceal : whereas you are using VBA or VBA-rr, discontinuance using them appropriate now. These emulators are extraordinarily wrong, and moreover like excessive security flaws. I strongly urge you to ditch these emulators and spread the notice.

In case your quiz is “What must I take advantage of for my sport challenge ?“, then you definately’re within the accurate allotment. The first quiz it is main to inquire your self is what languages you know.

# If you accomplish no longer know ASM, C or C++

Select into consideration starting with C and GBDK. This can introduce you to working with the hardware and is a less complicated starting region.

As soon as you will hang grasped C’s ideas (most importantly pointers), give ASM a crawl. The language is more uncomplicated than it seems. Even whereas you accomplish no longer manage to win working ASM code, it basically helps rather a lot (especially on one of these constrained machine) to clutch what’s “below the hood”. There is even a web based IDEstart in fresh window to experiment with.

For C / GBDK users, nice looking ASM will enable you to ticket what or no longer it is API (which is basically written in ASM) is doing on the help of the scenes and must build using emulator debuggers more uncomplicated to ticket.

If you accomplish no longer wan’t to learn a language at all, GB Studio is an alternative to C and ASM.

# If you know C but no longer ASM

Select into consideration the targets, scope and time physique of your challenge. If you will cherish to start constructing at once then C and GBDK will build that easy. You would possibly perhaps presumably well moreover hang increasing publicity to ASM as time goes on due to the working with the hardware and monitoring down complications within the debugger.

On the diversified hand, whereas you need to develop your programming capacity design and hang overtime, learning to use ASM and RGBDS offers you with rather quite a bit of info about the Sport Boy hardware. As soon as you know ASM as properly as to C, you will hang rather quite a bit of flexibility in what tools you utilize for projects.

# If you know ASM

RGBDS with ASM is a accurate risk. That you simply can win the most easy performance out of the hardware, and there is an experienced community on hand to support.

One other risk is to attain out to us, and discuss the subject.

The very first bid to build in all cases is to learn the doctorsstart in fresh window, to grab how the Sport Boy works. In ASM, that is obligatory; in C, this would possibly perhaps occasionally help you ticket what a given library feature does. This can moreover help you ticket what’s likely on the Sport Boy, and what’s now not forever surely. (That you simply can persistently inquire, whereas you will hang doubts.)

I moreover suggest making an strive up neatly-behaved-gbdevstart in fresh window for sources and tutorials. There are rather quite a bit of priceless articles there, as properly as helper tools.

# ASM Advantage

• Modules
  Separate your sport into several “entities” that hang interaction together. Digicam, Player, NPCs, Loading zones, and so on. This simplifies coding, by permitting you to reason independently on smaller units. This facilitates development and reduces the amount of bugs.
• File your capabilities
  For every feature, write a comment asserting what it does, what memory it touches, and what registers it impacts. This can steer clear of conflicts, and help you optimize your code by minimizing the amount of registers you save when calling a feature.
• Notion earlier than writing
  You ought to thought what register is going to be feeble for what within your capabilities earlier than starting to write down them. Your goal is to lower the amount of register swapping. There is no overall rule, so surely be at liberty to drop by and inquire us, whereas you are uncertain.
• RGBASM -E and RGBLINK -n
  If you occur to load ROM.gb or ROM.gbc in BGB, it mechanically hundreds (if it exists) the file ROM.sym within the identical folder as the ROM. This provides symbols to the debugger, which – imagine me – helps a ton.

# Optimizing For GBDK

• Global variables
  Utilize as many world variables as you would possibly perhaps presumably well well presumably; the Sport Boy has rather quite a bit of RAM compared to diversified platforms akin to the NES, but is gradual at using the stack. Thus, minimizing the assorted of local variables, especially in carefully-called capabilities, will lower the time spent manipulating the stack.
• Optimized code
  Write code as efficient as likely. Infrequently there is a readability tradeoff, so I suggest you win the comment machine gun out and save some in each put.
• By default GBDK-2020 (after v4.0.1) will use the SDCC flag --max-allocs-per-node 50000 for an elevated optimization pass. You furthermore mght can interact to use –decide-code-velocity (optimize code period in direction of immediate code, presumably on the expense of codesize) or –decide-code-size (optimize code period in direction of compact code, presumably on the expense of codespeed).
• Inlining
  When performance is main steer clear of using capabilities whereas you would possibly perhaps presumably well well presumably inline them, which skips passing all arguments to the stack, largely. Macros will be your mates there. If wanted you would possibly perhaps presumably well well presumably moreover use inline ASM.
• NEVER use recursive capabilities
• AVOID printf
  printf clobbers a sizeable chunk of VRAM with pointless text tiles. As an alternative, it is main to sprintf to a buffer in WRAM, then save that on the conceal using a customised font.
• Geometry funcs
  Steer clear of the capabilities that plot geometry on-conceal (traces, rectangles, and so on.). The Sport Boy is now not forever surely designed for this roughly drawing formulation, and you will hang a onerous time mixing this with, yell, background art. Plus, the capabilities are fat gradual.
• const (obligatory!)
  Declaring a variable that would now not replace as const greatly reduces the amount of ROM, RAM, and CPU feeble.
  The technical reason on the help of that is that non-const values, especially arrays, are loaded to RAM from ROM in an extraordinarily inefficient contrivance. This takes up a LOT more ROM, and copies the price(s) to RAM when or no longer it is unneeded. (And the GB does no longer hang enough RAM for that to be viable.)
• Procure no longer use MBC1
  MBC1 is usually assumed to be the most easy of all MBCs… but it has a quirk that provides some overhead whenever ROM or SRAM financial institution switches are performed. MBC3 and MBC5 accomplish no longer hang this quirk, and accomplish no longer add any complexity. Using MBC1 has no valid use. (Let’s no longer discuss MBC2, either.)

If you are trying to win support from the community, crawl:

• To the ancient IRC channel, #gbdev on EFNetstart in fresh window [if you don’t have an IRC client, you can use the “Webchat login” box, just enter a username].
• To the more most modern gbdev Discord serverstart in fresh window or GBDK/ZGBstart in fresh window particular server.
• And to the GBDev forumsstart in fresh window!