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.

Migrating from 2D Toolkit 1.x to 2.0

  1. Back-up your project.
  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.