AddressableBaseChunkStreamer Class

public abstract class AddressableBaseChunkStreamer : ChunkStreamer

Base class for addressable chunk streamer implementations. While it is not strictly necessary to use this with your custom addressable chunk streamers, doing so will automate many necessary task related to loading addressable assets.

The only thing you need to provide implementations for is the FileExtension property, the DetatchAndUnloadChunksFromCells method, and a custom AddressableStreamerBaseUser object, which should be returned in your implementation of the CreateAddressableLoaderUser method.

Furthermore, your custom AddressableStreamerBaseUser must implement certain methods and properties, which your IDE should highlight when implementing the class. You can also find information about those members, as well as other public/protected members of the AddressableStreamerBaseUser class on this page, listed among the normal members of the class. You can identify these members easily, as they will have AddressableStreamerBaseUser. in front of their name.

There are two additional nested classes which you may need to make use of in your AddressableStreamerBaseUser derived classes. These are the LoadedAsyncOperationInfo and ReadyOp classes. Fields, methods, and properties of these classes are listed on this page as well and begin with LoadedAsyncOperationInfo and ReadyOp respectively.

Properties

Name Type Description
AddressableStreamerBaseUser.CanReuseAddressables bool

An abstract property that must be overriden to return a value indicating whether the addressable assets (associated with the load operation) loaded by your streamer implementation can be reused between World Cells with the same Streamable Grid Cell index.

For example, the default Addressable Scene Streamer returns false for this, because scenes do not use an underlying asset that can be reused. The Prefab Streamer, on the other hand, returns true, because there is an underlying prefab asset that is loaded, which can be instantiated as many times as needed in order to be shared among different World Cells with the same Streamable Grid Cell index.

Reusing the underlying addressable asset is beneficial because it cuts down on the number of Async load operations needed. When this returns true, the key used to store each LoadedAsyncOperationInfo object is a combination of the Streamable Grid Cell index of the World Cell that triggered the load, and the chunk index of whatever chunk is needed by the cell. When other World Cells using the same Streamable Grid Cell index need to have chunks loaded for them, they are able to use the index (plus chunk number of the asset they need) to identify an addressable asset that has already been loaded, and use it to make a copy that can be used for that World Cell.

When this returns false, each World Cell will trigger an Async Load Operation, even if a World Cell with the same Streamable Grid Cell indexes has already been loaded. The key used to store the LoadedAsyncOperationInfo comes from the AsyncOperationHandle itself, which is retrieved by calling the GetNonReusableAssetKey method (which you also need to implement in your custom user class).

AddressableStreamerBaseUser.FileType Type

An abstract property that must be overriden to return a value indicating the file type of the addressable assets (for example typeof(SceneInstance) or typeof(GameObject)).

AddressableStreamerBaseUser.IsWaitingOnJob bool

Gets a value indicating whether the user is waiting on a multi threaded job to finish. This is very unlikely to ever be true, however it is still necessary to check this in your custom streamer whenever one of its public methods is called (such as LoadAndAttachChunksToCellsInSingleFrame or DetatchAndUnloadChunksFromCells). If the method is an enumerator, simply yield until IsWaitingOnJob returns false. If there is no possibility to wait (i.e., the method returns something other than IEnumerator<YieldInstruction>) you can call the method CompleteAllJobsImmediately to force the any running jobs to complete immediately.

AsyncLoadStrategy AsyncLoadStrategy

Gets or sets the Async Load Strategy.

ConstantDataToAppend string

Returns the FileExtension if Append File Extension is enabled in the inspector, otherwise returns null.

ErrorRepairer AddressableErrorRepairer

Gets the Addressable Error Repairer associated with the Addressable Loader.

ExtraDataToAppendKey string

See ChunkStreamer.ExtraDataToAppendKey for more information on this property. This implemention simply returns the value of 'Append Data Key' set in the inspector if 'Append Extra user Data' is true, or null if 'Prepend Extra User Data' is false.

ExtraDataToPrependKey string

See ChunkStreamer.ExtraDataToPrependKey for more information on this property. This implemention simply returns the value of 'Prepend Data Key' set in the inspector if 'Prepend Extra User Data' is true, or null if 'Prepend Extra User Data' is false.

FileExtension

Override to return the file extension associated with the addressable assets being loaded. You can override this to try and load custom asset types, such as scriptable objects, however there is no gaurantee that this will work. This is used when Append File Type is enabled in the inspector.

