NESFab

NROM is the simplest mapper. It is easy to use and offers good performance, but is lacking in features and memory size.

Note	8 KiB variants of NROM are not currently supported.

Memory Sizes:

Name	Min	Max	Default
PRG (Code)	16 KiB	32 KiB	32 KiB
CHR (Tilesets)	8 KiB	8 KiB	8 KiB

Name

Min

Max

Default

16 KiB

32 KiB

8 KiB

Other Details:

Name Description

Name	Description
Mirroring	Fixed H or V
Bus Conflicts	N/A
SRAM	By default, no
`state` Register	N/A
Unsafe Bank Switches	N/A

Fixed H or V

N/A

By default, no

N/A

N/A

7.2. `anrom`

ANROM is similar to BNROM, but allows mirroring to be changed on the fly.

Note	Related mappers like AMROM can be had using configuration options.

Memory Sizes:

Name	Min	Max	Default
PRG (Code)	32 KiB	512 KiB	256 KiB
CHR (Tilesets)	8 KiB (RAM)	8 KiB (RAM)	8 KiB (RAM)

Name

Min

Max

Default

32 KiB

512 KiB

256 KiB

8 KiB (RAM)

Other Details:

Name Description

Name	Description
Mirroring	1-Page switchable
Bus Conflicts	By default, no
SRAM	By default, no
`state` Register	Bit 4 changes mirroring
Unsafe Bank Switches	Acceptable risk

1-Page switchable

By default, no

By default, no

Bit 4 changes mirroring

Acceptable risk

7.3. `bnrom`

BNROM supports a huge amount of PRG, making it an excellent choice for large games.

Memory Sizes:

Name	Min	Max	Default
PRG (Code)	32 KiB	8192 KiB	128 KiB
CHR (Tilesets)	8 KiB (RAM)	8 KiB (RAM)	8 KiB (RAM)

Name

Min

Max

Default

32 KiB

8192 KiB

128 KiB

8 KiB (RAM)

Other Details:

Name Description

Name	Description
Mirroring	Fixed H or V
Bus Conflicts	By default, yes
SRAM	By default, no
`state` Register	N/A
Unsafe Bank Switches	N/A

Fixed H or V

By default, yes

By default, no

N/A

N/A

7.4. `unrom`

UNROM supports lots of PRG, like BNROM, but differs in that it has a fixed bank. Because of this, UNROM requires manual ROM layout with the +static modifier.

Note	Typically, BNROM is better for NESFab than UNROM, as it does not require the use of `+static`.

Memory Sizes:

Name	Min	Max	Default
PRG (Code)	32 KiB	4096 KiB	64 KiB
CHR (Tilesets)	8 KiB (RAM)	8 KiB (RAM)	8 KiB (RAM)

Name

Min

Max

Default

32 KiB

4096 KiB

64 KiB

8 KiB (RAM)

Other Details:

Name Description

Name	Description
Mirroring	Fixed H or V
Bus Conflicts	By default, yes
SRAM	By default, no
`state` Register	N/A
Unsafe Bank Switches	N/A

Fixed H or V

By default, yes

By default, no

N/A

N/A

7.5. `30` (UNROM 512)

Mapper 30 is an extended form of UNROM with CHRRAM banking. Like UNROM, mapper 30 requires manual ROM layout with the +static modifier.

Memory Sizes:

Name	Min	Max	Default
PRG (Code)	32 KiB	512 KiB	512 KiB
CHR (Tilesets)	32 KiB (RAM)	32 KiB (RAM)	32 KiB (RAM)

Name

Min

Max

Default

32 KiB

512 KiB

32 KiB (RAM)

Other Details:

Name Description

Name	Description
Mirroring	Fixed H, V, 4, or 1
Bus Conflicts	By default, no
SRAM	By default, no
`state` Register	High 3 bits switch CHR and mirroring
Unsafe Bank Switches	Acceptible risk

Fixed H, V, 4, or 1

By default, no

By default, no

High 3 bits switch CHR and mirroring

Acceptible risk

7.6. `cnrom`

CNROM is similar to NROM, but has multiple CHR banks.

Memory Sizes:

Name	Min	Max	Default
PRG (Code)	32 KiB	32 KiB	32 KiB
CHR (Tilesets)	8 KiB	2048 KiB	32 KiB

Name

Min

Max

Default

32 KiB

8 KiB

2048 KiB

32 KiB

Other Details:

Name Description

Name	Description
Mirroring	Fixed H or V
Bus Conflicts	N/A
SRAM	By default, no
`state` Register	Sets CHR bank.
Unsafe Bank Switches	N/A

Fixed H or V

N/A

By default, no

Sets CHR bank.

N/A

7.7. `gnrom`

GNROM offers both PRG and CHR banks.

Note	Related mappers like MHROM can be had using configuration options.

Memory Sizes:

Name	Min	Max	Default
PRG (Code)	32 KiB	512 KiB	128 KiB
CHR (Tilesets)	8 KiB (RAM)	128 KiB (RAM)	32 KiB (RAM)

Name

Min

Max

Default

32 KiB

512 KiB

128 KiB

8 KiB (RAM)

128 KiB (RAM)

32 KiB (RAM)

Other Details:

Name Description

Name	Description
Mirroring	Fixed H or V
Bus Conflicts	By default, yes
SRAM	By default, no
`state` Register	Low 4 bits switch CHR
Unsafe Bank Switches	Acceptable risk

Fixed H or V

By default, yes

By default, no

Low 4 bits switch CHR

Acceptable risk

7.8. `colordreams`

COLORDREAMS is similar to GNROM, but reverses the bank switching nybbles.

Note	PRG above 128 KiB may not be supported on physical cartridges.

Memory Sizes:

Name	Min	Max	Default
PRG (Code)	32 KiB	512 KiB	128 KiB
CHR (Tilesets)	8 KiB (RAM)	128 KiB (RAM)	128 KiB (RAM)

Name

Min

Max

Default

32 KiB

512 KiB

128 KiB

8 KiB (RAM)

128 KiB (RAM)

Other Details:

Name Description

Name	Description
Mirroring	Fixed H or V
Bus Conflicts	By default, yes
SRAM	By default, no
`state` Register	High 4 bits switch CHR
Unsafe Bank Switches	Acceptable risk

Fixed H or V

By default, yes

By default, no

High 4 bits switch CHR

Acceptable risk

7.9. `gtrom`

GTROM is a modern mapper designed to be cheap while offering a wide range of features.

Note	See the standard library file `lib/mapper/gtrom.fab`.

Memory Sizes:

Name	Min	Max	Default
PRG (Code)	32 KiB	512 KiB	512 KiB
CHR (Tilesets)	16 KiB (RAM)	16 KiB (RAM)	16 KiB (RAM)

Name

Min

Max

Default

32 KiB

512 KiB

16 KiB (RAM)

Other Details:

Name Description

Name	Description
Mirroring	Fixed 4
Bus Conflicts	Never
SRAM	By default, no
`state` Register	High 4 bits switch nametable, CHR, and LEDs
Unsafe Bank Switches	Acceptable risk

Fixed 4

Never

By default, no

High 4 bits switch nametable, CHR, and LEDs

Acceptable risk

7.10. `mmc1`

MMC1 is a flexible ASIC mapper with CHR banking and mirroring controls. Unfortunately, MMC1 is very slow to interface.

Note	See the standard library file `lib/mapper/mmc1.fab`.

Memory Sizes:

Name	Min	Max	Default
PRG (Code)	32 KiB	256 KiB	256 KiB
CHR (Tilesets)	8 KiB	128 KiB	128 KiB

Name

Min

Max

Default

32 KiB

256 KiB

8 KiB

128 KiB

Other Details:

Name Description

Name	Description
Mirroring	Switchable H, V, or 1
Bus Conflicts	Never
SRAM	By default, no
`state` Register	Sets internal $8000 register
Unsafe Bank Switches	Not recommended

Mirroring

Switchable H, V, or 1

Bus Conflicts

Never

SRAM

By default, no

state Register

Sets internal $8000 register

Not recommended

7.11. `mmc3`

MMC3 is a flexible ASIC mapper with CHR banking, mirroring controls, and a scanline counter. Because MMC3 uses fixed banks, it requires manual ROM layout with the +static modifier. See mapper 189 for an alternative.

Note	In NESFab’s implementation of MMC3, the two highest bits of `$8000` cannot and should not be set. When writing to `$8000`, leave the two highest bits zero.

Note	See the standard library file `lib/mapper/mmc3.fab`.

Memory Sizes:

Name	Min	Max	Default
PRG (Code)	32 KiB	2048 KiB	512 KiB
CHR (Tilesets)	8 KiB	256 KiB	256 KiB

Name

Min

Max

Default

32 KiB

2048 KiB

512 KiB

8 KiB

256 KiB

Other Details:

Name Description

Name	Description
Mirroring	Switchable H or V
Bus Conflicts	Never
SRAM	By default, no
`state` Register	N/A
Unsafe Bank Switches	Not recommended

Switchable H or V

Never

By default, no

N/A

Not recommended

7.12. `189` (MMC3 Variant)

Mapper 189 is a MMC3 variant originally designed for bootleg games. Is it an excellent choice for those wanting MMC3 features in NESFab, but has the caveat of being an uncommon mapper. Unlike mmc3, it does not support SRAM.

Note	Unlike MMC3, mapper 189 allows the highest bit of `$8000` to be set.

Note	See the standard library file `lib/mapper/mmc3.fab`.

Memory Sizes:

Name	Min	Max	Default
PRG (Code)	32 KiB	512 KiB	128 KiB
CHR (Tilesets)	256 KiB	256 KiB	256 KiB

Name

Min

Max

Default

32 KiB

512 KiB

128 KiB

256 KiB

Other Details:

Name Description

Name	Description
Mirroring	Switchable H or V
Bus Conflicts	Never
SRAM	No
`state` Register	N/A
Unsafe Bank Switches	Acceptible risk

Switchable H or V

Never

N/A

Acceptible risk

7.13. `mmc5`

MMC5 is a powerful ASIC mapper with many features. Notably, it extends rendering with 8x8 background attributes, per-tile banking, and vertical splits, extends audio with expansion channels, provides a scanline counter, and even has hardware to perform multiplication.

Unfortunately, MMC5 is a difficult mapper to reproduce and emulate, meaning it’s not usually recommended for homebrew releases.

Note	See the standard library file `lib/mapper/mmc5.fab`.

Memory Sizes:

Name

Min

Max

Default

128 KiB

1024 KiB

GitHub Documentation *NESDev Wiki Page

128 KiB

1024 KiB

Other Details:

Name Description

Switchable

Never

By default, yes

N/A

Recommended

Note	Enabling `unsafe-bank-switch` enables NESFab to use the MMC5 multiplication hardware for arithmetic.

Note	Enabling `expansion-audio` enables NESFab to use the MMC5’s expanded sound channels.

7.14. `rainbow`

Rainbow is a modern ASIC mapper with many features similar to mmc5, designed for commercial homebrew releases. Because it is so recent, emulation support may be spotty.

Note	See the standard library file `lib/mapper/rainbow.fab`.

Memory Sizes:

Name

Min

Max

Default

32 KiB

8192 KiB

8 KiB

8192 KiB

Other Details:

