V20 v1.2b - VIC 20 Emulator for DOS (c) Lance Ewing 1996 COPYRIGHT As the copyright owner of this work, I have the exclusive rights to copy the work, to issue copies to the public whether by sale or otherwise, to make an adaption of the work, and to authorise another person to do any of these acts. If I don't give you authorisation, then technically you are infringing copyright. Since I'm such a nice guy and I don't like emulators which have registered versions, I hereby authorise anyone who reads this document to copy V20 and to distribute copies to the public as long as it is free of charge. Now that you're protected, I'd better protect myself. DISCLAIMER The author of this software has used his best efforts in writing it to ensure that no damage can result from its use. However, the author makes no warranty of any kind, expressed or implied, with regard to the program, data or documentation included with the program archive. The author shall not be liable in any event for incidental or consequential damages in connection with, or arising out of, the furnishing, performance, quality, or use of the programs, data or documentation included in this archive. A NOTE BEFORE STARTING From now on the archive called V20DOS.ZIP will contain the latest release and the archive called V20PLUS.ZIP will contain the most up to date test version. The test version will become the next release once all the major errors of that test version are corrected. Sometimes the two ZIPs may be indentical. This will be the case if a new version has just been released and there is therefore no test version. THE ROM FILES You will need the following three ROM files to get this emulator working: BASIC.ROM KERNEL.ROM CHARGEN.ROM These files must have the names as given above. If you do not have the above ROMs, they are available on the net at various VIC 20 related sites. The best place to get them is probably at ftp.funet.fi/pub/cbm/firmware/vic20. The character generator ROM is in a separate directory off the firmware directory which contains the character ROMs for all the cbm machines. WHAT'S NEW - Version 1.2b has corrected only one problem with the 6502 emulation which caused the scores in some games to display funny characters. I thought that I'd better fix this up to keep you all happy while I work on the next version. The following errors have been reported but not yet corrected: - (See GAMES.TXT) - The program list can only display about 200 files and then causes problems. WHAT TO LOOK FORWARD TO - Define your own keyboard layout. - A function key which shows the default keyboard layout. - Hopefully more speed. I'm planning to use a 32 bit C compiler for the next release rather than the 16 bit compiler I have been using so far. - Full speed graphics emulation with proper timing. Things currently emulated: 6502 processor 6561 Video Interface Chip Graphics Sound (Should be loud enough now) 6522 Versatile Interface Adapter Timers Keyboard Joystick (Cursor keys instead of IBM joy. SPACE = fire) Using an IBM joystick has proved to be a problem. As far as I'm aware the only way to read an IBM compatible joystick is to write a value to the joystick port and then wait until the answer comes back. This time interval will give the x or y axis. This waiting tends to bring the emulator to a shameful crawl. Most games seem to need joystick input so I've had to provide some method of control. The cursor keys take care of that job. This is now quite adequate but proper joystick usage would be a lot better. There is now a utility called JOYKEYS available at Rick Melicks site which will allow you to use a PC joystick with V20. It doesn't slow the emulator down and the joystick control is quite good. Inside the Emulator - PgUp, PgDn, Delete, and End can be used to move the screen around. - Esc to enter the debug monitor (and then q to quit). - Ins centres the screen. - F10 takes a snapshot to a file called SNAPSHOT.V20. - F11 brings up the menu system (Esc leaves the menu system). - F12 resets the VIC 20. The Debug Screen The debug monitor is still available by using the Esc key. When you push Esc you are presented with a '-' prompt. Type '?' for help. -? accumulator a byte begin b [address] BASIC load B filename cycles c value cartridge load C filename dump d [start] [end] enter e address byte goto g address instruction i load snapshot l [filename] picture p quit q registers r RAM size R size save snapshot s [filename] SAVE basic S filename turn off/turn on t unassemble u [start] [end] video mode v mode x register x byte y register y byte - Get used to this list of commands since you'll be using them a lot. I will now take you through the important ones. (1) begin b [address] This command will begin executing instructions from the current address stored in the program counter. When you first start the emulator, the PC will be set to the address stored in the reset vector. All you have to do to start the VIC is push b and then enter. Once inside the VIC the ESC key will take you back to the debug screen. Pushing b again will return you to the VIC at exactly the same point that you left it at when you pushed ESC. Very handy. (2) BASIC load B filename Loads a basic program into memory. You must have already set up for the required amount of RAM (discussed below) and already have started the VIC so that it is in basic. These steps will be discussed in another section. (3) cartridge load C filename [address] Plugs a cartridge into the back of the VIC. Once you have loaded a cartridge file into memory, you only need to type b to start. (4) load snapshot l [filename] A snapshot is a file which contains enough information to restore the VIC to the state that it was in when the snapshot was saved. This is very handy for saving your place in the middle of a game or saving a program you've written in basic. (5) picture p Shows what is currently being displayed on the VIC-20's screen. (6) quit q Exits the emulator. (7) RAM size R size Sets the ram size to be used. Size must be one of 0, 3072, 8192, 16384 or 24576. The ram must be adjusted to your desired size before you do anything else. The default value is as an unexpanded VIC. (8) save snapshot s [filename] Will save the current state of the VIC into a file. If a filename is not specified, then it will use the file SNAPSHOT.V20. All snapshot files will have the extension V20. (9) turn off/turn on t Effectively resets the emulator to the state it was in when you first ran the program from the command line. This must be done if you want to begin another task such as loading another game. (10) video mode v mode This option allows you to change to a different video mode. There are now three options available: Mode 0 : Standard 320x200. (FAST) Mode 1 : 208x264 tweaked mode. This one has the right aspect ratio but doesn't take up the whole screen as we would want it to. (FAST) Mode 2 : The mode used in Paul Robsons emulator. (Slower) I like using Mode 1 and I may even make it the default mode if it works okay on other peoples machines. (11) SAVE basic S filename At any stage when you want to save a basic program that you have written, push ESC and then use this option to save the program to disk. It can then be loaded using the B option. (12) cycles c value This is a new feature which allows the user to specify the number of 6502 machine cycles in between each scan line drawn. The values can be one of 128, 256, 384, 512, 640, 768, 896, 1024. The higher the value, the faster the emulator gets, and the more flickering you can see. This is a trade between speed and video quality I guess. (13) My Debug Commands The following won't be of much use to you unless you like debugging your way through 6502 machine code. Play around with them if you want. All addresses are in hex. accumulator a byte instruction i x register x byte y register y byte enter e address byte dump d [start] [end] registers r goto g address unassemble u [start] [end] HOW TO RUN GAMES USING THE MENU Well, I think most of you can work this out for yourself but here is a run down just in case. The first handy tip is that the menu system recognises cartridge files by the extension .CRT, BASIC programs and machine language programs that run from BASIC by the extension .PRG, and V20 snapshots by the extension .V20. (1) Cartridge files Press F11 to enter the menu system. Move along to CARTRIDGE and push down. Select the cartridge game you want to play and push enter. (2) Program files The main thing to remember when loading BASIC programs and machine language programs that run from BASIC is to set up the ram size and reset the emulator so that it is running BASIC with the correct expansion for the game. Press F11 to enter the menu system. Push down on OPTIONS. Change ram size to that required by the game. Move along to PROGRAM and push down. Select the program you want to load and push enter. Back inside BASIC type run to play the game. (3) Snapshots Just like loading a cartridge. Press F11 to enter the menu system. Move along to SNAPSHOT and push down. Select the snapshot you want to continue with and push enter. HOW TO RUN GAMES USING THE MONITOR MODE At the present time the only way to load Scott Adams games is by using the C option below with the address 3FFE (eg. -C pirate 3ffe ). There are two types of programs that can be run on this emulator. (1) Cartridge ROM files eg. Terraguard, Cosmic Jailbreak, Gorf, Menagerie. All you have to do is start the emulator, load the cartridge file and then push b to begin. C:\VIC20> v20dos -C terragua -b (2) Basic Programs and Machine Language programs that run from Basic. eg. Dark Dungeons, Galactic Abductor, Psycho Shopper, Bongo. These involve a few more commands. Firstly you need to choose the correct amount of ram which will depend on the size of the file. The wrong amount of ram will cause all sorts of problems. Secondly you will have to push b to make the VIC load BASIC. When the power up message is displayed and the cursor is flashing, push ESC to take you back to the debug mode. Now use B to load the file you want. Once this is done, go back into VIC basic by pushing b and enter. The program will now be loaded into memory. Type in RUN and push enter to start the program. C:\VIC20> v20dos -R 16384 -b ESC -B galabdct -b RUN You need only do this once for each game that you try because you can always save the state of the emulator into a snapshot file for easy loading next time. Finishing Note Let me know how you think it is going at this stage. If you know anything about programming, could you contact me to discuss ways around the many problems evident in this prerelease. Help of any kind is always appreciated. Thanks. Lance Ewing. be@ihug.co.nz http://shell.ihug.co.nz/~be/vic.htm