Skip to content

Class AssetReferences

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

Finds the documents that refer to an asset and rewrites them when the asset is renamed or moved: what the editor's rename calls. A document is an authored file (: scenes now) or an .xml file in one of the definition folders the caller names, in any root of the . A reference is an attribute whose whole text is an (Model="res://models/car.glb|uid://4k2m9x7q1w3ze"); text inside elements is not looked at.

What counts as a reference to the asset: an attribute whose path is the asset's path (as the engine writes it: the two addresses of a package file, res://packages/id/x and mod://id/x, are the same), or whose UID is the asset's UID and whose path does not lead to some other file. That last condition is the engine's own rule, the path wins while its file exists (): a reference that carries the UID of a copied file and the path of the copy means the copy.

Rewriting changes the characters of the path part of each reference and nothing else (); a UID is never touched, so a reference keeps resolving through it even if a document is missed. It is all or nothing: every new text is made and checked before the first file is written, a file that changed in between stops the whole thing, and if a write fails the files already written are put back. Nothing here deletes or half-writes a file.

public static class AssetReferences

Inheritance

object ← AssetReferences

Inherited Members

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

Fields

MaxDocumentBytes

Documents and scripts larger than this are skipped (a hostile or mistaken file must not make a rename read gigabytes).

public const long MaxDocumentBytes = 67108864

Field Value

long

MaxPlannedBytes

The most memory the texts of all the documents of one rewrite may take (the old and the new bytes of each): a document that would go over it is skipped, with the reason.

public const long MaxPlannedBytes = 268435456

Field Value

long

MaxReferencesPerDocument

The most references to one asset that one document may hold to be rewritten; a document with more is skipped (a plan keeps a record of each).

public const int MaxReferencesPerDocument = 100000

Field Value

int

Methods

Find(AssetDatabase, AssetRef, IReadOnlyList<string>?, bool)

The places in the documents of the database's roots that name target: by its UID when it has one (also when the path in the reference is out of date), and by its path. Files that cannot be read or are not well-formed are left out here ( reports them). Each site is a reference, in document order.

public static IReadOnlyList<AssetReferenceSite> Find(AssetDatabase assets, AssetRef target, IReadOnlyList<string>? defFolders = null, bool includeScripts = false)

Parameters

assets AssetDatabase

The roots to search.

target AssetRef

The asset: a path, a UID, or both.

defFolders IReadOnlyList<string>?

Virtual folders (res://data) whose .xml files are searched as well as the authored files.

includeScripts bool

Also list the .luau files that mention the path or the UID ( is empty for these).

Returns

IReadOnlyList<AssetReferenceSite>

Rewrite(AssetDatabase, string, string, IReadOnlyList<string>?, bool, bool, bool)

Makes the references to the asset at oldPath say newPath. It may be called before the file is moved or after (the asset's UID is read from whichever of the two paths has the file), and with dryRun it only reports what it would do. The database is refreshed first, since the files may just have moved.

public static RewriteReport Rewrite(AssetDatabase assets, string oldPath, string newPath, IReadOnlyList<string>? defFolders = null, bool dryRun = false, bool includeScripts = true, bool allowSkipped = false)

Parameters

assets AssetDatabase

The roots whose documents are rewritten. Only writable ones are; a document in a read-only root is reported in .

oldPath string

The path the asset had.

newPath string

The path it has, or will have.

defFolders IReadOnlyList<string>?

Virtual folders whose .xml files are rewritten as well as the authored files.

dryRun bool

Report and write nothing.

includeScripts bool

List the scripts that mention the asset in (never rewritten).

allowSkipped bool

Go on although a writable document could not be used (it is not well-formed, not UTF-8, too big, cooked…): its references to the asset will not be rewritten. By default that refuses the rename (before anything is written), because the references would break silently; an editor passes true after it showed to the user and they agreed.

Returns

RewriteReport

Exceptions

ContentException

A path is not valid, they are the same, neither or both have a file, a writable document was skipped and allowSkipped is false, a file changed while the references were being prepared, or a write failed (the files already written were put back, and the message says so; if one could not be put back it is named).