If you are not familiar of JSON format itself, check out https://json.org/
Shortly, JSON is safe format to store and transmit data. JSON objects, when turned to string, contains only ASCII character 32 to 126. No worry of different systems using different localizations. JSON is simpler and more compact than XML, but is still human readable.
This package is nothing but C# code (excluding one example scene). All the public scripts are in folder TotalJSON/Scripts/
Take these in use in your own code:
using Leguar.TotalJSON;
Classes representing JSON objects and values are:
Scripts folder also contains JValue, which is just abstract base class for all above classes and is usually not used directly.
JSON and JArray are different from others in sense that they can be modified after instance is created. You can use provided methods to add, remove and replace values in them.
You can create new JSON object
JSON json = new JSON();
and use provided method to add/modify/remove data.
Arrays can be created similarly
JArray jArray = new JArray();
Typically values are added to JSON or JArray objects directly like
json.Add("answer", 42);
or
jArray.Add(true);
All the Add(), Replace(), Insert() etc methods accepts 'object' as input parameter. This object can be anything that can be converted to some JValue object without any ambiguity. For example strings, any C# number types, booleans and null. Obviously other JSON objects or JArray arrays are fine too.
JSON-number, -string, -boolean and -null values can be created separately
JNumber jsonNumber = new JNumber(42);
and then be added to JSON or JArray objects.
This is useful especially with numbers that would go outside normal C# number range:
json.Add("huge_integer", new JNumber("123456789012345678901234567890"));
or
jArray.InsertAt(0, new JNumber("3.1415E+42000"));
Strings that are in JSON format like {"name":"Pingu","active":true,"items":[1,2,4]}
can be turned to JSON object using static method
JSON json = JSON.ParseString(inputString);
Likewise, JSON object can be turned to JSON-formatted string using
string outputString = json.CreateString();
usually for storing or sending to another system.
There's also method to get JSON out in more human friendly format using
Debug.Log(json.CreatePrettyString());
typically for debug purposes.
All the same can be done to JArrays.
All the classes (JSON, JArray, JString, JNumber, JBoolean and JNull) have ToString() method overridden to print out information of the object. This meant to be just debug information about the object. In case of JSON, amount or key/value pairs in object. In case of JArray, count of objects and their types, or just the value stored in object. Generally, good for console output since length of the output is always relatively short.
All the classes also have CreateString() method that will print out all the content of object, in JSON format. (See "Parsing and creating JSON formatted strings" above.)
For example, if you have class like
class ExamplePlayer {
public string name;
public bool active;
public List<int> items;
public int? skill;
}
and instance 'examplePlayer' of that class where fields "name", "active" and "items" have
some values set.
You can turn class content to JSON
JSON json = JSON.Serialize(examplePlayer);
And this can be turned to string using CreateString() method like in example above.
Only public fields and fields marked with attribute [UnityEngine.SerializeField] or [IncludeToJSONSerialize] are serialized. Constant, static and readonly fields are not serialized. Additionally, you can exclude public fields from serialization by adding [System.NonSerialized] or [ExcludeFromJSONSerialize] attribute to it.
To other direction, if you have input string like {"name":"Pingu","active":true,"items":[1,2,4],"skill":null}
Then string values can be copied to class fields by first turning string in to JSON
JSON json = JSON.ParseString(inputString);
and deserialize JSON to class instance
ExamplePlayer examplePlayer = json.Deserialize<ExamplePlayer>();
You now have instance of class ExamplePlayer where field 'name' is "Pingu" etc.
For easy debugging, you can follow content of JSON objects in Unity Editor when application is running.
In your code, you can add any JSON or JArray object to debug by saying
myJsonObject.DebugInEditor("My JSON Object");
where parameter string is name that will appear in debug window.
In Unity Editor, open debug window from menu: Window -> Total JSON -> JSON Runtime Debug
Your objects and their content will appear there.
There is no harm leaving these "DebugInEditor(...)" lines in your code when making build. They do not have any effect outside Unity Editor.
Nothing is perfect and it may happen that JSON data you are trying to parse or handle is invalid. In editor this isn't so much problem but in production builds all you may get is exception like for example
> JSONKeyNotFoundException: Value for key "id" does not exist in this JSON
Depending on build, it might be that there isn't any stack trace available. If your project does handle lots of JSON objects, above error message may not tell you at all where the problem occurred.
This is why TotalJSON allows you to add Debug ID to JSON objects. For example:
JSON playerJSON = getPlayerJSONFromServerData();
playerJSON.SetDebugIDForExceptions("Player data from server");
If now any exceptions happens when handling 'playerJSON', they'll look like this:
> JSONKeyNotFoundException: Value for key "id" does not exist in this JSON - JSON Debug ID: "Player data from server"
So you'll immediately know which JSON caused the exception even if stacktrace is not available.
This Debug ID string can be added already when parsing JSON:
string playerDataString = <json formatted data here>
JSON playerJSON = JSON.ParseString(playerDataString, "Player data from server");
In this case, Debug ID is added to exceptions already if they happen when parsing JSON data. If parsing goes fine, that same Debug ID (in this case "Player data from server") is added to resulting JSON object, so there's no need to use SetDebugIDForExceptions(string) separately.
Open JSON validator from Unity Editor menu: Window -> Total JSON -> JSON Validator
To this window you can copy&paste JSON objects or arrays and click Validate button below. Not only this will check that JSON is in valid format, but it will also make it much more readable by adding indents and line feeds.
Validator will also make extra effort trying to remove leading or trailing texts that are not part of JSON object. So you can for example copy text directly from Unity Console with stack traces. As long as there is some JSON object in the text.
When turning JSON object to string using CreateString() method, it is possible to customize output string using CreateStringSettings.
string customOutput = json.CreateString( new CreateStringSettings() {
HumanReadable = true,
NewLine = CreateStringSettings.NewLineTypes.LF
});
Mostly this is needed when outputting human readable JSON. CreateStringSettings allows for example changing type and size of indentation, character that is used for line feed etc.
You can set JSON or JArray objects protected using
json.SetProtected();
This will set this JSON object and all other objects it contains to write protected. Nothing can be added, moved or changed. This is useful to make sure no accidental changes are made to objects that should be only for reading.
Once this is set, protection can't be removed.
TotalJSON package have directory TotalJSON/Examples/ that contains example scene and multiple example scripts.
All the classes have full inline C# documentation that is also available online in HTML format:
https://www.leguar.com/unity/totaljson/apidoc/2.1/
If you are happy with this asset, please rate us or leave feedback in Unity Asset Store:
https://assetstore.unity.com/packages/slug/130344
If you have any problems, or maybe suggestions for future versions, feel free to contact: