Manual

Manual

Assets, identities and addresses

Assets are the files your game is made of: models, images, sounds, materials, scenes and prefabs. This page covers how the editor keeps track of each file, imports it into the form the engine uses, and packs it into a build, how your code finds assets by typed keys, and how a component names an asset or another entity.

The assets folder

A project's assets/ folder holds everything the game ships that is not code. Beside it are scripts/ for the game's C#, shaders/, settings/ for the project's settings as JSON files, and packages/ (see Packages' assets). The editor makes cache/ for what it imports and builds/ for what it builds.

The Project panel shows assets/, with scripts/ and shaders/ beside it. What another program changes on disk, such as an image saved from a paint program, shows up there by itself.

KindFiles
Images.png, .jpg or .jpeg, .bmp, .tga, .webp
Models.gltf, .glb, .fbx, .obj
Sounds.wav, .ogg, .mp3, .flac
Scenes and prefabs.scene, .prefab
Materials.mat
Animation.anim clips, .controller animator controllers
Interface.ui documents, .css style sheets

Sidecars and identities

Next to every file and folder in your assets, the editor writes a sidecar: a small JSON file with the same name and .abyss added, such as abyss_logo.png.abyss. The Project panel hides sidecars, but keep them in version control with their files. Each holds the file's identity, guid, 32 hex digits made once and never changed; its import settings under import, where they differ from the defaults; and its address, labels and group once you make it addressable.

{
  "version": 3,
  "guid": "6d33cf113bfc4cd183855291b38be3c0",
  "import": {
    "filter": "bilinear",
    "wrap": "repeat",
    "compression": "lowquality",
    "maxSize": 256,
    "aniso": 6
  }
}

A path says where a file is today. An identity says which file it is, wherever it goes. Scenes and prefabs write both for every file they use, a material file names its images and its shader by identity, a PrefabRef field holds one, and the keys your code loads by look for the identity first.

Moving, renaming and copying

Move or rename files in the Project panel, and the sidecar goes with the file, so every scene, prefab, material and key that uses it keeps working. If you move a file with another program, such as your file manager or git mv, move its .abyss file with it: a file that arrives without a sidecar is a new file to the editor, with a new identity.

A copy, made with Ctrl+D or copy and paste in the Project panel, keeps the original's import settings under an identity of its own.

Importing

Source files stay as you made them. The editor imports what the engine uses from them into the project's cache/ folder: textures with their mipmaps and compression, models' meshes, and sounds re-encoded where you ask for it. The Project panel does not show cache/, and a .gitignore inside keeps it out of version control. If you delete it, the editor imports everything into it again.

A texture or a model is imported again only when its source file, its settings or the importer's version changes. Imports run in the background: the editor stays usable, the file's tile in the Project panel shows a spinner, the status bar counts what is left, and the scene swaps in the new import as it lands.

Pick a file in the Project panel and the Inspector shows its import settings, with Apply and Revert under them. Settings you changed and did not apply are asked about before the Inspector shows something else, and before you quit. Pick several images, or several models, to change their settings together: a dash marks a setting where they differ.

Textures

A texture nobody has configured gets mipmaps, a Max Size of 2048, bilinear filtering, repeat wrapping and Normal Quality compression. Its settings are in four sections:

  • Texture: Texture Type (Default, Normal Map, Sprite (2D and UI) or Single Channel) and sRGB (Color Texture). Picking a type sets the settings it starts with; a sprite has no mipmaps and clamps.
  • Mipmaps: Generate Mipmaps and Mipmap Filtering (Box or Kaiser).
  • Sampling: Filter Mode (Point, Bilinear or Trilinear), Aniso Level and Wrap Mode.
  • Size and Compression: Max Size and Compression (None, Low Quality, Normal Quality or High Quality).

The preview under the settings shows the import itself, so you see what compression did. A change of filter or aniso level applies without importing again.

Models

