Skip to content

Class AssetDatabase

Namespace: Apogee.Content.Assets
Assembly: Apogee.Content.dll

Which file an asset's UID names, and which UID a file has. The UID of an imported file is in its .import.xml, the UID of an authored one (a scene) is in its root element (); the database reads them from the files, so it is always about what is on disk. To find a UID it first asks the project's list, imported/assets.xml (written by : one read per root), and when that has nothing (or is out of date: the file moved after the import) it scans the files of its once. It never writes: giving files UIDs is the importer's job, so a read-only root (a pack, a mod, a shipped game) is fine, and its assets with no UID just have none.

Results are remembered until (call it after an import, or when files change on disk). Safe to use from several threads.

public sealed class AssetDatabase

Inheritance

object ← AssetDatabase

Inherited Members

object.Equals(object?), object.Equals(object?, object?), object.GetHashCode(), object.GetType(), object.ReferenceEquals(object?, object?), object.ToString()

Constructors

AssetDatabase(VirtualFileSystem)

Which file an asset's UID names, and which UID a file has. The UID of an imported file is in its .import.xml, the UID of an authored one (a scene) is in its root element (); the database reads them from the files, so it is always about what is on disk. To find a UID it first asks the project's list, imported/assets.xml (written by : one read per root), and when that has nothing (or is out of date: the file moved after the import) it scans the files of its once. It never writes: giving files UIDs is the importer's job, so a read-only root (a pack, a mod, a shipped game) is fine, and its assets with no UID just have none.

Results are remembered until (call it after an import, or when files change on disk). Safe to use from several threads.

public AssetDatabase(VirtualFileSystem files)

Parameters

files VirtualFileSystem

Fields

ListFileName

The name of the project's list of UIDs, in the imported folder of a root.

public const string ListFileName = "assets.xml"

Field Value

string

ListVersion

The version written in the list. A list with a newer one is ignored (the scan finds the same things, only slower).

public const int ListVersion = 1

Field Value

int

Properties

Duplicates

The groups of files that have the same UID (a copied asset and its .import.xml, or two mods that ship the same file), each with its paths and the first one the UID names. Importing a project makes a UID of its own for the copies; this is what is left when a root cannot be written to. It looks at every file of the roots once.

public IReadOnlyList<(AssetUid Uid, IReadOnlyList<string> Paths)> Duplicates { get; }

Property Value

IReadOnlyList<(AssetUid Uid, IReadOnlyList<string> Paths)>

Roots

The roots of the projects whose assets can be found: res:// first, and the host adds mod://<id>/ for each mounted package in load order. When two roots have the same UID the first one wins. Change it before the database is used, or call after.

public IList<string> Roots { get; }

Property Value

IList<string>

Methods

Move(string, string, IReadOnlyList<string>?, bool, bool)

Moves or renames the asset at from to to (both in the game folder, res://) and keeps everything that names it working:

  • the file, its .import.xml (so the UID goes with it) and its imported artifact move together;
  • the references in documents are rewritten (: scenes and the definition folders in defFolders), keeping their UIDs;
  • imported/index.xml and imported/assets.xml say the new path. The artifact is still good (the import key does not depend on the path), so nothing imports again; an editor that wants to be sure can call .

All or nothing for what matters: the documents are checked and prepared before anything is touched, the files are then moved, and if that fails the documents and the files are put back. The import data is a cache; if it cannot be updated that is a warning and the next import repairs it. .luau scripts are never rewritten: the ones that mention the old path are listed in . Only a file can be moved here (a folder is moved by moving what is in it, one call each).

public MoveReport Move(string from, string to, IReadOnlyList<string>? defFolders = null, bool dryRun = false, bool allowSkipped = false)

Parameters

from string

The asset's path. It must be a file, and not an .import.xml (that follows its asset) or something in imported/.

to string

The new path. Nothing may be there, neither a file nor a folder, and no .import.xml.

defFolders IReadOnlyList<string>?

Virtual folders whose .xml files are searched for references as well as the authored files.

dryRun bool

Report what would happen and change nothing.

allowSkipped bool

Go on although a writable document could not be used (not well-formed, not UTF-8, too big, cooked…) and its references to the asset will therefore break. By default that refuses the move before anything is written; see .

Returns

MoveReport

Exceptions

ContentException

Something is wrong with the request (a path, a read-only file, a target that exists), a writable document was skipped and allowSkipped is false, a document changed while it was being prepared, or a write failed. Nothing is left half done: the message says if something could not be put back.

PathOf(AssetUid)

The file that uid names, or null when no file of the roots has it. A file of a package that is mounted at mod://id/ (and is in ) is given by that address, the one the rest of the engine uses for it, and not by its place under res://packages/id/.

public string? PathOf(AssetUid uid)

Parameters

uid AssetUid

Returns

string?

RefOf(string)

The reference to the file at path: the path, normalized, and its UID (none when it has none).

public AssetRef RefOf(string path)

Parameters

path string

Returns

AssetRef

Refresh()

Forgets what was read, so that the next question reads the files again.

public void Refresh()

Resolve(AssetRef)

The file the reference means: its path when that file exists (the path is what people wrote, and it wins; an imported asset of a cooked pack counts as existing, since the pack holds its artifact and not the source), otherwise the file that has its UID (logged, so that whoever saves the document that holds the reference writes the new path), otherwise null.

public string? Resolve(AssetRef reference)

Parameters

reference AssetRef

Returns

string?

ResolvePath(string)

What a script or a document names, as a path: uid://… becomes the file that has it, anything else is returned as it is (it is not checked here, loading it says if it is wrong).

public string ResolvePath(string pathOrUid)

Parameters

pathOrUid string

Returns

string

Exceptions

ContentException

The text is a uid:// that is not valid or that no file has.

UidOf(string)

The UID of the file at path, read from its .import.xml or, for an authored file, its root; when the file does not exist or has none.

public AssetUid UidOf(string path)

Parameters

path string

Returns

AssetUid