440 lines
10 KiB
HTML
440 lines
10 KiB
HTML
|
<html lang="en">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<head>
|
|||
|
|
|
|||
|
|
<title>TotalJSON - ReadMe</title>
|
|||
|
|
|
|||
|
|
<style>
|
|||
|
|
body {
|
|||
|
|
background-color: linen;
|
|||
|
|
margin: 60px;
|
|||
|
|
}
|
|||
|
|
h1,h2,h3 {
|
|||
|
|
color: maroon;
|
|||
|
|
}
|
|||
|
|
h1 {
|
|||
|
|
font-size: 30px;
|
|||
|
|
}
|
|||
|
|
h2 {
|
|||
|
|
margin-top: 50px;
|
|||
|
|
font-size: 25px;
|
|||
|
|
}
|
|||
|
|
h3 {
|
|||
|
|
margin-top: 40px;
|
|||
|
|
font-size: 22px;
|
|||
|
|
}
|
|||
|
|
p, li {
|
|||
|
|
font-family: verdana, sans-serif;
|
|||
|
|
font-size: 17px;
|
|||
|
|
}
|
|||
|
|
code {
|
|||
|
|
font-family: monospace;
|
|||
|
|
font-size: 18px;
|
|||
|
|
white-space: pre-wrap;
|
|||
|
|
display: block;
|
|||
|
|
width: 900px;
|
|||
|
|
border: 1px solid maroon;
|
|||
|
|
padding: 5px;
|
|||
|
|
margin-top: 5px;
|
|||
|
|
margin-bottom: 5px;
|
|||
|
|
}
|
|||
|
|
</style>
|
|||
|
|
|
|||
|
|
</head>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<body>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<h1>TotalJSON - ReadMe</h1>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<h2>JSON</h2>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
If you are not familiar of JSON format itself, check out <a href="https://json.org/">https://json.org/</a>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<h2>Basic usage</h2>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
This package is nothing but C# code (excluding one example scene). All the public scripts
|
|||
|
|
are in folder <b>TotalJSON/Scripts/</b>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
Take these in use in your own code:
|
|||
|
|
<code>using Leguar.TotalJSON;</code>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<br/>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
Classes representing JSON objects and values are:
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li> JSON - Main JSON object class where data is saved as key/value pairs</li>
|
|||
|
|
<li> JArray - JSON array where data is accessed by index</li>
|
|||
|
|
<li> JString - String value</li>
|
|||
|
|
<li> JNumber - Number value (integer or floating point number)</li>
|
|||
|
|
<li> JBoolean - Boolean (bool) value</li>
|
|||
|
|
<li> JNull - JSON null value</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
Scripts folder also contains JValue, which is just abstract base class for all above classes
|
|||
|
|
and is usually not used directly.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<h3>Creating and modifying</h3>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
You can create new JSON object
|
|||
|
|
<code>JSON json = new JSON();</code>
|
|||
|
|
and use provided method to add/modify/remove data.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<br/>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
Arrays can be created similarly
|
|||
|
|
<code>JArray jArray = new JArray();</code>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<br/>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
Typically values are added to JSON or JArray objects directly like
|
|||
|
|
<code>json.Add("answer", 42);</code>
|
|||
|
|
or
|
|||
|
|
<code>jArray.Add(true);</code>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<br/>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<br/>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
JSON-number, -string, -boolean and -null values can be created separately
|
|||
|
|
<code>JNumber jsonNumber = new JNumber(42);</code>
|
|||
|
|
and then be added to JSON or JArray objects.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
This is useful especially with numbers that would go outside normal C# number range:
|
|||
|
|
<code>json.Add("huge_integer", new JNumber("123456789012345678901234567890"));</code>
|
|||
|
|
or
|
|||
|
|
<code>jArray.InsertAt(0, new JNumber("3.1415E+42000"));</code>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<h3>Parsing and creating JSON formatted strings</h3>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
Strings that are in JSON format like <b>{"name":"Pingu","active":true,"items":[1,2,4]}</b>
|
|||
|
|
can be turned to JSON object using static method
|
|||
|
|
<code>JSON json = JSON.ParseString(inputString);</code>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<br/>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
Likewise, JSON object can be turned to JSON-formatted string using
|
|||
|
|
<code>string outputString = json.CreateString();</code>
|
|||
|
|
usually for storing or sending to another system.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<br/>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
There's also method to get JSON out in more human friendly format using
|
|||
|
|
<code>Debug.Log(json.CreatePrettyString());</code>
|
|||
|
|
typically for debug purposes.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<br/>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
All the same can be done to JArrays.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<h3>Printing out values</h3>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
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.)
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<h3>Serializing and deserializing objects</h3>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
For example, if you have class like
|
|||
|
|
<code>class ExamplePlayer {
|
|||
|
|
public string name;
|
|||
|
|
public bool active;
|
|||
|
|
public List<int> items;
|
|||
|
|
public int? skill;
|
|||
|
|
}</code>
|
|||
|
|
and instance 'examplePlayer' of that class where fields "name", "active" and "items" have
|
|||
|
|
some values set.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
You can turn class content to JSON
|
|||
|
|
<code>JSON json = JSON.Serialize(examplePlayer);</code>
|
|||
|
|
And this can be turned to string using CreateString() method like in example above.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<br/>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
To other direction, if you have input string like <b>{"name":"Pingu","active":true,"items":[1,2,4],"skill":null}</b>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
Then string values can be copied to class fields by first turning string in to JSON
|
|||
|
|
<code>JSON json = JSON.ParseString(inputString);</code>
|
|||
|
|
and deserialize JSON to class instance
|
|||
|
|
<code>ExamplePlayer examplePlayer = json.Deserialize<ExamplePlayer>();</code>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
You now have instance of class ExamplePlayer where field 'name' is "Pingu" etc.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<h2>Additional features</h2>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<h3>Debugging in Unity Editor</h3>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
For easy debugging, you can follow content of JSON objects in Unity Editor when application
|
|||
|
|
is running.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
In your code, you can add any JSON or JArray object to debug by saying
|
|||
|
|
<code>myJsonObject.DebugInEditor("My JSON Object");</code>
|
|||
|
|
where parameter string is name that will appear in debug window.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
In Unity Editor, open debug window from menu: <b>Window -> Total JSON -> JSON Runtime Debug</b>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
Your objects and their content will appear there.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
There is no harm leaving these "DebugInEditor(...)" lines in your code when making build.
|
|||
|
|
They do not have any effect outside Unity Editor.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<h3>Debugging in production</h3>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
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
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
> <i>JSONKeyNotFoundException: Value for key "id" does not exist in this JSON</i>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<br/>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
This is why TotalJSON allows you to add Debug ID to JSON objects. For example:
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
<code>JSON playerJSON = getPlayerJSONFromServerData();
|
|||
|
|
playerJSON.SetDebugIDForExceptions("Player data from server");</code>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
If now any exceptions happens when handling 'playerJSON', they'll look like this:
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
> <i>JSONKeyNotFoundException: Value for key "id" does not exist in this JSON - JSON Debug ID: "Player data from server"</i>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
So you'll immediately know which JSON caused the exception even if stacktrace is not
|
|||
|
|
available.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<br/>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
This Debug ID string can be added already when parsing JSON:
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
<code>string playerDataString = <json formatted data here>
|
|||
|
|
JSON playerJSON = JSON.ParseString(playerDataString, "Player data from server");</code>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<h3>JSON validator</h3>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
Open JSON validator from Unity Editor menu: <b>Window -> Total JSON -> JSON Validator</b>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<h3>Customized string output</h3>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
When turning JSON object to string using CreateString() method, it is possible to customize
|
|||
|
|
output string using CreateStringSettings.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
<code>string customOutput = json.CreateString( new CreateStringSettings() {
|
|||
|
|
HumanReadable = true,
|
|||
|
|
NewLine = CreateStringSettings.NewLineTypes.LF
|
|||
|
|
});</code>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<h3>Protecting JSON objects</h3>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
You can set JSON or JArray objects protected using
|
|||
|
|
<code>json.SetProtected();</code>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
Once this is set, protection can't be removed.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<h2>Examples</h2>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
TotalJSON package have directory <b>TotalJSON/Examples/</b> that contains example scene and multiple example
|
|||
|
|
scripts.
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<h2>Full API docs</h2>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
All the classes have full inline C# documentation that is also available online in HTML format:
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
<a href="https://www.leguar.com/unity/totaljson/apidoc/2.1/">https://www.leguar.com/unity/totaljson/apidoc/2.1/</a>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<h2>Feedback</h2>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
If you are happy with this asset, please rate us or leave feedback in Unity Asset Store:
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
<a href="https://assetstore.unity.com/packages/slug/130344">https://assetstore.unity.com/packages/slug/130344</a>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<br/>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
If you have any problems, or maybe suggestions for future versions, feel free to contact:
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<p>
|
|||
|
|
<a href="https://www.leguar.com/contact/?about=totaljson">https://www.leguar.com/contact/?about=totaljson</a>
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</body>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</html>
|