FP: Currying vs. Partial application

While learning Functional Programming, there were two concepts that for me, were really hard set apart: currying and partial application. One day, I finally decided I would dig deeper and learn what each one represents and more importantly, why I mixed them up. In this article we’ll see what currying and partial application are, distinguish them, see how they’re used in functional languages, discuss why these concepts get mixed up so easily and present why they are so important.

One tiny thing before we start. Even though the concepts we focus are widely used in functional languages, we won’t use a purely functional language to explain them – Python. You have to trust me on this.

Currying

Currying is the process of transforming a function that takes many (N) arguments into a series of (N) functions, each one taking exactly one argument. Well, maybe doesn’t tell us much, but let’s take a look at the example code below and learn from example. The Python code above shows the definition of the mult_pow function, which takes 3 numbers, raises the first one to the power of the second, and multiplies the result by the third one. Pretty straight forward. The only way to evaluate this function is by calling it and providing the 3 arguments.

def mult_pow(x,y,z):
    return x ** y * z

print(mult_pow(2,3,4))
>> 32

Now let’s try to curry this function. As described above, we will transform this function into 3 new functions, each one taking exactly one argument. We call mult_pow_c the curried version of mult_pow.

def mult_pow_c(x):
    return lambda y: lambda z: x ** y * z

Let’s analyze this pice of code for a minute. The function mult_pow_c(x) takes one argument and will always return a lambda, which is… a function! The returned function takes exactly one argument – z – and returns another lambda. This last lambda, again, takes one argument and returns the result. Note that the outer variables x and y are part of the inner function’s closure and can be accessed by it. As you noticed, we did exactly what the definition of currying said two paragraphs ago: we turned a function that takes many arguments into a series of nested functions, each one taking exactly one argument. To put it in a more formal way, currying transforms a function of N-arity into N functions of 1-arity.

Let’s now try to use these two functions and see how their application differ. The first function call uses the uncurried version and the second one the curried version.

print(mult_pow(2,3,4))
>> 32

print(mult_pow_c(2,3,4))
>> TypeError: mult_pow_c() takes exactly 1 argument (3 given)

print(mult_pow_c(2))
>> <function <lambda> at 0x10e908050>

print(mult_pow_c(2)(3))
>> <function <lambda> at 0x10e908668>

print(mult_pow_c(2)(3)(4))
>> 32

The first call (lines 1-2) demonstrates function application on the uncurried version and behaves as expected. But when we try to run the second call (lines 4-5), invoking mult_pow_c instead of mult_pow and passing three arguments to it, we get a type error telling us that we called that function with the wrong number of arguments. And indeed we did. Remember that mult_pow_c is the curried version of mult_pow, hence it only takes one argument. When we give it only one argument (lines 7-8), it returns a function, exactly what we expected from a curried version of mult_pow. In this context, if we have a function, what’s the most reasonable thing to do with it? Apply it! We do so (lines 10-11) and we still got a function in return, which makes sense given that mult_pow originally is a function that takes 3 arguments (3-arity). Only when we apply the functions three times (lines 13-14), we get the result we expected.

Well, well, well. It looks like we just created a super complicated way of defining functions. We need lambdas, unnecessary parenthesis when calling a function and there is a big knot in my head when I think of it. At first sight, it might look like a cumbersome way of doing simple things, but bare with me along the next section so we can understand why this is a powerful tool.

Partial Application

Let’s again use a Python example to illustrate the concept of partial application. The following code defines a function to multiply two numbers – mult – and a function to double (multiply by two) a number – double. Easy peasy.

def mult(x,y):
    return x*y

def double(x):
    return mult(2,x)

Notice that the double is defined in terms of mult. This is a pattern that we’ve seen before and some call it “wrapper functions”. Another good example are the functions pow (power) and square (^2). We use previously implemented functionality and we fix one of the parameters to create a new function. This is also known as partially applying a function, simple like that. Given the original function, we limit its expressiveness by tying some of its parameters. For example, take the * operator (multiplication): initially, its image (the set of possible outcomes) includes all the integers, but when we partially apply it, by tying the first argument to 2 (*2), we reduce the function’s expressiveness by limiting its image to even numbers.

So that’s partial application. On a formal way, partially applying a function to X arguments is the process of transforming a N-arity function into a (N-X)-arity one by means of tying X arguments to values.

Currying vs. Partial Application

Even though the general idea – and even the semi-formal definitions – might seem closely related, keep in mind that unlike currying, partial application does change the function expressiveness and its meaning. Another way of seeing this is to look at both as a function, where currying would be Curry(f) and partial application would be PA(f, x…xn). Currying only takes a function as input and returns another function, whilst partial application takes a function and N (N > 0) parameters.

Also, remember the definitions previously introduced: currying is the process of transforming a function of N-arity into N functions of 1-arity. Partial application is the process of taking a N-arity function, X parameters and transforming it into a (N-X)-arity function. Now, let’s take a look on how these concepts are introduced in functional languages and why we mixed them up so easily.

Currying and Partial Application in Functional Languages

Even though we can manually curry a Python function (just like we did earlier), Python doesn’t support currying by default, which means that the following code doesn’t run, where mult_pow is the function we defined on the first section.

print(mult_pow(2))
>> TypeError: mult_pow() takes exactly 3 arguments (1 given)

That might seem logical for a Python (Or C, C++, Java…) programmer, but it makes currying – something that as we’re going to see, is extremely powerful – a manual, programmer-dependent task.

