Implementing libpd4unity in Unity 5

Screen Shot 2016-03-10 at 16.16.02

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

  1. Download the libpd4unity files from github
  2. Create a new project or open an existing one
  3. Open the libpd4unity folder you downloaded
  4. Copy LibPdFilterRead.cs, PluginUtils.cs, Plugins (folder), LibPD (folder) and Streaming Assets (folder) into your Assets folder of the Unity project.
  5. Copy your Pd patch and any abstractions into StreamingAssets > PdAssets
  6. 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.
  7. 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.

    Screen Shot 2016-03-01 at 18.28.31.png
    Adding an AudioListener in the inspector view
  8. 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.
  9. 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.
Screen Shot 2016-03-01 at 18.29.24.png
Adding the LibPdFilterRead script and naming the patch

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:

Screen Shot 2016-03-10 at 15.12.35.png

Create a new C# script called “oscControl” and place it on the LibPD object 

osccontrol.gif
Creating a new C# script

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).

runtime.gif
Changing the frequency of the oscillator from the inspector window.

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/

http://twobigears.com/labs/unity-and-libpd/

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s