Serial Filler. Copyright 2016 Christopher Stanley

Transcription

1 Serial Filler Copyright 2016 Christopher Stanley EasyNet is a serialization asset for Unity sequences of data a snap! It makes serializing and deserializing Examples In the Serial Filler\Examples folder you will find a progressive series of simple programs that demonstrate how to use Serial Filler. They put the content of this manual in a live setting. They work best if you look at them in order, from A to J. Thank you! These creations are a labor of love for me. It's very rewarding to know that what I make goes out into the world and helps people. Please feel free to contact me if you need any assistance or have any feedback. Thank you for your purchase, and I hope you enjoy using Serial Filler! Christopher If you like Serial Filler, please tell everyone! Leave a review on the Asset Store. If you don't like Serial Filler, please tell me! Let me know how I can help: support@christophercreates.com

2 Basic Usage Simple serialization and deserialization works like this. // Serialize byte[] bytes = SerialFiller.Break(Color.red); // Deserialize Color value = (Color)SerialFiller.Make(bytes); Data IDs When you break a value, you have the option of including an additional string to act as an identifier. This is purely for your reference, so you can put anything you want in it. // Break with ID byte[] bytes = SerialFiller.Break(Color.red, "Player Team"); // Make with ID string id = null; Color color = (Color)SerialFiller.Make(bytes, ref id); // id now contains "Player Team" Data Fills You can record everything you break into a data fill with IsFilling. // Start filling SerialFiller.IsFilling = true; // Serialize SerialFiller.Break(Color.red, "Player Team"); SerialFiller.Break("ABC", "Target Name"); SerialFiller.Break(Vector3.up, "Enemy Move"); // The serialized data is here var datafill = SerialFiller.DataFill; A data fill is a List<SerialFillerData>. Each element has a Value and an Id property. // Get the player team color Color color = (Color)SerialFiller.DataFill[0].Value; string id = SerialFiller.DataFill[0].Id;

3 Serializing Data Fills Once you have a data fill, you can store or transmit the whole thing and restore it later. // Save serialized data fill byte[] bytes = SerialFiller.BreakDataFill(); File.WriteAllBytes("DataFile", bytes); // Load deserialized data fill byte[] bytes = File.ReadAllBytes("DataFile"); SerialFiller.MakeDataFill(bytes); Searching Data Fills You can search data fills for particular types of data or IDs. The result is a custom data fill. // Search for Vector3 types var locations = SerialFiller.SearchDataFill(typeof(Vector3)); // Search for target IDs var targets = SerialFiller.SearchDataFill("Target"); // Search for both var targetlocations = SerialFiller.SearchDataFill(typeof(Vector3), "Target"); Multiple Data Fills The default data fill is kept in SerialFiller.DataFill. SearchDataFill can accept a custom data fill as a parameter. But BreakDataFill and // Get a custom data fill var customdatafill = SerialFiller.DataFill.GetRange(3, 7); // Break it byte[] custombytes = SerialFiller.BreakDataFill(customDataFill); // Search it var customtargets = SerialFiller.SearchDataFill("Target", customdatafill);

4 Serialization Types Serial Filler can serialize many types of data. C# Types All basic types (bool, float, int, string, etc). Unity Types Color, Color32, UNET GameObject*, Matrix4x4, NetworkHash128, NetworkIdentity, NetworkInstanceId, NetworkSceneId, Plane, Quaternion, Ray, Rect, UNET Transform*, Vector2, Vector3, and Vector4 *These are UNET references for Network Identity components, not the objects themselves. MessageBase Subclass Objects These are a great way to bundle groups of Unity type values into a single object. See below and the Serial Filler\Examples folder for examples. BinaryFormatter Serializable Objects Any object that has been properly formatted to be serializable by BinaryFormatter can be used. See below and the Serial Filler\Examples folder for examples. Arrays Serial Filler can also use arrays of any of the types above.

5 Using MessageBase Subclasses A MessageBase subclass object is very useful for bundling groups of related Unity type values. using UnityEngine; using UnityEngine.Networking; public class MyData : MessageBase { public Color PlayerTeam; public Vector3 TargetPosition; public string LevelName; } You can then break or make the whole object at once. // Create the custom object MyData mydata = new MyData(); mydata.playerteam = Color.yellow; mydata.targetposition = new Vector3(1, 2, 3); mydata.levelname = "Dungeon"; // Break it byte[] bytes = SerialFiller.Break(myData); // Make it MyData mydata = (MyData)SerialFiller.Make(bytes); See the Unity MessageBase documentation for more details. The advantage of MessageBase subclasses is that they can be serialized when containing Unity types, where BinaryFormatter-ready objects cannot. The disadvantage of MessageBase subclasses is that they cannot be as complex in structure as BinaryFormatter-ready objects.

6 Using BinaryFormatter-Ready Objects Objects formatted for use with BinaryFormatter are a useful way to bundle related data into a single object. using System; [Serializable] public class MyData { public int LevelNumber; public string PlayerName; public float TimeLeft; } You can then break or make the whole object at once. // Create the custom object MyData mydata = new MyData(); mydata.levelnumber = 4; mydata.playername = "Sue"; mydata.timeleft = 1.23f; // Break it byte[] bytes = SerialFiller.Break(myData); // Make it MyData mydata = (MyData)SerialFiller.Make(bytes); See the C# BinaryFormatter documentation for more details. The advantage of BinaryFormatter-ready objects is that they can be more complex in structure than MessageBase subclasses. The disadvantage of BinaryFormatter-ready objects is that they cannot be serialized when containing Unity types.

