The Potential for Broken Links

When you build a website, and you link to an image on somebody else's web server, they could potentially break your website by removing the image from their web server. Likewise, when you build a Wild Pockets game, and you refer to an asset in somebody else's folder, they could potentially break your game by removing the asset. Version locking is a mechanism to make sure this doesn't occur.

Removing an asset isn't the only way to break a game. Simply replacing an asset with a more recent version could break a game, if the new version isn't compatible with the old one. You don't even have to link to somebody else's folder to put yourself at risk. Even referencing your own assets can cause problems, if you intend to continue tweaking and improving those assets.

Version locking is designed to solve problems associated with asset and script updates unexpectedly causing a game to break.

The Core Idea of Version Locking

When you upload a file to the file server for the first time, the file server assigns the file a version number of 0. If you upload a new version, that version has a version number of 1. If you then delete the file, the version sequence is maintained. The file is now null, but if you recreate the file, that is now version 2. The version sequence never clears and never resets, the server saves all versions, indefinitely.

The key idea behind version locking is that when your game is in the gallery, it does not necessarily use the latest version of every asset. Instead, it uses the last-known-good version. To make this possible, the scene file contains a table that lists, for every asset, the last known good version. This is called the version lock table.

Having a table of last-known-good versions makes it possible to run the game in a safe mode where it always uses known good asset versions.

How the Version Lock Table is Built

Open the builder, then save a new game in your server folder. This is essential, you must save the game in your folder - it cannot build a version lock table unless you have write-access to the game. Your game initially has a blank version lock table, which you can see by opening the version lock editor. Do so by clicking in the File menu of the development environment.

The version lock table is built primarily by testing your game. To do so, click Debug/Begin Test. Each time you test your game, the development environment attempts to update the entries in the version lock table, and add new entries. The update process works as follows:

• Any asset that gets used during testing that is not in the table is added to the table, and the version is set to the latest version.
• If the testing process uses an asset that's already in the table, the version is updated to the latest version, unless the asset is marked frozen.

Because the development/testing environment is constantly updating the entries in the table to the latest version, you pretty much always see the latest version of every asset during the testing process. The only exception is when an entry in the table has the freeze checkbox next to it. This prevents the entry from getting updated. If nothing in the table is frozen (as is commonly the case), then testing works as if there were no version locking at all, always showing the latest version of everything.

When you publish your game to the gallery, or send it to a friend, the game runs in a different mode: production mode. Production mode differs from testing mode in that it does not attempt to update the table. Instead, it uses whatever versions are already recorded in the table.

The net effect is this: when you run the game in test mode, it uses the latest version of everything. When you run the game in production mode, it uses the same versions you last used during testing. Or to put it differently, the production game will always look exactly as it did during testing - even if the assets are being altered or deleted by their authors.

Tweaking the Version Lock Table

Suppose that you use a friend's dragon model in your game, and it looks great. But one day, you're testing your game and you see that your friend has recolored the dragon, and you like the old colors better. The system doesn't know that this update is undesired. You must tell it, by manually tweaking the version lock table.

Go into the version lock table, and find the entry for the dragon. Dial back the version number by clicking on it and selecting a different version. This will automatically "freeze" the entry at that version. After dialing back the version, test the game again - if the dragon looks right, you're done. If not, you may need to play with the version number some more until you find the version that was good.

Disabling Version Locking

Sometimes you really do want your game to use the latest version no matter what. For example, suppose that you intend to deliberately publish new textures every week, just to keep your game looking fresh. In that case, version locking is going to get in your way - it's going to keep the textures locked down to how they looked the last time you tested the game.

To disable version locking for an asset, go into the version lock editor and find the asset you intend to update frequently. Click the disable-icon next to the asset. This will grey out the line in the version lock editor. The result will be that the game will use the latest version no matter what, even if the latest version is broken.

The Local Folder

The file server assigns a version number to everything. When an asset is stored in your local folder, it doesn't have a version number yet. If a file has no version number, it is impossible to put the correct version number into the version lock table.

However, a file which is in your local folder will probably get uploaded eventually. At that time, it will be assigned a version number. The version locking system knows this and waits for that moment. As soon as the file is uploaded (and hence, assigned a version number), the version lock system inserts the correct version number into the table.

This process can fail under an extremely obscure set of circumstances. The sync tool leaves behind records showing what was uploaded, and what version number was assigned. These records are used by the version lock system to update the version lock table. If those records are deleted or overwritten before the version lock table can be updated, the version lock table can be left not knowing what the correct version number should be. It is very hard to get into this state. If you manage it, the solution is to test the game a second time. Testing the game a second time will clear up the problem.

Of course, during normal development you tend to test your game over and over, so this is not often an issue.

Versions of Versions

The file server saves old versions of every file. This is true for scene files as well. That has interesting consequences.

Suppose you're in the development environment, and you click File/Save As, and type in a filename: "mygame.scene". You have now created a file on the file server: mygame.scene version 0. If you then click File/Save, you have written another file to the file server: mygame.scene version 1. If you click File/Save again, you have written yet another file to the file server, mygame.scene version 2. The file server now contains three versions of your game.

Suppose that mygame.scene version 2 contains this version lock table:

12, dragon.jpg
27, lizard.jpg

And, suppose you continue development of your game - you make a lot of improvements to dragon.jpg, yielding dragon.jpg version 18. You test your game, and sure enough, the new dragon texture looks much better. So you save your game again. You have now created mygame.scene version 3, which contains this version lock table:

18, dragon.jpg
27, lizard.jpg

But remember, the file server saves everything, so mygame.scene version 2 is still being stored on the file server, and it still has this version lock table in it:

12, dragon.jpg
27, lizard.jpg

If you launch mygame.scene version 2, it will use version 12 of dragon.jpg. If you launch mygame.scene version 3, it will use version 18 of dragon.jpg.

The point is this: the version lock table captures a snapshot in time in the development of your game. Each time you save your scene, you save another snapshot. Those snapshots are all stored, in the version history of your scene file. You can launch your game not just in its current incarnation, but in any past incarnation.