The Public API includes various properties and methods for the Streamable Grid. The properties generally give you access to the Streamable Grids data, such as number of Rows, Columns, and Layers, while the methods focus on finding the dimensions of specific Rows, Columns, and Layers, as well as converting Endless Cell Indexes to Streamable Grid Indexes. Methods and Properties sometimes include PreInitSafe in their name. If you see one of these properties/methods, it means they can be accessed at any time (including in the editor). If you do not see PreInitSafe, it means the property/method can only be accessed after the Streamable Grid has been initialized!
A full list of the properties and methods can be found on the website using the following link, however in this Section I will be covering some especially useful things you can do with the API.
--Special Note--
You will need to add a using DeepSpaceLabs.SAM; statement in order to see the StreamableGrid class and its members!
The IsCellDisabled property includes both a Getter and Setter. The Getter allows you to retrieve a Function which can be used to evaluate whether a specific Streamable Grid Cell is disabled. By default this function simply uses the data set via the Streamable Grid in the editor, either via its inspector or via the World Designer tool.
The Setter allows you to assign your own function, overriding this default behavior. The most common use case would be using the Streamable Assets Manager with procedural worlds where the enabled/disabled state is only calculated at runtime, perhaps based on a seed value.
To access data associated with a specific LOD Group, you need to first retrieve a GridLODDetails object which contains the data. To do so, use the GetLODDetails method, which takes a 1 based LOD index as argument.
For a full overview of the data that can be retrieved via this object, take a look at the API page for the GridLODDetails object.
Extra Data stored on the Streamable Grid can either be accessed via a specific LOD Group's GridLODDetails object or directly from the Streamable Grid Global Extra Data store:
Via the LOD Group: Using GridLODDetails.TryGetExtraData_PreInitSafe
Via the Streamable Grid: Using StreamableGrid.TryGetGlobalExtraData_PreInitSafe
Both method require a key and out string argument, which will either be null (if the retrieval fails) or hold the data. Generally speaking, I recommend using the GridLODDetails method, as it will automatically query the global data store if the LOD does not contain data for the specified key.
A Streamable Grid Cell is represented by a Row, Column, and Layer value. Data belonging to a particular cell is most easily stored in a Dictionary or 3D array, however this is not the most efficient collection to use. If you wish to use a 1D array instead, you can use the Flattening functions to convert the Row/Column/Layer indexes to a single value that can be used as an index in a 1D array. These functions can either work with 1 based Cell Indexes, or 0 based Cell Indexes, however the converted 1D index will always be 0 based.
FlattenCellIndex/FlattenCellIndex_ZeroBased: Flattens a Cell Index without considering enabled/disabled cells. This creates an index into an array with size equal to total number of Streamable Cells on the Grid, which you can find out via the Streamable Grid's CalculateTotalCells method.
For especially large Grids, the size of that array will likely be too large. Since such a Grid will usually contain more Disabled Cells than Enabled Cells, you can create a more memory efficient array by storing information only for enabled cells. The arrays size would then be equal to the number of Enabled cells on the Grid (accessible via the EnabledCells property on the Grid), which should be considerably less than the total number of Cells on the Grid.
FlattenEnabledCellIndex/FlattenEnabledCellIndex_ZeroBased: Flattens a Cell Index belonging to an Enabled Cell on the Grid.
The Streamable Grid contains some methods that return enumerable structures, which can be used in a ForEach statement or iterated manually in a garbage free manner. They include:
1) StreamableGridCells_PreInitSafe: Iterates over every Cell in the Streamable Grid, regardless of whether that Cell is enabled or disabled. The iterator's Current value returns a Cell Index (containing a Row, Column, and Layer value).
2) EnabledStreamableGridCells: Iterates over every Enabled Cell in the Streamable Grid. Current returns a Cell Index (containing a Row, Column, and Layer value). Can only be used after the Streamable Grid has been initialized.
3) FlattenedEnabledStreamableGridIndexes: Iterates over every Enabled Cell in the Streamable Grid. Current returns the Flattened Cell Index of the Cell (as if the FlattenCellIndex Function was used). Can only be used after the Streamable Grid has been initialized.