For Prefabs this is .prefab, for scenes it is .unity

LoadedAsyncOperationInfo.ChunkName string

Gets the name of the Asset Chunk associated with this loaded async operation.

LoadedAsyncOperationInfo.Handle AsyncOperationHandle

Gets the handle associated with the operation.

LoadedAsyncOperationInfo.HasUsers bool

Gets a value indicating whether the loaded async operation has users.

MaxLoadAttempts int

Gets or sets the maximum number of attempts allowed for loading an asset.

PrintErrorToConsole bool

When FailureHandling is set to LoadPlaceholder, this controls whether the exception reported by Unity for the failed load operation is printed as an error in the console. Get or Set

ReadyOp.Cell WorldCell

Gets the World Cell associated with the operation, which is the World Cell that requested the Addressable Asset in the first place.

ReadyOp.ChunkIndex int

Gets the chunk index of the Asset Chunk that was loaded.

ReadyOp.LoadedAsyncOpInfo LoadedAsyncOperationInfo

Gets the information about the load operation.

UseAltLODFailSafe bool

Gets whether the streamer has been configured to a use a lowest quality LOD fail-safe asset when the original asset cannot be loaded for a cell chunk.

UsePlaceholderFailSafe bool

Gets whether the streamer has been configured to a use a placeholder fail-safe asset when the original asset (or lowest quality LOD asset) cannot be loaded for a cell chunk.

Constructors

AddressableStreamerBaseUser.AddressableStreamerBaseUser(AddressableBaseChunkStreamer, ILODGroup)

public AddressableStreamerBaseUser(AddressableBaseChunkStreamer parent, ILODGroup LODGroup) : base(parent, LODGroup)

Creates a new instance of the AddressableStreamerBaseUser. You will never call this directly, instead you will create a class derived from AddressableStreamerBaseUser that calls base(parent, LODGroup) after the constructor's declaration.

Parameters

Name Type Description
parent AddressableBaseChunkStreamer

The parent streamer of this instance.

LODGroup ILODGroup

The LOD Group associated with the instance.

Methods

AddressableStreamerBaseUser.CheckForLoadAndAttachChunksToCellsInSingleFrameExceptions()

public virtual void CheckForLoadAndAttachChunksToCellsInSingleFrameExceptions()

Some custom streamers cannot load addressable assets in one or two frames, which makes them incompatible with the Component Manager's Initialize method or 'Initialize On Awake' property. This method should perform checks to see if that's the case and throw exceptions if any issues exist. If you know there will never be any issues, you do not need to provide an override.

AddressableStreamerBaseUser.CompleteAllJobsImmediately()

public void CompleteAllJobsImmediately()

Completes any jobs currently running immediately. Note, this may cause a hitch in the frame rate. Jobs are used by the base chunk streamer to execute some CPU intensive code. Whenenever a publich method of your custom streamer is called, you need to check whether the user is currently running a job by querying the IsWaitingOnJob property. If it is waiting, you need to yield until the job is complete (IsWaitingOnJob returns false). If for any reason you are unable to yield, you can call this method to force the job to complete immediately.

AddressableStreamerBaseUser.CreateCellString(ILODGroup, string, string)

protected sealed override CellString CreateCellString(ILODGroup LODGroup, string extraDataToPrepend, string extraDataToAppend)

Creates a Cell String object, automatically taking into account whether Use Single Chunk Set For All Cells is enabled on the LOD Group associated with the user.

Parameters

Name Type Description
LODGroup ILODGroup

The LOD Group associated with this user.

extraDataToPrepend string

Extra data to prepend to the strings generated with the Cell String. Pass this into your CellString object, and don't worry about whether it is null or blank, as those cases are handled automatically by the CellString.

extraDataToAppend string

Extra data to append to the strings generated with the Cell String. Pass this into your CellString object, and don't worry about whether it is null or blank, as those cases are handled automatically by the CellString.

Returns

CellString
The Cell String object created.

AddressableStreamerBaseUser.GetNonReusableAssetKey(AsyncOperationHandle)

public virtual int GetNonReusableAssetKey(AsyncOperationHandle handle)

This is called when CanReuseAddressables is implemented to return false, and should return a unique key that can be used to store the passed in handle plus some additional information about the load operation used to load the addressable asset.

