Manual
Manual
Making a package
A package carries assets, code and shaders from one game to others. This page covers making one, the folder it is and its package.json, its C# and the NuGet packages it uses, its Rust, native libraries and web scripts, what it can add to the editor, and how to export it, share it and publish it on abyssengine.net. To install and manage packages, see Using packages.
Make a package
- Open Window ▸ Package Manager and click New Package at the bottom.
- Type its Id: your name as its maker, then the package's own, joined by a dot, such as
acme.demo. An id is two or more words of lowercase letters, digits and hyphens, each starting with a letter. - Type its Name, as a person reads it, such as Acme Demo. Left empty, the name is the id.
- Click Create.
The editor makes packages/acme.demo in the game, with empty assets, scripts and shaders folders and a package.json at version 0.1.0, made for the version of the engine your editor runs. The game's list names it as made in the game ("from": "project"), and the Package Manager picks it. Pick it in the Project panel's switch to work in its folders.
An id that is one word alone is refused, as is an id starting with abyss., which belongs to the engine's own packages.
The package folder
| Path | What it holds |
|---|---|
package.json | What the package is: see package.json |
assets/ | Its models, images, sounds, materials, prefabs, scenes and other assets, each with its sidecar |
scripts/ | Its C# |
shaders/ | Its shaders |
rust/ | Its Rust crate, if it has one |
native/ | Its native libraries, a folder for each platform, if it has any |
web/ | Scripts for the page a web game plays on, if it has any |
README, CHANGELOG, LICENSE | Notes about it, any file at its top whose name starts with one of these |
That is everything a package carries. Nothing else beside these is exported or installed, and neither is any file or folder whose name starts with a dot.
The editor writes two more files into a package. An installed copy keeps package.files.json, the hash of every file it was installed with, which is how the editor knows what was changed in it. And each build writes the package's C# project, which is never carried with the package and is left out of git.
A package's files are named after its id wherever the game refers to them: acme.demo://models/rock.glb is packages/acme.demo/assets/models/rock.glb, and a shader acme.demo://noise.wesl is packages/acme.demo/shaders/noise.wesl, which its other shaders import as package::noise and the game's as acme_demo::noise.
package.json
{
"abyssPackage": 1,
"id": "acme.demo",
"displayName": "Acme Demo",
"version": "1.2.0",
"description": "Rocks, a wobble and a noise shader.",
"author": { "name": "Acme Games", "url": "https://acme.example" },
"copyright": "© 2026 Acme Games",
"license": "MIT",
"engine": "^0.1",
"category": "Art",
"keywords": ["rocks", "noise"],
"dependencies": { "abyss.physics3d": "^0.15.0" },
"nuget": { "CommunityToolkit.HighPerformance": "8.4.0" }
}| Field | What it says |
|---|---|
abyssPackage | That the file is a package's, and which version of the format: 1. A package.json without it is not taken for a package. |
id | The package's id. Required. The package's folder has this name, or it is not read as a package. |
displayName | Its name, as the Package Manager and the Project panel show it. Its id where it gives none. |
namespace | The C# namespace of its code. Where it gives none, the id spelled as a namespace: acme.demo is Acme.Demo, and acme.fx-pack is Acme.FxPack. |
version | Its version, major.minor.patch, with a pre-release after a hyphen if it is one: 1.2.0, 2.0.0-beta.1. Required. |
description | A line on what it is |
author | Who made it: a name, or an object with name, url and email |
copyright | Whose it is |
license | What may be done with it: an SPDX name such as MIT or Apache-2.0, or Proprietary |
engine | The engine versions it is made for, as a range: ^0.1 |
dependencies | The other packages it needs, each by its id and the range of versions that will do |
nuget | The NuGet packages its code uses, each at one exact version. See NuGet packages. |
native | What its native libraries are built from. See Native libraries. |
category | What kind of package it is: Physics, Art, Tools |
keywords | Words it is found by, as the Package Manager's search finds it |
documentation | Where it is documented |
A package.json the editor cannot read, or a field it cannot take, such as a version that is not three numbers, leaves the package out, and the Logs panel says why.
Versions and ranges
A range in engine or dependencies is written as npm writes one:
| Range | Versions it takes |
|---|---|
^1.2.0 | From 1.2.0 up to, not including, 2.0.0. Below 1.0 it stops at the next minor version: ^0.2.0 takes 0.2.x. |
~1.2.0 | From 1.2.0 up to, not including, 1.3.0 |
1.2.0 | 1.2.0 alone |
A part left out is zero, so ^0.1 is ^0.1.0. A pre-release version is taken only by a range that names a pre-release of the same three numbers.
Raise the version as its parts mean: the patch for a fix, the minor version for something added, and the major version for a change that breaks what used the package.
Its C#
The code in a package's scripts folder is built into an assembly of its own, named as its namespace: Acme.Demo.dll. The project that builds it is written by the engine from package.json each time the game builds, as packages/acme.demo/Acme.Demo.csproj, so a package carries no project. That project references the packages its dependencies name, so its code can use theirs, and the game references every package. Beside the game, <Game>.slnx lists the game's project and every package's, for your code editor to open.
Every type of a package is in its namespace or one inside it; a type outside it is a build error (ABYSS027). In the Project panel, a script made in a package's scripts folder starts in the package's namespace.
A package declares components, systems, plugins, settings, data assets and UI documents as a game does; see C# in a game. Its plugin is named once in its assembly:
using Abyss.Core;
[assembly: AbyssPlugin<Acme.Demo.DemoPlugin>]
namespace Acme.Demo;
[AbyssComponent(Page = "https://acme.example/docs/wobble")]public partial struct Wobble{ public float Height = 0.25f; public float Speed = 2f;}
public sealed class DemoPlugin : IPlugin{ public void Build(Schedule schedule) { World world = schedule.World; // Add the package's systems here. }}The game registers each package's components before its own, and each package after the packages it needs. A package's plugins are built before the game's, in the editor and in a built game.
Components are named in full, so this one is Acme.Demo.Wobble in every scene, prefab, clip and animator condition that uses it. The Inspector heads it Wobble with Acme.Demo on the right, and Add Component lists it under its namespace. Page gives the address its ? opens; a component that names none has no ?.
A package's addressable assets, labels and shaders have keys of their own, public so the game's code can use them: Acme.Demo.Addresses.Models.Rock, Acme.Demo.Labels.Rocks, Acme.Demo.Shaders.Noise. A package's code loads by keys, as a game's does; loading by a string is the build error ABYSS026. See Keys in code.
Add to the editor
A package's [EditorOnly] plugins help whoever edits a game that uses it. What they put in the editor's menus goes under the package's name:
schedule.ToolsMenu("Rocks/Scatter", ...)adds Tools ▸ Acme Demo ▸ Rocks ▸ Scatter. Whatever it changes is one step of the undo.schedule.EntityMenu(...)adds a kind of entity to the Entity menu and the Hierarchy's + menu.schedule.ComponentMenu<T>(...)adds an item to a component's menu in the Inspector. The Navigation package's Bake and Clear on a navmesh surface are two.schedule.EditorWindow(...)adds a window to the Window menu. The Navigation package'sschedule.EditorWindow<NavigationView>("Navigation", Draw)is Window ▸ Navigation ▸ Navigation.
See Plugins for the other things an [EditorOnly] plugin can do.
NuGet packages
A package uses NuGet packages by listing them in package.json, each at one exact version, which its project references. So it builds the same wherever it is built.
"nuget": { "CommunityToolkit.HighPerformance": "8.4.0" }A range or a floating version, such as [8.0,9.0) or 8.*, stops the build at the manifest. Where two packages ask for one NuGet package at different versions, NuGet settles it as it does for any project. What the NuGet packages carry is copied beside the game as it builds, where the editor loads it from, and goes into the built game.
A built game is compiled ahead of time by NativeAOT. A NuGet package that NativeAOT cannot vouch for, for trimming or for compiling ahead of time, does not stop the build: the build notes say so, naming the package, and so does the Logs panel. Every NuGet package the game carries is listed in the THIRD-PARTY-NOTICES.txt beside it, with its license.
A game's own project takes a PackageReference as any .NET project does.
Its Rust
A package can have a Rust crate in its rust folder. Pick the package in the Project panel's switch and choose Rust Crate in the + menu to make one. A package's crate is carried as source and compiled on the computer that builds the game, linked with the engine and the game's own Rust. See Rust in a game.
Native libraries
A package can carry native libraries built from C, C++ or any language, which its C# calls by name, so the computer that builds the game needs no compiler for them. They go in its native folder, a folder for each platform:
| Folder | Platform | Library |
|---|---|---|
native/win-x64 | Windows | box2d.dll |
native/linux-x64 | Linux | libbox2d.so |
native/osx-arm64 | macOS on Apple Silicon | libbox2d.dylib |
native/wasi-wasm | The web | libbox2d.a, a static library |
using System.Runtime.InteropServices;
namespace Acme.Physics;
internal static partial class Box2D{ [StructLayout(LayoutKind.Sequential)] public struct Version { public int Major; public int Minor; public int Revision; }
// box2d.dll on Windows, libbox2d.so on Linux, libbox2d.dylib on macOS. [LibraryImport("box2d", EntryPoint = "b2GetVersion")] public static partial Version GetVersion();}The game's build copies the libraries for its own computer beside the game, and a build copies those of its platform beside the executable. The editor loads each from a copy of its own, so you can rebuild the game with the editor open, and a new library loads without a restart. A web build links each native/wasi-wasm/lib<name>.a into the game; a package with native libraries but none for the web stops a web build and says which.
Say in package.json what the libraries are built from, so the notices beside a built game carry each with its license:
"native": [{
"name": "Box2D",
"version": "3.1.1",
"license": "MIT",
"url": "https://github.com/erincatto/box2d",
"licenseFile": "native/LICENSE-Box2D.txt"
}]name, version and license are required. licenseFile is a file in the native folder; without one, the license's standard text is used.
The Project panel shows a package's native folder once it has a file in it, and each library says which platform it is for.
Its web scripts
A package can carry scripts for the page a web game plays on, in its web folder, as an ad network's or a game portal's calls would need. A new package has none: pick the package in the Project panel's switch and choose Web Script in the + menu to make the folder and its first script. See A package's scripts.
Export a version
Export writes one of the game's packages into your registry as a version, for other games to install.
- In the Package Manager, pick the package under In Project.
- Click Export....
- The window offers the next patch version, or the package's own version where your registry does not have it yet. Type another, or raise it with Patch, Minor or Major.
- Click Export.
The version is written into the package's package.json, and the package is written into your registry as acme.demo/1.2.0.abypackage. The game's copy keeps the hash of every file as it was exported, so from then on the editor marks what you change in it. A version your registry has already is never written again: give the next one another version. The engine's own packages cannot be exported.
An .abypackage file is a zip of what the package carries and the SHA-256 hash of each file, which every install checks. Any zip tool opens it.
Share a package
- Send the file. Give someone the
.abypackagefrom your registry folder. They add it to theirs with Add from File... in the Package Manager, and install it from My Assets. - Share a registry. Point everyone's Edit ▸ Preferences... ▸ Packages ▸ Registry at one folder, such as a network drive. What one person exports, everyone can install.
- Keep it in the game. A package made in the game, or installed from your registry, is always kept in git, so a teammate gets it with the repository.
A game whose settings/packages.json names a version that the building computer's registry lacks gets it from abyssengine.net, if it is published there; see Every build puts the packages back.
Publish on abyssengine.net
A package published on abyssengine.net can be found in every editor's Store and put back by any build. The editor has no button for this yet: a version is uploaded through the website's API.
- A publisher. Every package on the website belongs to a publisher, whose name is the first word of the package's id:
acmeforacme.demo. Nobody else can publish under that name. Your account gets a personal publisher on its first upload, and you can make a team publisher on the Publishers page of your account. A publisher's name is 2 to 32 lowercase letters and digits, starting with a letter. - A token. On the Access tokens page of your account, make a token with the Publish scope for that publisher.
- Upload, then publish. Upload the
.abypackagethat Export wrote, as a draft, then publish it. Uploading the same version again replaces its draft. A published version never changes.
curl -H "Authorization: Bearer $TOKEN" -F "File=@acme.demo/1.2.0.abypackage" -F "ReleaseNotes=Rocks cast shadows." https://abyssengine.net/api/v1/packages/acme.demo/versions
curl -X POST -H "Authorization: Bearer $TOKEN" https://abyssengine.net/api/v1/packages/acme.demo/versions/1.2.0/publishThe website checks an upload as the editor checks a package. A package starts Private, seen only by its publisher's owners and admins: on a personal publisher, only you. Internal shows it to every member of the publisher, and Public lists it in the Store for everyone once it has a published version. Making a package Public, or publishing a version of a Public package, waits until the website's malware scan finds it clean. Private and Internal packages are never scanned.
curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"visibility":"Public","price":null,"currency":null}' https://abyssengine.net/api/v1/packages/acme.demoIn the Scripting API
- PackageManifest: what a package's
package.jsonsays. - PackageVersion: versions, and how a range takes them.
- PackagePath: how a path names a package's file.
- Schedule.ToolsMenu and Schedule.EditorWindow: what a package adds to the editor.
- EditorOnlyAttribute: a plugin the editor runs and a built game never does.
