Direct N64 controller access plugins for mupen64plus and Project64

What is it for?
Screenshots
Supported adapters
How it works
Special builds
Download
Usage (Project64 under Windows)
Usage (1964 under Windows)
Usage (mupen64plus under Windows)
Usage (mupen64plus under Linux)
Confirming that it works (mupen64plus)
Disclaimer

What is it for?

Everything shown works!

These mupen64plus and Project 64 plugins use the direct controller access feature offered by my N64 to USB adapters (versions 3 and up) to let the emulated game communicate with the controllers directly.

So, what does this do for you? Many things! Here are the key advantages:

No calibration required. As the game talks to the controller directly, it reads exactly the same axis values it would in a non-emulated setup. In other words, the controller works, responds and feels exactly as it would in real life.
Low latency. When the game must read the controller, the request is forwarded directly to the controller by the adapter. The later immediately returns the controller's answer to the game.
Potential support for any expansion accessory without any intervention nor device-specific functionality required on the part of the emulator, of the plugin or of the adapter (except for the direct access feature), which means:
- Rumble pack support (tested)
- Memory pack support (tested)
- Transfer pack support (confirmed)
- Bio sensor support (tested)
And just like with a real N64 system, you simply need to insert the accessory you wish to use and the game will take care of everything else. No emulator configuration required to switch accessory...
Support for peripherals other than controllers.
- N64 mouse (tested)
- VRU (confirmed, requires special ports1_4 version of the plugin)
- N64 Keyboard (not confirmed^[1])

^[1] I cannot test accessories I do not own yet. But the nice thing about this plugin is that it probably already works. Please contact me if you get the chance to test.

Warning: This project is experimental and still in development. While it is already usable, some of the features above, especially the ones that are unconfirmed, may be found not to work at all. There can (and will) be bugs, and there are still many missing features such ~~as multi adapter support.~~ Your help and patience in testing as well as your constructive feedback are welcomed.

Screenshots

Here are a few screenshots taken with a memory card present in the N64 controller. The Mario Kart 64 built-in mempak manager (hold the START before running the emulator) is usable despite a few visual glitches. Then once in the game, we can see ghost data exists (saved in a previous session. The emulator had been restarted since). Later (and on a different machine, in this screenshot on a Linux system) the data written by MK64 can be accessed with the adapter management tool.

MK64 built-in manager

Ghost

Adapter manager

Note: For now at least, it is better not to run the adapter manager and a game (with this plugin) at the same time.

Contributions:

Controller, Transfer and Tremor paks

MaMaLuigi9001 tested the Transfer Pak and a Tremor Pak Plus (Third party Rumble Pak equivalent) and reports it works fine. The games he tested with the Transfer Pak are Pokemon Statium and Pokemon Statium 2, using Project 64 version 2.3.0.216 under Windows 10. He mentions however that the emulator crashes with a blank screen when he goes to the Gameboy Tower...

Here are a few screenshots of the Pokemon games:

Pokemon Stadium

Pokemon Stadium 2

MaMaLuigi9001 also confirmed the VRU works, but the ports1_4 version of the plugin where adapter port 2 acts as N64 port 4 is required. This version will be included in release 1.0.0.

VRU

Supported adapters

This plugin is for third generation raphnet GC/N64 to USB adapters. If you are not sure which generation yours are, there is a very quick way to tell: If it has a removable USB cable, it is a third generation unit.

Photo	Model(s)	Supported?
	ADAP-GCN64-USB_V3: N64 or Gamecube controller to USB adapter (V3, Black Edition) ADAP-GCN64-USB-V_V3: N64 or Gamecube controller to USB adapter (V3, Violet Edition) Prototype units (ADAP-USB-GCN64-V3-PROTO) and pre-release units (ADAP-USB-GCN64-V3-PR) are also supported!	Yes
	ADAP-N64-USB_V3: N64 controller to USB adapter (V3, Black Edition)	Yes
	ADAP-2XN64-USB: Dual N64 controller to USB adapter	Yes
	ADAP-GCN64-USB: N64 or Gamecube controller to USB adapter (no longer manufactured)	No
	ADAP-N64-USB: N64 controller to USB adapter (no longer manufactured)	No

