Table of Contents

Migration Guide

Migrating from v1.0.0 to v1.1.0

The rebranding of SOAP RPG Framework to Astra RPG Framework involves several changes that need to be addressed when updating existing projects. This guide outlines the necessary steps to ensure a smooth transition.

1. Backup Your Project

Before making any changes, it's crucial to back up your project. Whether you are using version control or simply creating a copy of your project folder, having a backup will allow you to revert to the previous state if anything goes wrong during the migration process.

2. Update the Package from the Package Manager

Open Unity and navigate to the Package Manager (Window -> Package Manager). In the "In This Project" section, locate the SOAP RPG Framework package. Update it to version 1.1.0, which is now listed as Astra RPG Framework.

3. Update Namespaces in Your Code

If your project contains scripts that reference the old SOAP RPG Framework namespaces, you'll need to update these references to the new Astra RPG Framework namespaces. For doing this, you can use your IDE's find-and-replace-all functionality (Ctrl + Shift + R in VSCode):

  1. Open the find-and-replace dialog in your IDE.
  2. Type ElectricDrill.SoapRpgFramework and assert that the "Match Case" option is enabled.
  3. Inspect the found occurrences to ensure they are correct.
  4. Replace all occurrences that makes sense to you with ElectricDrill.AstraRPGFramework.
  5. Save all modified files.
  6. Return to Unity and recompile the project. If this is not automatic, you can force recompilation with Ctrl + R.

If your project compiles correctly, you're done! If you get errors related to duplicate .asmdef files, follow the next steps.

4. Remove duplicate .asmdef files in the package

  1. In the hierarchy of your project, navigate to the Packages folder and locate the Astra RPG Framework package.
  2. Open the Runtime folder.
  3. Ensure that there is only one .asmdef file named com.electricdrill.astra-rpg-framework.Runtime. If you find also a file named com.electricdrill.soap-rpg-framework.Runtime, delete it.
  4. Open now the Editor folder of the package.
  5. Ensure that there is only one .asmdef file named com.electricdrill.astra-rpg-framework.Editor. If you find also a file named com.electricdrill.soap-rpg-framework.Editor, delete it.
  6. Click on the com.electricdrill.astra-rpg-framework.Editor file to select it. In the Inspector window, in the Assembly Definition References section, add the reference to com.electricdrill.astra-rpg-framework.Runtime if it's not already present, and delete any reference to com.electricdrill.soap-rpg-framework.Runtime if present.
  7. Click on apply to save the changes.
Note

Unity sometimes has unpredictable behaviors when updating .asmdef files in and their references. After applying the changes mentioned above, try also to close and reopen Unity to ensure that the changes are correctly applied. If you still encounter issues, fix the new problems and re-start Unity again. At that point, the changes should be correctly applied.

5. Recompile the Project

If Unity didn't automatically recompile the project after these changes, you can force recompilation.

Your project should now be successfully migrated to Astra RPG Framework v1.1.0.
Happy developing!

Troubleshooting

I re-imported Samples that I already had from v1.0.0 and now I have errors

If you used the ScriptableObject based samples of the Utils folder in your project, you can keep using them as they are fully compatible with the new version. In fact, you should not re-import them as that would create duplicates in your project.

Warning

Do not delete any ScriptableObject based asset that you are using in your project! Delete the duplicates from the newly imported samples instead. This will prevent data loss in your project.

Moreover, it was noticed that re-importing samples in a project that was using v1.0.0 of the package, resulted in old namespaces being used in the samples scripts. This is likely a Unity bug as does not happen on a fresh project. If this happens, please rename the old ElectricDrill.SoapRpgFramework namespace in the scripts of the samples to ElectricDrill.AstraRPGFramework manually, analogously to what is described in step #3.

Still Need Help?

For any issue during the migration, feel free to reach me out by sending me an email at electricdrill.info@gmail.com

Edit this page