Name Description

Switchable

Never

By default, yes

N/A

N/A

Note	Enabling `expansion-audio` enables NESFab to use Rainbow’s expanded sound channels.

8. Identifiers

Identifiers may contain letters, numbers, and underscores, but they cannot start with a number. To differentiate types names from other identifiers, the following rules apply:

User-defined types are written in PascalCase
Other definitions are written in snake_case or UPPERCASE_SNAKE_CASE.

For top-level definitions, identifiers beginning with _ are visible only in their containing file. In other languages, this behavior is sometimes called private.

Example:

Foo    // A type name.
foo    // A definition which isn't a type.
_foo   // An identifier only visible to this file.

9. Value Semantics

Values in NESFab are always passed and stored by value, not by reference. This means that when you call a function, its parameters will be copies of the arguments passed.

For example:

fn foo(U x) U
    x += 5
    return x

fn bar()
    U y = 10
    U z = foo(y)

At the end of bar, variable y will have the value 10, while variable z will have the value 15.

10. Indentation

Indentation refers to the spaces at the beginning of each line. In NESFab, indentation is significant and alters the behavior of code.

Indentation is used to create code blocks, where every line but the first is indented using spaces (not tabs). The amount of spaces is up to you, but it must be consistent throughout the block.

FIRST LINE
    INDENTED LINE
    INDENTED LINE
    INDENTED LINE

Code blocks can be nested:

FIRST BLOCK
    INDENTED LINE
    INDENTED LINE
    SECOND BLOCK
        INDENTED LINE
        INDENTED LINE
    THIRD BLOCK
        INDENTED LINE
        INDENTED LINE

11. Banks

The NES uses a 16-bit address space, but most games need more data than 16-bits can represent. To overcome this limitation, machine code can be broken up into segments called "banks", and hardware on the cartridge can switch between these banks at runtime.

In NESFab, banks are automatically handled for you, meaning you do not need to worry about them much. However, it is still useful to know a bit about them, to clarify how things work under the hood.

Pointers and Addressing: Implementation Details

When banks are involved, rather than addressing using 16-bit pointers, 24-bit pointers are used instead. A 24-bit pointer can be seen as a 16-bit address paired with an 8-bit integer representing the bank.

When dereferencing a 24-bit pointer, first the bank is swapped into memory using the 8-bit integer, then the data is read using the 16-bit address. The caveat is, the machine code performing the dereference needs to be in memory too. Depending on the mapper, this can involve duplicating the machine code across multiple banks, or storing the machine code in a specific location which won’t be switched out.

12. Groups

Groups organize globals together based on how they are used in the program. In NESFab, each global variable and pointer-addressible array is associated with a group.

There are two ways to declare groups: vars and data.

vars is for variables (RAM).
data is for read-only data (ROM).

Furthermore, data has two variants: data and omni data.

data is for read-only data that exists at a single address in a single bank.
omni data is for read-only data that exists at a single address, but is duplicated across multiple banks.

As a guideline, omni data uses more ROM space, but has better performance than data. Typically, it is recommended to use data for most everything, and only use omni data for small look-up tables that are frequently used.

Note	The variables and data belonging to groups are always global and exist at top-level scope.

Why groups?

To the programmer, the purpose of groups are:

To organize code.
To specify the storage of a variable.

To the compiler, the purpose of groups are:

To enable the compiler to smartly allocate variables by reusing RAM addresses.
To facilitate mappers with multiple banks, enabling smarter linking.
To simplify pointer aliasing optimizations.

When are groups mentioned?

When declaring groups.
In pointer types.
In a preserves modifier.
In a stows modifier.
In an employs modifier.
In a vars modifier.
In a data modifier.

How does one use groups?

For variables, it often makes sense to have at least one vars group per mode:

vars /main_menu
    U cursor_y

vars /game
    U player_x
    U player_y

Often, certain variables will be used across different modes. These can receive their own groups:

vars /high_scores
    UU high_score = 0

vars /settings
    Bool swap_buttons = false
    Bool mute = false

You can use these variables without any special syntax. The compiler infers everything for you:

fn move_right()
    player_x += 1

The exception to this is when defining an asm fn. The compiler cannot infer the groups it uses, and so an employs modifier is required:

asm fn move_right()
: employs /game
    inc &player_x
    rts

For data, create a group for each schema.

data /levels
    [] level1
        // ...
    [] level2
        // ...

data /songs
    [] song1
        // ...
    [] song2
        // ...

Then you can use pointers to access this data:

fn load_level(CCC/levels level)
    // ...

13. Comments

NESFab supports two kinds of comments: single-line and multi-line.

13.1. Single-Line Comments

Single-line comments begin with the character sequence //, and terminate at the end of the line.

// This is a single-line comment.

ct U foo = 10 // You can put them after lines of code to document it.

13.2. Multi-Line Comments

Multi-line comments begin with the character sequence /* on a new line, and terminate with the character sequence */, followed by a line ending.

Note	Unlike other languages, multi-line comments cannot share lines with code.

/*
   This is a multi-line
   comment!
*/

/* This is also a
   multi-line comment! */

ct U foo = 10 /* This won't compile.
Multi-line comments cannot share lines with code. */

/*
   This won't compile.
   Multi-line comments cannot share lines with code.
*/ ct U foo = 10

14. Byte Blocks

Byte blocks are a special syntax used to define inline assembly code and PAA data.

14.1. Typed Data

Data can be inserted into byte blocks using a syntax identical to casts.

Syntax:

Type(values...)

Type is a type name.
values are a comma-separated list of expressions.

The value is cast, then inserted into the byte block with the following order:

For numeric types, the bytes are inserted in little-endian order.
For structures, the first member is inserted first, then the second, and so on.
For TEAs, the first element is inserted first, then the second, and so on.
For VECs, the first element is inserted first, then the second, and so on.

Example:

data /some_group
    [] some_data
        U(10)
        UU(2000)
        U[3](1,2,3)

14.2. Untyped Data

The type name of typed data can be elided, causing the type to inferred from the expression.

Syntax:

(values)

values is an expression.

The value is inserted into the byte block following the rules of typed data.

Example:

data /some_group
    [] some_data
        (U(10) + U(20))
        (UU(300).x)

14.3. Assembly Instructions

Assembly instructions can be inserted into byte blocks with a syntax similar to 6502 assemblers.

Syntaxes:

op           // Implied
op #num      // Immediate
op addr      // Direct (Zero page or absolute)
op addr      // Relative
op (addr)    // Indirect
op addr, x   // Direct, X
op addr, y   // Direct, Y
op (addr, y) // Indirect, X
op (addr), y // Indirect, Y

op is one of the op codes listed below in all uppercase, or all lowercase letters.
num is a value of type U.
addr is a value of type AA.

Valid Op Codes:

adc
and
asl
bcc
bcs
beq
bit
bmi
bne
bpl
brk
bvc
bvs
clc
cld
cli
clv
cmp
cpx
cpy
dec
dex
dey
eor
inc
inx
iny
jmp
jsr
lda
ldx
ldy
lsr
nop
ora
pha
php
pla
plp
rol
ror
rti
rts
sbc
sec
sed
sei
sta
stx
sty
tax
tay
tsx
txa
txs
tya
lax
axs
anc
alr
arr
sax
skb
ign
dcp
isc
rla
rra
slo
sre

Example:

data /some_group
    [] some_data
        lda #30
        sta $2003
        ldy #0
        lda ($2000), y
        sta ($00, x)

14.4. Special Statements

The following statements have special meaning inside of byte blocks:

label
nmi

In addition, the following statements have special meaning inside of asm fn byte blocks:

fn
goto
goto mode
switch
push
pop

15. Function Pointers and Function Sets

Although NESFab supports function pointers, their use is more limited when compared to other languages.

For a function to compatible with function pointers, it must belong to a function set. Function sets are defined by prefixing the function’s name with a set name, followed by a period:

fn foo.bar() // Declare a function 'bar' in the function set 'foo'.

fn foo.qux() // Declare another function 'qux' in the function set 'foo'.

All functions belonging to the set must have the same type signature.

To reference a function belonging to a function set normally, you must include the function set name:

foo.bar() // Call 'bar'.

Using the @ operator, you can retrieve a function pointer. Note that function pointers have Fn types.

Fn.foo my_ptr = @(foo.bar)

Function pointers can be called using the regular function call syntax:

Fn.foo my_ptr = @(foo.bar)
my_ptr() // Call it.

Limitation: One calling thread only

Unfortunately, function pointers can only be called from a single thread. For example, the code below will not compile, as it calls from two different threads:

vars
    Fn.foo my_ptr

nmi my_nmi()
    my_ptr()

irq my_irq()
    my_ptr()

If you need behavior like this, avoid function pointers and instead use switch.

Limitation: No asm support

Currently, function pointers cannot be called from asm fn contexts.

16. Keywords

16.1. `if`

The if statement allows for conditional execution of code blocks. It behaves like if in most programming languages.

Syntax:

if expression
    code block

The conditional expression of if will be converted to Bool. If this evaluates to true, the body of the if statement will be executed.

16.1.1. `if` statement (byte block)

In byte blocks, the if statement enables conditional compilation of byte block data.

Syntax:

if condition
    byte block

condition is a compile-time constant value convertable to Bool.

Example:

lda #10
if MY_CONSTANT == 3
    sta &foo
tax

Note	In the current implementation, named labels cannot exist inside conditional blocks. Anonymous labels can, with caveats.

16.2. `else`

The else statement allows for control flow to branch between two code blocks. It behaves like else in most programming languages.

This statement must be paired with a corresponding if.

Syntax:

if expression
    code block
else
    code block

If the corresponding if evaluates to false, the body of the else statement will be executed.

For visual appeal, other statements may follow the else keyword on the same line, including if, for, and while. This looks like:

if expression
    code block
else if expression
    code block
else
    code block

16.2.1. `else` (byte block)

Like if statement (byte block), else is also usable in byte blocks.

16.3. `while`

The while statement allows for looping control flow. It behaves like while in most programming languages.

Syntax:

while condition
    code block

condition is an expression converted to Bool. While this expression evaluates to true, the loop body will execute. After the code in code block executes, control flow jumps back to the condition test.

Modifiers:

-unroll, +unroll
+unloop

16.4. `for`

The for statement allows for looping control flow, with more features than while. It behaves like for in most programming languages.

Syntax:

for initialization ; condition ; iteration
    code block

initialization executes before the loop and can be an expression or a variable initialization.
condition is an expression converted to Bool. While this expression evaluates to true, the loop body will execute.
iteration is an expression to be run at the end of every iteration (following the code block).

Any of these expressions may be empty. An empty condition is equivalent to true.

After the code in code block executes, iteration executes, and then control flow jumps back to the condition test.

Like while, the keywords break and continue may be used inside of a for.

For visual appeal, the expressions of for may be put on separate lines starting with the ; character, like so:

for initialization
; condition
; iteration
    code block

Modifiers:

-unroll, +unroll
+unloop

16.5. `do`

The do keyword can be prefixed to either while or for to alter their behavior. A loop with do skips the condition check of its first iteration.

Syntax:

do while condition
    code block

do for initialization ; condition ; iteration
    code block

Modifiers:

-unroll, +unroll
+unloop

