Project File

A project file is the easiest way to control a debug session. It is a JSON file; the VSCode extension ships a JSON schema for it, so you get completion and validation while editing. // line comments are allowed.

Property names are camelCase. An empty {} is valid and boots to the BASIC prompt.

Example

{
    "source": "main.bmasm",
    "outputFolder": "out",
    "directRun": true,
    "startStepping": true,
    "compileOptions": {
        "displaySegments": true,
        "displayVariables": true,
        "binFolder": "bin"
    },
    "sdCardFiles": [
        { "source": "assets/*.bin", "dest": "" }
    ],
    "symbols": [
        { "symbols": "kernal.sym", "romBank": 0 }
    ]
}

Properties

Name	Type	Default	Description
source	string	""	Main source file.
startStepping	bool	false	Start the session paused, ready to step. stopOnEntry in launch.json is ignored.
directRun	bool	false	Run the compiled code directly. If false, compile it and add it to the SD card as a file instead.
autobootRun	bool	true	Run the application by writing an AUTOBOOT.X16. Not written if the file already exists.
autobootFile	string	""	Write AUTOBOOT.X16 to run this named file instead. Overrides autobootRun.
outputFolder	string	""	Where to save the .prg and other host-side build outputs. Not the SD card.
startAddress	int	-1	Start address. -1 (or omitted) starts the ROM normally from the reset vector at $fffc.
romFile	string	""	ROM file to use.
emulatorDirectory	string	""	Folder holding the official X16 emulator. Its rom.bin is used if romFile is not set; ROM-bank symbols are loaded from here using romBankNames + .sym.
symbols	SymbolsFile[]	[]	Symbol files to import.
romBankNames	string[]	(the 16 standard banks)	Display names for the ROM banks. Defaults to Kernal, Keymap, Dos, Fat32, Basic, Monitor, Charset, Diag, Graph, Demo, Audio, Util, Bannex, X16Edit1, X16Edit2, Basload.
romBankSymbols	string[]	[]	Per-bank symbol files that override the defaults.
ramBankNames	string[]	[]	Display names for the RAM banks.
machine	string	"CommanderX16"	Machine to load globals from when there is no .bmasm source.
keyboardBuffer	byte[]	[]	Prefill the keyboard buffer. 16 bytes max; the rest are discarded.
mouseBuffer	byte[]	[]	Prefill the mouse buffer. 8 bytes max; the rest are discarded.
nvRam	RtcNvram	{}	RTC NVRAM contents.
sdCard	string	""	SD card image to start with.
sdCardOutput	string	""	SD card image to write. May end .gz or .zip to compress.
sdCardFinalOutput	string	""	SD card image to write once emulation finishes. May end .gz or .zip.
sdCardFiles	SdCardFile[]	[]	Files to add to the SD card. Wildcards accepted. Added in the order listed.
cartridge	string	""	Cartridge file to load.
wifi	bool	false	Enable the WiFi card at $9fe0.
romSource	RomSource[]	[]	Files to load into ROM banks.
compileOptions	CompileOptions	null	Compilation options.
memoryFillValue	byte	0	Value to fill CPU RAM and VRAM with at startup.
breakpoints	int[]	[]	Addresses to break on at startup.
historySize	int	0x800000	Size of the CPU history buffer. Must be a power of two.
windowScale	float	1	Multiplier for the emulator display window.
muteAudio	bool	false	Don’t play audio. Only the output is silenced, emulation is unaffected.
basePath	string	(workspace folder)	Base path that other relative paths are resolved against.
files	file[]	[]	Additional files to compile and debug.

files

Each entry has a type of either bitmagic or cc65, with different fields.

bitmagic

Name	Type	Description
type	"bitmagic"
filename	string	The .bmasm file.
outputFilename	string	Optional. The file to write the main output to, eg GAME.PRG or BIN/GAME.PRG. Defaults to the source name with a .prg extension, so main.bmasm writes MAIN.PRG. It’s written with a two-byte load address header, so it can be loaded with LOAD, unless the name ends .bin.

cc65

