Quick Start Guide


Follow these instructions to get up and running quickly with SwiftTree.


Summary for creating a SwiftTree Data Structure

Summary for using your new SwiftTree Data Structure


Details for creating a SwiftTree Data Structure

Create one or more empty classes that will be used to hold your data.

Create some classes that will hold your data. When all is finished these classes will be constructed by the SwiftTree tool and filled with your data. In this example we will make a Vehicle data set to describe some Vehicles with turrets, wheels, tracks and ammunition. First create the classes, you can skip this step if your classes already exist.

class Vehicle
{
}
class Turret
{
}
class Wheel
{
}
class Track
{
}
class Ammo
{
}

Think of a name for the type of data you are creating so you can mark up your classes.

This name is what you'll be marking up your classes with later on and is the name that will appear in the Select Tree Type drop down box when you choose to make a SwiftTree. For this demo we will choose "vehicleTree" as our tree type as it's a tree that describes vehicles. Later on you will see "vehicleTree" or whatever name you have chosen appear in a drop down menu...

Select Tree Type

Mark up the above classes with STClass, STChild and STLink as appropriate

Now that we have our classes we can mark them up with SwiftTree attributes so the SwiftTree tool knows how to manage them. Every class will need a SwiftTree.STClass entry. The parameters for the SwiftTree.STClass attribute are detailed in the Attributes page. If a class has any children then it will need a SwiftTree.STChild entry for each child. Below you can see that a Vehicle can have a Turret, Wheel or Track as children. Finally, If a class can link to any other classes they will need the SwiftTree.STLink attribute. A Turret will link to the Ammo it uses.

[SwiftTree.STClass("Vehicle({VarValues})", "vehicleTree", 1, true, SwiftTree.ClassColour.Hue040_Orange )]
[SwiftTree.STChild(typeof(Turret), "vehicleTree")]
[SwiftTree.STChild(typeof(Wheel), "vehicleTree")]
[SwiftTree.STChild(typeof(Track), "vehicleTree")]
class Vehicle
{
}

[SwiftTree.STClass("Turret({VarValues})", "vehicleTree", 1, false )] [SwiftTree.STLink(typeof(Ammo), "vehicleTree")] class Turret { }

[SwiftTree.STClass("Wheel", "vehicleTree", 1, false )] class Wheel { }

[SwiftTree.STClass("Track", "vehicleTree", 1, false )] class Track { }

[SwiftTree.STClass("Ammo({VarValues})", "vehicleTree", 1, true, SwiftTree.ClassColour.Hue140_SpringGreen )] class Ammo { }

Create a new SwiftTree and add some data

Now that your classes are marked up with the right SwiftTree attributes you can already create a "vehicleTree" SwiftTree and add some classes. In the Assets->Create menu, select SwiftTree to create a SwiftTree in the project window. You can also right click in the project window to get to Create->SwiftTree.

Create SwiftTree

In the SwiftTree inspector press the Select Tree Type button and select vehicleTree...

Select Tree Type

You can now right click anywhere in the SwiftTree inspector window to bring up the classes you are allowed to add to the root of your SwiftTree. Notice you can only create two types of classes in the root, that's because only the Vehicle and Ammo classes have their canBePlacedInTheRoot set to true, the fourth parameter in the STClass attribute.

Create Class

After creating a few root classes, you can right click on a class to add any of it's children. Right clicking on Vehicle will show it's child classes in a menu. The Wheel, Track and Turret classes are all children of the Vehicle class because an STChild attribute was added to the Vehicle class for each child class.

Create Child Class

Here is the tree after creating some more classes...

First version of tree

Add some members and mark them up with STVar

Now that the structure of the tree is finished it is time to add some data to the classes. Below you can see how to add member variables and mark them up with the STVar attribute.

[SwiftTree.STClass("Vehicle({VarValues})", "vehicleTree", 1, true, SwiftTree.ClassColour.Hue040_Orange )]
[SwiftTree.STChild(typeof(Turret), "vehicleTree")]
[SwiftTree.STChild(typeof(Wheel), "vehicleTree")]
[SwiftTree.STChild(typeof(Track), "vehicleTree")]
class Vehicle
{
    [SwiftTree.STVar]
    int speed;

[SwiftTree.STVar] public string name = ""; }

[SwiftTree.STClass("Turret({VarValues})", "vehicleTree", 1, false )] [SwiftTree.STLink(typeof(Ammo), "vehicleTree")] class Turret { [SwiftTree.STVar] public float ammoPerSecond = 1.0f; }

[SwiftTree.STClass("Wheel", "vehicleTree", 1, false )] class Wheel { }

[SwiftTree.STClass("Track", "vehicleTree", 1, false )] class Track { }

[SwiftTree.STClass("Ammo ({VarValues})", "vehicleTree", 1, true, SwiftTree.ClassColour.Hue140_SpringGreen )] class Ammo { [SwiftTree.STVar] public string UniqueName = "ammo";

[SwiftTree.STVar] public int damage = 0; }

Once the above is compiled you can see that the tree has errors...

UniqueName is not set

Arrow buttons have appeared on the right side of each box indicating that this class has paramaters that can be set. Clicking on the arrow will expand the parameters. Go ahead and expand all of the red classes that have errors. Enter a UniqueName for each of the Ammo classes will fix the errors like so...

UniqueName is now set

That's it for the data structure, the designers can now start creating data!

