[ Download | News | Screenshots | Source | API | FAQ ]

[ Getting Started | Input | Sound | Video | History Tracking | TAS Editor | File System | Netplay | Emulation | Cheats | Debugger | Family BASIC | Legal | Contact ]


Getting Started

What is Nintaco?

Nintaco is a cycle-accurate Nintendo Entertainment System (NES) / Famicom emulator and NES Sound Format (NSF) player written in Java, ostensibly making it cross-platform. It supports the vast majority of games including those for the Famicom Disk System (FDS), Dendy and Vs. UniSystem along with a plethora of peripherals. It tracks play history, enabling the player to rewind time to undo mistakes, and to watch, export, edit and resume play at any point in the past. It supports netplay, save states, video and audio recording, video filters, screenshots, cheat codes, a debugger and a TAS editor. It can be controlled programmatically via an API. It provides automatic capturing of sprites and level maps. It even simulates R.O.B., the Robotic Operating Buddy.

How do I install Nintaco?

Download the latest release .zip and extract it to any directory.

How do I run Nintaco?

Nintaco requires Java version 8 or above.

Depending on your file associations, you may be able to launch Nintaco by double-clicking on Nintaco.jar. If that does not work, use the following from the command-line:

java -jar Nintaco.jar

How do I run a game?

File | Open...

Where do I get the game files?

Try the World Wide Web, an information space where documents and other resources can be accessed via the Internet.

How do I uninstall Nintaco?

Erase the directory in which you extracted the release .zip file. By default, it does not generate content outside of that folder.

How do I upgrade to a newer version?

You can try to unzip the latest version into the directory of the older version. That might preserve configurations, save states, histories, etc. But, unfortunately, there is no guarantee that those files are actually compatible with the latest. Consequentially, you may need to delete the old to install the new.


Input

How do I configure the buttons?

Options | Button Mapping...

Do I need to set all the buttons?

No. In fact, the Button Mappings dialog (Options | Button Mapping...) provides Clear and Clear All that will un-map buttons.

Are game controllers supported?

Yes.

If pressing a button on your game controller is not detected within the Button Mappings dialog, try the following: shutdown Nintaco, press a few buttons on your game controller, start up Nintaco and see if Button Mappings now detects button presses. Some controllers, particularly wireless ones, shut off after a certain amount of inactivity. If Nintaco fails to detect your controller on startup, it may have difficulty accessing it later on.

Also, Java does not natively support game controllers. Nintaco depends on JInput, a library that purportedly provides game controller support on Windows, Linux and OS X. However, if you cannot map your keyboard or game controller, then you’re probably running on an operating system not supported by JInput.

Why is the keyboard unresponsive?

Windows

Issues detecting certain keys under Windows—such as apostrophe, left/right square bracket, equals, backslash, and backtick—are often related to the infrared remote control for multimedia. Any of the affected keys in the default button mapping will appear unresponsive.

A simple solution is to manually configure a button mapping instead of relying on the default. This can be done from the Button Mapping dialog (Options | Button Mapping...) by pressing Set All. The affected keys may appear with incorrect names, but they should function after being mapped.

Alternatively, the infrared remote control can be disabled. This can be done from the Device Manager under the Control Panel. Expand Keyboards and right-click "Microsoft eHome MCIR 109 Keyboard". Select "Update Driver". When prompted, choose to browse your computer for the update as opposed to going to the web. Make sure "show compatible hardware" is checked. Select "HID-compliant device". Then, press Next and any of the OK / Finish buttons to complete the install.

If that did not work, in the Device Manager, under the Keyboard node, try updating "Microsoft eHome MCIR 109 Keyboard" to a "HID-compliant device".

If that did not work and you are not actually using a wireless keyboard, then from the Keyboards node in the Device Manager, right-click and uninstall "Microsoft eHome MCIR 109 Keyboard", "Microsoft eHome MCIR Keyboard" and "Microsoft eHome Remote Control Keyboard keys" if they are present. And, under the "Human Interface Devices" node, right-click and disable "Microsoft eHome Infrared Transceiver".

No reboot is necessary after updating / uninstalling those drivers. However, you will need to bounce Nintaco. And, you may need to press Reset All in the Button Mapping dialog.

OS X

Older versions of Nintaco contain a file in lib/native called libjinput-osx.jnilib.

Rename it to libjinput-osx.dylib and bounce Nintaco.

This is corrected in the latest release.

Linux

The JInput library requires read access to the /dev/input/event device nodes, which, for security reasons, are not read-enabled by default. Read access can be granted to all input devices by issuing the following command:

sudo chmod go=u /dev/input/event*

Alternatively, you can set a udev rule where these permissions are set automatically. It would involve adding a rule similar to the following:

KERNEL=="event*", NAME="input/%k", MODE="640", GROUP="input"

If modifying permissions enabled game controllers to work, but the keyboard is still unresponsive, then check if you are running a system for entering in foreign characters, such as IBus, Fcitx, SCIM or UIM. If found, temporarily disable it to see it if is interfering.

The last resort is to launch Nintaco with root privileges. This is ill-advised for a number of reasons, but it will likely resolve the issue.

How do I setup turbo buttons like on the NES Advantage?

Options | Button Mapping... enables each player to setup Autofire A and B buttons and optionally, a button that will toggle normal A and B into Autofire A and B. The Autofire Rate can be controlled from Options | Input Settings...

