Content Streaming

In-experience content streaming allows the Roblox engine to dynamically load and unload 3D content and related instances in regions of the world. This can improve the overall player experience in several ways, for example:

• Faster join times — Players can start playing in one part of the world while more of the world loads in the background.
• Memory efficiency — Experiences can be played on devices with less memory since content is dynamically streamed in and out. More immersive and detailed worlds can be played on a wider range of devices.
• Improved performance — Better frame rates and performance, as the server can spend less time and bandwidth synchronizing changes between the world and players in it.
• Level of detail — Distant models and terrain remain visible even when they're not streamed to clients, keeping the experience optimized without entirely sacrificing background visuals.

Enabling Content Streaming

Content streaming can be enabled through the StreamingEnabled property of the Workspace object in Studio (this property cannot be set in a script).

Once enabled, it's recommended that you adhere to the following practices:

• Because clients will not typically have the entire Workspace available locally, use the appropriate tool/API to ensure that instances exist before attempting to access them in a LocalScript. For example, use WaitForChild() on objects that may not exist, detect instance streaming, or utilize model streaming controls.
• Minimize placement of 3D content outside of Workspace. Content in containers such as ReplicatedStorage or ReplicatedFirst is ineligible for streaming and may negatively impact join time and memory usage.
• If you move a player's character by setting its CFrame, do so from a server-side Script and use streaming requests to more quickly load data around the character's new location.
• Avoid parenting a part to another part, especially when the parent is far away from the child. Instead, group them as a Model or place them inside a Folder.
• Manually set the player's ReplicationFocus only in unique situations such as in experiences that don't use a Player.Character. In these cases, make sure the focus is near the object(s) that the player controls to ensure content continues to stream in around the player's interaction point.

Technical Behavior

Streaming In

When a player joins, all instances in the Workspace are sent to the client, excluding BaseParts, atomic or persistent models, and descendants of those instances. Then, during gameplay, the server streams in BaseParts and their descendants to the client, as well as atomic and persistent models.

Streaming Out

