Data Driven Collections (Preview)

NOTE: This is a preview feature. It may change significantly, or even be removed in a future version.

Data driven collections let you define a set of sprite collections in a very script-like syntax. However, your code is still running under .net, so you are still free to use advanced language features if you need them. This feature is currently a preview - only a few essential internal functions are exposed. We are not intending on exposing absolutely every feature, but will add the most requested features as required.

Getting Started

The data driven collection is defined by a class in Unity. Begin by creating a new C# script in Unity. Replace the automatically generated code with this boilerplate, replacing MyFirstDataDrivenCollection with the name you wish to give this data definition -

public class MyFirstDataDrivenCollection : tk2dDataDefinition {
    public override void Define() {
        // Data definition goes here.
    }
}

Your data is defined within the "Define" function as overriden above.

Building the data

Bring up the data definition editor by clicking on the 2D Toolkit > Data Definition Editor menu. This window lists all the data definition classes in your unity project and lets you build individual ones or batch build all of them. Clicking Build on MyFirstDataDrivenCollection will build the data. As there isn't any data defined in that class, nothing will be built.

Settings

Lets start by defining some settings for this job. Replace the Define function with the following.

   public override void Define() {
        Settings.InputPath = "TK2DROOT/tk2d_demo/datadrivencollection";
        Settings.OutputPath = "MyFirstDataDrivenColection";
        Settings.PixelsPerMeter = 10;
    }

This tells the system to look for input data (textures, etc) relative to TK2DROOT/tk2d_demo/datadrivencollection. It also tells it the output path is relative to MyFirstDataDrivenColection. These paths are relative to the project assets root, i.e. what you see in the Project window in Unity.

Creating a Sprite Collection

We'll now create a sprite collection. Replace Define with the following.

   public override void Define() {
        Settings.InputPath = "TK2DROOT/tk2d_demo/datadrivencollection";
        Settings.OutputPath = "MyFirstDataDrivenColection";
        Settings.PixelsPerMeter = 10;

        SpriteCollection.Add( "MyFirstSpriteCollection" );
            SpriteCollection.InputPath = "textures";
            Sprite.Add("anim/anim1.png");
    }

We're creating a new sprite collection called MyFirstSpriteCollection. It will be created in the MyFirstDataDrivenColection directory. This sprite collection sources textures from the textures directory - this is relative to Settings.InputPath, i.e. TK2DROOT/tk2d_demo/datadrivencollection/textures.

Add a sprite by calling Sprite.Add(...). This path is stacked on top of the previous patch, making the full search path TK2DROOT/tk2d_demo/datadrivencollection/textures/anim/anim1.png. This is a file included in the demo, so it should just work.

Save the file, switch back to Unity and Build this data definition. After a short pause, you should see a new sprite collection in that path. Opening up the sprite collection in the sprite collection editor will show you that it has indeed added anim1.png to it.

If you want to add anim1, anim2, anim3... in that directory, you can just replace the Sprite.Add line with the following:

Sprite.Add("anim/anim*.png");

To set the sprites anchor position, do the following:

Sprite.Add("anim/anim*.png").Anchor("LowerLeft");

Creating an Animation

Creating an animation follows the same principle. You should only define animations after all your sprites are defined. The following code creates an animation.

       AnimationCollection.Add( "DataDrivenAnim1" );
            AnimationCollection.DefaultFps = 30;

You can add a clip to the collection by doing the following. Note you do not need the sprite extension here.

           Clip.Add("Sample1", "Once", 15);
                Frame.Add("anim1");
                Frame.Add("anim2");
                Frame.Add("anim3");
                Frame.Add("anim4");
                Frame.Add("anim5");

You can also refer to sprites from a sprite collection by using this syntax:

               Frame.Add("MyFirstSpriteCollection:anim1");

Alternatively you can use this shorthand.

           Clip.Add("Sample1", "Once", 15);
                Frame.Add("anim*"); // adds all anim* sprites it can find in ascending order

And if you need to add sprites by range:

           Clip.Add("Sample1", "Once", 15);
                Frame.Add("anim*").Range(2, 4); // adds anim2, anim3, anim4

           Clip.Add("Sample1", "Once", 15);
                Frame.Add("anim*").Range(4, 2); // adds anim4, anim3, anim2

           Clip.Add("Sample1", "Once", 15);
                Frame.Add("anim*").Reverse(); // adds all anim* sprites it can find in descending order

Animation Triggers

You first define named triggers in your data defintion class by doing the following:

       DefineTrigger("MyTriggerName", "FootStep", 0, 3.0f);

FootStep is the string info field of the trigger, 0 and 3.0 are the int and float values respectively.

After which you can use this trigger by name in any of your frames, eg.

               Frame.Add("anim4").Trigger("MyTriggerName");

The defined trigger is valid throughout your data definition.

Platform sprite collection

To create a platform sprite collection, you need to make sure the textures exist in the correct locations and are named correctly. To enable the feature, simply add this line to your sprite collection. The first platform in the list is treated as the default collection, i.e. the ones referred to by your texture names.

       SpriteCollection.Add( "PlatformTest" ).Platforms("1x", "2x");

Example

Here is a complete example of a data driven collection. This file is included as a demo in the tk2d distribution. Building this will give you 2 sprite collections, 1 with platform data, and one animation collection.

public class tk2dDemoDataDrivenCollection : tk2dDataDefinition {
    public override void Define() {
        // These paths are relative to the project root
        // All subsequent paths are stacked on top of the parent
        Settings.InputPath = "TK2DROOT/tk2d_demo/datadrivencollection";
        Settings.OutputPath = "Unversioned/datadrivencollection";
        Settings.PixelsPerMeter = 10;

        SpriteCollection.Add( "DataDrivenTest1" );
            SpriteCollection.InputPath = "textures"; // Appends this texture path to Settings.inputPath for this sprite collection only
            Sprite.Add("anim/anim*.png").Anchor("LowerLeft");

        SpriteCollection.Add( "PlatformTest" ).Platforms("1x", "2x"); // the default is the first platform
            SpriteCollection.InputPath = "textures/platform";
            Sprite.Add("sample@1x.png");

        // Add animations
        DefineTrigger("MyTriggerName", "FootStep", 0, 3.0f); // subsequently these triggers are referenced by name. valid in all animation collections.

        AnimationCollection.Add( "DataDrivenAnim1" );
            AnimationCollection.DefaultFps = 30;
            
            Clip.Add("Sample1", "Once", 15);
                Frame.Add("ani*").Reverse();

            Clip.Add("Sample2", "Loop");
                Frame.Add("anim*").Range(4, 1);
                Frame.Add("DataDrivenTest1:anim*").Range(1, 4);

            Clip.Add("Platform", "Once");
                Frame.Add("sample");
                Frame.Add("anim2").Trigger("MyTriggerName");
    }
}