Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

Note

This page is currently a stub and needs more detail.

Starfrootle is a fantasy console written in Rust.

Specifications

Address space16 MB (24-bit addresses, 0x000000 to 0xFFFFFF)
Screen240x240 (30 tiles across, 30 tiles vertically)
Tile and sprite size8x8
Tile layers5 (each with a 64x64 tile map)
Sprites128
Palettes16 (16 colors each)
Controllers8
Audio16 channels, 48,000 Hz stereo output

Conventions

  • Big-endian. Multi-byte values are written most significant byte first. An address of C0 00 00 is 0xC00000.
  • Nybbles. A nybble is 4 bits, written as one hex digit. A byte is a pair of nybbles, and the high nybble is the left digit (in 47, the high nybble is 4 and the low nybble is 7).
  • Addresses are 3 bytes (6 nybbles) long.
  • Hex notation. In prose, values are written like 0x400000. Raw bytes in memory are written as space-separated pairs, like C0 00 00.

Project Structure

Note

This page is currently a stub and needs more detail.

Docs

Defines everything you need to know about Starfrootle

Core Library

Contains things such as the list of opcodes, constants, and other things that could be shared between the assembler, emulator, and other projects.

Emulator

Contains the actual Starfrootle emulator, including save state management, UI, keyboard/controller mapping, etc.

Assembler

Rust code for creating Starfrootle rom code, contains a built in library for fonts, sound and music management/playing, and meta/multi-sprite management.

Memory Map

Note

This page is currently a stub and needs more detail.

Warning

Starfrootle is still being built, these regions are very prone to moving, being resized, or having things slotted between them.

Addresses are 3 bytes long and big-endian, giving a 16 MB address space.

Each region ends right before the next one starts. In the case of ROM, it ends at 0xFFFFFF, the end of address space.

StartRegionNotes
0x000000RAM
0x200000VRAMSee VRAM Layout
0x220000I/OSee I/O Layout
0x230000Boot ROMSee Boot ROM. Read-only
0x240000Save RAMKept between sessions. See Save memory
0x250000ROMSee ROM Layout

I/O, Boot ROM and Save RAM each have a slot of 64 KB (0x10000).

ROM

Important

“ROM” is actually more RAM space, the ROM data from the game is copied to this section during the boot sequence by the hardware. This means ROM is actually writable like RAM, because it is RAM.

CPU

Note

This page is currently a stub and needs more detail. Information on cycles, stack, reset, the main loop, etc. are completely missing.

Registers

RegisterSizeNotes
General purpose (16)8 bits eachNumbered 0 to F, so a register fits in one nybble
Program counter24 bitsAddress of the next byte to read
Stack pointer24 bitsPushed big-endian
Flags8 bitsSee below

Flags

BitFlag
0Zero
1Carry
2Negative
3Overflow

Bits 4 to 7 are currently unused.

Reset State

The CPU starts with everything at 0, with the SP at 0x400000 with a pre-decrement

Timing/Main Loop

Note

This page is currently a stub and needs more detail.

Instruction Set

Note

This page is currently a stub and needs more detail. How flags are set for each instruction are not documented yet.

Warning

This is not the final instruction set. While opcodes are very unlikely to change, new opcodes/instructions will be created as Starfrootle develops.

Opcodes are a single byte, so there can be at most 256 different instructions. Opcodes are grouped by their high nybble. Any byte that is not a defined opcode behaves like NoOp.

High nybbleGroup
0xSystem
1xLoads and stores
2xMoves, pushes and pops
3xArithmetic
4xLogic and shifts
5xBit operations (planned)
6xComparisons
7xJumps and branches
8xCalls and returns
9xBlock operations (planned)

Defined opcodes

