Programming the Atari VCS in Assembly

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

Introduction#

If you arrive here from modern software development, much of your hard-won instinct will work against you. The things a career is built on — rich standard libraries, layers of hardware abstraction, portable code that runs anywhere — none of it exists on the VCS. There is no operating system to call, no driver sitting between you and the silicon, and nothing you write will run on any machine but this one. As a certain Jedi master would put it:

Pong (a minimal teardown)

Mon, 01 Jan 0001 00:00:00 +0000

Pong (a minimal teardown)#

Where Combat and Pitfall! are feats of compression — huge games squeezed into tiny ROMs — this Pong is the opposite lesson: the irreducible minimum, the smallest thing that is still a complete VCS game. It’s a clean, modern implementation by Lucas Avanço, built on Kirk Israel’s “thin red line” tutorial and the Stella Programmer’s Guide — not Atari’s 1977 cartridge, but all the better for reading, because there’s nothing in it that isn’t essential.

Combat (1977)

Mon, 01 Jan 0001 00:00:00 +0000

Combat (1977)#

Combat shipped in the box with the original console — for millions of people it was the Atari. Written by Larry Wagner with hardware help from Joe DeCuir, it packs 27 game variations (tanks, tank-pong, invisible tanks, biplanes, jets) into a 2 KB ROM. It’s also one of the most thoroughly annotated programs in 2600 history: the commented disassembly this teardown follows runs from Harry Dodgson’s original through Nick Bensema’s notes (1997) to Roger Williams’ full overhaul (2002).

Cosmic Ark's Star Field

Mon, 01 Jan 0001 00:00:00 +0000

Cosmic Ark’s Star Field#

Imagic’s Cosmic Ark (1982) opens with a starfield so clean it looks impossible on a machine that can show two sprites and a ball. Crisp white stars, evenly spaced, drifting smoothly — far more points of light than the TIA has objects to draw them with. The secret is the most celebrated bug in Atari history.

A glitch nobody ordered#

The effect is a single missile misbehaving. As Horizontal Positioning explained, an object’s position is retimed by strobing HMOVE — and that retiming is delicate, built on the TIA’s and CPU’s clocks lining up just so. Strobe HMOVE the wrong way — at the wrong point in the line, or an extra time — and the missile’s position logic comes unglued: instead of moving once, the missile gets redrawn again and again across the scanline, scattering a row of evenly-spaced dots. Point that at the screen every frame and you have a starfield, conjured from one object the TIA never meant to clone.

Counting Cycles

Mon, 01 Jan 0001 00:00:00 +0000

Counting Cycles#

Every other platform lets you write code and measure it later. On the VCS you must know the cost before you run it, because a visible scanline is 76 CPU cycles and there is no “a little slow” — a kernel line that needs 77 doesn’t lag, it corrupts the picture. Counting cycles is the habit that makes everything else in this chapter possible.

Budget from WSYNC to WSYNC#

A kernel is a loop, and the unit you budget is one pass: the cycles between one STA WSYNC and the next. Add up the cost of every instruction in that span — using the per-instruction costs — and confirm the total fits under 76 (minus whatever the visible drawing already spends).

Drawing a Player

Mon, 01 Jan 0001 00:00:00 +0000

Drawing a Player#

The two players (P0 and P1) are the TIA’s real sprites: 8-pixel-wide bitmaps you can move anywhere and color independently. A player is how you draw the tank, the spaceship, the character. Drawing one is, like everything on the VCS, a matter of feeding the right register at the right scanline.

One byte, one row#

A player’s shape lives in a single register — GRP0 for player 0, GRP1 for player 1. Its 8 bits are 8 pixels: a 1 lights a pixel in the player’s color (COLUP0 / COLUP1), a 0 is transparent. But a register holds only one row, so — exactly like the playfield kernel — you rewrite GRP0 on each scanline the sprite occupies, walking down a bitmap table:

How a Television Works

Mon, 01 Jan 0001 00:00:00 +0000

How a Television Works#

Before the VCS makes sense, the television has to. Every concept in this book — the frame loop, sync signals, “Racing the Beam,” the cycle budget — is a direct consequence of how a cathode-ray-tube TV paints a picture. You don’t need a broadcast-engineering course; you need the handful of facts the hardware forces you to care about.

The beam paints one line at a time#

A CRT television draws its image with a single electron beam that sweeps across the screen from behind. It moves in a fixed pattern:

Programming Across Banks

Mon, 01 Jan 0001 00:00:00 +0000

Programming Across Banks#

Bankswitching hands you the hardware: several 4 KB banks and a few hotspot addresses that swap which one the window shows. That much is simple. The hard part is living there — writing code that keeps working while the bytes underneath it change. Because the swap is a silent side effect of touching an address, the program counter doesn’t move when a bank flips; only the contents under it do. Two facts follow, and both shape how you lay out a banked game.

Registers & Status Flags

Mon, 01 Jan 0001 00:00:00 +0000

Registers & Status Flags#

The 6502 has astonishingly few places to keep data — three 8-bit working registers, and that scarcity shapes how every program is written. You can’t spread work across a bank of registers the way you would on a bigger CPU; values are constantly shuttled between these three and memory.

