Scripting API
Scripting API
AssetDatabase
Class in Abyss.Core, from Abyss.Core.
What every file under the asset root is called, and what it is.
public sealed class AssetDatabaseRemarks
The problem this exists for is that a path is not an identity. Everything a scene writes today names a file by where it is — models/pyramid.gltf#Mesh0/Primitive0 — so moving the model into a subfolder, or renaming it, silently empties every scene that used it. Nothing reports that; the entities load, the meshes do not, and the level is full of invisible things.
Upstream has no answer to lean on here, which is unusual for this engine. Bevy addresses assets by AssetPath throughout. There is an AssetId::Uuid, and its own documentation rules it out — "a stable-across-runs / const asset identifier ... only ... if an asset is explicitly registered in Assets with one" (bevy_asset 0.19.1, src/id.rs:36) — which is a constant for something declared in code, not a record of what is on disk. So this part is the engine's own.
Why the identity is not kept in Bevy's .meta file
It would work. Bevy's meta is RON through serde with no deny_unknown_fields anywhere in the crate, so a field it does not know is ignored; and every path that writes a source meta refuses when one already exists, so ours would not be rewritten away.
The cost is that keeping one field in Bevy's .meta means writing the whole of that file, and that file decides how the asset loads. When a meta exists Bevy picks the loader by the type-name string inside it (bevy_asset 0.19.1, src/server/mod.rs:1606) rather than by extension, so every asset would be pinned to a path like bevy_image::image_loader::ImageLoader and an upstream rename would break the project. A meta that fails to parse is a hard load failure (src/server/mod.rs:1587) and meta files are read by default (src/lib.rs:321), so one malformed file means one asset that does not exist. And meta_format_version is upstream's to change (src/meta.rs:19), which would make each change to Bevy's schema a migration of every project's files.
So the sidecar here is the engine's own, and is deliberately not called .meta — Bevy reads a file of that name whatever the engine wants. It holds an identity and, since version 2, how the file is to be read; and, for a file a game loads by an address, that address and its labels (AssetDatabase.AddressOf).
Why the settings live here rather than at the call site
Because there has to be exactly one answer per file. Bevy deduplicates a load by path: a second load of a file already in flight returns the first handle and the second set of settings is never applied (bevy_asset 0.19.1, src/server/mod.rs:1955). Settings passed per call would therefore be a race between call sites, decided by whichever ran first and silent when it went wrong. Settings read from the file cannot race, because every caller reads the same sidecar — and x.gltf#Mesh0/Primitive0 and x.gltf#Material0 are two loads of one file, so this is not a hypothetical.
What it does not do
It does not watch, cache or process anything. It is a scan and three dictionaries, and a rescan is what happens after the folder changes. That is enough for the thing that was actually broken, and small enough to replace when the importer arrives.
Properties
AddressVersion
public int AddressVersion { get; private set; }How many times the addresses have changed: a file ticked, renamed or labeled, or the folder read again. What lists them asks it, and lists them again when it has moved.
Root
public string Root { get; }The folder every path is relative to, but a package's; see UsePackages.
Packages
public IReadOnlyDictionary<string, string> Packages { get; }The packages whose files are known too, each by id, and the folder its files are in.
Count
public int Count { get; }How many files are known.
Notes
public IReadOnlyList<string> Notes { get; private set; }Anything that went wrong during the last scan, which is never fatal.
A sidecar that cannot be read, or cannot be written, costs that one file its stable identity and nothing else — the path still works, which is what everything did before this existed. Reported rather than thrown for the same reason the layout store reports: an editor that will not open because one file is read-only is worse than one that says so.
Empty
public static AssetDatabase Empty { get; }An empty database, for a caller with no folder to scan.
What the scene format falls back to, so that reading and writing a document without a project behind it behaves exactly as it did before identities existed.
Files
public IEnumerable<(string Path, AssetGuid Id)> Files { get; }Every file the database knows, by its path relative to the root and its identity, in no order.
Licenses
public IReadOnlyList<(string Path, TextImport License)> Licenses { get; }Every text file imported as a license, each by its path and what it says of the license, in order of their paths: what a build writes into the notices beside the game.
Labels
public IReadOnlyList<string> Labels { get; }Every label an addressable file or folder has, each once, in order.
Groups
public IReadOnlyList<string> Groups { get; }Every group a file or a folder is in, each once, in order; AssetAddress.DefaultGroup only where something is in it.
Addresses
public IReadOnlyList<(string Path, AssetAddress Address)> Addresses { get; }Every addressable file — on its own, or through its folder — by its path and what it is loaded by, in order of their paths: what a game finds by address.
Entries
public IReadOnlyList<(string Path, AssetAddress Address, bool Folder)> Entries { get; }Every addressable entry, in order of their paths: a file addressable on its own, and a folder, which makes what is inside it addressable — not what is inside one (AssetDatabase.Inside).
Methods
UsePackages
public bool UsePackages(IEnumerable<(string Id, string Folder)> packages)Knows the files of packages too, from the next AssetDatabase.Refresh on, in place of any it knew: each package's files under its own folder — a package's assets for an asset root, its shaders for a shaders folder — by their path there after the package's id, acme.physics://models/rock.glb, as the engine names them; see PackagePath. A database with no root knows none.
Parameters
packages
Returns Whether that is other packages than it knew, so it is worth reading again.
NamePackages
public void NamePackages(IReadOnlyDictionary<string, string> namespaces)Says each package's namespace, by its id, which its keys are in: Acme.Demo.Addresses.Rock (AssetDatabase.KeyOf). A package not named is in the namespace its id spells (PackageManifest.NamespaceOf).
Parameters
namespaces
FileOf
public string? FileOf(string path)The file on the disk a path names, without its label: under AssetDatabase.Root, or under its package's folder; null for a database with no root, or a path in a package it does not know.
Parameters
path
Located
public (string Root, string Inside) Located(string path)The folder a path is in on the disk and its path there: AssetDatabase.Root and the path as it is, or its package's folder and the path after its id. A path in a package not known is in the root, as it is written.
Parameters
path
Open
public static AssetDatabase Open(string root, bool mint = true)Scans a folder, giving every file in it an identity and keeping the ones it has.
Parameters
root: The asset root.mint: Whether to write a sidecar for a file that has none. False makes the scan read-only, which is what a game loading a shipped project wants.
Exceptions
DirectoryNotFoundException: The root does not exist.
Refresh
public void Refresh(bool mint = true)Scans the root again, keeping the identities of files that are still there.
Parameters
mint: Whether to give a file with no sidecar one.
IdOf
public AssetGuid IdOf(string path)The identity of a file, or AssetGuid.None if it is not known.
Parameters
path: A path relative to the root, with forward slashes, with or without a sub-asset label.
A file that has moved is known by where it was, too, for as long as this database is open and nothing else has taken the place. A scene loaded before the move names its assets by the paths they were loaded from, which is all the world kept; asked about one of those on a save, the answer has to be the file's identity, or the save writes a path that is no longer anywhere and nothing to find the file by — the broken reference that carrying the sidecar with the file is for. A move is seen when a AssetDatabase.Refresh finds an identity somewhere new, so it does not matter what moved the file, as long as its sidecar went too.
A file there now is always the answer for its path, and a file that has gone altogether takes its old paths with it.
PathOf
public string? PathOf(AssetGuid id)Where a file is now, or null if nothing here carries that identity.
Parameters
id: The identity a file was written down under.
SettingsOf
public ImportSettings SettingsOf(string path)How a file says it should be read, or ImportSettings.NothingSaid.
Parameters
path: A path relative to the root, with or without a sub-asset label.
The label is ignored, as it is for an identity: settings belong to the file, and models/x.gltf#Mesh0/Primitive0 and models/x.gltf#Material0 are one file. A path nothing here knows about answers "nothing said", because a project that has never been scanned and a file nobody has configured want the same load.
Set
public bool Set(string path, ImportSettings settings)Writes down how a file should be read, keeping the identity it already has.
Parameters
path: A path relative to the root, with or without a sub-asset label.settings: How the file should be read from now on.
Returns Whether it was written; a complaint is in AssetDatabase.Notes if it was not.
Nothing already loaded changes. A handle carries the settings it was created with, and Bevy's own reload re-applies those rather than looking again (bevy_asset 0.19.1, src/server/mod.rs:767) — so this decides how the file loads next time, which is the next time the project is opened. Re-importing in place is a real feature and this is not it.
A file with no identity yet is given one, because a sidecar holding settings and no id would be a file that survives being edited but not being moved.
ClipsOf
public ClipSettings ClipsOf(string path)How a model's clips are imported — whether at all, and which loop — or ClipSettings.Default. The label is ignored, as it is for AssetDatabase.SettingsOf.
Parameters
path: A path relative to the root, with or without a sub-asset label.
ClipNamesOf
public IReadOnlyList<string> ClipNamesOf(string path)A model's clips by their names, as its import found them and its sidecar keeps them: what the build names the keys of its clips by, Addresses.Fox.Walk, which it cannot read from the model itself. None for a model not imported since, or with no clips.
Parameters
path: A path relative to the root, with or without a sub-asset label.
MeshPartsOf
public IReadOnlyList<MeshPartName> MeshPartsOf(string path)A model's meshes' parts by their names, as its import found them and its sidecar keeps them: what the build names the keys of its meshes by, Addresses.Models.Door.Meshes.Frame, which it cannot read from the model itself. None for a model not imported since.
Parameters
path: A path relative to the root, with or without a sub-asset label.
MaterialSlotsOf
public IReadOnlyList<MaterialSlotName> MaterialSlotsOf(string path)A model's materials by their labels and names, as its import found them and its sidecar keeps them: what the build names the keys of its materials by, Addresses.Models.Door.Materials.Stone, which it cannot read from the model itself. None for a model not imported since.
Parameters
path: A path relative to the root, with or without a sub-asset label.
BakesOf
public IReadOnlyList<string> BakesOf(string path)The bakers a model's meshes are baked by as it is imported, by their names, as its sidecar keeps them (Schedule.BakeInEditor): abyss.physics3d for the shapes its Mesh Collider 3Ds are made of. None for a model baked by none.
Parameters
path: A path relative to the root, with or without a sub-asset label.
SetBakes
public bool SetBakes(string path, IReadOnlyList<string> bakes)Writes down the bakers a model's meshes are baked by, keeping everything else its sidecar says; nothing is written where they are what it keeps already.
Parameters
path: A path relative to the root.bakes: The bakers' names; each once, in the order given.
Returns Whether they are written; a complaint is in AssetDatabase.Notes where they could not be.
SetClipNames
public bool SetClipNames(string path, IReadOnlyList<string> names)Writes down a model's clips by their names, as its import found them, keeping everything else its sidecar says; nothing is written where they are what it keeps already, so a model imported again unchanged leaves its sidecar alone.
Parameters
path: A path relative to the root.names: Its clips' names, in the order its import found them.
Returns Whether they are written; a complaint is in AssetDatabase.Notes where they could not be.
SetModelNames
public bool SetModelNames(string path, IReadOnlyList<string> clips, IReadOnlyList<MeshPartName> meshes, IReadOnlyList<MaterialSlotName> materials)Writes down a model's clips, its meshes' parts and its materials by their names, as its import found them, keeping everything else its sidecar says; nothing is written where they are what it keeps already, so a model imported again unchanged leaves its sidecar alone.
Parameters
path: A path relative to the root.clips: Its clips' names, in the order its import found them.meshes: Its meshes' parts, in the order its import found them:MeshPartName.Of.materials: Its materials, in the order its import found them:MaterialSlotName.Of.
Returns Whether they are written; a complaint is in AssetDatabase.Notes where they could not be.
Set
public bool Set(string path, ImportSettings settings, ClipSettings clips)Writes down how a file should be read and, for a model, how its clips are imported, keeping the identity it already has; see AssetDatabase.Set.
Parameters
path: A path relative to the root, with or without a sub-asset label.settings: How the file should be read from now on.clips: How its clips are imported from now on.
Returns Whether it was written; a complaint is in AssetDatabase.Notes if it was not.
MaterialsOf
public MaterialRemap MaterialsOf(string path)The material files a model's own materials are drawn as instead of as its import describes them, or MaterialRemap.None. The label is ignored, as it is for AssetDatabase.SettingsOf.
Parameters
path: A path relative to the root, with or without a sub-asset label.
Set
public bool Set(string path, ImportSettings settings, ClipSettings clips, MaterialRemap materials)Writes down how a file should be read and, for a model, how its clips are imported and what its materials are drawn as, keeping the identity it already has; see AssetDatabase.Set.
Parameters
path: A path relative to the root, with or without a sub-asset label.settings: How the file should be read from now on.clips: How its clips are imported from now on.materials: What its materials are drawn as from now on.
Returns Whether it was written; a complaint is in AssetDatabase.Notes if it was not.
AudioOf
public AudioImport AudioOf(string path)How a sound clip is kept, or AudioImport.Default. The label is ignored, as it is for AssetDatabase.SettingsOf.
Parameters
path: A path relative to the root, with or without a sub-asset label.
SetAudio
public bool SetAudio(string path, AudioImport audio)Writes down how a sound clip is kept, keeping the identity it already has and what else its sidecar says; see AssetDatabase.Set.
Parameters
path: A path relative to the root.audio: How the clip is kept from now on.
Returns Whether it was written; a complaint is in AssetDatabase.Notes if it was not.
Set
public bool Set(string path, ImportSettings settings, ClipSettings clips, MaterialRemap materials, AudioImport audio)Writes down everything a file's sidecar says of how it is read, keeping the identity it already has; see AssetDatabase.Set.
Parameters
path: A path relative to the root, with or without a sub-asset label.settings: How the file should be read from now on.clips: How its clips are imported from now on.materials: What its materials are drawn as from now on.audio: How a sound clip is kept from now on.
Returns Whether it was written; a complaint is in AssetDatabase.Notes if it was not.
SpritesOf
public SpriteSheet SpritesOf(string path)How an image is drawn as sprites — its Sprite Mode — and the slices it is cut into, or SpriteSheet.None. The label is ignored, as it is for AssetDatabase.SettingsOf.
Parameters
path: A path relative to the root, with or without a sub-asset label.
SetSprites
public bool SetSprites(string path, SpriteSheet sprites)Writes down an image's Sprite Mode and slices, keeping the identity it already has and what else its sidecar says; see AssetDatabase.Set.
Parameters
path: A path relative to the root.sprites: Its Sprite Mode and slices from now on.
Returns Whether it was written; a complaint is in AssetDatabase.Notes if it was not.
TextImportOf
public TextImport TextImportOf(string path)What a text file is imported as, or TextImport.Default.
Parameters
path: A path relative to the root.
SetTextImport
public bool SetTextImport(string path, TextImport text)Writes down what a text file is imported as, keeping the identity it already has and what else its sidecar says; see AssetDatabase.Set.
Parameters
path: A path relative to the root.text: What it is imported as from now on.
Returns Whether it was written; a complaint is in AssetDatabase.Notes if it was not.
Set
public bool Set(string path, ImportSettings settings, ClipSettings clips, MaterialRemap materials, AudioImport audio, SpriteSheet sprites)Writes down everything a file's sidecar says of how it is read, its slices too, keeping the identity it already has; see AssetDatabase.Set.
Parameters
path: A path relative to the root, with or without a sub-asset label.settings: How the file should be read from now on.clips: How its clips are imported from now on.materials: What its materials are drawn as from now on.audio: How a sound clip is kept from now on.sprites: An image's Sprite Mode and slices from now on.
Returns Whether it was written; a complaint is in AssetDatabase.Notes if it was not.
AddressOf
public AssetAddress? AddressOf(string path)What an addressable file or folder is loaded by, or null for one that is not addressable. A file inside an addressable folder is addressable through it, whatever its own sidecar says: the folder's address and its path inside it, with the folder's labels and group (AssetDatabase.FolderOf).
Parameters
path: A path relative to the root, with or without a sub-asset label: a file's, or a folder's.
FolderOf
public string? FolderOf(string path)The addressable folder path is inside, and addressable through — the outermost, where one is inside another — or null for none.
Parameters
path: A file's or a folder's path relative to the root.
SetAddress
public bool SetAddress(string path, AssetAddress? address)Makes a file or a folder addressable, under an address, with labels and in a group, or — given null — not, keeping a file's identity and how it is read.
Parameters
path: A path relative to the root: a file's, with or without a sub-asset label, or a folder's.address: What it is loaded by from now on, or null.
Returns Whether it was written; a complaint is in AssetDatabase.Notes if it was not.
Written to the sidecar at once, as the inspector's tick and address are: there is no Apply for them, since nothing has to be imported again.
A folder's sidecar is beside it, enemies.abyss beside enemies, made when it is ticked and taken away when it is unticked: a folder that is not addressable says nothing.
Regroup
public int Regroup(string from, string to)Puts every file and folder of group from in group to: a group renamed, or one deleted, its entries going to AssetAddress.DefaultGroup.
Parameters
fromto
Returns How many were moved; a complaint is in AssetDatabase.Notes for each that could not be.
Addressed
public string? Addressed(string address)The file an address names, or null for an address no file has. Where two files have one, the first by path, which AssetDatabase.Repeated says.
Parameters
address: The address, matched exactly.
KeyOf
public string? KeyOf(string path)What a game's code loads an addressable file by, as its build writes it from the sidecars: Addresses.Scenes.Moons. Null for a file that is not addressable, of a kind no key loads — a stylesheet, a UI document — or whose address another file has before it by path.
Parameters
path: A path relative to the root, with or without a sub-asset label.
KeyOf
public string? KeyOf(string path, string piece)What a game's code loads a piece of an addressable model by, its clip or its mesh's part, as its build writes it: Addresses.Models.Door.Meshes.Frame. Null for a piece its sidecar does not name, and wherever AssetDatabase.KeyOf is null for the model.
Parameters
path: The model's path relative to the root.piece: A clip's name,Walk, or a mesh's part's label,Mesh0/Primitive0.
Repeated
public bool Repeated(string address)Whether more than one file has the address address.
Parameters
address
Labeled
public IReadOnlyList<string> Labeled(string label)The addressable files with a label, their own or their folder's, by path, in order of their paths.
Parameters
label: The label, matched exactly.
Inside
public IReadOnlyList<(string Path, AssetAddress Address)> Inside(string folder)The files an addressable folder makes addressable, by path and address, in order of their paths.
Parameters
folder: The folder's path relative to the root.
Resolve
public string? Resolve(AssetGuid id, string? path)Resolves a reference that may name a file by identity, by path, or by both.
Parameters
id: The identity the reference carries, orAssetGuid.None.path: The path the reference carries, ornull.
Returns The path to load, or null if the reference names nothing findable.
The identity wins, and the path is the fallback rather than the other way round. That is the whole feature: a scene written before the file moved carries the old path and the right identity, and taking the identity is what makes it still open.
The path is kept anyway, and is what answers when a project has no database, when the file has lost its sidecar, or when a scene was written by a build that had no identities. None of those is an error — they are what every scene looked like until now.
Source
public static string Source(string path)The file part of a path, without the sub-asset label a container path carries.
Parameters
path: A path, with or without a label.
models/x.gltf#Mesh0/Primitive0 is one file and one label. The identity belongs to the file, because that is the thing that can be moved.
Label
public static string? Label(string? path)The sub-asset label of a path, or null if it names a whole file.
Parameters
path: A path, with or without a label.
SidecarFor
public static string SidecarFor(string file)Where a source file's sidecar lives.
Parameters
file: The absolute path of the source file.
CopySidecar
public static string? CopySidecar(string from, string to)Gives the copy of a file a sidecar of its own: what the original's says of how it is read, under an identity nothing else has.
Parameters
from: The absolute path of the original.to: The absolute path of its copy.
Returns Why the copy was given none, or null when it was given one — or when the original has none to give, and the copy is given an identity when the project is next read, as any new file is.
The settings are the original's and the identity is not: the sidecar goes with the copy, with the identity taken out. A copy is another asset, and two files of one identity are what an identity is there to prevent; how a texture is filtered is as true of its copy. Nor is its address, for the same reason: the copy is not addressable until it is ticked.
A sidecar from a later build is not copied, since what else it says cannot be read, nor one that cannot be read at all: the copy is given an identity when the project is next read, and says nothing of how it is read.
Constants
Sidecar
public const string Sidecar = ".abyss"The extension of the file that holds a source's identity.
Not .meta. Bevy reads that name next to every asset it loads and fails the load if what it finds is not one of its own — see the note on this class.
SidecarVersion
public const int SidecarVersion = 3The version of the sidecar format, so a later one can be refused rather than misread.
Version 1 held an identity. Version 2 adds how the file is to be read. Version 3 adds an image's type, mipmaps, their filter, its Max Size, its aniso level and its compression, and names its filters point, bilinear and trilinear, reading version 2's nearest and linear as the first two. A build that knows no compression reads a sidecar naming one as the rest of it says, its texture imported as it imported every texture. A version 1 sidecar is read without complaint and reports ImportSettings.NothingSaid, which is the same thing it meant when there was nothing else it could mean — and it is not rewritten on the way past, because a scan that edits every file it looks at is a scan nobody can run on a project they do not own.
A later version is refused, and that is what the number is for: a build that cannot read a sidecar must not guess at the identity inside it and hand two files the same one.
An address and its labels are beside the import block, with no new number: a build before them reads past them and keeps the identity, so nothing it knew is misread.