The twist is that – unlike in imperative languages – in most functional languages, functions are curried by default. This might go by as a simple detail, but it has big consequences, as we’re going to see later. In Haskell or Clean, every function is curried by default. There’s no way of escaping out of it. As a consequence, every function that takes N arguments is actually a function that takes one argument and returns a function that takes N-1 arguments, just like we did on our first Python currying example (mult_pow_c). In addition, we get that for free: there is no need for any special implementation, syntax or annotation. That, aligned with higher-order functions gives us a great toolset to play with functions.

Partial application in such languages becomes so easy because of default currying. As we saw in the Python examples, partially applying a function isn’t as trivial as in a functional language.

Take the following Haskell example in consideration (if you’re not used to Haskell, don’t stop here, I won’t use it too much). We define the function multPow that takes 3 integers as arguments and returns an integer. Remember that since Haskell functions are curried by default, multPow actually is a function that takes an integer as parameter and returns another function that takes 2 integers as parameter.

To prove that, we use GHCi (GHC’s interactive environment), to partially apply multPow to the parameter 2 by doing pMultPow = multPow 2. Due to currying and partial application, pMultPow is a function that takes 2 integers as parameter and returns another one. You don’t believe me? Ask GHCi to give you some information about pMultPow by typing “:i pMultPow” and it will tell you exactly what we expected.

multPow :: Int -> Int -> Int -> Int
multPow x y z = x ^ y * z

-- In GHCi:
> pMultPow = multPow 2
> pMultPow 3 4
32
> :i pMultPow
pMultPow :: Int -> Int -> Int

One interesting fact is that you can notice that from the function’s type annotation itself. We’re used to read Haskell function type signatures in a non-curried manner. For example, we’d read multPow’s type signature as “it takes 3 integers and return an integer”, but we might as well read it as “it takes one integer and returns a function that takes 2 integers and returns an integer”. Both are equivalent in a language that is curried by default.

The Confusion

As we saw, partial application really shines in languages that have functions curried by default because there’s no extra step necessary to define curried function as in most imperative languages. That’s exactly why we easily mix up those concepts: we don’t see the currying, it’s done automatically. So every time someone tries to give an example of currying in a functional language, they fail to point exactly what it represents without using partial application, and the confusion is born. We can avoid that by explaining both concepts using a non-functional language and then bring the discussion back to the shiny, fancy functional world. It’s also why I chose to start this article with Python instead of Clean or Haskell.

Why is it so important?

The triad of higher-order functions, currying and partial application provides powerful benefits including expressiveness, higher level of abstraction and scalability, but there are two aspects that I want to focus: reusability and modularity.

With higher order functions, functions can be returned and passed as parameters, so you don’t need to overload a method, creating 10 different instances of it that are almost equal, except for one function call. Instead, make only one instance of that (previously overloaded) function that takes a function as parameter and every time you call it, pass the desired function.

With default currying, partially applying a function is trivial, which stops you from creating many wrapper functions just to fix some of the arguments. Let’s take the famous map as an example of how these concepts increase modularity and reusability. In Clean, map can be defined as in the code below. Start is Clean’s equivalent to C’s main and function type signatures use the arrow only before the output type (not in between inputs as in Haskell).

map :: (a -> b) [a] -> [b]
map _ [] = []
map f [x:xs] = [f x: map f xs]

double :: Int -> Int
double x = x * 2

Start = map double [1,2,3,4,5]
> [2,4,6,8,10]
Start = map ((*)2) [1,2,3,4,5]
> [2,4,6,8,10]

As we can see – by the (a -> b) – map is a higher-order function: it takes one function as input. It’s also polymorphic, given that it operates on lists of any type (a and b here are type variables). So, as expected, it maps a function over a list, element by element. In addition, we define the double function which… well, doubles a number. After mapping double over a list, we get a list in which all of its elements are the double of the original elements. Notice that we don’t limit the types a and b by any means. Given that, every time I need to apply a function over a list, I use map. Due to its high-order nature, I don’t need to worry about the list type as long as I provide a fit function as argument. That means that I don’t need to write 10 versions of overloaded maps, one for each kind I need, and even for different functions to map over! Imagine creating versions of map in C for ints and doubles, for doubling, squaring, dividing by 2 and many other possible operations. In a functional language, that’s not necessary.

Finally, let’s take a look on the second map example. Instead of defining a new function just to multiply an element by two, I can take advantage of Clean’s default currying and partially apply – on the spot – the * operator on the argument 2, which would give me a new function that takes one integer as input and return an integer – exactly what I need to use map, and exactly what double is.

This is a small and naive example to illustrate one of the biggest advantages of pure functional programming. Since function outputs only depend on its inputs (and nothing else!), and since we have higher-order functions with default currying and partial application, functions are little building blocks. You can just plug them, pass them around, partially apply them, run them over a list and all. That allows a level of reusability and modularity that simply isn’t possible (and won’t ever be) in imperative languages. Functions like map and foldr are reused on a daily bases by functional programmers, along with many functions they’re written themselves. Reusing functions is the bread and butter of a functional programmer. Every time you see yourself writing code that somehow resembles some code you’ve written, you think “how can I generalize this and then specialize it when I need to so I don’t need to write many slightly different versions of the same code?”

Conclusion

