IWorldUser Interface

bool IsReadyForOriginCellChange()

Called when the World the user is registered to is about to perform an Origin Cell Change. The World will query all users using this method to make sure they are ready. You can return false to tell the World your user is not ready. The world will exit the Current frame if at least one user is not ready, and then query all users again in a subsequent frame. Once all users are ready, the world will call OnOriginCellChanging before starting the Origin Cell change.

If you need to block execution of certain operations while the Origin Cell Change is running, or run certain code to prepare your user for the change, you should place such code within OnOriginCellChanging rather than IsReadyForOriginCellChange.

This is because some other World User may return false for IsReadyForOriginCellChange, in which case there is no reason for you to initiate the blocking code or run the preparation code yet. OnOriginCellChanging, on ther other hand, is only called after all users are ready, right before the Origin Cell Change begins, which is where you will need to initiate the blocking code and prepare for the Origin Cell change.

An Origin Cell change can be initiated in four ways. Via the Active Grid when the player crosses a World Reset boundary, via the Active Grid when its TryChangeOriginCellOfWorld is called, via the World when its ChangeOriginCell is called, or via the World when its LoadWorldRegion method is called with setOriginCellToWorldRegionOriginCell set to true. No matter how the Origin Cell update is initiated, this method will be queried.

Returns

bool
Return true if the user is ready for the Origin Cell Change, false otherwise. The Origin Cell change will not occur until all World users are ready for it.

void OnOriginCellChanged_Fast(Vector3Double shiftAmount, ReadOnlyArray<Cell> newOriginCells)

Called when the World the user is registered to has completed its Origin Cell change. There are two methods similarly named, OnOriginCellChanged_Fast and OnOriginCellChangeCompletedSlow.

OnOriginCellChanged_Fast is executed in a single frame and will be called when UseFastOnOriginCellChangedMethod is implemented to return true. This is ideal when your code is lightweight and/or doesn't need to be run over multiple frames.

OnOriginCellChanged_Slow is executed (usually) over multiple frames by introducing yield statements in your method implementation, and is called when UseFastOnOriginCellChangedMethod is implemented to return false.

Also note that if you are using a World Shift component with its Perform Shift In Single Frame option enabled, the OnOriginCellChanged_Slow method will be run in a single frame, which is a waste. In this situation, it is better to set your UseFastOnOriginCellChangedMethod to return true and put your code in OnOriginCellChanged_Fast.

An Origin Cell change can be initiated in four ways. Via the Active Grid when the player crosses a World Reset boundary, via the Active Grid when its TryChangeOriginCellOfWorld is called, via the World when its ChangeOriginCell is called, or via the World when its LoadWorldRegion method is called with setOriginCellToWorldRegionOriginCell set to true. No matter how the Origin Cell is initiated, this or OnOriginCellChangeCompletedSlow will be used.

Parameters

IEnumerator<YieldInstruction> OnOriginCellChanged_Slow(Vector3Double shiftAmount, ReadOnlyArray<Cell> newOriginCells)

Called when the World the user is registered to has completed its Origin Cell change. There are two methods similarly named, OnOriginCellChangeCompletedFast and OnOriginCellChanged_Slow.

OnOriginCellChanged_Fast is executed in a single frame and will be called when UseFastOnOriginCellChangedMethod is implemented to return true. This is ideal when your code is lightweight and/or doesn't need to be run over multiple frames.

OnOriginCellChanged_Slow is executed (usually) over multiple frames by introducing yield statements in your method implementation, and is called when UseFastOnOriginCellChangedMethod is implemented to return false.

Also note that if you are using a World Shift component with its Perform Shift In Single Frame option enabled, the OnOriginCellChanged_Slow method will be run in a single frame, which is a waste. In this situation, it is better to set your UseFastOnOriginCellChangedMethod to return true and put your code in OnOriginCellChanged_Fast.

An Origin Cell change can be initiated in four ways. Via the Active Grid when the player crosses a World Reset boundary, via the Active Grid when its TryChangeOriginCellOfWorld is called, via the World when its ChangeOriginCell is called, or via the World when its LoadWorldRegion method is called with setOriginCellToWorldRegionOriginCell set to true. No matter how the Origin Cell is initiated, this or OnOriginCellChangeCompletedFast will be used.

Parameters

Returns

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

void OnOriginCellChanging()

Called before an Origin Cell Change has started, after all World Users have returned true for IsReadyForOriginCellChange.

You can place code that prepares for the update or blocks other code from executing (that would interfere or cause issues if it ran at the same time as the change) here. Such code should not be placed inside of the IsReadyForOriginCellChange, as even if one user returns true for this method, one or more other users may return false, in which case the change will not proceed.

An Origin Cell change can be initiated in four ways. Via the Active Grid when the player crosses a World Reset boundary, via the Active Grid when its TryChangeOriginCellOfWorld is called, via the World when its ChangeOriginCell is called, or via the World when its LoadWorldRegion method is called with setOriginCellToWorldRegionOriginCell set to true. No matter how the Origin Cell is initiated, this method will be queried.

void OnOriginCellsClamped(ReadOnlyArray<Cell> newOriginCellValues, ReadOnlyArray<Cell> clampingShift)

Called when a World's Origin Cells are clamped. Clamping can only occur when you (the dev/user) call the World's ClampOriginCells method and the world utilizes one or more endless axes. The process of clamping takes Origin Cell values that fall outside the range of the Streamable Grid dimensions and shifts them so they DO fall within the Streamable Grid dimensions.

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

The Origin Cell of course cannot reach into infinity, since it is being represented by a fixed max/min value data type (in this case, integer), so astute observers will note that this system of handling things has the (incredibly minute) chance of causing issues in some rare cases. As such, Origin Clamping is an option.

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

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

This is the purpose of this method; to notify World users that are holding data affected by the Origin Cell shift that a clamping has occured, so that they can respond appropriately. Note, of course, it is not only row data that is clamped, column and (in the case of 3D worlds) layer data is also clamped. In addition, clamping will be done on each World Grouping separately!

Parameters

bool TryDesyncFromWorld(bool failureWillDelayDestruction)

Called when the World the user is registered to is about to be destroyed. There are two scenarios where this can occur:

1) The World is being destroyed via the Component Manager. In this case {BoldTagOpen}failureWillDelayDestruction{BoldTagClose} will be true and the destruction of the World can be delayed by the World User, by returning false in the method body.

This can be used if an operation is being performed that would fail if the World were destroyed, or result in cascading errors. Each user has the method queried and if one of them returns false for this method, a frame is yielded and the users are queried again afterwards. The cycle repeats until all users desync correctly. Please note, however, that once a user desyncs (and returns true), they will not be queried again (this differs from the way IsReadyForOriginCellChange works). Only users that fail to desync are queried again.

2) The World is being destroyed via a Destroy method call or the application quitting (which could be exiting play mode if in the editor). In this scenario the destruction cannot be delayed, so failureWillDelayDestruction will be false. Your users must perform as much cleanup as they can and should generally return true. If they return false, an error message is printed giving you details about the user that failed to desync and the World that was destroyed.

Parameters

Returns

bool
True if the user was able to sucessfully desync from the world, false otherwise. It's recommended to always return true when failureWillDelayDestruction is false, as returning false will only cause an error to print (but will accomplish nothing else).