Workspace
Manage the 3D world's physics settings, active camera, and spatial queries.
Workspace is the service that holds the 3D scene. Parts, models, terrain, and other 3D objects live under it, and it owns the physics settings and world queries that act on them.
If an object has a position in the world, it's usually parented to Workspace. Reparenting a part away from Workspace removes it from the simulated world.
Getting started
local Workspace = game:GetService("Workspace")
print(Workspace.Gravity)
local spawnPart = Workspace:FindFirstChild("SpawnPart")
if spawnPart then
print("Spawn is at", spawnPart.Position)
endProperties
| Property | Type | Access | Default | Description |
|---|---|---|---|---|
Gravity | number | Read/write | Physics default | Downward acceleration applied to simulated bodies. |
SimulatePhysics | boolean | Read/write | true | Whether the world simulates. AutoSimulate is an alias. |
GlobalWind | Vector3 | Read/write | Vector3.new(0, 0, 0) | Wind force applied to cloth and other affected objects. |
FallenPartsDestroyHeight | number | Read/write | -500 | Y position below which parts are destroyed. Clamped to -50000 through 50000. |
FallHeightEnabled | boolean | Read/write | true | Whether parts are destroyed when they fall below the limit. |
CurrentCamera | Camera? | Read/write | None until set | The camera used for rendering. |
Terrain | Terrain | Read-only | The Terrain service | Shorthand for the Terrain service. |
Dimension | Enum.Dimension | Read/write | Enum.Dimension.D3 | Which dimension the world renders and simulates. |
Enable3dRendering | boolean | Read/write | true | Whether 3D rendering is enabled. |
RenderCulling | boolean | Read/write | true | Whether off-screen parts are culled from rendering. |
MaxDrawDistance | number | Read/write | 0 | Maximum draw distance. |
LODDistance | number | Read/write | 0 | Distance used for level-of-detail switching. |
DistributedGameTime | number | Read-only | Accumulates | Time value maintained by the service. |
FinishedReplicating | signal | Read-only | N/A | Fires when the client has received the initial world data. |
GlobalWind must contain finite components; setting it to a vector with nan or inf raises an error. MaxDrawDistance and LODDistance clamp negative values to 0. FallenPartsDestroyHeight is clamped to its range rather than rejected, so a smaller value silently becomes -50000.
Turning SimulatePhysics off stops the simulation but keeps the world rendered. Cloth objects on screen switch to their preview pose while simulation is off, and switching it back on resumes from the current configuration.
Camera
Assigning CurrentCamera takes a Camera and makes it the renderer's active camera. Only a Camera object is accepted; other values aren't applied.
local Workspace = game:GetService("Workspace")
local Camera = workspace.CurrentCamera
if Camera then
Camera.FieldOfView = 70
endTerrain saves you a GetService() call when you're already working with the world:
local terrain = Workspace.TerrainMethods
Raycast
Raycast(origin: Vector3, direction: Vector3, params: RaycastParams?): RaycastResult?Casts a ray into the physics world and returns the first hit, or nil when nothing is hit. The optional RaycastParams filters which objects the query considers.
local function groundBelow(position)
local result = workspace:Raycast(position, Vector3.new(0, -100, 0))
if result then
return result.Position, result.Instance
end
return nil
endUse it for line-of-sight checks, ground detection, and placement previews. Because it goes through the physics world, it only sees objects that participate in physics and aren't filtered out by the parameters.
Runtime queries
| Signature | Description |
|---|---|
GetNumAwakeParts(): number | Number of physics bodies currently awake. |
GetRealPhysicsFPS(): number | Currently always returns 60. |
GetPhysicsThrottling(): number | Currently always returns 0. |
PGSIsEnabled(): boolean | Currently always returns true. |
GetWindowDimensions(): Vector2 | Drawable window size in UI units, excluding safe-area insets. |
Enable3D(): () | Turns 3D rendering on. |
Disable3D(): () | Turns 3D rendering off. |
GetRealPhysicsFPS() and GetPhysicsThrottling() are placeholders, so don't use them to profile frame timings. Measure with RunService instead.
GetWindowDimensions() exists on the object but isn't listed in the class's reflection metadata. It's still callable.
Events
FinishedReplicating
Fires on the client once the initial world data has arrived. The callback receives no arguments.
workspace.FinishedReplicating:Connect(function()
print("World is ready")
end)If the event fires before you connect, your callback won't run. Treat it as a one-time readiness notification rather than a persistent state query, and check the objects you need with FindFirstChild().
See also
Lighting, sky, shadows, and visual effects for the world.RunService, frame and simulation steps.Terrain, the voxel terrain owned by Workspace.