OpcodeNameOperandsBytesFlagsEffect
00NoOpnone1nonedo nothing
01Haltnone1nonestop the CPU
10LoadConstD_ value3noneregister = value
11LoadMemD_ address5noneregister = byte at address
12StoreMemS_ address5nonebyte at address = register
13LoadIndirectDS2noneD = byte at address at S, S+1, S+2
14StoreIndirectDS2nonebyte at address at D, D+1, D+2 = S
20CopyDS2noneD = S
21SwapDS2noneexchange D and S
22PushS_2nonepush register onto the stack
23PopD_2nonepop the stack into register
30AddDS2Z C N VD = D + S
31SubDS2Z C N VD = D - S
32IncD_2Z N VD = D + 1
33DecD_2Z N VD = D - 1
40AndDS2Z ND = D & S
41OrDS2Z ND = D | S
42XorDS2Z ND = D ^ S
43NotD_2Z ND = ~D
44ShiftLeftDn2Z C ND <<= n
45ShiftRightDn2Z C ND >>= n
60CompareDS2Z C N Vcomputes D - S, only sets flags
70Jumpaddress4nonePC = address
71JumpIfZeroaddress4nonejump if Z set
72JumpIfNotZeroaddress4nonejump if Z clear
73JumpIfCarryaddress4nonejump if C set
74JumpIfNoCarryaddress4nonejump if C clear
75JumpIfNegativeaddress4nonejump if N set
76JumpIndirectaddress4nonePC = the 3-byte address stored at address
80Calladdress4nonepush return address (3 bytes), jump
81Returnnone1nonepop PC
82CallIndirectaddress4nonepush return address (3 bytes), jump to the address stored at address

Unused Operand Nybbles

For instances like D_ or S_, the low nybble _ is completley ignored.

Indirect Jump and Call

JumpIndirect and CallIndirect take the address of a vector instead of a destination. The CPU reads the 3-byte (big-endian) address stored at that location and jumps to it, so code can jump to an address that is stored in memory. For example, the boot ROM uses JumpIndirect on the reset vector in the ROM header to start a game.

Indirect Load and Store

Register indexes beyond 0xD will wrap around to the start of the register indexes. For instance 13 7F would set the register at index 0x7 with the value of the address defined by the registers 0xF 0x0 and 0x1.

Cycle Cost

For each instruction, it’s 1 cycle plus 1 per byte fetched or accessed. For instance, TODO PUT EXAMPLE

ROM Layout

Note

This page is currently a stub and needs more detail.

OffsetSizeField
+0x004 bytesMagic Number (53 54 52 4C STRL)
+0x041 byteFormat version (0x00 Currently)
+0x058 bytesUnique Game ID
+0x0D3 bytesReserved
+0x104 bytesReset vector
+0x144 bytesVBlank vector
+0x184 bytesScanline vector
+0x1C36 bytesReserved for future vectors
+0x40restCode and data

Each vector is a 3-byte address followed by 1 reserved byte.

Boot ROM

Note

This page is currently a stub and needs more detail. Several parts of the boot ROM have not been decided yet, and are listed at the bottom of this page.

Every time the console starts, it runs the boot ROM before the game. The boot ROM is not optional, and it is not built into the emulator. It is a separate file that the emulator loads into its own region of memory, and if that file is missing the emulator will not start.

The intro animation can be skipped by pressing any binary input on any of the 8 controllers after the heafer is checked.

Region

Where the boot ROM starts is defined in starts is defined in the memory map. Unlike the game’s ROM, which is really RAM, the boot ROM is truly read-only and writes to it are ignored. A game that corrupts memory can never stop the console from starting again.

Boot Sequence

  1. The emulator loads the boot ROM file into the boot ROM region, and copies the game file into the ROM region.
  2. RAM, VRAM and I/O start out zeroed.
  3. The CPU starts running the boot ROM.
  4. The boot ROM plays the intro and checks the game’s header: the magic number and the format version. If either is wrong, it shows an error instead of starting the game.
  5. The boot ROM puts the console into a clean state.
  6. The boot ROM starts the game by jumping to the game’s reset vector, using JumpIndirect on the reset vector at rom start + 0x10.

