Odyssey² Computer Intro! emulator (Videopac 9)

The Odyssey² and Videopac 9

The Magnavox Odyssey² was a home video game console released in North America in 1978. Magnavox was owned by Philips, which sold the same console in Europe as the Philips Videopac G7000. Unlike most consoles of its time it had a full alphanumeric membrane keyboard built in. Its games came on cartridges, which in Europe were numbered: Videopac 1, Videopac 2 and so on.

Computer Intro! (Magnavox, 1979) used that keyboard to turn the console into a small programmable computer for learning machine code and assembly language. It came with a 104-page manual, A Beginner's Guide to Computer Technology. In Europe it was Videopac 9, sold by Philips as Computer Programmer and by Radiola as Programation. See its entry on odyssey2.info for more.

The emulator

An emulator of the Magnavox Odyssey² with the Computer Intro! cartridge (Philips Videopac 9) inserted, written in Go with Ebitengine so it runs on Windows, macOS and Linux.

The window shows a TV screen above a copy of the console keyboard as drawn in the manual. Click the keys or type on your own keyboard.

The cartridge turns the console into a small teaching computer, and that computer is what this emulator implements. It is built from the cartridge's manual (not included in this repository) and needs no ROM files:

• 16 registers (0–F), an accumulator, a program counter and a subroutine return register
• 100 program steps (00–99) that you enter in hex (machine code) or assembler
• an 11-position output line on the TV, with the 63 symbols from the manual's "Computer Symbols" chart
• all 8 operating modes: Command, Execution, Display, Program, Assembler, Hex Input, Input and Roll
• the full instruction set, including HLT for debugging
• the 4 built-in games: Creepy Crawler, Flash Card, Computer Telepathy and Between the Sheets
• the beep, one-second buzz and other sounds

Building

You need Go 1.27 or newer.

go build -o odyssey9 .        # odyssey9.exe on Windows
./odyssey9

• Windows: no extra setup. You can also cross-compile from any OS with GOOS=windows GOARCH=amd64 go build -o odyssey9.exe .

• macOS: install the Xcode command line tools (xcode-select --install). Build on a Mac, because macOS builds need cgo.

• Linux: install the X11, OpenGL and ALSA development headers first. On Debian/Ubuntu:

  sudo apt install gcc libx11-dev libxrandr-dev libxcursor-dev libxinerama-dev \
      libxi-dev libxxf86vm-dev libgl1-mesa-dev libasound2-dev pkg-config

To run the tests: go test ./machine. They run the programs from the manual and check what ends up on the screen. They also check that examples/ matches the programs in machine/samples.go. After changing a sample, regenerate the listings with ODYSSEY9_EXPORT=../examples go test ./machine. go test ./... also tests the window code. Ebitengine needs a display for that, so on a headless Linux machine run it under xvfb-run.

Command-line options:

Option	Meaning
-load FILE	load a program listing at start-up
-file FILE	file used by SAVE / LOAD (default ~/odyssey9-program.txt)
-monitor	start with the monitor panel open
-mute	no sound
-script KEYS	testing aid: type these keys at start-up (see below)
-screenshot FILE	testing aid: after the script has run, save a PNG of the window and quit (no sound)

If the emulator stops at start-up with an oto: or audio: error, your computer has no working sound output. Start it with -mute. If the sound output fails while you have an unsaved program, or the emulator is stopped from the terminal it was started in (Ctrl+C, or closing the terminal), it saves the program next to the SAVE file as odyssey9-recovered-….txt before it stops, or in the system's temporary folder if it can't write there. It prints where.

A -script is typed one key at a time. Letters, digits and the symbols in the PC keyboard table stand for themselves. {RESET}, {ENTER}, {CLEAR}, {YES}, {NO} and {SPACE} press those keys. {WAIT} pauses, and {HELP}, {PROGRAMS} and {SAVE} work like the emulator's buttons. While a panel is open, keys go to it, so {PROGRAMS}E loads the Message program. For example:

./odyssey9 -script "{RESET}PMI6B{ENTER}00{ENTER}" -screenshot out.png

Using it

Follow the manual. At power-on the screen says SELECT GAME:

• 1–4 start the built-in games.
• RESET (▲) gives you COMMAND, and from there:
  • E executes the program.
  • C continues after a HLT.
  • D is Display mode: 0–F show a register, P the program counter, S the subroutine register and X the accumulator.
  • P is Program mode: M for hex or A for assembler, then I to input or R to roll.
• In Input mode, type 6B, ENTER, 00, ENTER in hex, or LDV.B.00, ENTER in assembler. CLEAR steps back one mode.
• In Roll mode, U and D move through the steps. CLEAR returns to Program mode, so you can then press M/A and I to overwrite a step.
• Switching the power off (POWER button / F8) erases the program, just like the real console. If you haven't saved it, press POWER twice.

PC keyboard

PC key	Odyssey² key
letters, digits, . ? + - =, space	the same key
*	×
/	÷
[ / ]	YES / NO (Y and N have the same key codes, so they answer Between the Sheets too)
Enter	ENTER
Delete	CLEAR
Esc	RESET
Backspace	erases the last character you typed in Input mode, repeating while held (otherwise CLEAR)

