World Class

public void AddCellUsers(IList<Cell> cells, int groupingIndex, int lodIndex)

Sends in a request to add users to the list of specified cells. This method should only be used by advanced users, as in 99% of cases you should let the Active Grid class control the addition of cell users. If you do decide to use this method, keep the following in mind:

The World tallies all user requests (either add or remove) for World Cells. If the Active Grid sends in an add requests for a specific cell, then you send in an add requests for the same cell, a tally of 2 will exists for the cell. The cell is then loaded and will not be unloaded until the tally reaches 0. In this way, multiple users can lay claim to a cell, and rather than loading that cell multiple times, it is only loaded once.

This strategy introduces errors if you do not keep track of the users you have added to a cell, however. For every user you add, you will typically want to remove a user for the same cell at a later date. If you do not, the cell will likely never be unloaded.

Parameters

Exceptions

public void AddCellUsers(IList<LODCell> cells, int groupingIndex)

Sends in a request to add users to the list of specified cells, in the form of a list of LODCells. This method should only be used by advanced users, as in 99% of cases you should let the Active Grid class control the addition of cell users. If you do decide to use this method, keep the following in mind:

The World tallies all user requests (either add or remove) for World Cells. If the Active Grid sends in an add requests for a specific cell, then you send in an add requests for the same cell, a tally of 2 will exists for the cell. The cell is then loaded and will not be unloaded until the tally reaches 0. In this way, multiple users can lay claim to a cell, and rather than loading that cell multiple times, it is only loaded once.

This strategy introduces errors if you do not keep track of the users you have added to a cell, however. For every user you add, you will typically want to remove a user for the same cell at a later date. If you do not, the cell will likely never be unloaded.

Parameters

Exceptions

public void AddCellUsers(IList<WorldGroupingCell> cells)

Sends in a request to add World Cell users for the passed in cells, in the form of a list of WorldGroupingCells. This method should only be used by advanced users, as in 99% of cases you should let the Active Grid class control the addition of cell users. If you do decide to use this method, keep the following in mind:

The World tallies all user requests (either add or remove) for World Cells. If the Active Grid sends in an add requests for a specific cell, then you send in an add requests for the same cell, a tally of 2 will exists for the cell. The cell is then loaded and will not be unloaded until the tally reaches 0. In this way, multiple users can lay claim to a cell, and rather than loading that cell multiple times, it is only loaded once.

This strategy introduces errors if you do not keep track of the users you have added to a cell, however. For every user you add, you will typically want to remove a user for the same cell at a later date. If you do not, the cell will likely never be unloaded.

Please note, to save on performance, no error checking is done on the passed in World Grouping or LOD indexes, so please be sure that those values are valid!

Parameters

Exceptions

public void AddWorldGroupingListener(IWorldGroupingListener groupingListener, int groupingIndex)

Adds the IWorldGroupingListener to the World Grouping indicated by groupingIndex. Can be called before or after the World has been initialized.

DetermineMethodCalls and PrecomputeUseWithLODValues are called automatically when using this method.

Parameters

public Vector3Double CalculateShiftResultingFromNewOriginCell(Cell newOriginCell)

Calculates the amount the world would be shifted if the Origin Cell of the world was changed to a new Origin Cell. Note that this does not actually perform an Origin Cell Change.

This method merely calculates how much the world would be shifted if the passed in cell were made the Origin Cell.

This Origin Cell is always in reference to the Base Grouping (Grouping 1).

Parameters

Returns

Vector3Double
The amount of shift that would result from the Origin Cell change.

Exceptions

public void ChangeAllGroupNamesOnAllWorldGroupings(string[][] newGroupNames, Action<World> onCompletedCallback = null)

Changes the Group Names of all LOD's for the specified World Grouping (changes persistent with save data if World is persistent).

A rudimentary check is performed to try to catch instances when this method is called unecessarily. The check is performed separately for each World Grouping on the World, according to the following rules:

1) If all LODs on the World Grouping are already using the passed in Group Names, no Group Name change occurs for that Grouping (however the callback, if provided, is still invoked).
2) If only one LOD is not using the passed in Group Name for that LOD, only that LOD's Group Name is changed.
3) If more than one LOD is not using the passed in Group Name for those LODs, all LODs on the World Grouping are reset, regardless of whether each LOD is already using the passed in Group Name (as such, this may result in an unecessary refresh of the chunks on those LODs).

If you know only a few World Groupings need to be changed, it is better to use the method that targets a specific World Grouping.

If you know only a few LODs need to be changed, use the methods that target specific LODs on specific World Groupings.

The world is automatically refreshed and Asset Chunks changed out as a result of the Group Name changes, so this method should only be used when the world is hidden from the player (otherwise the player may see the change), and probably when the game is paused (so the player does not fall through the world).

Please note, all Group Name changes operate by performing LOD transitions from each World Cell currently belonging to the LOD of the World Grouping to a new World Cell of the same LOD but using the new Asset Chunks. This is important, as your custom World Grouping Listeners will only be notified of these updates if their IgnoreLODTransitions property is set to return false.

The operation is performed as a secondary operation using the World's update cycle, and as such if the World is currently in the process of being updated, or another secondary operation is in progress, those updates will be completed before this one begins execution. Once the new group names have been applied and Asset Chunks refreshed to use the new names, the onCompletedCallback action will be called.

Parameters

Exceptions

public void ChangeAllGroupNamesOnWorldGrouping(int groupingIndex, string[] newGroupNames, Action<World> onCompletedCallback = null)

Changes the Group Names of all LOD's for the specified World Grouping (changes persistent with save data if World is persistent).

A rudimentary check is performed to try to catch instances when this method is called unecessarily. This check adheres to the following rules:

1) If all LODs on the World Grouping are already using the passed in Group Names, no Group Name change occurs (however the callback, if provided, is still invoked).
2) If only one LOD is not using the passed in Group Name for that LOD, only that LOD's Group Name is changed.
3) If more than one LOD is not using the passed in Group Name for those LODs, Group Names for all LODs on the World Grouping are changed, regardless of whether each LOD is already using the passed in Group Name (as such, this may result in an unecessary refresh of the chunks on those LODs). If you know only a few LODs need to be changed, use multiple calls to the method that target specific LODs on the World Grouping.

The world is automatically refreshed as a result of the Group Name changes, so this method should only be used when the world is hidden from the player (otherwise the player may see the change), and probably when the game is paused (so the player does not fall through the world).

Please note, all Group Name changes operate by performing LOD transitions from each World Cell currently belonging to the LOD of the World Grouping to a new World Cell of the same LOD but using the new Asset Chunks. This is important, as your custom World Grouping Listeners will only be notified of these updates if their IgnoreLODTransitions property is set to return false.

The operation is performed as a secondary operation using the World's update cycle, and as such if the World is currently in the process of being updated, or another secondary operation is in progress, those updates will be completed before this one begins execution. Once the new group names have been applied and objects refreshed to use the new names, the onCompletedCallback action will be called.

Parameters

Exceptions

public void ChangeGroupName(string newGroupName, Action<World> onCompletedCallback = null)

Changes the Group Name of LOD Group 1 on World Grouping 1 (change persistent with save data if World is persistent).

A check is performed to ensure the current Group Name is not equal to the passed in Group Name. Nothing will happen if they are the same, although the callback (if provided) will still be invoked.

The world is automatically refreshed as a result of the Group Name change, so this method should only be used when the world is hidden from the player (otherwise the player may see the change), and probably when the game is paused (so the player does not fall through the world).

Please note, all Group Name changes operate by performing LOD transitions from each World Cell currently belonging to the LOD of the World Grouping to a new World Cell of the same LOD but using the new chunks. This is important, as your custom World Grouping Listeners will only be notified of these updates if their IgnoreLODTransitions property is set to return false.

The operation is performed as a secondary operation using the World's update cycle, and as such if the World is currently in the process of being updated, or another secondary operation is in progress, those updates will be completed before this one begins execution. Once the new Group Name has been applied and objects refreshed to use that name, the onCompletedCallback action will be called.

Parameters

Exceptions

public void ChangeGroupName(int groupingIndex, int lodIndex, string newGroupName, Action<World> onCompletedCallback = null)

Changes the Group Name of the specified LOD for the specified World Grouping (change persistent with save data if World is persistent).

A check is performed to ensure the current Group Name is not equal to the passed in Group Name. Nothing will happen if they are the same, although the callback (if provided) will still be invoked.

The world is automatically refreshed as a result of the Group Name change, so this method should only be used when the world is hidden from the player (otherwise the player may see the change), and probably when the game is paused (so the player does not fall through the world).

Please note, all Group Name changes operate by performing LOD transitions from each World Cell currently belonging to the LOD of the World Grouping to a new World Cell of the same LOD but using the new chunks. This is important, as your custom World Grouping Listeners will only be notified of these updates if their IgnoreLODTransitions property is set to return false.

The operation is performed as a secondary operation using the World's update cycle, and as such if the World is currently in the process of being updated, or another secondary operation is in progress, those updates will be completed before this one begins execution. Once the new Group Name has been applied and objects refreshed to use that name, the onCompletedCallback action will be called.

Parameters

Exceptions

public bool ChangeOriginCell(Cell newOriginCell)

Changes the Origin Cell of the World. The update does not occur immediately but rather during the natural World Update cycle. If you need to know when the world update containing the Origin Cell update has finished, you can register a callback method with the World via the RegisterOnUserRequestsFulfilledCallback method. The callback method will be invoked once the Origin Cell change has been completed.

In order to ensure the change can be made, you should query the IsExplicitOriginCellChangeBlocked property and ensure it is false before calling the method. If you decide to forsake this strategy and the update fails, a warning message will be printed to the console and the method will return false.

Setting the Origin Cell manually may have unintended consequences, especially when using an Active Grid. Therefore, it is recommended for advanced users only! Generally it is better to let the Active Grid change the Origin Cell, either automatically when the player crosses a reset boundary, or manually as a result of one its other methods being called, like TryMovePlayerAndChangeOriginCellOfWorld

Parameters

Returns

bool
True if Origin Cell will be changed, false otherwise. If true, remember that the actual change does not occur immediately, but rather will be caried out during a normal World update cycle.

public void ClampOriginCells(ReadOnlyArray<Cell> newOriginCellValues, ReadOnlyArray<Cell> clampingOffset, bool updateHiearchyOrganizers, bool notifyUsersInSingleFrame, Action<World> onCompletedCallback = null)

Clamps the origin cells of the world. Clamping can only occur when the world utilizes one or more endless axes. The process of clamping takes Origin Cell values that fall outside the range of the dimensions of the Streamable Grid used by the World component and attempts to shift them so they DO fall within the Streamable Grid dimensions. All World Cells currently loaded are offset by the same offset used to make the new Origin Cell fall within the bounds of the Streamable Grid. This process is performed for each World Grouping on the World.

For example, imagine you have a Streamable Grid with 2 rows. On a world with non endless rows, cells within this grid (upon being loaded into the scene) can have one of two values for their row, 1 or 2, which match perfectly with their Streamable Grid indexes. However, on an world with endless rows, once the world repeats on the row axis, the cells will have values 3 and 4, 5 and 6, 7 and 8, and so on, until infinity. And of course the world can repeat in the opposite direciton as well and have values like 0 and -1, -2 and -3, and so on. The Origin Cell of the world uses this Endless Grid, for various reasons.

