Like World Groupings, Active Grid Groupings allow you to configure different settings for different types of assets.
This is incredibly useful, as different assets generally have different requirements for what needs to be loaded. For example, an Asset Chunk group made up of grass will typically have a smaller viewing range than one made of trees, and thus should require fewer Cells to be loaded.
With v2 of SAM, at runtime each Active Grid Grouping is matched to World Groupings using both Grouping's Name setting. For example, if Active Grid Grouping 1's name is "Terrain", it will be matched a World Grouping named "Terrain". This behavior is different than the way it worked prior to v2, where each Active Grid Grouping was matched to the same Indexed Grouping on the World (Active Grid Grouping 1 was matched to World Grouping 1). If an Active Grid Grouping does not match to a World Grouping, that Active Grid Grouping will be disabled so long as the Active Grid is synced to that World.
Because Active Grid Groupings are automatically disabled when no matching World Grouping is found, this allows for one Active Grid to be used with multiple Worlds, as you can add as many Groupings to the Active Grid as you need to support across all Worlds the Active Grid will be used with.
If updating to V2 of SAM, it is recommended to automatically upgrade all Active Grids (and other SAM components) in your scene using the Assets -> Deep Space Labs -> SAM -> Upgrade Open Scenes menu command. This will ensure that the Grouping Names between the World and Active Grid match!
When adding new Active Grid Groupings, SAM will automatically attempt to match the new Grouping's Name to the same indexed Grouping on the World the Active Grid has been assigned (under Defaults). It will use this name unless another Active Grid Grouping is already using that name.
You can also match the name of an Active Grid Grouping to the Name of the same indexed World Grouping using the Match Name To World Grouping # button below the Active Grid Grouping Name field, however if the Active Grid Grouping is not at the same index as the World Grouping you want to match it to, you will need to manually enter the name (or copy/paste it from the World).
Note that the Active Grid Grouping and World Grouping Names must match perfectly for the matching algorithm to work. Extra spaces at the beginning or end of the Name will throw it off!
Loading Blueprints define both the shape of the pattern of Active Cells that are used by each Active Grid Grouping as well as which LOD assets are needed for those Active Cells.
Blueprints must come from the Loading Blueprint Repository assigned to the Active Grid, however you can change the Blueprint used at runtime via scripting and the changes will be saved with the persistent data.
The Fallback Loading Blueprint is a sort of fallback blueprint which is used when the Grouping is synced to a World Zone for which there is no Zone Blueprint Override provided.
--Special Note--
The Fallback Loading Blueprint work a bit differently than other Default Settings. Whereas other settings are automatically NOT used when persistent data exists for the Active Grid, the Fallback Loading Blueprint will be used so long as the Loading Blueprint assigned to the Grouping at the time of the Save was not different than the Fallback Loading Blueprint.
This let's you change the Fallback Loading Blueprint even after save data exist, and that change will be applied to all save files so long as the Player was using the Fallback Loading Blueprint when the save files were created.
Zone Blueprint Overrides allow you to specify alternative Blueprints for when the Active Grid Grouping is synced to a specific Zone on the World. Typically there use is only needed when using Non Uniform Custom Shape Blueprints which are configured precisely to work with specific content, however this is up to you!
Like the Fallback Loading Blueprint, when persistent data is saved, each Override's blueprint is only saved if it is different than the one set in the inspector. This allows you to change the Blueprint in the future and that change will apply to save data (assuiming you haven't changed the blueprints via the API at runtime).
If a Zone Blueprint Override is present, it will be used to set the Blueprint when synced to that Zone! This means if you originally have the Override Blueprint set to the same Blueprint as the Fallback Loading Blueprint, then change the Fallback Loading Blueprint via the API, the Override will still apply and the original Blueprint will still be used when synced to that Zone. In order to stop using an Override, you must manually remove the Override via the API!
Learn More About Loading Blueprints & Repositories
You can choose to enable or disable whether Active Grid Groupings update the World. When disabled, the Grouping will clear any Cells it has registered as a user for the World and will not register itself as a user of new Cells. In most cases, this will effectively disable that content and cause it to be unloaded from the scene, which is primarily useful for testing purposes.
You can enable/disable this setting (Update World) before entering Play mode, or while the game is running using scripting.
Note, the Grouping still updates the Cells internally and is able to still trigger Cell Player Is In Changed and Grid Moved events.
Also note that if the Active Grid Grouping is the only user registered with the World Grouping, disabling updates will likely result in the equivalent World Cells being unloaded.
Auto Tracking is the system by which the Grouping tracks the Player and updates its internal collection of Active Cells based on the Player position. If disabled in the inspector, the Grouping will still register itself as a user of the initial Active Cells that are needed based on the Player's initial position, however those Cells will never be changed (new Cells added, old Cells removed).
If Auto Tracking is enabled at runtime but you disable it using scripting, whatever Active Cells are currently registered with the World will remain registered, which means the equivalent World Cells will not be unloaded. This is useful if you want to temporarily freeze the World Grouping so its layout of World Cells does not change (this assumes the Active Grid Grouping is the only user of the World Grouping. If it has other users, this may not be the case).
Each Active Grid Grouping is capable of firing the Cell Player Is In Changed Event. If you know that this event is never used for anything, you are free to disable it, however it should be noted that the Distance Pooling Chunk Manager requires the Cell Player Is In Changed Event to be enabled.
Also note that while you can enable/disable this events on a per Grouping basis, the event itself is actually fired outside of the Groupings. This means that any subscriber to the events will receive the events triggered by all Groupings that have the event enabled. The event args include the grouping that triggered the event, which you can use for filtering purposes.
In addition to being fired whenever the Player moves between Cells, this event is also fired whenever the Active Grid desyncs from or syncs to a World (including when the Active Grid is initialized and has a World to sync to). The event may also be fired multiple times for a single Active Grid Grouping, if that Grouping is synced to multiple Zones. This is because each Zone is treated as a separate grid of cells under the hood.
For these and other considerations, please take a look at the Cell Player Is In Changed Event Args page.
--Subscribing To Events--
While you can subscribe to this event directly using an Active Grid reference, doing so can be inefficient. For example, if you have multiple Active Grids, you would need to subscribe to each Active Grid's event separately.
The Component Manager provides a convenient event handling system (but only for this event) that offers a number of benefits:
1) You can subscribe to the event of every Active Grid in the scene, rather than just a single one, using a single method (SubscribeToCellPlayerIsInChangedEvents).
2) You can filter events to only receive event notifications when an Active Grid synced to a particular World fires the event.
3) You can filter events to only receive event notifications when a particular Grouping fires the event.
4) You can combine options 2 & 3 for more fine-tuned filtering.
More information can be found in the Event Subscription Section within the Component Managers Chapter.
Component Manager Event Subscriptions
There are two additional events which are not related to particular Active Grid Groupings. These include the Player Moved By Grid Event and World Synced To Changed Event. Both events cannot be disabled, and to subscribe to them you will need to use an Active Grid reference (no event handling is performed by the Component Manager for these events).
The World Synced To Changed Event is fired whenever the World changes, which includes when the Active Grid is initialized, when syncing to a new World, and when Desyncing from a World without syncing to a new one.
Whenever subscribing to an event (either via the Active Grid or Component Manager), never forget to unsubscribe! Usually, subscribing is best done in OnEnable and unsubscribing in OnDisable.