World Class

public void AddCellUsers(IList<Cell> cells, int zoneIndex, 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 time. If you do not, the cell will likely never be unloaded.

Parameters

Exceptions

public void AddCellUsers(IList<LODCell> cells, int zoneIndex, 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 Zone Indexes, 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. Listeners are added/removed on a per Grouping basis, not a per Zone Grouping basis, so when you add/remove a listener for a World Grouping, all Zones that contain a valid Streamable Grid for that Grouping will have the listener added/removed.

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 World Grid.

Parameters

Returns

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

Exceptions

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

Changes the Group Names of all LOD Groups for all Zone Groupings in the specified Zone (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 a Zone 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 Zone 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 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 ChangeAllGroupNamesOnZoneGrouping(int zoneIndex, int groupingIndex, string[] newGroupNames, Action<World> onCompletedCallback = null)

Changes the Group Names of all LOD's for the specified Zone 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 of Zone 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 zoneIndex, int groupingIndex, int lodIndex, string newGroupName, Action<World> onCompletedCallback = null)

Changes the Group Name of the specified LOD for the specified Zone 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 ClampingOperationInfo ClampOriginCells(bool updateHiearchyOrganizers, bool notifyUsersInSingleFrame, Action<World> onCompletedCallback = null)

Clamps the world's Origin Cells. Clamping can only occur when the world utilizes one or more endless axes.

The process of clamping takes the current World's Origin Cell value and translates it to a value that falls between the normal Starting and Ending Cell of the World (which is determined by the layout of your Zones). Each Zone Grouping's Origin Cell is also translated in a way that is consistent with the translation of the World's Origin Cell. All loaded World Cells on each Zone Grouping have their Cell On Endless Grid value adjusted during the clamp.

For example, imagine you have a World with a single Zone Grouping, that is using a Streamable Grid with only 2 Rows. On a world with non endless rows, cells in this Zone Grouping (upon being loaded into the scene) can only have a row value of 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 a similar Endless World Grid, for many reasons.

Origin Cells of course cannot reach into infinity, since they are 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 World's Rows range between -2 and 2, we can note that this row 5 cell is equivalent to a row 0 cell. The goal of clamping, then, is to take the row 5 World Origin Cell and shift it so its value is 0. In this case, we must shift 5 by -5 to get it to 0. 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 (by -5) any data that was dependent on the origin row being 5, in order 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

Returns

ClampingOperationInfo
Information about the Clamping Operation. Only valid after the onCompletedCallback has triggered! The same object is reused for each Clamping Operation, which means the data in the Info will be cleared automatically each time a Clamping Operation is executed.

Do note, however, that the origin cell data should only be relied upon in the short time after onCompletedCallback is triggered, since the Origin Cell may change as a result of an Origin Cell change operation.

If you want to free up memory, you can call the ClearMemory method on this object, but only after onCompletedCallback is triggered and you have used the object's data as you need.

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

Creates a World Cell based on the passed in endlessGridCell, LOD, World Grouping index, and Zone 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 in reference an LOD Group 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 DetermineZoneGroupingOriginCellFromWorldOriginCell_PreInitSafe(int zoneIndex, int groupingIndex, Cell theoreticalWorldOriginCell, out Vector3Double zoneGroupingOriginCellPosition)

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

The Zone Grouping Origin Cell is always the Endless Grid Cell on the Zone Grouping that is closest to the Origin Position of the World. Note that it is possibe for multiple Endless Grid Cells on the Zone Grouping to be the same distance from the Origin Position. In these cases, usually the Cell with the smallest position is used.

Parameters

Returns

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

Exceptions

public Cell FindEndlessGridCellPositionIsInOrClosestTo(Vector3Double position, int zoneIndex, int groupingIndex, out bool positionIsInCell)

Finds the Endless Grid Cell that the specified position falls within on this World (given the current Origin Cell of the World), for the specified Zone and World Grouping. If the position does not fall in an actual Cell of the Zone, the returned Cell will be the closest Cell to the position instead.

Bear in mind that if the Zone Grouping is Two Dimensional, the position will always be considered inside of Layer 1, even if technically it falls outside of the Layer's Bounds as set on your Streamable Grid.

Parameters

Returns

Cell
The Endless Grid Cell the position falls within or is closest to.

Exceptions

public Cell FindEndlessGridCellPositionIsInOrClosestTo(Vector3Double position, int zoneIndex, int groupingIndex, out bool positionIsInCell, out Vector3Double endlessGridCellPosition)

Finds the Endless Grid Cell (and it's position) that the specified position falls within on this World (given the current Origin Cell of the World), for the specified Zone and World Grouping. If the position does not fall in an actual Cell of the Zone, the returned Cell will be the closest Cell to the position instead.

Bear in mind that if the Zone Grouping is Two Dimensional, the position will always be considered inside of Layer 1, even if technically it falls outside of the Layer's Bounds as set on your Streamable Grid.

Parameters

Returns

Cell
The Endless Grid Cell the position falls within or is closest to.

Exceptions

public Cell FindEndlessGridCellPositionIsInOrClosestTo(Vector3Double position, int zoneIndex, int groupingIndex, out Vector3Double endlessGridCellPosition, out bool positionIsInCell)

Finds the Endless Grid Cell that the specified position falls within on this World (given the current Origin Cell of the World), for the specified Zone and World Grouping. If the position does not fall in an actual Cell of the Zone, the returned Cell will be the closest Cell to the position instead.

Also outputs the position of the returned Cell.

Parameters

Returns

Cell
The Endless Grid Cell the position falls within.

Exceptions

public Cell FindEndlessGridCellPositionIsInOrClosestToUsingInitialOriginCell(Vector3Double position, int groupingIndex)

Finds the Endless Grid Cell that the input position would be in or be closest to 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 World's Grid.

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 void FindEndlessGridCellsPositionIsInAcrossAllZones(Vector3Double position, int groupingIndex, List<ZoneGroupingCell> cells)

Finds all Endless Grid Cells that a position is in across all Zones for a given World Grouping.

This is useful if you don't care what Zone the position is in.

Parameters

Exceptions

public void FindEndlessGridCellsPositionIsInAcrossAllZonesAndGroupings(Vector3Double position, List<ZoneGroupingCell> cells)

Finds all Endless Grid Cells that a position is in across all Zones and World Groupings.

This is useful if you don't care what Zone or World Grouping the position is in.

Parameters

Exceptions

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 zoneIndex, int groupingIndex, out bool positionIsInCell)

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 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 Cell FindUnboundWorldGridCellPositionIsIn(Vector3Double position)

Finds the Unbound Cell the position is in within the World's imaginary grid, given the current Origin Cell used by the World.

The unbound cell is similar to an endless grid cell, in that its indices are unique for each repeated instance of the World on any axis which have been set to be repeated/endless.

Parameters

Returns

Cell
The Unclamped World Grid Cell the position is in.

Exceptions

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

Adds all loaded World Cells for the specified Zone 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.

If the World has not been initialized or the Zone Grouping is not in use (because no Streamable Grid was assigned to it, nothing will be added to the list.

Parameters

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

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

Note that this method gets the currently loaded World Cells as contained in each Zone Grouping's internal dictionary. If a Zone 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 void GetAllLoadedWorldCellsInZone(int zoneIndex, List<WorldCell> addCellsTo)

Adds all loaded World Cells for the specified Zone (across all World Groupings) 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.

If the World has not been initialized, nothing will be added to the list.

Parameters

public void GetAllZonesWithinRangeOfPosition(ICollection<InRangeZone> inRangeZones, Vector3Double position, double range)

Gets all Zones in range of the position, where range is the passed in value. This is a highly efficient method that uses a Bounding Volume Hierarchy type structure under the hood to efficiently sort the Zones into discreet areas for faster identification of in range zones.

Whether the Zone is in range is based on that Zones bounding volume within the World. Because a Zone can have variable sized Streamable Grids across different World Groupings, this bounding volume's max position is based on the largest Streamable Grid in the zone. This means that although a Zone may be within range to the position, an individual Zone Grouping may not actually be in range.

On the other hand, if the input position is less than the Zone's min position on all three axes, all Zone Groupings will be in range if the Zone is in range, since the min position of each Zone Grouping is equal to the Zone's min position.

Check each InRangeZone's AllZoneGroupingsGauranteedToBeInRange value to see if this latter case has occured. If AllZoneGroupingsGauranteedToBeInRange is true, you do not need to do anything else. All Zone Groupings for the Zone will be in range. If AllZoneGroupingsGauranteedToBeInRange is false, you will need to perform a more precise check for each Zone Grouping you care about, which you can do using the IsZoneGroupingWithinRangeOfPosition method. Pass in each Zone's ZonePosition (found on each inRangeZone object).

Finally, it is VERY IMPORTANT to note that when using an endless/repeating World, the same Zone can be added multiple times using this method, as the method will take into account whether the World has been repeated on each axis. If it has, the Zone's position may fall in the repeated portion of the World rather than the original unrepeated portion. In these cases, the RepeatedWorldIndices value on each InRangeZone will tell you if the zone is from a repeated portion of the World (0 means it falls on an unrepeated section, while +/- values indicate it falls on a repeated section - for example +1 means it is on the first repeated portion on the + axis in relation to the original/unrepeated portion).

Since the player can travel freely on each each axis, note that the Row, Column, and/or Layer value for the RepeatedWorldIndices may be different. If not using any repeating/endless axes, RepeatedWorldIndices will always be equal to Cell.Zero.

Parameters

Exceptions

public void GetAllZonesWithinRangeOfPositionUsingTheoreticalOriginCell(ICollection<InRangeZone> inRangeZones, Vector3Double position, double range, Cell theoreticalOriginCell)

Gets all Zones in range of the position, but with the World projected using the passed in theoreticalOriginCell, where range is the passed in value. This is a highly efficient method that uses a Bounding Volume Hierarchy type structure under the hood to efficiently sort the Zones into discreet areas for faster identification of in range zones.

Whether the Zone is in range is based on that Zones bounding volume within the World. Because a Zone can have variable sized Streamable Grids across different World Groupings, this bounding volume's max position is based on the largest Streamable Grid in the zone. This means that although a Zone may be within range to the position, an individual Zone Grouping may not actually be in range.

On the other hand, if the input position is less than the Zone's min position on all three axes, all Zone Groupings will be in range if the Zone is in range, since the min position of each Zone Grouping is equal to the Zone's min position.

Check each InRangeZone's AllZoneGroupingsGauranteedToBeInRange value to see if this latter case has occured. If AllZoneGroupingsGauranteedToBeInRange is true, you do not need to do anything else. All Zone Groupings for the Zone will be in range. If AllZoneGroupingsGauranteedToBeInRange is false, you will need to perform a more precise check for each Zone Grouping you care about, which you can do using the IsZoneGroupingWithinRangeOfPosition method. Pass in each Zone's ZonePosition (found on each inRangeZone object).

Finally, it is VERY IMPORTANT to note that when using an endless/repeating World, the same Zone can be added multiple times using this method, as the method will take into account whether the World has been repeated on each axis. If it has, the Zone's position may fall in the repeated portion of the World rather than the original unrepeated portion. In these cases, the RepeatedWorldIndices value on each InRangeZone will tell you if the zone is from a repeated portion of the World (0 means it falls on an unrepeated section, while +/- values indicate it falls on a repeated section - for example +1 means it is on the first repeated portion on the + axis in relation to the original/unrepeated portion).

Since the player can travel freely on each each axis, note that the Row, Column, and/or Layer value for the RepeatedWorldIndices may be different. If not using any repeating/endless axes, RepeatedWorldIndices will always be equal to Cell.Zero.

Parameters

Exceptions

public Axes GetAxesTypeUsedByWorldGrouping(int groupingIndex)

Gets the Axes Type used by a particular World Grouping. This just finds the First Streamable Grid for the Grouping across all Zones, and returns its Axes type. This is only possible because all Streamable Grids for a World Grouping must have the same Axes type across all Zones.

Parameters

Returns

Axes
The Axes type of the World Grouping.

Exceptions

public Bounds GetBoundsOfEndlessGridCell(Cell endlessGridCell, int zoneIndex, 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 zoneIndex, int groupingIndex, int LOD, out ChunkManager chunkManager, out int managerUserID)

Gets the Chunk Manager and User ID for the given LOD Group on the given Zone 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.

Note that while all LOD Groups of the same "level" across the same World Grouping will use the same Chunk Manager no matter if they are within the same Zone, each LOD Group will have a unique managerUserID, as each is considered a separate user by the Manager.

Parameters

public void GetChunkStreamerAndID(int zoneIndex, 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 Zone 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.

Note that while all LOD Groups of the same "level" across the same World Grouping will use the same Chunk Streamer no matter if they are within the same Zone, each LOD Group will have a unique streamerUserID, as each is considered a separate user by the Streamer.

Parameters

public CellDimensions GetDimensionsOfEndlessGridCell(Cell endlessGridCell, int zoneIndex, 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 void GetEndlessGridCellsInAxisAlignedBoundingCube(int groupingIndex, Vector3Double min, Vector3Double max, List<CellAndIndex> endlessGridCellsInArea)

Gets all Endless Grid 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 port (obviously it will be approximate, since the camera viewport is not a cube).

Unlike the GetWorldCellsInAxisAlignedBoundingCube method, this one deals with Endless Grid Cells rather than World Cells, so it is not concerned with what cells are currently loaded, but instead which cells (loaded or unloaded) fall within the given area.

If you need additional information about the cells you can query the World. For instance, if you want to know the dimensions of one of the cells, you can use the GetBoundsOfEndlessGridCell method.

Each cell is a CellAndIndex that contains the endless grid cell and the zone that cell is a part of. Since gaps can exist between Zones, it is possible that the bounding box does not overlap any cells!

In some cases you may only care about enabled endless grid cells. In these instances, you can pass in true for the onlyIncludeEnabledCells argument and all disabled cells will be filtered out of the list.

Parameters

Exceptions

public string GetGroupingName_PreInitSafe(int groupingIndex)

Gets the name of a World Grouping as set in the inspector.

Parameters

Returns

string
The name of the Grouping (as set in the inspector).

public int GetIndexOfWorldGroupingUsingID_PreInitSafe(int groupingID)

Gets the current index of the World Grouping identified by the groupingID passed in.

Parameters

Returns

int
The index of the World Grouping on this World (as shown in the inspector).

public int GetIndexOfZoneUsingID_PreInitSafe(int zoneID)

Gets the current index of the zone identified by the zoneID passed in.

Parameters

Returns

int
The index of the Zone on this World (as shown in the inspector), or -1 if a Zone with the input ID does not exist.

public int GetIndexOfZoneUsingName_PreInitSafe(string zoneName)

Gets the current index of the zone identified by the zoneName passed in. This method is slower than the version that uses the ID of the Zone, so it is recommended to use that instead when possible.

Parameters

Returns

int
The index of the Zone on this World (as shown in the inspector), or -1 if a Zone does not exist with the input name.

public string GetLODGroupName(int zoneIndex, int groupingIndex, int lodIndex)

Gets the name of the LOD Group (specified by lodIndex) the Zone Grouping (specified by zoneIndex and groupingIndex) is currently configured to use. If no save data has been loaded or alt group names set via the PreInitialize method, and the World has not been initialized, this will return the Group Name specified for the LOD Group via the Streamable Grid asset.

Parameters

Returns

string
The Group Name of the LOD.

public Cell GetOriginCellOfZoneGrouping(int zoneIndex, int groupingIndex)

Gets the current Origin Cell of the Zone Grouping associated with the zoneIndex and groupingIndex. Each Origin Cell is the closest Endless Grid Cell to the Origin Position that belongs to the Zone Grouping.

Parameters

Returns

Cell
The one based Origin Cell of the World Grouping.

Exceptions

public Vector3Double GetOriginCellPositionOfZoneGrouping(int zoneIndex, int groupingIndex)

Gets the current Origin Cell Position of the Zone Grouping. Note that the World'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 Zone Groupings may be equal to this same position, or it may be different, as there is no gaurantee that a Cell from the Zone Grouping lines up perfectly with the Origin Cell. In these circumstances, SAM uses the closest Endless Grid Cell from the Zone Grouping (to the World's Origin Position).

Parameters

Returns

Vector3Double
The Origin Cell position of the World Grouping.

Exceptions

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

Retrieves the position and dimensions of an Endless Grid Cell.

Parameters

Exceptions

public Vector3Double GetPositionOfEndlessGridCellUsingInitialOriginCell(Cell endlessGridCell, int zoneIndex, 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 zoneIndex, 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 Vector3Double GetPositionOfEndlessGridCell_PreInitSafe(Cell endlessGridCell, int zoneIndex, int groupingIndex)

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

This method is safe to use at runtime before the World has been initialized. It is NOT SAFE to use outside of the editor!

The method uses the current World Origin Cell in its calculation. If SAM has not been initialized, this should be the Origin Cell set in the inspector, unless you call the method after loading save data.

Parameters

Returns

Vector3Double
The position of the cell.

Exceptions

public void GetRowAndLayerPositionOfCell(Vector3Double cellPosition, int zoneIndex, 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 GetStreamableGridOfZoneGrouping_PreInitSafe(int zoneGrouping, int groupingIndex)

Gets the Streamable Grid associated with a specific Zone 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).

Also note that this method is Zone agnostic. Cells will be returned so long as they are associated with the input World Grouping, no matter which Zone they fall within.

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 bool GetWorldCellsPositionIsIn(Vector3Double position, int groupingIndex, List<WorldCell> worldCells)

Gets any and all World Cells that the position is in for the specified World Grouping, across all Zones. If no World Cells can be identified, the input worldCells list will be empty.

Parameters

Returns

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

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 void GetZoneGroupingNeighbors(int zoneIndex, int groupingIndex, int[] neighborZones)

Parameters

Exceptions

public string GetZoneName_PreInitSafe(int zoneIndex)

Gets the name of a Zone as assigned in the World inspector.

Parameters

Returns

string
The name of the Zone.

public bool IsZoneEnabled(int zoneIndex)

Returns whether a Zone is enabled (as set via the inspector).

Parameters

Returns

bool
True if the zone is enabled, false otherwise.

public bool IsZoneGrouping3D_PreInitSafe(int zoneIndex, int groupingIndex)

Can be used to query whether a particular Zone Grouping is three dimensional (it's Streamable Grid uses the Three_Dimensional Axes type). This method will throw an exception if no Streamable Grid has been assigned to the Zone Grouping!

Parameters

Returns

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

public bool IsZoneGroupingEnabled_PreInitSafe(int zoneIndex, int groupingIndex)

Checks whether a Zone Grouping is enabled. Can be used when you know the Zone Index and Grouping Index of a Zone Grouping, but do not know if a Streamable Grid has been assigned to the Zone for the particular World Grouping, or whether the Zone has been disabled via the inspector.

Parameters

Returns

bool
True if a Streamable Grid has been assigned to the Zone for the input Grouping and the Zone is enabled (via the inspector), false otherwise. Also false if the World has not been initialized.

public bool IsZoneGroupingUpdatingCells(int zoneGrouping, int grouping)

Queries the World to determine if the given Zone 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 Zone 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 Zone 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 bool IsZoneGroupingWithinRangeOfPosition(int zoneIndex, int groupingIndex, Vector3Double position, double range, Vector3Double zoneGroupingPosition)

Checks whether a reference position is within range of the input Zone Grouping.

This method is intended to be used after calling GetAllZonesWithinRangeOfPosition or GetAllZonesWithinRangeOfPositionUsingTheoreticalOriginCell, for any InRangeZone's that were found with AllZoneGroupingsGauranteedToBeInRange set to false. It verifies that a Zone Grouping is actually In Range to the same reference position passed to GetAllZonesWithinRangeOfPosition, since when AllZoneGroupingsGauranteedToBeInRange is false, there is no gaurantee that each Zone Grouping in the Zone is actually in range.

This is why this method takes the zoneGroupingPosition as input, as that position is provided to the InRangePosition object when calling the methods listed above. Also note that you do not need to provide any Origin Cell when calling this method, because this method only uses the zoneGroupingPosition passed in to determine whether the position is within range. So if you used GetAllZonesWithinRangeOfPositionUsingTheoreticalOriginCell, the zoneGroupingPosition has already been calculated as if the Origin Cell were set to the origin cell you passed into that method.

Parameters

Returns

bool
True if the Zone Grouping is in range of the position, false otherwise.

Exceptions

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_SetActiveGameStartConfiguration(string configurationName)

Allows you to switch the game start configuration that will be used when this World is initialized. The Game Start Configuration controls the starting position of players which are used by Active Grids synced to this World, as well as the Origin Cell the World will use at start. Combined, these settings control the layout of cells at the start of the game.

Note that if SAM persistent data is loaded, no game start configurations will not be used, as the data in the persistent save file will be used instead.

Parameters

Exceptions

public void PreInitialize_SetGroupName(int zoneIndex, 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 Zone 1, Grouping 1's 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 zoneIndex, int groupingIndex, string[] newGroupNames, bool ignoreNamesFromPersistentData, bool applyOverwriteRuleToNullNames)

Changes the Group Names of all LOD Groups on the specified Zone 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_SetGroupNamesForZone(int zoneIndex, string[][] newGroupNames, bool ignoreNamesFromPersistentData, bool applyOverwriteRuleToNullNames)

Changes the Group Names of all LOD Groups on all World Groupings of the Zone specified, 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).

It is possible for a Zone to have some World Groupings not in use (by not supplying a Streamable Grid to it). When such a World Grouping is encountered, no Group Name changes will be applied to it, so it's typically a good idea to set those indexes in the array to null (via newGroupNames[someIndex] = null).

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 party 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 bool PreInitialize_TryGetActiveGameStartConfiguration(out string configurationName, out Cell configurationStartingOriginCell, out Vector3 configurationStartingPlayerPosition)

Attempts to get information about the Active Game Start Configuration for this World. The method will return false if there is no Active Configuration, in which case the out arguments should not be used.

Parameters

Returns

bool
True if a Game Start Configuration is active on this World, false otherwise.

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, or after processing the add/remove requests and the World determines no World Update is needed.

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 zoneIndex, 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 zoneIndex, 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.

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

Parameters

Exceptions

public void RemoveWorldGroupingListener(IWorldGroupingListener groupingListener, int groupingIndex)

Removes the IWorldGroupingListener from the World Grouping indicated by groupingIndex. Listeners are added/removed on a per Grouping basis, not a per Zone Grouping basis, so when you add/remove a listener for a World Grouping, all Zones that contain a valid Streamable Grid for that Grouping will have the listener added/removed.

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(int zoneIndex, Action<World> onCompletedCallback = null)

Resets the Group Names of every LOD Group on every Zone Grouping of the input Zone 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 Zone 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 Zone 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 Zone 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 ResetAllGroupNamesOnZoneGrouping(int zoneIndex, int groupingIndex, Action<World> onCompletedCallback = null)

Resets the Group Names of all LOD Groups on the specified Zone 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 zoneIndex, int groupingIndex, int lodIndex, Action<World> onCompletedCallback = null)

Resets the Group Name of the specified LOD Group on the specified Zone 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(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, 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 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 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 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 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 Zone and 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 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.

Final Note! Use of this method is only recommended if your game layout is stable, which is to say your Zone positions within the game world will not move in the future. If your zones are not stable and might be moved, you should use one of the methods that gives you a Zone Cell relative position. If you do not heed this advice, when you move your Zone, the position will not move in conjuction with the zone position change!

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 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.

Final Note! Use of this method is only recommended if your game layout is stable, which is to say your Zone positions within the game world will not move in the future. If your zones are not stable and might be moved, you should use one of the methods that gives you a Zone Cell relative position. If you do not heed this advice, when you move your Zone, the position will not move in conjuction with the zone position change!

Parameters

Returns

Vector3Double
The translated World Origin Cell relative position.

Exceptions

public bool TryGetWorldCellAssociatedWithEndlessGridCell(Cell endlessGridCell, int groupingIndex, out WorldCell worldCell, out NullWorldCellError 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 NullWorldCellError 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