Parrot Cart developersGet a Parrot Cart

The simulator

The simulator runs your plugin on your computer in a window, with sound and controls. It builds your plugin’s C files for your computer against models of the console and the cart, the same models test/run.sh uses. Then you play it with the keyboard or a game pad.

sim/run.sh src                       # the template's plugin
sim/run.sh examples/sound            # an example
sim/run.sh src --card ~/sdcard       # with a folder as the SD card
sim/run.sh src --usb host            # USB pads, a keyboard and a mouse on the cart

The first build takes a few seconds, and after that only what changed is built again, so it’s a quick way to try ideas. Before you release your plugin, try it on a real console too (see “What the simulator can’t show you” below).

1. Install SDL3

The simulator needs CMake, a C compiler, and SDL3 (3.2 or later).

macOS, with Homebrew:

brew install sdl3 cmake ninja

On Linux, Ubuntu 25.04 and later and Debian 13 have SDL3:

sudo apt install libsdl3-dev cmake ninja-build build-essential libasound2-dev

Older versions (Ubuntu 24.04, Debian 12) don’t. Install what SDL needs to build, then build SDL into the kit’s build-sim/sdl3. It takes a few minutes, and you only do it once:

sudo apt install cmake ninja-build build-essential libx11-dev libxext-dev \
    libwayland-dev libxkbcommon-dev libegl-dev libasound2-dev libpulse-dev libudev-dev
sim/get-sdl.sh

On Linux, libasound2-dev adds MIDI ports (section 4). Without it, the simulator still builds, but with no MIDI ports.

On Windows with Visual Studio 2022, use the “Desktop development with C++” workload, which includes CMake. In Git Bash, sim/get-sdl.sh puts the SDL team’s Windows build in build-sim\sdl3. You can also use vcpkg. Run vcpkg install sdl3, then set CMAKE_TOOLCHAIN_FILE to vcpkg’s scripts\buildsystems\vcpkg.cmake.

On Windows with MSYS2, in its UCRT64 shell:

pacman -S mingw-w64-ucrt-x86_64-sdl3 mingw-w64-ucrt-x86_64-cmake \
    mingw-w64-ucrt-x86_64-ninja mingw-w64-ucrt-x86_64-gcc

2. Run

sim/run.sh PLUGIN_DIR [options]

PLUGIN_DIR is the folder with your plugin’s .c and .cpp files. On Windows, sim\run.bat PLUGIN_DIR [options] does the same from the command prompt, and sim/run.sh works in Git Bash and MSYS2.

sim/run.sh src --help lists every option. These are the ones you’ll use most:

OptionWhat it does
--card FOLDERuses the folder as the SD card (section 5)
--open PATHstarts as if PATH had been picked in the cart’s menu (section 5)
--usb hostmakes the cart’s USB port a host, for pads, keyboards and mice (section 4)
--midi-in NAME, --midi-out NAMEchooses which MIDI ports the plugin uses (section 4)
--tvshows the TV’s shape, with a border and a 4:3 picture
--scale Nsets how many window pixels each console pixel takes (default 3)
--muteturns the sound off
--strictstops at the first rule the plugin breaks (section 6)
--shots DIRsets where F12 saves screenshots

If your plugin needs more files to build, give them before the simulator’s options:

sim/run.sh ../my-plugin/src --src '../vendor/lib/*.c' \
    --include ../my-plugin/vendor/lib --define USE_THIS=1

--src takes a file or pattern, relative to PLUGIN_DIR. --include adds a folder for #include, and --define adds a define. --no-sanitize builds without the memory checks (section 6), which makes it faster.

With sim\run.bat, or with your own build, use CMake directly:

cmake -S sim -B build-sim/myplugin -DPLUGIN_DIR=/path/to/my-plugin/src \
    "-DPLUGIN_SOURCES=../vendor/lib/*.c" -DPLUGIN_INCLUDES=/path/to/vendor/lib
cmake --build build-sim/myplugin --config Release
build-sim/myplugin/parrotsim --card ~/sdcard

3. Keys

KeyOn the console
arrows, or W A S Dthe controller’s stick
Z, Xits left and right fire buttons
0 to 9its keypad’s digits
- and =its keypad’s * and #

Any game pad works too. Its d-pad or left stick is the controller’s stick, its face buttons are the fire buttons, and Back and Start are * and #. Game pads are also the plugin’s USB pads (section 4).

KeyIn the simulator
F1lists the keys in the terminal
F2changes the keyboard’s role (below)
F5the console’s RESET
F12takes a screenshot
Escquits (so does closing the window)

F2 switches the keyboard between three roles:

  1. The controller (the default), with the keys above.
  2. USB pad 1, for a plugin that reads one when you don’t have a pad. The arrows are the d-pad, Z X A S are the face buttons (south, east, west, north), Q W are L and R, E R are ZL and ZR, Enter and Backspace are + and -, H is Home, and I J K L are the left stick.
  3. A USB keyboard and mouse. Every key goes to the plugin as if it came from a USB keyboard, and the mouse acts as a USB mouse (section 4). The window holds on to the mouse until you press F2 again. In this role, Esc goes to the plugin too, and only F1, F2, F5 and F12 still control the simulator.

