In order to support extremely large game environments, the World uses a floating origin based anchoring system. This system uses four key pieces of data to function; the World Grid, Zone Positions, the Origin Position and the Origin Cell.
Imagine your world is built on an invisible World Grid, like a giant 3D graph paper. This grid is divided into rows, columns, and layers—just like a Rubik’s Cube. Each row, column, and layer has a size you define (for example, rows might be 100 units long) via the World Dimensions settings in the General Settings tab of the World component.
--Version 2.0.0+ Note--
Prior to v2 of SAM, the Origin Cell referenced a Cell on the Base Grouping's Streamable Grid. With v2, we are introducing the concept of the World Grid, as mentioned above, and the Origin Cell is now in reference to a cell on this Grid. So long as you have upgraded your Worlds (using Assets -> Deep Space Labs -> SAM -> Upgrade Open Scenes), the Origin Cell will be updated to reflect this change and your Worlds should continue functioning normally.
The Origin Position is a fixed point in World Space where a specific cell of the World Grid will align. Think of it as the anchor point where the grid is pinned down in your game world. For example, you might set the Origin Position to (0, 0, 0) in Unity world space, or to some other location that makes sense for your game.
Once set, the Origin Position is usually left alone—it’s the stable point you build around.
The Origin Cell is the specific cell in your World Grid that will be aligned with the Origin Position. For example, you might say:
Origin Cell = Row 1, Column 1, Layer 1
Origin Position = (0, 0, 0)
This means that World Grid Row 1, Column 1, Layer 1 will sit exactly at (0, 0, 0) in Unity world space.
But here’s the twist: The Origin Cell can change. If your player moves far enough away, the system might shift the Origin Cell automatically to a new cell to keep the world stable and avoid floating point errors or precision issues. Or, you might change it manually for a specific purpose.
Content in SAM is associated with Streamable Grids, which are in turn combined together to form Zones.
All Streamable Grids that are part of the same Zone are aligned at their minimum point, which you can think of as the Zone's anchor point. In order to give Zone's actual position within the scene, we start by defining the Zone's Anchor Point position relative to World Grid Cell Row 1, Column 1, Layer 1.
This position (The Zone Position) effectively tells SAM how far a Zone is from World Grid Cell 1,1,1 on any given axis. A Zone Column Position of 400, for example, tells SAM the Zone is 400 units to the right (on the X Axis) of World Grid Column 1.
Currently you must enter the Zone Position manually, so we recommend sitting down with pen and paper and drawing out your World as best you can, with World Grid Cell 1,1,1 being placed as close to the center of your game world as possible. In the future we will introduce a GUI based workflow for viewing the layout of Zones and changing their positions.
Do not fret too much about getting the Zone Positions correct at the start. The great thing about this system is that you can change the position of Zones in relation to the World Grid at any time, which effectively allows you to reposition Zones in relation to other Zones with ease.
We now have the following key pieces of information to help us position each Zone within the game (i.e., world space):
1) A World Grid with consistent row lengths, column widths, and layer heights.
2) The position of each zone relative to Cell 1,1,1 on this World Grid.
3) The Origin Cell, which is the Cell from the World Grid which will be placed at the Origin Position.
4) The Origin Position, which is the world space position the Origin Cell will be placed at.
Because each Zone's Position (relative to World Grid Cell 1,1,1) remains fixed once the game starts, determining the in-game position of each Zone is a very simple mathematical operation, no matter which Origin Cell is used. We can also shift the in-game position of Zones very easily, by simply changing which World Grid Cell serves as the Origin Cell!
Imagine a Game World representing several continents of Earth. We might start by projecting this world onto a 2D map.
This map represents the logical layout of different zones in relation to each other, and in relation to World Grid Cell L1,R1,C1 (red outline) which is near the center of the map. We have marked the Column Position of each Zone, which is simply the distance from the World Grid Cell L1,R1,C1 (minimum point) to each zone (minimum point) on the X Axis. You can see that for Africa and South America, the Column Position is negative, since these Zones' positions are left of World Grid Cell L1,R1,C1', while Australia's Column Position is positive.
In-Game, assuming the Origin Position of our World is 0,0,0, if we were to use World Grid Cell L1,R1,C1 as the Origin Cell, the Australia Zone would have an X position of 3450, while Africa and South America would have X positions of -2350 and -5150 respectively.
However, if we change the Origin Cell to L1,R1,C3 (meaning the blue cell on the map would be fixed to where the red cell currently is), this would shift all of the Zones by -1000 (because we are shifting it by two columns, and each World Grid Column in this example has a width of 500). Thus, Australia would now have an X position of 2450, Africa -3350, and South America -6150.
In the example above, you can hopefully see that as we change the Origin Cell, some Zones (Australia) are pulled closer to 0,0,0, while other Zones are pushed away from it (Africa and South America). As the player travels around your game World, it's important that the content which immediately surrounds the player (as well as the player itself) is as close to World Space position 0,0,0 as possible. This is because the closer to 0,0,0, the more precision that will be available for various mathematical calculations. This results in more accurate calculations and helps reduce (or eliminate entirely) various issues, such as Z-Fighting, animation jittering, and physics peculiarities.
By adjusting the Origin Cell, we can shift the Zones (and by extension their content) in the direction we need. SAM also has several ways of shifting the Player in conjunction with the Origin Cell changes, to ensure that everything that is loaded is as close to 0,0,0 as possible!
And don't worry about those Zones which seem to be drifting further and further away from 0,0,0 as your player moves in one direction. As long as SAM is configured correctly, the Cells for those Zones will be unloaded LONG before they are too far from the origin.
In order to ensure that your World's layout matches what it was prior to v2, we have added an automatic upgrade path for the Origin Cell. This upgrade process will set the Origin Cell to a value which should result in the same cell layout you were getting prior to the update.
If it's important that everything be loaded exactly where it was prior to your upgrade to v2 of SAM, we recommend keeping the upgraded Origin Cell as is. If it's not important, you can review the Origin Cell and change it as you wish.
The upgrade process runs automatically when you click on a World in the scene (you will need to save the scene after), however we recommend using the Upgrade Command instead, which will upgrade all Worlds' in the scene, as well as other components and assets referenced in the scene which may need to be upgraded with v2. To use this command, simply press Assets - > Deep Space Labs -> SAM -> Upgrade Open Scene
If this command is greyed out, it means there are no components or assets in the scene which need to be upgraded.
In general, when launching your game, the Origin Cell used will either be the Origin Cell configured in the Origin Settings tab on the World component, or the Origin Cell stored in the Active Game Start Configuration (if using Game Start Configurations).
This behavior can be overridden in two ways:
1) If SAM persistent data is loaded before the World is initialized, that persistent data will typically contain the Origin Cell at the time that data was saved, and the World's Origin Cell will be set to it in order to ensure the layout of the World matches what it was at the time of the save.
2) You can manually override the starting Origin Cell via scripting, by using the World's PreInitialize_SetOriginCell method. Do note, this can only be used to override the Origin Cell set in the Origin Settings tab. If you are using an Active Game Start Configuration, this method's Origin Cell will not override the Configuration's Origin Cell!
While you can manually change the Origin Cell at any time, it is usually best to enable automatic re-centering, which automatically resets the Origin Cell when the player travels a pre-set distance from the Origin Position in any direction. To enable this functionality, you need to:
1) Enable Allow Active Grid Re-Centering on your World, which can be found within the Origin Settings Window.
2) Define the Re-Centering Boundary Distances From Origin. These define how far the player can travel from the Origin before a re-centering operation is triggered.
3) Enable Allow Grid To Re-Center World on at least one Active Grid that will be synced to the World, which can be found within the General Settings Window.
When the Player crosses the World Re-Centering Boundary, a world re-centering is triggered. This re-centering operation basically identifies which World Grid Cell the Player is in and then performs an Origin Cell Change, making that World Grid Cell the new Origin Cell. This results in the World being re-positioned so that the Player is more or less close to the Origin Position.
You can also change the Origin Cell of the World manually via the World's Change Origin Cell method, by loading World Regions, or by using the TryMovePlayerAndChangeOriginCellOfWorld method from the Active Grid class.
The Active Grid method is recommended if you are transporting the Player across large distances from one part of the World to another.
World Shifters fully manage the shifting process.
While we include a default World Shifter in SAM (that works with the Standard Hierarchy Organizer), you are also free to create a custom World Shifter for more fine-tuned control over the shifting process.
When using a Floating Origin communicating position data can be challenging, since most positions are relative to the current layout (dictated by the Origin Cell) rather than fixed scene positions.
You have two choices for how you communicate Position Data.
1) As Raw Scene Relative Positions (Vector3).
2) As Cell relative positions, in which case you must also send information about the Cell the position data is relative to
Option 1 should only be used if you know that the Scene Relative Positional Data will be accurate at the time the receiving system processes it. Put another way, the Origin Cell in use by the receiving system's game environment at the time of processing must be the same as the Origin Cell in use by the sending system's game environment when the position was recorded.
For example, in a multiplayer game, each client is likely to be using a different Origin Cell, so using option 1 to send data to/from different clients is not possible. Instead, you must convert each client's Scene Relative Positions to Cell Relative Positions, then send that data.
At the client's end, they can look at the position and the Cell it is relative to and basically say, "Okay, so this position is relative to Cell 1_4. Cell 1_4 is at position x,y,z in my game world, which means that the position is at x2, y2, z2."
For systems that are confined to the client only (using only data from that client and nothing else), using the Scene Relative Positions is usually not a problem, so long as you have a system in place that monitors and takes into account changes to the Origin Cell.
When sending Cell Relative Positions, using the Origin Cell as the reference cell is generally the easiest thing to do and is recommended in most cases, especially because it allows you to send multiple positions in combination with just a single Cell, which means using less network bandwidth. The only caveat to this is if whatever positions you are sending are a far distance from this Origin Cell, their relative positions may be too large and introduce floating point errors.
In these cases, you can either use the World Grid Cell that the position is in as the reference cell (recommended), or the Endless Grid Cell for a particular Zone and World Grouping (not recommended since you will need to send the Zone and World Grouping IDs as well) which will give a smaller relative position that you can send.
The API for the World has several translation methods to help you with these tasks.
The Component Manager's Save method automatically saves each World's current Origin Cell with the save data, allowing it to be restored when that data is loaded. Under most situations, this means you should be able to save Scene Relative Position data without issue. However, if implementing a Save System where the saving can occur over multiple frames, special care must be taken to ensure the Origin Cell does not change while the save operation is executing. Please adhere to the following guidelines in these situations:
1) Your Save script should implement the IWorldUser interface and register with the World as a user.
2) You should return false for the IWorldUser's IsReadyForOriginCellChange implementation if it is queried while a save operation is in progress.
3) Once the World Users OnOriginCellChanging method is called (which indicates that the Origin Cell Change is now in progress), the save script should delay save operations until the change is completed.
4) Depending on the value you return from your World User's UseFastOnOriginCellChangedMethod property, either OnOriginCellChanged_Fast or OnOriginCellChanged_Slow will be called. These methods are called when the Origin Cell change has completed, so you can use one of them to remove the save delay. You could even use the OnOriginCellChanged_Slow method to execute the pending multi-frame save.
The World delays execution of its next Update (in which the Origin Cell will be changed) until all users return true for IsReadyForOriginCellChange, which allows users to purposely delay the Origin Cell Change if it would cause issues with an operation they currently have in progress.
For more information on World Users and the IWorldUser interface, please take a look at the World Users Section within this Chapter.
Each Zone Grouping has an Origin Cell and Origin Position that is calculated at runtime. The Zone Grouping Origin Cell is effectively the Endless Grid Cell from the Zone Grouping that is closest to the Origin Position of the World, while the Origin Position is the world position of this Endless Grid Cell.
You can view these values in the inspector of the World, via it's Zones Tab, although we do not know how useful they will be to you.
These settings can also be retrieved via scripting after the World has been initialized, using the GetOriginCellOfZoneGrouping and GetOriginCellPositionOfZoneGrouping methods.
Do keep in mind that if your game world is small, there may not be a need to use a floating origin based World. In such worlds, you can always use the Scene Relative Positions if you know that the Origin Cell will never change.
For such Worlds, it is recommended to set the Origin Cell and Position in the inspector such that the center of your game world is as close to point 0,0,0 as possible.
The goal for floating Worlds is to configure the Origin Position in a way that the World will be as balanced as possible. Balanced in this sense simply means that at any given moment, the same amount of content is loaded in each direction of each used axis.
To start, you can try setting the Origin Position to a negative offset equal to half your World Grid Cell dimensions. This may not work perfectly but you can adjust the value as needed during game development (only when you start dealing with systems that rely on the Origin Position remaining stable [such as save systems] should you try to keep the Origin Position the same).
The Origin Cell Layer of the World can only be configured if the Predominant Axes Type of your World is Three Dimensional, otherwise the Layer value will be fixed at 1, and cannot be changed by any means. This means setting a Layer value other than 1 via the inspector, Game Start Configurations, World Regions, or scripting will not have any affect. The player's Y or Z (if using a 2D XY World) will also not cause automatic origin shifting, since the origin cell layer cannot be any other value except 1.