When chunks associated with a World Cell need to be unloaded, you must be able to produce or access the correct key for the chunk stored on the World Cell. Note, however, that if your Chunk Manager uses pooling, or has chunk reuse enabled, the chunk stored in the World Cell may have been originally loaded for a different World Cell. Therefore, it is imperative to use a key that is associated with the chunks themselves rather than World Cell. If using a chunk that derives from UnityEngine.Object, you can use the GetInstanceID to get a unique int that can be used as the key.

If CanReuseAddressables returns true, you do not need to override this method.

Parameters

Name Type Description
handle AsyncOperationHandle

The handle that the key needs to be generated for.

Returns

int
A unique key associated with the handle or the chunk loaded by the handle.

AddressableStreamerBaseUser.IsLowestQualityLODStreamerCompatible(ChunkStreamer)

protected abstract bool IsLowestQualityLODStreamerCompatible(ChunkStreamer streamerOfLowestQualityLODAssets)

Must be overriden to return a value that indicates whether the Chunk Streamer used by the lowest quality LOD for the Streamable Grid associated with this user is compatible with the type of Addressable Chunk Streamer in use. Typically it should be of the same type. This is only called when UseAltLODFailSafe would otherwise be true. If you return false from this method, UseAltLODFailSafe will be made false as well.

If the streamer is compatible, you can and should store it (casted to the derived type of streamer you are using) along with the chunkStreamerUserID to avoid having to look up the streamer and ID each time they are needed.

Parameters

Name Type Description
streamerOfLowestQualityLODAssets ChunkStreamer

The Chunk Streamer used by the lowest quality LOD.

Returns

bool
Should return true if the Chunk Streamer from the lowest quality LOD is compatible with this Chunk Streamer. False otherwise.

AddressableStreamerBaseUser.LoadNewAssetAsyncUsingKey(string)

public abstract AsyncOperationHandle LoadNewAssetAsyncUsingKey(string key)

Should be able to return an AsyncOperationHandle for loading an addressable asset by a key. If you have setup your chunk streamer to NOT use keys at all, then you can throw an exception in the method body if you want.

Parameters

Name Type Description
key string

The key to use to load the asset.

Returns

AsyncOperationHandle
An AsyncOperationHandle for the load.

AddressableStreamerBaseUser.LoadNewAssetAsyncUsingLocation(IResourceLocation)

public abstract AsyncOperationHandle LoadNewAssetAsyncUsingLocation(IResourceLocation location)

Should be able to return an AsyncOperationHandle for loading an addressable asset by its IResourceLocation. If you have setup your chunk streamer to NOT use IResourceLocations at all, then you can throw an exception in the method body if you want.

Parameters

Name Type Description
location IResourceLocation

The IResourceLocation of the asset.

Returns

AsyncOperationHandle
An AsyncOperationHandle for the load.

AddressableStreamerBaseUser.RemoveLoadedAsyncOpInfo(int, LoadedAsyncOperationInfo)

public void RemoveLoadedAsyncOpInfo(int key, LoadedAsyncOperationInfo info)

Can be used to remove information for a completed load operation from the users internal collection of infos. This should be used in cases where your streamer implementation is manually unloading the handle associated with the load operation. Typically this is only done if the underlying handle is not being resused among multiple World Cells, as otherwise you are better off destroying the instance of the resource, then calling RemoveUserOfReusableAsset and letting the base addressale chunk streamer unload the handle and remove this info.

Parameters

Name Type Description
key int

The key associated with the information, which should match the key returned by your implementation of the GetNonReusableAssetKey method. Note that since you are manually unloading the handle, you should have access to it and be able to retrieve the same key.

info LoadedAsyncOperationInfo

The info being removed. Passing this in allows the info object to be reset and returned to the pool without needing to be retrieved from the internal collection, which saves a few CPU cycles.

AddressableStreamerBaseUser.RemoveUserOfReusableAsset(WorldCell, int)

public void RemoveUserOfReusableAsset(WorldCell cell, int chunkIndex)

Removes a single user for the reusable chunk asset associated with the input World Cell and chunk index. If the user count for the asset falls to 0, the handle will be unloaded and LoadedAsyncOperationInfo removed.

Parameters

Name Type Description
cell WorldCell

The World Cell associated with the asset.

chunkIndex int

The chunk index of the asset.

AddressableStreamerBaseUser.SetupChunkFromLoadHandle(ReadyOp, AsyncOperationHandle, out ChunksPositioned)

