Cart-Forth reference

Cart-Forth is a small Forth subset compiled to spriteCart's stack-VM bytecode. Words are whitespace-separated; data flows through a single 16-bit signed stack. For the language-level view — what's in, what's cut from standard Forth, and the gotchas — see the cart-Forth subset page.

Stack primitives

Word	Stack effect	Summary
`dup`	`( a -- a a )`	Duplicate top of stack.
`drop`	`( a -- )`	Discard top of stack.
`swap`	`( a b -- b a )`	Swap top two cells.
`over`	`( a b -- a b a )`	Copy second cell to top.
`rot`	`( a b c -- b c a )`	Rotate top three cells.
`nip`	`( a b -- b )`	Discard second cell.
`tuck`	`( a b -- b a b )`	Copy top below second.
`pick`	`( xn ... x0 n -- xn ... x0 xn )`	Copy the nth cell from the top (0-indexed) to the top; 0 pick = dup, 1 pick = over.
`2dup`	`( a b -- a b a b )`	Duplicate the top cell pair (equivalent to `over over`).
`+`	`( a b -- a+b )`	Add.
`-`	`( a b -- a-b )`	Subtract.
`*`	`( a b -- a*b )`	Multiply.
`/`	`( a b -- a/b )`	Divide (signed; division by zero traps).
`mod`	`( a b -- a%b )`	Modulo.
`/mod`	`( a b -- a%b a/b )`	Push modulus then quotient (both signed).
`negate`	`( a -- -a )`	Two's complement negation.
`abs`	`( a -- \|a\| )`	Absolute value.
`min`	`( a b -- min )`	Minimum (signed).
`max`	`( a b -- max )`	Maximum (signed).
`=`	`( a b -- flag )`	Push -1 if equal, else 0.
`<>`	`( a b -- flag )`	Push -1 if not equal, else 0.
`<`	`( a b -- flag )`	Push -1 if a < b (signed), else 0.
`>`	`( a b -- flag )`	Push -1 if a > b (signed), else 0.
`<=`	`( a b -- flag )`	Push -1 if a ≤ b (signed), else 0.
`>=`	`( a b -- flag )`	Push -1 if a ≥ b (signed), else 0.
`and`	`( a b -- a&b )`	Bitwise AND.
`or`	`( a b -- a\|b )`	Bitwise OR.
`xor`	`( a b -- a^b )`	Bitwise XOR.
`invert`	`( a -- ~a )`	Bitwise NOT.
`lshift`	`( a n -- a<<n )`	Logical left shift by n bits (shift count masked to 4 bits).
`rshift`	`( a n -- a>>n )`	Logical right shift by n bits (unsigned; shift count masked to 4 bits).
`@`	`( addr -- v )`	Fetch cell at addr.
`!`	`( v addr -- )`	Store v at addr.
`c@`	`( addr -- byte )`	Fetch byte at addr.
`c!`	`( byte addr -- )`	Store byte at addr.
`+!`	`( v addr -- )`	Add v to the cell at addr (fetch, add, store).

Defining words

Word	Stack effect	Summary
`:`	`( -- )`	Begin a colon-definition; ends with `;`.
`;`	`( -- )`	End a colon-definition.
`variable`	`( -- )`	Define a 1-cell variable; the new word pushes its address.
`constant`	`( v -- )`	Define a constant; the new word pushes `v`.

Control flow

Word	Stack effect	Summary
`if`	`( flag -- )`	Begin a conditional. Paired with `else` (optional) and `then`.
`else`	`( -- )`	Else branch of an `if`.
`then`	`( -- )`	End an `if` (no relation to other Forths' postfix-then).
`begin`	`( -- )`	Top of a `begin … until` loop.
`until`	`( flag -- )`	Loop back to `begin` while flag is 0; exit when non-zero.
`do`	`( limit start -- )`	Begin a counted loop body; `i` accesses the index.
`loop`	`( -- )`	End a `do` loop; increments index by 1.
`i`	`( -- i )`	Push the current `do` loop index.
`exit`	`( -- )`	Return early from the enclosing colon-definition.

Literals

Word	Stack effect	Summary
`s"`	`( -- addr len )`	String literal: pushes (RAM address, byte length).
`."`	`( -- )`	Not yet implemented — use `s" ..." print` for now.

Host words

Host words compile to a single HCALL <id> instruction. The full HCALL wire reference (with hex ids) lives at /docs/hcalls.

Word	Stack effect	Summary
`cls`	`( c -- )`	Clear the screen to color index `c`.
`pixel`	`( x y c -- )`	Set pixel at (x,y) to color index `c`.
`sprite`	`( tile x y flags -- )`	Draw sprite `tile` at (x,y). `flags` bits: 1=hflip, 2=vflip, 4=wrap. Color 0 in the tile is transparent.
`rect`	`( x y w h c -- )`	Draw filled w×h rectangle at (x,y) in color `c`.
`line`	`( x0 y0 x1 y1 c -- )`	Draw a line from (x0,y0) to (x1,y1) in color `c`.
`print`	`( x y c addr len -- )`	Render text from RAM at (x,y) in color `c` using the 4×6 font; `\n` advances to a new line.
`camera`	`( x y -- )`	Set the camera offset (subtracted from draw coords).
`clip`	`( x y w h -- )`	Set the clipping rectangle for subsequent draws.
`blit`	`( sheet sx sy w h dx dy flags -- )`	GameTank only: copy a w×h rect from sprite sheet `sheet` at (sx,sy) to the framebuffer at (dx,dy). `flags` bits: 1=hflip, 2=vflip, 4=transparent (color 0 skipped), 8=fill (paint `sx` as a solid color instead of reading the sheet).
`note!`	`( pitch instrument voice -- )`	Trigger MIDI `pitch` on `voice` using `instrument`'s ADSR.
`mute!`	`( voice -- )`	Silence `voice` immediately (no release ramp).
`play-music`	`( pattern -- )`	Start the music slot on `pattern`, looping. Stops any music already playing; SFX slots are unaffected.
`play-pattern`	`( pattern -- )`	Alias for `play-music` (the canonical name as of P5.2). Pre-P5.2 carts using `play-pattern` keep working unchanged.
`play-once`	`( pattern -- )`	Fire a one-shot pattern on an auto-allocated SFX slot. As of P5.2 this overlays on music instead of cutting it. Equivalent to passing pattern + -1 to `play-sfx` (e.g. `2 -1 play-sfx`).
`play-sfx`	`( pattern slot -- )`	Fire a one-shot SFX pattern. `slot` is 0..=3 to target a specific slot or `-1` to auto-allocate (first idle; else evict the oldest).
`loop-sfx`	`( pattern slot -- )`	Looping SFX pattern (drones, ambient atmos). Same slot semantics as `play-sfx`; the only difference is it loops until you `stop-sfx` it.
`stop-music`	`( -- )`	Stop the music slot only. SFX slots keep playing.
`stop-sfx`	`( slot -- )`	Stop one SFX slot (0..=3) or all SFX (`-1`). Music slot unaffected.
`set-bpm`	`( frames-per-row -- )`	Set the music slot's tempo (frames per row, 2..=64). Takes effect at the next row boundary. No-op when music is stopped; never affects SFX slots.
`btn`	`( id -- flag )`	Push -1 if button `id` is held this frame, else 0.
`btnp`	`( id -- flag )`	Push -1 if button `id` was pressed this frame (rising edge), else 0.