Register	Width	Role
A (accumulator)	8-bit	The workhorse. The only register that does arithmetic and logic (`ADC`, `SBC`, `AND`, `ORA`, `EOR`). Almost all data flows through it.
X	8-bit	Index/counter. Used to offset addresses (`LDA table,X`) and to count loops. Also the bridge to the stack pointer (`TXS`/`TSX`).
Y	8-bit	The other index/counter. Similar to X, with its own indexed modes.
S (stack pointer)	8-bit	Points at the top of the stack.
PC (program counter)	16-bit	Address of the next instruction to execute.
P (status)	8-bit	The processor flags — see below.

A, X, and Y are not interchangeable: only A computes, only X and Y index, and each has instructions the others lack. Choosing which value lives in which register is a real part of writing tight 6502 code.

The Audio Registers

Mon, 01 Jan 0001 00:00:00 +0000

The Audio Registers#

The TIA gives you two independent audio channels, and that’s the whole orchestra — two voices, no more. Each channel is described by exactly three registers, and a sound is whatever you get by setting them and changing them over time.

Register	Width	Sets
`AUDC0` / `AUDC1`	4 bits	the waveform — which tone or noise shape this channel makes
`AUDF0` / `AUDF1`	5 bits	the frequency — a divisor, so 32 steps, higher value = lower pitch
`AUDV0` / `AUDV1`	4 bits	the volume — 0 (silent) to 15 (loudest)

The three combine in a fixed signal path: AUDC and AUDF feed a tone/noise generator, whose output is scaled by AUDV, and the two channels mix to the single output:

The Blue Box, Reborn

Mon, 01 Jan 0001 00:00:00 +0000

The Blue Box, Reborn#

The rest of this book hands you a 2026 toolchain: write 6502 in a text editor, run DASM, and watch the result in Stella a fraction of a second later. It works, it’s free, and it would have looked like science fiction to the people who actually invented these games. In 1979 there was no Stella, no DASM, no PC on the desk. There was a refrigerator-sized minicomputer down the hall, a serial cable, and — for David Crane at Activision — a blue sheet-metal box wired into the cartridge slot of a real console.

The Collision Registers

Mon, 01 Jan 0001 00:00:00 +0000

The Collision Registers#

The TIA tracks collisions between its six drawable objects — the two players, two missiles, the ball, and the playfield. Six objects make 15 possible pairs, and the chip reports them across eight read-only registers.

Detection is geometric, and it latches#

As the beam paints each visible pixel, the TIA asks a simple question: are two objects both lit here? If so, it sets the corresponding collision bit. Two things follow from that:

The Joystick

Mon, 01 Jan 0001 00:00:00 +0000

The Joystick#

The standard CX40 joystick is the simplest input on the system: five switches — four directions and a fire button — and nothing analog. The four directions of both joysticks are read from a single RIOT port, SWCHA; the fire button comes in elsewhere (see Buttons & Console Switches).

One byte, two joysticks#

SWCHA packs both controllers into its eight bits — player 0 in the high nibble, player 1 in the low nibble — each nibble holding right/left/down/up:

Toolchain: DASM & Stella

Mon, 01 Jan 0001 00:00:00 +0000

Toolchain: DASM & Stella#

Two tools cover the entire development loop for this book: DASM assembles your .asm source into a cartridge image, and Stella runs that image as if it were a real console.

Installing#

On macOS with Homebrew:

brew install dasm
brew install --cask stella

DASM is the de-facto assembler for the VCS; Stella is the reference emulator and an excellent debugger.

Assembling a ROM#

The canonical build command (from the repository’s xmas/Makefile) is:

Anatomy of a Minimal ROM

Mon, 01 Jan 0001 00:00:00 +0000

Anatomy of a Minimal ROM#

Every program in this book shares the same skeleton. Understanding these few lines means understanding what a VCS ROM fundamentally is.

The header#

 processor 6502

 include "vcs.h" ; TIA / RIOT register names (COLUBK, PF0, WSYNC, ...)
 include "macro.h" ; helper macros, e.g. CLEAN_START

vcs.h gives readable names to the hardware registers so you can write sta COLUBK instead of sta $09. macro.h provides convenience macros. In this repository both live in a shared top-level include/ directory that every game reaches via DASM’s -I../include flag — a single source of truth rather than a copy per game.

Reading 6502 Assembly

Mon, 01 Jan 0001 00:00:00 +0000

Reading 6502 Assembly#

Every line of code in this book is 6502 assembly language — human-readable names for the numeric machine code the 6507 actually executes. DASM translates it into the bytes that go on the cartridge. You don’t need to write it fluently yet, but you do need to read it, because every concept here is demonstrated in it. This page is just enough to follow along; the CPU’s full instruction set and addressing modes are the 6502 Basics chapter.

The Processor (CPU)

Mon, 01 Jan 0001 00:00:00 +0000

The Processor (CPU) — a 6507#

The CPU runs your program. On most computers that makes it the star; on the VCS it’s deliberately the least special of the four chips — a small, ordinary processor whose whole job is to operate the other three at exactly the right moments.

A 6502 with its wings clipped#

The 6507 is a cost-reduced version of the well-known 6502: the same instruction set, the same registers, the same programming model — but in a cheaper package with two consequential omissions:

The Video & Sound Chip (TIA)

Mon, 01 Jan 0001 00:00:00 +0000

The TIA: Programming the Television#

Every console has a graphics chip. What makes the TIA — the Television Interface Adapter — and therefore the VCS different is what it doesn’t have: a frame buffer. That single absence is the source of both the machine’s notorious difficulty and its peculiar charm, and it’s why the right mental model is not “drawing graphics” but programming the television itself.