Models are glTF (.gltf or .glb), FBX or OBJ files. Every model is imported in meters with +Y up: an FBX file authored +Z up in centimeters arrives upright and at its size, and an OBJ file, which says nothing of its units or axes, is read as meters with +Y up. Each model's meshes are imported into one .abymesh file in the cache, and the editor makes the model's prefab from its nodes; see Models are prefabs.

  • Scene: Scale Factor, Bake Axis Conversion and Preserve Hierarchy.
  • Geometry: Index Format, Normals (Import, Calculate or None), Smoothing Angle while normals are calculated, and Tangents.
  • Animation: Import Animation, the clips the file holds, and Skeleton, the model that clips exported on their own are for.
  • Materials: a slot for each material the model has. Drop a material file on one to draw the model with it, or click Extract Materials to write each as a .mat file in a Materials folder beside the model and edit them as any material.

A model's tile in the Project panel has an arrow that unfolds its meshes, materials, clips and skeleton beside it. Drag a part onto a slot that takes it, such as a mesh onto a Mesh slot or a clip onto an animator state's Clip slot.

Sounds

Sounds are WAV, OGG, MP3 or FLAC files. Load Type says how a clip is kept once loaded: Decompress On Load, the default, Compressed In Memory, or Streaming for music and other long clips. Compression Format is As Encoded by default, which plays and packs the file as it is; Vorbis (with a Quality), ADPCM or PCM imports it into the cache in that encoding. Force To Mono mixes its channels into one, and Sample Rate Setting can resample it to a lower rate as it is imported.

Addresses and labels

Most assets reach a game through its scenes: a build takes the scenes ticked in File ▸ Build Settings... and everything they use, and the prefab every PrefabRef field names. An asset your code loads by name has to be Addressable.

Tick Addressable under the asset's name in the Inspector. Its address starts as its path, which you can type over with any name that has no # in it, or click Simplify to make it the file's name. Under it, give it Labels, to load several assets together: + Label lists the project's labels to tick, with a box to type a new one and press Enter, and the cross on a label takes it off. The address and labels are kept in the sidecar as you change them, so they survive moves and renames, and nothing is imported again. If two files have the same address, the first by path keeps it, and the Inspector says so in amber.

A folder can be ticked too. Every file inside it is then addressable by the folder's address and its path inside, such as enemies/grunt.prefab, with the folder's labels and group. The Inspector of a folder lists the files inside it by their addresses. A file inside a ticked folder shows its own Addressable row grayed, ticked through the folder: untick the folder, or move the file out of it, to address the file on its own.

Groups

Each group is a pack the build writes. Default goes into game.abypack with the build's scenes, so it is where whatever must ship with the game goes. Any other group is built into its own pack, named after it in lowercase letters and digits: Level 2 is level2.abypack. Put an asset in a group with the Group list in its Inspector, under its labels. The groups are kept in settings/addressables.json.

A group can be an add-on: a pack that does not ship with the game, which the game attaches once it has it. That covers DLC a store installs, a pack downloaded later, or one a player was given. See Add-ons.

The Addressables window

Window ▸ Addressables lists every addressable asset, by group.

  • Along the top are New Group, Build Packs, which writes every pack again without building the executable (see Packs), and a search box that finds assets by address, file, label or group. Beside them, the window counts the groups and the addressable assets.
  • Each group is a band with its name, and its pack on the right: main pack · game.abypack for Default, add-on · level2.abypack for an add-on. Click a band to fold it away.
  • Each row shows an asset's address, its file and its labels. An address another file has too is amber. A ticked folder's row has its files under it, grayed, as they go where it goes.
  • Click a row to show its file in the Project panel, where its Inspector changes it.
  • Drag a row onto another group's band to move it there, or drag files from the Project panel onto a band, which ticks them Addressable in that group.
  • Right-click a band for New Group, Rename, Add-on and Delete. Add-on ticks the group as an add-on, or ships it with the game again. A deleted group's assets go to Default, which cannot be renamed, deleted or made an add-on.

Under the buttons, a line says how the last pack build went: how many packs, their size and where they went.

Keys in code

Your code never loads an asset by a string. The build writes a key for each addressable asset into your game's code, and the editor updates the keys as you tick, untick or re-address assets. Addresses has a nested class for each folder of an address and a key for each file, named without its extension; Labels has a key for each label; and Shaders a key for every shader in the game's shaders/ folder, addressable or not.