File Format

The boot ROM file the emulator needs is a raw binary file starting at where the boot ROM starts in memory, the CPU starts at its first byte.

Not Decided Yet

  • Exactly what state the console is in when a game starts, which step 5 has to produce.
  • What the error screen looks like, and what the boot ROM does after showing it.
  • Where the emulator looks for the boot ROM file.

Overview

Note

This page is currently a stub and needs more detail.

  • 240x240 screen size (30 tiles across, 30 tiles vertically)
  • 8x8 tiles and sprites
  • 5 tile layers (layer 0 is the topmost), each with a 64x64 tile map and its own scrolling
  • 128 sprites
  • 16 palettes
  • A background color, which is separate from the palettes

Where each of these lives in memory is described in VRAM Layout.

Draw Order

Everything on screen is drawn back to front:

StepDrawn
1Background color
2Sprites with layer offset 9
3Tile layer 4
4Sprites with layer offset 8, then 7
5Tile layer 3
6Sprites with layer offset 6, then 5
7Tile layer 2
8Sprites with layer offset 4, then 3
9Tile layer 1
10Sprites with layer offset 2, then 1
11Tile layer 0
12Sprites with layer offset 0

Sprites that share a layer offset are drawn in the order they appear in the sprite table, so later sprites are drawn on top.

A tile layer that is disabled (see Layer Registers) is skipped, and everything else is drawn in the same order.

How things blend as they are drawn is purposely undefined for now. See Blending.

VRAM Layout

Note

This page is currently a stub and needs more detail.

Where VRAM starts is defined in the memory map. Most regions have a slot that is larger than what it currently uses, so such regions can grow without the others having to move.

OffsetSizeUsedContents
+0x000000x10000x400Sprite table
+0x010000x10000x30Background color, Screen Brightness, and layer registers
+0x020000x20000x300Palettes
+0x040000x40000x4000Tile map for layer 0
+0x080000x40000x4000Tile map for layer 1
+0x0C0000x40000x4000Tile map for layer 2
+0x100000x40000x4000Tile map for layer 3
+0x140000x40000x4000Tile map for layer 4
+0x180000x80000Reserved

Sprite Table

128 sprite entries of 8 bytes each, which is 1 KB. Sprite N lives at vram start + N * 8.

Background Color

The background color is 3 bytes, red then green then blue, at +0x01000. It is drawn behind everything and is not part of any palette.

Screen Brightness

The byte at +0x01003 controls the screen brightness. At 0, the screen will render as normal. As the value approaches 255, the screen gets closer to pure black, where 255 is pure black.

The 4 bytes after it (+0x01004 to +0x01007) are reserved.

Layer Registers

Each layer has 8 bytes of layer registers. The registers for layer N live at vram start + 0x01008 + N * 8.

Palettes

16 palettes of 16 colors, 3 bytes per color. Color C of palette P is at vram start + 0x02000 + P * 0x30 + C * 3.

Tile Maps

Each tile layer has a tile map of 64x64 tile entries, 4 bytes each. The tile map for layer N starts at vram start + 0x04000 + N * 0x4000, and the entry at column X and row Y is at map start + Y * 0x100 + X * 4.

Palettes

Note

This page is currently a stub and needs more detail.

There are 16 palettes, each with 16 colors. Palettes are shared between tiles and sprites: every pixel of an image is an index (0 to F) into the palette chosen by the tile or sprite that draws it.

The background color is not part of any palette. See VRAM Layout.

Colors

A color is 3 bytes: red, green, then blue, with one byte per channel. A palette is 16 colors, so 48 bytes (0x30), and all 16 palettes take 0x300 bytes.

Color C of palette P is at palette table + P * 0x30 + C * 3. The address of the palette table is in VRAM Layout.

Transparency

Index 0 is transparent only if its color is exactly 00 00 00 (pure black). Any other color at index 0 is drawn like every other color. No other index is ever transparent.

Tiles

Note

