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
(.xml file in one of the definition folders the caller names, in any root of the 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 (
Rewriting changes the characters of the path part of each reference and nothing else (
public static class AssetReferences
Inheritance¶
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¶
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¶
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¶
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 (
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 (
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
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
Returns¶
Exceptions¶
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).