Because SAM projects contain a variety of components (some having more than one version), it does not make sense to have to initialize each one individually. In addition, these components are typically interconnected and precise ordering of specific method calls is necessary to get everything up and running correctly.
Because of these two factors, all initialization is carried out via the Component Manager, however typically this is done through a proxy class, which by default is the SAMInitializer component.
No matter how you choose to initialize the Component Manager, there are two options that control how the initialization process is carried out.
Initialization is performed over two frames, which can be the Awake and Start methods if you wish.
This option is useful for testing purposes, however in a real game it is usually not recommended since Asset Chunks are loaded in a single frame, which will typically result in a lag spike.
To use this method (in order of most recommended to least):
1) On the SAMInitializer component, disable the Initialize On Startup option and call the SAMInitializer's InitializeSAM_Immediate method, either via scripting or by hooking the method up to a UI Button (can be used for live games, although gradual initialization is recommended).
2) On the SAMInitializer component, enable the Initialize On Startup option and set Initialization Type to Two_Frame (not recommended for live games).
3) While in Play Mode, use the Perform Two Frame Initialization context menu option (via the SAMInitializer inspector). Note that this will only work in the Editor, and so is not suitable for live games.
4) Call the Initialize method (via scripting) of the ComponentManager class (not recommended).
Initialization is performed over multiple frames. This is the ideal method to use, as even though it takes longer the performance impact can be spread out over multiple frames.
To use this method (in order of most recommended to least):
1) On the SAMInitializer component, disable the Initialize On Startup option and call the SAMInitializer's InitializeSAM_Gradual method, either via scripting or by hooking the method up to a UI Button (can and should be used for live games).
2) On the SAMInitializer component, enable the Initialize On Startup option and set Initialization Type to Gradual (not recommended for live games, though in some scenarios it could be used).
3) While in Play Mode, use the Perform Gradual Initialization context menu option (via the SAMInitializer inspector). Note that this will only work in the Editor, and so is not suitable for live games.
4) Call the InitializeGradually method (via scripting) of the ComponentManager class (not recommended). If you use this method, note that the method is a coroutine and must be treated as such!
You can track the progress of the Initialize Gradually operation using the InitializationProgress property of the Component Manager. It is only set to 1 once the operation has fully completed.
It should be noted that the context menu is available in the inspector by right clicking the SAMInitializer title bar or left clicking the three vertical dots in the upper right corner. Because it is only available via the inspector, the context menu options are only usable in the editor, and as such, most useful for testing. In a real game, you will need to either use Initialize On Startup, scripting, or UI based initialization (as described above).
The SAM Initializer is a simple component designed to streamline the initialization process. Using it allows you to configure different Game Objects in the scene to be activated and/or deactivated before and/or after the Component Manager is initialized. It also allows you to easily update text and/or a slider to display the Initialization Progress to your user, trigger events before/after initialization, and modify the Application.backgroundLoadingPriority setting to make initialization faster.
Note that having the SAMInitializer in the scene will not automatically trigger the initialization process, unless you enable the Initialize On Startup option. This option is primarily intended for testing purposes, however, and for a live game it is recommended to disable it and trigger the initialization via a button OnClick event or scripting.
In order to enable the Initializer to be used with a variety of UI elements, the text and slider elements have been abstracted behind the SAMText and SAMSlider components. You can use one of the default implementations of these components or create your own. The default components include the UnityUISAMText, UnityUISAMSlider, TextMeshProSAMText, and TextMeshProUGUISAMText, all of which can be added via the Add Component -> Deep Space Labs -> -> SAM -> Secondary Components menu.
To use these, simply add them to the same Game Object as the Unity UI Text component, Unity UI Slider component, Text Mesh Pro component, or Text Mesh Pro UGUI component (respectively). Then, drag the reference to the appropriate field on the SAMInitializer.
Note that the use of the SAMInitializer is optional, although without it you will need to manually handle all of the things that it does by default.
If you used the Default SAM Setup command to add SAM related objects/components to the scene, your scene should already contain a SAM Initializer. However, if for some reason you need to add one manually, you can use the information found below.
You can add this component by selecting a game object and then selecting from the Top Menu Bar:
Component -> Deep Space Labs -> -> SAM -> Primary Components -> SAM Initializer
or by selecting a game object and using the Add Component menu via its inspector:
Component -> Deep Space Labs -> -> SAM -> Primary Components -> SAM Initializer
No matter which initialization method you choose, if you have persistent data for SAM that needs to be loaded, please bear in mind that the Component Manager's Load method needs to be called BEFORE the Component Manager has been initialized!