The window’s title always shows the keyboard’s role. When the simulator starts, and after you press F2, a label in the bottom left corner of the window shows it for three seconds too.

F5 works like the console’s RESET. The plugin’s session ends, the simulator saves the plugin’s changes to the card, and the window shows the note your plugin left for the menu (cvk_note()). Press F5 or a fire button there to start the plugin again from the beginning, as a fresh program, or press Esc to quit.

4. USB: pads, a keyboard, a mouse, MIDI

A plugin turns on the cart’s USB features with cvcart_features() in its CMakeLists.txt (docs/features.md). The simulator reads that line and sets up the same features.

On the cart, the USB port is either a MIDI device on a computer or a host for a hub (cvusb_mode()). The simulator picks the same way the cart does. A plugin with MIDI_OUT finds a computer listening and becomes its MIDI device after 0.3 seconds. Any other plugin is a host. You can change that with --usb:

OptionOn the cart’s USB port
--usb devicea computer that is listening (the default)
--usb hosta hub and no computer, so the port becomes a host after 1.5 seconds
--usb aska computer that asks its user first, and gets no answer

Pads, keyboards and mice only reach a plugin whose port is a host. To try them with a plugin that has MIDI_OUT, start the simulator with --usb host. F2 reminds you of this in the terminal.

Game pads (PADS). The first two game pads are the plugin’s USB pads 1 and 2, with all their buttons and both sticks. cvusb_pad_kind() reports a Switch Pro Controller as SWITCH PRO and any other pad as HID PAD. As on the cart, a pad keeps its number until you unplug it. If you unplug pad 1, pad 2 is still pad 2, and the next pad you plug in becomes pad 1. A third pad isn’t used. Pad 1 is also the console’s controller, or pad 2 while there’s no pad 1.

A keyboard and a mouse (KEYBOARD, MOUSE). In F2’s third role, each key goes to the plugin the way a USB keyboard sends it. The SDK’s code reads it (cvusb_keys.c), so cvusb_key() gives the same usage, character and modifiers as on the cart. Keys don’t repeat, just like on a USB keyboard. The mouse moves, clicks and scrolls like a USB mouse. When you press F2 again, or the window loses focus, the plugin sees every key and button released.

MIDI (MIDI_IN, MIDI_OUT). The plugin’s MIDI goes to and from your computer’s MIDI ports, through CoreMIDI on macOS, ALSA on Linux and WinMM on Windows.

  • Out: on a computer, the cart is a MIDI device named after the plugin. On macOS and Linux, the simulator makes a MIDI port with the plugin’s name, and your music apps see it as an input and an output. What the plugin sends comes out of that port, and what the apps send to it reaches the plugin. Windows can’t make ports like that, so use --midi-out NAME to send to a port that already exists, such as a synth or a port made with loopMIDI.
  • In: on the cart, a MIDI keyboard plugs into the hub. The simulator reads every MIDI input on your computer, or only the one you name with --midi-in NAME.
OptionWhat it does
--midi-in NAMEreads the MIDI input called NAME, or one with NAME in its name. all reads every input (the default with MIDI_IN), and none reads none
--midi-out NAMEsends the plugin’s MIDI to the output called NAME. virtual makes a port named after the plugin (the default with MIDI_OUT, on macOS and Linux), and none sends it nowhere
--midi-log FILEwrites each message the plugin sends to FILE, with the time in milliseconds
--midi-listlists the MIDI ports and quits

F1 shows which MIDI ports are open. With --usb host, what the plugin sends to the MIDI device on the hub goes to the same output.

The plugin’s MIDI goes out once a TV frame, so its timing can be up to 1/60 of a second off. Input reaches the plugin once a frame too. As on the cart, SysEx doesn’t reach the plugin.

5. The SD card

--card FOLDER turns a folder on your computer into the plugin’s SD card. The plugin sees a FAT32 card through the SDK’s file system code, with the folder’s files and subfolders on it. The simulator reads each file from your folder when the plugin reads it.

What the plugin writes is copied back to the folder when the session ends, which happens when you press RESET or Esc, or close the window. A save file the plugin makes (fs_create(), then fs_write_sec()) shows up as a new file in the folder, and a file it changes is changed there too. Please don’t change the folder while the simulator runs, since the plugin’s changes are written back to it at the end.

A few notes about the folder:

  • Files and folders whose names start with . aren’t on the card.
  • Files of 4 GB or more aren’t on the card, because FAT32 can’t hold them.
  • The card has extra free space for new files, and the terminal shows its size when the simulator starts.

--card also takes a disk image of a whole card, such as a .img file. The plugin reads and writes that file directly.

--open PATH starts the plugin as if PATH had been picked in the cart’s menu, so cvsd_open_launched() opens it. PATH is either a path on the card (--open /NES/game.nes) or a file on your computer. For a file on your computer, its folder becomes the card, unless you also give --card. In Git Bash, which turns a leading / into a Windows path, leave out the slash (--open NES/game.nes).