Note: It's not that I do not want to support old versions. It's just that direct controller communication is not possible with those.

How it works

Here is a diagram outlining the main differences between the usual architecture (input-sdl) and this plugin.

The normal event chain is more or less the following: (written with mupen64plus in mind, but also applies to project64)

The adapter polls the controller and stores the answer containing button and axis status data in RAM.
The host PC polls the adapter over USB and receives the most recently read data.
This newly received data makes its way through a few software layers including the HID driver, the DirectX (DirectInput) or joystick driver and the SDL library. (The data is in fact stored in a buffer somewhere)
When the game being emulated requests a controller status update, an answer is built using the most recent data returned by the SDL library.

Pros	Cons
The emulator does not need to wait. Relatively fresh data is always available immediately (the SDL library returns it without delay) so the emulator only needs to reformat the data to make it look like what a real controller would answer. This approach works with almost all controllers and adapters usable through SDL.	The exact axis value are often lost (calibration, dead-zone, assumptions on the exact axis range from the part of the emulator that are not met by the adapter-driver stack, etc) and restoring the original feel can require a lot of subjective tweaking. The emulator needs to know what kind of pack to emulate (i.e. mempak or rumble a pack?). This means the user must configure this depending on the game. While rumble packs can work mostly as intended (through HID PID) mempack emulation is almost always virtual (i.e. file-backed).

Pros

Cons

The emulator does not need to wait. Relatively fresh data is always available immediately (the SDL library returns it without delay) so the emulator only needs to reformat the data to make it look like what a real controller would answer.
This approach works with almost all controllers and adapters usable through SDL.

The exact axis value are often lost (calibration, dead-zone, assumptions on the exact axis range from the part of the emulator that are not met by the adapter-driver stack, etc) and restoring the original feel can require a lot of subjective tweaking.
The emulator needs to know what kind of pack to emulate (i.e. mempak or rumble a pack?). This means the user must configure this depending on the game. While rumble packs can work mostly as intended (through HID PID) mempack emulation is almost always virtual (i.e. file-backed).

The "direct access" event chain is more or less the following:

The emulated game requests a controller status update.
The plugin forwards the request as-is to the adapter through USB.
The adapter in turn forwards it to the actual controller (or other peripheral).
The controller (or peripheral) answers the request.
The adapter receives the answer and retransmits it through USB.
The input plugin receives it and serves it unmodified to the game.

