README.md
1[](https://travis-ci.org/github/libretro/vice-libretro)
2
3# VICE LIBRETRO
4
5Port of VICE, the Versatile Commodore Emulator 3.3
6
7Source base: [https://sourceforge.net/projects/vice-emu/files/releases/vice-3.3.tar.gz](https://sourceforge.net/projects/vice-emu/files/releases/vice-3.3.tar.gz)
8
9Supported platforms: Linux, Windows, Apple, Android, emscripten, Switch, Vita
10
11## Default controls
12
13| RetroPad button | Action |
14|-----------------|-------------------------|
15| D-Pad | Joystick |
16| Left Analog | Mouse/paddles |
17| B | Fire button |
18| X | Space |
19| L2 | Escape (RUN/STOP) |
20| R2 | Enter (RETURN) |
21| Select | Toggle virtual keyboard |
22
23| Keyboard key | Action |
24|-----------------|-------------------------|
25| F12 | Toggle statusbar |
26| RControl | Switch between joyports |
27| End | Reset |
28
29### Virtual keyboard controls
30
31| Button | Action |
32|-----------------|-------------------------|
33| B / Enter | Keypress |
34| A | Toggle transparency |
35| Y | Toggle ShiftLock |
36| Start | Press Return |
37
38Long press for sticky keys. Stickying the third key will replace the second.
39
40## Joyport control
41
42Older C64 games tend to use joystick port 1 and newer ones tend to use port 2 for player 1. There are several ways to switch ports in this core:
43
44- Use the core option: `Quick Menu -> Options -> RetroPad Port`
45- Bring up the virtual keyboard with `Select` button, and press the key labeled `JOY`
46- Press the default keyboard shortcut `Right Control`
47- Assign `Switch Joyport` to any RetroPad button under `Quick Menu -> Options`
48- Rename the game, eg. `Bruce_Lee_j1.tap` or `Bruce_Lee_(j1).tap` for port 1, and similarly `Bruce_Lee_j2.tap` or `Bruce_Lee_(j2).tap` for port 2
49- Add `-j1` or `-j2` parameters in custom command line `.cmd`
50
51## M3U support and disk control
52
53When you have a multi disk game, you can use a M3U playlist file to be able to change disks via RetroArch "Disc Control" interface.
54
55A M3U file is a simple text file with one disk per line ([Wikipedia](https://en.wikipedia.org/wiki/M3U)).
56
57Example:
58
59`Ultima VI - The False Prophet (1990)(Origin Systems).m3u`
60```
61Ultima VI - The False Prophet (1990)(Origin Systems)(Disk 1 of 3 Side A)(Game).d64
62Ultima VI - The False Prophet (1990)(Origin Systems)(Disk 1 of 3 Side B)(Surface).d64
63Ultima VI - The False Prophet (1990)(Origin Systems)(Disk 2 of 3 Side A)(Dungeon).d64
64Ultima VI - The False Prophet (1990)(Origin Systems)(Disk 2 of 3 Side B)(Populace A).d64
65Ultima VI - The False Prophet (1990)(Origin Systems)(Disk 3 of 3 Side A)(Populace B).d64
66Ultima VI - The False Prophet (1990)(Origin Systems)(Disk 3 of 3 Side B)(Populace C).d64
67```
68
69Path can be absolute or relative to the location of the M3U file.
70
71When the game asks for it, you can change the current disk in the RetroArch "Disc Control" menu:
72
73- Eject the current disk with "Eject Disc"
74- Select the right disk index with "Current Disc Index"
75- Insert the new disk with "Insert Disc"
76
77By default, RetroArch will display the filename (without extension) of each M3U entry when selecting a disk via the `Current Disc Index` drop-down menu. Custom display labels may be set for each disk using the syntax: `DISK_FILE|DISK_LABEL`. For example, the following M3U file:
78
79`Ultima VI - The False Prophet (1990)(Origin Systems).m3u`
80```
81Ultima VI - The False Prophet (1990)(Origin Systems)(Disk 1 of 3 Side A)(Game).d64|Game
82Ultima VI - The False Prophet (1990)(Origin Systems)(Disk 1 of 3 Side B)(Surface).d64|Surface
83Ultima VI - The False Prophet (1990)(Origin Systems)(Disk 2 of 3 Side A)(Dungeon).d64|Dungeon
84Ultima VI - The False Prophet (1990)(Origin Systems)(Disk 2 of 3 Side B)(Populace A).d64|Populace A
85Ultima VI - The False Prophet (1990)(Origin Systems)(Disk 3 of 3 Side A)(Populace B).d64|Populace B
86Ultima VI - The False Prophet (1990)(Origin Systems)(Disk 3 of 3 Side B)(Populace C).d64|Populace C
87```
88
89...will be shown in RetroArch's disk selection menu as:
90
91```
921: Game
932: Surface
943: Dungeon
954: Populace A
965: Populace B
976: Populace C
98```
99
100If `DISK_LABEL` is intentionally left blank (i.e. `DISK_FILE|`) then only the disk index will be displayed.
101
102For games that require a dedicated save disk, one may be generated automatically by entering the following line in an M3U file: `#SAVEDISK:VolumeName`. `VolumeName` is optional and may be omitted. For example, this will create a blank, unlabelled disk image at disk index 5:
103
104`Elite (1985)(Firebird Software).m3u`
105```
106Elite (1985)(Firebird Software).d64
107#SAVEDISK:
108```
109
110Although one save disk is normally sufficient, an arbitrary number of `#SAVEDISK:VolumeName` lines may be included. Save disks are located in the frontend's save directory, with the following name: `[M3U_FILE_NAME].save[DISK_INDEX].d64`.
111
112Save disks generated by the `#SAVEDISK:` keyword are automatically assigned the label: `Save Disk [SAVE_DISK_INDEX]`.
113
114### Extra features
115
116- `#COMMAND:<commands>`
117 - Pass arguments to VICE (place first, core name can be skipped)
118- `#SAVEDISK:<label>`
119 - Create a save disk in `saves`
120- `#LABEL:<label>`
121 - Alternative label for the next entry
122- `<disk>.d64:<prg>`
123 - Load a program instead of `"*"`
124- `<disk>.d64|<label>`
125 - Set a friendly name (shown in "Disc Control")
126- `<disks>.zip#<disk>.d64`
127 - Specify a disk inside a ZIP with multiple disks (not needed with single file ZIPs)
128
129M3U playlist supports disks, tapes, cartridges and programs.
130
131## ZIP support
132
133ZIPs are extracted to a temporary directory in `saves`, bypassing the default frontend extraction.
134The temporary directory is removed on exit. ZIP is not repacked, which means saves and highscores are lost.
135
136This allows:
137
138- Automatic M3U playlist generation of all files
139- The use of zipped images in M3Us
140
141## JiffyDOS support
142
143External ROM files required in `system/vice`:
144
145| Filename | Size | MD5 |
146|----------------------------------|--------|----------------------------------|
147| **JiffyDOS_C64.bin** | 8 192 | be09394f0576cf81fa8bacf634daf9a2 |
148| **JiffyDOS_C128.bin** | 16 384 | cbbd1bbcb5e4fd8046b6030ab71fc021 |
149| **JiffyDOS_1541-II.bin** | 16 384 | 1b1e985ea5325a1f46eb7fd9681707bf |
150| **JiffyDOS_1571_repl310654.bin** | 32 768 | 41c6cc528e9515ffd0ed9b180f8467c0 |
151| **JiffyDOS_1581.bin** | 32 768 | 20b6885c6dc2d42c38754a365b043d71 |
152
153## Command file operation
154
155VICE command line options are supported by placing the desired command line in a text file with `.cmd` file extension. The command line format is as documented in the [VICE manual](http://vice-emu.sourceforge.net/vice_6.html).
156
157Using this you can overcome limitations of the GUI and set advanced configurations required for running problematic files.
158
159
160VIC-20 Mega-Cart can be launched via `.cmd`:
161```
162xvic -cartmega "/path/to/rom/mega-cart-name.rom"
163```
164**VIC-20 Mega-Cart is supported automatically with NVRAM file directed to `saves`.**
165
166
167VIC-20 memory expansion can be set via `.cmd`: `-memory (3k/8k/16k/24k/all) / (0/1/2/3/5) / (04/20/40/60/a0)`:
168```
169xvic -memory 1 "/path/to/rom/some-8k-game.d64"
170xvic -memory 8k "/path/to/rom/some-8k-game.d64"
171xvic -memory 20 "/path/to/rom/some-8k-game.d64"
172```
173
174**VIC-20 memory expansion can be set with filename tags or directory matching:**
175
176- `some game (8k).prg` or `/8k/some game.prg`
177- `vicdoom (35k).d64`
178
179## Latest features
180
181- Automatic VIC-20 Mega-Cart support (with NVRAM)
182- Automatic NIB->G64 conversion
183- Region (PAL/NTSC) filepath tags for C64 & VIC-20
184- Memory expansion filepath tags for VIC-20
185- JiffyDOS support
186- Paddles & mouse
187- Zoom mode
188- Savestates
189- Keyrah joystick maps
190- Drive Sound Emulation (1541 & 1571 only)
191- Reset Type (Autostart, Soft, Hard, Freeze)
192
193## Build instructions
194
195Remember to run `make clean EMUTYPE=x` when building different EMUTYPEs.
196
197Currently working EMUTYPEs:
198
199- `x64`
200- `x64sc`
201- `x128`
202- `xcbm2`
203- `xcbm5x0`
204- `xpet`
205- `xplus4`
206- `xscpu64`
207- `xvic`
208
209### Linux
210
211```
212CC=gcc make -j4
213```
214
215### Windows
216
217```
218make -j4
219```
220
221### Win64 (crossbuild)
222
223```
224make platform=wincross64 -j4
225```
226
227### Android standalone toolchain Build
228
229```
230export path to your standalone toolchain like
231
232export PATH=$PATH:/opt/standtc/bin
233
234make platform=androidstc -j4
235```
236
237### Android ndk Build
238
239```
240cd jni
241ndk-build
242```
243
244## Original readme
245
246 ----------------------------------------------------------------------------
247
248 VICE 3.3 Dec 2018
249
250
251 _______________
252 | || ||
253 | || ||____________________________
254 | || || || || ||
255 | || || || | || ______||
256 | || || || |----|| ||
257 | || || || | || ------||
258 | ||____||_________||__________||
259 \ // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
260 \ //
261 \________// Versatile Commodore 8-bit Emulator
262
263
264
265 ----------------------------------------------------------------------------
266
267 This release stabilizes and introduces the GTK3 UI as the primary user
268 interface for all major ports. For "lesser" platforms we still have the SDL
269 based interface. All other user interfaces have been removed. RIP
270
271 We are still looking for dedicated maintainers for the Windows- and macOS
272 ports, if you want to help improving these and/or want to provide binaries,
273 please get in touch.
274
275 ----------------------------------------------------------------------------
276
277 This is version 3.3 of VICE, the multi-platform C64, C128, VIC20,
278 PET, PLUS4 and CBM-II emulator. This version can be compiled for
279 MSDOS, Win32, OS/2, BeOS, QNX 4.x, QNX 6.x, AmigaOS, Dingoo,
280 Syllable, SkyOS and for most Unix systems provided with
281 the X Window System version 11, R5 or later.
282
283 The following programs are included:
284
285 - x64, a C64 emulator;
286
287 - x64sc, a C64 emulator focused on accuracy;
288
289 - xscpu64, a C64 emulator with a SuperCPU cart;
290
291 - x64dtv, a C64 Direct-to-TV (DTV) emulator;
292
293 - x128, a C128 emulator;
294
295 - xvic, a VIC20 emulator;
296
297 - xpet, a PET emulator;
298
299 - xplus4, a PLUS4 emulator;
300
301 - xcbm2, a CBM-6x0/7x0 emulator;
302
303 - xcbm5x0, a CBM-5x0 emulator;
304
305 - vsid, a SID player;
306
307 - c1541, a stand-alone disk image maintenance utility;
308
309 - petcat, a CBM BASIC de-tokenizer;
310
311 - cartconv, a C64/C128 cartridge conversion program.
312
313 Moreover, the following documents are provided in both source and
314 binary distributions:
315
316 - README, this file;
317
318 - COPYING, the GNU General Public License under which VICE is
319 distributed -- *please read it before using the program*;
320
321 - INSTALL, installation instructions;
322
323 - NEWS, list of user-visible changes between this and older versions of VICE;
324
325 - FEEDBACK, something you should read before reporting bugs or sending mail
326 to any of the authors;
327
328 The following documents are provided in the source distribution:
329
330 - in the doc directory:
331
332 - vice.texi, the complete documentation; documentation in various different
333 formats may be generated from it (vice.txt, vice.pdf, vice.chm, vice.hlp,
334 vice.guide, vice.inf, vice.info)
335 - iec-bus.txt, overview of the VICE IEC bus emulation;
336 - CIA-README.txt, overview of the VICE CIA emulation;
337 - coding-guidelines.txt, description of VICE coding style
338 - Documentation-Howto.txt, information on how to edit the documentation
339 - Doxygen-Howto.txt, how to generate doxygen documentation
340 - Release-Howto.txt, some hints and reminders on how to create a release
341 tarball (for maintainers)
342 - ffmpeg-support.txt, this document details the results of test compiles
343 with regards to the included ffmpeg library.
344 - SDL-support.txt, this document details the results of test compiles with
345 regards to the SDL 1 and SDL 2 support.
346 - hardware-sids.txt, this document details the hardware SIDs and how they
347 are supported on the various platforms.
348
349 - in the doc/readmes directory:
350
351 - Readme-GTK3.txt, GTK3 specific documentation;
352 - Readme-SDL.txt, SDL specific documentation;
353 - Readme-SDL2.txt, SDL2 specific documentation;
354
355 - in the doc/building directory:
356
357 - Windows-MinGW-GTK3-Howto.txt, how to compile the Windows port using MingGW/MSYS2
358 - Linux-GTK3-Howto.txt, how to compile the GTK3 port on Linux
359 - GTK3-macOS.txt, how to compile the Mac OSX port with GTK3 UI
360 - SDL-Howto.txt, how to compile the SDL port on various platforms
361 - Android-Howto, how to compile the Android SDL port
362 - FreeBSD-GTK3-Howto.txt, hints on compiling the GTK3 port on FreeBSD
363 - NetBSD-howto.txt, hints on compiling for NetBSD
364
365 For the latest news, have a look at the VICE home page:
366
367 http://vice-emu.sourceforge.net/
368
369 Also some information that was previously included in the distribution has been
370 moved into our wiki at sourceforge:
371
372 - The TODO list,
373 http://vice-emu.sourceforge.net/wiki/index.php/Todo#New_Features
374
375 - The list of known BUGS,
376 http://vice-emu.sourceforge.net/wiki/index.php/Todo#Known_Issues
377
378 New versions are made available quite often, so please stay tuned.
379
380
381 Have fun!
382
383
384 Copyright notice
385 ----------------
386
387 VICE, the Versatile Commodore Emulator
388
389 Core Team Members:
390 2005-2018 Marco van den Heuvel
391 2007-2018 Fabrizio Gennari
392 2009-2018 Groepaz
393 2010-2018 Olaf Seibert
394 2011-2018 Marcus Sutton
395 2011-2018 Kajtar Zsolt
396 2016-2018 AreaScout
397 2016-2018 Bas Wassink
398 2017-2018 Michael C. Martin
399
400 Inactive/Ex Team Members:
401 1999-2017 Martin Pottendorfer
402 2011-2016 Stefan Haubenthal
403 2015-2016 BSzili
404 1999-2016 Andreas Matthies
405 2007-2015 Daniel Kahlin
406 2009-2015 Errol Smith
407 2012-2014 Benjamin 'BeRo' Rosseaux
408 2011-2014 Ulrich Schulz
409 2011-2014 Thomas Giesel
410 2009-2014 Ingo Korb
411 2008-2014 Antti S. Lankila
412 2006-2014 Christian Vogelgsang
413 1998-2014 Dag Lem
414 2000-2011 Spiro Trikaliotis
415 2007-2011 Hannu Nuotio
416 1998-2010 Andreas Boose
417 1998-2010 Tibor Biczo
418 2007-2010 M. Kiesel
419 1999-2007 Andreas Dehmel
420 2003-2005 David Hansel
421 2000-2004 Markus Brenner
422 1999-2004 Thomas Bretz
423 1997-2001 Daniel Sladic
424 1996-2001 André Fachat
425 1996-1999 Ettore Perazzoli
426 1993-1994, 1997-1999 Teemu Rantanen
427 1993-1996 Jouko Valta
428 1993-1994 Jarkko Sonninen
429
430 Translation Team Members:
431 2009-2017 Mikkel Holm Olsen
432 2000-2017 Martin Pottendorfer
433 2011-2017 Manuel Antonio Rodriguez Bas
434 2004-2017 Paul Dubé
435 2006-2017 Czirkos Zoltan
436 2006-2017 Karai Csaba
437 2001-2017 Andrea Musuruane
438 2011-2016 Jesse Lee
439 2005-2017 Marco van den Heuvel
440 2011-2017 Jarek Sobolewski
441 2010-2017 Michael Litvinov
442 2000-2017 Peter Krefting
443 2008-2017 Emir Akaydin
444
445 This program is free software; you can redistribute it and/or
446 modify it under the terms of the GNU General Public License as
447 published by the Free Software Foundation; either version 2 of the
448 License, or (at your option) any later version.
449
450 This program is distributed in the hope that it will be useful,
451 but WITHOUT ANY WARRANTY; without even the implied warranty of
452 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
453 GNU General Public License for more details.
454
455 You should have received a copy of the GNU General Public License
456 along with this program; if not, write to the Free Software
457 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
458 02111-1307 USA
459
460 The ROM files in the `C128`, `C64`, `CBM-II`, `DRIVES`, `PET`, `PLUS4`
461 `PRINTER` and `VIC20` directories are Copyright C by Commodore
462 Business Machines.
463
464 The ROM files in the `C64DTV` directory are Copyright C by Commodore
465 Business Machines, as well as Mammoth Toys, a division of nsi ltd.,
466 Digital Concepts DC studios inc., Ironstone Partners ltd., and
467 Toy:Lobster company ltd.
468
469### NIBTOOLS
470
471(C) 2005 Pete Rittwage and the C64 Preservation Project team
472
473It is based on MNIB which is copyrighted
474(C) 2000 Markus Brenner
475
476
){kind=link}