Set up for the NES
Build your first cartridge in the browser. Move to your own editor and Asm198x when you want a local workflow.
Assemble and run in your browser
The first NES lesson contains a complete editable program. Asm198x assembles it into a cartridge and Emu198x runs it on the page. Nothing needs installing.
Start with its red screen, change one instruction to make it blue, then use Download source and Download cartridge to keep your version. Download before leaving the page; a running browser session is not a saved project.
Work in your own editor
For local development you need a plain-text editor, Asm198x and an NES emulator. The source is the same one you edited in the browser.
Install Asm198x
macOS
If you already use Homebrew, install Asm198x with:
brew install asm198x/tap/asm198xWithout Homebrew, use the macOS installer or archive on the Asm198x release page. Choose Apple silicon or Intel to match your Mac. Extract an archive into a folder you can find again.
The commands below use asm198x by name. Homebrew makes the command available automatically. If you used an archive, add the extracted folder to your shell’s PATH, or use the full path to the executable instead. From its folder, use ./asm198x.
Check that your terminal can find it:
asm198x --versionIf the command is not found, check the executable’s location. A version number confirms installation; the program you run next checks the whole workflow.
Windows
Open the Asm198x release page and choose the Windows x86-64 ZIP (x86_64-pc-windows-msvc). Extract it into a folder you can find again.
The commands below use asm198x by name. Add the extracted folder to your user Path in Windows Environment Variables, then open a new PowerShell window. To run it from that folder without changing Path, use .\asm198x.exe instead.
Check that your terminal can find it:
asm198x --versionIf the command is not found, check the executable’s location. A version number confirms installation; the program you run next checks the whole workflow.
Linux
If you already use Homebrew, install Asm198x with:
brew install asm198x/tap/asm198xWithout Homebrew, use the Linux installer or archive on the Asm198x release page. Choose aarch64-unknown-linux-gnu for ARM64 or x86_64-unknown-linux-gnu for x86-64 Linux. Extract an archive into a folder you can find again.
The commands below use asm198x by name. Homebrew makes the command available automatically. If you used an archive, add the extracted folder to your shell’s PATH, or use the full path to the executable instead. From its folder, use ./asm198x.
Check that your terminal can find it:
asm198x --versionIf the command is not found, check the executable’s location. A version number confirms installation; the program you run next checks the whole workflow.
FCEUX is one local emulator you can use. Download the version for your operating system and follow its installation instructions. This example supplies its own cartridge program; no separate system ROM is needed.
Build your cartridge
Use Download source in the first lesson to save screen.asm. Open a terminal in that folder and run:
asm198x --dialect ca65 screen.asm -o screen.nesAsm198x assembles and links this example in one step. Its built-in linker configuration supports the layout used here; you do not need a separate nes.cfg for this lesson.
Open screen.nes in FCEUX. The original source produces a red screen. Change lda #$16 to lda #$11 between the YOUR CODE markers, save, rebuild and reopen the cartridge: the screen turns blue.
The ca65 dialect names the source syntax. It does not require installing ca65 too. The alternative ca65 guide is available if you already use that toolchain.
Keep your work and continue
Keep screen.asm alongside screen.nes. The cartridge is runnable; the source is what lets you change it again. Reopen both to check that you can recover your work.
Return to Assemble and Run or browse the NES assembly route.