AddressKey
pyramidAddresses.Pyramid
scenes/moons.sceneAddresses.Scenes.Moons
A clip Run of characters/fox.glbAddresses.Characters.Fox.Run
A mesh Frame of models/door.gltfAddresses.Models.Door.Meshes.Frame
A material Wood of models/door.gltfAddresses.Models.Door.Materials.Wood

A key is its address written as a name, each word starting with a capital: main menu is MainMenu, frames_angle_0 is FramesAngle0, and a name that would start with a digit has an underscore first, _16. Where a name is taken, by a folder's class or by a file before it whose name differs only in its extension, the file's kind comes after it: beside the material coin.mat, the image coin.png is CoinImage. A model's meshes are the parts drawn with one material each: a mesh drawn with one is named as the mesh is, Frame, and the parts of one drawn with several by the mesh's name and each material's, BodySkin and BodyCloth.

Each key has the type of its asset, such as PrefabAddress, SceneAddress or ClipAddress, so passing a clip where a prefab goes does not compile. A key finds its file by identity first and then by address, and a key whose asset went away is a build error on the line that uses it. An addressable asset's Inspector shows its key under its Group, ready to copy.

Loading by a string, anywhere in your game's or a package's code, is the build error ABYSS026. Its message names the key you most likely meant, or why there is none: a file not ticked Addressable, a clip its model does not have, or a label nothing carries.

To keep an asset in your game's own data, such as the sword in a save file, keep its key's identity and make a key of it again when you read it back:

AssetGuid kept = Addresses.Swords.Long.Id;                                // written into the savePrefabId sword = context.Assets.LoadPrefab(PrefabAddress.FromId(kept));   // read back, wherever the file is now

Load assets from code

Systems load assets through context.Assets and scenes through context.Scenes; flows use flow.Assets and flow.Scenes. See C# in a game for systems and flows.

PrefabId enemy = context.Assets.LoadPrefab(Addresses.Enemy);ClipId run = context.Assets.LoadClip(Addresses.Characters.Fox.Run);MeshId frame = context.Assets.LoadMesh(Addresses.Models.Door.Meshes.Frame);MaterialId wood = context.Assets.LoadMaterial(Addresses.Models.Door.Materials.Wood);ShaderId glow = context.Assets.LoadShader(Shaders.Glow);IReadOnlyList<PrefabId> wave = context.Assets.LoadPrefabs(Labels.Wave1);SceneId level = context.Scenes.Load(Addresses.Levels.First);

Each load returns an id at once and the asset arrives in the background. The ids are plain numbers that you can keep in components and resources. context.Assets.StateOf(id) says whether it is Loading, Loaded or Failed, and a flow can wait for it:

PrefabId boss = flow.Assets.LoadPrefab(Addresses.Boss);if (await flow.Loaded(boss) == AssetState.Loaded) { /* ready to instance */ }

Loads are counted. Loading an asset that is already loaded gives the same id and holds it once more, Release gives one load back, and the asset is unloaded once nothing holds it. A model's material key loads what the model is drawn with: the material file its Materials section gives it, or the model's own. For scenes and prefab instances, see Scenes and prefabs.

References in components

A component names an asset or another entity with a reference field, which the Inspector shows as a slot. Drop a file on it from the Project panel, or an entity from the Hierarchy, or click the button beside it to pick one from a list, None first. A click on a slot that holds a file shows that file in the Project panel, and a double-click picks it there. With several entities picked, a slot is set on all of them as one change.

A reference to a file holds the file's identity, not its path, so moving or renaming the file never breaks it. A reference to an entity is saved by the identity the scene gives that entity, so it names the same one each time the scene loads.

FieldWhat it namesWhat the slot takes
PrefabRefA prefabA .prefab or a model
EntityRefAnother entityAn entity of the scene
AssetRef<T>A data asset of the kind TA .asset file of that kind
FileRefA file of a kind the engine does not read itselfFiles with the extension its [FileKind] names

PrefabRef

