ChunkStreamer Abstract Class

public abstract class ChunkStreamer : MonoBehaviour

Provides a base implementation for Chunk Streamers. Chunk Streamers should be able to load objects over several frames and depending on the asset type, in a single frame. When single frame loading is impossible (as is the case with some load methods) pre-loading will be used (pre-loading occurs in one frame, then the actual single frame load occurs in the next).

In order to accomplish this, the IsSingleFrameAttachmentPreloadRequired property must be overridden in the derived class to indicate whether pre-loading is required.

If one or two frame loading is impossible, THAT'S OKAY!. However, you will need to ensure that 'Initialize On Awake' is disabled on your Component Manager, and manually initialize the everything over multiple frames via the InitializeGradually method (also via the Component Manager).

The Chunk Streamer class is also responsible for unloading asset chunks from the scene as well! In addition, you can use a custom Chunk Streamer to load and unload non Game Objects, by creating a custom Chunk Manager that makes use of your custom objects. These non game objects can be stored on World Cells just as Game Objects, however you will need to ensure that the Chunk Type on your LODs that use these objects are set to Custom Objects (on your Streamable Grid asset).

Additional Note: This component contains its own special class (ChunkStreamerUser) which enables multiple users to use the Chunk Streamer at the same time. The data associated with each user is stored in this user object and retrieved using the userID passed into each method. A user can effectively be thought of as a specific LOD from a specific Streamable Grid. The utlization of users allows the same streamer to be used with multiple LODs, so long as these LODs are setup to work with the settings configured on the streamer.

This user object contains a Cell String, which you are free to use in your own derived Chunk Streamer component. You can access the user object and cell string via the RegisteredUsers property and userID, like so: RegisteredUsers[userID] (accesses the user object) or RegisteredUsers[userID].CellString.

You may also create your own custom user object class which derives from ChunkStreamerUser, in order to store custom data or add custom methods. In fact, this strategy is utilized by some of the other Chunk Streamers in the kit. Simply override the CreateNewUser method and return your custom user object.

The properties, methods, and constructors of this ChunkStreamerUser class have been included on this webpage along side the other members of the ChunkStreamer class. You can easily identify them as their member names include a ChunkStreamerrUser prefix. You can use these as a reference when creating custom ChunkStreamerUser classes.

You should never have to interact directly with this component, as the methods/properties are called/used as needed by the Streamable Assets Manager.

Properties