Even though currying and partial application are concepts that are related, they are not the same thing. Currying is a process of transforming a function into an equivalent one and partial application involves fixing a function to one of its arguments. Partial application really shines on functional languages where functions are curried by default, and that might be the reason why functional programmers get those concepts mixed up so easily. Allied with higher-order functions, these concepts increase modularity and reusability in an extraordinary way, and that’s one of the aspects where functional programming shines the most.

If you have any comments, suggestions, corrections (especially corrections), please fell free to leave a comments below.

Sources:

I can’t remember all websites that helped me with this, but here are some:

http://www.defmacro.org/2006/06/19/fp.html
https://stackoverflow.com/questions/218025/what-is-the-difference-between-currying-and-partial-application
https://www.schoolofhaskell.com/user/EFulmer/currying-and-partial-application
http://learnyouahaskell.com/higher-order-functions

Advertisements

Android 6 (Marshmallow) permissions and Unity

While working on Overclock, our team faced a new problem with Android 6 (Marshmallow): all permissions were requested when the app launches the first time instead of when the user downloads the app. Not only that, but the permissions are requested individually and not altogether like it used to be, which showed us some permissions we didn’t even notice were there. After some research, we found some answers and some problems and I’ll list them here to hopefully help some developers in the future.

This article will talk about Android 6 permission changes, how Unity adds some of them based on your API requests, how the engine requests them and which changes should be made to this system.

Android Marshmallow’s permission changes

Starting on Android 6, user permissions are requested during run time rather than during installation. According to Google, the change streamlines the installation and update process and allows fine tuning of the app’s functionalities: since the permissions are requested individually, the user can allow some and deny others. For example: an user can grant location privilegies but deny camera permission and the app may function seamlessly. Before the update, given that all the permissions were displayed grouped before installation, denying them would cancel the installation.

The Android Support Library provides us with methods of checking, requesting and dealing with permissions request responses. You can check more about it here.

A bit about Android permissions

In order to fully understand the problem, we must learn a bit more about Android permissions, starting with protection levels.

Protection Levels
System permission are divided into two protection levels: normal and dangerous. Normal permissions usually request data or resources out of the app’s sandbox but that shouldn’t harm the user’s privacy or other apps, e.g., time zone permission. You can take a look at the list of normal permission here. Dangerous permissions request either data or resources that may affect the user’s privacy of the execution of other apps, e.g., read the phone’s contact list and manage phone calls. Normal permissions are automatically granted without user prompt, while dangerous permissions require user authorization.

Permission Groups
Another concept that we should talk about is Permission Groups. Given that the number of permissions available on an Android environment might be quiet long, they are grouped into Permission Groups based on which data or resource it requests access for.

Let’s take the “Contacts” permission group as an example. It contains three permissions: READ_CONTACTS, WRITE_CONTACTS and GET_ACCOUNTS. As you can see, all the permissions are directly related to the user contacts. Groups are extremely handy because if your app needs those three permissions, we don’t need to request each one individually. When we request any permission in the “Contacts” group, we are actually requesting a group permission. Given that, if an app is running on Android Marshmallow requests the READ_CONTACTS permission, the user grants it and later on it requests the WRITE_CONTACTS permission, no prompt will be shown to the user on the latter, because he/she already granted permission to the “Contacts” group. Hence the WRITE_CONTACTS permission shall be automatically granted.

Unity and Android permissions

Now that we know how Android permissions work and what changed after the latest update, let’s understand how Unity handles permissions.

Permissions Added by Unity
One of the most common searches about Unity and Android permissions is “why is my app  requesting permission to make and manage phone calls if I don’t have that on AndroidManifest.xml file?” and that’s exactly how we started our search. After some reading, we found out the READ_PHONE_STATE permission is the source of the problem.

We thought “we don’t need to read the phone state, why is that permission even in the AndroidManifest?” and proceeded to delete the permission request. To our surprise, even after deleting the entry, our app still requested the permission. We thought we were crazy for a second and started to dig in all the AndroidManifest files we have in our project (plugins) looking for that entry, but we couldn’t find it.

The villain
Then, after some more research, we found the villain: SystemInfo.deviceUniqueIdentifier. This simple example shows us how Unity sometimes might be a bit too nosy and adds some permissions to our AndroidManifest on the build process. Some of Unity’s API calls require a permission to be granted to function rightfully. Unity (trying to make your life easier) identifies when your application’s source code contains that call and adds the permission request to your AndroidManifest file during the build process (hence why you can’t find it in your Manifest file). Some might say that’s too much babysitting and some might say it’s a good feature and I personally think there should be a switch on that functionality, but let’s move on.

Now let’s understand why this call needs a permission. The deviceUniqueIdentifier call does exactly what it says: it returns the device’s unique identifier (genius!). This identifier is often used as an ID for guest users so the game can save its progress on the server, even though the user didn’t create an username. This allows users to keep their progress after deleting the app from their phone. Given the premise that every phone has an unique, non-mutable identifier (guess what, it doesn’t), this works great.

The problem lays on how the engine gets that identifier. There is no guaranteed way of getting a phone’s unique ID, but there are some solutions close enough and the IMEI is the most famous and used one. The IMEI is an – usually – unique identifier used to identify most mobile and satellite phones in the world and is generally used to block stolen phones around the globe.

The root of the problems is that to access the phone’s IMEI on an Android phone, you need the READ_PHONE_STATE permission, which is part of the PHONE Permission Group. Now try to guess how a request to that permission group is described. You’re right: “Allow this app to make and manage phone calls?”. That’s right. Just to access the IMEI, you must request permission to the entire PHONE group, which includes making and managing phone calls. It sounds like an overkill, but that’s how Android sets it up.