Note	Loops written with `do` often have better runtime performance than loops written without.

16.6. `break`

break ends the execution of the containing while, for, or switch statement. It behaves like break in most programming languages.

Syntax:

break

Example:

for U i = 0; i < 10; i += 1
    if array[i] == 0
        break // Exits the loop

If you want to exit out of multiple nested statements, use goto.

16.7. `continue`

continue is used inside while or for statements, and causes control flow to jump to the end of the loop’s code block. It behaves like condition in most programming languages.

Syntax:

continue

Example:

for U i = 0; i < 10; i += 1
    if array[i] == 0
        continue // If this executes, the line below it won't.
    array[i] += i

16.8. `switch`

The switch statement branches control flow based on an byte value. switch is similar to if, but instead of having a choice between two code blocks, switch allows multiple. It behaves like switch in most programming languages.

Syntax:

switch expression
    code block

expression must be of type U or S.

switch is intended to be used with case and default. Both of these label where control flow will jump.

Example:

switch player_state
    case 0
        do_run()
        break

    case 1
        do_jump()
        break

    case 2
        do_kick()
        break

    default:
        do_nothing()
        break

16.8.1. `switch` statement (byte block)

In byte blocks, the switch statement causes the mapper to bank switch to a specified bank.

Syntax:

switch regs

regs specifies which registers are holding the bank to switch to. The accepted values are a, x, y, and ax, where ax requires registers A and X to hold the same value.

Example:

ldy &my_bank1 // Load the bank in registers Y
switch y      // Switch to the bank in that register

lax &my_bank2 // Load the bank in registers A and X
switch ax     // Switch to the bank in those registers

16.9. `case`

case is used inside of switch statements as a label. Control flow will jump to the case from the switch if the switch’s expression matches the case value.

Syntax:

case constant expression
    code block

constant expression is an expression which can be computed at compile-time.

The code block of case exists only to provide a scope. There is no other difference between the syntax above, and this:

case constant expression
code block

As stated, case is a label. It can appear inside other statements such as for or if.

See more examples in switch.

16.10. `default`

default is used inside of switch statements as a label. Control flow will jump to the default from the switch if the switch’s expression matches no enclosed [hw_case] statement.

Syntax:

default
    code block

The code block of default exists only to provide a scope. There is no other difference between the syntax above, and this:

default
code block

As stated, default is a label. It can appear inside other statements such as for or if.

See more examples in switch.

16.11. `goto`

The keyword goto has use in two different types of statements: goto and goto mode.

16.11.1. `goto` statement

The goto statement causes control flow to jump to a corresponding label in the same function. It behaves like goto in most programming languages.

Syntax:

goto identifier

identifier refers to the name of a label in the current function.

Example:

fn example()
    U i = 0
    label loop
    i += 1
    if i < 10
        goto loop

goto can also jump to anonymous labels.

Syntax:

goto label+number
goto label-number

number refers relatively to an anonymous label. Positive refers to labels occuring later in the code, while negative labels occur prior.

Example:

fn example()
    U i
    label
    i = 5
    label
    i += 1
    if i < 10
        goto label-1 // Jump backwards to the previous label
    goto label-2 // Jump backwards two labels

Note that named labels do not affect the anonymous label numbering scheme.

16.11.2. `goto mode` statement

The goto mode statement causes control flow to jump to a mode, discarding the current call stack and starting anew. In the process, global variables will be reset to their initial value, unless they are explicitly preserved using preserves in the goto mode statement.

Syntax:

goto mode identifier(arguments)
: preserves /groups

identifier if the name of a mode function.
arguments is a comma-separated list of expressions to be passed to the mode function. The list may be blank.
groups are a list of vars groups, denoting which variables should not be reset. The list may be blank.

Note that preserves is a required modifier of this statement.

Example:

vars /my_vars
    U some_var = 10

mode foo()
    goto mode bar(some_var + 1)
    : preserves

mode bar(U some_argument)
    my_vars = some_argument

    goto mode foo()
    : preserves /my_vars

16.11.3. `goto` (assembly byte block)

In assembly functions, the goto statement causes control to switch execution to another function, clobbering all registers in the process. It behaves similar to the fn assembly statement, but does not return.

Syntax:

goto fn_identifier

fn_identifier is the name of a function.

If the function accepts arguments, those arguments must be set prior to the goto statement.

Example:

fn foo(U x)
    // ...

asm fn bar()
: employs
    default
        lda #5
        sta &foo.x      // Set the argument
        goto foo

16.11.4. `goto mode` (assembly byte block)

In assembly functions, the goto mode statement causes control to switch execution to a mode, clobbering all registers, discarding the current call stack, and starting anew. In the process, global variables will be reset to their initial value, unless they are explicitly preserved using preserves in the goto mode statement. It behaves similar to the fn assembly statement.

Syntax:

goto mode mode_identifier
: preserves /groups

mode_identifier if the name of a mode function.
groups are a list of vars groups, denoting which variables should not be reset. The list may be blank.

Note that preserves is a required modifier of this statement.

Example:

vars /my_vars
    U some_var = 10

mode foo()
    // ...

asm fn bar()
    goto mode foo
    : preserves /my_vars

16.12. `label`

The label statement introduces a point which a goto statement can jump to . It has no effect otherwise. It behaves like labels in most programming languages, albeit with a slightly different syntax.

Syntax:

label identifier
    code_block

identifier is an optional unique name of the label.
code_block is an optional indented code block.

Labels without identifires are called anonymous labels and can be referenced using a special goto syntax.

The code_block of label exists only to provide a scope. There is no other difference between the syntax above, and this:

label identifier
code_block

16.12.1. `label` statement (byte block)

Labels give names to specific addresses inside of byte blocks. They behave similarly to ct definitions, defining values of type AA and AAA.

Syntax:

label identifier
    byte_block

identifier is an optional unique name for the label.
byte_block is an optional indented byte block to be inserted into the containing byte block.

Labels without identifires are called anonymous labels and can be referenced using the label expression (byte block) syntax.

The byte_block of label exists only to provide a scope. There is no other difference between the syntax above, and this:

label identifier
byte_block

Example:

data /some_group
    [] some_data
        label foo
            jmp foo

In the current byte block implementation, when an anonymous label is placed inside an if statement (byte block) block, it is scoped to that if block. See the example code below for insight.

data /some_group
    [] some_data
        jmp label+ // Ignores the label inside the 'if' block:
        if true
            jmp label+ // Jumps to the next label inside the 'if' block.
            label
            jmp label+ // Jumps to the next label outside the 'if' block.
        label

16.13. `return`

16.13.1. `return` statement

The return statement ends the execution of the current function, using its argument as the function’s return value. It behaves like return in most programming languages.

Syntax:

return expression

Syntax for functions lacking a return value:

return

16.13.2. `label` expression (byte block)

In byte block contexts, label can be used as an expression.

Syntax:

label+number
label-number

number refers relatively to an anonymous label. Positive refers to labels occuring later in the code, while negative labels occur prior.

Example:

asm fn example()
: employs
    default
        label
        jmp label-1 // Jump to the previous anonymous label.

Note that named labels do not affect the anonymous label numbering scheme.

16.13.3. `return` expression

A return expression does not cause functions to return. Instead, it provides a handle to the current function’s return value. Although the value itself cannot be used, the address of can be taken using unary operator &,

This functionality exists because of inline assembly. Most often, it is used to allow inline assembly functions to return values by storing into the address.

Example:

AA return_addr = &return

16.14. `swap`

The swap statement exchanges its arguments, assigning the first to the second and the second to the first.

Syntax:

swap a, b

a and b are lvalue expressions.

Example:

fn foo()
    U x = 10
    U y = 20
    swap x, y
    // Now x = 20 and y = 10.

16.15. `push`

The push expression inserts values onto a VEC value. The expression returns a copy of its second argument.

Syntax:

push(vec, elem, index)

vec is an lvalue expression with a VEC type.
elem is a value to be inserted into vec.
index is an optional value of type Int.

When index is not included, elem is appended onto the end of vec. Otherwise, elem is inserted before the value at index.

Example:

ct fn foo()
    U{} vec = U{}()
    push(vec, 10)
    push(vec, 20)
    push(vec, 30, 0)
    // Now vec = U{}(30, 10, 20)

16.15.1. `push` statement (byte block)

In byte blocks, the push statement pushes the current bank onto the stack.

Syntax:

push

Example:

push          // Save the current bank

ldy &my_bank1 // Load the bank in registers Y
switch y      // Switch to the bank in that register

pop           // Restore the previous bank

16.16. `pop`

The pop expression removes a value from a VEC value, returning the removed valued.

Syntax:

pop(vec, index)

vec is an lvalue expression with a VEC type.
index is an optional value of type Int.

When index is not included, elem is removed from the end of vec. Otherwise, elem is removed at position index.

Example:

ct fn foo()
    U{} vec = U{}(30, 10, 20)
    U x = pop(vec, 0)
    U y = pop(vec)
    U z = pop(vec)
    // Now x = 30, y = 20, z = 10

16.16.1. `pop` statement (byte block)

In byte blocks, the pop statement pops a bank from the stack and switches to it.

Syntax:

pop

Example:

push          // Save the current bank

ldy &my_bank1 // Load the bank in registers Y
switch y      // Switch to the bank in that register

pop           // Restore the previous bank

16.17. `fence`

The fence statement is used for both writing concurrent code, and for interacting with hardware. It imposes constraints on how global variables are loaded and stored, preventing the compiler from reordering them.

More precisely:

Every global variable the function is tracking will be stored before the fence executes.
Every global variable the function is tracking will be loaded after the fence executes.

A function tracks a global variable if it reads or writes that variable, or if it calls another function that does. When dereferencing a pointer, the pointer’s groups define the set of globals to track.

Note	`fence` does not instruct the compiler which globals to track. To do that, the modifier `employs` is required.

Why is fence a thing in concurrent code?

The NESFab compiler performs optimizations which moves loads and stores around. This is normally fine, but issues arise due to interrupts.

To illustrate, take a look at the code below:

foo = 10
bar = 20

The compile is free to reorder these global variable assignments, storing into bar before foo. However, imagine if an interrupt were to occur between these stores. The interrupt would see that bar equals 20, but not foo equals 10, as the store to foo hasn’t happened yet.

To prevent this reordering, a fence statement can be used:

foo = 10
fence
bar = 20

Now if the interurpt sees that bar equals 20, foo must equal 10.

Why is fence a thing in sequential code?

Optimizations which reorder code can affect sequential code, too. For example, consider the following code which turns the grayscale bit of PPUMASK on until game_update completes. Visually, this will depict how long it takes for game_update to run by displaying a grayscale stripe on the screen.

while true
    {PPUMASK}(PPUMASK_GRAYSCALE_ON | PPUMASK_ON)
    game_update()
    {PPUMASK}(PPUMASK_ON)
    nmi

Unfortunately, this code may not work as intended. The compiler is allowed to reorder the game_update call and move it before the first PPUMASK write, or after the second PPUMASK write. This is because the compiler sees no connection between the two; there is no dependency from one to another, as they do not involve the same global variables.

To fix the problem, two fence statements are used:

while true
    {PPUMASK}(PPUMASK_GRAYSCALE_ON | PPUMASK_ON)
    fence
    game_update()
    fence
    {PPUMASK}(PPUMASK_ON)
    nmi