Name	Type	Description
ChunkStreamerUser.CellString	CellString	A Cell String object created via the CreateCellString method.
ChunkStreamerUser.ChunkStreamer	ChunkStreamer	The ChunkStreamer that created the user object. Think of it as the parent of the object.
ChunkStreamerUser.LODGroup	ILODGroup	The ILODGroup info passed in by the user. This contains useful information related to the user.
ChunkStreamerUser.UserScene		The scene associated with the user. If the user's World makes use of a Hierarchy Organizer, this will be the scene that the Organizer is in, otherwise it will be the scene that the World component is in. Keep in mind that in most instances, both the Organizer and World will be in the same scene.
CompatibleWithHiearchyOrganizer	bool	Gets a value indicating whether the Chunk Streamer is compatible with Hiearchy Organizers. By default it returns true, which should work for most Chunk Streamers. However, in cases where reassigning an Asset Chunks parent might be problematic (which is what occurs with Hierarchy Organizers), you can override this property to return false. This property is queried when the World using a Hiearchy Organizer is initialized, if an LOD Group using this Streamer has Hierarchy Organizers enabled (in the inspector). If they are enabled and the LOD Group's Streamer returns false for this property, the Hierarchy Organizer will be disabled for that LOD Group and an error will be printed to the console.
ConstantDataToAppend	string	Normally, the names used to load chunks are constructed using three or four components. The naming convention assigned to each user (via Streamable Grid LODs), the Group Name associated with the user, the Streamable Grid Cell Index of the cell whose chunks/objects are being loaded, and optionally the chunk index of the chunk being loaded (if multi chunking is being used). The output name is known as the Cell String, and is generated using the CellString class. In some cases, this is not enough to load the object. For instance, when loading Addressable Assets via one of the Addressable Asset Streamers, if the address of your assets include the file extension (.prefab for prefabs or .asset for scenes), this file extension will need to be included in the keys used to load the assets. In these situations, you have three options. Append extra data that is different for each Chunk Streamer user, append some data that is constant for all users, or append both types of data (in which case the constant data will be appended after the extra data that is different for each user). This property returns the constant data to append; by default it returns null, so if you want to return some other data, override it!
ExtraDataToAppendKey	string	Normally, the names used to load chunks are constructed using three or four components. The naming convention assigned to each user (via Streamable Grid LODs), the Group Name associated with the user, the Streamable Grid Cell Index of the cell whose chunks/objects are being loaded, and optionally the chunk index of the chunk being loaded (if multi chunking is being used). The output name is known as the Cell String, and is generated using the CellString class. In some cases, this is not enough to load the object. For instance, when loading Addressable Assets via one of the Addressable Asset Streamers, if the address of your assets include the file extension (.prefab for prefabs or .asset for scenes), this file extension will need to be included in the keys used to load the assets. In these situations, you have three options. Append extra data that is different for each Chunk Streamer user, append some data that is constant for all users, or append both types of data (in which case the constant data will be appended after the extra data that is different for each user). This property returns the key used to access the extra data that is different for each Chunk Streamer user. The extra data may be stored either in the Extra Data stored globally on the Streamable Grid associated with the user, or in the LOD's (also on the Streamable Grid asset) Extra Data. If extra data is stored in both places (matching the key), the extra data stored in the LOD takes priority. Note, it is possible to have some users need the appended data and others to not need it. In this case, simply omit the extra data from the LOD or Streamable Grid associated with the users that do not need to use the appended data. When the streamer finds no data associated with the key, appended data is simply ignored for that user. If you know that all users will use the same appended data, you may wish to override the ConstantDataToAppend property isntead. By default this returns null, indicating there is no extra data to append. Only override the property if you need to append extra data!
ExtraDataToPrependKey	string	Normally, the names used to load chunks are constructed using three or four components. The naming convention assigned to each LOD Group (via Streamable Grid LODs), the Group Name associated with the LOD Group, the Streamable Grid Cell Index of the cell whose chunks/objects are being loaded, and optionally the chunk index of the chunk being loaded (if multi chunking is being used). The output name is known as the Cell String, and is generated using the CellString class. In some cases, this is not enough to load the object. For instance, when loading prefabs from the Resources folder, and if the prefabs are located in a sub folder, just using this generated name will not allow the prefabs to be loaded. You must also include the sub folder path in the name passed to Resources.LoadAsync. In these situations, you may need to prepend some extra string data to each Cell String in order to generate a valid string that can be used to load your chunks. Rather than have this data be constant per user (which would limit the streamer to being used by a limited number of users), instead it is derived from each individual user by accessing either the Extra Data stored globally on the Streamable Grid associated with the user, or in the LOD's (also on the Streamable Grid asset) Extra Data. This extra data is stored in a dictionary and requires a key to access. This property returns the key that will be used by the streamer to look up the extra data to prepend. Note, it is possible to have some users need the prepended data and others to not need it. In this case, simply omit the extra data from the LOD or Streamable Grid associated with the users that do not need to use the prepended data. When the streamer finds no data associated with the key, prepended data is simply ignored for that user. Note, by default this property returns null, indicating that there is no extra data to prepend. Only override it you need to prepend some extra data!
IsSingleFrameAttachmentPreloadRequired	bool	When overridden in derived class, gets a bool value indicating whether the derived class requires pre loading in order to execute the PerformSingleFrameAttachmentPreload method successfully. If overridden to return true, then the PerformSingleFrameAttachmentPreload method must also be overridden.
LoadProgress	float	Tracks the progress of this Chunk Streamer's current LoadAndAttachChunksToCells method call as a value between 0 (nothing loading) and 1 (all chunks loaded). When LoadAndAttachChunksToCells is called, you should set this value to 0f, gradually incrementing it as you load a new chunk. At the methods end, it should be set to 1f. This is automatically done by the built in Chunk Streamer implementations, however you will need to do this manually if creating a custom Chunk Streamer. An easy way to calculate how much the progress should be incremented each time a new chunk is loaded is to divide 1f by the total number of chunks that need to be loaded with the operation (1f / total chunks). This value is used internally by SAM to track loading progress when the Component Manager is gradually initialized. You can query the property yourself, however it will only be valid when a load operation is in progress, which is difficult to know (though generally speaking, if the value is equal to 1f, a load operation is not in progress).
RegisteredUsers	RegistrationHandler<ChunkStreamerUser> (protected)	The users registered with the Chunk Streamer.

