Engine

Instance Streaming

In-experience instance 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. Clients spend less time updating instances that aren't currently relevant to the player.
  • 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 Streaming

Instance streaming is enabled through the StreamingEnabled property of the Workspace object in Studio. This property cannot be set in a script. Streaming is enabled by default for new places created in Studio.

StreamingEnabled property enabled on Workspace object in Studio

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, utilize per‑model streaming controls, detect instance streaming, or use WaitForChild() on objects that may not exist.
  • 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.
  • 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

By default, when a player joins an experience with instance streaming enabled, instances in the Workspace are replicated to the client, excluding the following:

Then, during gameplay, the server may stream necessary instances to the client, as they are needed.

Diagram showing when various instances and their descendants stream in
1 Terrain is treated uniquely, in that the instance replicates to the client when the experience loads, but terrain regions only stream in when needed

Model Behavior

Models set to non-default behavior like Atomic stream in under special rules as outlined in Per‑Model Streaming Controls. However, default (nonatomic) models are sent differently based on whether ModelStreamingBehavior is set to Default (Legacy) or Improved.

ModelStreamingBehavior property of Workspace object

When ModelStreamingBehavior is set to Default/Legacy, the Model container and its non‑spatial descendants such as Scripts replicate to the client when the player joins. Then, when eligible, the model's BasePart descendants stream in.

Diagram showing default model stream in behavior

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.

When an instance streams out, it is parented to nil so that any existing Luau state will reconnect if the instance streams back in. As a result, removal signals such as ChildRemoved or DescendantRemoving fire on its parent or ancestor, but the instance itself is not destroyed in the same sense as an Instance:Destroy() call.

To further anticipate stream out, examine these scenarios:

ScenarioExampleStreaming Behavior
A part is created locally through Instance.new() in a LocalScript.In a "capture the flag" game, you create and attach blue helmet parts to all players on the blue team through a LocalScript.The part is not replicated to the server, and it is exempt from streaming out unless you make it a descendant of a part that exists on the server, such as a part within a player's character model.
A part is cloned locally from ReplicatedStorage through Instance:Clone() in a LocalScript.A wizard character casts a spell by activating a Tool, upon which an object including several special effects is cloned from ReplicatedStorage and parented to the workspace at the wizard's position.The part is not replicated to the server, and it is exempt from streaming out unless you make it a descendant of a part that exists on the server.
A part is reparented from ReplicatedStorage to the workspace via a LocalScript.A "wizard's hat" is stored in ReplicatedStorage. When a player chooses to play on the wizard's team, the hat is moved into their character model via a LocalScript.The part remains eligible for streaming out since it came from the server and was replicated to ReplicatedStorage. Avoid this pattern as it causes a desync between the client and server, and the part may stream out; instead, clone the part.

Model Behavior

If you set ModelStreamingBehavior to Improved, the engine may stream out Default (Nonatomic) models when they're eligible to stream out, potentially freeing up memory on the client and reducing the instances which need property updates.

ModelStreamingBehavior property of Workspace object

Under Improved model streaming behavior, streaming out of Default (Nonatomic) models is based on whether the model is spatial (contains BasePart descendants) or non‑spatial (contains no BasePart descendants).

  • A spatial model only streams out completely when its last remaining BasePart descendant streams out, since some of the model's spatial parts may be near to the player/replication focus and some far away.
  • A non‑spatial model only streams out when an ancestor streams out, equivalent to legacy streaming out behavior.

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:

Assembly CompositionStreaming Behavior
Unanchored parts onlyEntire assembly is sent as an atomic unit.
Anchored root partOnly the parts, attachments, and constraints needed to link the streamed parts to the root part are streamed in together.

Timing Delay

There may be a slight delay of ~10 milliseconds between when a part is created on the server and when it gets replicated 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.

ScenarioExampleStreaming Behavior
A LocalScript makes a RemoteFunction call to the server to create a part.A player activates a Tool locally to spawn a part on the server that all players can see and interact with.When the remote function returns to the client, the part may not yet exist, even though the part is close to the client focus and within a streamed area.
A part is added to a character model on the server via a Script and a RemoteEvent is fired to a client.When a player joins the police team, a "police badge" part stored in ServerStorage is cloned and attached to the player's character model. A RemoteEvent is fired and received by that player's client in order to update a local UI element.Although the client receives the event signal, there is no guarantee that the part has already streamed to that client.
A part collides with an invisible region on the server and triggers a RemoteEvent on the client.A player kicks a soccer ball into a goal, triggering a "goal scored" event. Other players that are close to the goal may see the "goal scored" event before the ball has been streamed to them.