What the TIA handles#

For one chip, it does a lot — and all of it in real time, in step with the beam:

Memory, I/O & Timer (RIOT)

Mon, 01 Jan 0001 00:00:00 +0000

The Memory, I/O & Timer chip (RIOT) — a 6532#

The RIOT (the 6532) — sometimes called the PIA — is the unglamorous but essential housekeeping chip. While the TIA gets the glory, the RIOT quietly provides the three things every program needs but the TIA doesn’t supply. Its name is an inventory of those jobs: RAM, I/O, and Timer.

RAM — your 128 bytes#

The RIOT holds the VCS’s entire read/write memory: 128 bytes, at addresses $80–$FF. Every variable your game keeps — score, positions, velocities, game state — lives here, and nowhere else. Internalize how little that is: a single screen’s worth of modern data structures would not come close to fitting. Tight memory discipline isn’t an advanced topic on the VCS; it’s the baseline.

The Program ROM

Mon, 01 Jan 0001 00:00:00 +0000

The Program ROM — your cartridge#

Three of the four chips are inside the console. The ROM is the one you supply — it’s the cartridge — and it holds your program and all of its constant data: code, sprite bitmaps, lookup tables, music.

Where it lives#

The CPU maps the cartridge into the top of the address space, the $F000–$FFFF window, with the all-important reset vectors at $FFFC. When the console powers on, the 6507 reads that vector and jumps to it — so the very top of your ROM is where execution begins. The mechanics of that startup are in Anatomy of a Minimal ROM.

Addressing Modes

Mon, 01 Jan 0001 00:00:00 +0000

Addressing Modes#

An instruction like LDA doesn’t just load — it loads from somewhere, and the addressing mode is how that somewhere is specified. The same LDA comes in several forms, and they differ in both what they can reach and how many cycles they cost — which, on the VCS, is the part you care about most. Reading 6502 Assembly introduced the #/$/,X notation; here is what each mode actually does.

Buttons & Console Switches

Mon, 01 Jan 0001 00:00:00 +0000

Buttons & Console Switches#

The joystick directions come from SWCHA, but the fire buttons and the console switches live elsewhere — and they introduce the one idea that separates “input that works” from “input that feels right”: telling a held button from a just-pressed one.

Fire buttons (INPT4 / INPT5)#

A joystick’s fire button is read not from the RIOT but from two TIA registers: INPT4 for player 0, INPT5 for player 1. The state is in bit 7, and like everything else it’s active-low — pressed reads 0. Because the flag is in bit 7, BIT is the natural test:

Extra RAM

Mon, 01 Jan 0001 00:00:00 +0000

Extra RAM#

The console gives you 128 bytes of RAM, and that pool is shared with the stack. It is brutally little — a few sprite positions, a score, some counters, and it’s gone. The way past it is the same as for ROM: put more memory on the cartridge.

Cartridge RAM, and the two-port trick#

The best-known add-on is Atari’s “Superchip” — 128 extra bytes (some carts more) of RAM riding on the cartridge, mapped into the bottom of the cart window. Atari shipped it in a run of mid-1980s titles — Dig Dug, Crystal Castles, Off the Wall, Secret Quest — most of which bankswitch as well. But cartridge RAM has a wrinkle the console RAM doesn’t: the cartridge connector has no clean read/write signal the chip can use to tell a load from a store in time. So cartridge RAM is split across two address ranges — a write port and a read port:

Horizontal Positioning

Mon, 01 Jan 0001 00:00:00 +0000

Horizontal Positioning#

This is the technique that defines VCS sprite work, and the first place every beginner hits the cycle wall. A player has no X-coordinate register. You cannot write “put P0 at column 40.” Instead you position it by timing — and then nudge it into place.

Step one: strobe to a coarse position#

Writing to RESP0 is a strobe: the value doesn’t matter, the act of writing does. It snaps player 0’s horizontal position to wherever the beam happens to be at the moment the store executes. So you move a sprite by choosing when in the scanline to run STA RESP0.

Pitfall! (1982)

Mon, 01 Jan 0001 00:00:00 +0000

Pitfall! (1982)#

Pitfall! — David Crane, Activision, 1982 — sent Pitfall Harry running through a 255-room jungle of logs, vines, crocodiles, scorpions, and quicksand, and became one of the best-selling games on the system. It did all that on a 4 KB cartridge, which raises an obvious question: where do 255 rooms fit? The answer is the most famous idea in 2600 programming, and it’s the reason this game is worth taking apart. (The disassembly here is Thomas Jentzsch’s.)

Reading & Clearing

Mon, 01 Jan 0001 00:00:00 +0000

Reading & Clearing#

The TIA does the detecting; your job is two small, regular acts: read the latches once the frame has been drawn, and clear them before the next one. Get that rhythm right and collisions are nearly free; get it wrong and they either never fire or never stop.

Testing a latch with `BIT`#

Each collision flag sits in bit 7 (and bit 6) of its register, which is exactly where BIT is most useful: it copies a memory location’s bit 7 into the N flag and bit 6 into the V flag, without changing any register (see Registers & Flags). So one BIT tests both pairs at once:

Thinking in Bits

Mon, 01 Jan 0001 00:00:00 +0000

Thinking in Bits#

