Manual
Manual
Using packages
A package is a folder of assets, scripts and shaders that a game installs and builds with its own, such as 2D physics or a set of models. This page covers the Package Manager and where it lists packages from, signing in and the Store, installing, updating and removing a package, a package you changed, the list a game keeps of its packages and how every build puts them back, packages in the Project panel, and the packages that come with the engine. To make a package of your own, see Making a package.
What a package is
A package lives in the game's packages/ folder, in a folder named by its id, such as packages/acme.demo. Its package.json says what it is: its id, name and version, who made it, the engine versions it is made for and the packages it needs. Beside it are assets, scripts and shaders folders like the game's own, and a package may also carry Rust, native libraries and scripts for a web page.
A package's files stay in its folder. The engine names each one after the package's id, acme.demo://models/rock.glb, so a scene, a material or a model's import names a package's file without copying it into the game. Its C# is built into an assembly of its own, and its components are named in full, with their namespace, so a package's Wobble is never taken for the game's. A build packs a package's files and code with the game's, so a built game needs no packages folder beside it.
The Package Manager
Open Window ▸ Package Manager, or Manage Packages... at the foot of the Project panel's package switch. The window has three columns: where packages are listed from on the left, the packages of the source you pick in the middle, and the package you pick on the right.
| Source | What it lists |
|---|---|
| In Project | The game's packages, grouped under Abyss Registry, My Assets and Made Here by where each came from. Packages the game's list names and no registry could put back are under Missing. |
| Updates | The game's packages that have a newer version, in your registry or on abyssengine.net. |
| Abyss Registry | The engine's own packages. |
| My Assets | Every other package in your registry: those you exported or added from a file and, once you are signed in, every package your account owns on abyssengine.net. |
| Store | The packages on abyssengine.net. See The Store. |
In Project and Updates show how many packages they list. Each row shows a version on its right: the game's version with a newer one beside it (1.0.0 · 1.2.0 newer), or, in a registry's list, the version the game has (1.2.0 · in project). A package your account owns that is not in your registry yet says on the website.
The search box over each list, except the Store's, finds packages by name, id and keywords.
Along the bottom are New Package, Add from File... and the folder of your registry. Under them, a line says what the last change did, or why it was not done.
A package's details
Pick a package to see its name, its id, version and author, and its description. Under them:
| Row | What it says |
|---|---|
| License | What you may do with it, or Not said |
| Engine | The engine versions it is made for, and this editor's version. It is amber when this editor is not one of them. |
| Needs | Each package it needs, the versions that will do, and the version the game has, or not installed |
| Copyright | Whose it is |
| Changed here | How many of its files you changed, added or deleted since it was installed. See A package changed here. |
| Listed | The version settings/packages.json lists, where it is not the version the game has |
Install a package
- Pick a package under Abyss Registry or My Assets.
- Pick a version in the list beside Install. The newest is picked to start with.
- Click Install.
The package is copied into the game's packages folder, together with every package it needs that the game does not have yet. For each of those, the newest version your registry has that the range takes is installed:
| Range | Versions it takes |
|---|---|
^1.2.0 | 1.2.0 and later, below 2.0.0. Below 1.0, below the next minor version: ^0.2.0 takes 0.2.0 and later, below 0.3.0. |
~1.2.0 | 1.2.0 and later, below 1.3.0 |
1.2.0 | 1.2.0 alone |
If any of them cannot be installed, none is, and the window says why.
Installing, updating, reverting or removing a package changes the game's code, so the editor builds the game's scripts again at once.
The Store
The Store is the packages of abyssengine.net, the most downloaded first. Type in its search box, and it searches once you stop typing. It shows 50 at a time, and More under the list shows the next ones. Each row says what the package costs (Free, a price, or Owned), or the version the game has.
The package you pick shows its icon, name, publisher, description, Price, Downloads, the Engine versions it is made for and what it Needs. Pick a version, then:
- Get, for a free package you do not own yet, adds it to your My Assets on the website and installs it in the game.
- Install, for a package you own or one of the engine's, installs it.
- A paid package is bought on the website. Click Open on Website, buy it there, then come back and click Install.
- A package the game has already is changed to another version under In Project, as Update or go back says.
The version and each package it needs that your registry does not have are downloaded into your registry, each file checked against the size and SHA-256 hash the website signed, and installed from there. A free package it needs is added to your My Assets too. A paid one it needs stops the Get and says which.
You need to be signed in for anything but the engine's own packages. Signed out, the Store shows what anyone can see, and its button reads Sign In to Get. Sign in with Sign In at the right end of the editor's menu bar; see Sign in.
Update or go back
- Pick one of the game's packages under In Project or Updates.
- Open the version list under Export... and Remove.... It lists every version your registry and the website have, newest first, with the one the game has marked (installed). A package with no other version has no list.
- Pick another version, then click Update to it, or Go Back to an older one.
A version only the website has is downloaded into your registry first, with what it needs. Where you changed none of the files that version changes, the update is done at once: the files you changed that it leaves alone are kept, and the Logs panel says what it took.
Where you changed a file that the new version changes too, or the update would break something, the Update Package window asks first. It shows a tree of what the version changes, each file New, Updated or Deleted (struck through). A file you changed too says you changed it too and starts unticked. What is ticked is taken from the new version, and what is not stays as you have it; package.json, which holds the version, is always taken. All and None tick or untick everything. Your own copies of files taken over your changes go to the Recycle Bin (the Trash on macOS and Linux).
A version that needs a package the game does not have, or has at too old a version, says to install or update that one first. The window also says when another of the game's packages needs other versions of this one, or when the version is made for another engine.
Remove a package
Pick one of the game's packages and click Remove.... Before anything is removed, the window lists what uses the package:
- files that name its files or components, such as a scene or a prefab;
- packages that need it;
- scripts that name its namespace;
- Rust crates that name its crate.
It also says what cannot be got back: a version your registry does not have, which nothing can install again (export it first to keep it), or a copy you changed since it was installed. Click Remove, or Remove Anyway where something uses it. The package's folder goes to the Recycle Bin (the Trash on macOS and Linux), and a package your registry has stays picked, to install again.
A code editor with the game open does not stop a removal. A program that holds one of the package's files open does: the window names it, and the package is left as it was.
A package changed here
You can edit a package's files in the game as you edit the game's own. The game's copy remembers the hash of every file it was installed with, in package.files.json beside its package.json, so the editor knows what you changed. A changed package has an amber dot after its name in the Package Manager and in the Project panel's switch, and its Changed here row counts the files changed, added and gone.
Revert to Original... puts the package back as your registry has its version. It first lists each file it will write back, take out or restore. Your versions of the files it writes back or takes out go to the Recycle Bin. A package made in this game has no original to go back to, and a version your registry does not have cannot be put back.
The game's list of packages
A game lists its packages in settings/packages.json, which you keep in version control with the game. It gives each package's version and where it came from: abyss for the engine's own, assets for one from your registry, and project for one made in the game.
{
"abyssPackages": 1,
"packages": {
"abyss.physics3d": { "version": "0.15.0", "from": "abyss" },
"acme.demo": { "version": "0.1.0", "from": "project" }
}
}The Package Manager writes the list as it installs, updates, removes, makes and exports a package. A package it finds in the packages folder that the list does not name is added to it.
Every build puts the packages back
Every build of the game reads the list first: the editor's as it opens the game, and dotnet build or Visual Studio's alike.
- A listed package missing from the
packagesfolder is written out of your registry, each file checked against its hash. - An engine package nobody changed is moved to the version the list says, as a teammate's update leaves it.
- A copy you changed is kept as it is. The build warns, and the Package Manager's Listed row shows the version the list has.
- A version your registry does not have is downloaded into it from abyssengine.net first, with the sign-in your computer keeps for the editor and the Hub. The engine's own packages download even when you are signed out.
What a build put back or downloaded is said in the Logs panel. A version that neither your registry nor the website has stops the build and says which. The Package Manager lists that package under Missing, and Take Off the List removes it from settings/packages.json.
These settings change where a build looks. Each is an environment variable, or a property given to dotnet build:
| Variable | Property | What it does |
|---|---|---|
ABYSS_REGISTRY | -p:AbyssRegistry=<folder> | The registry to put packages back from, in place of the one Preferences names |
ABYSS_REGISTRY_TOKEN | -p:AbyssRegistryToken=<token> | An access token with the Read scope, for a build server, which has no sign-in of its own |
ABYSS_SITE | -p:AbyssSite=<address> | Another website to download from |
ABYSS_OFFLINE | -p:AbyssOffline=true | Downloads nothing |
Make an access token on the Access tokens page of your account on abyssengine.net.
Packages in version control
So that git can leave out what every build puts back, the editor writes packages/.gitignore and keeps it up to date as the game's packages change. It leaves out each engine package as it was installed. Change one file of an engine package and that package is kept in git from then on; put it back as installed, and it is left out again. A package from your registry, or one made in the game, is always kept, since a registry on another computer may not have it.
Where git still tracks a package that is now left out, the editor untracks it (git rm -r --cached) and leaves its files where they are, so your next commit takes it out of the repository. The game's own .gitignore is never touched.
The registry
Your registry is a folder holding every version of every package as its author made it, one file each: acme.physics/1.2.0.abypackage. Installing copies from it, Export writes into it, and the Store downloads into it, so it is also the editor's cache of what it downloaded. A registry never changes when you edit a game's copy of a package.
The registry is your own folder unless you choose another, such as a folder your team shares. Choose it in Edit ▸ Preferences... under Packages: Browse... picks a folder, and Use Default goes back to your own, %LOCALAPPDATA%\AbyssEngine\Registry on Windows.
Add from File... copies a package's .abypackage file, one somebody sent you or you downloaded, into your registry. Every file in it is checked against its hash first. The package is then listed under My Assets, ready to install.
Packages in the Project panel
When the game has packages, a switch at the left of the Project panel's bar picks whose folders the panel shows: the game, or one of its packages, each listed with its version. Rest the pointer on a package to see its id and description.
A package's folders are browsed, imported and edited as the game's are: its assets, scripts and shaders, and its rust, web and native folders where it has them. Each file's sidecar is kept in the package's folder. A package's models, materials and images go onto entities as the game's do, and a material picks a package's shader from the same list. In the native folder, each library says which platform it is built for. A folder of packages that is not a package is reported in the Logs panel and left out.
A package's addressable files and shaders have keys of their own, such as Acme.Demo.Addresses.Materials.Stone; see Packages' assets.
A package's components appear in Add Component under their namespace, and the Inspector shows that namespace at the right of the component's header.
The engine's own packages
The engine's own packages come with the editor, which puts them into your registry as it starts, so the Package Manager lists them under Abyss Registry as it lists any other. They install without signing in.
| Package | Id | What it is |
|---|---|---|
| Physics 2D | abyss.physics2d | 2D physics on Box2D. See Physics 2D. |
| Physics 3D | abyss.physics3d | 3D physics on Jolt Physics. See Physics 3D. |
| Navigation | abyss.navigation | Navigation meshes and the agents that walk them, on Recast & Detour. See Navigation. |
A new game from the 3D template has Physics 2D and Physics 3D, and one from the 2D template has Physics 2D.
Ids that start with abyss. belong to the engine: New Package and Export refuse them. A copy of an engine package that you changed stays in the game and is kept in git.
In the Scripting API
- PackageManifest: what a package's
package.jsonsays. - PackageVersion: a package's version, and the ranges a dependency is given in.
- PackageList: the packages a game lists in
settings/packages.json. - PackageRegistry: the folder of packages a game installs from.
