Assemble and Run

New to programming entirely? The Basics introduces variables, loops and subroutines. This track assumes you’ve met those ideas somewhere, even if assembly is completely new.

Your first NES program fills the screen with red. You’ll assemble and run it here, change one instruction to turn the screen blue, then download your own cartridge. Nothing needs installing: Asm198x builds the program in your browser, and Emu198x runs it.

This is the start of Meet the Machine. The NES uses a processor from the 6502 family, like the Commodore 64, but the machine around it is different. There’s no BASIC prompt waiting for your program. The console starts from a cartridge, and your code must prepare the display before it can draw anything.

Today we supply that preparation. Your first change is one instruction.

Assemble and run here

Press Assemble & run below. Asm198x turns the source into a cartridge and loads it into the NES player. The result is a solid red screen; there are no game controls to press yet. The first build also loads the assembler, so it may take a moment.

This is the complete source, including the setup code. You can edit it directly. Find the line lda #$16 between the YOUR CODE markers — that’s the instruction we’ll change shortly.

The emulator opens in a side panel when your build succeeds. Close it to pause; Show emulator brings it back.

Download cartridge assembles the source currently in the editor and saves screen.nes. You don’t have to run it first. Download source saves your edited screen.asm. Neither sends your code to a server.

For an unchanged reference, download the starting red-screen cartridge. Open any of these .nes files in Emu198x for desktop or another NES emulator. Choose the ordinary NTSC NES model if asked; this example needs no separate firmware file.

What the supplied code does

The source contains a small harness: the preparation needed to make this first experiment work. It has four jobs:

• Describe the cartridge with an iNES header, so the emulator knows how much program and graphics data to load.
• Set up the processor and wait for the PPU, the separate chip that produces the picture, to be ready.
• Write your chosen colour to the PPU’s backdrop palette entry.
• Keep the processor in a loop so it doesn’t run into unrelated bytes after finishing.

At the end of the cartridge, a reset vector tells the processor where to begin. The .segment lines group the header, program, vectors and graphics data so the build tool can place them correctly.

You don’t need to write all that preparation from memory. Read through it once, then find the YOUR CODE markers. That’s the part we’ll change. Later units return to registers and the display in more detail.

The instruction to change

Between the YOUR CODE markers is one instruction:

lda #$16

lda loads a value into register A, a small storage location inside the processor. The # means “use this number”, and $ means the number is written in hexadecimal. Here $16 selects a red entry in the NES palette.

The code below that line takes the value from A and writes it to the display hardware. Near the end, forever: jmp forever keeps jumping back to itself, leaving the picture unchanged.

Change the colour

In the editor above, replace:

lda #$16

with:

lda #$11

Before pressing anything, look at the screen. It is still red: editing source doesn’t change the cartridge already running. Now press Assemble & run. The newly built cartridge starts, and the screen turns blue.

That’s the loop: edit source → build cartridge → run cartridge. Asm198x translates your edit into machine code; the NES executes those new instructions. The browser handles the handoff between them.

Try $2a for green or $30 for white. Change only the value on that line, and predict the result before assembling. Download cartridge gives you a playable copy of your current version. Keep its source too, so you can change it again later.

To return to the starting program, press Revert source, then Assemble & run. Revert restores the lesson text; it doesn’t change the running machine until you assemble again.

Build locally with Asm198x

The browser uses a WebAssembly build of Asm198x, the same assembler you can run from a terminal. If you’d like to work in your own editor, use Download source above, or download the original screen.asm.

Follow the NES setup guide to install Asm198x. Then check that your terminal can find it:

asm198x --version

From the folder containing screen.asm, run:

asm198x --dialect ca65 screen.asm -o screen.nes

The source uses ca65 syntax: conventions such as .segment and .byte that describe how to organise the program. --dialect ca65 tells Asm198x to read that syntax; it doesn’t invoke the separate ca65 program. screen.asm is the input, and -o screen.nes names the cartridge to write.

Asm198x assembles the instructions and places the segments into its default NES cartridge layout in one invocation. This example needs no separate linker command or nes.cfg file with Asm198x, in the browser or at the terminal.

Open the resulting screen.nes in your emulator. You can also start the player above and use Change cartridge to load a file you’ve built locally. Assemble & run always builds from the text in this page’s editor; it cannot read later edits you’ve made in a desktop editor.

Using ca65 and ld65 instead

The native cc65 setup guide covers installing the separate tools. For this route, also download this lesson’s nes.cfg layout file and put it beside screen.asm.

Then run:

ca65 screen.asm -o screen.o
ld65 -C nes.cfg screen.o -o screen.nes

Here ca65 is the assembler: it produces an intermediate object file, screen.o. ld65 is the linker: it reads nes.cfg, places the segments and produces screen.nes. The layout work still exists when you use Asm198x; its default NES layout handles it within the single build command.

For this lesson, both routes produce the same cartridge bytes. Choose either route and use it for each edit/build/run cycle. The emulator loads the finished .nes file, not .asm, .o or .cfg.

If it doesn’t work

• The browser reports an assembly error. Read the line number and message below the buttons. The editor selects the offending line. Check your edit; the existing cartridge keeps running until a new build succeeds.
• The screen stays red after your colour edit. Press Assemble & run. Merely typing in the editor doesn’t update the running cartridge. If you’re building locally, save the source, rebuild successfully, then reopen the new .nes file.
• You want to undo your edits. Press Revert source, then Assemble & run to return to the supplied red-screen program.
• The browser assembler cannot load. Retry the build. You can also download the source and use the terminal command above; the reference cartridge remains available as a check on your emulator.
• The terminal can’t find asm198x or screen.asm. Finish the installation, reopen your terminal, and run the command from the folder containing your source. Check that your editor hasn’t added a .txt extension.
• A local build fails but there’s still a screen.nes file. It may be your previous successful build. Running that old file won’t test the change you just made.
• ld65 can’t find nes.cfg or a segment. This applies to the alternative toolchain: keep the supplied layout file beside the source and leave the .segment names unchanged.

What’s next

You’ve edited source, assembled it with Asm198x, and run the resulting cartridge. Register A carried the colour from your instruction to the display code. In LDA Is Not LET, we’ll look more closely at that register: how much it holds, how it changes, and why it behaves differently from a variable in a higher-level language.