Home › Page › ReferenceLink

ReferenceLink

Ugh Scripting Reference > ReferenceLink

ReferenceLink is an intermediate class that facilitates swapping assets from immediate loading to deferred loading.  The main objective of using a deferred load over an immediate load is to maintain a concise control of memory management in devices with limited system resources.  This system is used by UghSpriteDefinition to control which of a list of possible UghSpritePrototypes are loaded into memory at runtime.

A ReferenceLink has two potential states.  The state of all ReferenceLinks can be changed by using menu options in the editor.  In the Object state the ReferenceLink holds a direct link to a Unity.Object.  (This can be a GameObject, ScriptableObject, or any other sort of prefab.)  The linked object is directly loaded into memory when the rest of the scene is loaded.  In the Resource state the ReferenceLink holds information on where an object is located.  The object will not be loaded into memory until one of ReferenceLink’s Get() methods are called.

To reiterate:  All ReferenceLinks in the Object state will have their linked object loaded into memory when the scene loads.  All ReferenceLinks in the Resource state will not load their linked object into memory until instructed to by script.

ReferenceLink may use one of three different methods of storage when in the Resource state.  LINK_RESOURCE stores the linked object in the Resources folder and uses Unity’s Resource class to manage loading and unloading of the object.  This method is default and is best used when a project will be deployed locally (such as on PC or a mobile device.)  LINK_BUNDLE stores the linked object as an AssetBundle in the StreamingAssets path and uses Unity’s AssetBundle.CreateFromFile method to load the bundle.  This method is best used when a project might modify or update an individual asset file outside of runtime (such as during an update.)  LINK_EXTERNAL_ASSET stores the linked object as an AssetBundle in the StreamingAssets path and uses ExternalAssetManager to update, load, and unload the bundle.  This method is best used when a project requires individual assets to be modified frequently, and requires that some or all of the AssetBundles be stored on an external server.

To change the state of all ReferenceLinks, a text manifest must first be created.  Do this by selecting the “Custom->Reference Link->Gather Refs to Text” menu option.  This operation scours all prefabs in the AssetDatabase for ReferenceLinks and records them in a text file.  (The default name of this file is ”referenceLinkList.txt” and is in JSON format.)  In a project of any considerable size, this can take several minutes.  Once the text manifest is generated, it does not need to be generated again until ReferenceLinks are added or removed from assets in the project.  With a valid text manifest the “Custom->Reference Link->Swap All to Resource” and “Custom->Reference Link->Swap All to Object” menu options may be used to change ReferenceLinks to their respective states.

Variables
name type description
gameObject Object A link to the prefab this ReferenceLink represents.  This will be null when in the Resource state.
linkType LinkType The method this ReferenceLink will use to manage the linked object when in the Resource state.
Class Functions
name type description
Get GameObject Retrieves the linked object and returns it cast as a GameObject.
Get<Type> <Type> Retrieves the linked object and returns it cast as <Type>.
Unload void Attempts to release and free any memory used by a loaded object.
ToString string Returns a human-readable representation of the linked object.

_

Using ReferenceLink in Script

public GameObject Get()

 

public T Get&lt;T&gt;() where T : class

Both of these functions retrieve the linked object and return it.  The first function assumes the object is a GameObject.  The second function allows script to specify the Type of object being retrieved.  If the ReferenceLink is in the Object state, these functions simply return an appropriately cast reference to the gameObject variable.  If the ReferenceLink is in the Resource state, these functions will load an asset (if required,) and then return an appropriately cast reference.

public void Unload()

This function will attempt to release and free any memory used by a loaded object.  This function only has use when the ReferenceLink is in the Resource state.  Note that this function will call Resources.UnloadUnusedAssets and, in some cases, may cause a light performance hit.

public override string ToString ()

This function will return a human-readable representation of the linked object.  This function is most useful when debugging a project.