gbasm

A JavaScript Gameboy Assembler

gbasm is a JavaScript based compiler for Gameboy z80 assembly code.

gbasm is mainly being developed for and tested with Tuff.

Installation and Usage

• Install Node.js
• Now install gbasm by running npm install -g gbasm

Usage: gbasm [options] [sources]

   --outfile, -o <s>: The name of the output rom file (default: game.gb)
      --optimize, -O: Enable instruction optimizations
   --mapfile, -m <s>: Generates a ASCII overview of the mapped ROM space
   --symfile, -s <s>: Generates a symbol map compatible with debuggers
  --jsonfile, -j <s>: Generates a JSON data dump of all sections with their data, labels, instructions etc.
        --silent, -S: Surpresses all logging
         --debug, -d: Enable support for custom "msg" debug opcodes',
       --verbose, -v: Surpresses all logging
           --version: Displays version information
              --help: Displays this help text

Output Options

• __ --outfile / -o __

  Specifies the filename of the generated ROM image.

• __ --optimize / -O __

  Turns on assembly optimizations which are automatically performed during linkage.

• __ --mapfile / -m__

  Generates a ASCII overview of the mapped ROM areas.

• __ --symfile / -s __

  Generates a symbol map file for use with Debuggers (e.g. bgb)

• __ --debug / -d __

  Enables support for custom msg opcodes for use with Debuggers (e.g. bgb)

  ; This will log "Debug Message" when run in the debugger
  msg "Debug Message"
  

  Note: The msg opcode will be ignored when compiling without the flag.

• __ --jsonfile / -j __

  Generates a json file that contains the fully linked ROM data serialized into a detailed format useable for further, custom processing.

Compatibility Notes

gbasm is mostly compatible with rgbds but there are some deviations and additions:

General

• gbasm is a multipass compiler, meaning the all sources files and definitions are parsed before resolving any names or sizes.

Syntax

• The load accumulator and increment/decrement hl type instructions only take hli and hld as their second operand
• Memory operands do only support [ and ] in their syntax
• All names and labels which start with an underscore are treated as being local / private to the file they were defined in

Macros

• Most of the pre-defined macros from rgbds are available (e.g. COS, STRLWR etc.)

• User defined macros come in two flavors:

  • Expression Macros

  These macros contain only a single expression statement and can be used as values everywhere a built-in macro could be used:

  MACRO add(@a, @b)
    @a + @b
  ENDMACRO
  
  DB add(2, 5) ; essentially DB 7
  

  Expression Macros can take Numbers and Strings as their arguments.

  • Expansion Macros

  These are macros in the classical sense which just expand into additional assembler code:

  MACRO header()
    DB $11,$22,$33,$44,$55
    DW $1234,$4567
  ENDMACRO
  
  header(); expands into the DB and DW diretives above
  

  In addition to Strings and Numbers, expansion macros can also take Registers as their arguments.

  MACRO ld16(@number, @a, @b)
    ld @a,@number >> 8
    ld @b,@number & $ff
  ENDMACRO
  
  ld16($1234, b, c); turns into ld b,$12 and ld c,$34
  

License

Licensed under MIT.