Upgrading Bolt

This is the step-by-step process of upgrading Bolt:

Upgrading to Bolt 1.3

Updating to Photon Bolt v1.3 includes several breaking changes: namespaces were changed, some scripts had their visibility changed and you can experience some missing references on your Prefabs. The following instructions aim to minimize the impacts of this update process.

1. Ensure your project has a backup and/or is in a source control system (Git, SVN, Hg) before starting any changes. We can't stress this enought.
2. Before importing the new SDK version into your project, you need to prepare your Bolt Prefabs for the update. As the changes on v1.3 include namespaces modifications, some components were moved, leading to missing references on the game objects. For this reason, we wrote an update script to will help with this task.
   1. Download the Bolt Updater script from our Samples Repository.
   2. Import it into your project inside the Assets/Editor folder. This will make Unity load the Script and include the proper Menu Items.
   3. Make sure you've compiled Bolt (Bolt/Compile Assembly) and have all your prefabs listed on the Bolt Prefab Database (Assets\Photon\PhotonBolt\resources\BoltPrefabDatabase.asset).
   4. Run the task in the Bolt/Utils/Update/Save Prefabs menu. You should receive a log message with Save DONE! message. Take a look at the Assets\Photon\PhotonBolt\resources folder, and there should be an entity_data.json file. This file contains all major settings from your Bolt Entity Prefabs, which includes the BoltEntity component settings, but also information from any Bolt Hitbox, for example.
   5. Store this file somewhere for later use. That is important, otherwise, you will need to setup them manually.
   6. Note on BoltRuntimeSettings: on Scriptable Objects, changes to references are not easily fixable. This is the case of the BoltRuntimeSettings, which will lose the reference of the class it represents after the update. For this reason, considering the Bolt Settings are just a few values, we recommend annotating your current settings somewhere, or take a screenshot, for example. You will need the set the values again later.
3. Delete any Photon Bolt related folders:
   1. Assets/Photon;
   2. Assets/samples;
   3. Assets/Gizmos;
4. Use latest Bolt package and import to your project;
   • You can import all content of the package, as usual.
5. Include a new Scripting Define Symbols on your Project Settings, this will enable some sections of the code needed for the next steps:
   • BOLT_1_3_OR_NEWER
6. Restore the following files from your backup or source control:
   1. Assets/Photon/PhotonBolt/project.json: All your Bolt Assets;
      • In order to get the right references from the serialized data described on the project.json to reflect the new locations on the SDK v1.3, you must edit it manualy, but it should take just a few seconds:
        1. Open the project.json file on any editor of your choice;
        2. Replace all occurrences of Bolt.Compiler. by Photon.Bolt.Compiler. - please, be careful and replace all the text, including the dot at the end.
        3. Save the file.
   2. Open the Bolt Settings window at Photon Bolt/Settings and setup again your values based on the ones you saved earlier.
      • If you experience any errors while trying to edit the settings:
        1. Go to Assets\Photon\PhotonBolt\resources and remove the BoltRuntimeSettings.asset file;
        2. Create a new Bolt Settings: (i) right-click, (ii) Create/Bolt/Create BoltRuntimeSettings;
        3. Open the Bolt Settings window again.
7. As already mentioned, several namespaces were moved to best fit the naming and location of certain scripts. You should note that your project has a lot of broken references. In order to fix this, you will need to modify your source code changing the following namespaces:
   1. Most of the classes now are included inside the Photon.Bolt namespace, so you should include using Photon.Bolt; on every script that you are touching Bolt code.
   2. Remove the following namespaces from your scripts:
      1. using Bolt;
      2. using Bolt.Matchmaking;
      3. using Bolt.Photon;
   3. On direct references, you can just replace the Bolt. by Photon.Bolt. on the script, examples:
      • Bolt.Command to Photon.Bolt.Command;
      • Bolt.ScopeMode to Photon.Bolt.ScopeMode;
      • Bolt.GlobalTargets to Photon.Bolt.GlobalTargets;
      • Bolt.IProtocolToken to Photon.Bolt.IProtocolToken;
      • Bolt.EntityBehaviour to Photon.Bolt.EntityBehaviour;
      • Bolt.ReliabilityModes to Photon.Bolt.ReliabilityModes;
      • Bolt.GlobalEventListener to Photon.Bolt.GlobalEventListener;
   4. Other namespaces that often are used:
      • Photon.Bolt.Utils: include utility classes, like BoltLog and others.
      • Photon.Bolt.Collections: include the Bolt's own implementations of some collections, like BoltRingBuffer.
      • Photon.Bolt.Matchmaking: Matchmaking API;
   5. Now, you should have a project without any errors or missing references, it can take a while, depending on the size of your project, but it's totally possible.
8. Your project is now ready to re-set the Prefabs data.
   1. Depending on the Unity version you are using (specifically 2019 LTS onwards), it will not let us modify the Prefabs and save them back if they have missing script references. In order to solve this, we need to remove those references first:
      1. Run the task on the Menu Photon Bolt/Utils/Find Missing Scripts. It will show a list of all prefabs that has any missing script references.
      2. Run the task at Photon Bolt/Utils/Remove Missing Scripts in order to remove the missing references. Keep in mind that this code will run over all prefabs of the project and remove all references to any missing script components from them. If you want to do this manually, you can use the output from the step above as a reference.
      3. You can run the Photon Bolt/Utils/Find Missing Scripts again, just to confirm that there are no prefabs with missing components.
   2. Copy the entity_data.json file back to Assets\Photon\PhotonBolt\resources, as it was moved on step 2.5.
   3. Run the task at Photon Bolt/Utils/Update/Load Prefabs. This will read the serialized data from entity_data.json and set back all details on your prefabs. You should see a list of all affected prefabs on the Console like: Updating Player (UnityEngine.GameObject).
   4. At the end, you will see the message Load DONE! - meaning that all went well.
