Skip to main content
Version: Next (dev)

Packages

Engine features such as physics (plasma.jolt), audio (plasma.audio), Game UI (plasma.gameui) or visual scripting (plasma.visualscript) ship as packages. A project lists the packages it uses, and the editor installs them into the project's Plugins folder. This page explains how the editor decides which package versions load, how it keeps every computer on the same versions, and how packages declare the platforms they support.

Open the Package Manager with Project > Packages > Package Manager....

Which Versions Load​

The packages of a project are settled while the project opens, before any package code is loaded. The editor:

  1. Resolves versions. Every package names the versions of other packages it needs as a range (for example plasma.jolt ^1.0). The editor picks one version of each package that satisfies all ranges, newest first, and prefers what the project already uses: the version in the lock file, then the project's pinned version, then what is installed. Versions that do not fit this engine version, its ABI or the current platform are ruled out first. The same input always gives the same answer on every computer.
  2. Compares with the lock file. Editor/Packages.lock, next to Editor/Packages.ddl, records the exact version of every package the project resolved to, the registry it came from, and a SHA-256 hash of every component of that version.
  3. Restores from the lock. A locked version that is not installed is downloaded from the registry, but only if the registry still describes each component with the hash in the lock. Downloads are checked against the same hash.
  4. Checks every package that would load, without opening any library (see What is checked).
  5. Asks once about everything it found (see The prompt).
  6. Leaves out what stays unresolved. A package that is skipped does not load in the editor, its engine process, the EditorProcessor or the Player. The log names the skipped packages in one line: These packages are not loaded this session: ...

Every package that does load is loaded at the selected version, not at whichever installed copy is newest.

Version ranges​

RangeMeaning
^1.4>=1.4.0 <2.0.0. Below 1.0 the caret is narrower.
~1.4.2Patch updates of 1.4.
>=3.0 <4.0An explicit range.
=1.2.3 or 1.2.3Exactly this version.
1.4.xAny 1.4 version.
*Any version.

Prerelease versions are not supported.

The lock file​

Commit Editor/Packages.lock with the project. It makes every teammate and build machine load the same package versions. The file is sorted, has no timestamps, and ends with a digest of its own text. A hand edit, a bad merge or a truncated write fails the digest. The editor then reports the file instead of using it, and never silently rewrites it.

Project Checks includes the check Packages.lock matches the package list. It warns when the lock cannot be read, is out of date with the package list, or is missing (The project has no Packages.lock; other machines may install other versions).

What is checked​

A package is reported when:

  • it was built for another engine ABI (it was built for ABI '...', this engine is '...'), or its manifest does not say which engine build its binaries are for,
  • it does not support this engine version (it supports engine X to Y, this engine is Z),
  • it has no binaries for this platform, or none for the running configuration, or a plugin named in its manifest is missing,
  • it was built from source on this computer and its sources or manifest changed since,
  • its installed files differ from the lock.

Packages Need Attention​

All problems are collected into one prompt, Packages Need Attention. It says how many packages cannot be loaded as they are, lists each one with its reasons, and offers:

ButtonWhat it does
Fix AllRecompiles the packages whose source is on this computer, and installs or updates the others.
Choose Per Package...Asks about each package in turn: Recompile, Install / Update to / Reinstall, Skip or Skip Remaining.
Skip AllOpens the project without those packages. This is the default button.

When nothing can be fixed, the prompt only offers Continue Without Them. If an install or update fails, the packages keep the versions they had.

Version conflicts​

When no version of a package satisfies every requirement, the details name the packages and ranges, for example:

No version of 'plasma.jolt' satisfies every requirement:
- the project requires plasma.jolt =2.0.0
- plasma.networking 1.0.2 requires plasma.jolt ^1.0
Versions considered:
2.0.0 registry 'Plasma': outside ^1.0 required by plasma.networking 1.0.2
1.1.8 installed: outside =2.0.0 required by the project

