Player/Missile Graphics in Atari BASIC: A Hands-On Introduction
Player/missile graphics (PMG, "P/M") are the Atari's hardware sprites: four 8-pixel-wide players and four 2-pixel-wide missiles that float over any graphics mode, have their own colours, move horizontally with a single POKE, and report collisions in hardware. Atari BASIC has no commands for them, which is why so many 1980s magazine articles were devoted to explaining them. The good news: once the memory is set up, PMG is far easier than moving shapes around screen memory.
What you'll learn: why PMG exists, how player memory is laid out, the registers involved, and a complete BASIC program that moves a player with the joystick and detects when it touches a wall.
What you need: Atari BASIC on any 400/800/XL/XE (or emulator), a joystick in port 1.
Why players are easy to move
Here's the problem PMG solves. A shape on a normal bitmap screen is scattered through memory — one byte here, the next 40 bytes further on — so moving it means recalculating and rewriting many addresses. A player, by contrast, is a one-dimensional strip: a table of 128 or 256 bytes, each byte drawn as one row of an 8-pixel-wide column running the full height of the screen. To move it vertically you shift bytes within that table. To move it horizontally you write a single number to its horizontal position register. That's all.
The memory layout
All player and missile data lives in one block whose start you tell ANTIC through PMBASE (54279, $D407 — it has no OS shadow). The block's size and alignment depend on the vertical resolution:
| Double-line resolution | Single-line resolution | |
|---|---|---|
| Each byte covers | 2 scan lines | 1 scan line |
| Block size | 1K (unused first 384 bytes) | 2K (unused first 768 bytes) |
| PMBASE alignment | 1K boundary | 2K boundary |
| Missiles (all four) | PMBASE + 384 | PMBASE + 768 |
| Player 0 | PMBASE + 512 | PMBASE + 1024 |
| Player 1 | PMBASE + 640 | PMBASE + 1280 |
| Player 2 | PMBASE + 768 | PMBASE + 1536 |
| Player 3 | PMBASE + 896 | PMBASE + 1792 |
| Bytes per object | 128 | 256 |
(In hex, the missile and player offsets are $180/$200 in double-line mode and $300/$400 in single-line mode.) The four missiles share one table: missile 0 uses bits 0–1 of each byte, missile 1 bits 2–3, missile 2 bits 4–5 and missile 3 bits 6–7. The unused space below the missiles is free for your own data.
Not every row is visible. The usual visible window is rows 16–111 in double-line mode (32–223 in single-line mode), and horizontal positions from about 48 (left edge) to 208 (right edge) for a standard-width screen. TVs vary, so 60–200 is a conservative horizontal range.
The registers you need
| Address | Name | Use |
|---|---|---|
| 559 ($22F) | SDMCTL | Shadow of DMACTL. 34 = normal screen; add 4 (missile DMA), 8 (player DMA) and 16 (single-line). So 46 = double-line PMG on, 62 = single-line PMG on |
| 53277 ($D01D) | GRACTL | 1 = missiles on, 2 = players on, so 3 enables both |
| 54279 ($D407) | PMBASE | Page number (high byte) of the P/M block |
| 53248–53251 | HPOSP0–3 | Horizontal position of players 0–3 (write) |
| 53252–53255 | HPOSM0–3 | Horizontal position of missiles 0–3 (write) |
| 53256–53259 | SIZEP0–3 | Width: 0 normal, 1 double, 3 quadruple |
| 53260 | SIZEM | Missile widths, two bits per missile |
| 704–707 | PCOLR0–3 | Player/missile colours (shadows; use POKE, not SETCOLOR) |
| 623 ($26F) | GPRIOR | Priority: 1 = players in front of playfield, 4 = playfield in front of players; +16 = combine missiles into a "fifth player" coloured by 711; +32 = overlapping players mix colours |
| 53252 ($D004) | P0PF | (read) Player 0 to playfield collisions: bit 0 = PF0 … bit 3 = PF3 |
| 53260–53263 | P0PL–P3PL | (read) Player to player collisions |
| 53278 ($D01E) | HITCLR | Write any value to clear all collision registers |
Note that several addresses do double duty: writing 53252 sets missile 0's position, reading it returns player 0's playfield collisions. So POKE 53248,PEEK(53248)+1 does not work — keep the position in a BASIC variable.
Finding safe memory
The OS puts the screen just below RAMTOP (location 106, a page number). The clean way to get memory it won't touch is to lower RAMTOP and then issue a GRAPHICS statement, which rebuilds the screen below the new limit. Forgetting the screen's own size is the classic cause of stray coloured dots in P/M displays — lowering RAMTOP before GRAPHICS avoids that problem altogether.
Beware the "RAMTOP Dragon" described by K. W. Harms in the same book: a GRAPHICS statement or screen clear erases the first 64 bytes above RAMTOP, and scrolling the text window of a split-screen GRAPHICS 3–8 display can erase up to 800 bytes above it. In the double-line layout the first 384 bytes are unused, so 64 bytes is harmless — but text-window scrolling would eat into your missiles and player 0. The program below avoids this by using a full-screen mode with no text window.
A complete example
10 REM *** PLAYER/MISSILE DEMO ***
20 A=INT((PEEK(106)-8)/8)*8:POKE 106,A
30 GRAPHICS 3+16:SETCOLOR 4,0,0:SETCOLOR 0,12,8
40 COLOR 1:PLOT 0,0:DRAWTO 39,0:DRAWTO 39,23:DRAWTO 0,23:DRAWTO 0,0
50 PLOT 20,6:DRAWTO 20,17
60 PM=A*256:POKE 54279,A
70 FOR I=PM+384 TO PM+1023:POKE I,0:NEXT I
80 POKE 704,88:POKE 53256,0:POKE 623,1
90 POKE 559,46:POKE 53277,3
100 P0=PM+512:X=80:Y=50
110 FOR I=0 TO 7:READ D:POKE P0+Y+I,D:NEXT I
120 DATA 24,60,126,219,255,36,90,165
130 POKE 53248,X:POKE 53278,0
200 S=STICK(0):DY=0
210 IF S=11 OR S=10 OR S=9 THEN X=X-1
220 IF S=7 OR S=6 OR S=5 THEN X=X+1
230 IF S=14 OR S=10 OR S=6 THEN DY=-1
240 IF S=13 OR S=9 OR S=5 THEN DY=1
250 IF X<48 THEN X=48
260 IF X>200 THEN X=200
270 IF Y+DY<16 OR Y+DY>104 THEN DY=0
280 POKE 53248,X
290 IF DY=0 THEN 350
300 IF DY=1 THEN 330
310 FOR I=0 TO 7:POKE P0+Y-1+I,PEEK(P0+Y+I):NEXT I:POKE P0+Y+7,0
320 GOTO 340
330 FOR I=7 TO 0 STEP -1:POKE P0+Y+1+I,PEEK(P0+Y+I):NEXT I:POKE P0+Y,0
340 Y=Y+DY
350 IF PEEK(53252)=0 THEN 380
360 SOUND 0,100,10,8:POKE 712,68
370 GOTO 390
380 SOUND 0,0,0,0:POKE 712,0
390 POKE 53278,0:GOTO 200
How it works
- Line 20 reserves 2K under RAMTOP, rounded down to a multiple of 8 pages so the block is 2K-aligned (good for either resolution).
- Line 30 opens a full-screen GRAPHICS 3 display (no text window, so no Dragon), black background, green COLOR 1. Lines 40–50 draw walls in playfield colour 0.
- Lines 60–70 point PMBASE at the reserved block and clear the missile and player area. In BASIC this loop takes a few seconds; you can skip it on reruns, but garbage in the area shows up as stray stripes.
- Line 80 sets player 0 to pink (88 = hue 5 × 16 + luminance 8), normal width, and priority "players in front".
- Line 90 turns everything on: SDMCTL 46 = 34 + 4 + 8 (double-line, missiles and players), GRACTL 3.
- Lines 110–120 copy an 8-row invader shape into player 0 at row Y. Each DATA value is one row of 8 pixels: 24 =
00011000, 255 =11111111and so on. - Lines 200–240 decode STICK(0): 15 is centred, 14 up, 13 down, 11 left, 7 right, and 10/6/9/5 the diagonals.
- Lines 300–330 move the shape one row up or down by copying its bytes and blanking the row it leaves behind — the "one-dimensional move" described above. The copy runs in the correct direction so the shape doesn't smear.
- Lines 350–390 read P0PF; since the walls are drawn in COLOR 1 (playfield 0), a hit sets bit 0. The program beeps, flashes the background red, then clears the collision registers with HITCLR. Collisions are only registered as the beam actually draws the overlap, which is why the right order is check, clear, then move — the BASIC loop is slow enough that this works naturally.
Variations
- Single-line resolution:
POKE 559,62, use P0 = PM+1024, clear PM+768 to PM+2047, and allow Y from 32 to 216. Movement steps become one scan line instead of two. - Bigger sprites:
POKE 53256,1(double) or 3 (quadruple width). - More colours: use players 0 and 1 side by side and add 32 to GPRIOR so overlapping areas take a third colour (the OR of the two player colours).
- Missiles: missile 0 occupies bits 0–1 of the bytes at PM+384 onward; set them with
POKE PM+384+Y,3, position it withPOKE 53252,X. - Faster vertical motion: a short USR routine or the string-move trick lets BASIC shift a whole player in one statement.
Cleaning up
Pressing BREAK leaves the player on screen, because turning off DMA stops new data reaching GTIA, but the last bytes stay latched in the graphics registers. Use:
POKE 53277,0:POKE 559,34:POKE 53261,0:POKE 53248,0
That disables GRACTL, restores normal DMA, clears player 0's latch (GRAFP0, 53261) and moves it off-screen. Note that each RUN of the demo lowers RAMTOP a further 8 pages; press RESET (which restores RAMTOP) before re-running, or keep the original value and POKE it back on exit.
Troubleshooting
- No player visible: check SDMCTL and GRACTL — both must be set. Check the horizontal position is between about 48 and 200 and that the shape is within the visible rows.
- Player appears twice or stretched: PMBASE is not on the required 1K/2K boundary, or the shape was poked into the wrong section (single vs double line offsets).
- Random coloured streaks: the P/M area overlaps screen memory or wasn't cleared.
- Collisions never register: you cleared HITCLR immediately before reading without letting a frame pass, or you are testing the wrong bit for the playfield colour you drew with.
Further reading
- De Re Atari (Atari, 1982), Chapter 4 — includes BASIC programs for masking a player and using one as a special character.
- Atari Player Missile Graphics in BASIC by Philip C. Seyer (Prentice-Hall, 1984) — a whole book on this topic for BASIC programmers.
- Mapping the Atari by Ian Chadwick (COMPUTE! Books) — every PMG register, with examples.
- COMPUTE!'s Second Book of Atari Graphics (1984) — the memory-positioning and RAMTOP Dragon articles.
- Companion guide on this site: Player/Missile Graphics in Assembly.
Credits
- Picture: The player/missile demo running: the player is moved by joystick and collisions with the green walls are detected in hardware. — Program authors; screenshot by the site
- De Re Atari, Chapter 4: Player-Missile Graphics — Chris Crawford (Section 4 of De Re Atari)
- Mapping the Atari (revised edition) — 53248-53279 GTIA, 54279 PMBASE, 559 SDMCTL, 623 GPRIOR, 704-707 — AtariArchives.org
- Altirra Hardware Reference Manual, sections 4.13 and 6.5-6.7 — Avery Lee (Altirra)
- COMPUTE!'s Second Book of Atari Graphics — Beware the RAMTOP Dragon (K. W. Harms) — AtariArchives.org
- COMPUTE!'s Second Book of Atari Graphics — Positioning Player/Missile and Regular Graphics in Memory (Fred Pinho) — AtariArchives.org
- atari8bit.net database — Atari Player Missile Graphics in BASIC (Philip C. Seyer) — Atari8bit.net
