Programming Manual Chap. 20

Dealing with Incompatible Changes
Wild Pockets is being continually upgraded and improved. Most of the time, adding features and fixing bugs makes everyone happier. But sometimes, we wish to make changes that could cause problems for developers.

Here is an example: when Wild Pockets was first conceived, we weren't sure what units of length, force, and velocity to use. By failing to think it through thoroughly, we ended up with some units that didn't correspond to any reasonable standard of measurement. We call this crazy system of units "legacy units." Several games were written using these legacy units. It was an unfortunate situation.

At some point, we realized that we should have used the metric system (Meters, Newtons, Kilograms). Although it was obvious to us that the metric system would be better, it was also clear that switching from legacy units to the metric system would have caused existing games to stop working.

We consider this forbidden: one of our prime directives is "never break a game that works." A developer should be able to write a game, finish it, walk away, and then come back ten years later and the game should still be playable.

But of course, we still need to be able to make improvements to Wild Pockets, and the metric system would have been a big improvement.

To resolve the conflicting goals, we created the "engine version" system.

Engine Versions
The first publicly announced engine version was version 1.3, which was soon followed by version 1.4. Since then, we have released additional versions.

The first thing to know about engine versions is: we never throw out a version. If you want to make a game that uses engine version 1.3, you can. (It's not advised, that's a very old and buggy version, but you can do it.)

The second thing to know about engine versions is that every game in Wild Pockets is tied to a particular engine version. If a game was created using engine version 1.4, for instance, then that game will always run using engine version 1.4. Engine versions are "sticky."

Checking your Engine Version
When your game is running, or when editing your game in the builder, look in the lower right corner of the Windows taskbar: you will see the "WP" icon. You can click on the WP icon and select "About Wild Pockets." This will show you what engine version you are using.

Switching to a More Recent Version
If you created a game using engine version 1.4, and we release version 1.5, then your game remains tied to engine version 1.4. Although this is advantageous in that it means your game still works as well as it ever did, it's disadvantageous in that you can't take advantage of the features of the new version.

If you want access to the new features, then you can manually switch your game over to the new version, by issuing a command in the builder. Load your game in the builder, and open the debug console. In the debug console, type this command: Simulation.setEngineVersion("1.5") Notice that the parameter is a string, not a floating point number.

Save the game using the builder's file menu. Now that you've saved it, your game will use engine version 1.5.

Of course, once you switch engine versions, your game may not work any more. You may need to alter it to be compatible with engine 1.5. If this turns out to be more work than is practical, you can switch back to 1.4, using the same command.

How Games get Wired to a Version
In Wild Pockets, you don't create games from scratch. You always start by opening somebody else's game, editing it, and saving it as your own. When you do this, your game has the same engine version as the game you built upon.

Many Wild Pockets developers don't quite realize that they built their game on "somebody else's game," because they started with what appeared to be a "blank slate." But in fact, when you open the builder, the scene isn't actually completely blank - there are two blue cubes and a cloudy sky. Those cubes were loaded from a saved game file whose filename is ""Wild Pockets Team/default scene". Like every other Wild Pockets game, the default scene has an engine version. When you build a game on top of the default scene, you inherit the default scene's engine version.

When we release a new engine version, we update the engine version of the default scene. That way, if you build on top of the default scene, you're using the latest engine version. But if you build your game on top of anyone else's game, you need to check what engine version they used.

Upgrades to Existing Versions
Sometimes, we upgrade an existing version without changing the version number. For example, if we were to discover a bug in the 1.4 engine, we might release a bugfix. The bugfixed engine would still be version 1.4. Because of this, engine versions have a "minor" version number: 1.4.12, 1.4.13, 1.4.14, etc. When selecting an engine version, you cannot specify the minor version number.

We are strict about the following rule: when we upgrade an engine in-place, we are very careful not to break any existing games. We never make API modifications by altering an engine in-place. If we wish to make API or design changes, then those have to wait until we release a new engine version.

Maintenance of Deprecated Versions
When we release a new version, the old versions become deprecated. You can use them anyway! They will never be deleted.

However, when an engine is deprecated, it means we're going to put less effort into maintaining it. If a bug is found in engine version 1.4, we may fix it, if it's reasonably feasible to do so. But we may not. We rarely add features to old engine versions. The older the version is, the less likely we are to put effort into it.

Security vulnerabilities are a different story. If we discover that an old engine version allows some sort of exploit, it will be fixed.

Version History
We provide a version history page [6] that you can use to see the major changes in each engine version.