The Origin Cell of course cannot reach into infinity, since it is being represented by a fixed max/min value data type (in this case, integer), so astute observers will note that this system of handling things has the (incredibly minute) chance of causing issues in some rare cases (when the player plays the game for a long, long time). As such, Origin Clamping is an option to rectify the problem (and please, do consider your particular use case to determine if this problem is even possible!!).

If our Origin Cell has a Row of 5 and the Streamable Grid has 2 rows, we can note that this row 5 cell is equivalent to a row 1 cell. The goal of clamping, then, is to take the row 5 Origin Cell and shift it so its value is 1. In this case, we must shift 5 by -4 to get it to 1. Easy, right?

Yes and no. While the Origin Cell has been shifted, any data that is dependent on the Origin Cell is now invalidated, as the data is dependent on the Origin Cell having a row value of 5. Therefore, we must also shift any data that was dependent on the origin row being 5 by -4 to bring that data in line with our Origin Cell shift.

As such, this method will automatically notify World Users (registered with the World via the Register method) of the clamping, so that data can be updated (notification occurs in full before the call back is triggered).

Because the clamping operation can only be initiated manually by you, the developer, World Users are not queried to make sure the clamping operation can proceed. This differs from how normal Origin Cell changes occur. This decision was made because you should be in full control of all World Users in your game; therefore, you should know if the clamping operation would interfere with any operations the users have in progress, and you can delay the clamping operation until after those operations complete. For example, it is usually a bad idea to perform a clamping operation while a save is in progress!

Parameters

public WorldCell CreateWorldCell(Cell endlessGridCell, int LOD, int groupingIndex)

Creates a World Cell based on the passed in endlessGridCell, LOD, and World Grouping index. The data will be properly set, and the World Cell will be setup to be able to receive chunk attachments, however no objects will actually be associated with this Cell.

There are few use cases where you would need to use this method, one of them being when creating custom Chunk Managers that have pooled objects no longer associated with a World Cell that you need to unload.

In that case, in order to unload them properly with an existing Chunk Streamer, you can generate a sort of dummy World Cell using this method, attach your objects to the cell, and then use the DetachAndUnloadChunksFromCells method of the Chunk Streamer to unload the objects.

When creating a World Cell using this method, it is not used internallly by SAM at all. It's for your own use only. The objects are generated using the internal pool of World Cells, so the type of the World Cell may be a WorldCellWithTerrain if the LOD and World Grouping index you pass reference an LOD that utilizes terrain.

The internal array that stores game objects within the World Cell will be configured properly so that you can attach chunks to the cell via the WorldCell.AttachChunkToCell method.

You can return the WorldCell for pooling after you are done with it by calling the ReturnWorldCellForPooling method.

Note, if you have created a World Cell already for an Endless Grid Cell, and you need another World Cell for the same Endless Grid Cell, it is faster to use the CreateWorldCellCopy method rather than this one (assuming you have not returned the first World Cell).

Parameters

Returns

WorldCell
The created World Cell.

Exceptions

public WorldCell CreateWorldCellCopy(WorldCell worldCell)

Creates a World Cell as a copy of another World Cell. If there are chunks associated with the World Cell, they will not be copied over to the new cell, however the new cell will be properly setup to be able to store the proper number of Asset Chunks.

There are few use cases where you would need to use this method, one of them being when creating custom Chunk Managers that have pooled objects no longer associated with a World Cell that you need to unload.

In that case, in order to unload them properly with an existing Chunk Streamer, you can generate a sort of dummy World Cell using the CreateWorldCell method, and then for each additional World Cell you need to represent the same Endless Grid Cell, use this method to generate a new World Cell. This is faster than using CreateWorldCell multiple times for the same Endless Grid Cell.

When creating a World Cell using this method, it is not used internallly by SAM at all. It's for your own use only. The World Cell is generated using the internal pool of World Cells, so the type of the World Cell may be a WorldCellWithTerrain if the LOD and World Grouping index you pass in reference an LOD that utilizes terrain.

The internal array that stores Asset Chunks within the World Cell will be configured properly so that you can attach chunks to the cell via the WorldCell.AttachChunkToCell method.

You can return the WorldCell for pooling after you are done with it by calling the ReturnWorldCellForPooling method.

Parameters

Returns

WorldCell
The created World Cell.

Exceptions

public void DeRegister(int registrationID)

Deregister a World User from the World. Note that if the user is Currently "prepared" for an Origin Cell change, they will NOT receive notification from the World once the Origin Cell change is completed.

Parameters

public Cell DetermineSubGroupingOriginCellFromBaseGroupingOriginCell(int subGroupingIndex, Cell theoreticalOriginCell)

Can be used to determine what Origin Cell a Sub World Grouping would have if the if the Origin Cell of the Base Grouping were changed to the theoreticalOriginCell.

The Sub Grouping Origin Cell is always the Endless Grid Cell on the Sub Grouping that contains the position of the Origin Cell from the Base Grouping (the bottom left most point).

The position of the Sub Grouping's Origin Cell is not always the same as the position of the Base Grouping's Origin Cell, so if you need to perform some calculation that uses the Sub Grouping's Origin Cell Position, you should use one of the other DetermineSubGroupingOriginCellFromBaseGroupingOriginCell methods that has an out positionOfSubGroupingOriginCell paramater.

If you need to find out this info before the World has been initialized, use the pre init safe method called DetermineSubGroupingOriginCellFromBaseGroupingOriginCell_PreInitSafe instead (will be slower than this method).

Parameters

Returns

Cell
The one based Sub Grouping Origin Cell as determined by the method.

Exceptions

public Cell DetermineSubGroupingOriginCellFromBaseGroupingOriginCell(int subGroupingIndex, Cell theoreticalOriginCell, out GridValues<double> positionOfSubGroupingOriginCell)

Can be used to determine what Origin Cell a Sub World Grouping would have if the if the Origin Cell of the Base Grouping were changed to the theoreticalOriginCell.

The Sub Grouping Origin Cell is always the Endless Grid Cell on the Sub Grouping that contains the position of the Origin Cell from the Base Grouping (the bottom left most point).

The position of the Sub Grouping's Origin Cell is not always the same as the position of the Base Grouping's Origin Cell, so you should use the out positionOfSubGroupingOriginCell value in any calculations involving the Sub Grouping's Origin Cell Position.

If you do not need this information, you should use the other DetermineSubGroupingOriginCellFromBaseGroupingOriginCell method that does not provide this information, as it will be slightly faster.

This method can only be called after the World has been initialized. If you need a similar method that works before the World has been initialized, use the pre init safe method called DetermineSubGroupingOriginCellFromBaseGroupingOriginCell_PreInitSafe instead (will be slower than this method).

Parameters

Returns

Cell
The one based Sub Grouping Origin Cell as determined by the method.

Exceptions

public Cell DetermineSubGroupingOriginCellFromBaseGroupingOriginCell(int subGroupingIndex, Cell theoreticalOriginCell, out Vector3Double positionOfSubGroupingOriginCell)

Can be used to determine what Origin Cell a Sub World Grouping would have if the if the Origin Cell of the Base Grouping were changed to the theoreticalOriginCell.

The Sub Grouping Origin Cell is always the Endless Grid Cell on the Sub Grouping that contains the position of the Origin Cell from the Base Grouping (the bottom left most point).

The position of the Sub Grouping's Origin Cell is not always the same as the position of the Base Grouping's Origin Cell, so you should use the out positionOfSubGroupingOriginCell value in any calculations involving the Sub Grouping's Origin Cell Position.

If you do not need this information, you should use the other DetermineSubGroupingOriginCellFromBaseGroupingOriginCell method that does not provide this information, as it will be slightly faster.

This method can only be called after the World has been initialized. If you need a similar method that works before the World has been initialized, use the pre init safe method called DetermineSubGroupingOriginCellFromBaseGroupingOriginCell_PreInitSafe instead (will be slower than this method).

Parameters

Returns

Cell
The one based Sub Grouping Origin Cell as determined by the method.

Exceptions

public Cell DetermineSubGroupingOriginCellFromBaseGroupingOriginCell_PreInitSafe(int subGroupingIndex, Cell theoreticalOriginCell)

Similar to DetermineSubGroupingOriginCellFromBaseGroupingOriginCell except this method is safe to use before the World and its Streamable Grid have been initialized. See that method for more info.

Note that if you know the World has been initialized, you are better off using the method listed above, as it will be a little bit faster.

Parameters

Returns

Cell
The one based Sub Grouping Origin Cell as determined by the method.

public Cell DetermineSubGroupingOriginCellFromBaseGroupingOriginCell_PreInitSafe(int subGroupingIndex, Cell theoreticalOriginCell, out GridValues<double> positionOfSubGroupingOriginCell)

Similar to DetermineSubGroupingOriginCellFromBaseGroupingOriginCell except this method is safe to use before the World and its Streamable Grid have been initialized. See that method for more info.

Note that if you know the World has been initialized, you are better off using the method listed above, as it will be a little bit faster.

Parameters

Returns

Cell
The one based Sub Grouping Origin Cell as determined by the method.

public Cell DetermineSubGroupingOriginCellFromBaseGroupingOriginCell_PreInitSafe(int subGroupingIndex, Cell theoreticalOriginCell, out Vector3Double positionOfSubGroupingOriginCell)

Similar to DetermineSubGroupingOriginCellFromBaseGroupingOriginCell except this method is safe to use before the World and its Streamable Grid have been initialized. See that method for more info.

Note that if you know the World has been initialized, you are better off using the method listed above, as it will be a little bit faster.

Parameters

Returns

Cell
The one based Sub Grouping Origin Cell as determined by the method.

public Cell FindEndlessGridCellPositionIsIn(Vector3Double position, int groupingIndex)

Finds the Endless Grid Cell that the specified position falls within on this World (given the current Origin Cell of the World).

Parameters

Returns

Cell
The Endless Grid Cell the position falls within.

Exceptions

public Cell FindEndlessGridCellPositionIsIn(Vector3Double position, int groupingIndex, out Vector3Double endlessGridCellPosition)

Finds the Endless Grid Cell that the specified position falls within. Also outputs the current position of that Endless Grid Cell.

Parameters

Returns

Cell
The Endless Grid Cell the position falls within.

Exceptions

public Cell FindEndlessGridCellPositionIsInUsingInitialOriginCell(Vector3Double position, int groupingIndex)

Finds the Endless Grid Cell that the input position would be in if the Origin Cell of this world were equal to its initial Origin Cell (as set in the inspector of your World).

Note that if you use clamping, the endless cell indexes will be adjusted, so you cannot rely on the cell indexes remaining constant. For a non endless world clamping cannot be used therefore it is not an issue.

Finally, keep in mind that the Endless Grid Cell is in reference to the World Grouping you specify via groupingIndex, but the Origin Cell is always in reference to the Base Grouping (Grouping 1).

Parameters

Returns

Cell
The Endless Grid Cell the position would be in if the initial Origin Cell was the Origin Cell of this world.

Exceptions

public Cell FindEndlessGridCellPositionIsInUsingTheoreticalOriginCell(Vector3Double position, Cell theoreticalOriginCell, int groupingIndex)

Finds the Endless Grid Cell that the input position would be in if the Origin Cell of this world were equal to the theoretical Origin Cell provided.