These force the game_update call to remain between the PPUMASK writes.

Another purpose for fence:

fence is also used when interacting with the hardware directly. When reading or writing a global variable via its hardware address, two fence statements are recommended with the hardware access between them. These fence statements instruct the compiler to store the global before the hardware access, and load the value after it.

A common example arises when doing OAM DMA:

fence
{OAMDMA}((&oam).b)
fence

Without the first fence instruction, the compiler would not recognize that global variables are being read. and so the resulting read may have incorrect results. The second fence, although largely uncessary, ensures that future reads to oam occur after OAMDMA completes.

Note that this only applies when an address is written, and that write has an effect which dereferences the address. It is not necessary to use fence when a value is passed normally:

// fence isn't needed here:
{PPUDATA}(some_var)

Likewise, it is not necessary to use fence when the address is not dereferenced:

// fence isn't needed here:
{PPUDATA}(&some_var.a)

More on dependencies and side effects:

One way to think about fence is that the program is outputting a list of hardware reads and writes (i.e. those involving the PPU), and the compiler makes sure the order and the data written matches the original code.

16.18. `true`

true is an expression of type Bool, and has a compile-time constant value. When converted to an integer type, it will have the value 1.

Syntax:

true

16.19. `false`

false is an expression of type Bool, and has a compile-time constant value. When converted to an integer type, it will have the value 0.

Syntax:

false

16.20. `read`

read is an expression used to access the value a pointer is pointing at, advancing the pointer in the process.

Syntax:

read Type(ptr)

Type is a type name. The expression will read a value of this type from the pointer, returning it.
ptr is an lvalue expression with a pointer type. The expression will increment the pointer by sizeof Type bytes.

Example:

omni data
    [] my_data
        UU($1234)
        UU($5678)

mode main()
    CC ptr = @my_data
    UU first  = read UU(ptr)
    UU second = read UU(ptr)

16.21. `write`

write is an expression used to store a value at an address pointed-to by a pointer, advancing the pointer in the process. The expression returns no value.

Syntax:

write Type(ptr, expr)

Type is a type name. The expression will write a value of this type to the pointer.
ptr is an lvalue expression with a pointer type. The expression will increment the pointer by sizeof Type bytes.
expr is an expression of type Type. The value will be written at ptr.

Example:

vars
    [] my_data
        UU($1234)
        UU($5678)

mode main()
    MM ptr = @my_data
    write UU(ptr, $1234)
    write UU(ptr, $5678)

16.22. `ready`

ready is an expression of type Bool which returns true if both an NMI is active and the program was waiting on one, or false otherwise. It is intended to be used as a synchronization primitive (mutex) to avoid race conditions inside of NMI handlers.

Syntax:

ready

In general, if ready is true, all global variables are in a stable, concurrent-safe state. Likewise, if ready is false, either no NMI is happening, or the program is lagging one or more frames.

Example:

nmi foo()
    if ready
        upload_data()
        poll_controller()
    play_music()

The address of ready can be taken using unary operator &, but the pointed-to value must never be modified by the program.

Note	There is more than one way to achieve concurrent safety. See `fence`, for example.

16.23. `nmi_counter`

nmi_counter is an expression of type U whose value is incremented after each NMI. It can be used for timing purposes, to create simple animations, or to detect when NMI has occured.

Syntax:

nmi_counter

The address of nmi_counter can be taken using unary operator &, but the pointed-to value must never be modified by the program.

16.24. `state`

Some mappers have registers which combine bank switching with other functionality. For example, ANROM uses a bit to track the cartridge’s mirroring, and lets the programmer switch it on the fly. state expressions read or write these mapper registers while correctly handling the bank.

See the mappers page what state means for each mapper.

Note	The NESFab runtime duplicates the mapper’s register state to a fixed location in RAM. Reading the state will return this copy instead of polling the hardware.

16.24.1. `state` read

state is an expression of type U which returns the mapper’s last-set register state.

Syntax:

state()

Example:

U foo = state()

The address of state can be taken using unary operator &. This address refers to the copy in RAM; modifying it does not notify the hardware.

16.24.2. `state` write

state is an expression of type Void which sets the mapper’s register state.

Syntax:

state(expr)

expr is an expression of type U. The state will be assigned this value.

Example:

state(5) // The state will have a value of 5

Note	You should not alter the bits reserved for the mapper’s bank. Leave these bits set to `0`, or otherwise the program may crash.

16.25. `system`

system is an expression of type U which returns the current NES system.

Syntax:

system

The possible return values are listed below:

Enumeration	Value
`SYSTEM_NTSC`	0
`SYSTEM_PAL`	1
`SYSTEM_DENDY`	2
`SYSTEM_UNKNOWN`	3

Example:

fn foo()
    if system == SYSTEM_NTSC
        speed = 1.0
    else
        speed = 1.2

When the system option is set to detect, the value will be determined at program startup. Additionally, the address of system can be taken using unary operator &, but the pointed-to value must never be modified by the program.

When the system option is not set to detect, the expression is a compile-time constant and its address cannot be taken.

16.25.1. `SYSTEM_NTSC`

SYSTEM_NTSC is an expression of type Int, and has a compile-time constant value of 0.

Syntax:

SYSTEM_NTSC

16.25.2. `SYSTEM_PAL`

SYSTEM_PAL is an expression of type Int, and has a compile-time constant value of 1.

Syntax:

SYSTEM_PAL

16.25.3. `SYSTEM_DENDY`

SYSTEM_DENDY is an expression of type Int, and has a compile-time constant value of 2.

Syntax:

SYSTEM_DENDY

16.25.4. `SYSTEM_UNKNOWN`

SYSTEM_UNKNOWN is an expression of type Int, and has a compile-time constant value of 3.

Syntax:

SYSTEM_UNKNOWN

16.26. PPU Registers

The following PPU registers have keywords. All of these are expressions of type AA with compile-time constant values.

Enumeration	Value
`PPUCTRL`	$2000
`PPUMASK`	$2001
`PPUSTATUS`	$2002
`OAMADDR`	$2003
`OAMDATA`	$2004
`PPUSCROLL`	$2005
`PPUADDR`	$2006
`PPUDATA`	$2007
`OAMDMA`	$4014

16.26.1. `PPUCTRL`

PPUCTRL is an expression of type AA, and has a compile-time constant value of $2000.

Syntax:

PPUCTRL

16.26.2. `PPUMASK`

PPUMASK is an expression of type AA, and has a compile-time constant value of $2001.

Syntax:

PPUMASK

16.26.3. `PPUSTATUS`

PPUSTATUS is an expression of type AA, and has a compile-time constant value of $2002.

Syntax:

PPUSTATUS

16.26.4. `OAMADDR`

OAMADDR is an expression of type AA, and has a compile-time constant value of $2003.

Syntax:

OAMADDR

16.26.5. `OAMDATA`

OAMDATA is an expression of type AA, and has a compile-time constant value of $2004.

Syntax:

OAMDATA

16.26.6. `PPUSCROLL`

PPUSCROLL is an expression of type AA, and has a compile-time constant value of $2005.

Syntax:

PPUSCROLL

16.26.7. `PPUADDR`

PPUADDR is an expression of type AA, and has a compile-time constant value of $2006.

Syntax:

PPUADDR

16.26.8. `PPUDATA`

PPUDATA is an expression of type AA, and has a compile-time constant value of $2007.

Syntax:

PPUDATA

16.26.9. `OAMDMA`

OAMDMA is an expression of type AA, and has a compile-time constant value of $4014.

Syntax:

OAMDMA

Less Than or Equal To <=

16.27. `fn`

The fn keyword declares a function at global scope.

Syntax:

fn identifier(parameters) ReturnType
    code block

identifier is the name of the function.
parameters is a comma-separated list of variables with the syntax Type name.
ReturnType is a type name, but is optional. Leaving ReturnType blank is the same as specifying it as Void.
code block is the block of code which implements the function.

Functions can only be declared at global-scope. Unlike other programming languages, functions in NESFab cannot be nested or recursive.

Modifiers:

employs.
data.
vars.
+zero_page, -zero_page
+inline, -inline
+graphviz
+info
+static
+static_fixed
+sloppy, -sloppy

Example:

fn foo(U p1, U p2) U
    return p1 + p2

16.27.1. `fn` statement (assembly byte block)

In assembly functions, the fn statement calls a NESFab function, clobbering all registers in the process.

Note	Unlike the `JSR` instruction, the `fn` statement correctly handles the NESFab calling convention and runtime.

Syntax:

fn fn_identifier

fn_identifier is the name of a function.

If the function accepts arguments, those arguments must be set prior to the fn statement. If the function returns a value, it can be retrieved via return.

Example:

fn foo(U x) U
    return x + x

asm fn bar()
: employs
    default
        lda #5
        sta &foo.x       // Set the argument
        fn foo           // Call the function
        lda #&foo.return // Read the return value
        sta PPUDATA
        rts

16.28. `ct`

ct is short for compile-time. The keyword can be prefixed onto value and function declarations to insist that their computations occur at compile-time.

16.28.1. `ct fn`

Syntax:

ct fn identifier(parameters) ReturnType

ct fn has the same syntax as fn.

16.28.2. `ct` value

Syntax:

ct TypeName identifier = value

ct values are declared with the syntax of regular variables, but must be defined a value.

They can be declared at global scope, or inside functions.

16.29. `mode`

The mode keyword declares a mode function at global scope. Modes are similar to regular functions, but they do not return. Instead, the only way to leave a mode function is via a goto mode statement.

Syntax:

mode identifier(parameters)
    code block

identifier is the name of the mode function.
parameters is a comma-separated list of variables with the syntax Type name.
code block is the block of code which implements the mode function.

Every program is required to have a mode named main defined, which takes no parameters. When the program starts, execution will begin at main. This behavior is similar to main functions found in other programming languages.

Modes can be assigned a corresponding nmi function, using a modifier. While the mode function is executing, NMIs will be handled using the supplied nmi function.

Modifiers:

nmi.
irq.
employs.
data.
vars.
+zero_page, -zero_page
+graphviz
+info
+static
+static_fixed
+sloppy, -sloppy

Example:

mode main()
: nmi my_nmi
    while true
        x = x + 1

Why do modes exist?

There are two reasons.

First, it is convenient to be able to change what the program is doing deep inside a function call. For example, in a video game it can be useful to define one mode for the main menu, and another one for the actual gameplay. To switch between the two, a goto mode statement can be used anywhere in the program, which is nicer than having to use variables and switch-cases.

But more importantly, modes allow the compiler to smartly allocate memory, enabling variables used in different modes to share RAM addresses. This happens transparently from the programmer; no sum types needed.

16.30. `nmi`

The keyword nmi can be used as a statement, a declaration, or as a modifier.

16.30.1. `nmi` statement

The nmi statement blocks execution until an nmi function occurs. Until the nmi statement returns, ready will evaluate to true.

Syntax:

nmi

16.30.2. `nmi` statement (byte block)

In byte blocks, the nmi statement blocks execution until an nmi function occurs, clobbering all registers in the process. Until the nmi statement returns, ready will evaluate to true.

Syntax:

nmi

16.30.3. `nmi` function