On the VCS, almost every hardware register is a bag of individual switches — one bit turns on playfield reflection, one bit is the fire button, a group of bits picks a sound waveform. There is no high-level API; you set and clear bits directly. This page is the bit literacy the rest of the book assumes. Its companion, The Memory-Mapped Interface, covers where those bits live and how you reach them.

Tones, Noise & Pitch

Mon, 01 Jan 0001 00:00:00 +0000

Tones, Noise & Pitch#

Two registers shape what a channel sounds like: AUDC picks the waveform, and AUDF picks the pitch. Together they’re the source of both the VCS’s distinctive voice and its most infamous flaw — it can’t play in tune.

AUDC: pick a voice#

AUDC is a 4-bit selector (0–15) that routes the channel through different internal divider and polynomial-counter combinations. The result isn’t 16 evenly-graded timbres but a handful of distinct families — pure tones, buzzy/reedy tones, and noise. The ones you’ll reach for most:

Waiting Precisely

Mon, 01 Jan 0001 00:00:00 +0000

Waiting Precisely#

Half of kernel work is making things happen; the other half is making them happen at the right cycle. WSYNC handles the coarse case — it parks you at the start of the next line — but it can only round up to a line boundary. When you need to land on an exact cycle within a line (positioning a sprite, rewriting a playfield register mid-line), or to wait out a whole region of the frame, you need finer and coarser tools than WSYNC.

Yars' Revenge's Neutral Zone

Mon, 01 Jan 0001 00:00:00 +0000

Yars’ Revenge’s Neutral Zone#

Down the middle of Yars’ Revenge (Atari, 1982 — the best-selling original Atari-made VCS game) runs the neutral zone: a shimmering, churning band of multicolored static the player’s insect hero can hide in. It looks like deliberate visual noise. It is something stranger: you are looking directly at the game’s own program.

The picture is the code#

Howard Scott Warshaw had no spare ROM for a dedicated graphic — a 4 KB cartridge leaves nothing to waste. So instead of storing a pattern, he pointed the display at memory the program already contained: the neutral zone reads its bytes straight from the section of ROM that holds the game’s code, cycling through it so the bytes scroll and shimmer rather than sit still. The instructions that run the game do double duty as the texture on screen.

Numbers & Arithmetic

Mon, 01 Jan 0001 00:00:00 +0000

Numbers & Arithmetic#

Thinking in Bits covered a byte as a pattern of switches. This page is about a byte as a number — and the surprising limits of doing math on a 1977 processor. The big ones: there are only 256 possible values, negative numbers are a convention rather than a feature, and the 6502 cannot multiply or divide at all.

A byte is 0–255 — or −128 to 127#

An 8-bit byte holds 256 distinct values. Read as unsigned, that’s 0 to 255. But the CPU has no separate “signed” type; instead, by convention, the top bit is treated as a sign using two’s complement:

A Grab Bag of Clever Abuses

Mon, 01 Jan 0001 00:00:00 +0000

A Grab Bag of Clever Abuses#

Not every exploited quirk got its own legend like Cosmic Ark or Yars’ Revenge. Many became everyday tools — techniques born from a limitation that programmers simply learned to live inside. A sampler.

Flicker: more objects than the hardware has#

The TIA gives you exactly two players. Plenty of games need to show three, four, or a dozen moving things — the ghosts chasing Pac-Man, a field of asteroids, a wall of Warlords bricks. The answer is flicker: draw some objects on even frames and the rest on odd frames, reusing the same two players for different things each pass. At 60 frames a second, each object appears only 30 times a second, and the eye mostly fuses them into a steady crowd.

Adventure (1980)

Mon, 01 Jan 0001 00:00:00 +0000

Adventure (1980)#

Adventure — Warren Robinett, Atari — put an entire explorable world on the console: roughly thirty connected rooms, items you carry one at a time, three dragons that hunt you, a thieving bat, and locked castles opened with keys. It was the first action-adventure game on a home console, packing an astonishingly rich world into a 4 KB cartridge. It’s also famous for its hidden “Created by Warren Robinett” room — widely regarded as the first famous Easter egg in a video game, and the one that popularized the tradition of hiding secrets for players to find.

Multi-Line Kernels

Mon, 01 Jan 0001 00:00:00 +0000

Multi-Line Kernels#

Counting cycles eventually delivers bad news: there are jobs that simply don’t fit in one 76-cycle line. Updating both players, fetching their colors, advancing their counters, and still leaving room for the draw — added up, it overflows. When a single line can’t hold the work, you stop trying to do it in one.

Spread the work across two lines#

A two-line kernel runs its loop body once for every two scanlines. The TIA still draws every line — the beam doesn’t slow down — but your code now has roughly two lines’ worth of cycles to prepare what those lines show. You split the work: some on the first line, the rest on the second.

Paddles

Mon, 01 Jan 0001 00:00:00 +0000

Paddles#

Everything so far has been a switch: on or off, one bit. Paddles are different — they’re analog, a knob that turns through a continuous range — and the VCS has no analog-to-digital converter. Reading one is a small, clever piece of analog timing, and it’s the most unusual input on the machine.

Reading time, not voltage#

A paddle is a potentiometer: turning the knob changes a resistance. The TIA reads it by charging a capacitor through that resistance and timing how long the charge takes — a low resistance charges fast, a high resistance slowly. The charge time is the knob position.

Playing Music

Mon, 01 Jan 0001 00:00:00 +0000

Playing Music#