Streaming Properties

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

Streaming properties shown on Workspace object in Studio

ModelStreamingBehavior

Controls whether Default (Nonatomic) models are replicated when a player joins, or are only sent when needed. If this property is set to Improved, models in Workspace will only be sent to clients when needed, potentially speeding up join times. See Technical Behavior for more details.

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 Enum.StreamingIntegrityMode documentation for more details.

StreamingMinRadius

The StreamingMinRadius property indicates the radius around the player's character (or ReplicationFocus) in which instances stream 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 instances stream in. Note that the engine is allowed to retain previously loaded instances beyond the target radius, memory permitting.

A smaller StreamingTargetRadius reduces server workload, as the server will not stream in additional instances 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:

SettingStreaming Behavior
DefaultDefault behavior, currently the same as LowMemory.
LowMemoryThe client only streams out parts in a low memory situation and may remove 3D content until only the minimum radius is present.
OpportunisticRegions beyond StreamingTargetRadius can be removed on the client even when there is no memory pressure. In this mode, the client never removes instances that are closer than the target radius, except in low memory situations.

Per-Model Streaming Controls

Globally, the ModelStreamingBehavior property lets you control how models are streamed in on join. Additionally, to avoid issues with streaming on a per-model basis and minimize use of WaitForChild(), you can customize how Models and their descendants stream through their ModelStreamingMode property.

ModelStreamingMode property indicated on a model's properties in Studio

Default / Nonatomic

When a Model is set to Default or Nonatomic, streaming behavior varies based on whether ModelStreamingBehavior is set to Default (Legacy) or Improved.

ModelStreamingBehaviorTechnical Behavior
Default (Legacy)The model is replicated when a player joins. This potentially results in more instances sent during loading, more instances stored in memory, and additional complexity for scripts that want to access the model's descendants. For example, a separate LocalScript will need to use WaitForChild() on a descendant BasePart inside the model.
ImprovedThe model is only sent when needed, potentially speeding up join times.

See Technical Behavior for more details.

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 that needs to access instances in the model would need to useWaitForChild() on the model itself, but not on a descendant MeshPart or Part since they are sent alongside the model.

An atomic model is only streamed out when all of its descendant parts are eligible for streaming out, at which point the entire model streams out together. If only some parts of an atomic model would typically be streamed out, the entire model and its descendants remain on the client.

Diagram showing Atomic model streaming along with children
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.

Diagram showing Persistent model streaming along with children
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 the Tags section of an instance's properties, or Studio's Tag Editor, 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 tagName = "FlickerLightSource"
    local random = Random.new()
    local flickerSources = {}
    -- Detect currently and new tagged parts streaming in or out
    for _, light in CollectionService:GetTagged(tagName) do
    flickerSources[light] = true
    end
    CollectionService:GetInstanceAddedSignal(tagName):Connect(function(light)
    flickerSources[light] = true
    end)
    CollectionService:GetInstanceRemovedSignal(tagName):Connect(function(light)
    flickerSources[light] = nil
    end)
    -- Flicker loop
    while true do
    for light in flickerSources do
    light.Brightness = 8 + random:NextNumber(-0.4, 0.4)
    end
    task.wait(0.05)
    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 Players = game:GetService("Players")
local GuiService = game:GetService("GuiService")
local player = 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 by default. However, you can instruct the engine to render lower resolution "imposter" meshes for models that are not present on clients through each model's LevelOfDetail property.

LevelOfDetail property indicated for Model instance
Model in actual level of detail
Actual model
Model represented as low resolution imposter mesh
Low resolution "imposter" mesh
Model SettingStreaming Behavior
StreamingMeshActivates the asynchronous generation of an imposter mesh to display when the model is not present on clients.
Disabled / AutomaticThe model disappears when outside the streaming radius.

When using imposter meshes, note the following:

  • 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.
  • 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 as well as its descendant models. For better performance, it's recommended that you use Disabled for descendant models.
  • Textures are not supported; imposter meshes are rendered as smooth meshes.
  • While a Model is not completely streamed in, the imposter mesh is rendered instead of individual parts of the model. Once all individual parts are streamed in, they render and the imposter mesh is ignored.
  • Imposter meshes have no physical significance and they act as non-existent with respect to raycasting, collision detection, and physics simulation.
  • Editing a model in Studio, such as adding/deleting/repositioning child parts or resetting colors, automatically updates the representative mesh.