OSX Joystick Mapper Mercurial
Joystick mapping for OSX
Status: Alpha
Brought to you by:
alexandrehardy
Menu
▾
▴
Tree [bbd9f5] default tip / History
Read Me
This package provides joystick mapping support for a limited
set of applications in Mac OS X.
The intention is to provide an equivalent interface to
joymap for linux (http://linuxjoymap.sourceforge.net/).
The best way to do this is probably with kernel extensions
(.kext). Developments in Mac OS X makes this approach
less desirable (to me), since maintaining a signed kext could limit
the applicability of this work.
Instead, joymap for OSX uses DYLD_INSERT_LIBRARIES
to replace the IOKit implementation for an application,
and simulate a joystick in the library layer.
The program assumes a HOTAS kind of layout, where each product
occurs only once in the system (a current limitation).
The IOKit replacement library communicates with the joymap
process using a unix socket.
RUDIMENTARY INSTALLATION AND USAGE
==================================
Make the package with:
make
This creates three dylib files which you can place wherever you wish:
* joymap_iokit.dylib
* joymap_boxer.dylib
* joymap_sdl-1.2.15.dylib
There are also two CLI applications that are built:
* joymap
* jsinfo
* joymap_jsinfo
jsinfo can be used to examine the existing joystick devices, or
the programmed virtual joystick.
./jsinfo (shows a list of devices with vendor and product)
./jsinfo -v (shows additional element information)
./jsinfo vendor product (Continuosly display button and axes values)
joymap_jsinfo connects top the joymap socket and displays joystick status
received via this unix socket.
The program loadmap is used to load a joystick configuration as specified
the doc subfolder, including a joystick program to allow more advanced
programming of joystick actions. The loadmap program opens a socket in
$HOME/.joymap to publish virtual joystick information to any program
which includes joymap_iokit.dylib or joymap_boxer.dylib.
Some example programs are included in the doc subfolder.
To benefit from the virtual joystick you need to launch
the application with DYLD_INSERT_LIBRARIES. For example:
DYLD_INSERT_LIBRARIES=$HOME/joymap/joymap_boxer.dylib open /Applications/Boxer.app
You can use the joymap_boxer.dylib for Boxer (available from http://boxerapp.com/)
(which does not use the newer IOKIT libraries) and joymap_iokit.dylib for
applications that do use the newer IOKIT libraries. For example wine (https://www.winehq.org/).
In addition to the Boxer and standard IOKIT library, an SDL-1.2.15 Joystick replacement
is also provided. Linking is a bit tricky and is typically executed with something like:
DYLD_FORCE_FLAT_NAMESPACE=1\
DYLD_INSERT_LIBRARIES=$HOME/joymap_sdl-1.2.15.dylib:/Library/Frameworks/SDL.framework/SDL\
/Applications/FS2_Open.app
In this case the flat namespace and SDL framework need to be inserted to ensure
the correct SDL framework bindings are used. If SDL-1.2.14 is used instead, then the
application will typically crash.
The libraries *only* simulate a joystick, not a keyboard or mouse.
The loadmap program simulates the keyboard and mouse directly, so it
can be used to simulate keyboard and mouse events using the joystick
for any program.
DOSBOX and Wine
===============
Newer versions of Mac OS X prevent the use of DYLD_INSERT_LIBRARIES and related environment
variables. The source code here provides patches for dosbox and wine that allows
those programs to communicate with the joymap socket and get all joystick events from
there. These applications will have to be recompiled to benefit from these patches.
LIMITATIONS
===========
This is a work in development. Although I find it usable in the current state,
the implementation is incomplete.
* Queues aren't implemented.
* Anything that falls back to using mach_port in some way will not work.
* For the latter case I have resorted to custom built libraries (such as the boxer dylib).
Use of the software is entirely at your own risk.