This is useful if you're about to change the Origin Cell via the Active Grid's TryMovePlayerAndChangeOriginCellOfWorld method and need to calculate some data based on the new Origin Cell.

Finally, keep in mind that the Endless Grid Cell is in reference to the World Grouping you specify via groupingIndex, but the Origin Cell is always in reference to the Base Grouping (Grouping 1).

Parameters

Returns

Cell
The Endless Grid Cell the position would be in if the theoretical Origin Cell was the Origin Cell of this world.

Exceptions

public Cell FindEndlessGridCellPositionIsIn_PreInitSafe(Vector3Double position, Cell theoreticalOriginCell, int groupingIndex)

Finds the Endless Grid Cell (One Based) that the specified position falls within, for the World Grouping specified. You must specify a theoretical Origin Cell to use in the calculation, which is always in reference to the Base World Grouping, even if the grouping index specified is a Sub Grouping (2+).

This method is safe to call at any time, even before the World has been initialized. This means it can even be called on a World prototype. However, do keep in mind that the method will be slower than the method of the same name that is not pre init safe, therefore if you know the World has been intialized, you should use that method rather than this one.

Parameters

Returns

Cell
The Endless Grid Cell the position falls within.

public JobHandle FindEndlessGridCellsPositionsAreIn(NativeArray<Vector3Double> positions, NativeArray<Cell> cells, int groupingIndex, bool initializeWorkImmediately)

Can be used to find the endless grid cells that a batch of positions fall within. You can either queue up another Job that is dependent on the returned JobHandle, or use JobHandle.IsCompleted to ensure the job is completed (and then call JobHandle.Complete() after). The cells array data will only be valid after the job has completed!

Parameters

Returns

JobHandle
A Job Handle that will have been scheduled. Use IsCompleted to check if it is complete, then call Complete afterwards before accessing the data in the cells array.

Exceptions

public Cell FindStreamableGridCellPositionIsIn(Vector3Double position, int groupingIndex)

Finds the Streamable Grid Cell that the specified position falls within on this World (given the current Origin Cell of the World).

This uses the current Origin Cell of the World in the calculation. If you need to use the initial Origin Cell of the World, or a theoretical Origin Cell, use FindEndlessGridCellPositionIsInUsingInitialOriginCell or FindEndlessGridCellPositionIsInUsingTheoreticalOriginCell, then covert the Endless Grid Cell returned to a Streamable Grid Cell using the Streamable Grid's ConvertCellOnEndlessGridToCellOnStreamableGrid method.

Parameters

Returns

Cell
The Streamable Grid Cell the position falls within.

Exceptions

public Cell FindStreamableGridCellPositionIsIn_PreInitSafe(Vector3Double position, Cell theoreticalOriginCell, int groupingIndex)

Finds the Streamable Grid Cell (One Based) that the specified position falls within, for the World Grouping specified. You must specify a theoretical Origin Cell to use in the calculation, which is always in reference to the Base World Grouping, even if the grouping index specified is a Sub Grouping (2+).

This method is safe to call at any time, even before the World has been initialized. This means it can even be called on a World prototype. However, do keep in mind that the method will be slower than the method of the same name that is not pre init safe, therefore if you know the World has been intialized, you should use that method rather than this one.

Parameters

Returns

Cell
The Streamable Grid Cell the position falls within.

public JobHandle FindStreamableGridCellsPositionsAreIn(NativeArray<Vector3Double> positions, NativeArray<Cell> cells, int groupingIndex, bool initializeWorkImmediately)

Can be used to find the streamable grid cells that a batch of positions fall within. You can either queue up another Job that is dependent on the returned JobHandle, or use JobHandle.IsCompleted to ensure the job is completed (and then call JobHandle.Complete() after). The cells array data will only be valid after the job has completed!

Parameters

Returns

JobHandle
A Job Handle that will have been scheduled. Use IsCompleted to check if it is complete, then call Complete afterwards before accessing the data in the cells array.

Exceptions

public void GetAllLoadedWorldCells(int groupingIndex, List<WorldCell> addCellsTo)

Adds all loaded World Cells for the specified Grouping to the passed in addCellsTo list.

Note that this method gets the currently loaded World Cells as contained in the Grouping's internal dictionary. If the Grouping is in the process of being updated, the World Cells' state cannot be predicted (they may be missing Asset Chunks, or those Asset Chunks may be in a state you do not expect, for example).

As such, it is usually best to call this method only when the World is not currently being updated, which you can check using the IsUpdateInProgress property.

However, the best approach for tracking World Cells is to use a World Grouping Listener, as you can be confident about the state of the World Cells (depending on which method you use for the tracking), and can accurately track when World Cells are added and removed.

World Cells returned via this method can be removed at a moments notice, so you should only make use of them for a very short period of time.

Parameters

public Bounds GetBoundsOfEndlessGridCell(Cell endlessGridCell, int groupingIndex)

Get the bounds of an Endless Grid Cell (can be any value).

Parameters

Returns

Bounds
The bounds of the cell.

Exceptions

public void GetChunkManagerAndUserID(int groupingIndex, int LOD, out ChunkManager chunkManager, out int managerUserID)

Gets the Chunk Manager and manager user ID for the given LOD on the given World Grouping. It is very unlikely you will need to access the manager for any reason, as SAM already automates all of the interactions with it. In fact, it is discouraged that you interact with it. However, if for some rare reason you need to access it, you can do so with this method.

Parameters

public void GetChunkStreamerAndID(int groupingIndex, int LOD, out ChunkStreamer ChunkStreamer, out int streamerUserID)

Gets the Chunk Streamer and User ID for the given LOD Group on the given World Grouping. It is very unlikely you will need to access the Streamer for any reason, as SAM already automates all of the interactions with it. In fact, it is discouraged that you interact with it. This method primarily exist to be used by the Addressable Prefab and Scene Streamer, however if you need to use it for some other reason, you can.

Parameters

public CellDimensions GetDimensionsOfEndlessGridCell(Cell endlessGridCell, int groupingIndex)

Get the cell dimensions of an Endless Grid Cell (can be any value).

Parameters

Returns

CellDimensions
The cell dimensions of the cell.

Exceptions

public string GetLODGroupName(int groupingIndex, int lodIndex)

Gets the name of the LOD Group (specified by lodIndex) on the World Grouping (specified by groupingIndex). This is the current GroupName, which will reflect changes made by the Group Name changing methods.

Parameters

Returns

string
The Group Name of the LOD.

public Cell GetOriginCellOfWorldGrouping(int groupingIndex)

Gets the current Origin Cell of the World Grouping associated with the groupingIndex. Note that the Base Grouping's Origin Cell is equivalent to the World's Origin Cell, which can be viewed in the World's Inspector within the Origin Settings tab. The Origin Cell's of Sub Groupings are only caclculated at runtime, however they can be viewed within the Sub Groupings General Settings window.

Parameters

Returns

Cell
The one based Origin Cell of the World Grouping.

Exceptions

public Vector3Double GetOriginCellPositionOfWorldGrouping(int groupingIndex)

Gets the current Origin Cell Position of the World Grouping. Note that the Base Grouping's Origin Cell Position will be equal to either the position of the game object the World is on, or the position set in the World's inspector. The Origin Cell Position of Sub Groupings may be equal to this same position, or it may be slightly offset, depending on whether the Origin Cell of the Sub Grouping lines up with the Origin Cell of the Base Grouping.

Parameters

Returns

Vector3Double
The Origin Cell position of the World Grouping.

Exceptions

public void GetPositionAndDimensionsOfEndlessGridCell(Cell endlessGridCell, int groupingIndex, out Vector3Double positionOfCell, out CellDimensions dimensionsOfCell))

Retrieves the position and dimensions of an Endless Grid Cell.

Parameters

Exceptions

public Vector3Double GetPositionOfEndlessGridCell(Cell endlessGridCell, int groupingIndex)

Retrieves the position of an Endless Grid Cell. Unlike Streamable Grid cells, the indexes of this cell can be any value.

Parameters

Returns

Vector3Double
The position of the cell.

Exceptions

public Vector3Double GetPositionOfEndlessGridCellUsingInitialOriginCell(Cell endlessGridCell, int groupingIndex)

Gets the position of an Endless Grid Cell as if the Origin Cell of the World were still the initial Origin Cell (as set in the inspector of your World).

Note that the Endless Grid Cell is in reference to the World Grouping you specify via groupingIndex, but the Origin Cell is always in reference to the Base Grouping (Grouping 1).

Parameters

Returns

Vector3Double
The position of the Endless Grid Cell.

Exceptions

public Vector3Double GetPositionOfEndlessGridCellUsingTheoreticalOriginCell(Cell endlessGridCell, Cell theoreticalOriginCell, int groupingIndex)

Gets the position that an Endless Grid Cell would be at if the Origin Cell of the Base Grouping/World were set to a theoreticaly Origin Cell.

Note that the Endless Grid Cell is in reference to the World Grouping you specify via groupingIndex, but the Origin Cell is always in reference to the Base Grouping.

Parameters

Returns

Vector3Double
The (theoretical) position of the Endless Grid Cell.

Exceptions

public void GetRowAndLayerPositionOfCell(Vector3Double cellPosition, int groupingIndex, out double rowPosition, out double layerPosition)

Get the row and layer position of a Cell (can be a World Cell, Endless Grid Cell, or Streamable Grid Cell) given it position in the scene. This is useful because the row and layer positions may be using the y or z components of the Vector3Double, depending on the Axes set on the World Grouping's Streamable Grid.

When the Axes are set to Two_Dimensional_On_XZ_Axes or Three_Dimensional, the row position uses the z component and layer position uses y component of cellPosition.

When the Axes are set to Two_Dimensional_On_XY_Axes the row position uses y component and layer position uses the z component of cellPosition.

Parameters

Exceptions

public StreamableGrid GetStreamableGridOfGrouping_PreInitSafe(int groupingIndex)

Gets the Streamable Grid associated with a specific World Grouping.

Parameters

Returns

StreamableGrid
The Streamable Grid associated with the World Grouping.

public void GetWorldCellsInAxisAlignedBoundingCube(int groupingIndex, Vector3Double min, Vector3Double max, List<WorldCell> worldCellsInArea)

Gets all World Cells on the indicated World Grouping that fall within an axis aligned bounding cube within the scene. This can be used to determine which cells fall within an area of the scene, such as within the Camera's view point (obviously it will be approximate, since the camera viewport is not a cube).