Constructors

ChunkStreamerUser.ChunkStreamerUser(ChunkStreamer, ILODGroup)

public ChunkStreamerUser(ChunkStreamer streamer, ILODGroup LODGroup)

Creates a new instance of the Chunk Streamer User object. If you are overriding the ChunkStreamer class and not overriding the ChunkStreamerUser, you can create a new instance of this user object via this constructor, which can be returned in the ChunkStreamer's CreateNewUser method.

If you are overriding ChunkStreamerUser, your custom user class will need constructors with at least these parameters (but can also have more), and they must also call the base constructor, which is accomplished by placing : (streamer, LODGroup) after your constructor declaration.

Note, this constructor can only be used from a class deriving from ChunkStreamer or ChunkStreamerUser.

Parameters

Name	Type	Description
LODGroup	ILODGroup	The LODGroup associated with the user.
streamer	ChunkStreamer	The Chunk Streamer that created the instance of the ChunkStreamerUser.

Methods

ChunkStreamerUser.CreateCellString(ILODGroup, string, string)

protected virtual CellString CreateCellString(ILODGroup LODGroup, string extraDataToPrepend, string extraDataToAppend)

The method used to create the CellString object. By default it uses the Group Name from the ILODGroup objet, as well as the Naming Convention, UtilizesCellChunking, and StreamableGrid.IsStreamableGrid3D fields from the GridLODDetails property of the ILODGroup object. You can override to use different information, however do so with extreme caution only if you know what you are doing. The ILODGroup object passed in is the one passed to the ChunkStreamerUser constructor. To use a different group, call this method manually and pass in a different group, then use the returned CellString rather than the one from the CellString property.

Parameters

Name	Type	Description
LODGroup	ILODGroup	The ILODGroup to use to create the Cell String object.
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
A Cell String object

Awake()

protected void Awake()

Awake method for all Chunk Streamers. This method is where the background loading priority is set, if the Global Runtime Settings asset is configured to set it.

If you need to implement Awake related logic in your custom Chunk Streamers, override the AwakeExtended method.

AwakeExtended()

protected virtual void AwakeExtended()

Override to implement Awake related logic in your custom Chunk Streamers.

CreateNewUser(ILODGroup)

protected virtual ChunkStreamerUser CreateNewUser(ILODGroup LODGroup)

Method used to create a new user object during user registration. This can and usually should be overridden to return a custom user object. Each user represents a single LODGroup on a single World World Grouping.

Parameters

Name	Type	Description
LODGroup	ILODGroup	The lod group being registered.

Returns

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

DeRegister(int)

public void DeRegister(int userID)

A user can call this method to de register with the Chunk Streamer.

Parameters

Name	Type	Description
userID	int	The ID of the user to de register.

DetachAndUnloadChunksFromCells(List<WorldCell>, int)

public abstract IEnumerator<YieldInstruction> DetachAndUnloadChunksFromCells(List<WorldCell> cells, int userID)