This page is currently a stub and needs more detail.

Tiles are 8x8 images. Tiles are stored in the tile maps of tile layers, and a tile map entry is 4 bytes:

OffsetSizeField
+03 bytesImage address
+31 bytePalette (high nybble), Transform (low nybble)

This is the same format as the first 4 bytes of a sprite entry.

Image address (+0 to +2): the address of the image this tile reads as image data.

Palette (+3, high nybble): which of the 16 palettes this tile is using.

Transform (+3, low nybble): a transformation applied to the tile’s image when it is drawn. The values are listed under Images.

Tiles have no blend mode of their own. Blending is set for a whole layer instead, see Tile Layers.

Tile Layers

Note

This page is currently a stub and needs more detail.

There are 5 tile layers, numbered 0 to 4. Layer 0 is the topmost. Each layer has its own tile map, and each layer scrolls independently.

Tile Maps

A tile map is 64x64 tile entries of 4 bytes each, which is 16 KB (0x4000) per layer. The screen is 30x30 tiles, so a map is a little more than twice the screen in each direction (512x512 pixels).

Entries are stored one row at a time, so the entry at column X and row Y (both 0 to 63) is at map base + Y * 0x100 + X * 4. The address of each layer’s map is in VRAM Layout.

Scrolling

Scroll X and scroll Y are each 1 byte (0 to 255). A scroll value is the position in the map of the top left corner of the screen, in pixels.

At the largest scroll value the screen shows up to pixel 494 (255 + 239), which is inside tile column or row 61. Columns and rows 62 and 63 of a map can never be visible.

Sprites are not affected by scrolling. See Sprites.

Layer Registers

Each layer has 8 bytes of registers:

OffsetSizeField
+01 byteScroll X
+11 byteScroll Y
+21 byteBlend mode (see Blending)
+31 byteFlags
+44 bytesReserved

The address of each layer’s registers is in VRAM Layout.

Flags

Offset +3

BitFlag
0Enabled: 1 means the layer is drawn, 0 means the layer is skipped
1 to 7Reserved

A disabled layer is skipped entirely, but its scroll and blend mode values are kept. Sprites are still drawn in the same order relative to where the layer would have been (see the Overview).

Sprites

Note

This page is currently a stub and needs more detail. Larger Sprites needs more info on constructing “meta sprites” (sprites made up of multiple sprites)

Sprite Entry

A sprite entry is exactly 8 bytes. Sprite N lives at base + N * 8, where base is the start of the sprite table (see VRAM Layout).

A single sprite may look like this in memory:

C0 00 00 47 40 FF FF 00

Layout

OffsetSizeField
+03 bytesImage address
+31 bytePalette (high nybble), Transform (low nybble)
+41 byteLayer offset (high nybble), Blend mode (low nybble)
+52 bytesX and Y position
+71 byteReserved

Image Address

Offsets +0 to +2 (C0 00 00)

An address that defines what section of memory this sprite will read as image data.

This image data is read as an 8x8 indexed image. See Images for more information.

Palette and Transform

Offset +3 (47)

High nybbleLow nybble
PaletteTransform

Palette (4): which of the 16 palettes this sprite is using.

Transform (7): a transformation applied to the sprite’s image when it is drawn. The values are listed under Images.

Layer Offset

Offset +4, high nybble (4)

The layer offset places the sprite relative to the tile layers. Layer 0 is the topmost tile layer.

ValueSprite is drawn…
0In front of tile layer 0
1Behind tile layer 0
2In front of tile layer 1, behind anything on layer 0
3Behind tile layer 1
4In front of tile layer 2, behind anything on layer 1
5Behind tile layer 2
6In front of tile layer 3, behind anything on layer 2
7Behind tile layer 3
8In front of tile layer 4, behind anything on layer 3
9Behind tile layer 4

Values A to F are not yet defined.

Sprites with the same layer offset are drawn in the order they appear in memory, so the sprite that comes later in the sprite table is drawn on top. The full back-to-front order of layers and sprites is described in the Overview.