Unlike the other GetWorldCellsInAxisAlignedBoundingCube method, this one is LOD agnostic. All World Cells belonging to the World Grouping will be added to the list, regardless of which LOD they have in use (so long as they fall within the cube's area).

Parameters

Exceptions

public void GetWorldCellsInAxisAlignedBoundingCube(int groupingIndex, int LOD, Vector3Double min, Vector3Double max, List<WorldCell> worldCellsInArea)

Gets all World Cells on the indicated World Grouping and LOD that fall within an axis aligned bounding cube within the scene. This can be used to determine which cells fall within an area of the scene, such as within the Camera's view point (obviously it will be approximate, since the camera viewport is not a cube).

Parameters

Exceptions

public string GetWorldRegionName(int worldRegionNumber)

Gets the name of the World Region whose number in the World inspector matches the worldRegionNumber passed in. For performance reasons this method does not do any error checking, therefore please be absolutely sure that the number passed in is valid (not less than 1 and not greater than the number of World Regions on this world).

Parameters

Returns

string
The name of the World Region.

public Cell GetWorldRegionOriginCell(int worldRegionNumber)

Gets the one based Origin Cell of the World Region whose number in the World inspector matches the worldRegionNumber passed in. For performance reasons this method does not do any error checking, therefore please be absolutely sure that the number passed in is valid (not less than 1 and not greater than the number of World Regions on this world).

Parameters

Returns

Cell
The Origin Cell of the World Region.

public bool IsGrouping3D_PreInitSafe(int groupingIndex)

Can be used to query whether a particular World Grouping is three dimensional (it's Streamable Grid uses the Three_Dimensional Axes type).

Parameters

Returns

bool
True if the World Grouping is 3D, false otherwise.

public bool IsWorldGroupingUpdatingCells(int grouping)

Queries the World to determine if the given World Grouping is currently performing an update to its collection of World Cells. Generally speaking, methods that retrieve World Cells from this World should only be performed for World Groupings that this method returns false for. Otherwise, the cell you are trying to retrieve may have been removed from the Worlds internal collection of cells, even though it still 'appears' in the scene, or the cell may have not been fully loaded yet, meaning the cell is retrievable even though it might not 'appear' in the scene. When the value returns true, it means all cells belonging to the given World Grouping that exist in the internal collection of cells are in their correct state, and all cells appearing in the scene are correctly contained within the World's internal collection of cells.

Rather than retrieving World Cells directly from the World, however, we recommend using World Grouping Listeners, as you can be more assured of the World Cells' status.

Parameters

Returns

bool
See summary above.

public void LoadWorldRegion(int worldRegionNumber, bool changeOriginCell, bool clearLoadedWorldRegions)

Loads the World Region matching the input worldRegionNumber.

This method will not give you any insight into when the cells are actually loaded. If you need to know when the World has processed the World Region and updated itself to reflect changes resulting from the World Region being loaded, you can register a callback method with the World via the RegisterOnUserRequestsFulfilledCallback method. The callback method will be invoked once the World has completed an update cycle containing changes that resulted from the load operation.

This strategy also allows you to load and unload multiple regions in one World Update cycle, and be notified when all regions are loaded and/or unloaded. To do so, simply call the LoadWorldRegion and UnloadWorldRegion methods for each region that you want to load or unload before calling the WaitForUpdateThatIncludesRequests method (all must be called in the same frame).

Parameters

Exceptions

public void LoadWorldRegion(string worldRegionName, bool changeOriginCell, bool clearLoadedWorldRegions)

Loads the World Region matching the input worldRegionName.

This method will not give you any insight into when the cells are actually loaded. If you need to know when the World has processed the World Region and updated itself to reflect changes resulting from the World Region being loaded, you can register a callback method with the World via the RegisterOnUserRequestsFulfilledCallback method. The callback method will be invoked once the World has completed an update cycle containing changes that resulted from the load operation.

This strategy also allows you to load and unload multiple regions in one World Update cycle, and be notified when all regions are loaded and/or unloaded. To do so, simply call the LoadWorldRegion and UnloadWorldRegion methods for each region that you want to load or unload before calling the WaitForUpdateThatIncludesRequests method (all must be called in the same frame).

Parameters

Exceptions

public void PreInitialize_EnableWorldRegionAutoLoad(List<int> worldRegionNumbers, bool overwriteRegionsInPersistentData)

You can use this method to enable auto loading of World Regions so that they are loaded when the World is initialized (this is in addition to any Regions that have Auto Load enabled in the World's inspector).

Note that unlike the runtime LoadWorldRegion methods, you cannot set clearLoadedWorldRegions since no World Regions are loaded at this point. The Origin Cell data in the World Regions will also be ignored when using this method, so you must use PreInitialize_SetOriginCell if you want to make use of this data.

This must be called before the World has been initialized.

Parameters

Exceptions

public void PreInitialize_EnableWorldRegionAutoLoad(List<string> worldRegionNames, bool overwriteRegionsInPersistentData)

You can use this method to enable auto loading of World Regions so that they are loaded when the World is initialized (this is in addition to any Regions that have Auto Load enabled in the World's inspector).

Note that unlike the runtime LoadWorldRegion methods, you cannot set clearLoadedWorldRegions since no World Regions are loaded at this point. The Origin Cell data in the World Regions will also be ignored when using this method, so you must use PreInitialize_SetOriginCell if you want to make use of this data.

This must be called before the World has been initialized.

Parameters

Exceptions

public void PreInitialize_SetGroupName(int groupingIndex, int lodIndex, string newGroupName, bool overwriteNameFromPersistentData)

Changes the Group Name of the specified World Grouping's LOD Group, allowing for the initial Asset Chunks that are loaded to be different than what they normally are.

The main use of this will be to implement custom loading rather than making use of the automatic IPersistentDataController class, if you need to save different data in different places (on the server, on a file on the users system, etc.). Note, if all your data is stored in the same place, you are better off using a custom class that derives from IPersistentDataController, and then set it up to save data to that location (as Group Name changes are automatically tracked and saved with persistent data).

This must be called before the World has been initialized.

Parameters

Exceptions

public void PreInitialize_SetGroupName(string newGroupName, bool overwriteNameFromPersistentData)

Changes the Group Name of Grouping 1's (the Base Grouping) LOD Group 1, allowing for the initial Asset Chunks that are loaded to be different than what they normally are.

The main use of this will be to implement custom loading rather than making use of the automatic IPersistentDataController class, if you need to save different data in different places (on the server, on a file on the users system, etc.). Note, if all your data is stored in the same place, you are better off using a custom class that derives from IPersistentDataController, and then set it up to save data to that location (as Group Name changes are automatically tracked and saved with persistent data).

This must be called before the World has been initialized.

Parameters

Exceptions

public void PreInitialize_SetGroupNamesForAllLODGroupsOnWorldGrouping( int groupingIndex, string[] newGroupNames, bool ignoreNamesFromPersistentData, bool applyOverwriteRuleToNullNames)

Changes the Group Names of all LOD Groups on the specified World Grouping, allowing for the initial Asset Chunks that are loaded to be different than what they normally are.

If you only want to update some of the LOD's, set the names of LOD's that you don't want to update to null.

The main use of this will be to implement custom loading rather than making use of the automatic IPersistentDataController class, if you need to save different data in different places (on the server, on a file on the users system, etc.). Note, if all your data is stored in the same place, you are better off using a custom class that derives from IPersistentDataController, and then set it up to save data to that location (as Group Name changes are automatically tracked and saved with persistent data).

This must be called before the World has been initialized.

Parameters

Exceptions

public void PreInitialize_SetGroupNamesForAllWorldGroupings(string[][] newGroupNames, bool ignoreNamesFromPersistentData, bool applyOverwriteRuleToNullNames)

Changes the Group Names of all LOD Groups on all World Groupings of this world, allowing for the initial Asset Chunks that are loaded to be different than what they normally are.

If you only want to update some of the LOD Groups, set the names of LOD Groups that you don't want to update to null (as Group Name changes are automatically tracked and saved with persistent data).

The main use of this will be to implement custom loading rather than making use of the automatic IPersistentDataController class, if you need to save different data in different places (on the server, on a file on the users system, etc.). Note, if all your data is stored in the same place, you are better off using a custom class that derives from IPersistentDataController, and then set it up to save data to that location (as Group Name changes are automatically tracked and saved with persistent data).

This must be called before the World has been initialized.

Parameters

Exceptions

public void PreInitialize_SetOriginCell(Cell newOriginCell, bool overwriteOriginCellFromPersistentData)

Changes the Origin Cell that this World will initially use. This must be called before the World has been initialized.

The Origin Cell set is the Origin Cell of the base World Grouping. There is no need to set the Origin Cell of each sub World Grouping, as they are automatically set based on the Origin Cell of the base World Grouping.

The main use of this will be to implement custom loading rather than making use of the automatic IPersistentDataController class, if you need to save different data in different places (on the server, on a file on the users system, etc.). Note, if all your data is stored in the same place, you are better off using a custom class that derives from IPersistentDataController, and then set it up to save data to that location (as Origin Cell changes are automatically tracked and saved with persistent data)..

For methods or features that utilize the starting Origin Cell to calculate data, this Origin Cell will not be used. Instead, the origin Origin Cell as set in the inspector of your World will be used. Such data might be used to calculate the total offset of current world from the original world. For instance, imagine you have a 2D world with 2k x 2k cells at origin 0,0 in the scene, whose starting Origin Cell was ow = 6, column = 6, but whose current Origin Cell is row = 8, column = 8. In order to calculate the total offset of the world, we need to know that cell 6,6 is the starting Origin Cell and is currently positioned at -4000, -4000. Therefore, the total offset of the world is -4000, -4000. This is handy to know when dealing with 3rd part tools that utilize a root transform to track how much the world has been offset.

This must be called before the World has been initialized.

Parameters

Exceptions

public void PreInitialize_SetWorldOrigin(Vector3Double newWorldOrigin, bool overwriteWorldOriginFromPersistentData)

Changes the World's Origin Position.

This is the only way to change the World Origin position. Once the World is initialized, it's position cannot be modified.

This must be called before the World has been initialized.

Parameters

Exceptions

public void Register(IWorldUser user, out int registrationID)

Register an IWorldUser user with the World. Users may register in order to receive callbacks when the Origin Cell is changed or clamped, when the World is destroyed, or if they need to delay Origin Cell changes. See the IWorldUser page for more information.

Parameters

public void RegisterOnUserRequestsFulfilledCallback(Action<World> OnRequestsFulfilledCallback)

You can use this method to register a callback method that will be invoked after any outside requests to add/remove users (including loading/unloading World Regions) or change the Origin Cell have been fulfilled by the World. Basically, once a World Updated is completed that has taken into account the requests or Origin Cell change, the callback will be invoked.

In order to use the method for that use case, it is imperative that you call this method immediately after sending in all add/remove requests (using AddCellUsers and RemoveCellUsers), load world region calls, or change the Origin Cell, within the same frame. Otherwise there is no gaurantee that the method will be able to track the update that includes those requests.

When used correctly, the callback will only be invoked once a World update including the add/remove requests and/or origin cell change has been run.

This use case is also a replacement for the AddCellUsersAndWaitForChunksToBeLoaded and RemoveChunksAndWaitForChunksToBeUnloaded methods that were previously present.

Parameters

Exceptions

public void RemoveCellUsers(IList<Cell> cells, int groupingIndex, int lodIndex)

Sends in a request to remove users from the list of specified cells. This method should only be used by advanced users, as in 99% of cases you should let the Active Grid class control the removal of cell users. If you do decide to use this method, keep the following in mind:

The World tallies all user requests (either add or remove) for World Cells. If the Active Grid sends in an add requests for a specific cell, then you send in an add requests for the same cell, a tally of 2 will exists for the cell. The cell is then loaded and will not be unloaded until the tally reaches 0. In this way, multiple users can lay claim to a cell, and rather than loading that cell multiple times, it is only loaded once.

This strategy introduces errors if you do not keep track of the users you have added to a cell, however. For every user you add, you will typically want to remove a user for the same cell at a later date. If you do not, the cell will likely never be unloaded.

Parameters

Returns

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

Exceptions

public void RemoveCellUsers(IList<LODCell> cells, int groupingIndex)

Sends in a request to remove users from the list of specified cells in the form of LODCells. This method should only be used by advanced users, as in 99% of cases you should let the Active Grid class control the removal of cell users. If you do decide to use this method, keep the following in mind:

The World tallies all user requests (either add or remove) for World Cells. If the Active Grid sends in an add requests for a specific cell, then you send in an add requests for the same cell, a tally of 2 will exists for the cell. The cell is then loaded and will not be unloaded until the tally reaches 0. In this way, multiple users can lay claim to a cell, and rather than loading that cell multiple times, it is only loaded once.

This strategy introduces errors if you do not keep track of the users you have added to a cell, however. For every user you add, you will typically want to remove a user for the same cell at a later date. If you do not, the cell will likely never be unloaded.

Parameters

Returns

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

Exceptions

public void RemoveCellUsers(IList<WorldGroupingCell> cells)

Sends in a request to remove users from the list of specified cells, in the form of WorldGroupingCells. This method should only be used by advanced users, as in 99% of cases you should let the Active Grid class control the removal of cell users. If you do decide to use this method, keep the following in mind:

The World tallies all user requests (either add or remove) for World Cells. If the Active Grid sends in an add requests for a specific cell, then you send in an add requests for the same cell, a tally of 2 will exists for the cell. The cell is then loaded and will not be unloaded until the tally reaches 0. In this way, multiple users can lay claim to a cell, and rather than loading that cell multiple times, it is only loaded once.

This strategy introduces errors if you do not keep track of the users you have added to a cell, however. For every user you add, you will typically want to remove a user for the same cell at a later date. If you do not, the cell will likely never be unloaded.

Parameters

Exceptions

public void RemoveWorldGroupingListener(IWorldGroupingListener groupingListener, int groupingIndex)

Removes the IWorldGroupingListener from the World Grouping indicated by groupingIndex.

Removing Listeners can only be achieved after the World has been initialized. You can use this to remove either runtime added Listeners or Listeners added in the World inspector in the editor.

Parameters

Exceptions

public void ResetAllGroupNamesOnAllWorldGroupings(Action<World> onCompletedCallback = null)

Resets the Group Names of every LOD Group on every World Grouping of this World back to the default names set in the inspector (changes persistent with save data if World is persistent).

This can be used if you have changed the group names in the past to an alternate name but want the World Groupings' LOD Groups to go back to using their default ones.

A rudimentary check is performed to try to catch instances when this method is called unecessarily. The check is performed separately for each World Grouping and adheres to the following rules:

1) If all LOD Groups on a World Grouping are already using their default Group Names, no Group Name reset occurs for that Grouping (however the callback, if provided, is still invoked).
2) If only one LOD Group is not using its default Group Name, only that LOD Group name is reset.
3) If more than one LOD Group is not using its default Group Name, all LOD Groups on the World Grouping are reset, regardless of whether each LOD Group is already using the default Group Name (as such, this may result in an unecessary refresh of the World Cells' Asset Chunks using the non changed LODs).

If you know only a few World Groupings need to be reset, it is better to use the method that targets a specific World Grouping. If you know only a few LOD Groups need to be reset, use the methods that target specific LOD Groups on specific World Groupings.

The world is automatically refreshed as a result of the Group Name changes, so this method should only be used when the world is hidden from the player (otherwise the player may see the change), and probably when the game is paused (so the player does not fall through the world).

Please note, all Group Name changes operate by performing LOD transitions from each World Cell currently belonging to the LOD of the World Grouping to a new World Cell of the same LOD but using the new chunks. This is important, as your custom World Grouping Listeners will only be notified of these updates if their IgnoreLODTransitions property is set to return false.

The operation is performed as a secondary operation using the World's update cycle, and as such if the World is currently in the process of being updated, or another secondary operation is in progress, those updates will be completed before this one begins execution. Once the new group names have been reset and objects refreshed to use the new names, the onCompletedCallback action will be called.

Parameters

Exceptions

public void ResetAllGroupNamesOnWorldGrouping(int groupingIndex, Action<World> onCompletedCallback = null)

Resets the Group Names of all LOD Groups on the specified World Grouping of this World back to the default names set in the inspector (changes persistent with save data if World is persistent).

This can be used if you have changed the Group Names in the past to an alternate name but want the LOD Groups to go back to using their default ones.

A rudimentary check is performed to try to catch instances when this method is called unecessarily. It adheres to the following rules:

1) If all LOD Groups on the World Grouping are already using their default Group Names, no Group Name reset occurs (however the callback, if provided, is still invoked).
2) If only one LOD Group is not using its default Group Name, only that LOD Group is reset.
3) If more than one LOD Group is not using its default Group Name, all LOD Groups on the World Grouping are reset, regardless of whether each LOD Group is already using its default Group Name (as such, this may result in an unecessary refresh of the World Cell Asset Chunks using those unchanged LODs). If you know only a few LOD Groups need to be reset, use the method that targets specific LOD Groups on the World Grouping instead.

