TuxNES version 0.75
http://tmmm.simplenet.com/tuxnes/index.html
- About
TuxNES is an emulator for the 8-bit Nintendo Entertainment System.
TuxNES is based on Nestra, a great public-domain NES emulator by Quor. TuxNES adds many features not found in Nestra, and uses a more collaborative development model. Enhancements to Nestra often find their way into TuxNES. Enhancements to TuxNES don't generally find their way into Nestra due to licensing restrictions (since pieces of TuxNES are generally copyrighted by their authors, and covered by the GNU General Public License,) although similar changes by the same authors sometimes find their way back into Nestra.
Platforms:
TuxNES requires an x86-family processor.
TuxNES should work with these operating systems:
FreeBSD
Linux
NetBSD
OpenBSD [needs to be verified!]
TuxNES can render using the X Window System, the W Window System, or GGI.
- Installing
TuxNES follows the standard GNU process for installing tarballs. Download the archive, uncompress it and type
./configure
make
make install
Extra --enable and --with options understood by ./configure:
--enable-warnings enable more compilation warning checks [default=no] --enable-profiling enable profiling of functions [default=no] --without-ggi disable check for GGI (General Graphics Interface) --without-w disable check for the W Window System
For more information, see the INSTALL file.
(If you recieved a binary distribution of TuxNES, just copy the appropriate executable to a suitable directory such as /usr/local/bin.)
- Features
The current features in TuxNES include: - open source - runs under Linux, FreeBSD, and NetBSD on x86 platforms - uses an X11 server, W server or GGI for display and input handling - dynamic recompilation from 6502 opcodes -> x86 native opcodes - mappers: 0, 1, 2, 3, 4, 7, 9, 11, 32, 66, 99 - experimental mappers: 15, 22, 23, and 71 - gzip and zip file support - game saving - built-in disassembler - joystick support (2- & 4-button) - experimental sound support - capture screenshots in X pixmap (xpm) or portable pixmap (ppm) format - Game Genie code support - trainer support - alternate palette support
- Running
TuxNES is invoked from the command line and the command line options are similar to those used by Nestra. TuxNES also supports long options on the command line.
The only command line incompatibility TuxNES has with Nestra is mirroring. For example, TuxNES uses -mh rather than -hm for horizontal mirroring. Recent versions of Nestra support TuxNES-style mirroring specification.
Usage: tuxnes [--help] [options] filename Help topics:
--help=help Help topics (this list)
--help=options Major command-line options
--help=sound Sound synthesis options
--help=palettes Custom palette options
--help=synonyms Alternate option names
--help=controls Keyboard and joystick options and bindings
--help=version Version and copyright information
--help=all All help topics
--help=-help Concise version of --help=help
--help=-options Concise version of --help=options
--help=-sound Concise version of --help=sound
--help=-palettes Concise version of --help=palettes
--help=-all Concise version of --help=all
Major command-line options:
-v, --verbose Verbose output
-f, --fix-mapper Use only the low four bits of the mapper number
-M, --mapper=... Specify mapper to use
-g, --gamegenie=... Game Genie code
-H, --show-header Show iNES header bytes
-d, --disassemble Disassemble
-l, --link Link branches optimization (may improve speed)
-i, --ignore-unhandled
Ignore unhandled instructions (don't breakpoint) -m, --mirror=... Manually specify type of mirroring
h = Use horizontal mirroring
v = Use vertical mirroring
s = Use single-screen mirroring
n = Use no mirroring
-G, --geometry=WxH Specify window/screen geometry
--display=ID Specify display/driver ID
-E, --enlarge[=NUM] Enlarge by a factor of NUM (default: 2) -L, --scanlines[=%] Set alternate scanline intensity (default: 0%) -S, --static-color Force static color allocation (prevents flicker) -r, --renderer=... Select a rendering engine (default: auto)
x11 X11 renderer
diff differential X11 renderer
old old X11 renderer (tile-based)
auto Choose one automatically
none Don't draw anything
-I, --in-root Display in root window
-K, --sticky-keys Hit keys once to press buttons, again to release
-X, --swap-inputs Swap P1 and P2 controls
Sound synthesis options:
-s, --sound[=FILE] Append sound data to FILE (default: /dev/dsp)
(specify sound file as mute or none for no sound, e.g., -smute) -F, --format=... Use the specified sound sample format (default: 8)
mu8 8-bit Mu-Law encoded *tested, imperfect
8 8-bit unsigned
8s 8-bit signed *untested
16 16-bit signed
16u 16-bit unsigned *untested
le16 16-bit signed (little-endian)
le16u 16-bit unsigned (little-endian) *untested
be16 16-bit signed (big-endian) *untested
be16u 16-bit unsigned (big-endian) *untested
-R, --soundrate=NUM Set sound sample rate to NUM Hz (default: 44100)
-D, --delay=NUM Resynchronize if sound delay exceeds NUM seconds
Custom palette options:
-p, --palfile=FILE Load palette data from FILE
-P, --palette=... Use a specified built-in palette (default: loopy)
loopy Loopy's NES palette
quor Quor's palette from Nestra 0.63
chris Chris Covell's NES palette
matt Matthew Conte's NES palette
pasofami Palette from PasoFami/99
crashman CrashMan's NES palette
mess palette from the MESS NES driver
zaphod-cv Zaphod's VS Castlevania palette
zaphod-smb Zaphod's VS SMB palette
vs-drmar VS Dr. Mario palette
vs-cv VS Castlevania palette
vs-smb VS SMB/VS Ice Climber palette
-b, --bw Convert palette to grayscale
-N, --ntsc-palette[=[HUE][,TINT]]
Use Kevin Horton's dynamic NTSC palette generator
with given hue angle (default: 332 degrees) and tint
level (default: 0.5)
Alternate option names:
-c, --controls Equivalent to --help=controls
-h, --help Equivalent to --help=-help if stdout is a tty,
otherwise equivalent to --help=-all
-j, --joystick=FILE Equivalent to --js1=FILE
-o, --old Equivalent to --renderer=old
-V, --version Same information as --help=version
Keyboard and joystick options and bindings:
-1, --js1[=FILE] Use P1 joystick FILE (default: /dev/js0)
-2, --js2[=FILE] Use P2 joystick FILE (default: /dev/js1)
-J, --joystick-map=MAPSPEC Reassign joystick button bindings
- MAPSPEC
- Specify joystick, then indicate buttons with 'B' and axes with 'A' in
sequence: A, B, Start, Select, Left, Right, Up, Down, Pause
Multiple buttons may be bound to a single emulator control.
Default bindings will be used if no buttons are specified.
- Examples
- 1:B0,B1,B5,B2,A0,A1,B4
2:B0,B1,B5,B2,B10,B12,B11,B13,B4
1:B0B8,B1B9,B5,B2
2:,,,,A2,A3
- Keyboard
- Arrows - Move (P1)
A, C or Space
- A button (P1) Z, X or D - B button (P1) Tab - Select button (P1) Enter - Start button (P1) H, J, K, L - Move (P2) B - A button (P2) V - B button (P2) F - Select button (P2) G - Start button (P2) BackSpace - Reset game P, Pause - Pause or resume emulation ESC - Exit game 0-8, ` - Adjust emulation speed 0 stops the game, ` runs the game at half speed 1 runs at normal speed, 2..8 runs at 2..8x normal speed S, F7, PrintScreen
- Capture screenshot Under X11, save to ~/.tuxnes/snap????.xpm (Note: XPM/PPM support must be installed and compiled for this to work; see the README file for more info.)
- Keypad
- Arrows/12346789 - Move (P1)
Space/Begin/5, Delete/Decimal
- A button (P1) Insert/0 - B button (P1) Add - Select button (P1) Enter - Start button (P1)
Joystick Axes:
Axis 0 - Horizontal movement
Axis 1 - Vertical movement
Axis 2 - (unused)
Axis 3 - (unused)
Axis 4 - Horizontal movement
Axis 5 - Vertical movement
Joystick Buttons (2-button joysticks):
Button 0 - B button
Button 1 - A button
Joystick Buttons (other joysticks):
Button 0 - B button
Button 1 - Select button
Button 2 - A button
Button 3 - Start button
Button 4 - A button
Button 5 - B button
Button 6 - Select button
Button 7 - Start button
Button 8 - Pause or resume emulation
Extra keys for old X11 renderer (--renderer=old)
F1 - Disable background
F2 - Re-enable background
F3 - Disable sprites
F4 - Re-enable sprites
F5 - Alternate tiles
F6 - Default tiles
F8 - Flush tile cache
Extra Keys for VS UniSystem games:
[/{ - Insert Coin (Left)
]/} - Insert Coin (Right)
|/\ - Service Credit
Q/q - Toggle Dipswitch #1
W/w - Toggle Dipswitch #2
E/e - Toggle Dipswitch #3
R/r - Toggle Dipswitch #4
T/t - Toggle Dipswitch #5
Y/y - Toggle Dipswitch #6
U/u - Toggle Dipswitch #7
I/i - Toggle Dipswitch #8
Version and copyright information:
tuxnes 0.75
Copyright © 1999-2001, The TuxNES Team
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Written by The TuxNES Team; see the AUTHORS file. Based on Nestra v0.66 by Quor
- Screenshots
While you're running the emulator, you can capture screenshots in X pixmap (xpm) format anytime by pressing F7. However, you need to install the XPM library and compile TuxNES when the XPM library is installed in order to capture screens. TuxNES will still compile without the XPM library, but it won't take screenshots.
The pixmap files are stored in the ~/.tuxnes/ directory.
Of course, the XPM format is not the most widely accepted graphic file
format. If you need a simple way to convert XPM files to GIF files, you can
use the xpmtoppm and ppmtogif programs that should already be installed on
your computer. Try this:
xpmtoppm file.xpm | ppmtogif > file.gif
- Graphics
TuxNES has three different rendering engines, with different capabilities and limitations. Different renderers can be selected using the -r, --renderer=... command-line option. Available renderers:
x11 = X11 renderer
diff = differential X11 renderer
old = old X11 renderer (tile-based)
ggi = GGI renderer
w = W renderer
none = Don't draw anything
X11 renderer: (-r x11, --renderer=x11) + allows mid-screen PPU/VRAM updates + supports screenshots [requires libXpm] + uses shared-memory XImages [when available]
- fairly slow (especially at high bpp)
- supports only 1bpp, 4bpp, 8bpp, 16bpp, 24bpp and 32bpp
- no graphics debugging/ripping support
differential X11 renderer: (-r diff, --renderer=diff)
+ optimized differential display (ideal for >8bpp)
+ allows mid-screen PPU/VRAM updates
+ supports all bpps
+ supports screenshots [requires libXpm]
+ uses shared-memory XImages [when available]
- fairly slow (especially at 8bpp and lower)
- no graphics debugging/ripping support
old X11 renderer: (-r old, --renderer=old)
+ very fast (provided the game doesn't change too many tiles at once)
+ supports all bpps
+ supports screenshots [requires libXpm]
+ allows graphics debugging/ripping (F1-F6, F8)
- no shared-memory rendering
- doesn't support mid-screen PPU/VRAM updates
GGI renderer: (-r ggi, --renderer=ggi) [requires libgii and libggi] + allows mid-screen PPU/VRAM updates + supports screenshots [requires libppm] + uses direct buffer rendering [when available]
- fairly slow (especially at high bpp)
- supports only 1bpp, 4bpp, 8bpp, 16bpp, 24bpp and 32bpp
- no graphics debugging/ripping support
W renderer: (-r w, --renderer=w)
+ allows mid-screen PPU/VRAM updates
+ supports screenshots
- supports only 1bpp and 8bpp
- fairly slow
- no shared-memory rendering
- no graphics debugging/ripping support
Don't draw anything: (-r none, --renderer=none) + very, very fast!
- no display (sound still works)
- no screenshots
- no keyboard input (joystick still works)
- you must use Ctrl-C to quit
Renderer speed depends on many things. If performance is unacceptable, try another renderer.
The X Window System is available many places. My favorite implementation, XFree86, is available from:
libXpm is included in recent distributions of XFree86.
Other X Window System servers are listed on:
GGI (including libgii and libggi) is available from:
libppm is part of the netpbm package, available from web and ftp servers world-wide.
The W Window System is available from:
http://www.students.tut.fi/~t150315/
NOTE 1: libXpm (at least some versions) is badly broken for 1bpp X11 visuals. A workaround is present in TuxNES, but XPM screenshots are very slow on 1bpp visuals as a result of this.
NOTE 2: GGI's ggiUnpackPixels fails or is broken on some targets. As a result of this, TuxNES uses a workaround to capture screenshots on these targets. This workaround can cause flickering while the screenshot is saved, and under at least the "xlib" target, iconifying TuxNES during a screenshot will cause "missing" regions in the resulting image. The workaround is also very slow, but at least proper PPM screenshots are saved.
NOTE 3: GGI is badly broken for some 1bpp targets (notably "x", but not "xlib",) and for DirectColor X11 visuals -- sorry! If this affects you, you should fix GGI and submit patches to the GGI maintainers. The typical symptom is a core dump on startup... although it seems to work fine using a direct buffer (in libggi-2.0b2.1, at least.) Also note that TuxNES treats all 1bpp targets as having broken ggiUnpackPixels implementations, and so uses the workaround described above -- but screenshots are broken under the "xlib" target at 1bpp anyhow.
NOTE 4: Some GII input sources can't sense key release events, so they simulate key releases immediately following key presses. These input sources don't work right with TuxNES unless you use the --sticky-keys option.
NOTE 5: Be sure to read the GGI and GII documentation if you use the "ggi" target. It includes numerous examples of target specifications and other library options, which are generally set using environment variables.
NOTE 6: Note that some NES games change the palette in the middle of a screen refresh. If you're using a palettized display and you notice color flickering or unusual delays, you can force static color allocation using the --static-color option. This increases the number of colors allocated, but as a nice side-effect multiple TuxNES invocations will be able to share palette entries (provided they're using the same palette data.)
NOTE 7: The code for 4bpp rendering is untested, but it might work.
- Joystick
Linux joystick support is enabled by the -1, --js1 or -2, --js2 command line options (enabling the joystick for P1 or P2, resp.) A joystick device may optionally be supplied (defaults: /dev/js0 for P1, /dev/js1 for P2). If you need help setting up a joystick under Linux, check out The Linux Joystick Driver at:
If you need to reassign your joystick buttons, use the -J option as follows: -J, --joystick-map=MAPSPEC Reassign joystick button bindings
- MAPSPEC
- Specify joystick, then indicate buttons with 'B' and axes with 'A' in
sequence: A, B, Start, Select, Left, Right, Up, Down, Pause
Multiple buttons may be bound to a single emulator control.
Default bindings will be used if no buttons are specified.
- Examples
- 1:B0,B1,B5,B2,A0,A1,B4
2:B0,B1,B5,B2,B10,B12,B11,B13,B4
1:B0B8,B1B9,B5,B2
2:,,,,A2,A3
- Sound
TuxNES supports all five NES sound channels. TuxNES uses /dev/dsp as the default audio port. To change this, use the --sound command line option. In order to turn off the sound, specify the file as 'mute' or 'none', for example:
tuxnes --sound=mute [options...] tuxnes -smute [options...]
The audio sample rate and resolution default to 44100 Hz/8 bits, but this may be changed using the --soundrate command line option. If FILE is a sound device supporting OSS-style ioctl() commands, the sample rate may be changed automatically to the nearest sample rate supported by the device.
Using --sound=/dev/audio may improve your listening experience, if the default sound device (/dev/dsp) doesn't work right.
If you are experiencing sound delays, you may be able to fix the problem usign the -D, --delay=NUM option, which causes the sound generator to resynchronize if the sound delay exceeds NUM seconds. For example, if you consider 1/5th-second delays between graphics and sound to be acceptable, you would give the option --delay=0.2 (note that specifying too short a delay could lead to near-continuous resynchronization, and jerky graphics.)
esd: EsounD "Enlightened" Sound Daemon & TuxNES
http://www.tux.org/~ricdude/EsounD.html
EsounD may be used to send the audio output from TuxNES over a network, and/or to mix it with channels of audio output from other applications.
To use TuxNES with EsounD, run it inside the esddsp shim:
esddsp --server=audiohost:port \
tuxnes --sound=/dev/dsp [options...]
audiohost:port are the hostname and port where an esd is listening for your audio stream.
sfspeaker: Speak Freely Internet Telephone & TuxNES
Speak Freely may be used to send the audio output from TuxNES over the network to a wide variety of compatible internet phone receivers, inluding Speak Freely for UNIX and Windows.
To use TuxNES with Speak Freely, send audio output through a FIFO in Mu-Law encoding:
mkfifo sound-fifo
sfmike audiohost:port -N tuxnes-sf & \
tuxnes --sound=sound-fifo --format=mu8 [options...]
rm sound-fifo
audiohost:port are the hostname and port where an sfspeaker is listening for your audio stream. You may have to remove the -N option to sfmike to communicate with some other Internet Telephone programs, or to send audio over a slow network connection.
- Palettes
TuxNES has several built-in color palettes, selectable at run-time using the --palette command line option. Palette data can also be loaded from a file using the --palfile command line option. The two common NES palette data formats (iNES-style comma-separated hexadecimal and Nesticle-style raw binary) are supported. Many alternate palette files are collected in rvu's NES Palette Zoo, reachable from:
To use Kevin Horton's NTSC palette generator, use --ntsc-palette instead with an appropriate hue angle and tint level. The defaults are a hue angle of 332 degrees, and a tint level of 0.5. A tint level of 1 is fully saturated, and a tint level of 0 is grayscale.
By default, TuxNES will use the VS SMB/VS Ice Climber palette for VS UniSystem games, and Loopy's NES palette for all other games.
Games in .NES-format which include 192 bytes of RGB palette data or a 64-byte palette remapping block immediately following the regular ROM data will use that, by default. As a fallback, a palette file with the same name as the game, but ending in .pal, will be used if it is available. Games with palette remapping blocks always default to using Loopy's NES palette, even if they are VS UniSystem games.
Any color palette can be converted to grayscale using the --bw option.
Compressed ROMs:
TuxNES is able to read ROMs that are compressed with either the gzip or zip utilities. Since a gzipped file can only contain a single file, TuxNES will attempt to load and run that file in the archive. However, since a zip file can contain more than one file, TuxNES will attempt to load and run the first file in the zip archive with a .nes extension.
- Troubleshooting
Are you having trouble getting a particular ROM to work with TuxNES? This most likely has to do with the memory mapper. If you try to run a game and TuxNES advises that you may wish to use the -f option, then you probably should use it (especially if your game fails to work).
If the game still doesn't work, the game's header info may be completely wrong about which mapper to use. Consult the Bigass NES Mapper List at the TuxNES home page to find the proper mapper the game should use and then run the game with the -M<number> option.
- ROMs
Don't even bother requesting NES ROMs. However, you might enjoy Chris Covell's games and demos, including Solar Wars, a nice artillery simulator for two players. They are completely legal and freely available from:
http://mypage.direct.ca/c/ccovell/