How do I attach different input devices to each controller port?

Options | Ports...

If Auto-configure on open is checked, then Nintaco will automatically attach the appropriate devices for each game.

How do I use the Zapper?

Refer to the prior answer for setting up input devices in general.

For the NES, the Zapper can be attached to Port 2. For the Famicom, it must be attached to the Expansion Port.

The Zapper crosshairs target is controlled by the mouse. By default, the left mouse button is the Trigger and the right mouse button is Rewind Time.

How do I adjust the Zapper sensitivity?

The Zapper detects targets within a square region centered on the mouse position. Increasing the size of the region means that less accuracy is required to hit a target, potentially making a light gun game easier to play. The size of the region is established by the Zapper light detection margin, which is configurable from the Options | Input Settings... dialog box. The margin is similar to the radius of a circle. It is the number of padding pixel layers surrounding the central pixel. In other words, the side of the square region is 2 × margin + 1 pixels.

How do I use the Power Glove?

The Power Glove can be attached to Port 1 (Options | Ports...). If Auto-configure on open is checked, then Nintaco will automatically attach the Power Glove for Super Glove Ball. The Power Glove maps to the mouse, including the mouse wheel.

How do I use R.O.B.

R.O.B. only works with 2 games: Gyromite and Stack Up. When you start either of them, the Robotic Operating Buddy window will appear. If you inadvertently close that window during play, it can be reopened via View | R.O.B...

If you never played Gyromite before, start it up in Direct Mode. Practice picking up gyros and using them to hold down the blue and red buttons. When you’ve mastered that, press Select to return to the main menu, and then start Game A.

The goal of Game A is to collect all the dynamite within each stage. To raise and lower the blue and red gates, you’ll need to send commands to R.O.B. to hold down the respective blue and red buttons. Press Start before each command. You’ll also need to avoid the wandering Smicks or distract them with turnips.

Game B is controlled like Direct Mode. You simply need to raise and lower gates to advance the sleepwalker.

Like Gyromite, if you never played Stack Up before, start it up in Direct Mode. The goal is to rearrange the stack of blocks by sending commands to R.O.B. The other modes are variations on this idea.

On a side note, communication with the actual R.O.B. is one direction: from the NES to R.O.B. However, in Stack Up, once you reach the goal, the player is expected to press Start to advance to the next level. Nintaco actually does this automatically by comparing R.O.B.’s state against memory. In addition, it automatically setups the stacks. Nonetheless, you can still cheat by pressing Start to advance.

How do I use the Famicom 3D System?

The following Famicom games provide stereoscopic output: Attack Animal Gakuen, Cosmic Epsilon, Falsion, Famicom Grand Prix II, Highway Star and JJ: Tobidase Daisakusen Part II. Launching any of them will automatically open the Famicom 3D Glasses window. It displays a pair of images that the active shutter glasses would normally deliver to each eye. However, if you cross your eyes while viewing the images it is possible to experience a three-dimensional effect.

Most of the games use the Select button to toggle between 2D and 3D modes. Some lock you into 3D mode after selecting the option from the start screen menu.

If you inadvertently close the 3D window, you can reopen it via View | Famicom 3D Glasses...

Options | Input Settings... provides a checkbox that will exchange the left and right images displayed in the Famicom 3D Glasses window. The configuration is potentially useful for viewing with a stereoscope.

How do I use the Barcode Battler II?

Launching Barcode World will automatically open the Barcode Battler II window. It enables you to enter in an 8 or 13 digit barcode value or to have one randomly generated for you. The Transfer button applies the barcode.

How do I use the Oeka Kids tablet?

The default button mapping uses the keyboard and the mouse. Moving the mouse positions the stylus. Holding down X simulates contact between the stylus and the tablet. And, the left mouse button functions as the tablet button.

How do I adjust the ball firing rate when using the Coconuts Japan Pachinko Controller?

Rotate the scroll wheel on the mouse.

How do I use Bandai's Hyper Shot submachine gun?

The Hyper Shot was designed for the game Space Shadow. The mouse positions the crosshairs target. By default, the left mouse button is the Trigger and the right mouse button is the Grenade Launcher. Unlike the Zapper, holding down the Trigger fires a continuous stream of shots. Use the scroll wheel to advance to successive rooms.

What other input devices are supported?

Explore the port combo boxes under Options | Ports... including the Expansion Port for Famicom.

What is Multitap?

In the Ports dialog (Options | Ports...), checking Multitap is equivalent to attaching the NES Four Score / NES Satellite / 4-Players Adaptor. It increases the number of input ports from 2 to 4, but it’s only compatible with gamepads.

How do I attach a device to the Expansion Port?

In the Ports dialog (Options | Ports...), the Expansion Port options will become visible when you switch from NES to Famicom. The NES never took advantage of the Expansion Port since, unlike the Famicom, the controllers were detachable, providing 2 ports on the front of the machine for other input devices.


Sound

How do I set the volume?

Options | Volume Mixer... and adjust the Master slider.

How do I mute the emulator?

Options | Volume Mixer... and uncheck Sound Enabled.

How do I adjust the relative volumes of the various sound channels?

Options | Volume Mixer...

In the Volume Mixer, what is Smooth DMC?

