Introduction

Yagbas is a programming language that builds programs for the Game Boy, as well as for the three other compatible devices: the Game Boy Pocket, Super Game Boy, and Game Boy Color. A lot of useful documentation for this device family can be found in the Pan Docs.

Because of the limited nature of the Game Boy's CPU instruction set, yagbas does not aim to be a "general purpose" programming language. Instead, it is intended to be close to "assembly with modern syntax", including control flow constructs. The language is intended to look "like Rust", when possible.

Source Files

Source code files for yagbas must be written using UTF-8 encoded text files. Yagbas itself only relies on the Ascii subset of UTF-8, but code comments can be written using the full unicode range.

\r\n, \r, and \n are all treated as "a newline" in yagbas.

Newlines act as an implicit separation between statements in code, but whitespace is not otherwise significant. Explicit statement separation can be done with semicolon characters when desired.

By convention semicolons are not used, and each statement is simply put on a separate source line.

Source code files for yagbas conventionally use the .yag extension.

Comments

A single line comment starts with // and goes to the end of the line.

A multi-line comment starts with /* and ends with */. Multi-line comments can be nested.

A single line comment marker will "comment out" a multi-line comment close marker that appears later on the same line.

Items

Language constructs that appear at the top level of a file are called "items".

Conceptually, items are unordered within a program. One item may refer to another that is later within the source code.

Identifiers

All items are named by a particular "identifier".

An identifier must start with an underscore or an ascii letter, and can be continued with underscores, ascii letters, or digits.

There's no length limit on identifiers.

All item identifiers must be globally unique.

Any keyword of yagbas (such as register names, loop, return, etc) cannot be used as an identifier.

Functions

A function declaration looks like

fn NAME() {
  // statements here
}

The fn keyword marks the start of a function.

Next is an identifier that names the function, followed by an empty set of parentheses. Future versions of the language may put things into the parentheses, but in the current version they are always empty.

Finally, we have a set of braces around the code of the function.

The conventional code style for functions is as follows:

• Names are snake_case
• Indentation is 2 spaces
• The opening brace is on the same line as the function name

fn main()

The main function has a special meaning.

After booting, the Game Boy jumps to the "Entry Point" of the ROM ($0100) and begins running there. However, the entry point can only be 4 bytes long, because after that is the rest of the ROM header rather than meaningful instructions. The Entry Point is expected to jump to the actual beginning of the program.

The yagbas compiler always uses di; jp main as the effective code for the entry point. If your program does not include a main function, compilation will cause an error.

Statements

A function contains 1 or more statements.

Statements in yagbas map fairly directly to Game Boy assembly, though many statements expand to more than one assembly instruction during compilation.

Function Calls

Calling Another Function

One function can call to another by writing the name of the function to call and then an empty set of parentheses.

function_name()

Similar to the declaration of a function, future versions of yagbas may place something within the parentheses, but currently they are always empty.

Returning From A Function

To return control to the calling function use the return keyword.

return

Control Flow

Looping

To loop many times over a block of code, use the loop keyword followed by the statements of the loop in braces.

loop {
  // statements here.
}