7 Advanced Breaking and Making With Break, you can use an override flag to do the opposite of IsFilling. // Start filling SerialFiller.IsFilling = true; // Not added to data fill byte[] bytes = SerialFiller.Break(Color.blue, null, true); // Stop filling SerialFiller.IsFilling = false; // Is added to data fill SerialFiller.Break(Matrix4x4.zero, null, true); With BreakDataFill, you can select a range of values to break with an index and/or count. // Start at value 5 byte[] thesebytes = SerialFiller.BreakDataFill(null, 5); // Start at value 3 and get 7 values byte[] thosebytes = SerialFiller.BreakDataFill(null, 3, 7); With MakeDataFill, you can choose how the new fill affects DataFill. // By default, DataFill is replaced with the new data SerialFiller.MakeDataFill(bytes); // Add the new data to the end of DataFill SerialFiller.MakeDataFill(bytes, SerialFiller.MakeType.Append); // Add the new data to the beginning DataFill SerialFiller.MakeDataFill(bytes, SerialFiller.MakeType.Prepend); // Leave DataFill unchanged and use the returned data fill var custom = SerialFiller.MakeDataFill(bytes, SerialFiller.MakeType.Ignore);

8 Inside SerialFillerData Data fills are a List<> of type SerialFillerData. This class is how Serial Filler marries the two different serialization systems that it uses behind the scenes. NetworkReader and NetworkWriter Unity 5.1+ provides these tools for serializing basic Unity types (Color, Vector3, etc). They aren't very sophisticated, but they're the only built-in tools available. BinaryFormatter This is the standard C# serialization tool. It's very sophisticated, but it can't serialize Unity types and is picky about how objects are formatted. Both of these tools produce a byte[] representing the data, but they use different formats. So Serial Filler wraps them in SerialFillerData, which is also where it stores additional data about the serialized object. This is why each individual object must be serialized, and then the whole data fill must also be serialized. Each SerialFillerData contains the serialized object, but is itself not yet serialized. When the data fill is broken, it is serialized with BinaryFormatter. The DataType and Value properties of SerialFillerData are filled in after serialization or deserialization for ease of reference. They are not serialized as they are already represented in DataTypeName and Data. See the end of the Scripting Reference below for details about the SerialFillerData properties.

9 Scripting Reference SerialFiller Properties SerialFiller.DataFill List<SerialFillerData> - The sequence of data that has been serialized with Break while IsFilling. SerialFiller.IsFilling bool - If true, each Break stores serialized data in DataFill. SerialFiller.MakeType enum - On MakeDataFill, specifies how the created data fill affects DataFill. MakeType.Replace - The new data replaces the previous contents of DataFill. (Default) MakeType.Append - The new data is added to the end of DataFill. MakeType.Prepend - The new data is added to the beginning of DataFill. MakeType.Ignore - The new data is only returned and does not change DataFill. Methods SerialFiller.Break(object subject, string id = null, bool overridefill = false) Serializes an object into a byte array. If IsFilling, the data is added to DataFill. subject: The object to be serialized. id: Optional string to identify the object. overridefill: If true, the opposite value of IsFilling will be used. Returns: byte[] - The serialized data.

10 SerialFiller.BreakDataFill(List<SerialFillerData> datafill = null, int index = 0, int count = -1) Serializes a data fill into a byte array. datafill: The data fill to serialize. Defaults to DataFill. index: The starting position in the fill. Defaults to the beginning. count: The number of values from the index to deserialize. Defaults to all. Returns: byte[] - The serialized data. SerialFiller.Make(byte[] bytes, ref string id) Deserializes an object from a byte array. bytes: The byte array to deserialize. id: A string to receive the object ID. Returns: object - The deserialized object. SerialFiller.Make(byte[] bytes) Deserializes an object from a byte array. bytes: The byte array to deserialize. Returns: object - The deserialized object. SerialFiller.MakeDataFill(byte[] bytes, MakeType maketype = MakeType.Replace) Deserializes a data fill from a byte array. bytes: The byte array to deserialize. maketype: Specifies how the created data fill affects DataFill. Defaults to Replace. Returns: List<SerialFillerData> - A List of SerialFillerData. SerialFiller.SearchDataFill(Type datatype, string id, List<SerialFillerData> datafill = null) Searches a data fill for matching types and/or IDs. datatype: The type to search for. Null matches any type. id: The ID to search for. Null matches any ID. datafill: The data fill to search. Defaults to DataFill. Returns: List<SerialFillerData> - A new data fill containing only the search results.

11 SerialFiller.SearchDataFill(Type datatype, List<SerialFillerData> datafill = null) Searches a data fill for matching types. datatype: The type to search for. Null matches any type. datafill: The data fill to search. Defaults to DataFill. Returns: List<SerialFillerData> - A new data fill containing only the search results. SerialFiller.SearchDataFill(string id, List<SerialFillerData> datafill = null) Searches a data fill for matching IDs. id: The ID to search for. Null matches any ID. datafill: The data fill to search. Defaults to DataFill. Returns: List<SerialFillerData> - A new data fill containing only the search results. SerialFillerData Properties SerialFillerData.Data byte[] - The serialized bytes of the object. SerialFillerData.DataType Type - The type of the object. (Field not serialized.) SerialFillerData.DataTypeName string - The AssemblyQualifiedName of the object type. SerialFillerData.Id string - An optional identifier to provide context for the object. SerialFillerData.Value object - The object which was serialized. (Field not serialized.)