A steady tone is just six registers holding their values. Music is what happens when you change them on a schedule — and the schedule is the frame. A small routine, run once per frame, reads a song out of a data table and updates the audio registers; that routine is a sound engine, and even a tiny one carries a whole tune.

A song is a data table#

The simplest useful format is a list of (note, duration) pairs — which is exactly what the Song table in xmas/xmas.asm is: a note index and a length in frames, terminated by a zero:

Size & Copies (NUSIZ)

Mon, 01 Jan 0001 00:00:00 +0000

Size & Copies (NUSIZ)#

There are only two players, but a single register stretches what they can do. NUSIZ0 and NUSIZ1 (one per player) set a player’s width and let the TIA stamp out multiple copies of it across the line — and the same register sizes that player’s missile. It’s the cheapest way to get more than two objects on screen at once.

Player width and copies#

The low three bits of NUSIZ choose one of eight modes:

The DPC: A Coprocessor in the Cartridge

Mon, 01 Jan 0001 00:00:00 +0000

The DPC: A Coprocessor in the Cartridge#

Bankswitching adds ROM and the Superchip adds RAM, but both are still just memory — passive storage the CPU does all the work against. Pitfall II: Lost Caverns (1984) took the idea to its conclusion: David Crane designed a custom chip, the DPC — officially the Display Processor Chip, though the initials are also his own (David Patrick Crane) — and built it into the cartridge. It was the first — and in the commercial 2600 era, essentially the only — game cartridge with a coprocessor of its own. The console did nothing new; the cart did the new thing.

The Instruction Set

Mon, 01 Jan 0001 00:00:00 +0000

The Instruction Set#

The 6502’s instruction set is small — about 56 mnemonics — and you can write whole games with maybe two dozen of them. This page is a grouped tour, not an exhaustive datasheet: enough to recognize what you read and reach for what you need. Cycle counts live in Cycles & Timing; flag effects are in Registers & Status Flags.

Moving data#

The most common instructions by far — nothing computes until data is in a register.

The Memory-Mapped Interface

Mon, 01 Jan 0001 00:00:00 +0000

The Memory-Mapped Interface#

On the VCS you talk to hardware by reading and writing memory addresses. The chips that make sound, draw pixels, and read the joystick live in the same address space as RAM, so a sta to the right address isn’t storing data — it’s operating a chip. This page assumes the bit literacy from Thinking in Bits; here we cover where those bits go.

Registers are just addresses#

The 6502/6507 has exactly one kind of “talk to the outside world” instruction — the same loads and stores it uses for RAM. There is no separate I/O instruction. Instead, the TIA (graphics/sound), the RIOT (RAM, timer, and joystick/switch ports), and the cartridge ROM are all wired to respond to specific addresses. This is memory-mapped I/O: the chip behind an address decides what reading or writing it actually does.

The Frame Structure

Mon, 01 Jan 0001 00:00:00 +0000

The Frame Structure#

The TIA produces no picture on its own — your code defines the frame by toggling the VSYNC and VBLANK signals at the right times and spending the right number of scanlines in each region. An NTSC frame is 262 scanlines, conventionally divided as:

Region	Lines	Purpose
VSYNC	3	Tells the TV “new frame starts here.”
VBLANK	37	Top blanking. The picture isn’t visible yet — do game logic here.
Visible	192	The kernel. Everything the player sees is drawn here, one line at a time.
Overscan	30	Bottom blanking. Read input and collisions, update state.

The beam paints 262 lines top-to-bottom; only the 192 visible lines carry picture. Press play, then scrub to freeze any moment.

Vertical sync#

A frame begins by turning on VBLANK and VSYNC, then holding VSYNC for exactly three scanlines:

Color: Hue & Luminance

Mon, 01 Jan 0001 00:00:00 +0000

Color: Hue & Luminance#

The TIA holds exactly four color registers, one for each thing it can draw:

Register	Colors
`COLUBK`	the background
`COLUPF`	the playfield (and the ball, which borrows it)
`COLUP0`	player 0 (and missile 0)
`COLUP1`	player 1 (and missile 1)

Each takes a single byte, and each is latched — write it once and it sticks until you overwrite it. Set COLUBK during startup and the background stays that color for the whole game without you ever touching it again. That, and the fact that you can rewrite a color register mid-frame, are the two facts the rest of this page rests on.

The Three Registers

Mon, 01 Jan 0001 00:00:00 +0000

The Three Registers: PF0, PF1, PF2#

Everything the playfield does starts with three 8-bit registers — PF0, PF1, PF2 — and the 20 bits of them the TIA actually draws. This page lays out exactly which bit lights which pixel. We will stay on the left half of the screen the whole way; the other half turns out to be a story of its own.

What one “pixel” is#

First, what these bits paint. A playfield pixel is a virtual block, generated on the fly by the TIA as the beam passes — not a dot in any frame buffer. Each is 4 color clocks wide and exactly one scanline tall. The playfield has no vertical resolution of its own: a pixel is one scanline high, and a taller block is just the same bits held unchanged across consecutive lines — exactly how the Christmas-tree kernel grows its shape.

ARM Cartridges

Mon, 01 Jan 0001 00:00:00 +0000

ARM Cartridges#

The DPC put one small custom chip on the cartridge and let it do a few jobs the 6507 couldn’t spare cycles for. Modern homebrew takes that exact idea and pushes it as far as it will go.