Checking Smooth DMC will reduce clicks / pops from the Delta Modulation Channel at the start and end of sound samples. By default, it’s checked.

How do I select my audio device?

Options | Sound...

What is sound latency?

Generated sound data is buffered to accommodate a varying frame generation period. Crackling sound apparent on slower machines may be improved by increasing the latency. However, lower latency puts the audio more in sync with the video. Latency can be tuned to the millisecond via Options | Sound...

How do I configure the NSF Player?

Options | NSF...

How do I use the microphone to kill the Pols Voice in the Famicom version of the Legend of Zelda?

Machine | Scream into Microphone

That menu option simulates yelling or blowing into the Famicom player 2 controller microphone.


Video

How to I apply video filters / scalers?

View | Video Filter

All of the filters execute in software, parallelized across multiple background threads.

The LQx filters ("LQ" stands for "Low Quality" and "x" stands for magnification) were inspired by the HQx pixel art scaling algorithm. However, a performant implementation of HQx under Java was unavailable. Consequentially, LQx was invented as a substitute.

NTSC2x simulates the visual artifacts produced by composite video.

Retro3x simulates a number of CRT visual artifacts including a shadow mask texture, motion blur and noise. NTSC2x and Retro3x are both presented in CRT aspect ratio.

How do I change the screen size?

View | Screen Size or Alt+1 ... Alt+5.

You can also resize the window to any arbitrary size by dragging. The window can also be maximized.

How do I enter Fullscreen Mode?

View | Fullscreen or press Alt+Enter.

Use Esc or press Alt+Enter again to return to Window Mode.

One of the checkboxes under Options | User Interface... will force Nintaco to enter Fullscreen Mode when a game is loaded.

How do I switch to CRT aspect ratio?

View | Screen Size | TV Aspect

How do I hide the main menu bar?

View | Hide Menu Bar

Use Esc to bring it back.

How do I enable or disable status messages?

View | Show | Status Messages

How do I show the displayed vs. generated frames-per-second?

View | Show | Displayed/Generated FPS

How do I disable VSync in window mode?

Options | User Interface... and uncheck Use VSync in window mode.

How do I take a screenshot?

Tools | Save Screenshot or press F12.

Options | Screenshots… provides various options for configuring this feature.

How do I hide or show sprites or the background?

View | Show | Sprites

View | Show | Background

How can I see which elements are sprites?

View | Show | Sprite Bounding Boxes will put a colored box around each sprite.

Also, Debug | OAM Data... will bring up a dialog box that reveals all the sprites. The Highlight selected sprite checkbox will surround the associated sprite in a multicolored box.

How do I change the palette?

View | Palette

To view, import and export palette files, use Options | Palettes...

Is there any way to reduce flickering?

The NES graphics chip is only capable of rendering a limited number of sprites per scanline; only the first 8 drawn on a scanline will actually be visible. To compensate, NES games are written to constantly shuffle the drawing order, preventing any sprite from vanishing completely when too many align horizontally. But, this means that any given sprite may not appear on all frames, hence the flickering.

The option View | Show | More than 8 sprites per scanline will reduce flickering by eliminating that constraint. However, it may not stop flickering completely because the total number of sprites per frame is limited to 64 and the game may be written shuffle a set of sprites larger than that.

Why does Super Mario Bros. 3 have strangely-colored artifacts on the right-side of the screen?

That’s actually normal. It’s a consequence of being able to scroll in all 4 directions. That effect may have been minimized on your CRT back in the day because a narrow border around the picture, known as "overscan", might have been cropped off.

Overscan can be adjusted via Options | Overscan... If you really want to hide the artifacts completely, under NTSC, set Right to 16. That will conceal the right-most 16 columns of pixels.


History Tracking

How do I save my game progress?

Nintaco provides each game with 9 quick save slots. Press Shift+1 ... Shift+9 to snapshot the emulation state into one of those slots. Or, press Shift+0 to overwrite the least-recently-used slot.

Press 1 ... 9 to quick load from the associated slot. Or, press 0 to load from the most-recently-used slot.

Alternatively, press F5 to save the state to a specified file and F7 to restore from a specified file.

All of these options are also accessible from the File menu.

How do I rewind time?

Each player can individually configure a separate Rewind Time button via Options | Button Mapping... If you are using 8-button controllers, such as USB NES controllers, Rewind Time can be mapped to button combos, such as Start + B. It is also possible to rewind time via Tools | Rewind Time.

How do I watch my gameplay history?

Tools | Watch History...

How do I enable or disable History Tracking?

Tools | Track History

When watching history, how do I view the Zapper crosshairs position?

View | Show | Input Devices

This will actually render icons of all of the attached input devices that indicate which buttons are pressed at any given moment. In fact, when enabled, the icons can be recorded to video files.

How do I make a video or audio file from my history?

Tools | Export Video/Audio...

Select the Start and End Frames and then press Export...

How do I make an animated GIF?

Follow the prior answer, change type to animated gif, change the scale to 2x and then hit OK.

Why are the generated video / audio files so large?

The audio data is stored uncompressed.

Can I play in slow motion and then watch it back in real-time?

Yes. In addition, you can rewind mistakes away or modify inputs frame-by-frame using the History Editor.

What algorithm is used to track history?

Nintaco records controller input and it captures a save state every 64 frames. For random access, it restores the nearest save state and then it uses the input sequence to fill in the gap.