Recap
So we found the cause of the problem: fetching the device’s unique ID needs the READ_PHONE_STATE permission which is in the PHONE permission group. Unity, trying to help us, automatically adds the permission when the deviceUniqueIdentifier call is present in code. Based on those findings, it looked like there was no scape to that problem: we either don’t use that API call to fetch the device’s unique ID or we accept the problem and move on.

We considered abandoning the guest login option, since we had another login methods (email, Facebook, Game Center) that were also affected by the permission request problem, even though they didn’t even use the device ID. After some talk, we concluded that, from a game design perspective, removing that option was more painful than having that aggressive permission request.

But… What if?

During the talk about Android permissions and mobile games, we noticed that some of the games we played already made use of the runtime permissions, but on a less intrusive way. They only requested a permission when it was really necessary and showed a popup explaining why they needed that permission. That is far from ideal, but solves 2 problems:

  • Request permissions when it’s not necessary
  • Letting the user know why we need that permission

After some digging, we found out that Unity doesn’t provide a way of doing that natively. The engine simply requests every single permission when the app starts and there is no way you can control that. The only tool available is completely turning off the requests, which we will talk about on our workaround.

Non-official workaround
Since Unity lacks of a solution for this problem, we sought an alternative solution. We can’t control when Unity requests the permission, but we can use another tools (1, 2) to do that, totally bypassing Unity. Those tools let us work with the Android 6 permission model inside Unity. One extra step to implement that is to tell Unity to stop requesting the permissions when the app launches. We can do that easily by adding the following line to the AndroidManifest.xml file:

<meta-data android:name=“unityplayer.SkipPermissionsDialog” android:value=“true” />

Conclusion: What Unity should do

The final fix for this problem would be an official solution from Unity: an API that implements the Android Marshmallow (6.0) permission model, giving us control over runtime permission requests. Our team wasn’t the first one to bump into this problem and won’t be the last, and there is a Unity Feedback topic currently open that addresses this very same problem. If you feel affected by this, please vote for it.

Source:
http://developer.android.com/training/permissions/requesting.html
http://developer.android.com/guide/topics/security/permissions.html
http://answers.unity3d.com/questions/1152724/disable-permission-dialog-in-unity-5.html

Unity Serialization Part 3: Scriptable Objects

This post is part of a series about Unity serialization. Click here for part 1: how it works and examples or click here for part 2: defining a serializable type.

On the last article, we learnt how we can define our own serializable types and discovered some problems that can emerge from it. One solution (although not ideal) to our problems is ScriptableObjects. These objects have two major uses: saving and storing data in the Editor and saving and storing data as an asset. According to the documentation, they are optimized and can store huge portions of data. There are a few singularities about Scriptable Objects and we will discuss them on the following paragraphs.

Defining and Creating

Primarily let’s learn how to define a Scriptable Object using the same example we’ve been using in the last article:

public class MyDatabase : ScriptableObject
{
  public List<City> cities;
}

As we can see, the only difference is that our class now derives from ScriptableObject. There is no need to add a serializable modifier to our script, since ScriptableObject derives from Unity.Object and that should be enough to make it serializable. The next step is creating an instance of MyDatabase, which isn’t possible without some extra code. In the past, a mix of EditorUI and AssetDatabase code was required, but recently (Unity 5.1), a simple modifier can make our lives better: [CreateAssetMenu].

[CreateAssetMenu]
public class MyDatabase : ScriptableObject
{
  public List<City> cities;
}

By marking your ScriptableObject with this modifier, a menu item will be created in the Asset/Create menu. Easy like that, this should create an Asset called “New My Database” in the Assets folder and it can be referenced by any MonoBehaviour just like any other type derived from Unity.Obejct. By doing this, we solve the first problem present on the previous blog post: databases should be assets and not MonoBehaviours. Now let’s learn how ScriptableObjects act differently from custom serializable classes in Unity.

Objects are stored as references, not copies

Consider the example from the previous post and think about this: if a MonoBehaviour has two references to the same City object, how will they get serialized? How does the change made in one affect the other? The answer to these questions is slightly counterintuitive:  they are decoupled and serialized separately, hence changing one’s value won’t change the other’s. Let’s see an example using a MonoBehaviour that executes in edit mode just to make things easier:

[ExecuteInEditMode]
public class MonoBehaviourDecoupleTest : MonoBehaviour 
{
  public City city1;
  public City city2;
     
  private void OnEnable()
  {
    if (city1 == null)
    {
      City chicago = new City();
      chicago.name = "Chicago";
      city1 = chicago;
      city2 = city1;
    }       
  }
}

Based on this example, any changes made to the object “city2” are also reflected on the object “city1”, which happens… until you hit play and pause. After doing that, modifying one object doesn’t affect the other. That happens because by hitting play, we force Unity to serialize the scene data, which will serialize each object “in line” (copying all serializable variables into a new object) and not by reference. By doing that, Unity forgets that those two objects were actually the same and treats both as separate objects.

Only classes that inherit from Unity.Object are serialized as actual references and fortunately ScriptableObject can help us with that, since it is a UnityObject. Let’s use the same example, but first let’s define a new City class, this time as a ScriptableObject:

public class ScriptableCity : ScriptableObject 
{
  public string name;
}

Now let’s use it instead of a regular City like the previous example. Note that we have a peculiar way of instantiating a ScriptableObject, and the reason behind that will become clear soon:

