Set up the desktop emulator

Use this route for the tutorial and for keeping your game in files and Git. The emulator runs your MicroPython game on your computer; no console is needed.

Install dependencies

The previous setup guides recorded Ubuntu 24.04 x86_64, macOS Sonoma 14.5 on an M1 MacBook Air, and Windows 10 Intel 64-bit. These are recorded environments, not a claim that every current combination has been retested. SDK CI uses Python 3.12.

Linux (Ubuntu):

sudo apt install git micropython python3.12-venv ffmpeg

macOS: install Homebrew, then:

brew install git python@3.12 micropython ffmpeg

Use Homebrew’s installation instructions to put its binaries on PATH; its prefix differs between Apple Silicon and Intel machines.

Windows: install Git and Python 3.12, with Python on PATH. The SDK includes emulator/micropython.exe. FFmpeg is needed for audio conversion; see emulator/ffmpeg-win/README.md in the repository for the local binary directory. Game code is MicroPython, distinct from the CPython used to run the emulator host.

Clone and install

git clone https://github.com/ventilastation/vsdk.git
cd vsdk
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt

On Windows, use these commands in Command Prompt instead:

git clone https://github.com/ventilastation/vsdk.git
cd vsdk
py -3.12 -m venv .venv
.venv\Scripts\activate
python -m pip install -r requirements.txt
python -m pip install pywin32

You do not need to initialize the Retro-Go firmware submodule to write MicroPython games.

Run a known VS2 game

On Linux/macOS, run from the repository root:

./vs-emu.sh --game demos.tutorial_game

On Windows, with the virtual environment still active:

vs-emu.bat --game demos.tutorial_game

You should see Trench Run. A/D steer; Space is A and 1 is Select (Back). Without --game, the emulator opens the launcher; the finished tutorial is in Tech Demos. ROM generation happens automatically when sources change.

Next: create your own game and steer a ship.

Controls and troubleshooting

Control	Player 1	Player 2
Up / Down / Left / Right	Arrow keys	W / S / A / D
A / B / C / D	Numpad 0 / 1 / 2 / 3	Space / B / N / M
Select / Start	Numpad + / Enter	1 / 2

Press F1 to see the keyboard layout. Select is BACK in the game API; C and D are X and Y. Player 1 uses the numeric keypad, including its Enter key; the main Enter key is unassigned. The keypad works with Num Lock on or off.

Either player can navigate the launcher with Up/Down and select with A. Select or D returns from a submenu.

A USB gamepad also works. The terminal that launched the emulator shows Python tracebacks: keep it open when debugging. A missing PNG usually means images/__images__.yaml names a file you have not copied.

If python, micropython, or FFmpeg cannot be found, check PATH and activate .venv. If your game is missing, check its games/<group>/<name>/code/<name>.py entry point and metadata. --game group.name uses a dot between group and name.

The Unix launcher tries to build the optional native renderer. The GPU shader renderer needs OpenGL 3.3; ./vs-emu.sh --scene-renderer cpu selects the CPU path. For renderer profiling and parity checks, see the desktop scene-renderer comparison in the SDK internals.