The world is automatically refreshed as a result of the Group Name changes, so this method should only be used when the world is hidden from the player (otherwise the player may see the change), and probably when the game is paused (so the player does not fall through the world).

Please note, all Group Name changes operate by performing LOD transitions from each World Cell currently belonging to the LOD of the World Grouping to a new World Cell of the same LOD but using the new chunks. This is important, as your custom World Grouping Listeners will only be notified of these updates if their IgnoreLODTransitions property is set to return false.

The operation is performed as a secondary operation using the World's update cycle, and as such if the World is currently in the process of being updated, or another secondary operation is in progress, those updates will be completed before this one begins execution. Once the group names have been reset and objects refreshed to use the new name, the onCompletedCallback action will be called.

Parameters

Exceptions

public void ResetGroupName(int groupingIndex, int lodIndex, Action<World> onCompletedCallback = null)

Resets the Group Name of the specified LOD Group on the specified World Grouping of this World back to the default name set in the inspector (change persistent with save data if World is persistent).

This can be used if you have changed the Group Name in the past to an alternate name but want the LOD to go back to using its default one.

A check is performed to ensure the Group Name of the specified World Grouping's LOD Group is not already set to the default one, and nothing will happen if it is, although the callback (if provided) will still be invoked.

The world is automatically refreshed as a result of the Group Name change, so this method should only be used when the world is hidden from the player (otherwise the player may see the change), and probably when the game is paused (so the player does not fall through the world).

Please note, all Group Name changes operate by performing LOD transitions from each World Cell currently belonging to the LOD of the World Grouping to a new World Cell of the same LOD but using the new chunks. This is important, as your custom World Grouping Listeners will only be notified of these updates if their IgnoreLODTransitions property is set to return false.

The operation is performed as a secondary operation using the World's update cycle, and as such if the World is currently in the process of being updated, or another secondary operation is in progress, those updates will be completed before this one begins execution. Once the Group Name has been reset and objects refreshed to use the new name, the onCompletedCallback action will be called.

Parameters

Exceptions

public void ReturnWorldCellForPooling(WorldCell worldCell)

Returns a WorldCell created using CreateWorldCell or CreateWorldCellCopy so that it can be reused by SAM in order to save on memory.

Parameters

Exceptions

public void TranslateCellRelativePositionToSceneRelativePosition_BatchConversion(NativeArray<Vector3Double> positions, Cell cellInputPositionsAreRelativeTo, int groupingIndex, Action<World> onCompletedCallback)

Similar to TranslateCellRelativePositionToSceneRelativePosition_BatchConversion except the conversions are carried out using the Jobs system as a World secondary operation.

This means the scheduling of the batch conversion jobs will be delayed until the current World update (if any) completes. Once the jobs are scheduled, all World updates are delayed, which is useful as it ensures the state of the World will remain consistent during the conversion process.

Use this method only if the execution of the method you are calling it from is not driven by the World. If the execution is driven by the World (one of the methods of the World Grouping Listener, for example), using this method will stall out the World.

In these instances, use TranslateCellRelativePositionToSceneRelativePosition_BatchConversion instead.

Parameters

Exceptions

public void TranslateCellRelativePositionToSceneRelativePosition_BatchConversion(List<Vector3Double> positions, List<Cell> cellsInputPositionsAreRelativeTo, int groupingIndex, int minConversionsProcessedPerFrame, Action<World> onCompletedCallback)

Similar to TranslateCellRelativePositionToSceneRelativePosition_BatchConversion except the conversions are carried out over multiple frames as a World secondary operation.

This means the execution of the batch conversion will be delayed until the current World update (if any) completes. Once the batch conversion starts, all World updates are delayed, which is useful as it ensures the state of the World will remain consistent during the conversion process.

Using the job based method is recommend over this one, however this is useful if you wish to avoid jobs for some reason.

Use this method only if the execution of the method you are calling it from is not driven by the World. If the execution is driven by the World (one of the methods of the World Grouping Listener, for example), using this method will stall out the World. In these instances, use TranslateCellRelativePositionToSceneRelativePosition_BatchConversion instead.

Parameters

Exceptions

public void TranslateCellRelativePositionToSceneRelativePosition_BatchConversion(NativeArray<Vector3Double> positions, NativeArray<Cell> cellsInputPositionsAreRelativeTo, int groupingIndex, Action<World> onCompletedCallback)

Similar to TranslateCellRelativePositionToSceneRelativePosition_BatchConversion except the conversions are carried out using the Jobs system as a World secondary operation.

This means the scheduling of the batch conversion jobs will be delayed until the current World update (if any) completes. Once the jobs are scheduled, all World updates are delayed, which is useful as it ensures the state of the World will remain consistent during the conversion process.

Use this method only if the execution of the method you are calling it from IS NOT driven by the World. If the execution is driven by the World (one of the methods of the World Grouping Listener, for example), using this method will stall out the World. In that case, use TranslateCellRelativePositionToSceneRelativePosition_BatchConversion instead.

Parameters

Exceptions

public void TranslateCellRelativePositionToSceneRelativePosition_BatchConversion(List<Vector3Double> positions, List<Cell> cellsInputPositionsAreRelativeTo, int groupingIndex)

Uses a single frame approach to translate multiple positions relative to multiple Endless Grid Cells (cellsInputPositionsAreRelativeTo) to positions relative to the scene (World Space). This is useful when each input position is relative to a different Endless Grid Cell. The input cells are associated with a World Grouping, which is specified via groupingIndex.

This methods uses a single list for the positions to save on space. After the method runs, each position in the positions list will be replaced by the translated scene relative position. If for some reason you need to make use of the cell relative positions after the method is run, you will need to make a copy of the list before calling this method.

This method is meant to be used in situations where a floating origin based World is being used (one where its Origin Cell changes). In these situations, raw non static positions cannot be used as normal, because the state of the World at the time the position is being retrieved/used may be different than the state of the World when the position was recorded (i.e., the Origin Cell may be different).

The solution to this problem is to save the position value relative to a cell, and then save/send that cell value along with the new relative position. These positions can be used along with the cell they are relative to in order to produce a scene relative position, which you can then use to position the objects correctly.

When each position is saved for reuse or sent somewhere else, the cell it is relative to needs to also be recorded or sent so that the position can be translated back into a scene relative position via this method.