Blend Mode

Offset +4, low nybble (0)

The blend mode affects how the sprite blends with the pixels behind it. The available modes are listed under Blending. Blending is purposely left undefined for now.

Position

Offsets +5 to +6 (FF FF)

The game screen has an 8 pixel margin around it, and sprites can hide behind these. Sprite positions are screen-spaced, meaning any tile layer scrolling will not scroll sprites with it.

  • X (FF, from +5): sprites start 8 pixels outside the left of the screen. This value shifts the sprite right along the X axis, in pixels.
  • Y (FF, from +6): sprites start 8 pixels outside the top of the screen. This value shifts the sprite down along the Y axis, in pixels.

If you wish to hide a sprite or aren’t using it, parking it in any corner outside the screen is the correct way to do it. Most commonly, this is done at the top left corner, 0,0.

Example

C0 00 00 47 40 FF FF 00 decodes to:

FieldValue
Image address0xC00000
Palette4
Transform7 (horizontally flipped, then 270 degrees clockwise)
Layer offset4 (in front of tile layer 2, behind anything on layer 1)
Blend mode0 (Normal)
X0xFF (255)
Y0xFF (255)
Reserved0x00 (0)

Larger Sprites

128 sprites is 8 characters of 32x32 (16 parts each), or 32 of 16x16.

Images

Note

This page is currently a stub and needs more detail.

An image is 8x8 pixels, made up of 32 bytes, with each nybble representing which color in the palette that specific pixel uses.

Tiles and sprites don’t store pixels themselves. They store the address of an image (see Tiles and Sprites).

Index 0 of a palette can be transparent. See Palettes.

Pixel Order

An image is stored one row at a time, starting with the top row. Each row is 4 bytes, with 2 pixels per byte. Inside a byte, the high nybble is the left pixel and the low nybble is the right pixel, the same way the byte is written.

OffsetRow
+0 to +3Row 0 (top)
+4 to +7Row 1
+8 to +11Row 2
+12 to +15Row 3
+16 to +19Row 4
+20 to +23Row 5
+24 to +27Row 6
+28 to +31Row 7 (bottom)

Within a row:

Byte+0+1+2+3
Pixels (left to right)high, lowhigh, lowhigh, lowhigh, low
Columns0, 12, 34, 56, 7

For example, a row of 12 34 56 78 has the palette indexes 1 2 3 4 5 6 7 8 from left to right.

Transformations

Tiles and sprites can both apply a transformation to their image when it is drawn. A transformation is a single nybble value:

ValueTransformation
0No rotation
190 degrees (clockwise)
2180 degrees (clockwise)
3270 degrees (clockwise)
4Horizontally flipped, no rotation
5Horizontally flipped, then 90 degrees (clockwise)
6Horizontally flipped, then 180 degrees (clockwise)
7Horizontally flipped, then 270 degrees (clockwise)

Anything beyond this repeats the previous entries in the list. These may be used for something in the future.

Blending

Note

This page is currently a stub and needs more detail.

Warning

Blending is purposely left undefined for now. The math behind each mode, the order blending is applied in, and how modes like Clip behave are all still being designed, and will be documented here once they are decided.

Available Modes

ValueModeSpritesTile layers
0NormalYesYes
1AddYesYes
2MultiplyYesYes
3InvertYesYes
4ClipYesNo

Currently only these 5 modes exist. Future modes may be added. Values above the listed modes are not yet defined.

Where the Blend Mode is Stored

  • Sprites store a blend mode in the low nybble of offset +4 of their sprite entry.
  • Tile layers store a blend mode in offset +2 of their layer registers. Individual tiles don’t have a blend mode.

Input

Note

This page is currently a stub and needs more detail.

Controller Entry

A controller entry is exactly 16 bytes. Controller N lives at base + N * 16, where base is the start of the controller table (see I/O Layout).