See ca65 Projects for how to build and debug a ca65 program.

Name	Type	Description
type	"cc65"
outputs	Cc65Output[]	The binaries ld65 produced. Filenames can use wildcards, eg DAT/*.
debugFile	string	Required. The ld65 --dbgfile output, which provides the source map.
objectFiles	string[]	Optional. The .o files, checked against the outputs to catch out of date builds. Wildcards accepted.
sourcePath	string	Extra folder to search for source files.
includes	string[]	Extra source files (eg .mac) to use when a source file in the debug file can’t be found. Matched by filename.
filemap	Cc65FileMap[]	Path rewrites, applied to paths in the debug file.
basepath	string	Folder ca65 and ld65 were run from, relative to the project.
config	string	No longer used.
defaultOutputFile	string	No longer used.

cc65 output

Name	Type	Description
filename	string	The produced binary, as named in the debug file. Wildcards accepted.
startAddress	int	Optional. Address it is loaded at; taken from the debug file if not set.
default	bool	No longer used.
hasHeader	bool	The file has a two-byte load-address header. Default true.
referenceFile	string	Read this file instead of filename.

cc65 file map

Name	Type	Description
path	string	Path prefix to match in the debug file.
replace	string	What to replace it with.

symbols

Name	Type	Description
symbols	string	The symbol file. Required.
romBank	int?	ROM bank the symbols are for. Omit for a non-bank file. If set, symbols outside the ROM area are discarded.
ramBank	int?	RAM bank the symbols are for. Omit for a non-bank file. If set, symbols outside the RAM area are discarded.
filename	string	X16 filename the symbols belong to. Omit if not for an X16 binary.
rangeDefinitions	RangeDefinition[]	Memory ranges that are jump tables, used to synthesise extra symbols.

Range definition

Name	Type	Description
start	string	Start address of the jump table.
end	string	End address of the jump table.
type	string	Only jumptable is supported.

About symbol files

A .sym file is the cc65 / VICE label format: one al <hex address> .<name> per line. ld65 -Ln game.sym produces one for a ca65 build, and the x16-rom build produces one per ROM bank (kernal.sym, basic.sym, and so on).

Set emulatorDirectory to an X16 emulator checkout and the ROM-bank symbol files are picked up automatically, named from romBankNames. A symbol at $c000 or above needs romBank set; one in $a000 to $bfff needs ramBank; symbols in the wrong area for the bank are dropped.

rangeDefinitions names ranges of jmp instructions, such as the KERNAL jump table. The debugger follows each jmp and gives its target a symbol, so calls made through the table decompile with names.

sdCardFiles

Name	Type	Description
source	string	File(s) on the host. Wildcards and directories accepted.
dest	string	Destination directory on the SD card.
allowOverwrite	bool	Allow overwriting files already on the card. Default true.

rtcNvram

Name	Type	Description
file	string	File to load into 0x00 to 0x60 of the RTC NVRAM. Ignored if data is set.
data	byte[]	Bytes to load into 0x00 to 0x60 of the RTC NVRAM.
writeFile	string	File to write the RTC NVRAM to at the end. Overwrites.

romSource

Name	Type	Description
filename	string	File to load.
bank	int	ROM bank to load it into.
address	string | int	Address within the bank. Default "0".

compileOptions

Name	Type	Description
displayVariables	bool	List all names and their values.
displaySegments	bool	List the segments.
displaySymbols	bool	Log symbol loading.
displayCode	bool	Show generated code.
displayData	bool	Show generated data.
rebuild	bool	Force a full rebuild.
binFolder	string	Folder for the built template assemblies. If omitted, generated files land directly in the project’s base path rather than a bin subfolder; the scaffolded project sets this to bin explicitly.
saveGeneratedBmasm	bool	Write the generated .bmasm to the bin folder. Default true.
saveGeneratedTemplate	bool	Write the generated template C# to the bin folder. Default false.
savePreGeneratedTemplate	bool	Write the pre-template intermediate to the bin folder. Default false.
warnOnBranchOverPage	bool	Warn when a branch crosses a page boundary.