This method is carried out in a single frame, and when you have a large number of positions to translate this may cause a performance hitch. In that situation, you should use one of the other batch conversion methods.

Parameters

Exceptions

public IEnumerator<YieldInstruction> TranslateCellRelativePositionToSceneRelativePosition_BatchConversion(List<Vector3Double> positions, List<Cell> cellsInputPositionsAreRelativeTo, int groupingIndex, int maxConversionsProcessedPerFrame)

Similar to TranslateCellRelativePositionToSceneRelativePosition_BatchConversion except the conversions are carried out over multiple frames using an iterator whose execution you must drive.

This means the execution of the batch conversion starts, continues, and finishes only if you drive it, usually using StartCoroutine or from another iterator based method that has been started using that method (although technically this method only yield returns null, so you can also drive it from a regular Update method as well).

Using the job based method is recommend over this one, however this is useful if you wish to avoid jobs for some reason.

You should use this method only if the execution of the method you are calling it from IS driven by the World (one of the methods of the World Grouping Listener, for example). If the execution IS NOT driven by the World, using this method can be dangerous as the World's state may change while the conversion is in progress, if for example an Origin Cell is executed during the conversion process. In that case, use TranslateCellRelativePositionToSceneRelativePosition_BatchConversion instead.

Parameters

Returns

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

Exceptions

public JobHandle TranslateCellRelativePositionToSceneRelativePosition_BatchConversion(NativeArray<Vector3Double> positions, NativeArray<Cell> cellsInputPositionsAreRelativeTo, int groupingIndex, bool initializeWorkImmediately = true)

Similar to TranslateCellRelativePositionToSceneRelativePosition_BatchConversion except the conversions are carried out using the Jobs system as a World secondary operation.

This means the execution of the batch conversion will be delayed until the current World update (if any) completes. Once the batch conversion starts, all World updates are delayed, which is useful as it ensures the state of the World will remain consistent during the conversion process.

You should use this method only if the execution of the method you are calling it from IS driven by the World (one of the methods of the World Grouping Listener, for example). If the execution IS NOT driven by the World, using this method can be dangerous as the World's state may change while the conversion is in progress, if for example an Origin Cell is executed during the conversion process. In that case, use TranslateCellRelativePositionToSceneRelativePosition_BatchConversion instead.

Parameters

Returns

