A libpd wrapper for Unity.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Assets
docs/images
extras
LICENSE.txt
README.md
ToDo.txt

README.md

LibPd Unity Integration

About

LibPdIntegration is a wrapper for libpd developed at Abertay University for incorporating Pure Data patches into Unity. It currently supports Windows and OSX.

Unique Features

LibPdIntegration offers a couple of features which set it apart from existing implementations of libpd for Unity:

  • It works with recent versions of Unity (at time of writing, tested on 2018.1 and 2018.2).
  • It supports multiple instances. This was impossible with previous implementations, as libpd itself did not support running multiple patches side by side. The libpd developers have recently removed that limitation however, meaning LibPdIntegration can allow developers to run multiple PD patches in their Unity projects. This also means it's now feasible to build a 3D scene in Unity with multiple PD patches all spatialised using Unity's audio code.

Quickstart

This repository contains everything you need to incorporate PD patches into your Unity project. First download it from the releases page, then copy the contents of the Assets folder into your project's Assets folder. LibPdIntegration provides native libpd binaries for supported platforms in the Plugins subfolder, and a single C# script, LibPdInstance.cs in the Scripts subfolder.

PD patches should be placed in the StreamingAssets/PdAssets folder (you can create your own subfolders within).

To associate a PD patch with a Unity GameObject, you need to add a single Lib Pd Instance Component to the GameObject. Doing this will also add an Audio Source Component; this is necessary because Unity does not process audio for GameObjects without an Audio Source.

Lib Pd Instance is our wrapper for libpd. To associate a PD patch with it, drag the patch from your StreamingAssets/PdAssets folder to the Patch selector in the Inspector.

LibPdInstance Inspector Patch Selector

Note that the order of Components matters. Audio Source must come before Lib Pd Instance.

The Pipe Print To Console toggle provided by Lib Pd Instance lets you pipe any print messages sent by your PD patch to Unity's console for debugging purposes. Note that due to a limitation with libpd, this toggle is global. i.e. if you activate it for one Lib Pd Instance, it will be active for all Lib Pd Instances.

See the sister project LibPdIntegrationExamples and the wiki for more information, including how to communicate between Unity and libpd.

Spatialisation

There are a number of different methods for spatialising Pure Data patches in Unity. At the time of writing, the simplest method involves the use of one of Unity's included Spatializer plugins.

For example, to use the OculusSpatializer plugin, you will first need to update your project settings:

  1. Edit -> Project Settings... -> Audio.
  2. Set Spatializer Plugin to OculusSpatializer.

Unity Audio Settings: Spatializer Plugin

Then, for each Audio Source in your scene, set the Spatial Blend slider to 1(3D), and toggle the Spatialize and Spatialize Post Effects options:

Audio Source Spatial Blend slider

Audio Source Spatialize toggles

For a complete list of spatialisation methods, see the Spatialisation page on the wiki.

Caveats

  • Only Pure Data Vanilla is supported. Additional objects included with distributions like Purr Data and Pd-Extended do not currently work (it's not clear yet whether this is a Unity-specific issue or an bug with LibPdIntegration).
  • Although libpd provides C# bindings, 1.) I could not get them to play nicely with Unity, and 2.) they don't currently support libpd's new mutiple instance system. As such, LibPdIntegration interfaces directly with the libpd C library. This may change if libpd's C# bindings get updated in the future, but they should be functionally identical to the C library anyway, so I'm not sure it's necessary.
  • In order to get libpd working with Unity, a small patch to libpd is necessary (included in this repository). The native Plugins in this repository include this patch, but if you want to deploy to other platforms, you'll need to apply the patch yourself. This should no longer be necessary with the latest version of libpd.

Future Plans

  • Support for more platforms. As libpd itself is provided as a native binary, it needs to be compiled for each platform you plan to deploy to. This is complicated slightly by the fact that LibPdIntegration requires a patch to libpd (included in this repository), so any existing libpd binaries found on the internet will not work. The plan is to provide binaries for more platforms as time and resources allow.

  • Expand the example project.

  • Gallery of projects using LibPdIntegration?

Pure Data Resources

Credits

LibPdIntegration is developed by Niall Moody at Abertay University, with assistance from Yann Seznec. It is licensed under the MIT License.