The nmi keyword declares an NMI interrupt function at global scope. NMI interrupts are similar to regular functions, but they have no parameters, cannot return values, and cannot be called. Instead, they execute once per frame at the start of VBLANK, so long as bit 7 of PPUCTRL is set.

Syntax:

nmi identifier()
    code block

identifier is the name of the mode function.
code block is the block of code which implements the mode function.

Modifiers:

employs.
data.
vars.
+zero_page, -zero_page
+graphviz
+info
+static
+static_fixed
+sloppy, -sloppy

Why do NMI interrupt functions exist?

NMI interrupts provide a way for code to detect the vertical blanking interval (VBLANK). This is important, as most modifications to the PPU’s state require that rendering be turned off, and VBLANK is one such time.

Since the NMI interrupt occurs once per frame, it’s also convenient to use it as a timer. Typically, game updates are run in sync with the NMI, as otherwise the game would speed up or slow down based on how much computation is happening.

16.31. `irq`

The keyword irq can be used as a statement, a declaration, or as a modifier.

16.31.1. `irq` statement

The irq statement is used to enable or disable IRQ interrupt handling. When disabled, no IRQ functions will be called.

Syntax:

irq expr

expr is an expression of type Bool.

Example:

irq true // Enable IRQs

Note	The `irq` statement corresponds to assembly instructions `SEI` and `CLI`.

16.31.2. `irq` function

The irq keyword declares an irq interrupt function at global scope. IRQ interrupts are similar to regular functions, but they have no parameters, cannot return values, and cannot be called. Instead, they are triggered by hardware such as the APU frame counter, or MMC3 scanline counter.

Syntax:

irq identifier()
    code block

identifier is the name of the mode function.
code block is the block of code which implements the mode function.

Modifiers:

employs.
data.
vars.
+zero_page, -zero_page
+graphviz
+info
+static
+static_fixed
+sloppy, -sloppy
+solo_interrupt

Note	`asm` can be applied to `irq`, so long as `+solo_interrupt` and `+static` are used.

16.32. `asm`

The asm keyword declares an function at global scope using byte block inline assembly syntax.

Syntax:

asm fn identifier(parameters) ReturnType
: employs /groups
    vars
        local vars
    byte block

identifier is the name of the function.
parameters is a comma-separated list of variables with the syntax Type name.
ReturnType is a type name, but is optional. Leaving ReturnType blank is the same as specifying it as Void.
/groups is an optional list of groups that the function uses. See employs.
local vars is a line-separated list of variables with the syntax Type name.
byte block is the byte block of code which implements the function.

A special default label is required in each asm function, and specifies the entry point to the function.

Example:

asm fn waste_time()
: employs
    vars
        U counter
    default
        lda #0
    label loop
        sta &counter
        inc &countner
        bne loop
        rts

Modifiers:

employs.
data.
vars.
+zero_page, -zero_page
+info

The labels of an asm function are visible using the . operator. Although the address cannot be taken of these labels, it is possible to call them like functions.

Example:

waste_time.loop()

Note	`asm` can be applied to `irq`, so long as `+solo_interrupt` and `+static are used. `asm` is not currently supported with `nmi`.

16.33. `struct`

The struct keyword is used to define new types (records) at global scope. It behaves similarly to the struct keyword in other languages.

Syntax:

struct NewTypeName
    fields

NewTypeName is the name of the struct.
fields is a newline-separated list of fields, with the syntax TypeName field_name.

Example:

struct Circle
    S center_x
    S center_y
    UF radius

struct types may contain arrays and other struct types, so long as multi-dimensional arrays are not created.

Like all values in NESFab, struct types are passed by value.

Field Modifiers:

+inherit

16.34. `vars`

The vars keyword declares a block of global variables, and potentially their group.

Syntax:

vars /group_name
    variables

/group_name is the optional name of the group that the variables will be part of.
variables are global variables definitions with the syntax TypeName identifier or TypeName identifier = value.

Assigning to a global variable in a vars block sets its initial value. The variable will reset to this value at the start of the program, but also whenever a goto mode statement occurs and the variable’s group is not preserved

The same vars group can be declared multiple times, with each declaration defining additional global variables. The group will be defined as the union of these declarations.

Variable modifiers:

+align
+zero_page, -zero_page
+sram, -sram
+unused

Example:

vars /my_group
    U score = 0 // Set an initial value for 'score'
    UU player_x
    UU player_y

vars /my_group
    U speed

16.35. `data`

The data keyword declares a group and the pointer-addressable global constants inside of it.

Syntax:

data /group_name
    constants

group_name is the mandatory name of the group that the constants will be part of.
constants are global constant definitions with the syntax [optional_size] identifier, followed by a byte block.

The same data group can be declared multiple times, with each declaration defining additional global variables. The group will be defined as the union of these declarations.

Constant modifiers:

+align
+dpcm
+sector
+static
+static_fixed
+unused

Example:

data /my_group
    [4] player_speeds
        U(1)
        U(4)
        U(8)
        U(20)

    [4] player_attacks
        U(10)
        U(20)
        U(30)
        U(40)

16.36. `omni`

The omni keyword can be prefixed to data to alter its behavior. Groups declared using omni will have their data duplicated across every bank of the ROM. Pointers to data inside this group will not include a bank field (e.g. type CC instead of CCC).

Syntax:

omni data /group_name
    constants

group_name is the optional name of the group that the constants will be part of.
constants are global constant definitions with the syntax [optional_size] identifier, followed by a byte block.

Why use omni?

Data inside an omni block can be accessed slightly quicker, at the expense of ROM size. Additionally, pointers to omni data take up only two bytes, as opposed to three.

When using a mapper without PRG banks (such as NROM), it is strictly better to use omni data instead of data.

16.37. `charmap`

The charmap keyword defines character maps, which are sets of characters with a mapping from each character to byte values. It is used to specify text encoding, like ASCII, EBCDIC, or MIK.

Syntax:

charmap identifier("string", 's', offset)

identifier is the name of the charmap. This is optional. When left out, the default charmap is defined.
"string" is a string literal, defining the characters of the charmap. The first character in the string will map to a value of offset (or zero if offset is not defined), with other characters mapping to one higher than the character preceding them.
's' is an optional character literal, defining the sentinel. When left out, no sentinel is defined.
offset is an optional integer literal, defining the value of the first charmap element.

Modifiers:

stows

Example:

charmap foo(" ,.!?ABCDEFGHIJKLMNOPQRSTUVWXYZ\0", '\0')

// Defines the mapping:
// ' ' = 0
// ',' = 1
// '.' = 2
// '!' = 3
// '?' = 4
// 'A' = 5
// 'B' = 6
// 'C' = 7
// ... and so on
// with the sentinel being: '\0'

Example:

charmap bar("abcd", 10)
: stows /strings

// Defines the default charmap mapping:
// 'a' = 10
// 'b' = 11
// 'c' = 12
// 'd' = 13
// with no sentinel,
// and stowing its literals in group /strings.

Shared Characters

The escape sequence \/ has a special meaning inside of charmap definitions. A character preceding \/ will map to the same value as the character following it.

Commonly, \/ is used when multiple characters can use the same glyph, such as 0 and O, or 1 and I.

charmap foo("_0\/O1\/I\/|X", '\0')

// Defines the mapping:
// '_' = 0
// '0' = 1
// 'O' = 1
// '1' = 2
// '|' = 2
// 'I' = 2
// 'X' = 3

Sizes and Members

The number of unique values in a charmap can be accessed using the size member, which is a compile-time constant value of type Int.

charmap foo("abc")

// The member 'size' is defined as:
// foo.size = 3

// Example use:
ct U last_foo_char = foo.size - 1

To access the members of the default charmap, the expression charmap is used:

// Define the default charmap:
charmap("xyz")

// Access the default charmap using 'charmap':
ct U last_default_char = charmap.size - 1

Sentinels

For charmaps that define a sentinel character, two things occur:

String literals using the charmap have the sentinel character appended onto the end.
The member sentinel of type U is defined for charmap.

The intention behind sentinel characters is to mark the end of strings. This can be used to mimic the behavior of the C programming language’s null-terminated strings.

charmap foo("abc", 'b')

// String literals have 'b' tacked on:
// "string"foo[6] = 'b'
// len("string"foo) = 7

// The member 'sentinel' is defined for 'foo':
// foo.sentinel = 1

charmap c_string("\0abc", '\0')

// This literal is terminated by the value 0:
// "hello world"c_string

// The member 'sentinel' is defined for 'c_string':
// c_string.sentinel = 0

Note that sentinels must have a mapping defined in the charmap. Doing so otherwise is an error.

charmap bad_charmap("abc", 'z') // Error! 'z' is not in the charmap!

stows Group

charmap accepts a single group in its stows modifiers. If defined, string literals using the charmap become valid operands to operator @ and operator &. When using these operators, the contents of the string literal will exist in the group as data.

Example:

charmap foo("ABCD")
: stows /strings

// Can now reference strings using literals:
ct CCC/strings some_ptr = @"AAA"

// This is akin to defining the string inside a 'data' block first:
data /strings
    [] some_string
        ("AAA")
// ... and then referencing it:
ct CCC/strings another_ptr = @some_string

16.38. `chrrom`

The chrrom keyword is only used for mappers which use CHR ROM (as opposed to CHR RAM). It specifies the data of the CHR ROM using a byte block syntax.

Syntax:

chrrom name(offset)
    byte block

name is an optional name which allows the `chrrom’s labels to be accessed in code.
offset is an optional offset which determines which address the data gets stored. If left out, offset is treated as 0.

Example:

// Store at offset $0000:
chrrom
    file(fmt, "sprites.png")
    file(fmt, "bg.png")

// Store at offset $2000:
chrrom ($2000)
    file(fmt, "more_sprites.png")
    file(fmt, "more_bg.png")

// Store at offset $4000 under the name 'foo':
chrrom foo($4000)
    file(fmt, "more_sprites.png")
    file(fmt, "more_bg.png")

The compiler will issue a warning if the supplied data does not match what the mapper expects.

chrrom blocks can have labels. If the chrrom is named, these labels can be accessed, returning their position in CHR memory. These labels have a value of type Int.

Example:

chrrom foo
    label spr
        file(fmt, "sprites.png")
    label bg
        file(fmt, "bg.png")

// Access the CHR addresses:
ct Int bar = foo.spr
ct Int qux = foo.bg

16.39. `file`

The file keyword imports and converts data from an external file. It can be used as a statement in byte blocks, or as an expression.

Syntax:

file(target, "filename", args...)

target specifies the output conversion target to use.
"filename" is a string literal path to the file.
args… is a list of arguments that the conversion script will use. (Most conversion scripts do not use arguments.)

Modifiers:

+spr_8x16
+palette_3
+palette_25

16.39.1. `file` expression

file expressions produce compile-time constant values of type U{}. To use modifiers with them, write the modifiers on the same line.

Example:

ct U{} my_data = file(fmt, "sprites.png") : +spr_8x16

16.39.2. `file` statement (byte block)

file statements insert data into a byte block. Unlike file expressions, these statements can can introduce accessory definitions.

Example:

chrrom
    file(fmt, "sprites.png")
    : +spr_8x16

    file(fmt, "bg.png")

16.39.3. Conversions

Input File Conversions

