Manually trying to reason about which Origin Cell should be used and where your Player should be positioned when launching your game can be difficult. Prior to v2 of SAM, using the World Designer tool was the best method for doing this, however it was difficult to keep track of multiple potential starting configurations.
Game Start Configurations are the answer to this problem. They allow you to record a set of Player Position and Origin Cell values, which can be stored directly on the World component. You can then switch which Configuration is active (either in the inspector outside of Play Mode, or at runtime before the World is initialized using scripting), allowing you to easily change where the player starts.
It should go without saying, but when using an Active Game Start Configuration, the starting Origin Cell in the Configuration will override the Origin Cell set in the inspector!
While you can manually add and edit Game Start Configurations directly on your World Component, using the World Designer Tool will be the easiest way to work with them. To do so:
1) Load the Cells you need in order to position your player correctly.
2) Navigate to the Global Settings tab of the Tool (found under Main Controls).
3) Adjust the Origin Cell of the Tool so that the content around this starting position is as close to 0,0,0 as possible.
4) Assign your Player to the Config Player field. If your Player is only created at runtime, assign a proxy Transform to this field whose position is where you want the player to start.
5) Give the Configuration a name via the Config Name field.
6) If you want this Configuration to immediately be set as the Active Configuration, enable the Set As Active Config setting.
7) Press the Add/Update Configuration button. If a Configuration already exists with the same Config Name, that configuration will be updated with the current Origin Cell of the Tool and position of the Config Player transform. Otherwise, a new Configuration will be added.
Note, when changing the Origin Cell, always make sure to press the Update Origin Cell/Position button. The Origin Cell set on the Configuration is the values shown in parenthesis, not the values shown in the text edit fields!
You may only know which configuration you want to use at runtime. For instance, you may have a multi-player game and want to assign different Game Start Configurations to the World of each player. In these situations, you can set the Active Configuration using the PreInitialize_SetActiveGameStartConfiguration method (which, as the name indicates, must be used before the World has been initialized).
You may also need to access information about the currently Active Game Start Configuration (the player starting position most likely). This can be accomplished using the PreInitialize_TryGetActiveGameStartConfiguration method. Because there is no guarantee that any Game Start Configuration will be active, this method can return false, in which case you should not use the out parameter values!
The most common use case for this method is cases where you need to know where the Player is going to start, in order to configure other game systems for example. You may also need to retrieve the position when using something other than an Active Grid to determine which World Cells should be loaded and unloaded.
The starting player position stored in the Active Game Start Configuration is applied to any Active Grids which are synced to the World at the time of the World's initialization, and which are they themselves not initialized yet.
This is carried out via the publicly available method on the Active Grid class. You should take a look at this method, as there are certain situations where the passed in starting player position will NOT be used (e.g. when SAM persistent data is loaded).