by Joe McKenzie / Chupi
October 11, 2011
This is the same content as README.txt, except reformatted into basic Markdown.
I've seen some YouTube videos where people made games on oscilloscopes. But all those use "fancy" setups, like a digital scope with 2 beams and an FPGA to generate the signals to drive it. So I set out to make a game using just my old Knight Kit analog one-beam scope and a computer with a stereo sound card. This is the result.
There are 2 versions of this. Asteroids-scope (the "real" version) draws vector graphics and renders them to looping sound clips it plays. You need an oscilloscope and stereo sound card to use this one. Asteroids-window (the "fake" version) draws the exact same graphics, but renders them to a window on your computer screen. It produces no sound. You don't need any additional hardware to run it.
The faint rays flying around in the background are to help stabilize the picture on old analog oscilloscopes. The game draws things by moving the scope's beam around the screen. Since this is using a sound card and a not-fancy scope, it can't turn off the beam. It can move it really fast so it doesn't leave much of a trail though. After drawing every few objects, it moves the beam to a random corner of the screen and draws a faint border around the screen before moving it to the start of the next object. It does this up to 100 times a second, resulting in lines in the background that change quickly. (They have to change quickly because if the same faint line gets drawn over and over, it becomes bright due to the phosphors in the scope's CRT.)
These rays are also visible in the windowed, non-oscilloscope version of the program. The same code is running, and it doesn't know or care which of the two graphics library backends is attached to it.
On a real scope, wiggles or zigzags are visible where the beam enters and leaves some shapes. This is because the audio signal controlling it just made a big jump. The small audio amps found in PC sound cards do this, and you can see it if you play a square wave using the sound card and watch it on a scope, or record it using an audio program that lets you zoom in on the wave. You might get better results with a hi-fi amp connected via S/PDIF. (The S/PDIF part is very important -- otherwise you're still feeding the hi-fi amp the inferior original signal generated by the sound card's amp; S/PDIF is digital, so it avoids this.)
The wiggles and zigzags shake too. This is because of the picture stabilizing stuff above. If the stabilizer code always used the same screen corner, the wiggles wouldn't move from one frame to the next. But then those faint rays would get drawn over and over and be more visible. Also some shakiness helps hide image defects, as can be seen on older analog TVs.
At the title screen:
- Space = start new game
- M = cycle screen orientations/flips (if your scope or wiring is backwards)
During the game:
- left/right arrows = spin ship left or right
- up/down arrows = forward and reverse thrusters
- space = cannon
When you die: (ship breaks up and vanishes)
- R = respawn ship in the center of the screen (or in the middle of an asteroid, if that's what's in the center of the screen!)
Any time:
- Q or ESCape = quit
Note that you have infinite lives in this game, and there's no on-screen score indicator. This is to reduce the number of things on the scope screen. Otherwise it would flicker even more than the title screen.
You can see your score on the console/terminal/stdout.txt whenever you die.
System requirements:
- Windows (win32), Linux or Mac OS X - see below
- Stereo line-out or headphone jack on computer
Hardware and tools:
- Oscilloscope that has an option for an external horizontal drive signal (It might be called something else. On my Knight KG-635, you set the "H. SELECTOR" knob to "EXT" on the far right of the "AMP" zone. Anyhow, it's not horizontal sync. That won't work - you'll see waveforms instead of a picture.)
- Something you can chop a cord off of that has a 1/8" headphone plug and enough length of cord to reach from the computer's line out/headphone out to the scope.
- A knife, scissors, wire stripping tool, etc. Anything to take insulation off the audio cable.
Chop off the audio cable so you have a headphone plug you can connect to your computer, and enough wire to easily reach your scope. Note the wire colors. There will be 3-4 wires. Right is usually red, left usually green or white. Ground is usually either black or uninsulated. If your wires are colored but not insulated, they're enameled -- remove the enamel with fine sandpaper, a flame, or carefully with a knife.
Locate the vertical and horizontal inputs on your scope. Connect the left wire to vertical and right to horizontal. You might have to strip or split 6 inches of cable to make it reach the 2 inputs.
If you don't know which one is right or left, it doesn't matter. The software can handle it so long as you have one channel attached to vertical and one attached to horizontal. Polarity of each channel doesn't matter either. (Press the "M" key on the game's title screen to cycle through all (8) possible permutations of backward left, backward right, and switched left and right.)
Now you have 1 or 2 ground wires left. Connect them to the scope's ground terminals. There's most likely a ground terminal next to each input. If you only have 1 ground wire (as with many headphones), connect it to one terminal. It might help to run a separate wire between the ground terminals if you only have one ground wire.
Make sure your wires are screwed down tight. If you like, you can now connect an iPod or other audio source to the headphone plug and play some music through it. In normal mode, the scope should show one channel of the sound. If you set it to external horizontal drive, you should see an interesting blob pulsing and wiggling to the music.
Plug the headphone plug into the computer's line out or headphone jack. Make sure your computer is set to play sound to that jack, plug the cable in and turn the volume to the max. Now launch asteroids-scope.
If you like, use a splitter to connect speakers so you can hear the picture. :) However, noises in the room might then affect the picture, since speakers also act as microphones, and splitters don't stop signals from going the other way.
This package includes binaries for Windows, Linux and Mac, plus source code.
Windows binaries: Run one of the .exe files in the bin-windows folder. Note that under Windows you won't see any console messages. They'll be written to a file named stdout.txt.
Mac binaries: Mount bin-mac-intel.dmg and its contents will open. The .app files will run without any additional software, and have been tested on a fresh install of Mac OS X 10.7 Lion. The downside is that console output is hidden. The raw UNIX executables open a Terminal window, but require SDL to be installed. You can get SDL from libsdl.org, or right-click one of the .app packages, "Show Package Contents", browse to Contents/Frameworks, and drag the SDL.framework folder into /Library/Frameworks in Macintosh HD. (The Mac binaries are Universal Intel Binaries. They will run on any Intel Mac. PPC isn't supported because I can't properly compile for PPC on Snow Leopard.)
Linux (Intel 32-bit) binaries: You need SDL (libsdl) installed, but it comes pre-installed on many modern Linux distros, like Ubuntu. You might need to chmod +x them before they'll run. That is, open a terminal window and type chmod, a space, +x, another space, then drag asteroids-scope or asteroids- window onto the terminal, and then hit enter.
Requirements, Windows:
- MinGW installed
- libsdl development files for MinGW installed. Download from libsdl.org and unpack in C:\MinGW or wherever your MinGW root is.
- SDL.dll. You can get this from the bin directory of the libsdl dev package for MinGW. Copy it into the src dir of this package.
Build from a MinGW prompt, not plain cmd.exe. Otherwise you won't have all the UNIX utilities needed. Navigate to the src directory and run "make".
Requirements, Linux:
- build-essential (Debian/Ubuntu/etc.; you need make and gcc)
- libsdl1.2-dev (or however you get the SDL dev files on your distro)
Go to the src directory and run make.
Requirements, Mac:
- XCode. You won't be using XCode itself, but it brings in all the Mac OS X development utilities.
- The MacPorts or Fink version of SDL. For MacPorts, "sudo port install libsdl" should do it. I built and tested with MacPorts, not Fink. (The libsdl.org one WILL NOT work. It only works if you do everything in XCode, which I don't because I want my stuff to be cross-platform.)
Go to the src directory and run make. If you want pretty Mac .app packages instead of UNIX executables that run in Terminal, make macapps. Also note that the makefile includes a target to make Mac redistributables -- .app packages with universal binaries and built-in SDL.framework. See makefile comment.
main.c : Initialization and game program
gfx.h : Vector graphics library header
gfx.c : Vector graphics output-to-audio code
gfx_debug.c : Vector graphics output-to-window-on-the-screen code
asteroids_objects.h : Assorted vector shapes for the game, in polar coordinates
Reuploading due to MediaFire file deletion. Switching licensing to WTFPL. It said public domain before. I'm switching because of varied definations of "public domain" around the world. This way should be a little clearer: Anybody can do whatever they want with this code. No restrictions at all.
Reuploading due to the server it was on going down. Only change is I'm putting it on Github now, so the readme has been reformatted to Markdown.