Quick Start

This walkthrough assembles a tiny ZX Spectrum Next program — a flashing border — into a .nex you can run in Bizmuth. It assumes fantasm is on your PATH (see Installation).

1. Write a program

Create main.asm:

!target zxnext          ; ZX Spectrum Next
!format nex             ; output a .nex executable
!nex pc main            ; entry point

ORG $8000

main:
    ld a, 0             ; border colour counter
.loop:
    out ($fe), a        ; set the border colour
    inc a
    and %00000111       ; keep it in range 0–7
    jr .loop

2. Assemble it

The default command is build, so these are equivalent:

fantasm build main.asm hello.nex
fantasm main.asm hello.nex

The !target/!format directives already select the Next and .nex output; you can also set them on the command line instead:

fantasm main.asm hello.nex -t zxnext -f nex

3. Run it

Open hello.nex in Bizmuth — the border cycles through colours. That’s the full write → assemble → run loop.

Starting a real project

For anything larger than a single file, let FantASM scaffold a project with a fantasm.toml:

fantasm init

This creates a project config that records your target, output path, include directories and defines, so a plain fantasm (with no arguments) builds the whole thing. See Project configuration for the details.

Next steps