Latest news

Flatbuffers for Unity + Sample Code

9 comments

Saving and loading a game is something that any game should have by default these days. But after all these years, we still don’t have a universal way of saving data and each game uses different methods for storing and loading their info. This is pretty much normal, since the way we store the data depends on the type of game you’re making and how you’re making it.

For us, Afterloop is all about zero loading times, and choosing a format like XML and JSON for saving was out of question due to their slow parsing speeds.

We started with binary serialization, but soon enough we had problems making saves backwards compatible, we needed SPEED and FLEXIBILITY.
Flatbuffers had everything we needed.

In this post, I’ll explain how we used flatbuffers for saving and loading data in Unity.
Flatbuffers might seem scary and mysterious at first, but in reality it’s not that hard to use !

Obviously, this is not something that beginners should use but since I couldn’t find any examples of flatbuffers with Unity3D on the web, I had to make this post.

For more info about flatbuffers, check this video:

1- First step is to get the “flatc” compiler and “FlatBuffers.dll”

Flatc is used to convert schemas into c# code which I’ll explain later, and the dll is the main library.

You can download the latest release at :
https://github.com/google/flatbuffers/releases

or you can simply compile the bleeding edge version yourself like a pro ( not recommended ) :
https://github.com/google/flatbuffers

You first either compile or simply download the latest flatc.exe file,
then you go to “\net\FlatBuffers” folder inside the source and open up “FlatBuffers.csproj”
and compile it to get the “FlatBuffers.dll” which you’ll need to put inside your unity project ( I put it inside assets/plugins folder ).

What I did next was create a separate folder for my compiler and schema like this :

Captur52423e

And instead of hurting my fingers by writing same command to compile over and over again, I simply made this dumb batch script ( compile.bat ) which contains these lines :

This executes flatc with parameters such as “-n” for c# code generation, “–gen-onefile” for generating all classes inside one .cs file which is optional, and finally “@pause” which is also completely optional but it prevents from the console window from closing automatically ( useful when you have compile errors ).

And for demonstration purposes, I’ll use a demo SaveSchema.txt file :

The schema file is what defines the structure of the save, and what values are gonna be saved.
For more info on the schema syntax please read this official doc page.

Once you execute compile.bat it’ll create a new file named “SavedSchema.cs”

Captu4545re

Flatc now generated several classes with names such as “WeaponClassesOrWhatever”

This file is your whole loading and saving system for that schema, this file is now your ultimate file.

2- Next step, how do we save our data?

The generated .cs file contains all classes and functions required to save and load data from and to flatbuffers. But in order to load, we’ll need to save something first.

Place that generated file into your project
( Also don’t forget to place “FlatBuffers.dll” in your project or else you’re gonna see some errors )

Then place this code :

The way you write your data is ORDER DEPENDENT.
You always have to create items from inside out.
Starting from everything that object contains ( such as strings, arrays, other objects ) to the object itself.
Basically, you have to create objects upfront before setting them inside another object.

So what happens here is :
We create the weapon and string first because it’s gonna be inside the GameDataWhatever.
Everything that can have a variable length needs to be setup first before it is inserted in the buffer.
And only then once we have them setup, we create GameDataWhatever in which we’re gonna set those values.

The saving part can be really tricky, I advise you to read this page to have a better understanding on how to store data.

3- Finally, reading the file is a piece of cake.

Reading can be done in any order you want, if you want you don’t even need to go through all values because flatbuffers work like magic !

There you go !

We tested flatbuffers on all major mobile platforms ( iOS, Android, Amazon Os, Windows Phone ) we’re building on and it works pretty well.

4- Source Code for Unity

If you want the full working sample code along with compiled flatbuffer files flatc.exe and flatbuffers.dll, then download this file :

FlatBuffersTest.zip

 

   This article has been written for Unity 5.1.3, newest version of Unity3d might not be compatible.

exiinFlatbuffers for Unity + Sample Code

9 comments

Join the conversation
  • Jérémie - 3 December 2015 reply

    Great article! How would I save the position of multiple game objects? Do I need to create a table with a vector of positions or is there a way to append the byte buffers in the C# code?

    Sam - 4 December 2015 reply

    Unfortunately, I haven’t had the chance to append buffers since most of my data needs to be updated. But for the multiple objects, all you have to do is create an array of tables ( if content is flexible, like for instance it uses strings,arrays or tables ) or simply create a struct for fixed ones. For dictionaries I just use two arrays, one for string and the other for tables.

    Hope this helps 🙂

  • Oliver - 14 March 2016 reply

    This page is really the missing link between their repo / docs and actually getting FlatBuffers up and running in a project. It was obvious from the start this was the serialization solution we wanted to use, we’re just pretty green, so this guide proved indispensable. Hopefully it’s smooth sailing from here, but we might be back with a question or two. Thanks a bunch!

  • Rich - 15 September 2016 reply

    How do we use bools? Do we instead use int 0 or 1?

    exiin - 24 September 2016 reply

    yes

  • Mashox - 14 October 2016 reply

    Flatbuffer work on Unity well. But When I build apk and install on my android phone flatbuffer not work I research it for the reason of .dll file anroid can not work .dll file because linux based work with .os files. Any Help?

    Antoine AGTHE - 13 January 2017 reply

    I didn’t use FlatBuffers yet.
    But FlatBuffers.dll is a pure .NET assembly.
    While adding it to your Unity project, it should be compiled as well as your project code, which is also compiled in a DLL assembly by the way.
    Can you share more info ?

  • gabokun - 9 February 2017 reply

    how we using array when making schema?

  • Maximilien - 20 July 2017 reply

    On FlatBuffers 1.7.0, the txt extension doesn’t work for creating a schema. flatc will run but not create the C# file. The SaveSchema needs to end in .fbs

Leave a Reply

Your email address will not be published. Required fields are marked *