When loading a file, its data is first interpreted based on its filename extension. The following filenames are accepted:

File Format Description

Raw binary data

Raw binary data

Raw binary data

Nametable data

Textual data

Output Target Conversions

Once a file has been loaded, it is then converted based on its target. The following targets are accepted:

Conversion Target Description

raw

Raw binary data

fmt

Formatted data

pbz

Compressed graphical data

donut

Compressed graphical data

rlz

Compressed data

16.39.4. Accessory Definitions

In addition to defining a byte sequence, file statements (but not expressions) may define compile-time constants in the byte block’s namespace. These constants will have names prefixed by the previous label and the character _, if such a label exists.

Example:

[] compressed_data
    file(pbz, "sprites.png")
    label bg
    file(pbz, "bg.png")

In the example above, the pbz target is used. This target has two accessory definitions: chunks and tiles. Thus, compressed_data would gain the following members:

compressed_data.chunks
compressed_data.tiles
compressed_data.bg_chunks
compressed_data.bg_tiles

Note that the first two refer to the first file, while the second two refer to the second file. The second two are prefixed with bg_, as the previous label is bg.

16.39.5. Binary file formats

The filetypes .bin, .chr, and .nam are loaded as raw binary data, with no conversions happening.

16.39.6. `.txt` format

The filetype .txt is interpreted as ASCII data, with newline sequences replaced with a single newline character.

The following newline sequences are replaced with \n:

\r
\r\n
\n\r

Where \r has an ASCII value of $0D, and \n has an ASCII value of $0A.

16.39.7. `.map` format

The filetype .map, originating from the NEXXT tool, describes tile maps. When imported into NESFab, the data is interpretted as a series of nametables, one after another. Note that this interpretation requires that the tile map have dimensions evenly divisible by 32x30.

16.39.8. `.png` format

The filetype .png is interpreted as a PNG image representing CHR tileset data. The input image must have dimensions that are multiples of 8 x 8 pixels.

If the PNG image is encoded using a palette, the resulting CHR will use the palette indexes as each pixel’s color, modulo 4. Otherwise, the PNG will be converted to a grayscale image with pixel values in the range [0, 3]; black represents color 0 and white represents color 3.

16.39.9. `raw` target

The raw target imports raw binary data, without performing any filetype conversions. It accepts no arguments.

Example:

[] sin_table
    file(raw, "sin_table.bin")

Accessory Definitions

There are no accessory definitions for raw.

16.39.10. `fmt` target

The fmt target imports data after first processing it using filetype conversions. It accepts no arguments.

Example:

chrrom
    file(fmt, "tiles.png")

Accessory Definitions

There are no accessory definitions for fmt.

16.39.11. `pbz` target

The pbz target compresses the data into the PBZ encoding after first processing it using filetype conversions. It accepts no arguments.

Example:

[] compressed_data
    file(pbz, "sprites.png")

Accessory Definitions

chunks: An Int equal to the decompressed size divided by 8.
tiles: An Int equal to the decompressed size divided by 16. If the size is not a multiple of 16, the value is left undefined.

Decompressing

The standard library file pbz.fab can be used to decompress PBZ-encoded data.

Encoding Description

PBZ is a simple run-length encoding that is good for representing graphical data. As it decompresses into chunks of 8 bytes, it won’t work with arbitrarily-sized data.

The data is formatted as a sequence of compressed 8-byte chunks. The first byte of a chunk encodes it run-length encoding in a unary-encoded format. For each bit of this byte, starting from the highest bit:

0 bit: Read a byte from the sequence and output it.
1 bit: Output the previous byte outputted for this chunk, or $00 if none was.

For example, given the sequence:

$AF $11 $22

The unary-encoded byte is $AF, which has the binary representation %10101111. Starting from the highest bit and working to the lowest bit, the decompressed sequence is:

$00 $11 $11 $22 $22 $22 $22 $22

16.39.12. `donut` target

The donut target compresses the data into the Donut encoding after first processing it using filetype conversions. It accepts no arguments.

Example:

[] compressed_data
    file(donut, "sprites.png")

Accessory Definitions

chunks: An Int equal to the decompressed size divided by 64.

Decompressing

The standard library file donut.fab can be used to decompress Donut-encoded data.

16.39.13. `rlz` target

The rlz target compresses the data into the RLZ encoding after first processing it using filetype conversions.

Arguments

1st (optional): Include terminator. If true, the byte sequence will have a $00 byte appended onto the end. If false, no $00 will be appended. By default, the value is true.

Example:

[] compressed_data
    file(rlz, "sprites.png", false)
    file(rlz, "sprites2.png")

Accessory Definitions

There are no accessory definitions for rlz.

Decompressing

The standard library file rlz.fab can be used to decompress RLZ-encoded data.

Encoding Description

RLZ is a simple run-length encoding that’s good for data with long sequences of repeating bytes.

The data is formatted as a sequence of runs, where the first byte, N, of a run determines the effect.

$00 byte: Terminate the data sequence.
$01 to $7F byte: Copy the next byte, (N + 2) times.
$80 to $FF byte: Copy the next (N - 127) bytes verbatim.

For example, given the sequence:

$03 $11 $81 $22 $33 $02 $44 $00

The decompressed sequence is:

$01 $01 $01 $01 $01 $22 $33 $44 $44 $44 $44

16.40. `macro`

The macro keyword generates and compiles a new source file by substituting its arguments into an existing .macrofab file. It is only usable at top-level scope.

Syntax:

macro("macro_name", "args"...)

"macro_name" is the string literal name of the macro file being invoked, without the .macrofile extension or path. If the string is empty, no macro is invoked.
"args" are a comma-separated list of string literals to be substituted into the .macrofab file.

Macro Files:

Macro (.macrofab) files resemble regular .fab files, but have additional syntax:

#:identifier:# declares a macro parameter. The order of these declarations determines the argument order for the macro keyword.
#identifier# expands a macro argument.
#'identifier'# expands a macro argument, putting it inside ' quotes and escaping its characters.
#"identifier"# expands a macro argument, putting it inside " quotes and escaping its characters.
#`test`# expands a macro argument, putting it inside ` quotes and escaping its characters.
#-identifier-# expands a macro argument, converting underscores to camel-case.
#=identifier=# expands a macro argument, converting underscores to snake-case.

Note that macro arguments are not parsed inside comments or string literals.

Example:

// Declare the parameters first:
#:my_arg:#
#:another_arg:#

// Now expand them:
vars
    U #my_arg# = #another_arg#

If this is saved as foo.macrofab, the macro can be invoked in a .fab file like so:

macro("foo", "something", "100")

Which would generate the following source file and compile it:

// Declare the parameters first:



// Now expand them:
vars
    U something = 100

Note	The generated file is not saved to disk. It is compiled, and then forgotten.

Modifiers:

+fork_scope

16.41. `mapfab`

The mapfab keyword parses a .mapfab file and invokes a series of macros based on the data. It is only usable at top-level scope.

Note	MapFab is a level editor designed to be used with NESFab.

Syntax:

mapfab(target, "mapfab_file", "chr_macro", "palette_macro", "metatiles_macro", "level_macro")

target specifies the output target to use for the level tiles.
"mapfab_file" is the string literal path to the .mapfab or .json file.
"chr_macro" is the name of the macro to invoke for each CHR definition.
"palette_macro" is the name of the macro to invoke for each palette definition.
"metatiles_macro" is the name of the macro to invoke for each metatile set definition.
"level_macro" is the name of the macro to invoke for each level definition.

If any of the macro names are the empty string (""), those macros are not invoked.

CHR Macro:

The following macro arguments are supplied for each CHR definition:

#:name:#   // The name of the CHR definition
#:path:#   // The path to the CHR definition

Additionally, the following private definitions are defined:

ct Int _index   // The unique index of the CHR definition.

Note	It can make sense to ignore `path`, and instead use `name` to derive the desired path.

Palette Macro:

The following macro arguments are supplied for each palette definition:

#:name:# // The name of the palette definition, which is an integer from 0 to 255.

Additionally, the following private definitions are defined:

ct Int _index       // The unique index of the palette definition.
ct U[25] _palette   // The palette's data.

Metatiles Macro:

The following macro arguments are supplied for each metatile set definition:

#:name:#         // The name of the metatile definition.
#:chr_name:#     // The name of the CHR definition the metatile set uses for display.
#:palette_name:# // The name of the palette definition the metatile set uses for display.

Note	Typically, `chr_name` and `palette_name` should be ignored for metatile sets, as level macros have this information too.

Additionally, the following private definitions are defined:

ct Int _index       // The unique index of the metatile set definition.
ct Int _num         // The number of metatiles in the set.
ct U[_num] _nw      // The north-west tiles of each metatile.
ct U[_num] _ne      // The north-east tiles of each metatile.
ct U[_num] _sw      // The south-west tiles of each metatile.
ct U[_num] _se      // The south-east tiles of each metatile.
ct U[_num] _attributes // The 2-bit attribute data of each metatile.
ct U[_num] _collisions // The 6-bit collision data of each metatile.
ct U[_num] _combined     // The two arrays above combined: attribute | (collision << 2)
ct U[_num] _combined_alt // The two arrays above combined: (attribute << 6) | collision

If the target is mmt_32, the following definitions are also defined:

ct Int _mmt_num            // The number of metametatiles in the set.
ct U[_num] _mmt_nw         // The north-west metatiles of each metametatile.
ct U[_num] _mmt_ne         // The north-east metatiles of each metametatile.
ct U[_num] _mmt_sw         // The south-west metatiles of each metametatile.
ct U[_num] _mmt_se         // The south-east metatiles of each metametatile.
ct U[_num] _mmt_attributes // The combined 8-bit attribute data of each metametatile.

Levels Macro:

The following macro arguments are supplied for each level set definition:

#:name:#           // The name of the level definition.
#:chr_name:#       // The name of the CHR definition the metatile set uses for display.
#:palette_name:#   // The name of the palette definition the metatile set uses for display.
#:metatiles_name:# // The name of the metatile set definition the metatile set uses for display.
#:macro_name:#     // Contents of MapFab's macro field.

Additionally, the following private definitions are defined:

ct Int _index       // The unique index of the level definition.
ct Int _width       // The width of the level, in tiles.
ct Int _height      // The height of the level, in tiles.
ct U[_width * _height] _row_major    // The level's contents in a row-major order.
ct U[_width * _height] _column_major // The level's contents in a column-major order.

For each object class (CLASS), the following VECs are defined:

ct Int{} _CLASS_x
ct Int{} _CLASS_y

For each field (FIELD) in CLASS, additional VECs are defined, with the string of each field wrapped inside a cast.

ct TYPE{} _CLASS_FIELD

For example, if the class foo had three objects in this level, and each object had a field U bar, the following definitions would exist:

ct Int{} _foo_x = Int{}(203, -3, 3099)
ct Int{} _foo_y = Int{}(13, 991, -30)
ct U{} _foo_bar = U{}(U(0), U(5), U(2))

Note	Objects are ordered based on their names.

For each named object, addition Ints are defined. Each Int holds the object’s index in its object array:

ct Int _CLASS_name_NAME = ID

For example, if an object was named foo and belonged to object class bar with index 2, the following Int would be defined:

ct Int _bar_name_foo = 2

