buttplugio/buttplug-unity

Unity plugin for Buttplug.io

Buttplug Unity

Unity Package for Buttplug support in Unity 2019.4+.

NOTE: This package may work as far back as Unity 2018.2, but for anything before Unity 2019.4, you may need to provide your own Newtonsoft.Json.dll package. We now rely on the built-in library from unity by default.

Buttplug Unity is a repackage of the Buttplug C# Libraries for Unity.

Unlike older versions. Buttplug Unity v3 and later DO NOT CONTAIN ANY EXECUTABLES OR WAYS TO ACCESS HARDWARE. It is assumed that users will have Intiface Central installed.

It is highly recommended that developers check out the Buttplug Developer Guide for more info on Buttplug architecture and usage before delving into using this package with their Unity project.

Installation

Option #1: OpenUPM CLI

If you have the OpenUPM command line interface installed, then this is the fastest way to add the package to your project:

• Open your Unity project folder in a terminal like CMD or PowerShell
• Run openupm add com.nonpolynomial.buttplug-unity

Option #2: Use OpenUPM's Installer Package

You can download and import the ButtplugUnity installer package which sets up the package reference and then removes itself.

• Download the Latest Buttplug Unity Installer Package
• In Unity, use Assets > Import Package > Custom Package...
• Open the downloaded package.
• Click Import

Option #3: Edit Package Manager

You can also manually perform the setup steps in Unity 2019+.

Add the OpenUPM registry and Buttplug Unity's scope to Project Settings:

• Go to Edit > Project Settings > Package manager
• Click the + button in the registry list
• Name it OpenUPM
• Set the URL to https://package.openupm.com
• Set the Scope to com.nonpolynomial.buttplug-unity
• Click Apply

Add the Buttplug Unity package in the Package Manager:

• Go to Window > Package Manager
• Use the drop down in the upper left to select My Registeries
• Select the ButtplugUnity package
• Click Install

Options #4: Clone This Project

This is a fully functional Unity project that you can clone as your own. This will mean you have the Buttplug Unity package files locally, so you'll need to manually update the package or pull latest from this project as updates are made.

• Clone https://github.com/buttplugio/buttplug-unity with your favorite Git client
• Open root of the cloned project folder in Unity >= 2019.
• Open the Example/Example.unity scene file to run the example script.

Usage

See the Buttplug Unity example directory as well as the Buttplug Developer Guide for code and usage advice.

Note that this repo is a complete Unity project that can be opened and run in Unity.

Using Buttplug consists of the following steps:

• Setting up a connector and client
• Connecting to a server
• Scanning for devices
• Controlling devices

In Buttplug C# (which Buttplug Unity is built on), most of these are async functions, as accessing both the network and the hardware are slow functions that can block. We highly recommend executing tasks on background thread pools, as not to interrupt game actions.

FAQ

What hardware will this work with?

An up-to-date list is kept at IOSTIndex, using the Buttplug C# filter.

Why do I have to run Intiface Central alongside my game?

Intiface Central is a cross platform application for running Buttplug servers and managing updates. Buttplug (the library) and Intiface (the official application layer on top of Buttplug) change frequently and allow for deep user configuration. Intiface Central manages those updates and configuration, meaning game devs only need to worry about connecting to Central and controlling devices.

Why not run hardware access inside the game process? By hosting hardware access externally, we minimize the impact of errors and crashes on the game process. While we certainly do our best to avoid errors, dealing with hardware can sometimes be a dynamic and challenging situation, where an extended period of normal usage can be suddenly interrupted by shit going absolutely fucked. By keeping process separation as a boundary, we can assure games that as much of the fuckery as possible stays on the Buttplug side.

Does Buttplug Unity work with IL2CPP?

Yes.

Can I use Buttplug Unity in my commercial game?

Yes, Buttplug Unity falls under the same BSD 3-Clause license as the rest of the library, meaning you just need a copyright acknowledgement in your game credits and license file. If you are interested in featuring our logos on your loading screen (which we appreciate!), please contact us on Discord or Twitter to discuss.

How can I get direct support from the Buttplug developers for my game?

The Buttplug Developers are happy to consider paid support contracts. Please contact us on Discourse, Discord or Twitter to discuss.

I don't see my question here, what should I do?

• File an issue on this repo
• Check our forums
• Join the Discord Server and ask there

Contributing

If you have issues or feature requests, please feel free to file an issue on this repo.

We are not looking for code contributions or pull requests at this time, and will not accept pull requests that do not have a matching issue where the matter was previously discussed. Pull requests should only be submitted after talking to qdot via issues on this repo (or on discourse or discord if you would like to stay anonymous and out of recorded info on the repo) before submitting PRs. Random PRs without matching issues and discussion are likely to be closed without merging. and receiving approval to develop code based on an issue. Any random or non-issue pull requests will most likely be closed without merging.

If you'd like to contribute in a non-technical way, we need money to keep up with supporting the latest and greatest hardware. We have multiple ways to donate!

• Patreon
• Github Sponsors
• Ko-Fi

License

This project is BSD 3-Clause licensed.

Copyright (c) 2016-2024, Nonpolynomial, LLC
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
  list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.

* Neither the name of buttplug nor the names of its
  contributors may be used to endorse or promote products derived from
  this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.