Introduction
Note
This page is currently a stub and needs more detail.
Starfrootle is a fantasy console written in Rust.
Specifications
| Address space | 16 MB (24-bit addresses, 0x000000 to 0xFFFFFF) |
| Screen | 240x240 (30 tiles across, 30 tiles vertically) |
| Tile and sprite size | 8x8 |
| Tile layers | 5 (each with a 64x64 tile map) |
| Sprites | 128 |
| Palettes | 16 (16 colors each) |
| Controllers | 8 |
| Audio | 16 channels, 48,000 Hz stereo output |
Conventions
- Big-endian. Multi-byte values are written most significant byte first. An address of
C0 00 00is0xC00000. - 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 is4and the low nybble is7). - 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, likeC0 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.
| Start | Region | Notes |
|---|---|---|
0x000000 | RAM | |
0x200000 | VRAM | See VRAM Layout |
0x220000 | I/O | See I/O Layout |
0x230000 | Boot ROM | See Boot ROM. Read-only |
0x240000 | Save RAM | Kept between sessions. See Save memory |
0x250000 | ROM | See 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
| Register | Size | Notes |
|---|---|---|
| General purpose (16) | 8 bits each | Numbered 0 to F, so a register fits in one nybble |
| Program counter | 24 bits | Address of the next byte to read |
| Stack pointer | 24 bits | Pushed big-endian |
| Flags | 8 bits | See below |
Flags
| Bit | Flag |
|---|---|
0 | Zero |
1 | Carry |
2 | Negative |
3 | Overflow |
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 nybble | Group |
|---|---|
0x | System |
1x | Loads and stores |
2x | Moves, pushes and pops |
3x | Arithmetic |
4x | Logic and shifts |
5x | Bit operations (planned) |
6x | Comparisons |
7x | Jumps and branches |
8x | Calls and returns |
9x | Block operations (planned) |
Defined opcodes
| Opcode | Name | Operands | Bytes | Flags | Effect |
|---|---|---|---|---|---|
00 | NoOp | none | 1 | none | do nothing |
01 | Halt | none | 1 | none | stop the CPU |
10 | LoadConst | D_ value | 3 | none | register = value |
11 | LoadMem | D_ address | 5 | none | register = byte at address |
12 | StoreMem | S_ address | 5 | none | byte at address = register |
13 | LoadIndirect | DS | 2 | none | D = byte at address at S, S+1, S+2 |
14 | StoreIndirect | DS | 2 | none | byte at address at D, D+1, D+2 = S |
20 | Copy | DS | 2 | none | D = S |
21 | Swap | DS | 2 | none | exchange D and S |
22 | Push | S_ | 2 | none | push register onto the stack |
23 | Pop | D_ | 2 | none | pop the stack into register |
30 | Add | DS | 2 | Z C N V | D = D + S |
31 | Sub | DS | 2 | Z C N V | D = D - S |
32 | Inc | D_ | 2 | Z N V | D = D + 1 |
33 | Dec | D_ | 2 | Z N V | D = D - 1 |
40 | And | DS | 2 | Z N | D = D & S |
41 | Or | DS | 2 | Z N | D = D | S |
42 | Xor | DS | 2 | Z N | D = D ^ S |
43 | Not | D_ | 2 | Z N | D = ~D |
44 | ShiftLeft | Dn | 2 | Z C N | D <<= n |
45 | ShiftRight | Dn | 2 | Z C N | D >>= n |
60 | Compare | DS | 2 | Z C N V | computes D - S, only sets flags |
70 | Jump | address | 4 | none | PC = address |
71 | JumpIfZero | address | 4 | none | jump if Z set |
72 | JumpIfNotZero | address | 4 | none | jump if Z clear |
73 | JumpIfCarry | address | 4 | none | jump if C set |
74 | JumpIfNoCarry | address | 4 | none | jump if C clear |
75 | JumpIfNegative | address | 4 | none | jump if N set |
76 | JumpIndirect | address | 4 | none | PC = the 3-byte address stored at address |
80 | Call | address | 4 | none | push return address (3 bytes), jump |
81 | Return | none | 1 | none | pop PC |
82 | CallIndirect | address | 4 | none | push 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.
| Offset | Size | Field |
|---|---|---|
+0x00 | 4 bytes | Magic Number (53 54 52 4C STRL) |
+0x04 | 1 byte | Format version (0x00 Currently) |
+0x05 | 8 bytes | Unique Game ID |
+0x0D | 3 bytes | Reserved |
+0x10 | 4 bytes | Reset vector |
+0x14 | 4 bytes | VBlank vector |
+0x18 | 4 bytes | Scanline vector |
+0x1C | 36 bytes | Reserved for future vectors |
+0x40 | rest | Code 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
- The emulator loads the boot ROM file into the boot ROM region, and copies the game file into the ROM region.
- RAM, VRAM and I/O start out zeroed.
- The CPU starts running the boot ROM.
- 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.
- The boot ROM puts the console into a clean state.
- The boot ROM starts the game by jumping to the game’s reset vector, using
JumpIndirecton the reset vector atrom 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:
| Step | Drawn |
|---|---|
| 1 | Background color |
| 2 | Sprites with layer offset 9 |
| 3 | Tile layer 4 |
| 4 | Sprites with layer offset 8, then 7 |
| 5 | Tile layer 3 |
| 6 | Sprites with layer offset 6, then 5 |
| 7 | Tile layer 2 |
| 8 | Sprites with layer offset 4, then 3 |
| 9 | Tile layer 1 |
| 10 | Sprites with layer offset 2, then 1 |
| 11 | Tile layer 0 |
| 12 | Sprites 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.
| Offset | Size | Used | Contents |
|---|---|---|---|
+0x00000 | 0x1000 | 0x400 | Sprite table |
+0x01000 | 0x1000 | 0x30 | Background color, Screen Brightness, and layer registers |
+0x02000 | 0x2000 | 0x300 | Palettes |
+0x04000 | 0x4000 | 0x4000 | Tile map for layer 0 |
+0x08000 | 0x4000 | 0x4000 | Tile map for layer 1 |
+0x0C000 | 0x4000 | 0x4000 | Tile map for layer 2 |
+0x10000 | 0x4000 | 0x4000 | Tile map for layer 3 |
+0x14000 | 0x4000 | 0x4000 | Tile map for layer 4 |
+0x18000 | 0x8000 | 0 | Reserved |
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:
| Offset | Size | Field |
|---|---|---|
+0 | 3 bytes | Image address |
+3 | 1 byte | Palette (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:
| Offset | Size | Field |
|---|---|---|
+0 | 1 byte | Scroll X |
+1 | 1 byte | Scroll Y |
+2 | 1 byte | Blend mode (see Blending) |
+3 | 1 byte | Flags |
+4 | 4 bytes | Reserved |
The address of each layer’s registers is in VRAM Layout.
Flags
Offset +3
| Bit | Flag |
|---|---|
0 | Enabled: 1 means the layer is drawn, 0 means the layer is skipped |
1 to 7 | Reserved |
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
| Offset | Size | Field |
|---|---|---|
+0 | 3 bytes | Image address |
+3 | 1 byte | Palette (high nybble), Transform (low nybble) |
+4 | 1 byte | Layer offset (high nybble), Blend mode (low nybble) |
+5 | 2 bytes | X and Y position |
+7 | 1 byte | Reserved |
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 nybble | Low nybble |
|---|---|
| Palette | Transform |
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.
| Value | Sprite is drawn… |
|---|---|
0 | In front of tile layer 0 |
1 | Behind tile layer 0 |
2 | In front of tile layer 1, behind anything on layer 0 |
3 | Behind tile layer 1 |
4 | In front of tile layer 2, behind anything on layer 1 |
5 | Behind tile layer 2 |
6 | In front of tile layer 3, behind anything on layer 2 |
7 | Behind tile layer 3 |
8 | In front of tile layer 4, behind anything on layer 3 |
9 | Behind 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:
| Field | Value |
|---|---|
| Image address | 0xC00000 |
| Palette | 4 |
| Transform | 7 (horizontally flipped, then 270 degrees clockwise) |
| Layer offset | 4 (in front of tile layer 2, behind anything on layer 1) |
| Blend mode | 0 (Normal) |
| X | 0xFF (255) |
| Y | 0xFF (255) |
| Reserved | 0x00 (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.
| Offset | Row |
|---|---|
+0 to +3 | Row 0 (top) |
+4 to +7 | Row 1 |
+8 to +11 | Row 2 |
+12 to +15 | Row 3 |
+16 to +19 | Row 4 |
+20 to +23 | Row 5 |
+24 to +27 | Row 6 |
+28 to +31 | Row 7 (bottom) |
Within a row:
| Byte | +0 | +1 | +2 | +3 |
|---|---|---|---|---|
| Pixels (left to right) | high, low | high, low | high, low | high, low |
| Columns | 0, 1 | 2, 3 | 4, 5 | 6, 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:
| Value | Transformation |
|---|---|
0 | No rotation |
1 | 90 degrees (clockwise) |
2 | 180 degrees (clockwise) |
3 | 270 degrees (clockwise) |
4 | Horizontally flipped, no rotation |
5 | Horizontally flipped, then 90 degrees (clockwise) |
6 | Horizontally flipped, then 180 degrees (clockwise) |
7 | Horizontally 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
| Value | Mode | Sprites | Tile layers |
|---|---|---|---|
0 | Normal | Yes | Yes |
1 | Add | Yes | Yes |
2 | Multiply | Yes | Yes |
3 | Invert | Yes | Yes |
4 | Clip | Yes | No |
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
+4of their sprite entry. - Tile layers store a blend mode in offset
+2of 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
| Offset | Size | Field |
|---|---|---|
+0 low nybble | Face buttons: South, East, West, North (bits 0 to 3) | |
+0 high nybble | 1 byte | Start, Select, Left stick click, Right stick click |
+1 low nybble | D-pad: Up, Down, Left, Right | |
+1 high nybble | 1 byte | Left bumper, right bumper, left trigger (digital), right trigger (digital) |
+2 | 1 byte | Left stick X |
+3 | 1 byte | Left stick Y |
+4 | 1 byte | Right stick X |
+5 | 1 byte | Right stick Y |
+6 | 1 byte | Left trigger |
+7 | 1 byte | Right trigger |
+8 | 1 byte | Battery |
+9 | 1 byte | Flags |
+10 | 6 bytes | Reserved |
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
| Bit | Flag |
|---|---|
0 | Controller connected |
1 | Controller uses battery |
2 to 7 | Reserved |
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:
- Source: a generated wave, noise, or a sample.
- Filter: a low-pass filter (only if the filter is enabled).
- Envelope and volume: the envelope shapes the volume over time (only if the envelope is enabled).
- Effect sends: a part of the signal is sent to the global reverb, chorus and delay.
- 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
| Offset | Size | Field |
|---|---|---|
+0x00 | 1 byte | Flags |
+0x01 | 1 byte | Source |
+0x02 | 1 byte | Variant |
+0x03 | 1 byte | Volume |
+0x04 | 1 byte | Pan (signed) |
+0x05 | 2 bytes | Pitch |
+0x07 | 1 byte | Envelope: attack |
+0x08 | 1 byte | Envelope: decay |
+0x09 | 1 byte | Envelope: sustain level |
+0x0A | 1 byte | Envelope: release |
+0x0B | 1 byte | Vibrato: rate |
+0x0C | 1 byte | Vibrato: depth |
+0x0D | 1 byte | Vibrato: shape |
+0x0E | 1 byte | Filter: cutoff |
+0x0F | 1 byte | Filter: peak |
+0x10 | 1 byte | Reverb send |
+0x11 | 1 byte | Chorus send |
+0x12 | 1 byte | Delay send |
+0x13 | 1 byte | Reserved |
+0x14 | 3 bytes | Sample start address |
+0x17 | 3 bytes | Sample end address |
+0x1A | 3 bytes | Sample loop start address |
+0x1D | 3 bytes | Sample loop end address |
+0x20 | 32 bytes | Reserved |
Flags
Offset +0x00
| Bit | Flag |
|---|---|
0 | Gate: a note starts when this changes from 0 to 1, and is released when it changes from 1 to 0 |
1 | Loop (samples only) |
2 | Envelope enabled |
3 | Filter enabled |
4 | Active (read only): 1 while the channel is making sound. The console sets and clears this bit, and writes to it are ignored. |
5 to 7 | Reserved |
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
| Source | Sound |
|---|---|
0 | Pulse |
1 | Triangle |
2 | Saw |
3 | Sine |
4 | Noise |
5 | Sample |
Values above 5 are not yet defined.
The variant changes how some sources sound, and is ignored by the others:
| Source | Variant |
|---|---|
| Pulse | Duty cycle: the fraction of each wave that is high, as the value divided by 256 (0x80 is 50%, 0x40 is 25%) |
| Noise | 0 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:
| Note | Pitch | Note | Pitch |
|---|---|---|---|
| C-5 | 0x1000 | F#-5 | 0x16A1 |
| C#-5 | 0x10F4 | G-5 | 0x17F9 |
| D-5 | 0x11F6 | G#-5 | 0x1966 |
| D#-5 | 0x1307 | A-5 | 0x1AE9 |
| E-5 | 0x1429 | A#-5 | 0x1C82 |
| F-5 | 0x155C | B-5 | 0x1E34 |
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.
| Offset | Field | Meaning |
|---|---|---|
+0x07 | Attack | Frames to rise from silence to full volume |
+0x08 | Decay | Frames to fall from full volume to the sustain level |
+0x09 | Sustain level | The level held while the gate is 1, from 0 (silent) to 255 (full) |
+0x0A | Release | Frames 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.
| Offset | Field | Meaning |
|---|---|---|
+0x0B | Rate | Cycles per second, as the value divided by 16 (0x60 is 6 Hz) |
+0x0C | Depth | The 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. |
+0x0D | Shape | 0 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.
| Offset | Field | Meaning |
|---|---|---|
+0x0E | Cutoff | Cutoff frequency, from 20 Hz at 0 rising exponentially to about 20 kHz at 255. The frequency is 20 Hz × 2^(value / 25.5). |
+0x0F | Peak | Resonance 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.
| Offset | Field |
|---|---|
+0x14 | Start address: where playback begins when a note starts |
+0x17 | End address: the address just after the last sample. Playback stops here unless the loop flag is set. |
+0x1A | Loop start address |
+0x1D | Loop 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).
| Offset | Size | Field | Meaning |
|---|---|---|---|
+0x00 | 1 byte | Master volume | 0 (silent) to 255 (full) |
+0x01 | 1 byte | Reverb return | How loud the reverb is in the mix, 0 to 255 |
+0x02 | 1 byte | Reverb decay | How long the reverb lasts, 0 (shortest) to 255 (longest) |
+0x03 | 1 byte | Chorus return | How loud the chorus is in the mix, 0 to 255 |
+0x04 | 1 byte | Chorus rate | Speed of the chorus, in the same units as the vibrato rate (value divided by 16, in Hz) |
+0x05 | 1 byte | Chorus depth | Amount of the chorus, 0 (none) to 255 (most) |
+0x06 | 1 byte | Delay return | How loud the delay is in the mix, 0 to 255 |
+0x07 | 1 byte | Delay time | Time between echoes, in units of 5 milliseconds (up to 1.275 seconds) |
+0x08 | 1 byte | Delay feedback | How much of each echo is fed back into the delay, as the value divided by 256 |
+0x09 | 7 bytes | Reserved |
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.
| Offset | Size | Contents |
|---|---|---|
+0x0000 | 0x80 | Controller table |
+0x1000 | 0x400 | Audio channel table |
+0x1400 | 0x10 | Global 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.
| Part | License |
|---|---|
| This documentation | MIT |
| The emulator and the assembler | GPL-3.0-or-later |
| The boot ROM source | GPL-3.0-or-later |
| The standard library, and anything else that is included inside games | MIT-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.