sim/run.sh examples/open-file --open ~/Documents/notes.txt

6. Problems the models find

The models check the same rules as test/run.sh. They catch a list for the console that’s malformed, too long or sent too early, and a frame list that runs past its TV frame. The simulator prints each problem in the terminal, shows a red mark in the corner of the window for a second, and counts the problems in the window’s title. The plugin keeps running. With --strict, the simulator stops at the first problem.

On macOS and Linux, the simulator is built with the compiler’s memory checks (AddressSanitizer and UndefinedBehaviorSanitizer). A plugin that writes past the end of an array, uses freed memory, or overflows a signed number stops with a report that names the line. On the cart, the same bug just does something odd later. --no-sanitize builds without the checks.

Each session also leaves a log of what the plugin did in build-sim/NAME/out/log.txt, next to screen.png, the last picture.

7. Screenshots

F12 saves the picture as screenshot-1.png, then screenshot-2.png, and so on, in the current folder (or in --shots DIR). They’re 256x192, exactly the console’s pixels, which is what the plugins site needs (docs/screenshots.md).

8. Without a window: tests

--headless runs with no window and no sound, as fast as your computer can go, and always stops by itself. Use it for tests and scripts.

sim/run.sh src --headless --ms 3000 --script "500:joy=up 900:key=5 1200:key=" \
    --shot hello.png --wav hello.wav
OptionWhat it does
--frames Nstops after N TV frames (the default is 600, which is 10 seconds)
--ms Nstops after N milliseconds of console time
--script Sgives the inputs, in the script language of test/run.sh (docs/testing.md), plus the words below
--shot FILE.pngsaves the last picture
--wav FILE.wavsaves the sound (48 kHz, 16-bit, mono)
--midi-log FILEsaves what the plugin sent over MIDI (section 4)

In headless mode, the simulator opens no MIDI ports unless --midi-in or --midi-out names one, so a test never touches your MIDI devices. Use --midi-log to see what the plugin sent, and the script’s midiin= word to send it MIDI. With a port open, a headless run goes at the console’s real speed instead of as fast as it can.

The script words from docs/testing.md (pad=, keydown=, mouse=, midiin= and the rest) go straight to the models. The words below go through the simulator’s keyboard, mouse and game pad code instead, the same way input from the window does. They only work in the simulator:

WordWhat it does
simrole=controller, pad or keyboardsets the keyboard’s role, like F2
simkey=04, simkeyup=04presses or releases a key, given as its USB usage in hex (04 is A, 28 is Enter, E1 is left Shift)
simmouse=DX,DY,BUTTONS[,WHEEL]moves the mouse, holds its buttons (1 left, 2 right, 4 middle) and turns the wheel
simpad=switch or hidplugs in a game pad, either a Switch Pro Controller or another pad
simbuttons=N:south+lholds these buttons on the Nth pad plugged in (with the names pad= uses). simbuttons=N: releases them all
simsticks=N:LX,LY,RX,RYsets the Nth pad’s sticks as the computer reads them, from -32768 to 32767, with y down
simunplug=Nunplugs the Nth pad plugged in

While a simpad= pad is plugged in, it’s the console’s controller, just like a real pad, and the script’s joy= and key= don’t reach the console.

sim/run.sh test/usb --headless --usb host --ms 3000 \
    --script "1600:simrole=keyboard 1620:simkey=0B 1640:simkeyup=0B 1700:simpad=switch 1750:simbuttons=1:south"

sim/test.sh tests the simulator itself this way. It runs the template’s plugin and every example headless, and compares their logs and pictures with the ones from test/run.sh. It also checks that the Sound example’s scale is in tune in the WAV, that the Frames example beeps when its lists say it should, and that a save ends up in a card folder. Last, it runs test/usb, a plugin with every USB feature on, through the keyboard, mouse, pads and MIDI.

What the simulator can’t show you

The simulator shows you what your plugin draws and plays, and how it responds to the controls. It can’t show you how the plugin runs on the cart:

  • Your computer runs the plugin’s code many times faster than the cart’s chip. The simulator keeps the console at 60 frames a second, but a loop that’s too slow on the cart still looks fine here. You’ll only see that on a console.
  • On the cart, a plugin’s code, data and heap share about 507 KB, and its stack is 4 KB (docs/hardware.md). Your computer has far more memory, so a plugin that runs out on the cart may run fine here.
  • A desktop game pad acts as a perfect USB pad, and your computer’s keyboard, mouse and MIDI ports act as perfect USB devices. The cart’s USB code (TinyUSB) doesn’t run, so hubs, how a device starts up, and devices TinyUSB doesn’t support aren’t tested. Neither is MIDI timing, which moves once a TV frame here.
  • The colors are exactly the video chip’s, while a TV blurs them and makes them bleed. The sound comes from a model of the console’s sound chip, which is close but not exact.
  • Reads and writes on the card take a fixed time here. A real card is slower, and some are much slower.
  • The cart’s start-up isn’t simulated, including the menu copying the plugin and the switch between the menu and the plugin.

docs/testing.md has more about testing, including a test plan for a real console.

This page is docs/simulator.md in the starter kit.