Migration Guide

Before upgrading or migrating.

2D Toolkit 2.0 is data-compatible with 2D Toolkit 1.x, but not entirely API compatible. We found this the right time to update some of the APIs. You will be able to use most if not all of your assets and scenes without any modifications. You will, however, be required to update your scripts appropriately to work with the new API.

Before upgrading, please ensure that your project runtime isn't corrupt. You can verify this by running the 2D Toolkit Integrity Checker.

If you use PlayMaker or other Unity middleware that depends on 2D Toolkit, ensure that these have been updated to work with 2D Toolkit 2.0 before you migrate to this version.

If you have moved the source files from the default installation directories, it is highly recommended to move them back to the default installation directory.

IMPORTANT: Make a backup of your project before updating.

Data incompatibilities.

While we have taken a lot of care in making 2D Toolkit data compatible, there are certain smaller less-used features which may be incompatible depending on how you have used it in your project. These features are listed here - please keep an eye out for irregularities with these, and fix them appropriately.

Static Sprite Batcher.

The static sprite batcher had numerous small bugs to do with hierarchy reconstruction which has been corrected in 2D Toolkit 2.0. This may cause different behaviours when your static sprite batcher is rebuilt, either due to a manual rebuild or an automatic build at scene load.

The potential incompatibility may only occur when you set up a hierarchy in the static sprite batcher, and the batcher itself AND other objects within it are scaled.

Sliced Sprite.

The sliced sprite used to have a "legacy mode" for backwards compatibility with 2D Toolkit 1.70 and earlier. There is an automatic upgrade process that is executed when a legacy sliced sprite is loaded for the first time, but there are certain cases where this may fail.

When operating in "legacy mode" the sliced sprite used the anchor set up in the sprite collection as the anchor for the sprite. The automatic migration is capable of upgrading all the preset anchor positions, but will fail when using a custom anchor in the sprite collection settings.

API changes.

• tk2dButton is now deprecated, but is still there in the distribution. Use tk2dUI instead, its much more powerful and flexible.

• tk2dBaseSprite.SwitchCollectionAndSprite is now removed. You can use tk2dBaseSprite.SetSprite to achieve the same thing. You can safely find and replace all occurances of SwitchCollectionAndSprite to SetSprite.

• tk2dBaseSprite.FlipX() and FlipY() are removed, and replaced with properties. You can now do things like sprite.FlipX = true; You should change all occurances of FlipX() to sprite.FlipX = !sprite.FlipX; to get the old "toggle" behaviour back.

• Removed "Always pixel perfect" from sprites & textMeshes. This isn't necessary for operation, and can be called manually if still required.

• tk2dAnimatedSprite is now deprecated, and replaced with tk2dSpriteAnimator. tk2dSpriteAnimator now attaches to a sprite type, and can animate all sprite types - including sliced sprites, tiled sprites, etc. All currently existing tk2dAnimatedSprites simply work - it now acts as a wrapper to tk2dSpriteAnimator, but some functions have been removed.

  • tk2dAnimatedSprite.anim is now private. Replace with tk2dAnimatedSprite.Library.
  • tk2dAnimatedSprite.clipId is now DefaultClipId.
  • tk2dAnimatedSprite.Play( int clipId ) variants are now removed - there was an explosion of function types, and was getting unmanageable. Replace with animatedSprite.Play( animatedSprite.Libary.GetClipById(id) ).
  • tk2dAnimatedSprite.GetClipIdByName removed - prefer tk2dAnimatedSprite.GetClipByName instead.
  • tk2dAnimatedSprite.Play will NO LONGER restart a clip that is already playing. If you want to restart a clip, either Stop and Play again or Play(clip, 0, DefaultFps). This brings the behaviour in line with the Unity animation.Play function.

• Migrating from tk2dAnimatedSprite to tk2dSpriteAnimator on a sprite.

  • Clicking "Convert to Sprite Animator" in the inspector will convert the selected tk2dAnimatedSprite to a tk2dSpriteAnimator. This will break all references to this object, so it is probably not a good idea to do this on a working project. You can create new sprites as tk2dSpriteAnimators, though, safely mix and match.
  • tk2dSpriteAnimator is no longer a sprite. If you need to change sprite properties, eg. scale, spriteId or color - use tk2dSpriteAnimator.Sprite to get a reference to it. So - instead of animSprite.color = Color.red, do spriteAnimator.Sprite.color = Color.red; You do not need to cache the result of this property, as it is already cached in the sprite animator.
  • tk2dSpriteAnimator callback signatures have been changed, and are now called AnimationCompleted and AnimationEventTriggered.
  • Since the tk2dSpriteAnimator is a separate behaviour to the sprite itself, the behaviour can be disabled and time stepped manually, eg. when you need an animation to run while the game is paused.
  • tk2dSpriteAnimator.PlayFrom replaces the the Play overloads that start from a particular time offset. This makes it in line with the PlayFromFrame functions.

• tk2dRuntime.SpriteCollectionSize now replaced with tk2dSpriteCollectionSize. Other systems (sprite collection, font) will be migrated over to this new system in the future, but the changes will be versioned.

• tk2dUIManager.OnMouseWheelChange has been changed to tk2dUIManager.OnScrollWheelChange. Unity was complaining about the OnMouse... function name when built to iOS.

• Building a static sprite batcher in code - use batchedSprites.relativeMatrix.SetTRS( position, rotation, scale ); instead of batchedSprites.position.

Migrating from 2D Toolkit 1.x to 2.0

1. Back-up your project.

• Ideally, have meta files turned on. Read more about meta files here. This is not essential.

1. Run the 2D Toolkit Integrity Checker to ensure the runtime scripts are not corrupt. If it is corrupt, do not proceed. Contact support for more information on how to update.

2. Create a new scene in Unity.

3. Import the 2D Toolkit 2.0 unitypackage.

4. IMPORTANT Restart Unity.

5. If you have previously used the "Setup for JS" command, run it again now. Files will be moved to appropriate locations.

6. Fix up all code incompatibilites as outlined above.

7. Check that you are not affected by the data incompatibility.

8. With a bit of luck, your project should now be running on 2D Toolkit 2.0.