The scheduled Job Handle. Use IsCompleted to check if the jobs are finished, then when it is true call JobHandle.Complete to finalize the data (not strictly sure if this is necessary but it shouldn't hurt anything to do it).

Exceptions

public void TranslateCellRelativePositionToSceneRelativePosition_BatchConversion(List<Vector3Double> positions, Cell cellInputPositionsAreRelativeTo, int groupingIndex, int minConversionsProcessedPerFrame, Action<World> onCompletedCallback)

Similar to TranslateCellRelativePositionToSceneRelativePosition_BatchConversion except the conversions are carried out over multiple frames as a World secondary operation.

This means the execution of the batch conversion will be delayed until the current World update (if any) completes. Once the batch conversion starts, all World updates are delayed, which is useful as it ensures the state of the World will remain consistent during the conversion process.

Using the job based method is recommend over this one, however this is useful if you wish to avoid jobs for some reason.

Use this method only if the execution of the method you are calling it from is not driven by the World. If the execution is driven by the World (one of the methods of the World Grouping Listener, for example), using this method will stall out the World. In these instances, use TranslateCellRelativePositionToSceneRelativePosition_BatchConversion instead.

Parameters

Exceptions

public void TranslateCellRelativePositionToSceneRelativePosition_BatchConversion(List<Vector3Double> positions, Cell cellInputPositionsAreRelativeTo, int groupingIndex)

Uses a single frame approach to translate multiple positions relative to a single Endless Grid Cell (cellInputPositionIsRelativeTo) to positions relative to the scene (World Space). The input cell is associated with a World Grouping, which is specified via groupingIndex.

This methods uses a single list for the positions to save on space. After the method runs, each position in the positions list will be replaced by the translated scene relative position. If for some reason you need to make use of the cell relative positions after the method is run, you will need to make a copy of the list before calling this method.

This method is meant to be used in situations where a floating origin based World is being used (one where its Origin Cell changes). In these situations, raw non static positions cannot be used as normal, because the state of the World at the time the position is being retrieved/used may be different than the state of the World when the position was recorded (i.e., the Origin Cell may be different).

The solution to this problem is to save the position value relative to a cell, and then save/send that cell value along with the new relative position. These positions can be used along with the cell they are relative to in order to produce a scene relative position, which you can then use to position the objects correctly.

When the position is saved for reuse or sent somewhere else, the input cell needs to also be recorded or sent so that the position can be translated back into a scene relative position via this method.

This method is carried out in a single frame, and when you have a large number of positions to translate this may cause a performance hitch. In that situation, you should use one of the other batch conversion methods.

Parameters

Exceptions

public IEnumerator<YieldInstruction> TranslateCellRelativePositionToSceneRelativePosition_BatchConversion(List<Vector3Double> positions, Cell cellInputPositionsAreRelativeTo, int groupingIndex, int maxConversionsProcessedPerFrame)

Similar to TranslateCellRelativePositionToSceneRelativePosition_BatchConversion except the conversions are carried out over multiple frames using an iterator whose execution you must drive.

This means the execution of the batch conversion starts, continues, and finishes only if you drive it, usually using StartCoroutine or from another iterator based method that has been started using that method (although technically this method only yield returns null, so you can also drive it from a regular Update method as well).

Using the job based method is recommend over this one, however this is useful if you wish to avoid jobs for some reason.

You should use this method only if the execution of the method you are calling it from IS driven by the World (one of the methods of the World Grouping Listener, for example). If the execution IS NOT driven by the World, using this method can be dangerous as the World's state may change while the conversion is in progress, if for example an Origin Cell is executed during the conversion process. In that case, use TranslateCellRelativePositionToSceneRelativePosition_BatchConversion instead.

Parameters

Returns

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

Exceptions

public JobHandle TranslateCellRelativePositionToSceneRelativePosition_BatchConversion(NativeArray<Vector3Double> positions, Cell cellInputPositionsAreRelativeTo, int groupingIndex, bool initializeWorkImmediately = true)

Similar to TranslateCellRelativePositionToSceneRelativePosition_BatchConversion except the conversions are carried out using the Jobs system as a World secondary operation.

This means the execution of the batch conversion will be delayed until the current World update (if any) completes. Once the batch conversion starts, all World updates are delayed, which is useful as it ensures the state of the World will remain consistent during the conversion process.

You should use this method only if the execution of the method you are calling it from IS driven by the World (one of the methods of the World Grouping Listener, for example). If the execution IS NOT driven by the World, using this method can be dangerous as the World's state may change while the conversion is in progress, if for example an Origin Cell is executed during the conversion process. In that case, use TranslateCellRelativePositionToSceneRelativePosition_BatchConversion instead.

Parameters

Returns

The scheduled Job Handle. Use IsCompleted to check if the jobs are finished, then when it is true call JobHandle.Complete to finalize the data (not strictly sure if this is necessary but it shouldn't hurt anything to do it).

Exceptions

public Vector3Double TranslateCellRelativePositionToSceneRelativePosition(Vector3Double cellRelativePosition, Cell cellInputPositionIsRelativeTo, int groupingIndex)

Translates a position relative to the input Endless Grid Cell (cellInputPositionIsRelativeTo) to a position relative to the scene (World Space). The input cell is associated with a World Grouping, which is specified via groupingIndex.

This method is meant to be used in situations where a floating origin based World is being used (one where its Origin Cell changes). In these situations, raw non static positions cannot be used as normal, because the state of the World at the time the position is being retrieved/used may be different than the state of the World when the position was recorded (i.e., the Origin Cell may be different).

The solution to this problem is to save the position value relative to a cell, and then save/send that cell value along with the new relative position. These positions can be used along with the cell they are relative to in order to produce a scene relative position, which you can then use to position the objects correctly.

When the position is saved for reuse or sent somewhere else, the input cell needs to also be recorded or sent so that the position can be translated back into a scene relative position via this method.

If you wish to translate multiple positions, you may wish to use one of the BatchConversion methods instead.

Parameters

Returns

Vector3Double
The position relative to the scene (World Space).

Exceptions

public void TranslateSceneRelativePositionToCellRelativePosition_BatchConversion(List<Vector3Double> positions, Cell cellOutputPositionsAreRelativeTo, int groupingIndex, int minConversionsProcessedPerFrame, Action<World> onCompletedCallback)

Similar to TranslateSceneRelativePositionToCellRelativePosition_BatchConversion except the conversions are carried out over multiple frames as a World secondary operation.

This means the execution of the batch conversion will be delayed until the current World update (if any) completes. Once the batch conversion starts, all World updates are delayed, which is useful as it ensures the state of the World will remain consistent during the conversion process.

Using the job based method is recommend over this one, however this is useful if you wish to avoid jobs for some reason.

Use this method only if the execution of the method you are calling it from is not driven by the World. If the execution is driven by the World (one of the methods of the World Grouping Listener, for example), using this method will stall out the World. In these instances, use TranslateSceneRelativePositionToCellRelativePosition_BatchConversion instead.

Parameters

Exceptions

public void TranslateSceneRelativePositionToCellRelativePosition_BatchConversion(NativeArray<Vector3Double> positions, Cell cellOutputPositionsAreRelativeTo, int groupingIndex, Action<World> onCompletedCallback)

Similar to TranslateSceneRelativePositionToCellRelativePosition_BatchConversion except the conversions are carried out using the Jobs system as a World secondary operation.

This means the scheduling of the batch conversion jobs will be delayed until the current World update (if any) completes. Once the jobs are scheduled, all World updates are delayed, which is useful as it ensures the state of the World will remain consistent during the conversion process.

Use this method only if the execution of the method you are calling it from is not driven by the World. If the execution is driven by the World (one of the methods of the World Grouping Listener, for example), using this method will stall out the World. In these instances, use TranslateSceneRelativePositionToCellRelativePosition_BatchConversion instead.

Parameters

Exceptions

public void TranslateSceneRelativePositionToCellRelativePosition_BatchConversion(List<Vector3Double> positions, Cell cellOutputPositionsAreRelativeTo, int groupingIndex)

Uses a single frame conversion process to translate an list of positions relative to the scene (World Space) to positions relative to a specific Endless Grid Cell on the World Grouping specified.

This methods uses a single list for the positions to save on space. After the method runs, each position in the positions list will be replaced by the translated cell relative position. If for some reason you need to make use of the scene relative positions after the method is run, you will need to make a copy of the list before calling this method.

This method is meant to be used in situations where a floating origin based World is being used (one where its Origin Cell changes). In these situations, raw non static positions cannot be used as normal, because the state of the World at the time the position is being retrieved/used may be different than the state of the World when the position was recorded (i.e., the Origin Cell may be different).

The solution to this problem is to save the position value relative to a cell, and then save/send that cell value along with the new relative position. Truthfully, you can use any Endless Grid Cell for this purpose, including the Origin Cell, however in some instances using a specific cell (other than the Origin Cell) is easier.

In either case, when the position is saved for reuse or sent somewhere else, the reference cell needs to also be recorded or sent so that the positions can be translated back into scene relative positions via one of the cell relative to scene relative positions batch conversion methods.

Parameters

Exceptions

public IEnumerator<YieldInstruction> TranslateSceneRelativePositionToCellRelativePosition_BatchConversion(List<Vector3Double> positions, Cell cellOutputPositionsAreRelativeTo, int groupingIndex, int maxConversionsProcessedPerFrame)

Similar to TranslateSceneRelativePositionToCellRelativePosition_BatchConversion except the conversions are carried out over multiple frames using an iterator whose execution you must drive.

This means the execution of the batch conversion starts, continues, and finishes only if you drive it, usually using StartCoroutine or from another iterator based method that has been started using that method (although technically this method only yield returns null, so you can also drive it from a regular Update method as well).

Using the job based method is recommend over this one, however this is useful if you wish to avoid jobs for some reason.

You should use this method only if the execution of the method you are calling it from IS driven by the World (one of the methods of the World Grouping Listener, for example). If the execution IS NOT driven by the World, using this method can be dangerous as the World's state may change while the conversion is in progress, if for example an Origin Cell is executed during the conversion process. In that case, use TranslateSceneRelativePositionToCellRelativePosition_BatchConversion instead.

Parameters

Returns

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

Exceptions

public JobHandle TranslateSceneRelativePositionToCellRelativePosition_BatchConversion(NativeArray<Vector3Double> positions, Cell cellOutputPositionsAreRelativeTo, int groupingIndex, bool initializeWorkImmediately = true)

Similar to TranslateSceneRelativePositionToCellRelativePosition_BatchConversion except the conversions are carried out using the Jobs system as a World secondary operation.

This means the scheduling of the batch conversion jobs will be delayed until the current World update (if any) completes. Once the jobs are scheduled, all World updates are delayed, which is useful as it ensures the state of the World will remain consistent during the conversion process.

You should use this method only if the execution of the method you are calling it from IS driven by the World (one of the methods of the World Grouping Listener, for example). If the execution IS NOT driven by the World, using this method can be dangerous as the World's state may change while the conversion is in progress, if for example an Origin Cell is executed during the conversion process. In that case, use TranslateSceneRelativePositionToCellRelativePosition_BatchConversion instead.

Parameters

Returns

The scheduled Job Handle. Use IsCompleted to check if the jobs are finished, then when it is true call JobHandle.Complete to finalize the data (not strictly sure if this is necessary but it shouldn't hurt anything to do it).

Exceptions

public void TranslateSceneRelativePositionToCellRelativePosition_BatchConversion(List<Vector3Double> positions, List<Cell> cellsOutputPositionsAreRelativeTo, int groupingIndex, int minConversionsProcessedPerFrame, Action<World> onCompletedCallback)

Similar to TranslateSceneRelativePositionToCellRelativePosition_BatchConversion except the conversions are carried out over multiple frames as a World secondary operation.

This means the execution of the batch conversion will be delayed until the current World update (if any) completes. Once the batch conversion starts, all World updates are delayed, which is useful as it ensures the state of the World will remain consistent during the conversion process.

Using the job based method is recommend over this one, however this is useful if you wish to avoid jobs for some reason.

Use this method only if the execution of the method you are calling it from is not driven by the World. If the execution is driven by the World (one of the methods of the World Grouping Listener, for example), using this method will stall out the World. In these instances, use TranslateSceneRelativePositionToCellRelativePosition_BatchConversion instead.

Parameters

Exceptions

public void TranslateSceneRelativePositionToCellRelativePosition_BatchConversion(NativeArray<Vector3Double> positions, NativeArray<Cell> cellsOutputPositionsAreRelativeTo, int groupingIndex, Action<World> onCompletedCallback)

Similar to TranslateSceneRelativePositionToCellRelativePosition_BatchConversion except the conversions are carried out using the Jobs system as a World secondary operation.

This means the scheduling of the batch conversion jobs will be delayed until the current World update (if any) completes. Once the jobs are scheduled, all World updates are delayed, which is useful as it ensures the state of the World will remain consistent during the conversion process.

Use this method only if the execution of the method you are calling it from is not driven by the World. If the execution is driven by the World (one of the methods of the World Grouping Listener, for example), using this method will stall out the World. In these instances, use TranslateSceneRelativePositionToCellRelativePosition_BatchConversion instead.

Parameters

Exceptions

public void TranslateSceneRelativePositionToCellRelativePosition_BatchConversion(List<Vector3Double> positions, List<Cell> cellsOutputPositionsAreRelativeTo, int groupingIndex)

Uses a single frame based approach to identify the Endless Grid Cell each scene relative position is in, and then translate each scene relative position to a position relative to that cell.

This methods uses a single list for the positions to save on space. After the method runs, each position in the positions list will be replaced by the translated cell relative position. If for some reason you need to make use of the scene relative positions after the method is run, you will need to make a copy of the list before calling this method.

This method is meant to be used in situations where a floating origin based World is being used (one where its Origin Cell changes). In these situations, raw non static positions cannot be used as normal, because the state of the World at the time the position is being retrieved/used may be different than the state of the World when the position was recorded (i.e., the Origin Cell may be different).

The solution to this problem is to save the position value relative to a cell, and then save/send that cell value along with the new relative position. Truthfully, you can use any Endless Grid Cell for this purpose, including the Origin Cell, however in some instances using a specific cell (other than the Origin Cell) is easier.

In either case, when the positions are saved for reuse or sent somewhere else, the cells the position are relative to also need to be recorded or sent so that the positions can be translated back into scene relative positions via one of the cell relative to scene relative positions batch conversion methods.

Parameters

Exceptions

public IEnumerator<YieldInstruction> TranslateSceneRelativePositionToCellRelativePosition_BatchConversion(List<Vector3Double> positions, List<Cell> cellsOutputPositionsAreRelativeTo, int groupingIndex, int maxConversionsProcessedPerFrame)

Similar to TranslateSceneRelativePositionToCellRelativePosition_BatchConversion except the conversions are carried out over multiple frames using an iterator whose execution you must drive.

This means the execution of the batch conversion starts, continues, and finishes only if you drive it, usually using StartCoroutine or from another iterator based method that has been started using that method (although technically this method only yield returns null, so you can also drive it from a regular Update method as well).

Using the job based method is recommend over this one, however this is useful if you wish to avoid jobs for some reason.

You should use this method only if the execution of the method you are calling it from IS driven by the World (one of the methods of the World Grouping Listener, for example). If the execution IS NOT driven by the World, using this method can be dangerous as the World's state may change while the conversion is in progress, if for example an Origin Cell is executed during the conversion process. In that case, use TranslateSceneRelativePositionToCellRelativePosition_BatchConversion

Parameters

Returns

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

Exceptions

public JobHandle TranslateSceneRelativePositionToCellRelativePosition_BatchConversion(NativeArray<Vector3Double> positions, NativeArray<Cell> cellsOutputPositionsAreRelativeTo, int groupingIndex, bool initializeWorkImmediately = true)

Similar to TranslateSceneRelativePositionToCellRelativePosition_BatchConversion except the conversions are carried out using the Jobs system as a World secondary operation.

This means the scheduling of the batch conversion jobs will be delayed until the current World update (if any) completes. Once the jobs are scheduled, all World updates are delayed, which is useful as it ensures the state of the World will remain consistent during the conversion process.

You should use this method only if the execution of the method you are calling it from IS driven by the World (one of the methods of the World Grouping Listener, for example). If the execution IS NOT driven by the World, using this method can be dangerous as the World's state may change while the conversion is in progress, if for example an Origin Cell is executed during the conversion process. In that case, use TranslateSceneRelativePositionToCellRelativePosition_BatchConversion instead.

Parameters

Returns

The scheduled Job Handle. Use IsCompleted to check if the jobs are finished, then when it is true call JobHandle.Complete to finalize the data (not strictly sure if this is necessary but it shouldn't hurt anything to do it).

Exceptions

public Vector3Double TranslateSceneRelativePositionToCellRelativePosition(Vector3Double sceneRelativePosition, int groupingIndex, out Cell cellOutputPositionIsRelativeTo)

This method first identifies the Endless Grid Cell on the World Grouping specified that the input scene relative position is in, then translates the scene relative position to a position relative to this cell (and returns it).

This method is meant to be used in situations where a floating origin based World is being used (one where its Origin Cell changes). In these situations, raw non static positions cannot be used as normal, because the state of the World at the time the position is being retrieved/used may be different than the state of the World when the position was recorded (i.e., the Origin Cell may be different).

The solution to this problem is to save the position value relative to a cell, and then save/send that cell value along with the new relative position.

When the position is saved for reuse or sent somewhere else, the cell the position is relative to also needs to be recorded or sent so that the position can be translated back into a scene relative position via one of the cell relative to scene relative position conversion methods.

If you need to convert multiple positions you may be better off using one of the BatchConversion methods of the same name.

Parameters

Returns

Vector3Double
The position relative to cellOutputPositionIsRelativeTo.

Exceptions

public Vector3Double TranslateSceneRelativePositionToCellRelativePosition(Vector3Double sceneRelativePosition, Cell cellOutputPositionIsRelativeTo, int groupingIndex)

Translates a single position relative to the scene (World Space) to a position relative to the input Endless Grid Cell (cellOutputPositionIsRelativeTo) on the World Grouping specified.

This method is meant to be used in situations where a floating origin based World is being used (one where its Origin Cell changes). In these situations, raw non static positions cannot be used as normal, because the state of the World at the time the position is being retrieved/used may be different than the state of the World when the position was recorded (i.e., the Origin Cell may be different).

The solution to this problem is to save the position value relative to a cell, and then save/send that cell value along with the new relative position.

When the position is saved for reuse or sent somewhere else, the input cell needs to also be recorded or sent so that the position can be translated back into a scene relative position via one of the cell relative to scene relative position conversion methods.

If you need to convert multiple positions you may be better off using one of the BatchConversion methods of the same name.

Parameters

Returns

Vector3Double
The position relative to cellOutputPositionIsRelativeTo.

Exceptions

public void TranslateSceneRelativePositionToOriginCellRelativePosition_BatchConversion(List<Vector3Double> positions, Cell[] originCellPositionsAreRelativeTo, int minConversionsProcessedPerFrame, Action<World> onCompletedCallback)

Similar to TranslateSceneRelativePositionToOriginCellRelativePosition_BatchConversion except the conversions are carried out over multiple frames as a World secondary operation.

This means the execution of the batch conversion will be delayed until the current World update (if any) completes. Once the batch conversion starts, all World updates are delayed, which is useful as it ensures the state of the World will remain consistent during the conversion process.

Using the job based method is recommend over this one, however this is useful if you wish to avoid jobs for some reason.

Use this method only if the execution of the method you are calling it from is not driven by the World. If the execution is driven by the World (one of the methods of the World Grouping Listener, for example), using this method will stall out the World. In these instances, use TranslateSceneRelativePositionToOriginCellRelativePosition_BatchConversion instead.

Parameters

Exceptions

public void TranslateSceneRelativePositionToOriginCellRelativePosition_BatchConversion(NativeArray<Vector3Double> positions, NativeArray<Cell> originCellPositionsAreRelativeTo, Action<World> onCompletedCallback)

Similar to TranslateSceneRelativePositionToOriginCellRelativePosition_BatchConversion except the conversions are carried out using the Jobs system as a World secondary operation.

This means the scheduling of the batch conversion jobs will be delayed until the current World update (if any) completes. Once the jobs are scheduled, all World updates are delayed, which is useful as it ensures the state of the World will remain consistent during the conversion process.

Use this method only if the execution of the method you are calling it from is not driven by the World. If the execution is driven by the World (one of the methods of the World Grouping Listener, for example), using this method will stall out the World. In these instances, use TranslateSceneRelativePositionToOriginCellRelativePosition_BatchConversion instead.

Parameters

Exceptions

public Vector3Double TranslateSceneRelativePositionToOriginCellRelativePosition_BatchConversion(List<Vector3Double> positions)

Uses a single frame approach to translate an array of positions relative to the scene (World Space) to positions relative to the Origin Cell of World Grouping 1 on this world.

This methods uses a single list for the positions to save on space. After the method runs, each position in the positions list will be replaced by the translated origin relative position. If for some reason you need to make use of the scene relative positions after the method is run, you will need to make a copy of the list before calling this method.

This method is meant to be used in situations where a floating origin based World is being used (one where its Origin Cell changes). In these situations, raw non static positions cannot be used as normal, because the state of the World at the time the position is being retrieved/used may be different than the state of the World when the position was recorded (i.e., the Origin Cell may be different).

The solution to this problem is to save the position value relative to a cell, and then save/send that cell value along with the new relative position. Truthfully, you can use any Endless Grid Cell for this purpose, including the cell that the position actually falls within, however in some instances using the Origin Cell as the reference is easier.

Note, if your World Origin Position 0,0,0, then the positions will be equivalent to the positions within the scene, so calling this method is redundant. Just save the scene positions along with the current Origin Cell.

In either case, when the position is saved for reuse or sent somewhere else, the Origin Cell needs to also be recorded or sent so that the positions can be translated back into scene relative positions via one of the cell relative to scene relative positions batch conversion methods. You can retrieve this Origin Cell via athe OriginCell property on the World.

Parameters

Exceptions

public IEnumerator<YieldInstruction> TranslateSceneRelativePositionToOriginCellRelativePosition_BatchConversion(List<Vector3Double> positions, Cell[] originCellPositionsAreRelativeTo, int maxConversionsProcessedPerFrame)

Similar to TranslateSceneRelativePositionToOriginCellRelativePosition_BatchConversion except the conversions are carried out over multiple frames using an iterator whose execution you must drive.

This means the execution of the batch conversion starts, continues, and finishes only if you drive it, usually using StartCoroutine or from another iterator based method that has been started using that method (although technically this method only yield returns null, so you can also drive it from a regular Update method as well).

Using the job based method is recommend over this one, however this is useful if you wish to avoid jobs for some reason.

You should use this method only if the execution of the method you are calling it from IS driven by the World (one of the methods of the World Grouping Listener, for example). If the execution IS NOT driven by the World, using this method can be dangerous as the World's state may change while the conversion is in progress, if for example an Origin Cell is executed during the conversion process. In that case, you should use TranslateSceneRelativePositionToOriginCellRelativePosition_BatchConversion

Parameters

Returns

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

Exceptions

public JobHandle TranslateSceneRelativePositionToOriginCellRelativePosition_BatchConversion(NativeArray<Vector3Double> positions, NativeArray<Cell> originCellPositionsAreRelativeTo, bool initializeWorkImmediately = true)

Similar to TranslateSceneRelativePositionToOriginCellRelativePosition_BatchConversion except the conversions are carried out using the Jobs system as a World secondary operation.

This means the scheduling of the batch conversion jobs will be delayed until the current World update (if any) completes. Once the jobs are scheduled, all World updates are delayed, which is useful as it ensures the state of the World will remain consistent during the conversion process.

You should use this method only if the execution of the method you are calling it from IS driven by the World (one of the methods of the World Grouping Listener, for example). If the execution IS NOT driven by the World, using this method can be dangerous as the World's state may change while the conversion is in progress, if for example an Origin Cell is executed during the conversion process. In that case, you should use TranslateSceneRelativePositionToOriginCellRelativePosition_BatchConversion instead.

Parameters

Returns

The scheduled Job Handle. Use IsCompleted to check if the jobs are finished, then when it is true call JobHandle.Complete to finalize the data (not strictly sure if this is necessary but it shouldn't hurt anything to do it).

Exceptions

public Vector3Double TranslateSceneRelativePositionToOriginCellRelativePosition_SingleImmediate(Vector3Double sceneRelativePosition)

Translates a position relative to the scene (World Space) to a position relative to the Origin Cell of World Grouping 1 on this World.

This method is meant to be used in situations where a floating origin based World is being used (one where its Origin Cell changes). In these situations, raw non static positions cannot be used as normal, because the state of the World at the time the position is being retrieved/used may be different than the state of the World when the position was recorded (i.e., the Origin Cell may be different).

The solution to this problem is to save the position value relative to a cell, and then save/send that cell value along with the new relative position. Truthfully, you can use any Endless Grid Cell for this purpose, including the cell that the position actually falls within, however in some instances using the Origin Cell as the reference is easier.

Note, if your World Origin Position 0,0,0, then the Origin Cell relative position will be equivalent to the position within the scene, so calling this method is redundant. Just save the scene position along with the current Origin Cell.

In either case, when the position is saved for reuse or sent somewhere else, the Origin Cell needs to also be recorded or sent so that the position can be translated back into a scene relative position via one of the cell relative to scene relative position conversion methods. You can use the Origin Cell property for this purpose. Note that you must record the Origin Cell that is set at the time of saving/sending the position, since this Origin Cell may change in the future.

Note regarding performance critical code: If you wish to perform batch conversions of scene relative positions to Origin Cell relative positions, you are better off not using this method and instead using the batch conversion methods.

Parameters

Returns

Vector3Double
The Origin Cell relative position to translate.

Exceptions

public bool TryGetBaseGroupingWorldCellAssociatedWithInputWorldCell(WorldCell inputWorldCell, out WorldCell worldCell)

Tries to get the World Cell from the base World Grouping that the input World Cell resides in. Calling this method for an input World Cell on the Base Grouping is redundant. This method may fail to identify a World Cell for several reasons. The out paramater reasonForFailure will give you a clue as to why it is failing when that happens.

It's also possible that the World Cell's boundaries are such that they fall within multiple World Cells' from the Base Grouping. The World Cell returned by this method is always the World Cell that contains the CellPosition of the inputWorldCell, which is always the minimum point on the World Cell's Bounds.

Use this method rather than the other method of the same name when you don't care about the reason for the out worldCell being null, and this method returning false.

Parameters

Returns

bool
A bool indicating whether the World Cell was able to be retrieved.

Exceptions

public bool TryGetBaseGroupingWorldCellThatInputWorldCellIsIn(WorldCell inputWorldCell, out WorldCell worldCell, out string reasonForFailure)

Tries to get the World Cell from the base World Grouping that the input World Cell resides in. Calling this method for an input World Cell on the Base Grouping is redundant. This method may fail to identify a World Cell for several reasons. The out paramater reasonForFailure will give you a clue as to why it is failing when that happens.

It's also possible that the World Cell's boundaries are such that they fall within multiple World Cells' from the Base Grouping. The World Cell returned by this method is always the World Cell that contains the CellPosition of the inputWorldCell, which is always the minimum point on the World Cell's Bounds.

If you do not need to know why the method fails and returns false, use the method of the same name that does not contain the reasonForFailure out parameter.

Parameters

Returns

bool
A bool indicating whether the World Cell was able to be retrieved.

Exceptions

public bool TryGetWorldCellAssociatedWithEndlessGridCell(Cell endlessGridCell, int groupingIndex, out WorldCell worldCell, out string reasonForFailure)

Tries to get the World Cell associated with the Endless Grid Cell. If no World Cell can be identified, false will be returned and worldCell will be null. In this case, reasonForFailure can tell you important information on why the World Cell could not be found, such as the Endless Grid Cell was outside the bounds of the Streamable Grid or was associated with an disabled Streamable Grid Cell.

Parameters

Returns

bool
A bool indicating whether the World Cell was able to be retrieved.

Exceptions

public bool TryGetWorldCellAssociatedWithEndlessGridCell(Cell endlessGridCell, int groupingIndex, out WorldCell worldCell)

Tries to get the World Cell that the position is in. This method may fail to identify a World Cell for several reasons. If you are having trouble identifing the reason, you can use the alternative method with the out string parameter.

Parameters

Returns

bool
A bool indicating whether the World Cell was able to be retrieved.

Exceptions

public bool TryGetWorldCellPositionIsIn(Vector3Double position, int groupingIndex, out WorldCell worldCell, out string reasonForFailure)

Tries to get the World Cell that the position is in. If no World Cell can be identified, false will be returned and worldCell will be null. In this case, reasonForFailure can tell you important information on why the World Cell could not be found, such as the position was outside the bounds of the Streamable Grid or fell within the bounds of a disabled Streamable Grid Cell.

Parameters

Returns

bool
A bool indicating whether the World Cell was able to be retrieved.

Exceptions

public bool TryGetWorldCellPositionIsIn(Vector3Double position, int, out WorldCell worldCell)

Tries to get the World Cell that the position is in. This method may fail to identify a World Cell for several reasons. If you are having trouble identifing the reason, you can use the alternative method with the out string reasonForFailure parameter.

Parameters

Returns

bool
A bool indicating whether the World Cell was able to be retrieved.

Exceptions

public void UnloadWorldRegion(int worldRegionNumber)

Unloads the World Region matching the input worldRegionNumber.

This method will not give you any insight into when the cells are actually unloaded. If you need to know when the World has processed the World Region and updated itself to reflect changes resulting from the World Region being unloaded, you can register a callback method with the World via the RegisterOnUserRequestsFulfilledCallback method. The callback method will be invoked once the World has completed an update cycle containing changes that resulted from the unload operation.

This strategy also allows you to load and unload multiple regions in one World Update cycle, and be notified when all regions are loaded and/or unloaded. To do so, simply call the LoadWorldRegion and UnloadWorldRegion methods for each region that you want to load or unload before calling the WaitForUpdateThatIncludesRequests method.

Parameters

public void UnloadWorldRegion(string worldRegionName)

Unloads the cells in the World Region matching the input worldRegionName.

This method will not give you any insight into when the cells are actually unloaded. If you need to know when the World has processed the World Region and updated itself to reflect changes resulting from the World Region being unloaded, you can register a callback method with the World via the RegisterOnUserRequestsFulfilledCallback method. The callback method will be invoked once the World has completed an update cycle containing changes that resulted from the unload operation.

This strategy also allows you to load and unload multiple regions in one World Update cycle, and be notified when all regions are loaded and/or unloaded. To do so, simply call the LoadWorldRegion and UnloadWorldRegion methods for each region that you want to load or unload before calling the WaitForUpdateThatIncludesRequests method.

Parameters

public void UpdateLoadCushion(double newLoadCushion)

Updates the Load Cushion used by the World.

The load cushion is the amount of time the World will wait after it receives cell add/remove request or a world origin reset order before proceeding with a World Update or Origin Reset. Increasing the load cushion time gives your player time cross additional boundaries before the world is updated, or to cross back over a boundary that they just crossed. This can reduce some loading/unloading that occurs as the result of a very fast moving player or small terrain/object sizes.

Parameters