Following on from a tutorial I ran for the Interactive Sound Environments students at the University of Edinburgh, in March 2016, I thought it may be helpful to centralise my notes about how to use libpd4unity in your own projects.
Libpd4unity is a way of embedding Pure Data within your games allowing you to design a highly flexible and dynamic sound engine of your own.
While previously it was only possible to run libpd4unity in Unity Pro due to restrictions on the use of plugins, Unity 5 changed this, making the whole process much more accessible.
Implementing libpd in Unity
- Download the libpd4unity files from github
- Create a new project or open an existing one
- Open the libpd4unity folder you downloaded
- Copy LibPdFilterRead.cs, PluginUtils.cs, Plugins (folder), LibPD (folder) and Streaming Assets (folder) into your Assets folder of the Unity project.
- Copy your Pd patch and any abstractions into StreamingAssets > PdAssets
- If there isn’t already an AudioListener component on any of the game objects e.g. Main Camera, then create an empty game object in your scene, name it LibPd for easy reference.
- Add an AudioListener component (if there’s not already one), this will act at the
dac~object in Pd. Any spatialisation must be manually programmed, so the position of the Audio Listener has no effect on your Pd sounds unlike when using Unity’s inbuilt sound source components or middleware such as FMOD or Wwise.
Adding an AudioListener in the inspector view - Drag the LibPdFilterRead.cs script onto the game object where the audio listener component is placed (e.g the LibPD or Main Camera game object). This is where the patch is loaded from. Be careful to only include one instance of LibPdFilterRead.cs in your scene.
- Write the name of the Pd patch you copied into the Streaming Assets folder in the “Name of Patch” field in inspector. Note: This is case sensitive so be sure to copy the name exactly, including the .pd extension.
If your Pd patch requires no control to trigger sounds, when you press play you should now hear some sound!
Communicating with Pure Data from Unity.
Pure Data patches really come to life through user interaction, communicating with your patch is straight forward.
At the top of the C# script from which you would like to send a value to your Pd patch, add in the following:
using LibPDBinding;
If you wish to send a float to Pd use:
LibPD.SendFloat(“yourPdReceiveName”, yourValue);
If you wish to send a bang to Pd use:
LibPD.SendBang(“yourPdReceiveName”);
A quick example:
Say you want to control the frequency of the oscillator in this patch:
Create a new C# script called “oscControl” and place it on the LibPD object
Right click on the script and choose Edit Script, this will open MonoDevelop
Replace the default code with:
using UnityEngine;
using System.Collections;
using LibPDBinding;
public class oscControl : MonoBehaviour {
public float frequency;
void Update () {
LibPD.SendFloat ("frequency", frequency);
}
}
In the inspector you should now be able to alter the frequency of the oscillator at runtime (when you press Play).
General Tips
If you find your project crashing, it could be because some Pd objects aren’t supported, therefore to avoid problems, test your patch regularly once integrated in Unity and stick mostly to pd-vanilla objects.
Don’t use [print] objects in your Pd patches.
The above method will work for OS X standalone builds and Android (as long as you don’t use any abstractions). It won’t work for iOS … but more on this coming soon!
Credits
https://github.com/patricksebastien/libpd4unity
http://www.thefuntastic.com/2014/04/the-misadventures-of-unity-and-puredata-libpd/
Kirsty Keatch 