LibPdIntegration is a wrapper for libpd developed at Abertay University for incorporating Pure Data patches into Unity. It currently supports Windows and OSX.
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 2019.1).
- 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.
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.
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.
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:
- Edit -> Project Settings... -> Audio.
- Set Spatializer Plugin to OculusSpatializer.
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:
For a complete list of spatialisation methods, see the Spatialisation page on the wiki.
- 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.
-
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?
LibPdIntegration is developed by Niall Moody at Abertay University, with assistance from Yann Seznec. It is licensed under the MIT License.