The packages in a conflict stay out; the rest of the project loads. Change the project's requirement or update the package that asks for the old range.

Upgrades are all-or-nothing​

Adding, updating or restoring packages installs the new versions beside the old ones first. Only then are Packages.ddl and Packages.lock swapped in. A journal in Plugins/.transaction records what is being replaced. If the editor or the computer stops in the middle, the next start either finishes the change or rolls it back, so the project is left with the previous working set. Old versions are removed only after the change is complete.

note

Recompiling a package replaces its installed binaries in place. That step is not part of the rollback.

Runs Without a User​

RunBehaviour
Headless, -nostartupdialogsMissing locked versions are restored automatically. Any other problem fails the run with one summarised error and exit code 2: The project's packages cannot be loaded as they are: ... Open the project in the editor to recompile or update them, or restore the versions in Editor/Packages.lock.
Read-only projectNothing is installed and the lock is not written.
Background processes, unit testsSkip what cannot be loaded and log one line.
PlayerChecks the package folders before it loads them. Packages that do not match the engine are left out with one error (N package(s) were not loaded because they do not match this engine) and exit code 2.

Platform Support​

A package publishes components, named <kind>-<platform>:

KindContents
runtime-*The runtime plugins the game loads.
editor-*Editor plugins.
sdk-*Headers and import libraries for building against the package.

The platforms are win64, linux64, macos64 and android-arm64 (for example runtime-linux64, runtime-macos64, runtime-android-arm64). Components without a platform, such as assets, apply everywhere.

Each platform's components carry their own ABI tag, and the engine checks the tag of the platform it runs on. A package can therefore publish a Windows build and a macOS build made at different times. The binaries live in Bin/<Platform>_<Arch>_<Configuration>: Windows_x64_*, Linux_x64_*, Mac_x64_* (also used on Apple silicon) and Android_arm64_*. Libraries are named X.dll, libX.so and libX.dylib.

The editor installs the editor and SDK components for the computer it runs on, and the Android runtime components so the project can be exported for Android.

Android in the Package Manager​

Each package row has a Win64 badge and an Android badge: Android, Android · not built, Android · excluded or editor only. The Android badge is red when the package does not support Android. The details panel shows the Android status (published, local build, not built, unsupported, editor only, content only or part of the engine) and lists the runtime-android-arm64 component.

A banner at the top says whether Android export can package every runtime package of the project, or names the packages that block it. Only packages that block Android filters the list down to those.

For a package that blocks Android you have two options:

  • Build for Android (local) (or Rebuild for Android (local)) builds its arm64 libraries for every configuration the SDK ships. This needs the package's source and the Android toolchain.
  • Exclude from Android exports leaves the package out of Android exports, so its plugins do not load there. The exclusion is stored with the project in Editor/Packages.ddl. Use it for packages the game does not need on phones.

Package Manager: the Android banner lists the packages that block Android export, each package shows Win64 and Android badges, and the details panel has Exclude from Android exports

In 0.12 the packages of the launch set have Android builds: plasma.ai, plasma.angelscript, plasma.audio (on AAudio), plasma.cameras, plasma.gamecomponents, plasma.gameui, plasma.jolt, plasma.networking, plasma.particles, plasma.procgen, plasma.rmlui, plasma.terrain, plasma.vegetation, plasma.visualscript and plasma.water.

Troubleshooting​

ProblemCause and fix
Editor/Packages.lock: ... in the promptThe lock failed its digest (hand edit, merge, truncated write). Restore it from version control, or let the editor write a new one with Fix All.
the lock records another version than the one that would be usedSomeone changed the package list without committing the new lock. Pull the matching lock, or accept the new resolution.
A build machine fails with exit code 2A package is out of date for that engine. Open the project in the editor once, fix it, and commit Editor/Packages.lock.
Android export reports N packages block AndroidBuild those packages for Android, or tick Exclude from Android exports for them.

See Also​