In addition, Nintaco maintains a running buffer of the last 64 rendered images and their associated audio samples. During Rewind Time, the frames of that buffer are displayed in reverse order. As this occurs, Nintaco incrementally fills a second buffer in the forward direction based on the prior save state. That buffer becomes completely filled at the moment the other becomes empty. Then, the buffers are swapped and the cycle repeats with earlier save states.

Does History Tracking work with games that generate random events?

Yes. Events that seem random are actually triggered by a pseudorandom number generator, a mathematical formula that generates a reproducible sequence of numbers that approximates randomness. In fact, the emulated hardware is completely deterministic in nature. Restoring a save state and playing back the controller input sequence with the same timing as it was recorded results in exactly the same performance.

If Nintaco tracks an indefinite amount of history, won’t it eventually run out of memory?

Probably. If you are playing for a very long period and you have concerns, you can always clear the history (Tools | Clear History). Or, you can simply disable history tracking all together (Tools | Track History).

It is also possible to increase the Java Virtual Machine maximum memory allocation pool size via the -Xmx flag on the command-line. For example, the following command specifies a size of 3 gigabytes.

java -Xmx3G -jar Nintaco.jar


TAS Editor

How do I launch the TAS Editor?

Tools | Edit History...

What is TAS editing?

Gameplay history is stored as a starting save state followed by a recording of controller input, sampled once per frame. Restoring the starting save state and playing back the input sequence results in the same performance thanks to the deterministic nature of the emulated hardware.

The History Editor enables you to view and manipulate the input sequence. It can be used to generate gameplay that exceeds human limitations and any mechanical impediments of the controllers. The resulting tool-assisted speedrun / superplay (TAS) typically demonstrates play virtually impossible to achieve in real-time.

What does the table do?

Each row displays sampled gamepad inputs for a particular frame. The frame index is displayed in the second column and the first column is used for navigation. The remaining columns appear in groups of 8, each associated with a gamepad button. Cells that are populated with values indicate buttons held down during the corresponding frames. The checkboxes in the View area to the right of the table enable you to select which gamepad columns are shown. 3P and 4P require Multitap (Options | Ports...).

You can view any frame within the history by clicking on a cell in the first column. From that position, the Frame-1 and Frame+1 buttons move backwards and forwards by a single frame, respectively. Random access is possible because a save state is captured every 64 frames; i.e. it restores the nearest save state and then it uses the input sequence to fill in the gap.

Clicking on or dragging across multiple gamepad cells will toggle the associated buttons. But, that comes with a consequence: the save states for the modified row and all rows below it become invalid. Rows with invalid save states turn gray and the History Editor responds by automatically updating them. It generates new save states by internally playing the input sequence from the modified point forward. The animated bar to the right of the table displays the progress of this mechanism.

Since restoring the save states of a large number of rows is a lengthy process, it is useful to mark a row as a restoration end-point. This will actually happen automatically when you navigate to a frame by clicking on a cell in the first column. Successive edits to the gamepad button cells in any of the rows above it will cause the History Editor to restore save states only up to the navigated end-point row. The History Editor uses a tan arrow in the first column as an identifier of that row.

The blue arrow in the first column marks the last generated frame. If you click on a cell in the first column in any of the blue rows, the main window will be updated with the associated frame and the blue arrow will follow. On the other hand, if you click on a cell in the first column in any of the gray rows, it will take time to restore the save states of all the rows in between. As this happens, the blue arrow will advance down the first column until it reaches the navigated row. This mechanism can be disabled by unchecking Restore position. In addition, the rate of restoration can be controlled by the Fast generation checkbox.

How do I jump to the last generated frame?

Press the Head button. It will scroll the row with the blue arrow into view.

How do I record a block of frames?

In the Record area, check the gamepads from which to obtain input. 3P and 4P require Multitap (Options | Ports...). Other refers to non-gamepad input such as pressing the Reset button, flipping a Famicom disk, inserting a coin, etc. When Merge is checked, it will combine new input with the existing recording, as opposed to replacing it; Merge is a way to record a block in multiple passes, each potentially with a different gamepad.

When you're ready to record, press Resume. If Track cursor is checked, the table will scroll with the newly recorded frames. Press Pause to stop recording.

How do I save and load?

File | Save Project and File | Load Project...

TAS editing involves a lot of experimentation. To make this easier, the History Editor provides project quick save slots. They are accessible via the File | Quick Save/Load Project menus and also by the Slots area to the right of the table. Each slot can be used to explore a different path. And, the best results can be persisted via File | Save Project.

Also, all the modifications to the project appear in the History area list. Clicking on any row of the list will restore the project back to an earlier state. This can be controlled incrementally using the Undo and Redo buttons.

How do I use bookmarks?

To create a bookmark, in the Bookmarks area, press Add... A dialog box will appear and the Frame number field will be auto-populated by the blue arrow row index. Enter a Name and press OK. The new bookmark will appear in the Bookmarks area list. In addition, bookmarked rows are marked by a pink box in the first column.

To jump to a bookmark, simply select it from the list or press Seek to jump to the currently selected entry. The Previous and Next buttons navigate forward and backwards through the list, respectively. Bookmarks can be modified via the Edit... and Delete buttons. And, bookmarks can be used as the bounds of a selection (Edit | Select Between Bookmarks).

How do I select a block of rows?

