Skip to content

Latest commit

 

History

History
155 lines (110 loc) · 5.62 KB

README.md

File metadata and controls

155 lines (110 loc) · 5.62 KB
Raw

PlasticBand-Unity

An add-on for the Unity InputSystem package that provides mappings and classes for Rock Band and Guitar Hero peripherals.

Table of Contents

Usage

After installation, this package integrates and operates on its own. No manual initialization is required.

Device layouts from this package are used just like the built-in ones. You can use them in input actions, poll them manually through the provided static current and all properties on each layout, receive low-level InputEventPtrs through InputState.onChange, etc.

Warning

Usage of InputSystem.onEvent for low-level state handling is not recommended, as many layouts in this package have their own manual state handling requirements (see IInputStateCallbackReceiver) which will be bypassed if you use it. Use InputState.onChange or IInputStateChangeMonitors instead. I've done my best to keep compatibility where I can, but certain spots are just inherently incompatible, and there's not much I can do.

In addition, some special handling will be needed for InputSystem.onDeviceChange with regards to the variant device system that this package uses for certain devices. Any devices being InputDeviceChange.Added where device.enabled is false must be ignored, as these are the container devices used to enable variance. An example of this is provided in the DeviceConnectionHandler sample.

This package has no dependencies, however I highly recommend installing the HIDrogen package in addition to this one, as it helps provide additional controller support that Unity does not provide on its own.

Notes

  • Unity 2022.2 and onward do not natively support XInput instruments. This can be addressed by using v0.4.0 or higher of HIDrogen.
  • Pre-compiling the layouts from this package is not currently possible without breaking things. A large number of them have to determine or construct things at runtime, and pre-compilation circumvents the mechanisms that allow these layouts to determine things in the first place.
    • At some point I could consider looking into workarounds for this (e.g. initializing everything in an OnAdded override), but for the time being it's not a priority. (PRs welcome if you can get it worked out!)
  • Xbox 360/One controllers will only work properly on Windows currently. Mac and Linux require custom drivers or support through raw USB handling.
  • Xbox One support on Windows requires the HIDrogen package to be installed alongside this one. No errors will occur without it, but they will not be detected by the input system otherwise.

Configuration

Some configuration is available through compile defines:

  • PLASTICBAND_VERBOSE_LOGGING: Enables some potentially repetitive logging to help debug issues with devices.
  • PLASTICBAND_DEBUG_CONTROLS: Enables verbose logging for custom control types to help debug issues with devices.
    • Independent from verbose logging, since this is strictly meant for active development and debugging.

Supported Devices

5-Fret Guitars

Guitar Hero

  • Xbox 360
  • PS2
    • Likely won't be possible to support directly, PS2 adapters are all over the place and usually show up as PS3 controllers.
  • PS3
  • Wii
  • Santroller

Rock Band

  • Xbox 360
  • Xbox One
  • PS3
  • PS4
  • Wii
  • Santroller

TODO: Auto-calibration sensors; not currently possible due to Unity not supporting HID feature reports.

Riffmaster

  • Xbox One
  • PS4/5

Other

  • Guitar Praise

6-Fret Guitars

  • Xbox 360
  • Xbox One
  • PS3/Wii U
  • PS4
  • iOS
  • Santroller

4-Lane Drumkits (Rock Band)

  • Xbox 360
  • Xbox One
  • PS2/PS3
  • PS4
  • Wii
  • Santroller

5-Lane Drumkits (Guitar Hero)

  • Xbox 360
  • PS2/PS3
  • Wii
  • Santroller

DJ Hero Turntables

  • Xbox 360
  • PS3
  • Wii
  • Santroller

Rock Band Pro Guitars

  • Xbox 360
    • Tilt on this model is unsupported unfortunately, due to not being reported through XInput.
  • PS3
  • Wii

TODO: Auto-calibration sensors; not currently possible due to Unity not supporting HID feature reports.

Rock Band Pro Keyboards

  • Xbox 360
  • PS3
  • Wii
  • Santroller

Rock Band MIDI Pro Adapters

  • Xbox 360
  • PS3
  • Wii

Rock Band Stage Kits

  • Xbox 360
  • Santroller

Rock Band Legacy Adapters

  • Wired (Xbox One)
  • Wireless (Xbox One)

License

This project is licensed under the MIT license. See LICENSE.md for details.