Proposal for #169: Add TRSE, restructure, expand hardware, add links

website/guides/tools.md

@@ -14,7 +14,7 @@ head:
 
 This essay gives an overview of the Game Boy's capabilities, discussing the pros and cons of the available development tools, and providing a few tips to write more efficient code.
 
-Written by [ISSOtm](https://github.com/ISSOtm/) with help from [tobiasvl](https://github.com/tobiasvl), some updates by [bbbbbr](https://github.com/bbbbbr).
+Written by [ISSOtm](https://github.com/ISSOtm/) with help from [tobiasvl](https://github.com/tobiasvl), some updates by [bbbbbr](https://github.com/bbbbbr) and [numma_cway](https://github.com/nummacway).
 
 ---
 
@@ -30,7 +30,7 @@ If you want to program for the GBA, which is much more C-friendly (and C++ and R
 When someone wants to make their own game, one of the first problems they will encounter is picking the *tools* they will use. There current main options are:
 - RGBDS (Rednex Game Boy Development System) and the Game Boy's Assembly language (ASM)
 - GBDK-2020 (Game Boy Development Kit) and the C language
-- ZGB (an engine built on GBDK-2020) and the C language
+  - ZGB (an engine built on GBDK-2020) and the C language
 - GB Studio (a drag-and-drop game creator with scripting)
 
 The purpose of this document is to provide some insights and help you make the better choice if you're starting a new project. I will also provide some "good practice" tips, both for C and ASM, if you have already made up your mind or are already using one of these.
@@ -39,24 +39,36 @@ The purpose of this document is to provide some insights and help you make the b
 
 # Overview
 
-The original Game 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\]. Given that an instruction takes approximately 2 to 3 cycles, this gives the CPU a capacity of 333,000~500,000 instructions per second.
-Its LCD boasts 60 fps \[it's actually 59.73 fps\], which rounds up to between 50,000 and 80,000 instructions per frame. Suddenly not so much, eh?
-It also has 8 kB of RAM, and 8 kB of video RAM ; a 160x144 px LCD (thus slightly wider than it's tall), 4 colors, and 4-channel audio.
+The original Game Boy, codenamed the DMG (for Dot Matrix Game), has a 1 MiHz CPU \[the CPU is actually clocked at 4 MiHz, but every instruction takes up a multiple of 4 clocks, so it's often simplified to a 1 MiHz CPU\]. Most instructions take approximately 2 to 3 cycles, this gives the CPU a capacity of 333,000~500,000 instructions per second.
+Its LCD boasts 60 fps \[it's actually 59.73 fps\], which rounds up to between 5,000 and 8,000 instructions per frame. Suddenly not so much, eh? And half of that time, you won't be able to access VRAM data. The CPU handles only 8-bit and 16-bit values; among other things, it lacks support for floats, multiplication, division and 16-bit subtraction.
+
+The DMG has 8 KiB of RAM, and 8 KiB of video RAM; a 160x144 pixel LCD (thus slightly wider than it's tall), 4 colors, and 4-bit audio generated by 4 specialized audio channels.
 
 The Super Game Boy adds a few minor things, such as a customizable screen border, and some crude color. It's also slightly faster than the DMG.
 
-The Game Boy Color *can* \[if you tell it to\] unlock additional functionality, such as more fleshed-out color, a double-speed CPU, twice the video RAM and *four times* the RAM! (With caveats, obviously.)
+The Game Boy Color, codenamed CGB, *can* \[if you tell it to\] unlock additional functionality, such as more fleshed-out color, a double-speed CPU, twice the video RAM and *four times* the RAM! (With caveats, obviously.)
+
+The Game Boys' _audio processing unit_ is not designed to play arbitrary audio like voice samples, and the _pixel processing unit_ too has significant limitations:
+- Everything on the screen is composed of 384 (768 on CGB) _tiles_ – 8x8-pixel 2bpp images with no color mapping yet
+- Two 32x32-tile _maps_ that are used for the background and an optional _window_ (a background layer that is drawn on top of the background and can be placed in the bottom and/or right corner/edge)
+- Forty _objects_ ("sprites"), all being either 8x8 or 8x16 pixels (equal to 1 or 2 tiles)
+- Cannot really draw arbitrary images; instead, it takes a 160x144-pixel piece of the background and draws the window and the objects on top, all of the three being tile-based
+- Maximum of ten objects per scanline (generally considered to be the worst limitation)
+- Four colors per background palette, three per sprite palette
+- One background palette and two object palettes (eight each on the CGB); one is assigned to every tile where it is used
+
+Games are stored on cartridges. Originally limited to 32 KiB of ROM, several so-called [Memory Bank Controllers (MBCs)](https://gbdev.io/pandocs/MBCs.html) have boosted this to up to 8 MiB of ROM and added up to 128 KiB of cartridge RAM (also used for savegames). Since the CPU can only access a 16-bit address space (64 KiB), you can guess that more sophisticated games will have to use a lot of banking, so does making use of virtually any CGB feature.
 
 
-# Languages
+# Languages and Development Platforms
 
-The choice of programming language is important and can have a very large effect on a project. It determines how much work is involved, what will be possible, and how fast it will be able to run.
+The choice of programming language (or its absence) is important and can have a very large effect on a project. It determines how much work is involved, what will be possible, and how fast it will be able to run.
 
-### Assembly (ASM)
-Most games and programs for the Game Boy written in ASM will use RGBDS or WLA-DX.
+## Assembly (ASM)
+Most homebrew games and programs for the Game Boy written in ASM will use RGBDS or WLA-DX.
 
 Strengths:
-* Not too difficult to learn.
+* Not too difficult to learn (partially thanks to the CPU's limited instruction set).
 * Extremely powerful and flexible.
 * When well written it allows for maximum speed and efficiency on the limited resources of the Game Boy hardware.
 
@@ -66,45 +78,39 @@ Weaknesses:
 * Will require more time and learning to get up and running when compared with C.
 * Code may not be easily shared with ports of a game on other platforms.
 
+### [RGBDS](http://github.com/rednex/rgbds)
 
-### C
-C will typically be used with the SDCC compiler and GBDK-2020 or ZGB, though it can also be used on its own without a framework or with a different compiler/dev kit (such as [z88dk](https://github.com/z88dk/)).
+RGBDS is an actively maintained suite of programs that allow building a ROM using ASM (assembly). It contains three programs that perform different stages of the compilation, as well as a program that converts PNG images to the Game Boy's tile format. RGBDS is available for Linux, Windows and MacOS. There is also a [simple browser-based IDE](https://gbdev.io/rgbds-live/) (beta) for small ad-hoc projects.
 
 Strengths:
-* Allows for getting up and running faster than with ASM, especially when building on top of GBDK-2020 and ZGB.
-* The language abstractions make it relatively easy to implement ideas and algorithms.
-* C source debugging is available through Emulicious with the VSCode debug adapter, making it easier to understand problems if they arise.
-* ASM can be included in projects with C, either standalone or inline for speed critical features.
+* Very knowledgeable community with a lot of history.
+* Built in support for ROM banking.
+* Works quite well with BGB for debugging.
 
 Weaknesses:
-* The SDCC C compiler won't always generate code that runs as fast as skilled, hand-optimized assembly. It has matured a lot in the 20 years since the original GBDK, but bugs still turns up on occasion. On a platform with a slow CPU such as the Game Boy this can be a factor.
-* It’s easier to write inefficient code in C without realizing it. The Game Boy's CPU is only capable of performing 8-bit addition or subtraction, or 16-bit addition. Using `INT32`s is quite taxing on the CPU (it needs to do two consecutive 16-bit adds, and add the carry). See the tips below to avoid such blunders.
-* There is overhead due to C being a stack-oriented language, whereas the Game Boy's CPU is rather built for a register-oriented strategy. This most notably makes passing function arguments a lot slower, although SDCC has some optimizations for this.
-
-
-### Non-Programming Language option
-Using a GUI instead- If you don’t want to learn a programming language in order to make Game Boy games, then GB Studio is an option. See the [GB Studio](#gb-studio) section for more details.
+* Provides a limited amount of built-in code and functionality (does not include a large API like GBDK-2020 does), most of which revolve around macros and calculating constants at assembly-time (rather than on the Game Boy).
 
+### [WLA-DX](https://github.com/vhelin/wla-dx)
+WLA-DX is also sometimes used when writing in ASM, mostly due to its better struct support than RGBDS.
 
-# Development Platforms
+While RGBDS is made specifically for the Game Boy, WLA-DX targets many retro consoles. This means that if you're reading the docs, many things will not apply to the Game Boy.
 
-### [RGBDS](http://github.com/rednex/rgbds) with ASM
 
-RGBDS is an actively maintained suite of programs that allow building a ROM using ASM (assembly). It contains three programs that perform different stages of the compilation, as well as a program that converts PNG images to the Game Boy's tile format. RGBDS is available for Linux, Windows and MacOS.
+## C
+C will typically be used with the SDCC compiler and GBDK-2020 or ZGB, though it can also be used on its own without a framework or with a different compiler/dev kit (such as [z88dk](https://github.com/z88dk/)).
 
 Strengths:
-* Very knowledgeable community with a lot of history.
-* Built in support for ROM banking.
-* Works quite well with BGB for debugging.
+* Allows for getting up and running faster than with ASM, especially when building on top of GBDK-2020 and ZGB.
+* The language abstractions make it relatively easy to implement ideas and algorithms.
+* C source debugging is available through Emulicious with the VSCode debug adapter, making it easier to understand problems if they arise.
+* ASM can be included in projects with C, either standalone or inline for speed critical features.
 
 Weaknesses:
-* Provides a limited amount of built-in code and functionality (does not include a large API like GBDK-2020 does).
-
-### [WLA-DX](https://github.com/vhelin/wla-dx) with ASM
-WLA-DX is also sometimes used when writing in ASM, mostly due to its better struct support than RGBDS.
-
+* The SDCC C compiler won't always generate code that runs as fast as skilled, hand-optimized assembly. It has matured a lot in the 20 years since the original GBDK, but bugs still turns up on occasion. On a platform with a slow CPU such as the Game Boy this can be a factor.
+* It’s easier to write inefficient code in C without realizing it. The Game Boy's CPU is only capable of performing 8-bit addition or subtraction, or 16-bit addition. Using `INT32`s is quite taxing on the CPU (it needs to do two consecutive 16-bit adds, and add the carry). See the tips below to avoid such blunders.
+* There is overhead due to C being a stack-oriented language, whereas the Game Boy's CPU is rather built for a register-oriented strategy. This most notably makes passing function arguments a lot slower, although SDCC has some optimizations for this.
 
-### [GBDK-2020](https://github.com/Zal0/gbdk-2020) with C
+### [GBDK-2020](https://github.com/Zal0/gbdk-2020)
 GBDK-2020 is a development kit and toolchain built around the SDCC C compiler which allows you to write programs in C and build ROMs. It includes an API for interfacing with the Game Boy. GBDK-2020 is a modernized version of the original [GBDK](http://gbdk.sourceforge.net). It's available for Linux, Windows and MacOS.
 
 Strengths:
@@ -118,8 +124,9 @@ Weaknesses:
 * ROM banking may require more management in code than RGBDS.
 
 
-### [ZGB](https://github.com/Zal0/ZGB/) with C & GBDK-2020
+### [ZGB](https://github.com/Zal0/ZGB/)
 ZGB is a small engine for the Game Boy built on top of GBDK-2020 and written in C.
+
 Strengths:
 * The basic graphics, sound and event structure are all pre-written, so it’s faster and easier to start writing a game.
 * Several open source games built with it are available as examples.
@@ -129,6 +136,32 @@ Weaknesses:
 * Even more of the hardware configuration and processing is taken care of behind the scenes than with GBDK, so less experienced users may have trouble when problems arise.
 
 
+
+## Pascal
+Being a high-level language, Pascal generally has the same _technical_ strengths and weaknesses as C. More limitations arise from having a single implementation by a single, yet active maintainer. The community for the Game Boy target is tiny, to say the least.
+
+### [Turbo Rascal Syntax Error, ";" expected but "BEGIN"](https://lemonspawn.com/turbo-rascal-syntax-error-expected-but-begin/the-turbo-rascal-syntax-error-programming-language/)
+TRSE is an IDE with its own Pascal-like programming language of the same name. If you already know Pascal and your idea doesn't need to push the hardware to its limits, it might be worth a look.
+
+Strengths:
+* Easy to set up.
+* Complete IDE (comes with a graphics editor).
+* Contains some examples.
+* Multiple retro target platforms.
+* Easy to add ASM sections.
+
+Weaknesses:
+* Pascal dialect with some unusual quirks.
+* Incomplete documentation.
+* You'll quickly notice that the Game Boy isn't its primary target platform.
+* Generated ASM code can be weirdly inefficient at times.
+
+
+
+## Non-Programming Language option
+If you don’t want to learn a programming language in order to make Game Boy games, then GB Studio is an option.
+
+
 ### [GB Studio](https://www.gbstudio.dev/)
 
 GB Studio is a drag-and-drop game creator for the Game Boy that does not require knowledge of programming languages. Games are built using a graphical interface to script graphics, sound and actions. It is available for Linux, Windows and MacOS.
@@ -139,14 +172,14 @@ Strengths:
 * Very active community for help and support.
 
 Weaknesses:
-* It’s games will tend to be slower than both ASM and C.
+* Its games will tend to be slower than both ASM and C.
 * There is a limited set of commands to script with and some artificially smaller restrictions on palettes, sprites, background tiles and other hardware features (due to how GB Studio manages them).
-* Games may be more constrained or require workarounds to do things if they don’t easily fit within the available scripting, graphics and sound tools. (Though it is possible for advanced users to do a “engine eject” and add more functionality using C and ASM.)
+* Games may be more constrained or require workarounds to do things if they don’t easily fit within the available scripting, graphics and sound tools. (Though it is possible for advanced users to do an “engine eject” and add more functionality using C and ASM.)
 
 
 
 # Emulators and debuging tools
-Accurate emulators and debugging tools are tremendously helpful for testing and tracking down problems. The following Game Boy emulators provide excellent accuracy and include a variety of different features.
+Accurate emulators and debugging tools are tremendously helpful for testing and tracking down problems. The following Game Boy emulators provide [excellent accuracy](https://vulcandth.github.io/GBEmulatorShootout/) and include a variety of different features.
 
 * [BGB](http://bgb.bircd.org) has a convenient (ASM) debugger, though its minimal interface can be confusing at first. It is available for Windows only, but runs almost flawlessly with Wine.
 
@@ -157,9 +190,9 @@ Accurate emulators and debugging tools are tremendously helpful for testing and
 * [Gambatte](http://github.com/sinamas/gambatte) lacks a debugger and must be compiled from source, but is packaged both in [RetroArch](http://retroarch.com) (Linux, Windows and Mac) and [BizHawk](http://tasvideos.org/BizHawk.html) (Windows-only).
 
 
-* Purists prefer to also run their games on hardware, which is possible thanks to flashcarts. My personal recommendation is [krikzz's carts](http://krikzz.com/store/), particularly the [Everdrive GB X5](https://krikzz.com/store/home/47-everdrive-gb.html).
+* Purists prefer to also run their games on hardware, which is possible thanks to flashcarts. Consider [krikzz's carts](http://krikzz.com/store/), particularly the [Everdrive GB X5](https://krikzz.com/store/home/47-everdrive-gb.html). Based on a microSD card, you don't need a flasher and can start right away. The EZ-Flash Jr. also has good game compatibility and even comes with a real-time clock, but has a higher power consumption and a sluggish menu if you have many ROMs. Beware of Everdrive bootlegs out there. When using any bootlegs (SD-based or single games), don't expect support for more than 4 MiB of ROM and 32 KiB of cartridge RAM, and stick to MBC5. If you are going for a high-quality physical release, try to keep your game as small as possible for lower production costs.
 
-Side note : if you are using VBA or VBA-rr, **stop using them right now**. These emulators are extremely inaccurate, and also contain **severe security flaws**. I strongly urge you to ditch these emulators and spread the word.
+Side note: if you are using VBA or VBA-rr, **stop using them right now**. These emulators are extremely inaccurate, and also contain **severe security flaws**. I strongly urge you to ditch these emulators and spread the word.
 
 
 
@@ -207,6 +240,8 @@ I also recommend looking up [awesome-gbdev](https://gbdev.io/resources.html) for
 - *RGBASM `-E` and RGBLINK `-n <symfile>`*<br>
   When you load `ROM.gb` or `ROM.gbc` in BGB, it automatically loads (if it exists) the file `ROM.sym` in the same folder as the ROM. This adds symbols to the debugger, which - believe me - helps *a ton*.
 
+You can find snippets for common problems in the [GB ASM Tutorial cheat sheet](https://gbdev.io/gb-asm-tutorial/cheatsheet.html) and over at [pret's ASM optimization guide](https://github.com/pret/pokecrystal/wiki/Optimizing-assembly-code).
+
 
 ## Optimizing For GBDK
 
@@ -233,5 +268,5 @@ I also recommend looking up [awesome-gbdev](https://gbdev.io/resources.html) for
 
 If you want to get help from the community, go:
 - To the historical IRC channel, #gbdev on [EFNet](http://efnet.net) \[if you don't have an IRC client, you can use the "Webchat login" box, just enter a username\].
-- To the more recent [gbdev Discord server](https://gbdev.io/chat.html) or [GBDK/ZGB](https://github.com/Zal0/gbdk-2020#discord-servers) specific server.
+- To the more recent [gbdev Discord server](https://gbdev.io/chat.html) or [GBDK/ZGB](https://github.com/Zal0/gbdk-2020#discord-servers) specific server. GB Studio also has [its Discord server](https://discord.gg/bxerKnc).
 - And to the [GBDev forums](http://gbdev.gg8.se/forums)!