Versions & compatibility

The API version

viewpoint-api.jar contains only viewpoint.api.**. It has its own version, with semantic versioning. This version is not the same as the Viewpoint version.

• In 1.x, changes only add. New types and new methods come with a default body. An interface that addons implement never gets a new abstract method.
• Deprecated members stay for two releases. Then they are removed.
• Use viewpoint.api when you can. You can also use or hook some of Viewpoint’s internal members. They are in the Viewpoint internals list. Internal members can change in each release, and they give your addon an Amber or Red label. Viewpoint does not load a jar that uses an internal member that is not in the list.

At run time, Viewpoint uses only its own copy of the API. Viewpoint refuses a jar that contains viewpoint.api classes.

Tell Viewpoint the API version

Set api=1.0 in the descriptor to the version that you compiled against. Viewpoint accepts the addon if the major version is the same and its own minor version is the same or higher.

Ask what is available

Version.API is the API version of the installed Viewpoint. To use a feature that comes after 1.0, and also run on 1.0, ask for the feature first:

if (Version.has("view.pose", 2)) {
    // the second generation of the pose is available
}

has(capability, generation) tells you if a generation of a capability is available. The javadoc of the type that adds a capability gives its name and generations.

The passes of a Shaderpack have a version also. Ask for it with Version.has("passes", generation).

Internal members change

The members of Viewpoint on the internals list have no promise of stability. Each release can add, deprecate or remove members. Internals changes lists the changes of each release.

The member is	What occurs
Deprecated	The addon works. The card shows the replacement and the Amber reason uses deprecated internals.
Removed	The addon shows Needs an update: uses <member>, removed in <release>; use <replacement>. It does not start.

A removed member stays in the list as a record, so that the card can tell the author what to use. Test your addon with each release that your players use.

The game and Viewpoint

Set game.min, game.max, viewpoint.min and viewpoint.max to the builds that you tested. Outside this range the package is Incompatible, and the player cannot switch it on. The card names the limit.

Viewpoint supports one game build. On a different game build, Viewpoint stays off, and all addons stay off with it. Your ranges do not change this.

Errors

You see	Cause	Fix
Failed: built for another API	Your code needs a class or method that this API does not have. Java throws a LinkageError during enable.	Compile against the API version that you set in api. Use Version.has before you use a newer feature.
Incompatible	A range in the descriptor does not agree with this installation.	Read the card. Correct the range, or update the game or Viewpoint.
Needs an update	The addon uses an internal member that Viewpoint has removed.	Read the card. It names the replacement.

Old jars

A jar that you compile for API 1.0 loads in all 1.x versions.