A controller entry in memory can be modified but will be overwritten by the hardware each frame.

Layout

OffsetSizeField
+0 low nybbleFace buttons: South, East, West, North (bits 0 to 3)
+0 high nybble1 byteStart, Select, Left stick click, Right stick click
+1 low nybbleD-pad: Up, Down, Left, Right
+1 high nybble1 byteLeft bumper, right bumper, left trigger (digital), right trigger (digital)
+21 byteLeft stick X
+31 byteLeft stick Y
+41 byteRight stick X
+51 byteRight stick Y
+61 byteLeft trigger
+71 byteRight trigger
+81 byteBattery
+91 byteFlags
+106 bytesReserved

Face Buttons

Other Buttons

D-pad

Bumpers and Triggers

Triggers (analogue)

Sticks

Battery

Outputs a level from 0 (empty) to 255 (full). A controller with no battery level will always return 255.

Flags

BitFlag
0Controller connected
1Controller uses battery
2 to 7Reserved

Audio

Note

This page is currently a stub and needs more detail.

Starfrootle has 16 audio channels. Every channel is a mono source with a pan control, and all channels are mixed into a stereo output at 48,000 Hz (800 samples per frame at 60 FPS). Pan the center to get a mono sound, or play a stereo sound on two channels panned hard left and hard right.

The CPU only writes to registers. The console generates the sound itself, and music and sound effects are handled by code in the game.

Where the audio registers live in memory is described in I/O Layout.

Signal Flow

Each channel passes through the following steps, in order:

  1. Source: a generated wave, noise, or a sample.
  2. Filter: a low-pass filter (only if the filter is enabled).
  3. Envelope and volume: the envelope shapes the volume over time (only if the envelope is enabled).
  4. Effect sends: a part of the signal is sent to the global reverb, chorus and delay.
  5. Pan: the signal is placed between the left and right outputs.

The three global effects are mixed with the channels to make the final output, which is then scaled by the master volume.

Channel Entry

A channel entry is exactly 64 bytes. Channel N lives at base + N * 0x40, where base is the start of the audio channel table (see I/O Layout).

All of the multi-byte values in a channel entry are big-endian. Zeroed memory is silent.

Layout

OffsetSizeField
+0x001 byteFlags
+0x011 byteSource
+0x021 byteVariant
+0x031 byteVolume
+0x041 bytePan (signed)
+0x052 bytesPitch
+0x071 byteEnvelope: attack
+0x081 byteEnvelope: decay
+0x091 byteEnvelope: sustain level
+0x0A1 byteEnvelope: release
+0x0B1 byteVibrato: rate
+0x0C1 byteVibrato: depth
+0x0D1 byteVibrato: shape
+0x0E1 byteFilter: cutoff
+0x0F1 byteFilter: peak
+0x101 byteReverb send
+0x111 byteChorus send
+0x121 byteDelay send
+0x131 byteReserved
+0x143 bytesSample start address
+0x173 bytesSample end address
+0x1A3 bytesSample loop start address
+0x1D3 bytesSample loop end address
+0x2032 bytesReserved

Flags

Offset +0x00

BitFlag
0Gate: a note starts when this changes from 0 to 1, and is released when it changes from 1 to 0
1Loop (samples only)
2Envelope enabled
3Filter enabled
4Active (read only): 1 while the channel is making sound. The console sets and clears this bit, and writes to it are ignored.
5 to 7Reserved

When a note starts, the envelope begins its attack from silence, the vibrato starts at the beginning of its cycle, the filter is cleared, and a sample starts playing from its start address.

When a note is released, the envelope starts its release. If the envelope is not enabled, the sound stops immediately. The active bit is cleared once the sound has fully stopped, which includes a sample reaching its end when it isn’t looping. To play a note again after that, write 0 and then 1 to the gate.

Source and Variant

Offsets +0x01 and +0x02

SourceSound
0Pulse
1Triangle
2Saw
3Sine
4Noise
5Sample

