Project upgrade 170

Sometimes, when a new version of the popcorn runtime & editor is released, some things might change that will cause assets to break.
Although the file formats popcorn uses support retro-compatibility, it is on-purpose that we do not make everything retro-compatible.
This gives us much more freedom to improve and refactor things that need to be, to bring you a better system.

However, we have a system that knows the history of breaking-changes in assets, from version to version, and can automatically upgrade yours if they are from an earlier version.
It can only upgrade assets from an earlier version to a newer version, NOT downgrade them from a new version to an old one.

Out-of-date projects

The upgrade system has various implications:

• Your editor packs must ALWAYS have the "LastRevision.txt" file next to their "PopcornProject.xml" project-file. This is where the editor stores the last version of the pack. (This might change in the future to add a per-asset version number, to make it easier to transfer assets from one machine to another, that might not have the same editor version)
• If you have popcorn packs in source-control, Make sure their "LastRevision.txt" file is in source-control too, so that the pack won't get upgraded twice by different people.
• You should avoid manually copy/pasting assets from packs that are not upgraded to the same popcorn version.
• Your popcorn editor version should match your runtime version

The editor makes it clear in the project list which projects are out-of date and need updating, by highlighting them in red and displaying a tooltip giving details about what changes have taken place between that pack's version and the current editor version:

Projects without the "LastRevision.txt" file next to their "PopcornProject.xml" file will be treated as legacy packs (before the revision system was introduced), and ALL patches will be applied:

Upgrading a project

To upgrade an out-of-date project, simply click on the 'update' icon appearing next to the 'delete' icon:

This will show the upgrade window, where you can see a detailed list of upgrades, and which ones need to be applied.
Upgrades shown in green are already applied. Upgrades shown in red still need to be applied.

You can choose to upgrade step by step by clicking the small upgrade button next to each upgrade.
Doing so will run all upgraders up to that upgrade included, but will not upgrade further.

Here, we clicked on the 1.5.5.20320 'upgrade' button:

Clicking 'Apply' will upgrade up to the selected upgrade, by default, it will upgrade to the latest upgrade.
When the pack is up to date, the upgrade window will say so:

Troubleshooting project upgrade

Sometimes, a project upgrade can fail.

Most of the time, this is due to the access permissions on the files that the editor tries to upgrade.
It can happen if you are using a source-control software that locks the files and sets them to read-only mode.
The popcorn editor will not force them to read-write, therefore will fail upgrading them if they are read-only.

If anything goes wrong during the upgrade, it will be logged in the 'Errors' output panel underneath the list of upgrades:

You can also take a look at the 'Infos' output panel to see which files were touched during the upgrade, which will tell you exactly which files have failed, and why:

You might also get this error when upgrading:

Which indicates the editor failed writing to the "LastRevision.txt" file at the root of the PopcornFx pack.

Projects more recent than the editor

A project MORE RECENT than the editor will appear in a slightly deeper red, and the tooltip will say so explicitely:

Trying to open the project will pop up the following warning window: