Versioning and Releases
The PlayCanvas Engine follows semantic versioning. Every release has a version number of the form major.minor.patch, such as 2.23.3.
In rare cases, a minor release has included a breaking change. For example, 2.5.0 changed how ShaderMaterial handles gamma correction, tone mapping and fog. We work hard to avoid this, and any such change is listed in Engine Migrations.
Choosing Which Updates to Accept
When you run npm install playcanvas, npm records the Engine in your package.json with a caret (^) range, such as "playcanvas": "^2.23.3". A caret range accepts any later 2.x release, so updating your dependencies can move you to a new minor version. To accept fewer updates, install with a different range:
| Updates accepted | Command | package.json entry |
|---|---|---|
| Minor and patch releases (npm's default) | npm install playcanvas | "^2.23.3" |
| Patch releases only | npm install playcanvas@~2.23.3 | "~2.23.3" |
| None (one exact version) | npm install playcanvas --save-exact | "2.23.3" |
The range decides which version npm update can move to, and what a fresh install resolves to when there is no lockfile. package-lock.json still records the exact version you have installed, and npm ci installs that version. None of these ranges selects a beta, preview or alpha build, so you only get one of those by asking for its tag.
If you load the Engine from a CDN instead, put the version in the URL, for example https://cdn.jsdelivr.net/npm/playcanvas@2.23.3/+esm. A URL without a version always loads the latest release.
Release Types
| Release | Example | Contents |
|---|---|---|
| Patch | 2.23.2 → 2.23.3 | Bug fixes only. No API changes. |
| Minor | 2.22.6 → 2.23.0 | New features. Existing APIs may be deprecated: they keep working, and the debug Engine logs a warning when you use one. |
| Major | 1.x → 2.0.0 | Large API changes. Engine v2 removed WebGL 1 support and the legacy scripting system, along with many deprecated APIs. |
npm Tags
As well as stable releases, the Engine publishes prerelease builds to npm. Each kind of build has its own tag:
| Tag | Version format | Contents |
|---|---|---|
latest | X.Y.Z | The current stable release. npm install playcanvas installs this. |
beta | X.Y.0-beta.N | A build of the main branch toward the next minor release, made each night at 02:00 UTC if main has changed since the last beta. It contains merged features that have not been through release testing yet. |
preview | X.Y.Z-preview.N | Published when a minor or patch release is being prepared on its release-X.Y branch, before the release is final. Recent releases have followed within minutes, so this tag often points at a version older than latest. |
alpha | X.Y.Z-alpha.PR.N | An occasional build of a pull request, made so the change can be tested before it merges, for example on mobile devices. Don't use it in projects. |
lts | 1.Y.Z | The latest Engine v1 release. Engine v1 receives critical fixes only. See Engine Compatibility. |
To install a tagged build, add the tag to the package name:
npm install playcanvas@beta
To see which version each tag currently points at, run:
npm view playcanvas dist-tags
Editor Projects
Editor projects don't install the Engine from npm. Instead, you choose which Engine release is used to launch, publish and download your project in the Editor's Engine Settings.