A* Pathfinding Project  3.8.2
The A* Pathfinding Project for Unity 3D
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Properties Events Macros Groups Pages
Saving and Loading Graphs

Saving and Loading Graphs.

All graphs can be saved and loaded from files. The is actually what the editor does all the time, barely any Unity serialization is used, instead all graph settings are serialized and stored in a byte array. However, not only settings can be saved, once calculated, a graph can save all nodes to a compact byte array representation, which can then be saved to a file and loaded somewhere else.
In the A* inspector, under the Save & Load tab, there are two buttons named "Save to file" and "Load from file", these can be used to save and load graph files.

Caching Graph Calculation

Recalculating the graphs at startup is usually what you want, but sometimes especially if you are using the RecastGraph or developing for the iPhone or Android the lag at the start can get very annoying. It might also be the case that you cannot calculate the graph at startup for some reason.
Then graph caching is great. It enables you to scan the graph in the editor, save it to an internal byte array which will be loaded at startup. It is a lot faster than scanning the graphs in most cases and you know exactly how the graph will look.

To create a cache, open the Save & Load tab in the A* inspector and check the Cache Startup toggle. Also make sure "Save Node Data" is toggled. Then simply click Generate Cache. It might also ask you if you want to rescan the graph before saving. Now the graph you saved will be loaded with all node info intact at startup, no calculation time necessary.

Saving Graphs to File and Loading them

You might also want to save the graphs to a file which you can load later. You can even load it during runtime from a server for example.

If you want to save your graphs, open the Save & Load tab, and click the Save to file button. If you want to include node data in the graph, make sure Save Node Data is toggled.

When you want to load the graphs again, simply press the Load from file button and locate the file. Note that this will replace your current graphs.

Loading and Saving using Scripting

If you want to load or save graphs during runtime, you cannot use the editor interface for obvious reasons. So how do you do it then?

There is an easy API for saving and loading files.
This will serialize graph settings to a file

byte[] bytes = AstarPath.active.astarData.SerializeGraphs ();

If you want more control, you can add some settings

Pathfinding.Serialize.SerializeSettings settings = new Pathfinding.Serialize.SerializeSettings();
//Save node info, and output nice JSON
settings.nodes = true;
settings.prettyPrint = true;
byte[] bytes = AstarPath.active.astarData.SerializeGraphs (settings);

To load saved data there is an as simple call for that:

AstarPath.active.astarData.DeserializeGraphs (bytes);

If you only load settings, you might want to call Scan after you have loaded the settings:

AstarPath.active.astarData.DeserializeGraphs (bytes);

Including Data In A TextAsset

Graph data can be included in textassets for easier inclusion in the build. When you have saved the data to a file, rename that file to something like "myGraph.bytes" and place it in your Unity Project. This will tell Unity to handle it as binary information. With an extension like .txt the data would get corrupted because Unity would try to read it as text. Some operating systems like to hide the extension, so if Unity doesn't seem to recognize the file with the .bytes extension make sure it really has a .bytes extension, the .zip (or other) extension might just be hidden. Then you can load the graph from a text asset by referencing it in a variable, and the accessing the .bytes field.

using UnityEngine;
using System.Collections;
public class TestLoader : MonoBehaviour {
public TextAsset graphData;
// Use this for initialization
void Start () {
AstarPath.active.astarData.DeserializeGraphs (graphData.bytes);
}
}

Internal Data Structure

All settings are serialized to JSON. This is a good way to keep it forwards and backwards compatible. All files referred to below are compressed into a single zip file to make the size smaller and make it easier to handle the data. This means you can actually open the zip file up and edit the settings manually.

Note
Many of the files mentioned below are not always included in the zip. If it is determined that a file would not contain any relevant information (such as saving user created connections, but no connections have been created), it is left out.

Meta

A meta.json file is present in all serializations. This file contains information which is not connected to a specific graph, or is needed to load the other graphs.

The meta file contains

  • Version number for the system
  • Number of graphs which are saved
  • GUID values for each graph, to identify them
  • Type of each graph
  • Number of nodes in each graph

Below is an example of a meta.json file:

{
"version": "3.0.9.5",
"graphs": 1,
"guids":
[
"0d83c93fc4928934-8362a8662ec4fb9d"
],
"typeNames":
[
"Pathfinding.GridGraph"
],
"nodeCounts":
[
10000
]
}

Graph Settings

Settings for each graph is stored as "graph#.json" where # is the graph number. Here is an example of serialized settings for a grid graph (with some settings removed to keep the length down):

{
"aspectRatio":1,
"rotation":{
"x":0,
"y":0,
"z":0
},
"center":{
"x":0,
"y":-0.1,
"z":0
},
"unclampedSize":{
"x":100,
"y":100
},
"nodeSize":1,
"maxClimb":0.4,
"maxClimbAxis":1,
"maxSlope":90,
"erodeIterations":0,
"autoLinkGrids":false,
"autoLinkDistLimit":10,
"neighbours":"Eight",
"cutCorners":true,
"penaltyPositionOffset":0,
"penaltyPosition":false,
"penaltyPositionFactor":1,
"penaltyAngle":false,
"penaltyAngleFactor":100,
"open":true,
"infoScreenOpen":false
}

Node information (if included in the serialized data) would take too much space to be included as JSON, instead it is written to binary data.

Node Data

Node information is stored as "graph#_nodes.binary" where # is the graph number.

an Int32 with the value 1 to identify the first section
for each node in the graph:
x y z coordinates (type Int32, read as Int3, node.position)
an Int32 with the value 2 to identify the second section
for each node in the graph:
penalty (UInt32 Node.penalty)
an Int32 with the value 3 to identify the third section
for each node in the graph:
flags (Int32 Node.flags)

Node Connections

In addition to node specific information, node connections are stored in the file "graph#_conns.binary".

for each node in the graph:
number of connections (UInt16)
for each connection:
other node index (Int32)
connection cost (Int32)
See Also
Pathfinding.Serialize.AstarSerializer.GetNodeWithIndex

Extra Node Data

Every graph type has also the ability to save additional binary data for the nodes if necessary. If the graph overrides the SerializeExtraInfo and DeserializeExtraInfo functions extra binary data can be saved to the file "graph#_extra.binary".

User Created Connections

User created connections, or "links" are stored in the file "connections.json".