PROTOCOL

Streams ASCII text directly at the current cursor offset using the active default foreground color. The stream terminates as soon as a Carriage Return (`$0D`) or Line Feed (`$0A`) is parsed. Letters are dynamically converted from ASCII to native C64 screen codes on-the-fly.

// Example: Write "RIFT64 ACTIVE" and wrap cursor
!RIFT64 ACTIVE<CR>

A high-speed shortcut command that updates the position of one or more sprites without altering pointers, colors, or other configurations. `MM` is an 8-bit mask whose set bits select which of the 8 sprites are being updated; the client then reads one 6-hex-digit `XHXLYY` block per set bit, in ascending sprite-ID order. `XH` carries the X-MSB bit (used when X > 255), `XL` is the low byte of X, and `YY` is the Y coordinate.

// Example: Move Sprite 0 to (X=300, Y=150) and Sprite 2 to (X=80, Y=200)
// Mask = %00000101 = $05; entries follow in ID order (0, then 2)
@05 012C96 0050C8

Invokes a framed, checksum-verified packet. `C` is a one-byte framed command ID (e.g. `L` for length text, `C` for clear). `LL` is the payload length. `SS` is an additive checksum calculated over the entire packet: `SS = (C + LL + sum(data)) & $FF`.

// Example: Send a framed text packet with checksum verification
~L13FRAMED TEXT PAYLOAD5F

Instructs the Commodore 64 client to write its features/capabilities string back upstream. Useful on connection handshakes to detect compatibility and the set of supported command opcodes. The C64 client immediately streams back a CR-terminated response listing the supported command letters, terminated by an `ACK` token: RIFT64 CKPLQXZ~FIDY@UGHNA ACK<CR>.

// Example: Send query to the C64
?

Drives the resident SID music-module player. The first byte `S` is an ASCII subcommand digit selecting the operation; remaining hex bytes are subcommand-specific arguments. Most subcommands return `A` (ACK) on success or `N` (NAK) on failure; A7 returns a single state byte instead.

// Example: Bind a music module previously uploaded to $C000, then start subtune 1
A500C0
A101

Automatically draws a rectangular border outline on the C64 screen starting from the current cursor coordinates. `WW` is the width, and `HH` is the height. The 9-byte configuration payload contains the raw C64 character codes representing corners and vertical/horizontal bars.

// Example: Draw a 10x10 border outline using custom corners and line characters
B0A0A[9 bytes of layout config]

Clears the 40x25 character matrix back to spaces (`$20`), resets the cursor position to column 0, row 0, and hides the hardware cursor. To avoid a jarring visual flash, the border and background colors are preserved during this clear step.

// Example: Clears screen instantly
C

Renders a rectangular window of a tile-id map into screen RAM in a single round-trip. Supports three tile modes (1 = raw 1×1 char, 2 = 2×2 metatiles, 3 = 3×3 metatiles), arbitrary target stride, sub-tile scroll offsets (offX/offY) for smooth scrolling, an edge fill character, and a configurable colour-RAM pass (cMode: 00=NONE, 01=FILL, 02=MAP, 03=PERCELL). PERCELL is mode-2 only and uses a 1 KB page-aligned bank of 4 parallel slot pages, indexed by tile id, giving a distinct colour to each child cell of every metatile (mode 3 transparently falls back to MAP). The renderer ACKs with A after the entire window is drawn. See the metatile guide for the full payload layout and SDK helper.

// Payload (each field is one hex pair):
// mode mapLo mapHi mapW mapH metaHi tgtLo tgtHi stride winW winH x y offX offY fill cMode cTgtLo cTgtHi cSrcLo cSrcHi cFill
D[20 hex bytes]

Writes exactly `LL` spaces (`$20`) starting from the current cursor offset. When complete, the cursor position automatically restores to its starting offset. Ideal for erasing lines, status displays, or rendering clear space runs.

// Example: Erase 40 ($28) cells (a full row) from current cursor
E28

Alters the active VIC-II bank and character memory offset mapping. Allows developers to toggle live between uppercase, lowercase, and custom uploaded fonts/tile matrices. The client responds with `A` (ACK) after register swapping.

// Example: Switch charset bank register offsets
F[Hex Nibble + Hex Byte]

Executes hardware subregion shifting of width `WW` and height `HH` from coordinate `XXYY`. Direction `D` controls the shift: `0` Up, `1` Down, `2` Left, `3` Right. Shshifted lines automatically preserve color RAM values. Newly exposed row/column slots are cleared to spaces using the default background/foreground colors.

// Example: Scroll a 40x10 region from column 0, row 5 upwards
G0005280A0

Controls whether the C64 client actively renders and flashes the text cursor. Hiding the cursor (`H0`) is highly recommended during game loops or graphic rendering to prevent visual glitches. Show the cursor (`H1`) when waiting for text inputs.

// Example: Hide the cursor
H0

Switches the active VIC-II graphics mode. Allows the host to switch the screen from standard text mode into multicolor bitmap, standard bitmap, or extended color modes. Returns `A` (ACK) on successful transition.

// Example: Set screen to Multicolor Bitmap Mode
I[Mode parameters]

Controls the upstream telemetry generator. The first byte `S` is an ASCII subcommand digit. J1 additionally takes a 1-byte hex divider DD (frames between sends) and a 1-byte hex channel mask MM selecting which hardware sources to sample.

// Example: Enable telemetry every 3 frames, sampling both joysticks + sprite collisions
J1030F

Sets the background and border color registers to the hex color value `B`, and sets the default text foreground write color to `F`. Both `B` and `F` must be lowercase or uppercase hex digits (0-F).

// Example: Set background/border to Black ($00), and foreground to White ($01)
K01

Writes exactly `LL` bytes of text. Safe for streaming raw strings containing control characters, escape sequences, or binary formatting bytes that would prematurely terminate a standard `!` command. The client returns `A` (ACK) once the exact byte length is consumed.

// Example: Write exactly 12 ($0C) bytes of raw text
L0CHELLO WORLD

Writes binary bytes directly to C64 RAM starting at destination address `AAAA` for length `LL` (where `00` represents 256 bytes). This is highly powerful, allowing you to stream custom sprite bitmaps, font banks, or raw 6502 Machine Language code directly to the C64.

// Example: Upload 64 ($40) bytes of sprite data to $3E00
M3E0040[64 bytes of raw sprite binary]

Configures a horizontal raster split line. Highly advanced, this enables split-screen graphics—for example, rendering a full-color bitmap image at the top of the screen while preserving a standard character text terminal at the bottom! Returns `A` (ACK) on completion.

// Example: Configure a raster split at horizontal line 150
N[Split parameters]

Signals a custom, client-side visual restoration routine. Used to return from heavy custom graphics or raster split interfaces back to standard boot screen matrices.

// Example: Invoke client custom restore
O

Positions the hardware cursor on the screen. `XX` represents the column offset (clamped to 0-39) and `YY` represents the row offset (clamped to 0-24). Decoding is performed on the C64 dynamically to calculate the absolute RAM writing index.

// Example: Move the cursor to Column 10 ($0A), Row 5 ($05)
P0A05

Directly updates the color RAM matrix for a rectangular region of width `WW` and height `HH` from coordinate `XXYY` without changing any text character codes on the screen. Each color is a single low-nibble byte. Returns `A` (ACK) on completion.

// Example: Paint a 10x2 block at (2, 5) with custom colors
Q02050A02[20 color bytes]

Restores the complete 1000-character screen and color RAM grids back from one of the off-screen backup slots (0 or 1) on the C64. This is extremely fast (virtually instantaneous), allowing you to draw temporary popups, overlay menus, or dialogs, and then dismiss them instantly without stream overhead!

// Example: Restore the screen from Slot 0
R0

Saves the entire current screen RAM (`$0400-$07E7`) and color RAM (`$D800-$DBE7`) matrices into a local backup buffer slot (0 or 1) residing in upper C64 RAM. Essential for preserving the screen state before loading overlays or menus.

// Example: Save screen to Slot 0
S0

Sets the active default foreground text color to `F` (low nibble), then writes the text exactly like the `!` write text command. Terminated by a Carriage Return or Line Feed.

// Example: Write "ONLINE" in Cyan ($03) text
T3ONLINE<CR>

Configures the VIC-II's sprite multicolor state. Allows you to toggle individual sprites between standard (high resolution, 1 color) and multicolor (lower resolution, 4 colors) modes, and configure the two shared multicolor registers (`$D025` and `$D026`).

// Example: Configure sprite multicolor registers
U[Multicolor registers]

Sets the active default foreground text color to `F` (low nibble), then writes a window block exactly like the standard `W` draw window command.

// Example: Draw a 10x2 window in Orange ($08) foreground
V80A02[20 bytes of raw data]

Writes a rectangular grid of raw characters of width `WW` and height `HH`. The current cursor position forms the top-left boundary of the window. After each row of size `WW` is written, the cursor position dynamically resets to the starting column and advances down by one row, allowing rapid batch painting.

// Example: Render a 4x2 ($0402) block of filled blocks (8 bytes)
W0402[8 bytes of raw data]

Buffered window block render verified by an 8-bit additive checksum `SS`. The C64 client reads the incoming character stream first into an internal, 256-byte staging buffer named `MemoryStoreBuffer` (located in the client's memory copying module, memory_store.asm). It then validates the checksum. If the checksum matches, the block is dynamically copied row-by-row to the screen matrix; if it fails, the C64 drops the data and returns `N` (NAK).

// Example: Write a verified 4x2 window with checksum (8 bytes + 1 checksum byte)
X0402[8 bytes of raw data]5A

Configures one of the 8 built-in C64 hardware sprites. `II` selects the sprite ID (0-7). `XH` handles the Sprite X-MSB bit (controls if X is > 255). `XL` is the X position (0-255). `YY` is the Y position. `CC` controls the sprite color. `PP` is the sprite memory block pointer (relative to VIC Bank). `BB` controls the active 16KB VIC bank. `EE` toggles the sprite's enable status (`00` is off, `01` is on).

// Example: Enable Sprite 0 at X=150, Y=120, Color Green ($05), Pointer $3E
Y00009678053E0301

Identical to the `M` memory copy command, but validated via an 8-bit additive checksum `SS`. If the checksum fails, the write is aborted, and `N` is returned, preventing code or memory corruption in noisy serial environments.

// Example: Upload checked binary blocks to RAM (64 bytes + 1 checksum byte)
Z3E0040[64 bytes of raw sprite binary]AF