Today’s Harmony and Melody cartridges, together with the DPC+ and CDF programming models, take exactly the same idea to its conclusion. Hidden behind the cartridge edge connector is a modern ARM microcontroller running at hundreds of megahertz. To the Atari, it still appears to be an ordinary ROM with a handful of special registers. Behind the scenes, however, the ARM is decompressing graphics, streaming music, copying data, calculating game logic, and emulating the original DPC hardware — all while the humble 1.19 MHz 6507 remains blissfully unaware.

Cycles & Timing

Mon, 01 Jan 0001 00:00:00 +0000

Cycles & Timing#

On most computers an instruction’s cycle count is trivia. On the VCS it is the central fact of the craft: every visible scanline is 76 CPU cycles, and a kernel that needs 77 doesn’t run slow — it tears the picture. This page is the reference for counting them.

A “machine cycle” is one tick of the 6507’s ~1.19 MHz clock; the TIA runs at three times that, so one CPU cycle = three color clocks (three pixels). You budget in CPU cycles and the picture pays out in pixels.

Driving & Keyboard Controllers

Mon, 01 Jan 0001 00:00:00 +0000

Driving & Keyboard Controllers#

The joystick, paddle, and console switches are the common cases — but the same controller ports accept stranger devices, and two are worth knowing because they show how flexible the VCS’s I/O really is. The driving controller is a paddle look-alike that isn’t analog at all, and the keyboard controller is a twelve-key matrix. Both are built entirely from the SWCHA and INPT registers you’ve already met.

Front-Loading & Tables

Mon, 01 Jan 0001 00:00:00 +0000

Front-Loading & Tables#

The last way to fit work into a 76-cycle line is to not do it on that line. Two habits push work out of the hot path: front-loading — computing a line’s data before the line needs it — and tables — computing it before the program even runs. Both trade something plentiful (earlier time, ROM) for something scarce (cycles in the critical window).

Front-loading: be early#

In the moment the beam reaches a sprite, you have just a few cycles to put the right byte in GRP0. If those cycles are also spent deciding which byte — fetching a pointer, adding an offset, looking up a color — you’ll overflow. So you do that deciding earlier, during the slack of the previous line, and leave only a fast store for the critical instant.

Missiles & the Ball

Mon, 01 Jan 0001 00:00:00 +0000

Missiles & the Ball#

The other three movable objects — two missiles and one ball — are the TIA’s single-bit shapes. They have no bitmap; each is just a solid colored rectangle whose only graphic choice is its width. That makes them cheap to position and toggle, which is exactly what you want for bullets, balls, and small markers.

The missiles#

Missile 0 and missile 1 are turned on by ENAM0 / ENAM1 and positioned with the same strobe-and-HMOVE dance as the players (RESM0/RESM1, HMM0/HMM1). The catch — and the convenience — is color: a missile has none of its own. M0 always draws in player 0’s color (COLUP0), M1 in player 1’s. A missile is, by design, this player’s projectile.

River Raid (1982)

Mon, 01 Jan 0001 00:00:00 +0000

River Raid (1982)#

River Raid — Carol Shaw, Activision — flies a jet up a winding river that never ends: shoot the ships, helicopters, and jets, blow the bridges, and watch the fuel gauge, because the banks keep narrowing. It was one of the best-selling and most acclaimed games of the era, and a landmark for another reason — Shaw was among the first women to design and program a commercial video game, and River Raid is her masterpiece. The disassembly here is Thomas Jentzsch’s.

Symmetry: Reflection & Repetition

Mon, 01 Jan 0001 00:00:00 +0000

Symmetry: Reflection & Repetition#

The three registers gave you 20 bits — the left 20 pixels of a 40-pixel-wide screen. You never wrote the other 20. This page is where they come from.

The TIA generates the right half automatically from those same 20 bits, and a single flag decides whether it does so as a copy or a mirror. That is why the playfield is inherently symmetric: one write of PF0/PF1/PF2 per line paints the whole 40-pixel width, but both halves are built from the same bits.

The Asymmetric Playfield

Mon, 01 Jan 0001 00:00:00 +0000

The Asymmetric Playfield#

Symmetry is the playfield’s default because its 20 bits describe only the left half and the TIA mirrors or copies them onto the right. To show two different things on the two halves — a genuinely asymmetric playfield — you have to break that deal. The escape hatch is timing.

The TIA reads the registers as it goes#

The crucial fact: the TIA does not snapshot PF0/PF1/PF2 at the start of the line. It reads them continuously as the beam sweeps across, consulting each register at the exact moment the beam reaches the pixels it controls. So if you rewrite the registers partway across the line — after the beam has drawn the left half, but before it reaches the right half — the right half is built from the new values. The two halves now differ.

Building a Scoreboard

Mon, 01 Jan 0001 00:00:00 +0000

Building a Scoreboard#

A two-player scoreboard is the textbook use of an asymmetric playfield — two different numbers, one on each half of the screen — and it pulls together nearly everything in this chapter: digit graphics drawn from the playfield, bit masking to pack two digits into a byte, the no-multiply ×5 index trick, and BCD arithmetic to keep the count in decimal.

The code here is illustrative — the repository doesn’t ship a scoreboard project yet. Treat the snippets as sketches of the technique, not a drop-in kernel.

Object Priority

Mon, 01 Jan 0001 00:00:00 +0000

Object Priority#

