1. Installation
2. Navigating the Menu
3. Loading Software
4. Configuring Input
5. Customization
6. Screen Effects
7. Per-Game Profiles
8. Exploring Features
9. Command Line Options
10. Language Support
11. Troubleshooting

BigPEmu doesn't require an installation process, just download the latest version and unzip it somewhere (with directory structure intact), then run the BigPEmu executable file.



To stay up to date with the latest version of BigPEmu, there's a "Check for Updates" menu item under the application's "Information" menu. Selecting this item will automatically check for available updates and, if any are available, BigPEmu will be updated in-place (wherever you're running it from) to the latest version.

By default, the menu can be navigated with the arrow keys on the keyboard, with Enter and Escape functioning as "Accept" and "Cancel" (or "Back") respectively. You can hold the Jaguar's "Pause" button in the menu ("Q" on the keyboard by default) at any time to get a list of menu controls and their active bindings.



Any keys/buttons bound to the Jaguar's directional pad and face buttons can also be used to navigate the menu. This allows for intuitive default mappings for any device listed in the built-in controller database.

Software can be loaded from any of the supported file types (.j64;.cof;.rom;.jag;.abs;.zip;.cue;.cdi) through the "Load Software" menu item. This menu item will be selected by default.



BigPEmu also supports loading cartridge images through zip files, but be aware that it will just scan the top level directory in the zip file and accept the first file with a supported extension. The criteria for what BigPEmu will accept as a loadable cartridge image is very loose, by design. This means that it's not too difficult to make the emulator crash by throwing bad images at it, so you'll probably want to avoid doing that.

If you're playing a game from the Jaguar's retail library, it's strongly recommended that you make sure the 64-bit FNV-1a hash for the ROM image you're loading matches the hash listed on the compatibility page. The hash for your ROM image will be visible in the upper-right of the browser by default:



If the hash for your image does not match the hash provided on the compatibility page, compatibility is not guaranteed. Bug reports will not be accepted in cases of bad dumps, ROM images with missing headers, and so on. It should also be noted that for disc-based images, in order to avoid reading the entire image, the calculated hash is only based on the ToC (which may be partially derived if the image is missing information) and part of the boot track. This means that in addition to making sure the FNV-1a hash matches the one given on the compatibility page, you should use an alternate checksum to verify that your image matches a good source and is known to run well on hardware.

Through the stock input plugin, BigPEmu supports virtually any input device that your system recognizes. If the device is already in the internal controller database and it's attached when you run BigPEmu for the first time, input bindings will be automatically assigned for the device. Typically, "Input Device 1" will correspond to player 1's controller, "Input Device 2" will correspond to player's 2 controller, and so on. However, this mapping can get complicated with Team Tap emulation. See the emulator's in-menu description prompts for details.



If you wish to swap devices or assign inputs for a newly-connected device, you'll need to go into the appropriate device input menu and use "Reset All" in the binding menu in order to assign defaults for the new device. Rather than resetting, you can also manually assign inputs for your device of choice. Manually assigning inputs will also be necessary in cases where your input device doesn't have its own mapping in the controller database.

Every input device in the controller database will effectively be mapped to Xbox controller inputs. You'll also see Xbox button/analog/etc. glyphs in the interface. Specialized glyph sets for different controller types may be added in the future. For now, if you don't have an Xbox controller, you get to do some extra mental gymnastics.

Under each input device, you will be able to set the device type (choosing from a variety of supported native Jaguar input devices), as well as enter the binding menu:



The binding menu offers a great deal of flexibility. You can specify a number of different potential triggers for each Jaguar input, and specify an optional hold input for each trigger. The default binding setup uses the "left trigger" (or your input device's equivalent) as a hold key in order to map many of the controller's buttons to buttons on the Jaguar's number pad when the trigger is held. However, it may often be preferable to map those Jaguar inputs to something like directions on an analog stick. The system allows this, and analog/digital inputs can be bound to Jaguar analog/digital inputs interchangeably.

Additionally, it will often by more convenient to use the "Set All" option near the top of the binding menu instead of navigating through and changing each trigger manually.



Set All will prompt you to provide an input for each Jaguar input, and will automatically overwrite any existing triggers which are provided by the device for which you've provided the new input. What a confusing sentence! Trust me, though, it's not too complicated.

It may also be important to take note of the "Share Xbox Triggers" option in the Input menu. If you have an Xbox controller and you've found that the triggers are incorrectly bound, try enabling this option and resetting the device's bindings. Because of a Microsoft engineer's ancient sin, we have ended up in a situation where a given controller masquerading under a single GUID can either share a single analog axis for the triggers or use separate axes, and we don't have a good way of knowing which (maybe checking driver versions and getting into crappy process permission issues, but to hell with that), and this is why manual intervention may still be necessary here. Normally, I would advise you to try updating the drivers for your device, but in many cases Microsoft has also made that impossible for mysterious (maybe terrible) reasons.

Another tool that you may find helpful is the Input Overlay. This overlay is a toggle which can be assigned to any key, you'll see it near the end of the input list in the binds menu. The scale and placement of this overlay is customizable through the Input menu.



It is a terrifying sight to behold after first, but once you adjust, it can be a helpful way to quickly remember the bindings for those number pad keys if you have a fairly complicated setup like this one. As you can see in this Cybermorph example, if you've provided a pad overlay image for the currently loaded software, it will also be composited into the controller image for this overlay.

Additionally, although BigPEmu doesn't use SDL (at least not in any of the stock plugins), it does support SDL-style gamecontrollerdb.txt files! If you put this file in the same directory as the BigPEmu executable, it will be used instead of the internal database. This is another means by which, if you prefer it to just manually adjusting binds in the emulator, you can adjust the defaults for your device or add mappings for new devices.

BigPEmu allows you to specify custom images for backgrounds, box art, and controller overlays. It also looks for the same MRQ files used by Jaguar Game Drive, in order to provide title metadata as well as (low resolution) box art. Here's an example of a fully decked out setup for Cybermorph:



Take note of each name/extension suffix here. Each file has the following role:

.mrq - The JGD-format MRQ file. Provides additional title metadata.
.png - High-resolution box art. This overrides the low-resolution box art in the MRQ file, which would otherwise be used in absence of the PNG.
_bg.png - This background will be displayed behind the visible area when the software is loaded. It will automatically be stretched to the extent of the application's viewport, so it's up to you to find/create an image with an aspect ratio and resolution that looks good with your settings.
_padol.png - This image will be composited into the Jaguar controller in both the binding menu and the Input Overlay.

You can find the example Cybermorph pad overlay image here. Thanks to AtariAge for the source image. Stick to the image space in the cm_padol.png, and you'll be good to go in creating your own overlay images. As you can see, it's fine to leave the tags in, they'll be handled in the compositing. Just remember that the alpha channel is still important!

It's also possible to specify a global background for all software, keeping in mind that it will be overridden if a software-specific background image exists. This is done by placing a bg_common.png file next to the BigPEmu executable. Whenever this file is present, it will be used as the default background. If you want something more interesting than a static image for your background, however, that's what screen effects are for!

Screen effects are represented by .dstack (Dick's Post Stack) files, located in BigPEmu's Data/ScreenEffects directory. These files are parsed as JSON and specify one or more passes, with each pass specifying a vertex/pixel shader and potentially referencing other passes or additional (texture) resources. Screen effects can be selected under the Video menu, and the effect browser is populated by the .dstack files in Data/ScreenEffects.



To you, our precious End User, screen effects represent some bitchin' effects. BigPEmu includes some basic (demonstrative) effects, as well as a few excellent shaders written by Hyllian, which I've taken the liberty of auto-translating into the Dick Stack system.


The Shadertoy screen effect, using some unmodified Shadertoy code thanks to assistance from the Shadertoy template.
BigPEmu also comes with a Shadertoy template, which by default includes this shader by Matt Halford. You will probably not want to play this way, unless you spent your Jaguar years in a fallout shelter playing on a CRT with a wide array of severely damaged components. However, it's here for demonstrative purposes. You can copy-paste Shadertoys straight into shadertoy.glsl to apply them as screen effects. However, the template functionality is limited, so if you get into more advanced effects which depend on additional resources, you'll have to make some modifications to the .dstack and template files.

Screen effect passes can also render outside of the game region, set blend modes, and achieve quite a few interesting effects with a minimal number of passes.



The system itself supports shader inputs in a variety of languages including GLSL, ESSL, and HLSL. However, since there is only one video plugin at the moment, GLSL is all you need to worry about if you want to try your hand at writing your own effects. If more video plugins come online in the future (although this is probably not really necessary, since OpenGL/GLES is supported by all targets of interest at the moment), I'll provide some tools to automate (completely or at least mostly) the translation process.

As a mercy, I've also written a command line program which can auto-translate RetroArch's .slangp ("preset") files directly over to the Dick Stack system. I don't guarantee that it supports the whole gamut of RetroArch's preset/shader functionality, or that it produces good/efficient output, but it seems to work well enough on the stuff I've tried. You can download it here.

I've taken the liberty of auto-translating a few of those preset files with this program, which you can download here. Extract that zip straight into Data/ScreenEffects, and you'll be all set. Check the included documentation (and probably do some amateur sleuthing) for information on the complicated web of licensing/copyrights. I'm not totally sure who owns what in there, so I would probably not want to distribute any of it in direct connection to anything else, but it does include this excellent Mega Bezel shader by HyperspaceMadness. (and by quite a few others, from what I gather)



Indeed, it's hard to find a game that doesn't look good with a nice Dick Stack at 4K in HDR.

BigPEmu supports per-game profiles. This is accomplished by creating a BigPEmu configuration file of the same name as the software image you're loading, with a .bigpcfg extension. For example, if your software image file is named Cybermorph.j64, you would create a Cybermorph.bigpcfg file alongside it.

In order to create the per-game configuration file, it's recommended that you just make a copy of your central BigPEmu configuration file. Under Windows, you can find this file at %APPDATA%\BigPEmu\BigPEmuConfig.bigpcfg. (which usually resolves to something like C:\Users\YourUsername\AppData\Roaming\BigPEmu\BigPEmuConfig.bigpcfg) Other platforms may vary. It's sufficient to simply copy this file and rename it.

Once you've created the game-specific configuration file, all configuration changes made through the menus while the game in question is loaded will apply and be saved only to this configuration file. If the software is unloaded, the central configuration will be loaded again.

BigPEmu is packed full of all kinds of special options and features. These options allow you to fine-tune virtually every aspect of your Jaguar experience. Don't be afraid to explore the menus! You'll find that nearly every menu item has some (usually rather elaborate) descriptive text which pops up when you highlight it!



As seen above, the menu takes care to tell you exactly what you're getting yourself into with the HDR options. You'll find the same thing everywhere. More video options, audio processing and buffering options, and options which allow you to modify and enhance the Jaguar itself. Every option is designed to bring you joy, or maybe sorrow, so take a look around and enjoy every little crevice of BigPEmu.

BigPEmu always expects the first command line argument to be a software (e.g. cartridge) image path. This also allows BigPEmu to be associated with image file extensions, to auto-load an image when it's drag-and-dropped onto the executable, and so on. When launching BigPEmu with a ROM on the command line, the intro sequence is also skipped. If you'd like to skip the intro and load directly into the menu without actually loading any software, specify * in place of a valid path.

All additional command line options must come after the first path argument, whether it's a valid path or an asterisk. Available options are:
Some command line options also exist for the internal Benjamin Kitten auto-regression tester. I'm not bothering to document them for the time being, because normally aging humans probably won't have a use for them.

BigPEmu has a custom localization system, designed to make additional language support both easy and efficient. Any text file in BigPEmu's Strings directory will be seen as a language file. Language files should all be encoded as UTF-16. (it's convenient for the system, as I do enjoy the benefits of linear string data over the small increase in memory footprint)

If you're finding that BigPEmu is displaying a lot of characters for your paths in the file browser as question marks, it's probably because you're using characters that aren't included in the default character set and aren't used in any of the localized text. A fun trick to get around this is to make a dummy string (just call it STR_DUMMY) in the localized text file and include all of the characters of interest in that string. BigPEmu will regenerate the font cache on startup to include those characters. Note that you may also need to change the LOC_SETTING_FONTCHARSET setting in the language file, if the desired characters don't exist in the selected/default character set.

If you want to add support for a new language to BigPEmu, great! Just keep a couple of things in mind. First, BigPEmu is under active development, so future versions could invalidate your language file or leave a lot of new options untranslated. Second, please don't distribute BigPEmu in its entirety along with your language file. Instead, please distribute the language file alone and direct people to download BigPEmu from the official site. This solves many problems (including bug reports from stale builds which users don't think to update) and eliminates some of the potential for unofficial, virus-ridden emulator builds to begin circulating. (either intentionally, or unintentionally as a result of passive executable modifications occurring on an infected system)

When distributing a language file, it's also recommended that you distribute the generated .bigpfc file alongside it. This will eliminate any font/character set dependencies on the user's system, and will ensure that everyone sees the same thing when using your language file. It's also possible that BigPEmu will be ported to platforms where native character set availability is limited, or font cache generation is not supported at all.

If you're experiencing audible skips/pops along with a low native framerate, make sure you're running on adequately powerful hardware. BigPEmu has fairly low system requirements, with much of the Jaguar's retail cartridge library running fine on most processors (in the x64-capable realm) with clockspeeds around 1GHz. However, some games in the library may require something closer to 1.4GHz. (if there are few to no idle cycles, heavy Blitter use, etc.) CD games are generally more expensive (usually due to more excessive interrupt requirements), and some may require clockspeeds closer to 1.6GHz to run smoothly.

If BigPEmu initially ran without any issues but has stopped working, resetting your configuration is the first thing you should try. You can accomplish this by deleting your BigPEmuConfig.bigpcfg file. Under Windows, this file is located at %APPDATA%\BigPEmu\BigPEmuConfig.bigpcfg. (which usually resolves to something like C:\Users\YourUsername\AppData\Roaming\BigPEmu\BigPEmuConfig.bigpcfg) Feel free to make a backup of this file first, in case deleting it doesn't solve your problem, or in case you'd like to later troubleshoot to identify which setting is causing your problem.

If BigPEmu still fails to load with a default configuration file, the next step is to enable logging and check the log file. See Command Line Options for more information. The log may reveal more information about the problem which BigPEmu is encountering on your system. You can also try the -forcecompat command line option to attempt to rule out problems with the video plugin.

When all else fails, or when you determine that you're experiencing a problem related to the video plugin, update the drivers for your graphics/display device. There's always a fairly good chance that some basic OpenGL feature is somehow broken in any given version of any given vendor's drivers, because that shit happens. It's certainly happened to me more than once!

After verifying that your display device driver is up to date and functioning correctly, it's also a good idea to make sure all of the other device drivers on your system are up to date. If you're running under Windows, make sure there are no issues reported in the Device Manager.

If you're encountering an issue with a particular piece of software, such as an audio timing or stability problem, see if the software is listed on the compatibility page. If it is, make sure the hash for your cartridge/disc image matches the one provided on that page. Additionally, you can try making changes to the Jaguar's system settings (under "System" and "Settings" in the menu) to see if any of these overrides help. You may have to restart the Jaguar, or at least reload a saved state, for some of those settings to take effect. The first setting to try is "Lockstep Mode", setting it to "Close" or "Closest" can potentially resolve many different issues. This option does place a greater performance burden on the host machine, but your machine can probably handle it. In some rare instances, changing "Blitter Speed" to "Free" may alleviate timing issues, but take note that this is more often likely to create stability problems.

For disc-based software, changing the "CD Seek Speed" setting (for example, setting it to "Free") may resolve timing or stability issues. Some titles in the known software library may require this, as they'll crash even on hardware in some circumstances if disc seek times vary too much. Additionally, do not explicitly set a cartridge image when running CD software, unless the CD software is designed to work with that cartridge. This has the potential to cause all kinds of adverse effects.

If none of the above has resolved your problem, you may have a genuine bug on your hands (or maybe a terrible virus is ravaging your system), so you can head on over to the bug report section.