[ExecuteInEditMode]
public class ScriptableDecoupleTest : MonoBehaviour 
{
  public ScriptableCity city1;
  public ScriptableCity city2;

  private void OnEnable()
  {
    if (city1 == null)
    {
      city1 = ScriptableObject.CreateInstance<ScriptableCity>();

      city1.name = "Chicago";
      city2 = city1;
    }

    Debug.Log(city1.name);
    Debug.Log(city2.name);
    city1.name = "New York";
    Debug.Log(city1.name);
    Debug.Log(city2.name);
  }
}

We use Debugs to check the data since the inspector won’t show us much useful info easily. Differently from the first example, hitting play and pause won’t decouple the references and both cities will be named “New York”. Notice the difference here: the variables “city1” and “city2” were not serialized as part of the ScriptableDecoupleTest script – which happened in the first example. What Unity actually does is create a scene object (remember the odd way of instantiating it?) and keep it hidden, serialize it as part of the scene, and save its reference in “city1” and “city2”. Therefore, every time we change one variable, the other changes too, since both reference the same object, just like any reference to an UnityObject (Rigidbody, Collider, Renderer…). Thereby, ScriptableObjects solves the third problem presented on the previous blog post: reference decoupling.

We can also use ScriptableObjects as assets instead of scene objects and the effect is the same. In addition, this approach may be considered really specific, but is essential when really complicated relationships must be consistent between objects.

Polymorphism

We face a serialization problem when using polymorphism and custom serializable classes: an instance of a derived class is serialized as an instance of the base class. Let’s use the example the Unity Documentation does: Animals. See the example:

[System.Serializable]
public class Animal 
{
  public string name;

  public Animal (string name)
  {
    this.name = name;
  }
}

Now let’s define the Dog class:

public class Dog : ScriptableAnimal 
{
  public string breed;

  public Dog (string name, string breed) : base(name)
  {
    this.breed = breed;
  }
}

And a simple MonoBehaviour that runs in the editor for testing:

ExecuteInEditMode]
public class BehaviourExample : MonoBehaviour 
{
  public List<Animal> animals;

  private void OnEnable()
  {
    if (animals == null)
    {
      animals = new List<Animal>();
    }
    if (animals.Count == 0)
    {
      Animal elephant = new Animal("Elephant");
      Dog dog = new Dog("Dog", "Bulldog");
      Animal lion = new Animal("Lion");

      animals.Add(elephant);
      animals.Add(dog);
      animals.Add(lion);
    }
  }

  private void OnDisable()
  {
    Debug.Log(animals[1] is Dog);
  }
}

If you have a list of Animals and you add a Dog to it, it will be serialized as an Animal, not a dog. Add this script to an object in the scene and observe the console when you deactivate it, you will see it displays “True”. Nice! That means that Unity knows that that object is a Dog, right? Well, hit play, then stop and do that again. Now it doesn’t remember that anymore, but what happened to that Dog? When you hit play, you told Unity to serialize the scene data, and that’s exactly what it did. It happens that because of how Unity’s serialization process works, it forgets about the fact that the Dog is a Dog and treats it as an animal instead.

ScriptableObjects can help us with that, given that it inherits from Unity.Object and that type is always serialized as references – and never inline. Let’s change the definition of Animal a bit and make it inherits from ScriptableObject:

public class ScriptAnimal : ScriptableObject 
{
  public string name;
}

Now let’s use an equivalent example to the one above, but adapting it to the way ScriptableObjects are created and initialized:

[ExecuteInEditMode]
public class ScriptableExample : MonoBehaviour
{
  public List<ScriptAnimal> animals;

  private void OnEnable()
  {
    if (animals == null)
    {
      animals = new List<ScriptAnimal>();
    }

    if (animals.Count == 0)
    {
      ScriptAnimal a1 = ScriptableObject.CreateInstance<ScriptAnimal>();
      Dog dog = ScriptableObject.CreateInstance<Dog>();
      ScriptAnimal a2 = ScriptableObject.CreateInstance<ScriptAnimal>();

      a1.name = "Elephant";
      dog.name = "Dog";
      dog.breed = "Bulldog";
      a2.name = "Lion";

      animals.Add(a1);
      animals.Add(dog);
      animals.Add(a2);
    }
  }

  private void OnDisable()
  {
    Debug.Log(animals[1] is Dog);
  }
 }

This example is analogue to the previous one, so run it and observe the console. Even after hitting play, stopping the game and disabling the script, we get “True” as output, which means that the Dog is still a Dog and it was serialized as one, keeping the polymorphism intact. Therefore, ScriptableObjects solve the second problem introduced in the last blog post: polymorphism and user-defined classes. This might not be the best solution ever when dealing with serialized polymorphic code (we can’t use constructors anymore and inspecting the objects is a pain) but it may be necessary in some situations.

In addition, a fix to this polymorphism serialization problem has been extremely requested by the community in the last years and haven’t been solved it.

 Serialization depth limit (or no support for null)

Demonstrating an example of the depth serialization problem in Unity is fairly simple. Take a look:

[Serializable]
public class DepthClass  
{
  public List<DepthClass> depthObjects; 
}

This code looks harmless, but it’s not, as seen on the error thrown (on previous versions of Unity it was a warning, or simply didn’t thrown any message at all):

Serialization depth limit exceeded at ‘DepthClass’. There may be an object composition cycle in one or more of your serialized classes.