Values above 5 are not yet defined.

The variant changes how some sources sound, and is ignored by the others:

SourceVariant
PulseDuty cycle: the fraction of each wave that is high, as the value divided by 256 (0x80 is 50%, 0x40 is 25%)
Noise0 is long noise, 1 is short, more metallic noise. Other values are not yet defined.

Volume and Pan

Offsets +0x03 and +0x04

Volume goes from 0 (silent) to 255 (full volume).

Pan is a signed byte from -128 (fully left) through 0 (center) to 127 (fully right). At the center, both sides play at full volume. Moving away from the center fades the opposite side out linearly.

Pitch

Offsets +0x05 and +0x06

Pitch is a 16-bit value that sets the playback speed as a multiple of the sample’s native speed:

speed = pitch / 0x1000

So 0x1000 plays at normal speed, 0x2000 plays one octave higher, and 0x0800 plays one octave lower. A pitch of 0x0000 is silent. The values are linear in frequency, so going up an octave doubles the value, which is a shift left.

Samples are expected to be tuned to C-5 and have a native rate of 32,000 Hz, so 0x1000 is C-5. Generated waves at 0x1000 also produce C-5 (about 523.25 Hz), and scale linearly from there. Noise advances at the same ratio.

Notes follow equal temperament with A-4 at 440 Hz. This is the table for octave 5, and every other octave is this table shifted left (up) or right (down) once per octave:

NotePitchNotePitch
C-50x1000F#-50x16A1
C#-50x10F4G-50x17F9
D-50x11F6G#-50x1966
D#-50x1307A-50x1AE9
E-50x1429A#-50x1C82
F-50x155CB-50x1E34

The range of notes that fit is C-0 (0x0080) to B-8 (0xF1A2). One step of pitch is about 0.42 cents at C-5, and is coarser for lower notes.

Envelope

Offsets +0x07 to +0x0A

The envelope shapes the volume of a note, and only applies if the envelope flag is set. Without it, a note plays at full volume until it is released.

OffsetFieldMeaning
+0x07AttackFrames to rise from silence to full volume
+0x08DecayFrames to fall from full volume to the sustain level
+0x09Sustain levelThe level held while the gate is 1, from 0 (silent) to 255 (full)
+0x0AReleaseFrames to fall from the current level to silence after the gate is released

A frame is 1/60 of a second, and a time of 0 is instant. All of the changes are linear.

Vibrato

Offsets +0x0B to +0x0D

Vibrato is a low frequency oscillator (LFO) that moves the pitch up and down.

OffsetFieldMeaning
+0x0BRateCycles per second, as the value divided by 16 (0x60 is 6 Hz)
+0x0CDepthThe peak change in pitch in semitones, as the value divided by 16 (0x10 is one semitone up and down). A depth of 0 is no vibrato.
+0x0DShape0 sine, 1 triangle, 2 saw, 3 square. Other values are not yet defined.

The depth is measured in semitones, so vibrato sounds the same in every octave.

Filter

Offsets +0x0E and +0x0F

A two pole low-pass filter that only applies if the filter flag is set.

OffsetFieldMeaning
+0x0ECutoffCutoff frequency, from 20 Hz at 0 rising exponentially to about 20 kHz at 255. The frequency is 20 Hz × 2^(value / 25.5).
+0x0FPeakResonance peak at the cutoff, from 0 (no peak) to 255 (the strongest peak), roughly a Q of 0.7 to 10

Effect Sends

Offsets +0x10 to +0x12

Each send is how much of this channel’s sound goes to the matching global effect, from 0 (none) to 255 (full). The send is taken after the envelope and volume are applied, and before pan.

Samples

Offsets +0x14 to +0x1F

A sample is a run of 8-bit signed mono samples, one byte per sample, with a native rate of 32,000 Hz. Samples are read straight from memory, usually ROM. Playback uses linear interpolation.