Keys pressed while Ctrl, Alt or Cmd is held are left to your system as shortcuts and don't reach the console. AltGr and the Mac's Option key still type characters.

Emulator controls

There is a row of buttons under the TV, and each one also has a function key:

• POWER (F8) switches the console off and on.
• SPEED (F5) sets how fast programs run:
  • SLOW: 4 steps/s, for watching a program work
  • NORMAL: 1000 steps/s
  • FAST
• PROGRAMS (F4) loads any of the 14 programs printed in the manual. Click one, or press its key (1–9, A–E). Esc closes this panel and the help panel.
• SAVE (F2) / LOAD (F3) write and read your program as a text listing. You can also drop a listing file onto the window. To keep you from losing work, a few actions only happen when repeated within four seconds:
  • a SAVE that would replace a different program in the file, or a file it can't read
  • a LOAD, dropped file or PROGRAMS choice that would replace a program you haven't saved
  • POWER, which erases the program, when you haven't saved it
  • closing the window while you have a program you haven't saved
• MONITOR (F6) opens a side panel showing the registers, the accumulator, the program counter and a disassembly of program memory.
• F7 colours the characters the way the manual's symbol chart does.
• HELP (F1) shows a quick reference.

The examples/ folder holds the manual's programs as listing files.

Listing format

Each line has a decimal step number, then one or more two-digit hex bytes separated by single spaces. The bytes end at the first word that isn't one, or at a gap of two or more spaces or a tab. Everything after that is ignored, and so is any text after ; or #. So the step lines of the manual's tables load as they are:

; lines from the manual's tables
04   6B 00  LDV.B.00   Set output position to 00
30   1D 12 0E 0E 17 00  HELLO

Each step may be given only once, and a line may not run past step 99. A listing is plain text in UTF-8, or in UTF-16 with a byte order mark, as some Windows tools save it.

The manual's column headings and its remarks on lines of their own are not step lines: delete them, or start them with ;. A remark straight after the bytes needs two spaces in front of it. Otherwise one that starts with a hex-like word, such as BE QUIET, would be read as more bytes.

How the computer behaves

The manual doesn't spell out every detail, so some behaviour was worked out from its example programs. All 14 examples give the results the manual describes. For example, 9 ÷ 2 shows 04+R, Message 2 shows TAKE A LOOK and the Area program computes 8 × 3 = 24.

• Step numbers are decimal. GTO.15 is coded 12 15, and ADD, SUB, INC and DEC work in decimal. That is why 9+9 unpacks to the digits 1 and 8, and why Creepy Crawler II's 13 + digit lands on steps 13–22. The assembler rejects a branch target that isn't a step number, such as GTO.A5. If one gets in as hex, the monitor and listings show where it really goes: 12 A5 is GTO.A5 (=05). LDV still takes any hex value.
• SUB.R works out register − accumulator. DEC takes 00 down to 99. BDB branches when the accumulator's high digit is 9, and BDC when it is not 0.
• MOV loads the accumulator from the step whose number is in register C, then advances C by one. That is how the Message program walks through its text.
• OUT/OTA write at the position in register B (00–0A), which then advances and wraps from 0A back to 00.
• INP/INA show ? and wait for a key, which beeps. The value stored is the key code from the manual's Key Codes table (YES = 2C, NO = 2D, CLEAR = 2E, ENTER = 2F). Keys typed while a program isn't waiting are kept for its next INP/INA, up to 16 of them, and are dropped when it stops. After RESET at a ?, C waits for the key again.
• SIG buzzes for one second, and the program pauses while it sounds.
• HLT (FF) stops with HALT shown and puts you in Command mode. Then D P shows the step that holds the FF, and C continues from the following step, even after RESET or a visit to Program mode or a game.
• Undefined opcodes act as NOP. The manual's rule about adding a NOP after three outputs in a row was a hardware timing limit, and the emulator doesn't need it.
• The manual doesn't describe the screen layout of the built-in games in full, so their exact layout and timing are reconstructions from its text.

Project layout

Path	Contents
machine/	the emulated computer, with no GUI code: CPU and modes (machine.go), the instruction table shared by the CPU and the assembler/disassembler, and decimal arithmetic (asm.go), games, font, key codes, listing format, sample programs, tests
main.go, signals_*.go	command-line options, start-up, and stopping on Ctrl+C or a closed terminal with a recovery file
game.go	emulator state and the update loop
tv.go	drawing the TV screen and the buttons under it
input.go	function keys, mouse, typed keys and dropped files
files.go, files_*.go	SAVE, LOAD and loading the manual's programs, and the parts of saving that differ by system (Unix, Linux access control lists, Windows)
monitor.go, panels.go	the monitor panel, and the help and programs panels
keyboard.go	on-screen keyboard, and host keyboard mapping, including characters that come late from an input method
audio.go	sound synthesis
draw.go	resolution-independent drawing helpers
script.go	scripted key input and screenshots, used for testing (-script, -screenshot)

License

The emulator source code is released under the MIT License. The Computer Intro! manual is © 1979 Magnavox. It is not included in this repository and is not covered by this license.