Struct ggbasm::RomBuilder

pub struct RomBuilder { /* private fields */ }

Keeps track of the state of a rom as it is being constructed.

Keeps track of the current address and inserts binary data and instructions at that address. The address is advanced when binary data or instructions are added and can also be manually advanced. When manually advanced the area in between is filled with zeroes. The address can only be advanced, it can never go backwards.

In *.asm files, the advance_address instruction will cause the space between the last instruction . and the new address to be filled with zeroes.

Implementations

impl RomBuilder

pub fn new() -> Result<RomBuilder, Error>

Creates a RomBuilder.

pub fn add_basic_interrupts_and_jumps(self) -> Result<Self, Error>

Adds basic interrupt and jump data from 0x0000 to 0x0103.

The entry point jumps to 0x0150. The interrupts return immediately. The RST commands jump to the entry point. Returns an error if the RomBuilder address is not at 0x0000.

pub fn add_header(self, header: Header) -> Result<Self, Error>

Adds provided header data at 0x0104 to 0x149.

Returns an error if the RomBuilder address is not at 0x104

pub fn add_bytes(self, bytes: Vec<u8>, identifier: &str) -> Result<Self, Error>

Includes raw bytes in the rom. The name is used to reference the address in assembly code. Returns an error if crosses rom bank boundaries.

pub fn add_image(
    self,
    file_name: &str,
    identifier: &str,
    color_map: &HashMap<Color, u8>
) -> Result<Self, Error>

Includes graphics data generated from the provided image file in the graphics folder.

The name is used to reference the address in assembly code. Returns an error if crosses rom bank boundaries. The color_map argument specifes how to convert 24 bit rgb color values into the 2 bit color values used by the gameboy.

TODO: Describe the format of generated images.

pub fn add_audio_file(self, file_name: &str) -> Result<Self, Error>

Includes audio data generated from the provided ggbasm audio text file in the audio folder.

Returns an error if crosses rom bank boundaries.

Currently only supports playing one track at a time, playing sound effects on top of background music might not be possible with the current architecture. Oops…

Format

There are long lines containing the data for each sound register and how long to wait before running the next command. There are also various commands to e.g. set a label or continue playing from a specific label

label my_cool_song
07                       D6:2:10:7:4Y:NY
07                       D6:2:10:7:4Y:NY
07  D6:2:10:7:4Y:NY:Y00                 
07                       D6:2:10:7:4Y:NY
07  D6:2:10:7:4Y:NY:Y00  D6:2:10:7:4Y:NY
playfrom my_cool_song

Channel formats

Data for each channel is written on the same line like this:

RST CHANNEL1             CHANNEL2         CHANNEL3      CHANNEL4
0F  D6:2:10:7:4Y:NY:Y00  D6:2:10:7:4Y:NY  TODO          TODO

Only changes between lines are included in the audio data.

Channel 1 format:

AB:C:DD:E:FG:HI:JKL

Key:

• A: Note A-G (natural), a-g (sharp)
• B: Octave 1-8
• C: Duty 0-3
• DD: length 0-3F
• E: envelope initial volume 0-F
• F: envelope argument 0-7
• G: envelope increase Y/N
• H: enable length Y/N
• I: initial Y/N
• J: sweep increase Y/N
• K: sweep time 0-7
• L: number of sweeps 0-7

For example: D6:2:10:7:4Y:NY:Y00

Channel 2 format:

AB:C:DD:E:FG:HI

Key:

• A: Note A-G (natural), a-g (sharp)
• B: Octave 1-8
• C: Duty 0-3
• DD: length 0-3F
• E: envelope initial volume 0-F
• F: envelope argument 0-7
• G: envelope increase Y/N
• H: enable length Y/N
• I: initial Y/N

For example: D6:2:10:7:4Y:NY

Channel 3 format:

TODO

Channel 4 format:

TODO

Control lines

• rest AA - rest AA frames before continuing
• jp foo - set the GGBASMAudio
• disable - disables audio by setting the value at GGBASMAudioEnable to 0

TODO: Maybe syntax highlighting could help make the audio format more readable

pub fn add_audio_player(self) -> Result<Self, Error>

Includes bytecodes generated from the audio player

Returns an error if crosses rom bank boundaries.

Functions

This should be called once during initialization:

call GGBASMInitAudio

This should be called once per frame:

call GGBASMStepAudio

RAM Locations

These identifiers need to be set to some unused ram values.

GGBASMAudioEnable    EQU 0xC020 ; dont process music when 0 otherwise process it
GGBASMAudioBank      EQU 0xC021 ; the bank the currently playing song is stored on
GGBASMAudioPointerLo EQU 0xC022 ; pointer to the currently playing song
GGBASMAudioPointerHi EQU 0xC023
GGBASMAudioRest      EQU 0xC024 ; rest for this many steps

Change the currently playing song by setting GGBASMAudioBank, GGBASMAudioPointerHi and GGBASMAudioPointerLo to the address of the song you want to play

Make sure the memory is accessible (correct bank enabled) whenever an audio function is called.

pub fn add_asm_file(self, file_name: &str) -> Result<Self, Error>

Includes bytecodes generated from the provided assembly file in the gbasm folder.

TODO: Document the syntax. Its very similar to the RGBDS syntax with the addition of the advance_address command. However we should have our syntax documentation listing every instruction and every operator in rom compile time expressions.

Returns an error if crosses rom bank boundaries. Returns an error if encounters file system issues.

pub fn add_instructions(
    self,
    instructions: Vec<Instruction>
) -> Result<Self, Error>

This function is used to include instructions in the rom. Returns an error if crosses rom bank boundaries.

pub fn advance_address(self, rom_bank: u32, address: u32) -> Result<Self, Error>

Sets the current address and bank as specified. Returns an error if attempts to go backwards. To cross bank boundaries you need to use this function.

pub fn get_address_global(&self) -> u32

Gets the current address within the entire rom.

pub fn get_address_bank(&self) -> u16

Gets the current address within the current bank.

pub fn get_bank(&self) -> u32

Gets the current bank.

pub fn print_variables_by_value(self) -> Result<Self, Error>

pub fn print_variables_by_identifier(self) -> Result<Self, Error>

pub fn compile(self) -> Result<Vec<u8>, Error>

Compiles assembly and binary data into binary rom data.

pub fn write_to_disk(self, name: &str) -> Result<(), Error>

Compile the ROM then write it to disk at the root of the project. The root of the project is the outermost directory containing a Cargo.toml file.

pub fn write_to_disk_html(self, _name: &str) -> Result<(), Error>

Provide some sort of mechanism to generate an html file with embedded gb emulator and rom data. Use Cargo.toml metadata to generate a link to repository, include developers name etc. (use panic-handler as a reference here) This is completely unimplemented, its just a reminder to do this some day.