public abstract object SetupChunkFromLoadHandle(ReadyOp readyOp, AsyncOperationHandle handle, out ChunksPositioned chunksPositioned)

Should get (from the AsyncOperationHandle) and setup the asset chunk that will be attached to the World Cell. Once the asset is returned it is simply attached to the World Cell; no other processing is done with it, so you must ensure the asset is configured exactly as you want. For instance, for Game Objects, you should set the name of the object to readyOp.LoadedAsyncOpInfo.ChunkName.

Parameters

Name Type Description
readyOp ReadOp

Contains some information about the chunk asset, such as its name.
handle AsyncOperationHandle

The handle used to load the asset, which should contain a reference to the asset. Note that typically, this asset is not suitable to be attached to the World Cell. You will likely need to cast the handle to the correct type using handle.Convert, then retrieve or instantitate the actual object that will be attached to the World Cell (for example, prefab streamers load a GameObject resource, but this resource doesn't actually exist in the scene, so a different GameObject must be instantiated from the resource.

chunksPositioned ChunksPositioned

Set to whether you have positioned the chunks or not (if you are not sure, set to Maybe).

Returns

object
The chunk object to attach to the World Cell

AddressableStreamerBaseUser.TryGetAssetLoadInfo(int, out LoadedAsyncOperationInfo)

public bool TryGetAssetLoadInfo(int key, out LoadedAsyncOperationInfo info)

Tries to get information associated with a completed load operation using a specific integer key. If the load operation is reusable, you should use one of the TryGetReusableAssetLoadInfo methods instead. Otherwise, use this method with the same key returned by your implementation of GetNonReusableAssetKey.

Parameters

Name Type Description
key int

The key to use to get the information.

info LoadedAsyncOperationInfo

If the method returns true, this will contain the information.

Returns

bool
True if the information could be retrieved, false otherwise.

AddressableStreamerBaseUser.TryGetReusableAssetLoadInfo(WorldCell, int, out Cell, out int, out LoadedAsyncOperationInfo)

public bool TryGetReusableAssetLoadInfo(WorldCell worldCell, int chunkIndex, out Cell streamableGridCellToLoad, out int assetKey, out LoadedAsyncOperationInfo info)

Use to try and retrieve LoadedAsyncOperationInfo for a reusable asset that has already been loaded. If your custom addressable chunk streamer has asset reuse disabled, will always return false and you must ignore the out arguments.

Parameters

Name Type Description
worldCell WorldCell

The World Cell whose chunks you are trying to load.

chunkIndex int

The index of the chunk you are trying to load.

streamableGridCellToLoad Cell

The Streamable Grid Cell that will actually be loaded for this World Cell, as calculated by the user based on whether the LODGroup is using a Single Object Cell Set

assetKey string

The key produced by the user to try and retrieve the asset load info. Will be set correctly so long as the custom addressable chunk streamer does not have asset reuse disabled.

info LoadedAsyncOperationInfo

If the method returns true, this will contain the info about the async operation handle that was used to load the asset to be reused (found in the handles .Result property). Note, if you use the Result, you must call IncrementUserCount!

Returns

bool
Returns true if there is an addressable asset that can be reused by the input World Cell, and false if not.

AddressableStreamerBaseUser.TryGetReusableAssetLoadInfo(Cell, int, out int, out LoadedAsyncOperationInfo)

public bool TryGetReusableAssetLoadInfo(Cell streamableGridCellToLoad, int chunkIndex, out int assetKey, out LoadedAsyncOperationInfo info)

Use to try and retrieve LoadedAsyncOperationInfo for a reusable asset that has already been loaded. If your custom addressable chunk streamer has asset reuse disabled, will always return false and you must ignore the out arguments.

This alternative method can be used if you have already determined the correct Streamable Grid Cell to use to load the Assets for a particular World Cell.

Parameters

Name Type Description
streamableGridCellToLoad Cell

The Streamable Grid Cell that is actually being used to load Assets for a given World Cell.

chunkIndex int

The index of the chunk you are trying to load.

assetKey string

The key produced by the user to try and retrieve the asset load info. Will be set correctly so long as the custom addressable chunk streamer does not have asset reuse disabled.

info LoadedAsyncOperationInfo

If the method returns true, this will contain the info about the async operation handle that was used to load the asset to be reused (found in the handles .Result property). Note, if you use the Result, you must call IncrementUserCount!

Returns

bool
Returns true if there is an addressable asset that can be reused by the input World Cell, and false if not.

AwakeExtended()

protected void AwakeExtended()

Awake implementation. If you want to implement custom Awake logic, implement AwakeExtended2.

AwakeExtended2()

protected virtual void AwakeExtended2()

Can be overriden to implement Awake related logic. Called at end of base classes AwakeExtended method.

CreateAddressableLoaderUser()

protected abstract AddressableStreamerBaseUser CreateAddressableLoaderUser(ILODGroup LODGroup)

Override to return a new user object that derives from AddressableStreamerBaseUser. The derived class must implement certain abstract methods/properties from AddressableStreamerBaseUser.

Parameters

Name Type Description
LODGroup ILodGroup

The lod group being registered.

Returns

AddressableStreamerBaseUser
A user object deriving from AddressableStreamerBaseUser

CreateNewUser()

protected sealed override ChunkStreamerUser CreateNewUser(ILODGroup LODGroup)

Creates a new ChunkStreamerUser by calling CreateAddressableLoaderUser. This method is overriden to force sub classes to create a new ChunkStreamerUser that derives from AddressableLoaderBaseUser. This is necessary because AddressableLoaderBaseUser is an abstract class and some of its methods/properties need to be implemented.

Parameters

Name Type Description
LODGroup ILodGroup

The lod group being registered.

Returns

ChunkStreamerUser
A new user object created using the LODGroup as input.

LoadAndAttachChunksToCells(List<WorldCell>, int)

public sealed override IEnumerator<YieldInstruction> LoadAndAttachChunksToCells(List<WorldCell> cells, int userID)

Loads and attaches the chunks associated with the input cells to the cells over a period of frames.

Parameters

Name Type Description
cells List<WorldCell>

The cells whose objects need to be loaded and attached.
userID int

The ID of the user requesting the load and attachment.

Returns

IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine. See the YieldInstruction page for more info.

LoadAssetForCell(Cell, int, int, out string, out IResourceLocation, out string)

public AsyncOperationHandle LoadAssetForCell(Cell streamableGridCell, int chunkIndex, int userID, out string chunkName, out IResourceLocation location, out string key)

Used to load lower quality assets when a streamer is unable to load a higher quality addressable asset. You shouldn't need to call this yourself, unless you are creating a custom Addressable Chunk Streamer.

Parameters

Name Type Description
streamableGridCell Cell

The Streamable Grid Cell indexes associated with the asset we want to load.

chunkIndex int

The index of the chunk we want to load.

userID int

The ID of the user whose info will be used to load the asset.

chunkName string

The name of the chunk asset that this streamer is attempted to load, set once the method executes.

location IResourceLocation

The IResourceLocation used to load the asset. May be null if the Key was used instead to load the asset.

key string

The key used to load the asset. May be null if the IResourceLocation was used instead to load the asset.

Returns

AsyncOperationHandle
An async op handle for the asset that is being loaded.

OnDestroy()

protected void OnDestroy()

OnDestroy implementation. If you want to implement custom OnDestroy logic, implement OnDestroyExtended.

OnDestroyExtended()

protected virtual void OnDestroyExtended()

Can be overriden to implement OnDestroy related logic. Called at end of base classes OnDestroy method.

RecalculateIResourceLocations()

public void RecalculateIResourceLocations()

Recalculates the IResourceLocations for the addressable assets associated with all users of this streamer. This will do nothing if Pre Calculate IResourceLocations is disabled. Only use this when you know the locations need to be recalculated.

If you only need one users data reculated, use RecalculateIResourceLocations instead.

RecalculateIResourceLocations(int)

public void RecalculateIResourceLocations(int userID)

Recalculates the IResourceLocations for the addressable assets associated with the user ID. This will do nothing if Pre Calculate IResourceLocations is disabled. Only use this when you know the locations need to be recalculated.

You can use the World's GetChunkStreamerAndID method in order to find out the chunk streamer ID for a particular World Grouping and LOD.

Parameters

Name Type Description
userID int

The ID of the user whose IResourceLocations you want to recalculate.

Start()

protected void Start()

Start implementation. If you want to implement custom Start logic, implement StartExtended.

StartExtended()

protected virtual void StartExtended()

Can be overriden to implement Start related logic. Called at end of base classes Start method.