When two objects cover the same pixel, one of them has to win — and which one shows in front is object priority. This is a separate question from collisions: collision detection only tells you that two objects overlapped, never which was drawn on top. Priority is what decides the picture.

The default order#

The TIA ranks the six things it can draw in a fixed order. Highest priority is drawn in front:

Should You Extend at All?

Mon, 01 Jan 0001 00:00:00 +0000

Should You Extend at All?#

This chapter has watched a cartridge grow from a slab of read-only memory into a machine carrying its own ARM computer. Which leaves an honest question hanging over all of it: just because you can put a supercomputer in the slot, should you?

The clearest way to think about it is to follow one game through three lives.

Three Pac-Mans#

1982 — the original. Atari handed Pac-Man to Tod Frye — a capable programmer who’d actually wanted Defender and got Pac-Man by default — under enormous corporate pressure: ship the most-wanted arcade game of the year in time for the holidays, on the cheapest cartridge the company would pay for (a single 4 KB chip), against a deadline that left no room to refine it. The result became the best-selling game on the entire system and a byword for disappointment — the ghosts flickered relentlessly, the colors looked nothing like the arcade, the whole thing played like a rough sketch of the real game. Atari pressed something like twelve million copies — more carts than there were consoles to play them — and it turns up in nearly every story told about the 1983 crash. The lesson everyone drew at the time was simple, and wrong: the 2600 just can’t do Pac-Man. The fault was never the programmer’s talent; it was the calendar and the boardroom — the very same pressure that, that same year, gave Howard Scott Warshaw about five weeks to make E.T. and turned the designer of the brilliant Yars’ Revenge into the other name blamed for the 1983 crash.

Space Invaders (1980)

Mon, 01 Jan 0001 00:00:00 +0000

Space Invaders (1980)#

Space Invaders — Rick Maurer, Atari — was the first officially licensed arcade game to land on a home console, and it changed everything. It was the 2600’s killer app: the cartridge people bought the console in order to play, widely credited with roughly quadrupling hardware sales in 1980 and turning the VCS from a curiosity into a phenomenon. Maurer’s port is also a quiet masterclass in TIA economy — it fills the screen with marching aliens using astonishingly little hardware. The disassembly here was produced from the cartridge with DiStella.

The Stack & Subroutines

Mon, 01 Jan 0001 00:00:00 +0000

The Stack & Subroutines#

The stack is the 6502’s scratch area for return addresses and saved values, and subroutines (JSR/RTS) are built on it. On most 6502 systems it’s an afterthought. On the VCS it deserves real care, because the stack and your variables share the same 128 bytes of RAM — and can run into each other.

How the stack works#

The stack pointer S is an 8-bit offset into a fixed region, and it grows downward:

Sprite Multiplexing

Mon, 01 Jan 0001 00:00:00 +0000

Sprite Multiplexing#

The TIA gives you two players, and — unlike ROM or RAM — no cartridge hardware adds more. The two-sprite limit is one you beat in software. Yet games routinely show a screen full of enemies, shots, and characters; they do it by time-sharing the two players — reusing each one to be several different things, either down the screen or across frames.

Reuse down the screen#

The key realization: a player only occupies the scanlines you actually draw it on. If two objects never share a scanline, one player can be both of them — enemy A in the top third of the screen, enemy B in the middle, enemy C at the bottom, all drawn by the same player 0 in a single kernel.

Video Chess (1979)

Mon, 01 Jan 0001 00:00:00 +0000

Video Chess (1979)#

Video Chess — Larry Wagner (the chess engine) and Bob Whitehead (the kernel and display), Atari — is the one that shouldn’t fit. It is a real chess program: it knows the legal moves, it looks ahead, it plays a whole game against you at eight levels of strength. And it does all of that in 4 KB of ROM and 128 bytes of RAM — less working memory than a single line of this paragraph. By legend it almost didn’t ship: Atari had advertised a chess cartridge in its earliest VCS catalog, couldn’t deliver for a year or two, and — the often-told story goes — a customer’s threatened lawsuit over the no-show product is what finally pushed it out the door in 1979.

Cosmic Ark (1982)

Mon, 01 Jan 0001 00:00:00 +0000

Cosmic Ark (1982)#

Cosmic Ark — Rob Fulop, Imagic — casts you as a sort of Noah in orbit: a great ark sweeping the galaxy to rescue pairs of animals from dying worlds. It plays in two alternating acts — fend off a meteor storm from the center of the screen, then drop to a planet and lift creatures aboard with a tractor beam. It’s a fine game. But it is remembered for four instructions.

Breakout (1978)

Mon, 01 Jan 0001 00:00:00 +0000

Breakout (1978)#

Breakout is where the VCS came from. The 1976 arcade machine was conceived by Nolan Bushnell and Steve Bristow as a one-player Pong with a wall to chip away at, and the prototype was built — famously, over a few sleepless nights — by Steve Wozniak, with Steve Jobs handling the deal with Atari (and, the story goes, the bonus). The 1978 cartridge brought it home. It is Pong’s child: a ball, a paddle, and a wall of bricks.

Choosing the Chip

Mon, 01 Jan 0001 00:00:00 +0000

Choosing the Chip#

“EPROM” is the traditional name, but you have a few families to pick from, and the choice mostly comes down to how painful it is to reprogram when you find a bug — and you will find bugs.

The three families#

