Compiler

Vectrex Studio has two compiler backends selectable from the IDE Settings panel. Buildtools is recommended for all new projects. The Core backend is deprecated.

Backend 1 — Core (Deprecated)

Status: ⚠️ DEPRECATED — maintenance mode, no new features

Use Buildtools for all new projects. See the migration note at the bottom of this page.

Single-pass pipeline: lexer → parser → AST → optimizer → codegen → MC6809 assembly → binary. Always outputs a fixed 32 KB ROM. No PDB debug symbol generation.

Backend 2 — Buildtools (Recommended)

Status: ✅ Active — single-bank and multibank, all new features here

A modular multi-crate Rust pipeline with one crate per phase.

Buildtools handles both 32 KB (single-bank) and 64 KB+ (multibank) games. All new builtins, bug fixes, and hardware features ship here first.

Additional features

• Variable-sized types (u8, i8, u16, i16) — declare with Python type-hint syntax (counter: u8 = 0). 1-byte types save RAM; defaults to i16 when no annotation is given. See the language manual for details.
• Level system with horizontal scrolling — load .vplay scenes with LOAD_LEVEL("name"), render with SHOW_LEVEL(), and scroll with SET_CAMERA_X(x). Objects are culled automatically outside the viewport. See Level System below.

Multibank ROMs

VPy supports ROMs from 32 KB up to 4 MB with zero changes to your game code. Add two META directives:

META ROM_TOTAL_SIZE = 65536    # pick your target (see table below)
META ROM_BANK_SIZE  = 16384    # always 16 KB per bank

The compiler divides the ROM into 16 KB banks, assigns functions and assets automatically via call graph analysis, and generates all bank-switching wrappers. Banks 0 through N−2 are switched in at $0000–$3FFF; the last bank (helpers) is fixed at $4000–$7FFF.

Supported sizes

Configurations larger than 4 banks compile, but cross-bank symbol resolution is still being completed. 4-bank (64 KB) is the recommended configuration for production today.

Memory map

$0000-$3FFF  Banked window (16 KB) — switches via STA $DF00
$4000-$7FFF  Helpers bank  (16 KB) — last bank, always visible

Level System

The level system lets you design game scenes visually in the Playground tab and load them at runtime.

Builtins

Horizontal scrolling

Levels can be wider than the Vectrex screen (−128 to +127). Move the viewport with SET_CAMERA_X:

camera_x: i16 = 0
 
def loop():
    joy = J1_X()
    if joy > 20:
        camera_x = camera_x + 2
    if joy < -20:
        camera_x = camera_x - 2
    camera_x = clamp(camera_x, 0, 800)   # clamp to world width
    SET_CAMERA_X(camera_x)
    SHOW_LEVEL()

Objects outside the viewport are automatically culled. Only X-axis scrolling is supported.

.vplay file format

Files are authored in the IDE Playground and saved as JSON v2.0:

{
  "version": "2.0",
  "worldBounds": { "xMin": -96, "xMax": 863, "yMin": -128, "yMax": 127 },
  "layers": {
    "background": [ { "vectorName": "ground", "x": 0, "y": -60, ... } ],
    "gameplay":   [ { "vectorName": "player", "x": 0, "y":   0, ... } ],
    "foreground": []
  }
}

x/y are world coordinates. SHOW_LEVEL() subtracts CAMERA_X from each object's X to produce the screen position.

Project File Format (.vpyproj)

[project]
name        = "mygame"
version     = "0.1.0"
entry       = "src/main.vpy"
description = "My Vectrex game"
author      = "Your Name"
 
[build]
output         = "build/mygame.bin"
target         = "vectrex"
optimization   = 2
debug_symbols  = true   # required for source-level debugging
 
[sources]
vpy = ["src/**/*.vpy"]
 
[resources]
vectors = ["assets/vectors/*.vec"]
music   = ["assets/music/*.vmus"]
sfx     = ["assets/sfx/*.vsfx"]

Building from the Command Line

# Build a project with Buildtools
cd buildtools && cargo run --bin vpy_cli -- build path/to/project.vpyproj
 
# Run compiler tests
cd buildtools && cargo test --all

Migrating from Core to Buildtools

1. Create a .vpyproj file next to your main .vpy (see the project format section above).
2. In the IDE Settings panel, switch the backend selector to Buildtools (New).
3. Rebuild — single-bank output is identical to Core.

The only common issue is that Buildtools requires the .vpyproj file; there is no bare .vpy build mode.