During gameplay, a client may stream out (remove from the player's Workspace) regions and the BaseParts contained within them, based on the behavior set by StreamOutBehavior. The process begins with regions furthest away from the player's character (or ReplicationFocus) and moves in closer as needed. Regions inside the StreamingMinRadius range never stream out.

To further anticipate stream out, examine these scenarios:

Assemblies and Mechanisms

When at least one part of an assembly is eligible for streaming in, all of the assembly's parts also stream in. However, an assembly will not stream out until all of its parts are eligible for streaming out. During streaming, all of the Constraints and Attachments descending from BaseParts and atomic or persistent Models also stream, helping to ensure consistent physics updates on clients.

Note that assemblies with anchored parts are treated slightly differently than assemblies with only unanchored parts:

Timing Delay

There may be a slight delay of ~10 milliseconds between when a part is created on the server and when it gets sent to clients. In each of the following scenarios, you may need to use WaitForChild() and other techniques rather than assuming that events and property updates always occur at the same time as part streaming.

Streaming Properties

The following properties control how content streaming applies to your experience. All of these properties are non-scriptable and must be set on the Workspace object in Studio.

StreamingIntegrityMode

Your experience may behave in unintended ways if a player moves into a region of the world that hasn't been streamed to them. The Streaming Integrity feature offers a way to avoid those potentially problematic situations. Please see the StreamingIntegrityMode documentation for more details.

StreamingMinRadius

The StreamingMinRadius property indicates the radius around the player's character (or ReplicationFocus) in which content streams in at the highest priority. Care should be taken when increasing the default, as doing so will require more memory and more server bandwidth at the expense of other components.

StreamingTargetRadius

The StreamingTargetRadius property controls the maximum distance away from the player's character (or ReplicationFocus) in which content streams in. Note that the engine is allowed to retain previously loaded content beyond the target radius, memory permitting.

A smaller StreamingTargetRadius reduces server workload, as the server will not stream in additional content beyond the set value. However, the target radius is also the maximum distance players will be able to see the full detail of your experience, so you should pick a value that creates a nice balance between these.

StreamOutBehavior

The StreamOutBehavior property sets the streaming out behavior according to one of the following values:

Model Streaming Controls

As noted previously, the client of a joining player receives all instances in the Workspace, excluding BaseParts, atomic or persistent models, and descendants of those instances. Then, during gameplay, the server streams in BaseParts and their descendants to the client, as well as atomic and persistent models.

To avoid issues with model streaming and minimize use of WaitForChild(), you can customize how Models and their descendants stream through their ModelStreamingMode property.

Default / Nonatomic

When a Model is set to Default or Nonatomic, its child Script instance will exist when the experience loads, but its child MeshPart and Part will not exist. This results in more instances that must be sent during loading, more instances stored in memory, and additional complexity for scripts that want to access the contents of the model. For example, a separate LocalScript will need to use WaitForChild() on the descendant MeshPart and Part.

LocalScript
-- Default/Nonatomic model exists at load time and is immediately accessible
local model = workspace.Model

-- Descendant parts do not exist at load time; use WaitForChild()
local meshPart = model:WaitForChild("MeshPart")
local part = model:WaitForChild("Part")

Atomic

If a Model is changed to Atomic, all of its descendants are streamed in together when a descendant BasePart is eligible. As a result, a separate LocalScript will need to use WaitForChild() on the model, but not on its descendant MeshPart or Part.

LocalScript
-- Atomic model does not exist at load time; use WaitForChild()
local model = workspace:WaitForChild("Model")

-- Descendant parts stream in with model and are immediately accessible
local meshPart = model.MeshPart
local part = model.Part

Persistent

Persistent models are not subject to normal streaming in or out. They are sent as a complete atomic unit soon after the player joins and before the Workspace.PersistentLoaded event fires. Persistent models and their descendants are never streamed out, but to safely handle streaming in within a separate LocalScript, you should use WaitForChild() on the parent model, or wait for the PersistentLoaded event to fire.

LocalScript
-- Persistent model does not exist at load time; use WaitForChild()
local model = workspace:WaitForChild("Model")

-- Descendant parts stream in with model and are immediately accessible
local meshPart = model.MeshPart
local part = model.Part

PersistentPerPlayer

Models set to PersistentPerPlayer behave the same as Persistent for players that have been added using Model:AddPersistentPlayer(). For other players, behavior is the same as Atomic. You can revert a model from player persistence via Model:RemovePersistentPlayer().

Requesting Area Streaming

If you set the CFrame of a player character to a region which isn't currently loaded, streaming pause occurs, if enabled. If you know the character will be moving to a specific area, you can call Player:RequestStreamAroundAsync() to request that the server sends regions around that location to the client.

The following scripts show how to fire a client-to-server remote event to teleport a player within a place, yielding at the streaming request before moving the character to a new CFrame.

Script - Teleport Player Character
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local teleportEvent = ReplicatedStorage:WaitForChild("TeleportEvent")

local function teleportPlayer(player, teleportTarget)
	-- Request streaming around target location
	player:RequestStreamAroundAsync(teleportTarget)

	-- Teleport character
	local character = player.Character
	if character and character.Parent then
		local currentPivot = character:GetPivot()
		character:PivotTo(currentPivot * CFrame.new(teleportTarget))
	end
end

-- Call teleport function when the client fires the remote event
teleportEvent.OnServerEvent:Connect(teleportPlayer)

LocalScript - Fire Remote Event
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local teleportEvent = ReplicatedStorage:WaitForChild("TeleportEvent")
local teleportTarget = Vector3.new(50, 2, 120)

-- Fire the remote event
teleportEvent:FireServer(teleportTarget)

Detecting Instance Streaming

In some cases, it's necessary to detect when an object streams in or out and react to that event. A useful pattern for streaming detection is as follows:

1. Using a tool such as the Tag Editor, accessible from Studio's View tab, assign a logical CollectionService tag to all of the affected objects.

2. From a single LocalScript, detect when a tagged object streams in or out through GetInstanceAddedSignal() and GetInstanceRemovedSignal(), then handle the object accordingly. For example, the following code adds tagged Light objects into a "flicker" loop when they stream in and removes them when they stream out.

   LocalScript - CollectionService Streaming Detection
   local CollectionService = game:GetService("CollectionService")
   local RunService = game:GetService("RunService")
   
   local random = Random.new(tick())
   local heartbeatCount = 0
   local flickerSources = {}
   
   -- Detect tagged parts streaming in or out
   if workspace.StreamingEnabled then
   	CollectionService:GetInstanceAddedSignal("FlickerLightSource"):Connect(function(light)
   		flickerSources[light] = true
   	end)
   	CollectionService:GetInstanceRemovedSignal("FlickerLightSource"):Connect(function(light)
   		flickerSources[light] = nil
   	end)
   end
   
   -- Flicker loop
   RunService.Heartbeat:Connect(function()
   	heartbeatCount += 1
   	if heartbeatCount > 5 then
   		heartbeatCount = 0
   		for light, _ in pairs(flickerSources) do
   			light.Brightness = 8 + random:NextNumber(-0.4, 0.4)
   		end
   	end
   end)

Customizing the Pause Screen

The Player.GameplayPaused property indicates the player's current pause state. This property can be used with a GetPropertyChangedSignal() connection to show or hide a custom GUI.

LocalScript
local GuiService = game:GetService("GuiService")
local player = game.Players.LocalPlayer

-- Disable default pause modal
GuiService:SetGameplayPausedNotificationEnabled(false)

local function onPauseStateChanged()
	if player.GameplayPaused then
		-- Show custom GUI
	else
		-- Hide custom GUI
	end
end

player:GetPropertyChangedSignal("GameplayPaused"):Connect(onPauseStateChanged)

Model Level-of-Detail

When streaming is enabled, Models outside of the currently streamed area will not be visible. However, you can tell the engine to create approximate "imposter meshes" for models that are not present on clients. Level-of-detail for these meshes works on a per-model basis and is selectable via the model's LevelOfDetail property.

When using imposter meshes, note the following precautions:

• Imposter meshes are designed to be seen at 1024 studs away from the camera or further. If you've reduced StreamingTargetRadius to a much smaller value like 256, imposter meshes may not be visually acceptable for the model they replace.
• Textures are not supported; imposter meshes are rendered as smooth meshes.
• If a model and its descendant models are all set to StreamingMesh, only the top-level ancestor model is rendered as an imposter mesh, wrapping all geometries under the ancestor model as well as its descendant models. For better performance, it's recommended that you use Disabled for descendant models.