Press and hold a cell in the first column and drag upwards or downwards within the column. Or, click on a cell in the first column, and then hold down Shift and click on a different cell in the first column to select the rows in between. Also, a selection does not need to be contiguous. You can add rows to a selection by holding down Ctrl and clicking on cells in the first column.

The Edit menu provides many options for manipulating selected rows. Copy saves the selection to the clipboard. It can actually be pasted into a text editor, modified there and pasted back into the History Editor. Be aware that Paste replaces existing rows while Merge combines the contents of the clipboard with the existing input sequence. The Insert options inject a new rows at the current navigation point. And, the Append option add new rows to the bottom.


File System

What file formats are supported?

Nintaco supports .nes (iNES and NES 2.0), .fds (with and without header), .unif and .nsf (normal and extended) file formats.

Files can be loaded from compressed archives (.zip, .7z, .rar and .tar*). The user will be prompted to select a specific file within an archive when it contains multiple entries; however, Nintaco will automatically highlight the best candidate among the list based on configured preferences (Options | Archive Files...) and it can even be setup to skip the prompt and always go with the default. Alternatively, it is possible to specify a file within an archive like this:

tortilla.zip <salsa.nes>

How do I change the location of generated content?

Options | Content Directory...

How do I load a game from the command-line?

java -jar Nintaco.jar salsa.nes

java -jar Nintaco.jar tortilla.zip <salsa.nes>

What is an IPS patch?

An IPS stores the differences between two files. The ROM-hacking community uses them to deploy patches to existing files.

How do I load an IPS patched game?

Place the IPS file in the same directory as the file to load and name it [filename with extension].ips:

salsa.nes      salsa.nes.ips
salsa.zip      salsa.zip.ips
salsa.nes.gz   salsa.nes.gz.ips

How do I create an IPS patch?

Tools | Create IPS Patch...

How do I apply an IPS patch?

Tools | Apply IPS Patch...

How do I setup and control the Famicom Disk System?

The Famicom Disk System requires a BIOS file to function; it’s a sort of operating system that controls the drive. Once obtained, it can be loaded into Nintaco via Options | Famicom Disk System...

Insert Disk, Flip Disk Side and Eject Disk can be found under the Machine menu.

How do I edit an iNES or NES 2.0 file header?

Tools | Edit File Header...

How do I disable the Cart DB?

Options | User Interface... and then uncheck Soft patch file header on load.

Where can I find a description of the currently running game?

View | File Info...


Netplay

What is Netplay?

Netplay links together multiple instances of Nintaco over a network for multiplayer gaming. One instance acts as the server and one or more other instances act as clients.

How do I setup the Netplay server?

To put Nintaco into Server Mode, select Tools | Start Netplay Server... The window that appears will enable you to configure the localhost (if there are multiple network interface controllers) and the listening port. Checkboxes allow you to specify the local players, those that will play in the server instance; enable Multitap (Options | Ports...) to get up to 4 players. The remaining options enable you to setup a password and to control what clients can do: act as spectators, access quick saves, rewind time and control high-speed. Press Start Server to enter Server Mode. These steps can be followed before or after opening a game file.

How do I setup a Netplay client?

To put Nintaco into Client Mode, select Tools | Connect to Netplay Server… The window that appears accepts the server host and port and optionally the password. You can connect as players 1–4, though players 3 and 4 are only applicable to multitap games. You can also specify which controller will be used by the client. Alternatively, the client can connect as a non-player by selecting Spectator. Press Connect to enter Client Mode. Whatever game is running on the sever will automatically be downloaded and launched.

Do I need to keep the Netplay windows open?

The server and client control windows do not need to remain open during Netplay. You can always return to them via the Tools menu.

Does Netplay work over the Internet?

Netplay uses a simple TCP protocol designed for local area networks; it might not be performant over the Internet.


Emulation

How do I increase the emulator font size?

View | Font Size...

How do I change the skin / visual style of the emulator?

View | Look and Feel

How do I operate Vs. UniSystem games?

Machine | Insert Coin or press F2.

Machine | Press Service Button

Machine | Dip Switches...

What is the difference between Power Cycle and Reset?

Power Cycle is equivalent to closing and re-opening the current file. It completely wipes out the emulation state, including play history.

On the other hand, the Reset button is treated as an input device. Like any other button, it sends a signal to the running file to do something. And, in this case, it’s instructed to reset itself. As a consequence, Reset does not affect play history; you can even rewind back to before the reset happened.

How do I control emulation speed?

Machine | Speed provides the means of speeding up or slowing down emulation. In addition, each player can individually configure a separate High-speed button via Options | Button Mapping... It can be used to skip past intermission scenes or to rewind faster. The high-speed rate can be set from Options | Input Settings...

Is there a way to speed up Nintaco when running on older hardware?

Nintaco favors modern machines; however, there are some settings that may help. Under Options | User Interface..., try switching the Inter-frame delay from Sleep to Spin.

It only takes a fraction of the frame period to actually generate a new frame and, by default, Nintaco sleeps away the remaining time. It does this by asking the operating system to wake it up at the start of the next frame period. However, depending on the immediate needs of the system, the wakeup may be delayed. In contrast, the Spin option burns up the remaining time in a loop that repeatedly consults the real-time clock. While this increases the accuracy of the frame timer, it consumes processor time that could be used to execute other tasks (1 core will run at 100%). The Yield option does something in-between.