Output Target Conversions

The data of each level (_row_major and _column_major) are converted based on specified target:

Conversion Target Description

raw

No conversion

pbz

Compress using PBZ compression

rlz

Compress using RLZ compression (no terminator)

mmt_32

Compress using 32x32 pixel metametatiles.

Modifiers:

+fork_scope

16.41.1. `mmt_32` target

The mmt_32 target generates 32x32 pixel metametatiles, where each metametatile is comprised of four 16x16 metatiles. These metametatiles are not user-defined. Instead, they are computed automatically by scanning the level data.

Note	An error will occur if more than 256 metametatiles are found.

See examples/meta_meta_tiles for code which decompresses this.

16.42. `audio`

The audio keyword imports and converts audio data from an external file, converting the data into code definitions. It is only usable at top-level scope.

Syntax:

audio(target, args...)

target specifies the output target to use.
args… is a comma-separated list of arguments that the conversion script will use.

Example:

audio(puf1_music, "music.txt")

Output Targets

The following targets are accepted:

Conversion Target Description puf1_music

Music

puf1_sfx

Sound Effects

16.42.1. `puf1_music` target

The puf1_music target converts music data and generates code compatible with the PUF music engine.

Example:

audio(puf1_music, "music.txt")

Arguments

1st (optional): Filename as a string literal. The file should be a .txt file exported by FamiTracker. If this argument is left out, definitions will still be generated, albeit with zero tracks.

Definitions

Every generated definition will be prefixed with puf_, and will have /puf_data or /puf_omni as its group.

Because tracks are indexed by number, puf1_music enumerates each track with a compile-time constant definition. The names of these definitions are prefixed with puf_track_, followed by the track’s name converted to lowercase, with _ characters replacing spaces and other special characters.

For example, if the tracks are:

Main Menu
Game Play 1
Death

The following definitions would be defined by puf1_music:

ct U puf_track_main_menu   = 0
ct U puf_track_game_play_1 = 1
ct U puf_track_death       = 2

Use

The standard library file puf1.fab can be used to play the converted music. A description of how to compose compatible music can be found in that file.

Note	You will also need a `puf1_sfx` audio target.

16.42.2. `puf1_sfx` target

The puf1_sfx target converts sound effect data and generates code compatible with the PUF music engine.

Example:

audio(puf1_sfx, "music.txt", "music.nsf")

Arguments

1st (optional): Filename as a string literal. The file should be a .txt file exported by FamiTracker. If this argument is left out, definitions will still be generated, albeit with zero sound effects.
2nd (optional): Filename as a string literal. The file should be a .nsf file exported by FamiTracker, from the same project as the .txt. If both arguments are left out, definitions will still be generated, albeit with zero sound effects.

Definitions

Every generated definition will be prefixed with puf_, and will have /puf_data or /puf_omni as its group.

Because sound effects are indexed by number, puf1_sfx enumerates each track with a compile-time constant definition. The names of these definitions are prefixed with puf_sfx_, followed by the sound effect track’s name converted to lowercase, with _ characters replacing spaces and other special characters.

For example, if the sound effect tracks are:

Attack
Double Jump
Death

The following definitions would be defined by puf1_sfx:

ct U puf_sfx_attack      = 0
ct U puf_sfx_double_jump = 1
ct U puf_sfx_death       = 2

Use

The standard library file puf1.fab can be used to play the converted sound effects. A description of how to compose compatible sound effects can be found in that file.

Note	You will also need a `puf1_music` audio target.

16.43. `stows`

See stows.

16.44. `employs`

See employs.

16.45. Implementation Keywords

Keywords prefixed with two underscores (__) provide access to specific niches of the compiler, and are primarily intended for use in the standard library, not by users.

16.45.1. `__controllers`

__controllers is a value of type Int which returns the value set by the --controllers option.

16.45.2. `__sector_size`

__sector_size is a value of type Int which returns the value set by the --sector-size option.

16.45.3. `__expansion_audio`

__expansion_audio is a value of type Int, determined by the --expansion-audio option and the --mapper option.

Its possible values are below:

Value	Meaning
0	No expansion audio
1	MMC5 audio enabled
2	VRC6 audio enabled

16.45.4. `__mapper`

__mapper is a value of type Int which returns the INES mapper number set by the --mapper option.

16.45.5. `__illegal`

__illegal is a value of type Bool which returns true when the compiler supports the generation of illegal instructions.

16.45.6. `__mapper_state`

__mapper_detail is a value used by specific mappers (such as MMC1) to workaround interrupts that occur during bank switches. It is not recommended to use this keyword.

16.45.7. `__mapper_reset`

__mapper_reset is a function used by specific mappers (such as MMC1) to reset their state. It is not recommended to use this keyword.

16.45.8. `__fixed`

__fixed is a value of type Bool which returns if the mapper uses a fixed bank.

16.45.9. `__multiply`

__multiply is a value of type Void representing NESFab’s multiply subroutine. Referencing the value using unary operator & returns an address of type AA, pointing to the subroutine.

This subroutine expects two 8-bit multiplicands in registers A and Y. It returns the result of the multiplication with the low byte in A and the high byte in Y.

Example:

    lda #3
    ldy #10
    jsr &__multiply
    // Result in A and Y

17. Modifiers

Modifiers add additional metadata to definitions.

Example:

fn foo(U x) U
: employs /bar
: +align
    return x + x

17.1. Modifier Flags

Modifier flags are specified prefixed with a - or + character. - is used to disable the modifier, while + is used to enable it.

The following flags exist for definitions:

+inline, -inline: Force / prevent the function from being inlined.
+align: Aligns the data to fit inside a 256-byte page (or to 256 bytes otherwise).
+zero_page, -zero_page: Force / prevent variables from using fast zero-page RAM.
+sram, -sram: Force / prevent variables from using SRAM (see sram).
+spr_8x16: Reorders file CHR data from 8x16 tiles to 8x8 tiles.
+graphviz: Output the function’s intermediate representation in a graphviz file.
+info: Output the function’s intermediate representation in a text file.
+dpcm: Align and store the data in a ROM location suitable for DPCM.
+sector: Align and store the data in a ROM location aligned to the ROM chip’s sectors (for flash saving, etc).
+static: Allocate the function or data in every bank (or force them into the fixed bank, for mappers with one). This modifier is incompatible with asm functions that return in a different bank than they started in. You must validate this yourself.
+static_fixed: The same as +static, but only applies to mappers that have a fixed bank, like UNROM.
+palette_3: Converts 4-byte palettes into 3-byte palettes.
+palette_25: Converts 32-byte palettes into 25-byte palettes.
+sloppy, -sloppy: Enables / disables faster compilation speed, at the cost of performance.
+fork_scope: The invoked macro(s) will have access to private definitions inside the invoking file.
+solo_interrupt: Disable switchable interrupts and always use this interrupt.
+unused: Do not warn if the definition is unused.

Example:

fn foo(U x) U
: -inline
: +align
: +graphviz
    return x + x

17.2. Field Modifier Flags

Modifier flags are specified prefixed with a - or + character. - is used to disable the modifier, while + is used to enable it.

The following flags exist for struct fields:

+inherit: The struct will implicitly cast to the field’s type. The field of the field can be accessed directly.

17.3. Loop Modifier Flags

Modifier flags are specified prefixed with a - or + character. - is used to disable the modifier, while + is used to enable it.

The following flags exist for loop statements:

-unroll, +unroll: Hint to prevent/enable loop unrolling.
+unloop: Hint to unroll a loop completely, replacing the loop.

Example:

for U i = 0; i < 10; i += 10
: -unroll
    {PPUDATA}(i)

17.4. `nmi`

The nmi modifier is used inside a mode declaration to specify the mode’s NMI handler.

Syntax:

: nmi nmi_handler

nmi_handler is a nmi function handler to be used while this mode is executing.

The nmi modifier is optional. Modes without one will use an NMI handler that immediately returns from the interrupt.

Example:

nmi my_nmi()
    {PPUMASK}(PPUMASK_ON)

mode foo()
: nmi my_nmi
    // ...

17.5. `irq`

The irq modifier is used inside a mode declaration to specify the mode’s IRQ handler.

Syntax:

: irq irq_handler

irq_handler is an irq function handler to be used while this mode is executing.

The irq modifier is optional. Modes without one will use an IRQ handler that immediately returns from the interrupt.

Example:

irq my_irq()
    {PPUMASK}(PPUMASK_ON)

mode foo()
: irq my_irq
    // ...

17.6. `stows`

The stows modifier is used inside charmap definitions to enable string literals to use said charmap.

Syntax:

: stows /group_name

/group_name is a single data group which string literals will be stored in.

17.6.1. `stows omni`

The stows omni modifier behaves like stows, except it stores its data inside an omni data group.

Syntax:

: stows omni /group_name

/group_name is a single omni data group which string literals will be stored in.

17.7. `employs`

The employs modifier instructs a function to be dependent on a group. From the time the function is called to the time the function returns, the memory associated with that group will be usable by the function.

Normally, the compiler automatically infers the groups a function depends on. The employs modifier is only required in these circumstances:

A value is read or written using a hardware address (type AA or AAA).
The modified function is an asm fn.

Syntax:

: employs /group_names

/group_names is an optional list of groups.

17.7.1. `employs vars` and `employs data`

For additional control, employs vars and/or employs data modifiers can be used. These behave like employs, but only include the vars and/or data definitions of each groups.

Syntax:

: employs vars /group_names
: employs data /group_names

/group_names is an optional list of groups.

17.8. `preserves`

The preserves modifier is used inside a goto mode statement to specify which variables are kept, and which are reset to their initial value.

Syntax:

: preserves /group_names

/group_names is an optional list of vars groups.

If a global variable is not in a preserved group, it will be reset to its initial value if one exists. If no initial value was specified, the value will enter an undefined (garbage) state.

17.9. `data`

The data modifier is used to document which data groups a function uses.

Syntax:

: data /group_names

/group_names is an optional list of data groups.

The function will be checked by the compiler to ensure it only uses data from the listed groups.

17.10. `vars`

The vars modifier is used to document which vars groups a function uses.

Syntax:

: vars /group_names

/group_names is an optional list of data groups.

The function will be checked by the compiler to ensure it only uses variables from the listed groups.

18. Operators

18.1. Operator Tables

18.1.1. Unary Operators

Note	Operators with lower precedence numbers come earlier in the order of operations.

Operator Precedence Description

@

Get Pointer @

&

Get Hardware Address &

+

Unary Plus +

-

Unary Negate -

~

Unary Bitwise NOT ~

!

Unary Logical NOT !

18.1.2. Binary Operators

Note	Operators with lower precedence numbers come earlier in the order of operations.

Operator Precedence Associativity Description

.

Left

Member Access .

*

Left

Multiply *

+

Left

Add +

-

Left

Subtract -

<-<

Left

Rotate Left <-<

>->

Right

Rotate Right >->

<<

Left

Shift Left <<

>>

Left

Shift Right >>

&

Left

Bitwise AND &

^

Left

Bitwise XOR ^

|

Left

Bitwise OR |

<

Left

Less Than <

<=

Left

>

Left

Greater Than >

>=

Left

Greater Than or Equal To >=

==

Left

Equal To ==

!=

Left

Not Equal To !=