Let’s understand why. Let’s take a look at the “depthObjects” variable and try to figure out how it would be serialized in Unity if it’s an empty list. The naive thought would say that if it should be serialized as null, like any other field, but it’s not. It happens that Unity doesn’t support null serialization for custom classes (like it does for UnityObjects) and that object will be serialized as en empty instance – which is transparent to the user. On top of that, each of those empty instances has its own “depthObjects” variable, which would be serialized as another empty instance, creating a cycle that would never end, therefore crashing Unity. To avoid that, the folks at Unity Technologies set a limit (7 levels) for serialization depth, which means that after 7 levels of depth, Unity will assume that it hit a cycle and will stop the serialization at that point. Seven levels of serialization can sound like too much, but for some problems, it might be necessary.

Given that, always think twice before serializing any field that has recursive declarations. If it’s not really necessary to serialize it, don’t! But if you really want to use 7 or more levels, or you really need to serialize it, you should use ScriptableObjects. Since ScriptableObjects do support null serialization, this problem simply vanishes:

[Serializable]
public class DepthClass : ScriptableObject
{
  public List<DepthClass> depthObjects;  
}

And this simple change should get rid of the error and let you use more than 7 depth levels of references.

Data can be shared among objects

This problem (although not listed on the previous article) is exactly the same discussed in the Unity documentation about ScriptableObjects. If you store an array of integers that occupies about 4MB in a prefab and you instantiate that prefab 10 times, you would have a copy of the array in each prefab’s instance, occupying a total of 40MB. That happens because the array lives on the script itself, and copying the prefab copies the script, hence the array.

If instead of declaring the array on the prefab’s script you had a reference to a ScriptableObject which contains the array, all the instances would point to the same data. Therefore, 10 instances of that prefab would store 10 references to the same object (and not the actual data), occupying about 4MB only. Not only that substantially saves memory, but changes made to the array from any of the instances will affect the others, maintaining database consistency.

There is a catch, though. What if, instead of storing the array on a ScriptableObject, we store it on an empty prefab with a MonoBehaviour? Let me show what I mean. First let’s create a MonoBehaviour to holds the data:

public class BehaviourDatabase : MonoBehaviour 
{
  public Vector4[] vectors;
}

Let’s add this script to a scene object and save it as a prefab. Now let’s create another script that holds a reference to a BehaviourDatabase, add it to a scene object (let’s call it DatabaseModifier) and drag the prefab we just created to it’s “database” field.

public class MemoryTest : MonoBehaviour 
{
  public BehaviourDatabase database;
}

If we copy this DatabaseModifier object a dozen times and run the scene, we see that it behaviors exactly how we expected the ScriptableObject to behave: they all store a reference to the prefab on the project folder – and not the actual data. Not only that, but any change made on the array of Vector4s will also change the prefab’s data. Well, but if that also works, so why use ScriptableObjects instead of a prefab and a MonoBehaviour to store only data as an asset?* That’s what I tried to find out, but coudln’t find any solid, convincing and direct answer. Among some reasons, I found that:

  • We don’t have a GameObject and a Transform and any overhead it can create;
  • The idea behind a prefab is that it can be instantiated multiply times in runtime, which isn’t our case;

Those are not really convincing, but I personally rather have a ScriptableObject just because of the second reason. For the other uses, though, ScriptableObejcts are extremely recommended.

*Note the emphasis on _data_only_. Using a prefab and a MonoBehaviour won’t solve the other problems.

Conclusion

In this article we learnt how to solve some problems (most described on the last article) that may emerge when dealing with custom serialized types and Unity serialization. Even though some problems can be solved by using ScriptableObjects, it’s far form ideal.

 

Unity Serialization Part 2: Defining a Serializable type

This post is part of a series about Unity serialization. Click here for part 1: how it works and examples.

On the last article, we discussed about serialization concepts and how Unity implements it, learning which types can be serialized and which cannot. But what if we want to define our own type? How can I make it serializable so I can keep its data stored?

Understanding the problem

Let’s choose a (slight biased) model to implement as our example: a script to keep all the data to an investigation game which contains numerous cities, each one containing several places. Sounds pretty easy and straightforward, so let’s do it naively by creating MonoBehaviours: one for the database, one for the cities and one for the places. That should work:

public class MyDatabase : MonoBehaviour
{
  public List<City> cities;
}

public class City : MonoBehaviour
{
  public string name;
  public List<Place> places;
}

public class Place : MonoBehaviour 
{
  public string name;
}

There, done! But wait a second, something’s wrong: I can’t just create an instance of a MonoBehaviour, it should be attached to a GameObject and I don’t want to create a one to each instance of a city or place. Something is wrong conceptually. It happens that we can’t think of that data as behaviors, because they are not. They are simply objects, just like good old object-oriented programming. So let’s go ahead and take the MonoBehaviour inheritance from the City and Place classes.

public class City
{
  public string name;
  public List<Place> places;
}

public class Place 
{
  public string name;
}

Now let’s add the MyDatabase script to an object in the scene. Something is wrong again: I can’t see the list of cities in the inspector even though the field is public and should be serialized (therefore shown in the inspector).

Screen Shot 2015-09-20 at 7.47.14 PM

Defining a Serializable Type

That happens because we didn’t define our type as serializable, so Unity won’t serialize it. We never faced that problem before because we usually deal with classes that inherit from Unity.Object (Collider, RigidBody, Animation, MonoBehaviour…), which is a serializable type. There is an easy way to do it: add the [System.Serializable] modifier to the class:

[System.Serializable]
public class City 
{
  public string name;
  public List<Place> places;
}

[System.Serializable]
public class Place 
{
  public string name;
}

That gives us the expected result:

Screen Shot 2015-09-20 at 7.52.02 PM

By simply adding that modifier, we mark our class as serializable and solve our problem. The same process is also required when dealing with structs (serializable since Unity 4.5). In addition, Unity also serializes lists and arrays of serializable types by default.

Problems with that approach

Although this looks like a great solution, there are a few problems with it. The first (but not biggest) is that even though MyDatabase only stores data, it still is a MonoBehaviour and needs a GameObject to exist. Ideally, it should be an asset that only holds data, but we can’t simply take the MonoBehaviour inheritance off the class, otherwise we wouldn’t have a way to serialize it. What if there was a serializable type just like MonoBehaviour that doesn’t need a GameObject to live on? Keep that in mind. The other problems doesn’t involve data-storing objects only like the first one, but are also valid.

The second problem involves polymorphism and happens when a class inherits from a user-defined serialized class. Even though it’s intuitive that fields from both classes should be serialized regardless, that doesn’t happen. Let’s use the same example as Unity blog does: animals.

[System.Serializable]
public class Animal 
{
  public string name;
}

[System.Serializable]
public class Dog : Animal 
{
  public string breed;
}

public class PolymorphismExample : MonoBehaviour 
{
  public Animal[] animals;
}

Even though both Animal and Dog classes are serializable and Dog inherits from Animal, if we add a dog to our list of animals in PolymorphismExample, they will be serialized as Animals, losing the Dog type and consequently its fields. What if user-defined classes supported polymorphism? Again, keep that in mind.

The third problem is related to decoupled references, which is a fancy name to something really simple. Imagine you have the same Animal example as the problem above and you add 3 animals to your array, but all of them point to the same object. Due to how Unity’s serialization works, these references are decoupled and they are serialized as three different objects, hence changes made to any of those three objects won’t affect the other two. Unity simply forgets that those objects point to the same reference, which can be devastating to systems that keep complex relation between objects of that class.

The decoupling problem happens because these fields (primitives and user-defined) are serialized “in line” since they are actually part of the MonoBehaviour’s serialization data and not a data object itself. With objects that derive from Unity.Object though, the fields are serialized as actual references to the object, and not “in line” like custom classes. What if we could use a class that derives from Unity.Object, serializes the objects as references and maintains complex relations between our objects?

The last problem is related to recursive declarations, which can generate cycles. Consider this example:

[Serializable]
public class DepthClass  
{
  public List<DepthClass> depthObjects; 
}

And a MonoBehaviour that holds a reference to an instance of it:

public class DepthTest : MonoBehaviour 
{
  public DepthClass test;
} 

How many allocations will be done to serialize an uninitialized “DepthTest” script? The intuitive answer would be 1 – a null reference – but it happens that the Unity serializer doesn’t support null references of custom classes so it creates an empty object and serializes it instead (this is transparent to the user). And since this object is created and it has a reference to a list of objects of its own type, it creates a cycle in the serialization process that should go on forever. To prevent this cycle (for real, it’s not a joke) the Unity guys picked the – magical – limit of 7 depth levels and after reaching that level, the serializer will assume that a cycle was defined and will stop serializing fields of custom classes. What if we could use a type that supports null in the serialization pipeline?

Each problem described above has a potential solution and It turns out that all four can be fixed with the same resource: ScriptableObjects. It’s not an extremely elegant or ideal solution, but it’s the closest we get from one. Since it’s a fairly long subject, Scriptable Objects are described in depth on my next article. For now, let’s just acknowledge that those problems have a common way out and if you believe you may face one of those, take a look into it.

Modifiers and Serialization

Finally, let’s summarize the modifiers involved in serialization.

  • Use [System.Serializable] on a class or struct definition if you want it to be serialized;
  • Publics fields are serialized by default, but only if its type is serializable (constants, static and readonly fields are not serialized);
  • Use [SerializeField] if you wish to serialize a private field;
  • Use [NonSerialized] if you want to avoid serialization on a public field;
  • Use [HideInInspector] if you want to serialize but not expose the field in the inspector;

Conclusion

In this blog post we learnt how to define our own serializable types and acknowledged some problems that can emerge by doing it. On the next article, we will dive deep into a resource that can work out those problems: ScriptableObjects.

Reference

Unity Manual: Script Serialization
Unity Blog: Serialization in Unity
Unity Blog: Unity Serialization
Unity Tutorials: ScriptableObject

Unity Serialization Part 1: How it works and examples

This post is part of a series about Unity serialization.  On this series of articles we will discuss a topic that is extremely  important to Unity3D development: serialization. This subject may be a bit cloudy for beginners, but understanding it not only helps to figure out how the Unity engine works, but it can also become really handy during a game development process and assist you to build better solutions. We will concentrate our study on the following subjects:

  • What is it? (Part 1)
  • How Unity does (Part 1)
  • Examples (Part 1)
  • Defining a Serializable Type (Part 2)
  • Problems with Serialization (Part 2)
  • Scriptable Objects (Part 3)

Fell free to navigate through the sections if you are comfortable with the previous concepts.

What is it?

Among other definitions, serialization is the process of converting the state an object to a set of bytes in order to store (or transmit) the object into memory, a database or a file. In another words: it’s how you can save an object to restore its state for later use.