OffsetField
+0x14Start address: where playback begins when a note starts
+0x17End address: the address just after the last sample. Playback stops here unless the loop flag is set.
+0x1ALoop start address
+0x1DLoop end address: the address just after the last looped sample

When the loop flag is set, playback jumps back to the loop start whenever it reaches the loop end, and the end address is not used. Samples can have an intro before the loop start.

Global Block

The global block holds settings for the whole mix. It lives right after the channel table (see I/O Layout).

OffsetSizeFieldMeaning
+0x001 byteMaster volume0 (silent) to 255 (full)
+0x011 byteReverb returnHow loud the reverb is in the mix, 0 to 255
+0x021 byteReverb decayHow long the reverb lasts, 0 (shortest) to 255 (longest)
+0x031 byteChorus returnHow loud the chorus is in the mix, 0 to 255
+0x041 byteChorus rateSpeed of the chorus, in the same units as the vibrato rate (value divided by 16, in Hz)
+0x051 byteChorus depthAmount of the chorus, 0 (none) to 255 (most)
+0x061 byteDelay returnHow loud the delay is in the mix, 0 to 255
+0x071 byteDelay timeTime between echoes, in units of 5 milliseconds (up to 1.275 seconds)
+0x081 byteDelay feedbackHow much of each echo is fed back into the delay, as the value divided by 256
+0x097 bytesReserved

Since zeroed memory has a master volume of 0, a game has to set the master volume before it will hear anything.

Warning

The exact algorithms behind the reverb, chorus and delay are purposely left undefined for now. Only their settings are defined here.

I/O Layout

Note

This page is currently a stub and needs more detail.

Where I/O starts is defined in the memory map. Each device gets a slot of 0x1000 bytes, so a device can grow without the others having to move.

OffsetSizeContents
+0x00000x80Controller table
+0x10000x400Audio channel table
+0x14000x10Global audio block

Controller Table

8 controller entries of 16 bytes each, for a total of 128 bytes. Controller N lives at i/o start + N * 16.

Audio

16 audio channel entries of 64 bytes each, for a total of 1 KB. Channel N lives at i/o start + 0x1000 + N * 0x40.

The global audio block is 16 bytes and lives right after the channel table, at i/o start + 0x1400.

Note

Below this point are planned features. None of these have been expanded on yet.

System Status

  • Vblank flag
  • Current scanline
  • Free-running frame counter

Interrupt control

  • Enable and status bits for vblank and scanline.
  • A scanline compare value.

Save memory

  • A small region of RAM is dedicated to save data, and is kept between sessions. Its place in memory is in the Memory Map.
  • Game ID used in the header, emulator uses the game id to help name the save file.
  • Emulator writes the save data to a file.

Debug port

  • A byte you write to prints a character in the emulator’s terminal, plus an assert or breakpoint register.

RNG

  • A register that returns the next value of a seeded generator, with a writable seed.

Timers

  • Countdowns that aren’t tied to frames.

Real-time clock

  • Host date and time.

Rust Assembler

Note

This page is currently a stub and needs more detail.

  • Header manager
  • Music tools
  • Sound tools
  • Fonts
  • Meta sprite manager
  • Save utils

License

Starfrootle uses different licenses for different parts of the project.

PartLicense
This documentationMIT
The emulator and the assemblerGPL-3.0-or-later
The boot ROM sourceGPL-3.0-or-later
The standard library, and anything else that is included inside gamesMIT-0

Games

Games made for Starfrootle belong to their authors. They can be sold, and they don’t have to be open source. Running a game on the emulator does not put the game under the GPL.

The standard library is under the MIT-0 license, which has no credit or notice requirement. A game that includes standard library code does not owe Starfrootle any credit. Credit is always appreciated, but it is never required.

Documentation

This documentation is under the MIT license. You may use it, copy it, change it and sell it, as long as the copyright notice and the permission notice stay with it.

The license files for the rest of the project are in the repository.

MIT License

Copyright (c) 2026 DogeisCut

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.