[AbyssComponent]public partial struct Spawner{    public float Every;    public PrefabRef Enemy;   // a slot that takes a prefab or a model}
PrefabId enemy = context.Assets.LoadPrefab(spawner.Enemy);

Holding a PrefabRef loads nothing: LoadPrefab does, as Instance prefabs from code shows. A scene writes the field as the file it names, "Enemy": { "prefab": "prefabs/enemy.prefab", "guid": "…" }, and finds the file by that path should its identity be lost. A build packs every prefab a PrefabRef names, addressable or not, and a built game finds it through its pack's catalog.

EntityRef

[AbyssComponent]public partial struct Follower{    public float Speed;    public EntityRef Target;   // a slot that takes an entity}
if (!follower.Target.IsNone){    ulong target = follower.Target.Entity;}

Drag an entity onto the slot from the Hierarchy, or click its button to pick one of the scene's entities, listed as the Hierarchy has them, with a search box. Click the slot to see the entity it names in the Hierarchy.

The field holds the entity's number in the world, which only means something while the game runs, so a scene writes the identity the scene gives that entity instead, "Target": { "entity": 4128 }, and a load names the same entity whatever its number is then. In a prefab, each instance names its own parts: a wheel joined to its car's body names the body of its own car. A reference from outside an instance to a part inside it is saved where the scene can tell that part apart; where another instance of the same prefab has a part with the same identity, it is saved as naming none, and the log says so.

The field keeps naming the same entity when the editor brings entities back with new numbers: at Stop, when an undo puts back a deleted entity, and when an instance is built again because its prefab changed. Duplicate several entities that name each other, and the copies name each other's copies.

AssetRef

An AssetRef<T> names a data asset of the kind T, a struct marked [DataAsset] (see Data assets declared in code). Its slot takes only assets of that kind.

[AbyssComponent]public partial struct Wielder{    public AssetRef<Weapon> Held;}
Weapon weapon = context.Assets.Data(wielder.Held);   // read the first time, then kept

Data returns a copy of the asset's struct, read the first time it is asked for, from the game's pack or from the file. TryData returns false where the field names nothing that can be read. A build packs every data asset of the game into the main pack, unless an Addressables group holds it, along with what its own references name.

FileRef

A FileRef names a file the engine has no kind of its own for, such as one a package bakes and reads back itself: the Navigation package's navmeshes are .abynav files. [FileKind] says which files its slot takes:

[AbyssComponent]public partial struct Level{    [FileKind(".layout")]    public FileRef Layout;}
byte[] bytes = world.ReadFile(level.Layout);

world.ReadFile reads the file as it is, from the pack the game plays from, or from the project's folders while the game is edited or played from them; TryReadFile returns false where it names nothing the game has. A built game's pack carries every file a scene's reference reaches. In the editor, an [EditorOnly] plugin writes such a file under the assets with world.SaveAssetFile("levels/first.layout", bytes), which returns a FileRef to it; the file keeps its identity when it is written again.

Packs

A built game reads its assets from packs, not from folders. Build in File ▸ Build Settings... writes them beside the executable, and Build Packs in Window ▸ Addressables writes them again without building the executable. Each asset goes in as the engine keeps it: textures and meshes as imported, materials packed, shaders compiled ahead of time, and scenes and prefabs as binary images.

  • game.abypack holds the scenes ticked in Build Settings and everything they reach (meshes, materials, images, the prefabs they instance and the prefabs PrefabRef fields name), the Default group's addressable assets, and the game's UI documents.
  • Each other group's pack holds that group's assets and what they reach.
  • A file in no group that two packs need goes into both, and the build says so: give it a group to keep one copy. What nothing reaches and is not addressable is left out, and listed.
  • A scene ticked in Build Settings is always in the main pack, even when another group holds it.
  • An add-on's pack goes into a folder of its own beside the game's, not into it (see Add-ons).
  • A pack an earlier build made for a group that is gone is taken away. A pack beside the others that no build made stays, and the build says that a game playing from there mounts it too.

The build also says what a game could not load: an addressable file in no pack, and an address that two files have, with the one a load finds. Last Build in Build Settings lists each pack, its size and what it holds.

Each pack keeps a catalog of each asset's path, identity, address and labels, so the same keys find the same assets in a built game, with no folders and no sidecars. See Build and run your game.

Every pack beside the executable is mounted as the game starts. Each pack is stamped with your game's identity, which the editor gives a project in settings/project.json the first time it opens it. A pack another game's build made is never mounted, and the log says so.

Add-ons

An add-on is a group whose pack does not ship with the game. The build writes it into a folder beside the game's, such as builds/win64-addons beside builds/win64, so shipping the game's folder never ships it. The same folder gets a list named by the game's Version, such as catalog_1.23.1.json, or catalog.json (see Downloading add-ons), which lists each add-on with its file, its name on the host, its length, its SHA-256 and the addressable assets it holds, so the game can tell which add-on an address needs before it has it. The main pack keeps the same list, so the game knows its add-ons with no file beside it. Upload the folder as it is to wherever players get add-ons. It holds only the current build's add-ons; the ones you uploaded before stay on the host until you delete them.

A string table in an add-on group is built into a pack for each language, so a player downloads only their own language's strings: see Strings players download.

As a game starts, it attaches each add-on it lists that is already on the computer:

  • in an addons folder beside its main pack, where a store installs the DLC a player has;
  • in addons in the player's own folder, where what the game downloads is kept. This one is looked at first.

An add-on another build of the game made is attached too, and the log says it is another build's. A pack in those folders that the list does not name, such as a player's mod, is not attached: that is your code's to decide.

A pack your game gets later is attached from a flow, and can be taken away again; what was loaded from it stays loaded. Check a file against the list before attaching it:

AddOn bonus = flow.Packs.AddOns.First(addOn => addOn.Name == "Bonus");if (!flow.Packs.IsAttached(bonus) && flow.Packs.Check(bonus, file))   // its length and SHA-256 as built{    PackId attached = flow.Packs.Attach(file);                         // relative to the main pack's folder, or a whole path    PrefabId gem = flow.Assets.LoadPrefab(Addresses.Gem);              // found in the add-on    flow.Packs.Detach(attached);}

Attach takes any pack of your game's, listed or not, and refuses another game's with an InvalidOperationException. Loading an asset that only an add-on not yet attached holds writes a warning naming the add-on, and flow.Packs.AddOnOf("gem") tells your code which add-on an address needs.

The build says when a pack that ships needs an asset an add-on holds: the game finds that asset only once the add-on is attached.

Downloading add-ons

Edit ▸ Project Settings… ▸ Add-ons sets where a built game downloads its add-ons from, saved in settings/addons.json:

  • Content Address: one address for every platform, such as https://cdn.example.com/knight/{platform}/. {platform} becomes the name of the platform's build folder (win64, macos, linux64 or web), so builds/win64-addons is uploaded, as it is, to …/knight/win64/. {version} becomes the game's Version from Player settings, for a folder for each version: …/knight/{platform}/{version}/. Hovering the box shows the address as your platform reads it. With no address, the game downloads nothing.
  • File Names: how add-ons are hosted. With Hash, the default, names each build of an add-on by its SHA-256, such as levels_3f9a1c2bd4e5f607.abypack, and writes a list for this version of the game, named by its Version, such as catalog_1.23.1.json. Every version's lists and add-ons sit in one folder, and an add-on two versions share is kept once: a new add-on, or one that needs a newer game, is listed for the versions that should have it, and an older version keeps reading its own. A host's cache can never give a player an old build for a new one; you upload the add-ons before the list that names them, so players see the old set or the new one, never a mix; and putting an older list back brings its add-ons back, as they are still on the host. Plain names them as on the player's computer, levels.abypack, in catalog.json, which every version reads, for a host where you replace files by hand. On the player's computer an add-on keeps its plain name either way, and an update replaces it.
  • Check on Start: the game reads its list at the address in the background as it starts. That list can name an add-on made after the game shipped, or a newer build of one, so new DLC reaches players without a game update. Until it arrives, and offline, the game goes by the list it has: its main pack's, or the newer one it kept from the address last time.

A download goes into addons in the player's folder. Its progress can be read every frame, and the download is awaited from a flow:

await flow.Packs.Checked;                                  // the list at the address, or the one the game hasAddOn castle = flow.Packs.AddOns.First(addOn => addOn.Name == "Castle");long size = flow.Packs.SizeToDownload([castle]);           // for "Download 34 MB?"AddOnDownload download = flow.Packs.Download(castle);// a system or a binding shows download.Progress, from 0 to 1, and download.Received of download.Sizeif (await download == AddOnDownloadState.Attached){    PrefabId tower = flow.Assets.LoadPrefab(Addresses.Tower);}
  • A download that stops (the connection lost, download.Cancel(), the game closed) keeps what arrived, and the next download of the add-on asks the host for the rest. Problem says why one failed.
  • Every download is checked against the list's length and SHA-256 before it is attached. A file that does not match is deleted.
  • flow.Packs.Updates lists the add-ons attached as an older build than the list names. Downloading one puts the new build in the old one's place once it is checked, so only one copy is kept. The old build stays attached until then.
  • flow.Packs.Remove(addOn) detaches an add-on and deletes what the game downloaded of it. One a store put beside the game is only detached.
  • Once the list at the address has been read, a file the game downloaded that no add-on names any more is deleted. A file the game did not download, such as a store's DLC or a player's own pack, is never touched.
  • flow.Packs.CheckList() reads the list again, for a game that looks for new content while it plays.

A game in a browser downloads through the page, with the same calls. Its add-ons are kept in the browser's storage for the site, where its saves are, so the next visit attaches them without downloading them again; a browser may clear that storage when it runs short of space, and the game then downloads them again. Upload builds/web-addons beside the game's page, or, on another address, from a host that allows the page to read it: its answers carry Access-Control-Allow-Origin naming the page's site.

Trying add-ons on your computer

Play gives the game your add-on groups as its add-ons. The Add-ons list in the Game panel's top row, shown when the game has an add-on group, sets how:

  • Attached: every add-on is attached, as the project has them, and a download ends at once.
  • To Download: the game plays as a new player who has none of them. They are listed but not attached, so loading something only an add-on holds finds nothing, by its address, its key or its path, and the log names the add-on. flow.Packs.Checked is true at once. A download takes as long as the add-on's files would take at the Test Server's Speed, then attaches it from the project, so you can try a loading screen by pressing Play. Its size is what a player downloads, as your last build for this computer listed it; before the first build, it is the size of its files and of what their scenes name.

The list is told to the game as Play starts, so it cannot be changed while the game plays.

The Test Server, at the foot of the Add-ons page, serves the game's builds folder on your computer as a host would, at http://127.0.0.1:8790/ (or the next free port). A download cut off goes on from where it stopped, a browser keeps each file and asks whether it changed, and a list of add-ons is never kept, so a new one is seen at once. The Logs panel shows each request.

  • Serve Add-ons: while it is ticked, Build And Run starts the game pointed at the server for its add-ons. A desktop game gets --content http://127.0.0.1:8790/win64-addons/ on its command line, and a web game's page opens with ?content=/web-addons/. This stands in for the Content Address, and the game reads the list there even with Check on Start off. The build keeps your Content Address, so a game you ship never downloads from your computer.
  • Speed: Unlimited, 16, 4 or 1 MB/s. This is how fast the server sends an add-on, and how fast Play downloads one at To Download, for watching a download's progress or trying a slow connection. A web build's own files are always sent at full speed.

Both settings, and the Add-ons list in the Game panel, are kept on your computer, in the project's cache folder, not in its settings. Build And Run for the web always plays the game from this server, whether Serve Add-ons is ticked or not.

Packages' assets

A package is a folder of the game's packages/ folder named by its id, such as packages/acme.demo, with assets, shaders and scripts folders of its own and a package.json that says what it is. Its files stay in its folder, and the engine names each after the package's id: acme.demo://models/rock.glb.

When the game has packages, a switch at the left of the Project panel's bar picks the game or a package. A package's files are browsed, imported and edited as the game's are, each with its sidecar in the package's folder, and its models, materials and images go onto entities as the game's do.

A package's addressable files and shaders have public keys of their own, in the package's namespace, such as Acme.Demo.Addresses.Materials.Stone and Acme.Demo.Shaders.Noise. A build packs a package's files with the game's, so a built game needs no package folder beside it. See Using packages to install packages, and Making a package to make one.

In the Scripting API