If the wakeup event is delayed, Nintaco will notice that it got behind and it will generate a burst of frames in rapid succession in attempt to catch up. However, if it trails more than the number of frames specified by the Max lag frames option, then it will give up by resetting the frame timer. By default, the threshold is 60 frames; meaning, it would have to lag for a full second under NTSC to trigger a timer reset.

Also, see the answer to What is sound latency?

How do I switch to Dendy mode?

Machine | TV System | Dendy

Nintaco automatically sets the TV System based on file name region codes and information in its cart DB.

What does the Map Maker do?

The Map Maker automatically generates level maps as you play through stages. Tools | Map Maker... will launch the Map Maker window. Hit Start to begin mapping.

The Map Maker does not work for all games because of the various ways that games can render levels. And, for the games that do work, a bit of configuration is usually required. For example, in Super Mario Bros. 3, after starting the game and selecting a world, change Capture to Vertical Band and set Update on scanline to 0, and then press Start.

The Map Maker stitches together backgrounds incrementally as a player advances through a stage. It does this by comparing the background tiles that are currently visible against the tiles in the last known position within an expanding map. The Capture option specifies what it considers visible tiles. For instance, the Nametables viewer reveals that Super Mario Bros. 3 updates vertical strips as the player scrolls horizontally. Consequentially, setting Capture to Vertical Band will scan from sky to ground. If it were set to Visible Window, then the player would have to fly around the sky in addition to walking along the ground to generate a full stage map. The Visible Window and Horizontal Band options can be refined further by adjusting the Start and End tile rows; this makes it possible to eliminate status bars.

The Tracking size is the largest jump in any scrolling direction that it will account for during the comparison. For example, 2 means that the game is not expected to scroll faster than 2 tiles per frame (most games only scroll a fraction of a single tile per frame). The Tracking size can be thought of as a scanning radius; it will move the map in all possible directions up to that distance while trying to find a match.

When auto flush is selected, Map Maker uses the match threshold specified in the Max differences field. The default value of 160 means that no more than 160 tiles can be different. If no match is found, the map is flushed to an image file and a new map is started. Or, at any time, the Flush button can be pressed to force a flush. The Post flush frames field specifies the number of frames to wait after a flush before constructing a new map. A flush will automatically happen when Stop is pressed.

Update on sprite 0 hit and Update on scanline affect the point within the current frame that it scans the background. Both of those values are relevant when a game uses a fixed status bar. The same options appear in the Nametable viewer and you can experiment with values there until the background looks correct.

In some games, the Start / Pause button blanks out the screen or it brings up an options dialogs. Both of these would normally interfere with map mapping; however, the Auto pause option automatically stops mapping when Start is pressed. It will resume on the successive Start and after it detects that the background returned to normal. Since tracking Start presses can easily get of sync with what is actually happening in the game, you can manually control this by pressing the Pause / Resume button in the Map Maker window.

What does the Sprite Saver do?

The eponymous Sprite Saver saves sprites—or more technically meta-sprites, which are composed out of 8×8 pixel sprite tiles—encountered during gameplay. Tools | Sprite Saver... will bring up the Sprite Saver window. Hit Start to begin saving sprites.

The field Min occurrences specifies the number of times that the meta-sprite must appear within the provided time window (Within seconds) for it to be saved.

How do I un-glitch the emulator?

The menu option Machine | Glitch simulates poor connectivity between the cartridge and the slot. It only affects the pins that access tile data, enabling the game to continue running with glitched graphics. Rather than remedying the situation, successive Glitch applications leave the contacts in other randomly generated, bad states. Even if there were an option to restore the connection (Blow in Cart?), the game would likely fail to fully recover due to graphical loads during the glitched period. Consequentially, there are 2 ways to un-glitch the emulator: Reset / Power Cycle or Rewind Time to before the glitch happened.


Cheats

How do I enter Game Genie codes?

Tools | Manage Cheats... automatically displays a table of all Game Genie codes from the cheats database found for the current game. These cheats can be enabled or disabled by clicking on the checkboxes in the first column. If a code doesn’t appear on the list, it can be entered manually by clicking on New.

How do I invent new cheats?

Tools | Cheat Search... will bring up the Cheat Search window. Each row in the table on the right corresponds to a CPU RAM address. Columns R0 and R1 represent snapshots of memory; they are initialized to 0’s. Pressing the Snap R0 or Snap R1 will fill the respective column with values. In addition, per the Pause after snap checkbox, snapshotting memory will also pause emulation. Once the columns are populated with values, the rows can be filtered using the options above the Snap buttons.

The idea is to snapshot memory before and after an event and compare the results. For example, you can snapshot immediately before and after the player loses a life. By comparing the results, you might be able to track down which address stores the lives counter.

The panel on the left enables you to enter in a new cheat. The Address is the memory location to be affected. The Value is what the emulator will receive when it reads from that Address. Compare is an optional field; when present, the emulator compares it against the actual value stored at the Address. And, only when they match will the emulator receive the substitute Value.

On a side note, Game Genie and Pro Action Rocky codes are limited to addresses $8000 or above. However, Nintaco cheat codes do not have this restriction, making it possible to generate cheats directly from RAM comparisons.

How else can I monitor changes to RAM?