When overridden in a derived class, detaches and unloads the objects associated with the input cells over a period of frames.

Please note that the list of World Cells passed in may need to be used by the calling method after this method finishes executing; as such, you should not remove World Cells or otherwise manipulate the list, as that will result in errors.

Also note that in some instances, the Chunk Set on the World Cell may have been re-used/taken from another World Cell, so if you need to access some data related to the chunk set, it is better to use an identifier from the underlying objects in the chunk set rather than data from the World Cell. This is especially true because the Endless Grid Cell value on the World Cell may not be accurate, therefore you should never use it as a key to store data.

Parameters

Name	Type	Description
cells	List<WorldCell>	The cells whose chunks need to be detached and unloaded.
userID	int	The ID of the user requesting the unload and detachment.

Returns

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

LoadAndAttachChunksToCells(List<WorldCell>, int)

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

When overridden in a derived class, loads and attaches the chunks associated with the input cells to the cells over a period of frames.

If you need to store some data about chunks in order to properly unload them later using DetachAndUnloadChunksFromCells, you should use a key related to the underlying chunk objects themselves rather than the World Cell. This is because the chunks may be passed between World Cells (if using Chunk Reuse or Pooling), so the World Cell the chunks were originally loaded for may not be the World Cells they are attached to when DetachAndUnloadChunksFromCells is called.

Parameters

Name	Type	Description
cells	List<WorldCell>	The cells whose chunks 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.

LoadAndAttachChunksToCellsInSingleFrame(List<WorldCell>, int)

public abstract void LoadAndAttachChunksToCellsInSingleFrame(List<WorldCell> cells, int userID)

When overridden in a derived class, loads and attaches the chunks associated with the input cells to the cells in a single frame.

If you need to store some data about chunks in order to properly unload them later using DetachAndUnloadChunksFromCells, you should use a key related to the underlying chunk objects themselves rather than the World Cell. This is because the chunks may be passed between World Cells (if using Chunk Reuse or Pooling), so the World Cell the chunks were originally loaded for may not be the World Cells they are attached to when DetachAndUnloadChunksFromCells is called.

Parameters

Name	Type	Description
cells	List<WorldCell>	The cells whose chunks need to be attached.
userID	int	The ID of the user requesting the attachment.

PerformSingleFrameAttachmentPreload(List<WorldCell>, int)

public virtual void PerformSingleFrameAttachmentPreload(List<WorldCell> cells, int userID)

Certain types of load methods require a frame to pass before objects are added to the scene (LoadLevelAdditive for example). In order to successfully execute the LoadAndAttachChunksToCellsInSingleFrame method, these load methods must "pre load" the objects in the frame before. This method is used to do that, but should only be called by the registered user when IsSingleFrameAttachmentPreloadRequired is true.

By default, this method does nothing, and you only need to provide your own implementation if pre loading is required (in which case, IsSingleFrameAttachmentPreloadRequired must also be overridden to return true.

If you need to store some data about chunks in order to properly unload them later using DetachAndUnloadChunksFromCells, you should use a key related to the underlying chunk objects themselves rather than the World Cell. This is because the chunks may be passed between World Cells (if using Chunk Reuse or Pooling), so the World Cell the chunks were originally loaded for may not be the World Cells they are attached to when DetachAndUnloadChunksFromCells is called.

Parameters

Name	Type	Description
cells	List<WorldCell>	The cells whose objects need to be pre loaded.
userID	int	The ID of the user requesting the pre load.

Register(ILODGroup, out int)

public void Register(ILODGroup LODGroup, out int userID)

A user can call this method to register with the Chunk Streamer. The userID must be stored by the user and passed in when calling the methods of the Chunk Streamer.

Parameters

Name	Type	Description
LODGroup	ILODGroup	The lod group being registered.
userID	int	An ID that is assigned to the user when this method is called. Each user has its own ChunkStreamerUser object created for it.