Family	Examples	Erase method	Reusable?	Notes
UV EPROM (windowed)	2716, 2732, 2764, 27256, 27512	UV light (~15–20 min in a UV eraser box)	Yes, many times	The classic. The quartz window over the die lets a UV eraser box wipe it clean for reuse. Just keep the window covered with a sticker in normal use, or ambient UV slowly corrupts it.
OTP EPROM (no window)	same part numbers, plastic package	—	No — one shot	Electrically identical die, but the plastic package has no window, so there’s no way to get UV to it. Programs once, then it’s permanent. Cheap for production; avoid while iterating.
EEPROM	28C16, 28C64, 28C256	Electrically, in the programmer	Yes, instantly	No UV lamp. Slightly pricier, sometimes slower write, very convenient for iteration.
Flash / “electrically-erasable EPROM”	W27C512, W27C020 (Winbond), SST39SF	Electrically, in the programmer	Yes, instantly	Cheap, reusable, no UV — the modern homebrew favorite. The Winbond W27C512 is a drop-in-ish 27512 replacement that erases in the programmer.

For iterating on a game, pick something electrically erasable (EEPROM or a Winbond/SST flash part). Reserve UV EPROMs for when you specifically want the vintage experience or already own a stack of them — the burn → test → “oops” → 20-minute-erase cycle gets old fast.

Preparing the ROM Image

Mon, 01 Jan 0001 00:00:00 +0000

Preparing the ROM Image#

The bytes you send to the programmer are not always the bytes DASM emitted. Two things have to be right: the reset vectors must land at the very top of the address the console fetches from, and the image must fill the chip in a way the cartridge wiring expects.

The reset vectors must be at the top#

When the console powers on, the 6507 reads its program-counter start address from the reset vector at $FFFC/$FFFD. On the cartridge that is the last two bytes of ROM space. Every ROM in this book ends with:

Wiring the Cartridge

Mon, 01 Jan 0001 00:00:00 +0000

Wiring the Cartridge#

Once the chip is programmed it has to be wired into something the console’s cartridge slot can read. This is where the project leaves software and becomes electronics — and where the mistakes stop being syntax errors and start being bus contention and floating address lines.

Strong recommendation: copy the connections from a proven, published cartridge schematic or reproduction PCB (AtariAge has well-documented designs) rather than improvising them. The pin-level details below are to help you understand and verify such a design, not to reverse-engineer one from scratch. This is the one part of the pipeline where “close enough” produces hardware that intermittently works, which is worse than hardware that never works.

Gotchas: Works in Stella, Dies on Hardware

Mon, 01 Jan 0001 00:00:00 +0000

Gotchas: Works in Stella, Dies on Hardware#

This is the page worth bookmarking. The bugs here share a signature: the game is perfect in the emulator and wrong on the console. That signature is diagnostic — it means the fault is in an assumption the emulator papers over, not in your game logic.

RAM is not zero on real hardware#

Stella conveniently clears the 128 bytes of RAM at startup. A real 6507 powers on with RAM full of random garbage. If any of your code reads a variable before writing it — a counter, a flag, a sprite position — it works in Stella (where it read 0) and does something random on hardware.

Programming the Atari VCS in Assembly

Introduction

Introduction#

Pong (a minimal teardown)

Pong (a minimal teardown)#

Combat (1977)

Combat (1977)#

Cosmic Ark's Star Field

Cosmic Ark’s Star Field#

A glitch nobody ordered#

Counting Cycles

Counting Cycles#

Budget from WSYNC to WSYNC#

Drawing a Player

Drawing a Player#

One byte, one row#

How a Television Works

How a Television Works#

The beam paints one line at a time#

Programming Across Banks

Programming Across Banks#

Registers & Status Flags

Registers & Status Flags#

The Audio Registers

The Audio Registers#

The Blue Box, Reborn

The Blue Box, Reborn#

The Collision Registers

The Collision Registers#

Detection is geometric, and it latches#

The Joystick

The Joystick#

One byte, two joysticks#

Toolchain: DASM & Stella

Toolchain: DASM & Stella#

Installing#

Assembling a ROM#

Anatomy of a Minimal ROM

Anatomy of a Minimal ROM#

The header#

Reading 6502 Assembly

Reading 6502 Assembly#

The Processor (CPU)

The Processor (CPU) — a 6507#

A 6502 with its wings clipped#

The Video & Sound Chip (TIA)

The TIA: Programming the Television#

What the TIA handles#

Memory, I/O & Timer (RIOT)

The Memory, I/O & Timer chip (RIOT) — a 6532#

RAM — your 128 bytes#

The Program ROM

The Program ROM — your cartridge#

Where it lives#

Addressing Modes

Addressing Modes#

Buttons & Console Switches

Buttons & Console Switches#

Fire buttons (INPT4 / INPT5)#

Extra RAM

Extra RAM#

Cartridge RAM, and the two-port trick#

Horizontal Positioning

Horizontal Positioning#

Step one: strobe to a coarse position#

Pitfall! (1982)

Pitfall! (1982)#

Reading & Clearing

Reading & Clearing#

Testing a latch with BIT#

Thinking in Bits

Thinking in Bits#

Tones, Noise & Pitch

Tones, Noise & Pitch#

AUDC: pick a voice#

Waiting Precisely

Waiting Precisely#

Yars' Revenge's Neutral Zone

Yars’ Revenge’s Neutral Zone#

The picture is the code#

Testing a latch with `BIT`#