Debug | RAM Search... provides a tool similar to Cheat Search. However, it shows changing values in real-time. When a table row is selected, several options become available, including an Add Cheat button. The Watch button will start tracking the associated address in the RAM Watch window, which can also be opened via Debug | RAM Watch...

How do I invent new Game Genie codes?

Game Genie and Pro Action Rocky codes affect reads from PRG ROM, addresses $8000 and above. The codes effectively act as program patches. The first step for inventing a new Game Genie code is the same procedure describe above for inventing a new cheat: pinpoint where relevant values are stored in RAM. Next, by using breakpoints in the Debugger, locate which parts of the executing program affect those RAM addresses. Finally, using knowledge of assembly language, create one more or Game Genie codes that modify the program’s behavior. The Compare value described above is used to confirm that the relevant PRG bank is loaded.

What is Hot Swap?

Machine | Hot Swap... simulates changing cartridges without turning off the power. The second game will begin executing with the memory state of the first game.

This can be used to warp to unofficial worlds in Super Mario Bros. Here’s how:

Open Super Mario Bros. and select Machine | Hot Swap... When prompted, hit Yes, and then open Tennis. Reset until it starts. Begin a game, toss the ball twice, serve and walk around briefly. Next, select Machine | Hot Swap... and re-open Super Mario Bros. Again, reset until it starts. Finally, hold down A and press Start to continue in what it will interpret as a prior game on some unofficial world. The number of steps taken while walking around in Tennis affects which world you’ll end up in.

Alternatively, select and copy the program below:

10 FOR I=&H7D3 TO &H7DC:POKE I,0:NEXT
20 POKE &H7FF,&HA5
30 INPUT "WORLD=";A
40 POKE &H7FD,A+255AND255

Next, start Family BASIC and paste in the program via Machine | Family BASIC | Paste Program. Press F8 to run it. When you are prompted with WORLD=?, type in a world number and then hit Enter. It should print OK in response. Next, select Machine | Hot Swap... and open Super Mario Bros. Reset until it starts. Finally, hold down A and press Start to warp to the specified world.


Debugger

How do I start the Debugger?

Debug | Debugger...

The Debug menu also provides access to the OAM Data, Pattern Tables, Nametables, Hex Editor, Assembler-Disassembler, RAM Search and RAM Watch windows.

How do I use the Debugger?

To begin debugging, the actively running game needs to be paused. It can be manually paused via the Pause button or it can be paused automatically by setting up breakpoints. Once paused, the panel on the left will show the disassembly and the PC pointer. To advance the PC, the Step Into button will execute one instruction. Step Over does the same; however, JSR will run until RTS. Step Out runs until the current subroutine ends. The neighboring buttons are variations of this (hover the mouse over the buttons to see tooltips). For instance, if you click on an address in the disassembly, it will populate the Seek To: and Step To: fields. Pressing Step To: will execute until the specified address is reached.

The debugger shows the current values of CPU and PPU registers and the data on the stack. Register values can be changed before executing successive instructions.

How do I run the Trace Logger?

The Trace Logger can be started from the Debugger by pressing the Start Logger button. It can also be launched from the main menu via Debug | Start Trace Logger. Both of those are toggle buttons; use the same to stop logging.

The Config Logger… button within the Debugger and Options | Trace Logger... in the main menu will enable you to configure what data gets logged. Note that logging will stop automatically after the specified Max lines is reached.

How are Camera X and Camera Y computed?

Camera X:((v >> 2) & 0x100) | ((v << 3) & 0xF8) | (x & 0x07)

Camera Y:(y >= 240) ? (y - 16) : y

where y = ((v >> 3) & 0x100) | ((v >> 2) & 0xF8) | ((v >> 12) & 0x07)

and v and x are the current VRAM address (15 bits) and the fine X scroll (3 bits), respectively.

In the Hex Editor, why can't I edit CPU memory beyond $8000?

Some, possibly banked, segment of PRG ROM is mapped to CPU addresses $8000–$FFFF. And, writes to that region may be mapped to registers within the cartridge; writes can trigger bank-switches, which will likely crash the game.

However, it is possible to edit the ROM segment directly. Highlight the region of interest and select Navigate | Go to File Index from the Hex Editor menu. Changes to PRG ROM affect the running game immediately. To preserve the changed ROM, select File | Save File or File | Save File As...

What is a table file?

The region on the right side of the Hex Editor displays the bytes as ASCII characters. However, the mapping between byte value and character can be altered using a table file (*.tbl). Each file line is of the form xx=c, where xx is a 2 digit hex value and c is the associated character. xx=ret is a special escape sequence that will substitute the value with Return (ASCII character $0A). The text region can be edited directly and the mapping will work in reverse to update the bytes.

How do I search the ROM for strings from the Nametable viewer?

With the mouse, highlight the region of interest and hit Search. It will open the Hex Editor at the point within the loaded file where the selection can be found.

How do I use the Debugger with the History Editor or Watch History?

The Debugger is active only when the History Editor / Watch History is playing. Breakpoints and the Debugger Pause button will suspend emulation without affecting play mode.


Family BASIC

How do I enable the Machine | Family BASIC menu?

Opening the Family BASIC ROM will enable the menu.

What is the difference between Paste Program and Type Paste?

Paste Program injects the BASIC code directly into RAM. Type Paste simulates typing on the Family BASIC Keyboard.