&&

Left

Logical AND &&

||

Left

Logical OR ||

<=<

Right

Assign by Rotate Left <=<

>=>

Left

Assign by Rotate Right >=>

*=

Right

Assign by Multiply (*=)

+=

Right

Assign by Add +=

-=

Right

Assign by Subtract -=

<<=

Right

Assign by Shift Left <<=

>>=

Right

Assign by Shift Right >>=

&=

Right

Assign by Bitwise AND &=

^=

Right

Assign by Bitwise XOR ^=

|=

Right

Assign by Bitwise OR |=

=

Right

Assign =

18.1.3. Function-like Operators

Note	All function-like operators have left associativity and evaluate first in the order of operations.

Operator Description

fn_expression(argument_expressions…)

Function Call

Type(argument_expressions…)

Explicit Type Cast

sizeof Type

Size of a Type

sizeof(expression)

Size of an Expression

len Type

Array Length of a Type

len(expression)

Array Length of an Expression

abs(expression)

Absolute Value

min(expression)

Minimum

max(expression)

Maximum

array_expression[index_expression]

U-Indexed Array/Pointer Access

array_expression{index_expression}

UU-Indexed Array/Pointer Access

{address_expression}()

Hardware Read>>

{address_expression}(value_expression)

Hardware Write

18.2. Operator Listings

18.2.1. Get Pointer `@`

Converts an lvalue pointer-addressable array into a corresponding pointer.

18.2.2. Get Hardware Address `&`

Converts an lvalue into its corresponding hardware address, of type AA or AAA.

This operator is intended to be used with inline assembly code. Although this operator by itself is safe, dereferencing the addresses it returns can easily cause undefined behavior. For regular code, it’s recommended to use Get Pointer @ instead.

18.2.3. Unary Plus `+`

Returns its operand, type and value unchanged. The operand must be an arithmetic type.

Example:

+100 // Equivalent to 100

18.2.4. Unary Negate `-`

Returns its operand subtracted from zero, type unchanged. The operand must be an arithmetic type.

Example:

-100 // Equivalent to (0 - 100)

18.2.5. Unary Bitwise NOT `~`

Returns its operand with every bit flipped (1 becomes 0, and vice versa), type unchanged. The operand must be an arithmetic type.

Example:

U bits = %1010
~bits // Equivalent to %11110101

18.2.6. Unary Logical NOT `!`

Returns its operand, converted to type Bool, then negated (true becomes false and vice versa). The operand must be an arithmetic type.

Example:

!0     // Equivalent to true
!5     // Equivalent to false
!true  // Equivalent to false
!false // Equivalent to true

18.2.7. Member Access `.`

Operator . is used to access members and nested values, and works similarly to other languages. Its behavior depends on the left hand side of the operator:

For structure values, returns the specified member as an lvalue.
For scalar values, returns the specified byte or pointer member as an lvalue.
For fn values and PAA values, returns the ct value in its scope.

Additionally, if the left hand side is an asm fn and the right hand side is a label, the result is a callable function with the label being the entry point.

Example:

foo.bar = 10               // Modify a struct member
some_uu.a = 10             // Modify a byte
some_asm_fn.some_label(10) // Call an assembly function

Scalar value members:

Scalars of types such as UU, SSSF, or CCC have the following members defined for them, when applicable:

Member Defined For Byte

.a

Scalars

1st (lowest) whole byte

.b

Scalars

2nd whole byte

.c

Scalars

3d whole byte

.z

Scalars

1st (highest) fractional byte

.y

Scalars

2nd fractional byte

.x

Scalars

3rd fractional byte

.bank

Only Pointers

Bank byte

.ptr

Only Pointers

Non-banked pointer

These members can be read or set using operator . like struct members can.

Example:

UUU foo = $123456
foo.a = 0   // Set the low byte.    foo is now $123400
foo.b = 0   // Set the middle byte. foo is now $120000
foo.c = 0   // Set the high byte.   foo is now $000000

18.2.8. Multiply `*`

Returns its operands multiplied together, of a type large enough to hold the product. The return type is signed if either operand is signed, but unsigned otherwise. The operands must be quantity types.

To be more precise, if the operand types have F and F' fractional bytes, the return type will have F + F'. Likewise, if the operand types have W and W' whole bytes, the return type will have W + W'. The return type will be truncated to fit the compiler’s available types.

Example:

5 * 3             // Equivalent to 15, of type Int
U(5) * U(8)       // Equivalent to 40, of type UU
UF(5.5) * SS(-10) // Equivalent to -55, of type SSSF

Note	Multiplying two variables together is a very slow operation, but multiplying a variable by a constant is faster since the compiler can convert the expression to a sequence of shifts and adds. However, if you need to do lots of multiplications, consider using lookup tables instead.

18.2.9. Assign by Multiply (`*=`)

Multiplies its operands together, then assigns the value to the lvalue left operand, converting as needed. Returns the left operand’s new value.

Example:

U a
a *= b // Equivalent to a = U(a * b)

18.2.10. Add `+`

Returns the sum of its operands. The operands must be of the same quantity type, although Int and Real will convert.

Example:

3 + 7 // Equivalent to 10

18.2.11. Assign by Add `+=`

Converts the right operand to the left operand’s type, then performs an addition using both operands and assigns the value to the lvalue left operand. Return the carry: a value of type Bool that is true when the resulting sum overflowed, and false otherwise.

Example:

U x = 200
x += 50  // 'x' is now equal to 50. The expression returns 'false'.
x += 100 // 'x' is now equal to 94 due to overflow. The expression returns 'true'.

Note	Unlike in other languages, this operator doesn’t return its left operand.

18.2.12. Subtract `-`

Returns the difference of its operands (the right operand subtracted from the left). The operands must be of the same quantity type, although Int and Real will convert.

Example:

10 - 7 // Equivalent to 3

18.2.13. Assign by Subtract `-=`

Converts the right operand to the left operand’s type, then performs a subtraction using both operands and assigns the value to the lvalue left operand. Return the carry: a value of type Bool that is false when the resulting sum underflowed, and true otherwise.

Example:

U x = 200
x -= 50  // 'x' is now equal to 150. The expression returns 'true'.
x -= 300 // 'x' is now equal to 106 due to underflow. The expression returns 'false'.

18.2.14. Rotate Left `<-<`

Moves each of the bits of the left operand one place to the left, with the lowest bit being filled with the value of the right operand. The left operand must be a type_quantity, and the right operand must be type Bool. The return type matches the left operand’s type.

Example:

U(%11001010) <-< false // Equivalent to U(%10010100)
U(%11001010) <-< true  // Equivalent to U(%10010101)
U(%01111111) <-< false // Equivalent to U(%11111110)

18.2.15. Assign by Rotate Left `<=<`

Performs a left rotation using both operands, then assigns the value to the lvalue left operand. Returns the carry: a value of type Bool equal to left operand’s highest bit prior to the operation.

Example:

U foo = %11001010
foo <=< false // Sets 'foo' to U(%10010100). Returns true.

18.2.16. Rotate Right `>->`

Moves each of the bits of the right operand one place to the right, with the highest bit being filled with the value of the left operand. The right operand must be a type_quantity, and the left operand must be type Bool. The return type matches the right operand’s type.

Example:

false >-> U(%11001010) // Equivalent to U(%01100101)
true  >-> U(%11001010) // Equivalent to U(%11100101)
false >-> U(%11111110) // Equivalent to U(%01111111)

Note	This operation corresponds to the 6502 assembly instruction `ROR`.

18.2.17. Assign by Rotate Right `>=>`

Performs a right rotation using both operands, then assigns the value to the lvalue right operand. Returns the carry: a value of type Bool equal to right operand’s lowest bit prior to the operation.

Example:

U foo = %11001010
false >=> foo // Sets 'foo' to %01100101. Returns false.

Note	This operator requires an lvalue on the right side of the operator, which is unlike other assignment operators.

18.2.18. Shift Left `<<`

Moves each of the bits of the left operand to the left N places, where N is the right operand of type U, and filling blank spaces with 0. The return type matches the left operand’s type.

Example:

U(%11110001) << 1 // Equivalent to U(%11100010)
U(%11110001) << 3 // Equivalent to U(%10001000)

Note	The NES performs shifts one bit at a time, meaning `x << 1` is five times faster than `x << 5`, and shifting by a variable (`x << y)` generates a loop in the assembly.

18.2.19. Assign by Shift Left `<<=`

Performs a left shift using both operands, then assigns the value to the lvalue left operand. Returns the carry: a value of type Bool equal to last bit shifted out (or false if no shifting occurred).

Example:

U foo = %11001010
foo <<= 2 // Sets 'foo' to U(%00101000). Returns true.

Note	Unlike in other languages, this operator doesn’t return its left operand.

18.2.20. Shift Right `>>`

Moves each of the bits of the left operand to the right N places, where N is the right operand of type U. If the left operand is unsigned, the blank spaces are filled with 0, otherwise the blank spaces are filled with the highest bit of the left operand (this is called sign extension). The return type matches the left operand’s type.

Example:

U(%11110001) >> 1 // Equivalent to U(%01111000)
S(%11110001) >> 1 // Equivalent to S(%11111000)
U(%11110001) >> 3 // Equivalent to U(%00011110)
S(%11110001) >> 3 // Equivalent to S(%11111110)
S(%01110001) >> 3 // Equivalent to S(%00001110)

Note	The NES performs shifts one bit at a time, meaning `x >> 1` is five times faster than `x >> 5`, and shifting by a variable (`x >> y)` generates a loop in the assembly.

18.2.21. Assign by Shift Right `>>=`

Performs a right shift using both operands, then assigns the value to the lvalue left operand. Returns the carry: a value of type Bool equal to last bit shifted out (or false if no shifting occurred).

Example:

U foo = %11001010
foo >>= 2 // Sets 'foo' to U(%00110010). Returns true.

Note	Unlike in other languages, this operator doesn’t return its left operand.

18.2.22. Bitwise AND `&`

Applies the AND operation across each bit of the operands, returning the result. The operands must be of the same arithmetic type, although Int and Real will convert.

Example:

U(%11110000) & U(%10101010) // Equivalent to U(%10100000)

18.2.23. Assign by Bitwise AND `&=`

Converts the right operand to the left operand’s type, then performs a bitwise AND using both operands and assigns the value to the lvalue left operand. Returns the left operand’s new value.

Example:

U foo = %11110000
foo &= %10101010 // Sets 'foo' to U(%10100000)

18.2.24. Bitwise XOR `^`

Applies the XOR operation across each bit of the operands, returning the result. The operands must be of the same arithmetic type, although Int and Real will convert.

Example:

U(%11110000) ^ U(%10101010) // Equivalent to U(%01011010)

18.2.25. Assign by Bitwise XOR `^=`

Converts the right operand to the left operand’s type, then performs a bitwise XOR using both operands and assigns the value to the lvalue left operand. Returns the left operand’s new value.

Example:

U foo = %11110000
foo ^= %10101010 // Sets 'foo' to U(%01011010)

18.2.26. Bitwise OR `|`

Applies the OR operation across each bit of the operands, returning the result. The operands must be of the same arithmetic type, although Int and Real will convert.

Example:

U(%11110000) | U(%10101010) // Equivalent to U(%11111010)