Let’s say you have a Vector3 and you need to store it for future use. Which fields would you save into a file to restore its state? X, Y and Z, that’s easy! Apply this rule for any object and if you serialize all the (important) data, you can reload the object exactly how it was before. We name the process of storing the state of the object as “serialization” and the reverse process of building an object out of a file “deserialization”.

As we already read, this process is really useful to store and transmit data, so think about this: you have an online store deployed on your server, probably running a database manager application aside. Eventually, we need to store the data from memory into the disk (primary storage is volatile) and we do it by serializing our objects into database tables (which basically are files). The same process happens with every application that needs to store data into a disk, and computer games (and engines) are not an exception.

How Unity Does

Unity, as a Game Engine, needs to load a lot of stuff (scripts, prefabs, scenes) from the disk into the memory within application data. Maybe more important than that, Unity needs to move data between the native C++ side of the engine and the managed C# side. Even though we may think this task is strict to loading and storing assets processes, the serialization is used in many more situations than we think (like inspector window, reloading of editor code and instantiation among other scenarios). You can learn a bit more about Unity Serialization on their own blog. I’d risk to say it’s a mandatory read for developers.

The UnityEngine.Object class (which is serializable) provides us with the serialization resource in Unity: any other class than inherits from it – that includes MonoBehaviour, ScriptableObject (more on this later on the series), Shader, Sprite and basically everything in Unity – can also be serialized. Most of its uses are invisible and don’t matter when developing a game, except for a major use: scripting. When you create scripts, you need to keep on mind which fields you want to serialize, and, to do so, your field must:

  • Be public, or have [SerializeField] attribute
  • Not be static
  • Not be const
  • Not be readonly
  • The fieldtype needs to be of a type that we can serialize.

Which fieldtypes can we serialize? According to Unity’s documentation:

  • Custom non abstract classes with [Serializable] attribute.
  • Custom structs with [Serializable] attribute. (New in Unity 4.5)
  • References to objects that derive from UntiyEngine.Object
  • Primitive data types (int,float,double,bool,string,etc)
  • Array of a fieldtype we can serialize
  • List of a fieldtype we can serialize

A really common data structure isn’t serializable: Dictionaries, even if you declare them as public, and [SerializeField] atribute. So keep that in mind when developing a game.

Ok, this is a lot of information, so let’s break it to a straightforward code example:

Examples

Let’s take the following code (MyBehaviour.cs) as an example:

using UnityEngine;

public class MyBehaviour : MonoBehaviour
{
  [SerializeFieldprivate int x = 3;
  [SerializeFieldprivate float y = 5.6f;
  public float pi = 3.1415f;
  private int mySecret = 42;
  public static int myStatic = 10;
  public const int myConst = 22;
  public readonly int myReadOnly = 99;
  public int MyProperty { get { return 100; } }
}

The only fields that are serialized are “x”, “y” and “pi” because they are not static, const, readonly, a property or private with no [SerializeField] attribute. One way to show this is by taking a look at the script’s inspector, which only shows us serialized fields (that can come handy):

Screen Shot 2015-04-08 at 10.48.08 PM

But there is a better way to show that the other fields were not serialized: by cloning the object. Remember I told you that the Instantiate method uses the Unity serialization process? So let’s test it by adding the following method to our script:

private void Start()
{
  Debug.Log("Pi:" + pi + ". MySecret:" + mySecret + ". MyStatic:" + myStatic);
}

private void Update()
{
  if (Input.GetMouseButtonDown(0))
  {
    pi = -4;
    mySecret = -11;
    myStatic = 13;
    GameObject.Instantiate(gameObject);
  }
}

This method should modify the current object and create another object in the scene when the mouse’s left button is pressed. A naive thought would be that since the second object is a clone of the first one, it should have the same value for “pi”, “mySecret” and any other field as the first object, right? Well, it does for “pi”, because it’s a public field (hence it’s serialized), but it doesn’t for “mySecret”: its value remains unchanged when the second Debug.Log() is executed:

screen-shot-2016-11-03-at-3-47-32-pm

The field “mySecret” can’t be serialized because it’s a private field with no [SerializeField] attribute (which is the only circumstance a private fields will be serialized*).

*: Private fields are serialized in some circumstances in the Unity Editor and that can lead us to some problems we will discuss later on the next article on the “Problems” session. (source)

Curiously, the value of “myStatic” changes in both objects, but does that mean static fields are serializable? The answer is no. Even though its behavior leads us to conclude that, remember that static fields belong to the class, and not to an instance of it. That said, if we, per example, create a new object and add a MyBehaviour script to it in play mode (Using “GameObject > Create Empty” in the menu), “myStatic” will have the same value as the other objects, although it isn’t a copy of any other object. However, note that the “pi” variable has its original value.

screen-shot-2016-11-03-at-3-51-03-pm

This proves what the Unity documentation tells us about how can we make a field of a serializable type be serialized. This works with most Unity objects, including MonoBehaviours, but what if I don’t want to define a MonoBehaviour and I still want to create a Serializable type? In other words, how can I define a Serializable type?

On the next article we will find out how to declare our own serializable types and how to treat problems that can come along with it.

Fell free to write me any suggestions, errors, complements or just to say hi on the comments section 🙂

Source:
Serialization in Unity by Lucas Meijer (mandatory read)
Unity Serialization Best Practices by Tim Cooper
ScriptableObject
Serialization (C# and Visual Basic)