It should also be noted that Copy Program copies BASIC code from RAM to the clipboard. And, Load and Save Program... function similarly.

What is the Family BASIC Background Editor?

Family BASIC is primarily designed to create simple games and the built-in background editor is the way to create a single screen world for a game. However, drawing an entire background with a gamepad is a tedious process. Nintaco makes this considerably easier via the Family BASIC Background Editor (Edit Background...).

Draw mode allows you to select a pattern and a palette and then draw freehand in the Background area. Fill mode performs a flood fill. Select & Copy allows you to highlight a region to copy; it automatically switches to Paste mode. The Text button enables you to enter and paste strings. When done with pasting, switch back to Draw mode.

Backgrounds can be loaded and saved from the File menu or directly from the Family BASIC menu.

How do I save a BASIC program to the Data Recorder?

The SAVE command writes a BASIC program to a cassette tape. To save to a file called, "TEST", type in the following, but do not hit Return.

SAVE"TEST"

Start the Data Recorder by selecting Machine | Family BASIC | Record Tape and now hit Return.

It will output:

WRITING TEST

And, when that process is completed, it will display:

OK

Next, select Machine | Family BASIC | Stop Tape.

Finally, select Machine | Family BASIC | Save Tape... to store the tape data to an actual file.

Record Tape actually simulates rewinding the tape back to the beginning before recording. Consequentially, only one file can be stored on the virtual cassette tape. Also, Family BASIC limits file names to 16 characters.

How do I load a BASIC program from the Data Recorder?

If the tape data is in an actual file, select Machine | Family BASIC | Load Tape... to retrieve it.

Next, enter the following command and press Return:

LOAD

Select Machine | Family BASIC | Play Tape. A loading message will appear followed by OK.

Finally, stop the Data Recorder via Machine | Family BASIC | Stop Tape.

Can other games use the Data Recorder?

Yes. Arkanoid II, Castle Excellent, Excitebike, Mach Rider and Wrecking Crew can use the Data Recorder to save tracks or stages created by players. To attach the Data Recorder, first select Options | Ports... to bring up the Ports dialog. Then, switch to Famicom mode and select Data Recorder under the Expansion port. Be sure to select Record Tape to start the Data Recorder before selecting save in the game. And, select Play Tape after selecting load in the game.

How do I configure Family BASIC?

Options | Family BASIC...

That dialog enables you to adjust keyboard entry timing values and the Data Recorder sampling period. The default sampling period should work for Family BASIC and the other games that use the Data Recorder. If you encounter data errors, try decreasing the value.

What is a .tape file?

Nintaco stores cassette data in a proprietary file format. The file consists of short header followed by the bit stream emitted to the Data Recorder, sampled at a fixed rate. The prior answer explains how to adjust the sampling period.


Legal

How much does Nintaco cost?

It's free.

How do I donate money to further the development of Nintaco?

You don't. There is no means of paying for any aspect of Nintaco.

Can I use Nintaco for business, commercial, school or government use, or is it only free for "personal" use?

Nintaco is free for all of these purposes. You may install it on as many systems as you would like. There are no license fees of any kind.

Can I mirror or host Nintaco on my own website?

Yes. Just don’t charge users to download Nintaco.

What license applies to Nintaco?

GNU Lesser General Public License v2.1 (LGPLv2.1)

The full license can be viewed via Help | License...

Can I hack up the source?

Sure. If you modify Nintaco, document the changes and license the result under LGPLv2.1.

Can I use Nintaco as a library?

You can use Nintaco’s resources as a library in your own software, even commercial software, with a few restrictions. If you release your software under LGPLv2.1, then use Nintaco’s resources as you like. If you release under a different license, then in principle, it should be possible to swap in other compatible versions of Nintaco’s resources. Meaning, Nintaco’s resources shouldn’t be baked into your software in such a way that the boundary between them is unclear. Subclassing Nintaco’s classes is one way to blur that boundary. But, you can get around that by packaging up any changes to Nintaco into an external form that is licensed under LGPLv2.1 and shipping that modified version along with your software.

Can I box up Nintaco into an emulator machine and then market the machine?

This is similar to the prior question. You can do it as long as Nintaco’s resources could be swapped in with other compatible versions, at least in principle. But, you do not actually need to provide a way to upgrade to newer versions of Nintaco. You just need to keep Nintaco’s resources clearly separated from your own and you need to release any modifications made to Nintaco under LGPLv2.1.

Is this an official product?

Nintaco and its author is not affiliated with or endorsed by Nintendo Co., Ltd. or Nintendo of America in any way. "Nintendo", "NES", "Famicom", "Zapper", "R.O.B.", "NES Advantage", "Super Mario Bros.", "Excitebike", "The Legend of Zelda", "Mach Rider", "Wrecking Crew", "Family BASIC" and "Famicom Data Recorder" are products and/or trademarks of Nintendo Co., Ltd.


Contact

How do I contact the author?

Email: moc.liamtoh@1__o

NesDev board presence: enoorez

How do I report a bug?

Use the contact information above. Or, post a message on NesDev, a community of brilliant coders and hardware archivists.

Please provide the log files in the system subdirectory in your bug report.


Copyright © 2017 nintaco.com
Nintaco is free software; you can redistribute it and/or modify it under the terms of LGPLv2.1.