Skip to Content
Kinemium
Services

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)
end

Properties

PropertyTypeAccessDefaultDescription
GravitynumberRead/writePhysics defaultDownward acceleration applied to simulated bodies.
SimulatePhysicsbooleanRead/writetrueWhether the world simulates. AutoSimulate is an alias.
GlobalWindVector3Read/writeVector3.new(0, 0, 0)Wind force applied to cloth and other affected objects.
FallenPartsDestroyHeightnumberRead/write-500Y position below which parts are destroyed. Clamped to -50000 through 50000.
FallHeightEnabledbooleanRead/writetrueWhether parts are destroyed when they fall below the limit.
CurrentCameraCamera?Read/writeNone until setThe camera used for rendering.
TerrainTerrainRead-onlyThe Terrain serviceShorthand for the Terrain service.
DimensionEnum.DimensionRead/writeEnum.Dimension.D3Which dimension the world renders and simulates.
Enable3dRenderingbooleanRead/writetrueWhether 3D rendering is enabled.
RenderCullingbooleanRead/writetrueWhether off-screen parts are culled from rendering.
MaxDrawDistancenumberRead/write0Maximum draw distance.
LODDistancenumberRead/write0Distance used for level-of-detail switching.
DistributedGameTimenumberRead-onlyAccumulatesTime value maintained by the service.
FinishedReplicatingsignalRead-onlyN/AFires 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
end

Terrain saves you a GetService() call when you're already working with the world:

local terrain = Workspace.Terrain

Methods

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
end

Use 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

SignatureDescription
GetNumAwakeParts(): numberNumber of physics bodies currently awake.
GetRealPhysicsFPS(): numberCurrently always returns 60.
GetPhysicsThrottling(): numberCurrently always returns 0.
PGSIsEnabled(): booleanCurrently always returns true.
GetWindowDimensions(): Vector2Drawable 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.

On this page