Pros	Cons
The game actually communicates with the controller. Accessoires such as memory packs and rumble packs (and potentially others) are therefore supported natively. The answer from the controller does not undergo any transformation. The axis values received by the game are exactly what they would be on a non-emulated setup. No unknowns and no tweaking!	Since the request has to do a round-trip to the controller, the action of reading the controller status takes a bit more time. When there are a lot of exchanges (especially when writing and reading mempacks) this can cause a temporary slow down of the emulator. Only possible on adapters offering a way to communicate with the controllers directly. (For me of course that's a pro)

Special builds

The .zip files for Project 64 (see the download section) contains several raphnetraw DLLs. Here's a summary of what those are and what they are for:

Name	Filename	Purpose and description
Standard	pj64raphnetraw.dll	The standard version. Supports up to 4 players through any combination of 1 and 2 player adapters.
Single player	pj64raphnetraw_1player.dll	Special version supporting only one controller, regardless of how many ports your adapter has. Meant for use with dual-controller adapters where there can be, depending on the game, a small performance penalty caused by polling the second (unused or absent) controller. If you mostly play alone, you should use this version. When playing with friends, you should use the above (Standard) version.
Ports 1 and 3	pj64raphnetraw_ports1and3.dll	Special build where the first two adapter ports are mapped to ports 1 and 3 on the emulated N64 console. Intended to be used with Densha de GO! where the game expects a special controller in port 3.
Ports 1 and 4	pj64raphnetraw_ports1and4.dll	Special build where the first two adapter ports are mapped to ports 1 and 4 on the emulated N64 console. Intended to use with the VRU which must be connected to port 4.
Net	pj64raphnetraw_net.dll	There are some (currently) unexplained compatiblity issues for netplay with Project64k. It does not work unless a very old adapter firmware (v3.3.2) is used. A feature was introduced in firmware version 3.4.0 to boost performance, and raphnetraw v0.9.4 make use of it, but when this feature is used, it breaks netplay... As a temporary solution, this version disables the use of the offending feature and hopefully fixes netplay.

Download

Question: Which file do I need? What is the difference between the .zip and .tar.gz files?
Answer: The .zip files contain ready to use plugin files (.DLL) for Windows. The .tar.gz files contain the source code. If using Linux, this is what you need.

RSS feed for this table

Version 1.0.7 June 28, 2021 (Monday)
Fix controller swapping for some games. Show a message box when attempting to configure the plugin. (contributed by CEnnis91)
File(s): pj64raphnetraw-1.0.7.tar.gz (21.6 KB) pj64raphnetraw-1.0.7.zip (490.2 KB)

Show previous releases...

Version 2019-07-16 July 16, 2019 (Tuesday)
Maintenance for mupen64plus only: (for project64, see previous releases) Update to input plugin API 2.1.0
File(s): mupen64plus-input-raphnetraw-1.1.0.tar.gz (30.6 KB) mupen64plus-input-raphnetraw-windows-1.1.0.zip (262.6 KB)

Version 2018-10-06 October 6, 2018 (Saturday)
Maintenance: Support for adapters running firmware version 3.6.x
File(s): pj64raphnetraw-1.0.6.tar.gz (21.3 KB) pj64raphnetraw-1.0.6.zip (483.1 KB) mupen64plus-input-raphnetraw-1.0.2.tar.gz (30.3 KB) mupen64plus-input-raphnetraw-windows-1.0.2.zip (262.2 KB)

Version 1.0.5 May 16, 2018 (Wednesday)
Bugfix/maintenance: Add protection against invalid commands (Fixes errors when using more than one controller pak) Disabled logging (slight increase in performance)
File(s): pj64raphnetraw-1.0.5.zip (483 KB) pj64raphnetraw-1.0.5.tar.gz (21.3 KB)

Version 1.0.4 November 22, 2017 (Wednesday)
pj64 plugin version 1.0.4 and mupen64plus plugin version 1.0.1: Add support for the upcoming 3.5.x adapter firmware (2-player adapters won't work properly otherwise)
File(s): pj64raphnetraw-1.0.4.tar.gz (21 KB) pj64raphnetraw-1.0.4.zip (204.6 KB) mupen64plus-input-raphnetraw-1.0.1.tar.gz (30.2 KB) mupen64plus-input-raphnetraw-windows-1.0.1.zip (161.9 KB)

Version 1.0.3 April 16, 2017 (Sunday)
Bugfixe(s): Fix ports 1 and 3 special version Another attempt to fix netplay (version 1.0.2 did not work)
File(s): pj64raphnetraw-1.0.3.tar.gz (20.9 KB) pj64raphnetraw-1.0.3.zip (204.6 KB)

Version 1.0.2 April 10, 2017 (Monday)
New special builds: Add a single-port version (improves dual-port adapter performance in some situations by not attempting to poll non-connected controllers) Add a netplay version. ~~(Single player only. Hopefully this one will work with the newest firmware)~~Update: Unfortunately, it did not.
File(s): pj64raphnetraw-1.0.2.tar.gz (20.7 KB) pj64raphnetraw-1.0.2.zip (203.9 KB)

Version 1.0.1 February 4, 2017 (Saturday)
Add another special build where two-port adapters act as N64 ports 1 and 3. (This is in the hope that the Densha de GO! controller will then work.)
File(s): pj64raphnetraw-1.0.1.tar.gz (20.3 KB) pj64raphnetraw-1.0.1.zip (139.2 KB)

Version 1.0.0 January 15, 2017 (Sunday)
New features and internal changes: Now supports multiple adapters simultaneously. Includes a special build for PJ64 where two-port adapters act as N64 ports 1 and 4 (For VRU use)
File(s): mupen64plus-input-raphnetraw-1.0.0.tar.gz (30.1 KB) mupen64plus-input-raphnetraw-windows-1.0.0.zip (161.8 KB) pj64raphnetraw-1.0.0.tar.gz (20.3 KB) pj64raphnetraw-1.0.0.zip (106.6 KB)

Version 0.9.4 December 3, 2016 (Saturday)
Maintenance release: Improved structure and separation for easier maintenance of the code shared between the Project 64 and mupen64plus versions of this plugin. Support for the upcoming 3.4.x adapter firmware (will provide even lower latency/overhead)
File(s): mupen64plus-input-raphnetraw-0.9.4.tar.gz (29.8 KB) mupen64plus-input-raphnetraw-windows-0.9.4.zip (161 KB) pj64raphnetraw-0.9.4.tar.gz (19.6 KB) pj64raphnetraw-0.9.4.zip (72.8 KB)

Version 0.9.3 November 26, 2016 (Saturday)
Optimisation and bug fix: Only handle channels supported by the adapter. This increases performance (reduces lag) by preventing meaningless attempts to communicate with controllers connected to non-existing ports on the adapter. It also fixes issues where games would see more controllers than actually present (on single-player adapters).
File(s): mupen64plus-input-raphnetraw-0.9.3.tar.gz (26.8 KB) mupen64plus-input-raphnetraw-windows-0.9.3.zip (158.4 KB) pj64raphnetraw-0.9.3.tar.gz (16.1 KB) pj64raphnetraw-0.9.3.zip (71.6 KB)

Version 0.9.2 November 24, 2016 (Thursday)
Reliability fix: Protect against invalid commands received from emulator. This fixes some games that failed to start. (The issue was present in PJ64 and mupen64plus)
File(s): mupen64plus-input-raphnetraw-0.9.2.tar.gz (26.3 KB) mupen64plus-input-raphnetraw-windows-0.9.2.zip (155.7 KB) pj64raphnetraw-0.9.2.tar.gz (15.9 KB) pj64raphnetraw-0.9.2.zip (69.4 KB)

Version 0.9.1 November 23, 2016 (Wednesday)
Changes specific to the Project64 version: Changed the plugin specification version (Now using v1.0 instead of v1.1) in order to be usable with old Project 64 releases (v1.4 - v1.6). Changes common to both plugins: Controller polling is now disabled only while a ROM is open. (In the previous version, after using the plugin, to use the adapter normally (eg: Through DirectInput) one had to disconnect and reconnect it.
File(s): mupen64plus-input-raphnetraw-0.9.1.tar.gz (25.8 KB) mupen64plus-input-raphnetraw-windows-0.9.1.zip (155.6 KB) pj64raphnetraw-0.9.1.tar.gz (15.2 KB) pj64raphnetraw-0.9.1.zip (69.3 KB)

Version 0.9.1
November 23, 2016 (Wednesday)

Changes specific to the Project64 version:

Changed the plugin specification version (Now using v1.0 instead of v1.1) in order to be usable with old Project 64 releases (v1.4 - v1.6).

Changes common to both plugins:

Controller polling is now disabled only while a ROM is open. (In the previous version, after using the plugin, to use the adapter normally (eg: Through DirectInput) one had to disconnect and reconnect it.

File(s):
mupen64plus-input-raphnetraw-0.9.1.tar.gz (25.8 KB)
mupen64plus-input-raphnetraw-windows-0.9.1.zip (155.6 KB)
pj64raphnetraw-0.9.1.tar.gz (15.2 KB)
pj64raphnetraw-0.9.1.zip (69.3 KB)

Version 0.9b November 22, 2016 (Tuesday)
First release for project64
File(s): pj64raphnetraw-0.9.tar.gz (13.8 KB) pj64raphnetraw-0.9.zip (69.3 KB)

Version 0.9 November 20, 2016 (Sunday)
First release version (mupen64plus)
File(s): mupen64plus-input-raphnetraw-0.9.tar.gz (25.7 KB) mupen64plus-input-raphnetraw-windows-0.9.zip (155.4 KB)

This project is also available on GitHub!
To request features, report issues or contribute, you may send me an email or use the GitHub repository:
https://github.com/raphnet/mupen64plus-input-raphnetraw

This project is also available on GitHub!
To request features, report issues or contribute, you may send me an email or use the GitHub repository:
https://github.com/raphnet/pj64raphnetraw

Usage (Project64 under Windows)

To install and use the PJ64 plugin, there are two files to place at specific locations.

1: Copy the following file to "your PJ64 installation directory"/Plugin/Input:

pj64raphnetraw.dll

(for older PJ64 versions (such as v1.4), place the file directly in the Plugin directory as there are no subdirectories per plugin type).

2: You must also copy the following file to your PJ64 installation base directory (i.e. The directory where the .EXE is):

libhidapi-0.dll

Then in the settings dialog, select "raphnetraw for Project64 version xx.xx" in the Input plugin list.

Installing the plugin (pj64raphnetraw.dll)

Installing the support file (libhidapi-0.dll)

Input plugin selection (PJ64 v2.3)

Note: The current version of the plugin will create a log file named raphnetraw.log in your home directory.

Usage (1964 under Windows)

Only the "net" version (see Special versions) of this plugin is compatible with 1964. This is due to a performance hack that only works with Project64. (This hack was also found to break net play).

Installation for use with 1964 is as follows:

Copy the raphnetraw_net.dll file to the plugin/ directory in the 1964 folder.
Copy the libhidapi-0.dll file to the 1964 directory (not the plugin directory)
Select the raphnetraw plugin from the list in the Change Plugins dialog.

raphnetraw_net.dll in plugin/

libhidapi-0.dll in the 1964 folder

Plugin selection

Usage (mupen64plus under Windows)

The .zip version of the plugin available from the downloads section above contains the 32 and 64 bit versions of the plugin files. The .zip contents will look like this:

mupen64plus-input-raphnetraw-windows-0.9/
mupen64plus-input-raphnetraw-windows-0.9/README.md
mupen64plus-input-raphnetraw-windows-0.9/dist_win64/
mupen64plus-input-raphnetraw-windows-0.9/dist_win64/libhidapi-0.dll
mupen64plus-input-raphnetraw-windows-0.9/dist_win64/mupen64plus-input-raphnetraw.dll
mupen64plus-input-raphnetraw-windows-0.9/dist_win32/
mupen64plus-input-raphnetraw-windows-0.9/dist_win32/libhidapi-0.dll
mupen64plus-input-raphnetraw-windows-0.9/dist_win32/mupen64plus-input-raphnetraw.dll

If you use a 64-bit version of mupen64plus, copy the files from the dist_win64 directory. For the 32-bit version, copy the files from the dist_win32 directory.

Copy the appropriate plugin (.dll files) to the directory your mupen64plus installation uses for plugins (eg: Along with the main executable and other plugin .DLL files). Then run the emulator like this:

$ mupen64plus --input mupen64plus-input-raphnetraw

(of course you will add other arguments such as the rom file...)

Usage (mupen64plus under Linux)

Copy the plugin (.so file) to the directory your mupen64plus installation uses for plugins. Then run the emulator like this:

$ mupen64plus --input mupen64plus-input-raphnetraw

(of course you will add other arguments such as the rom file...)

Confirming that it works (mupen64plus)

If you are not sure if you were able to enable, have a look to the emulator output:

Disclaimer

I cannot be held responsible for any damages that could occur to you or your equipment while following the procedures present on this page. Also, I GIVE ABSOLUTELY NO WARRANTY on the correctness and usability of the informations on this page. Please note, however, that the procedures above have worked in my case without any damages or problems.

Now you cannot say that I did not warn you :)