VPy and C: how they correspond

VPy and C are two ways into the same runtime. The VPy builtins are implemented once, in C, in libvpy (vpy.h in the SDK). VPy programs on the ARM targets and C games both link it, and a C game calls its functions directly. The 3D builtins call the SDK's vpy3d, which C games use too. So when you learn one language you have learned most of the other: the same coordinates, the same assets, the same frame model, often the same names.

This page lines the two up. For the C side in the IDE see C Projects, and for the full C API see libvpy and vpy3d.

Project files

A new VPy project (File → New → Project, language VPy):

[project]
name = "ship"
version = "0.1.0"
entry = "src/main.vpy"
 
[build]
output = "build/ship.bin"
optimization = 2
debug_symbols = true
 
[sources]
vpy = ["src/**/*.vpy"]
 
[resources]
vectors = ["assets/vectors/*.vec"]
music = ["assets/music/*.vmus"]
# ... one line per asset folder
 
[sdk]
version = "v1.4.4"

A new C project (language C (SDK)):

[project]
name = "ship"
type = "c-external"
target = "rp2350"
entry = "src/main.c"
 
[build]
command = "make"
args = ["rp2350"]
artifact = "build_rp2350/ship_sd.bin"
 
[targets.uvm2]
command = "make"
args = ["uvm2"]
artifact = "build_uvm2/ship.um2"
 
[simulate]
command = "make"
args = ["sim"]
module = "build_wasm/ship.js"
 
[sdk]
version = "v1.4.4"

The full C manifest is in C Projects, and the pin in Projects and the SDK.

Program structure

Both languages have a run-once function and a per-frame function. Neither one has a frame loop to write.

# VPy
x = 0
 
def main():
    SET_INTENSITY(127)
 
def loop():
    x = clamp(x + J1_X() / 32, -100, 100)
    PRINT_TEXT(-60, 60, "HELLO")
    DRAW_LINE(x - 10, 0, x + 10, 0, 127)

/* C */
#define VPY_SHORT_NAMES
#include <vpy.h>
 
static int x;
 
static void setup(void) { SET_INTENSITY(127); }
 
static void loop(void)
{
    x = vpy_clamp(x + J1_X() / 32, -100, 100);
    PRINT_TEXT(-60, 60, "HELLO");
    DRAW_LINE(x - 10, 0, x + 10, 0, 127);
}
 
int main(void) { vpy_run(setup, loop); return 0; }

Don't add a frame sync of your own in either language. In C, calling v_WaitRecal() directly skips the flush and nothing is drawn. If you need the boundary yourself, use vpy_wait_recal().

Builtins and their C calls

In C, #define VPY_SHORT_NAMES before #include <vpy.h> gives you VPy's upper-case names as macros. Without it, use the vpy_* names. The tables below list only pairs confirmed in vpy.h, in vpy3d's header or in the compiler's C backend. Short name is the C macro, and — means there is none: call the long name. Where the arguments differ, the C form is shown.

Drawing

Text and debug

Input

Sound

Levels, camera and enemies

Math

libvpy has no short names for the math helpers. Use the vpy_* names in C.

3D

The VPy 3D builtins call vpy3d, the same layer a C game includes with #include <vpy3d.h> (add $(VPY_C_SDK)/vpy3d.c to the sources). They are shaped differently, though. VPy names a mesh by string and keeps transforms in 12-element i32 arrays. C keeps a vpy_mesh object per mesh and passes vpy_xf values.

The skeleton builtins (BONE_*) sit on vpybone, and the jukebox builtins (MUSIC_TRACK, SFX_PCM…) on the same player C games use, but through small adapters of the compiler's own, so their C calls are not one-to-one. See VPy 3D and vpy3d.

Assets

Both languages use the same files, made in the same editors. VPy names an asset with a string and the compiler embeds it. C includes the header vpy_cli compile-asset writes to gen/<name>.h and passes its arrays. In the table, N is the name in upper case.

"All" means m6809, rp2350, uvm2 and pitrex for VPy, and sim, rp2350 and uvm2 for C. In C, SET_INTENSITY does not override a sprite's own intensities. Give each asset of a C project its own name: ship.vec and ship.vmus would both become gen/ship.h.

Targets and languages

See Compiler & Build Targets for what each VPy target produces, and Cartridges for the hardware.

VPy built through C

On uvm2 and rp2350, a VPy program can be compiled as C. The compiler writes the whole program as C and builds it with gcc against libvpy, the same runtime C games link:

[uvm2]
backend = "c"
sdk_opt = "O2"                         # optional: "O2", "Os" or "O1"
defs = "UVM2_DRAW_SCALE=127"           # optional; several are separated by ;
 
[rp2350]
backend = "c"                          # if absent, [uvm2] backend is used

• Size. On a large game we measured 224 KB of code with the C backend against 323 KB with the ARM backend. A .um2 runs entirely from the cartridge's SRAM, code included, so this is room for levels. An untyped const array whose values all fit in a byte is stored as int8_t with this backend.
• Same drawing as C games. The 2D builtins are libvpy's own, so text and vectors draw exactly as in a C game.
• rp2350 gets the 3D, effects and jukebox builtins this way. The result is always the SD card's RAM image. The cartridge has no audio jack, so the jukebox builtins compile and stay silent (JUKEBOX_LIVE() returns 0).
• sdk_opt builds the SDK's C libraries (libvpy, vpy3d and the layers on it) at that level instead of the build's own.
• defs passes defines to the SDK (pool sizes, limits). The [rp2350] keys fall back to [uvm2] ones.
• Semantics are the ARM backend's: 32-bit wrapping integers, truncating /, typed arrays.
• Not everything is there yet. Builtins with no libvpy counterpart in this backend (levels, enemies, animations, samples) are a compile error for now.
• Debugging. gcc optimises, so a line may be skipped, a breakpoint on a call can stop in the inlined function, and some locals show as optimised out here. main() and loop() appear in the call stack inlined into the runtime. See Debugging.

Shared conventions

On the ARM targets the C calls behave like the VPy ones, with the same bytes and the same runtime arithmetic, so positions and timings carry over when you port a game from one language to the other.