9. Compile Bolt (Photon Bolt/Compile Assembly) and you are done.

Upgrading to Bolt 1.2.9 or newer

1. Ensure your project has a backup and/or is in a source control system (Git, SVN, Hg);
2. Delete Assets/bolt and any other Bolt related files:
   1. Assets/Photon;
   2. Assets/samples;
   3. Assets/Plugins;
3. Use latest Bolt package and import to your project;
4. Restore the following files:
   1. If you are updating from Bolt v1.2.5 or older:
      1. Assets/bolt/project.bytes or Assets/bolt/project.xml;
      2. In this case you should also delete the Assets/Photon/PhotonBolt/project.json file, so your Assets could be converted to the JSON format.
   2. If you are updating from Bolt v1.2.7 or newer:
      1. Assets/bolt/project.json;
   3. Assets/bolt/assemblies/bolt.user.dll;
   4. Assets/bolt/resources/BoltRuntimeSettings.asset;
5. Move the following files:
   1. Assets/bolt/project.json to Assets/Photon/PhotonBolt/project.json;
   2. Assets/bolt/assemblies/bolt.user.dll to Assets/Photon/PhotonBolt/assemblies/bolt.user.dll;
   3. Assets/bolt/resources/BoltRuntimeSettings.asset to Assets/Photon/PhotonBolt/resources/BoltRuntimeSettings.asset;
6. Remove the Assets/bolt folder;
7. Quit Unity;
8. Open Unity and compile Bolt:
   1. Run the compilation at Bolt/Compile Assembly menu.
   2. Open the Bolt Assets window (Bolt/Assets menu), you should have all your assets as expected.
9. If the Wizard window did not show up, open it at Bolt/Wizard menu;
10. Follow the steps on the Wizard:
    1. Configure your Photon Cloud credentials;
    2. Install all desired packages. The Core package installation is not required anymore;
11. Any doubt, talk with us on our Discord Community.
12. You are ready to use Photon Bolt.

Upgrading from Bolt 1.2.0.0 to 1.2.8

1. Ensure your project has a backup and/or is in a source control system (Git, SVN, Hg);
2. Delete Assets/bolt and any other Bolt related files:
   1. Assets/Photon;
   2. Assets/bolt_samples;
   3. Assets/Plugins/;
3. Use latest Bolt package and import to your project;
4. If the Wizard window did not show up, open it at: Bolt/Wizard menu;
5. Follow the steps on the Wizard:
   1. Configure your Photon Cloud credentials;
   2. Install all desired packages. You must install at least the Core package;
   3. Any doubt, talk with us on our Discord Community.
6. Quit Unity;
7. Restore the following files:
   1. Assets/bolt/project.bytes or Assets/bolt/project.xml, if you are updating from Bolt v1.2.5 or older;
      1. In this case you should also delete the Assets/bolt/project.json file, so your Assets could be converted to the JSON format.
   2. Assets/bolt/project.json, if you are updating from Bolt v1.2.7 or newer;
   3. Assets/bolt/assemblies/bolt.user.dll;
   4. Assets/bolt/resources/BoltRuntimeSettings.asset;
8. Open Unity and compile Bolt:
   1. Run the compilation at Bolt/Compile Assembly menu.
   2. Open the Bolt Assets window (Bolt/Assets menu), you should have all your assets as expected. If it's true, you can remove/delete the old project files (Assets/bolt/project.bytes or Assets/bolt/project.xml).
9. You are ready to use Bolt.

Migrating Bolt Assets

Bolt saves all of its objects, states, commands and events in the Assets/bolt/project.json file.
It's just a JSON file that defines all information from the assets.
You can read it but we highly discourage that you modify this file directly, the modification can break the deserialization process.

To migrate to a new project, simply copy this file to the same location in the new project. This is also useful if you need to share Bolt data with other team members.

Upgrading Bolt Free to Bolt Pro

If you now have access to Photon Bolt Pro, it's easy to update your SDK to this new version.
First, follow the instructions on the section Upgrading Bolt, as you are changing versions, the instructions are the same as if you upgrading.

The important aspects of the update are that you must maintain your project using a Version Control System like SVN or GitHub before doing any changes or make a backup of it.
There are some files that are the most important ones for your game work properly after the update:

• Assets/Photon/PhotonBolt/project.json: this contains all your Bolt Assets descriptions;
• Assets/Photon/PhotonBolt/assemblies/bolt.user.dll: this is the generated DLL every time you Compile Bolt, it's nice to have it saved, so you don't see errors after the update.
• Assets/Photon/PhotonBolt/resources/BoltRuntimeSettings.asset: the Scriptable Object that contains all Bolt Settings you've set for your game.

In summary, the update process is:

1. Backup the files described above;
2. Remove All Bolt Related files;
3. Import the new version of Bolt;
4. Revert your files on the right locations;
5. Done.

Also, you need to restart Unity at least once, so it reloads all Bolt DLLs.
We also suggest you remove the folders: Library, obj and Temp on the root for your project folder (those folders are not inside the Assets folder) only if you are having compilation issues.
Keep in mind that removing those folders will cause your project to be completely recompiled by Unity, which may take a while, depending on the size of your project.

Regardless of the code or script changes, the update is almost minimal.
The main difference is that you are now able to connect to a server directly using its IP/port.
Once you have imported the SDK, you will find the samples_pro folder, and there you will find the BoltPro/BoltProInit.cs script.
This script shows how you can start a Game Server using the DotNetPlatform (that allows the direct connection), and later how to connect to the server from the client using the BoltNetwork.Connect using the server EndPoint.
The rest of the code and behaviors should be the same as on the Free version.