The above is enough to get the designers creating a data hierarchy. In order to get at the data you will need to continue to the next section. One more thing, now that we have a UniqueName for each of our Ammo classes, we can create Turrets that link to those classes. Right click on Vehicle and add a Turret. Then right click on the Turret and link to the Rock Ammo class. You should see an entry for every Ammo class in the tree. Keep on adding/setting data until your tree looks like this...

Example Tree

Details for using your new SwiftTree Data Structure

Create a behaviour that has a public SwiftTree.SwiftTreeScript member in it.

public class VehicleBehaviour : MonoBehaviour 
{
    public SwiftTree.SwiftTreeScript swiftTree;
}

The SwiftTree.SwiftTreeScript member is a reference to a SwiftTree asset. Once you've made the above script and attached it to a GameObject then you can drag the "vehicleTree" SwiftTree asset that you have already made above from the project window to the SwiftTree.SwiftTreeScript member in the inspector.

In the Start method of your behaviour call SwiftTree.Build.FromString(...)

Add a Start method to your new behaviour and call SwiftTree.Build.FromStrings( swiftTree.swiftTreeText.lines ) The Build.FromStrings function will construct instances of you classes. It will return a list of objects that are the instances of your classes that you have placed in the root of the tree. Add the following code shown below to iterate through your new classes.

public class VehicleBehaviour : MonoBehaviour 
{
    public SwiftTree.SwiftTreeScript swiftTree;
    List<object> vehicles;
    void Start () 
    {
        vehicles = SwiftTree.Build.FromStrings( swiftTree.swiftTreeText.lines );
        foreach( object obj in vehicles )
        {
            if( obj is Vehicle )
            {
                Vehicle vehicle = (Vehicle)obj;
            }
            else if (obj is Ammo)
            {
                Ammo ammo = (Ammo)obj;
            }
        }
    }
}

Implement the STAddChild, STAddLink and STCommit methods on any of your classes that need them

So far the above code would have created instances of all of your classes that you have specified in your tree, but now you need to implement the STAddChild, STAddLink and STCommit methods. These methods will allow you to connect your classes together in the manner you desire. You will likely need to implement STAddChild, but STAddLink and STCommit will only need to be implemented in certain cases.

STAddChild - Will be called on this object for each child that it has, useful for keeping a list of children.

STAddLink - Will be called on this object for each link that it has, useful for keeping a list of links.

STCommit - Will be called on this object after all of the children and links have been added. Also after every class in the tree has been instantiated. Useful for performing any final processing that needs all of the data present.

Below is a full listing of the data classes that includes usages of the STAddChild, STAddLink and STCommit methods. Notice that UnityEngine is not needed, so your data can be used outside of Unity e.g. on a server.

using System.Collections.Generic;

[SwiftTree.STClass("Vehicle({VarValues})", "vehicleTree", 1, true, SwiftTree.ClassColour.Hue040_Orange )] [SwiftTree.STChild(typeof(Turret), "vehicleTree")] [SwiftTree.STChild(typeof(Wheel), "vehicleTree")] [SwiftTree.STChild(typeof(Track), "vehicleTree")] class Vehicle { [SwiftTree.STVar] int speed; [SwiftTree.STVar] public string name = ""; public int wheelCount = 0; public int trackCount = 0; public int combinedCount = 0; List<Turret> turrets = new List<Turret>(); bool STAddChild( object child ) { if( child is Turret ) { turrets.Add((Turret)child); } else if ( child is Wheel ) { wheelCount++; } else if ( child is Track ) { trackCount++; } return true; } public List<Turret> GetTurrets() { return turrets; } bool STCommit( object rootObject ) { combinedCount = wheelCount + trackCount; return true; } } [SwiftTree.STClass("Turret({VarValues})", "vehicleTree", 1, false )] [SwiftTree.STLink(typeof(Ammo), "vehicleTree")] class Turret { [SwiftTree.STVar] public float ammoPerSecond = 1.0f; public Ammo ammo; bool STAddLink( object link ) { if( link is Ammo ) { ammo = (Ammo)link; } return true; } } [SwiftTree.STClass("Wheel", "vehicleTree", 1, false )] class Wheel { } [SwiftTree.STClass("Track", "vehicleTree", 1, false )] class Track { } [SwiftTree.STClass("Ammo ({VarValues})", "vehicleTree", 1, true, SwiftTree.ClassColour.Hue140_SpringGreen )] class Ammo { [SwiftTree.STVar] public string UniqueName = "ammo";

[SwiftTree.STVar] public int damage = 0; }

Below is a full listing of the VehicleBehaviour that includes some debug output to display the contents of your tree.

public class VehicleBehaviour : MonoBehaviour 
{
    public SwiftTree.SwiftTreeScript swiftTree;
    List<object> vehicles;
    void Start () 
    {
        Profiler.BeginSample("SwiftTree");
        vehicles = SwiftTree.Build.FromStrings( swiftTree.swiftTreeText.lines );
        Profiler.EndSample();
        foreach( object obj in vehicles )
        {
            if( obj is Vehicle )
            {
                Vehicle vehicle = (Vehicle)obj;
                Debug.Log (vehicle.name + " has " + vehicle.combinedCount + " wheels and/or tracks");
                foreach( Turret t in vehicle.GetTurrets() )
                {
                    Debug.Log ("Turret fires " + t.ammo.UniqueName + " every " + t.ammoPerSecond + " seconds");
                }
            }
            else if (obj is Ammo)
            {
                Ammo ammo = (Ammo)obj;
                Debug.Log ("There is ammo " + ammo.UniqueName + " with damage " + ammo.damage );
            }
        }
    }
}


Big Bag of Bits
Big Bag of Bits