Workspace
The core job of Workspace is to hold objects that exist in the 3D world, effectively BaseParts and Attachments. While such objects are descendant of Workspace, they will be active. For BaseParts, this means they will be rendered, and physically interact with other parts and the world. For Attachments, this means that objects adorned to them, such as ParticleEmitters, Beams, and BillboardGuis, will render.
Understanding this behavior is important, as it means objects can be removed from Workspace when they are not needed. For example, map Models can be removed when a different map is being played on. Objects that are not immediately needed in the 3D world are generally stored in ReplicatedStorage or ServerStorage.
In its role as the holder of active 3D objects, Workspace includes a number of useful functions related to parts, their positions, and joints between them.
Accessing the Workspace
Workspace can be accessed several ways, all of which are valid.
- workspace
- game:GetService("Workspace")
- game.Workspace
Notes
- Objects that require adornment, such as ParticleEmitters and BillboardGuis, will be at the
(0, 0, 0) position when parented to Workspace without an adornee otherwise being set. - The Model:MakeJoints() and Model:BreakJoints() methods inherited from the Model class are overridden by Workspace:MakeJoints() and Workspace:BreakJoints() which can only be used in plugins.
- It is impossible to delete Workspace.
- A client's current Camera object can be accessed using the Workspace.CurrentCamera property.
- The Terrain object can be accessed using the Workspace.Terrain property.
Summary
Properties
The air density at ground level, used in the aerodynamic force model.
Determines whether assets created by other users can be sold in the game.
Specifies the animation throttling mode for the local client.
The Camera object being used by the local player.
The amount of time, in seconds, that the game has been running.
Determines the height at which falling BaseParts and their ancestor Models are removed from Workspace.
Determines whether the physics engine computes aerodynamic forces on BaseParts whose EnableFluidForces property is true.
Specifies the global wind vector for animated terrain grass, dynamic clouds, and particles.
Determines the acceleration due to gravity applied to falling BaseParts.
Enables support for constraints for IKControls. If disabled, IKControls ignore physics constraints.
Sets whether character Heads and Accessories should be downloaded as MeshParts.
Controls the logic used to select the assembly root part when using any of the mover constraints.
Sets how the solver will advance the physics simulation forward in time.
Configures when the engine resumes event handlers.
Configures how the engine decides when to Stream content away from players.
Whether content streaming is enabled for the place.
Determines whether StreamingIntegrityMode is active.
Minimum distance that content will be streamed to players with high priority.
Maximum distance that content will be streamed to players.
A reference to the Terrain object parented to the Workspace.
Determines whether parts in different groups set to not collide will ignore collisions and touch events.
Properties
Sets the level of detail on the model for experiences with instance streaming enabled.
Controls the model streaming behavior on Models when instance streaming is enabled.
The primary part of the Model, or nil if not explicitly set.
Editor-only property used to scale the model around its pivot. Setting this property will move the scale as though Model/ScaleTo was called on it.
Determines where the pivot of a Model which does not have a set Model.PrimaryPart is located.
Properties
Methods
Returns the number of BaseParts that are deemed physically active, due to being recently under the influence of physics.
Returns an integer, between 0 and 100, representing the percentage of real-time that physics simulation is currently being throttled to.
Returns the number of frames per second that physics is currently being simulated at.
Returns the server's Unix time in seconds.
Creates joints between the specified Parts and any touching parts depending on the parts' surfaces and the specified joint creation mode.
Returns true if the game has the PGS Physics solver enabled.
Breaks all joints between the specified BaseParts and other BaseParts.
Positions and zooms the Workspace.CurrentCamera to show the extent of BaseParts currently in the Workspace.
Methods
Returns true if any of the given BasePart are touching any other parts.
Casts a block shape in a given direction and returns a RaycastResult if the shape hits a BasePart or Terrain cell.
Returns an array of parts whose bounding boxes overlap a given box.
Returns an array of parts whose bounding boxes overlap a given sphere.
Returns an array of parts whose occupied space is shared with the given part.
- IKMoveTo(part : BasePart,target : CFrame,translateStiffness : number,rotateStiffness : number,collisionsMode : Enum.IKCollisionsMode):()
Moves the specified part to the specified location via inverse kinematics rather than moving it there directly, to ensure any joints, constraints, or collisions that part is participating in remain physically satisfied.
Casts a ray using an origin, direction, and optional RaycastParams, then returns a RaycastResult if an eligible object or terrain intersects the ray.
- Spherecast(position : Vector3,radius : number,direction : Vector3,params : RaycastParams):RaycastResult?
Casts a spherical shape in a given direction and returns a RaycastResult if the shape hits a BasePart or Terrain cell.
Advances the simulation for parts in the world forward based on a specified time increment and an optional set of BaseParts.
Methods
Sets this model to be persistent for the specified player. ModelStreamingMode must be set to PersistentPerPlayer for behavior to be changed as a result of addition.
Returns a description of a volume that contains all parts of a Model.
Returns the size of the smallest bounding box that contains all of the BaseParts in the Model, aligned with the Model.PrimaryPart if it is set.
Returns all the Player objects that this model object is persistent for. Behavior varies based on whether this method is called from a Script or a LocalScript.
Returns the canonical scale of the model, which defaults to 1 for newly created models and will change as it is scaled via Model/ScaleTo.
Moves the PrimaryPart to the given position. If a primary part has not been specified, the root part of the model will be used.
Makes this model no longer persistent for the specified player. ModelStreamingMode must be set to PersistentPerPlayer for behavior to be changed as a result of removal.
Sets the scale factor of the model, adjusting the sizing and location of all descendant Instances such that they have that scale factor relative to their initial sizes and locations when scale factor was 1.
Shifts a Model by the given Vector3 offset, preserving the model's orientation. If another BasePart or Terrain already exists at the new position then the Model will overlap said object.
Methods
Gets the pivot of a PVInstance.
Transforms the PVInstance along with all of its descendant PVInstances such that the pivot is now located at the specified CFrame.
Events
Fires when persistent models have been sent to the specified player.
Properties
AirDensity
AllowThirdPartySales
AuthorityMode
AvatarUnificationMode
ClientAnimatorThrottling
CurrentCamera
DistributedGameTime
FallHeightEnabled
FallenPartsDestroyHeight
FluidForces
GlobalWind
Gravity
Code Samples
local MOON_GRAVITY_RATIO = 1.62 / 9.81
local DEFAULT_GRAVITY = 196.2
local MOON_GRAVITY = DEFAULT_GRAVITY * MOON_GRAVITY_RATIO
-- Create a touch pad
local pad = Instance.new("Part")
pad.Size = Vector3.new(5, 1, 5)
pad.Position = Vector3.new(0, 0.5, 0)
pad.Anchored = true
pad.BrickColor = BrickColor.new("Bright green")
pad.Parent = workspace
-- Listen for pad touch
local enabled = false
local debounce = false
local function onPadTouched(_hit)
if not debounce then
debounce = true
enabled = not enabled
workspace.Gravity = enabled and MOON_GRAVITY or DEFAULT_GRAVITY
pad.BrickColor = enabled and BrickColor.new("Bright red") or BrickColor.new("Bright green")
task.wait(1)
debounce = false
end
end
pad.Touched:Connect(onPadTouched)IKControlConstraintSupport
InsertPoint
LuauTypeCheckMode
MeshPartHeadsAndAccessories
ModelStreamingBehavior
MoverConstraintRootBehavior
PathfindingUseImprovedSearch
PhysicsImprovedSleep
PhysicsSteppingMethod
PlayerCharacterDestroyBehavior
PrimalPhysicsSolver
RejectCharacterDeletions
RenderingCacheOptimizations
ReplicateInstanceDestroySetting
Retargeting
SandboxedInstanceMode
SignalBehavior
StreamOutBehavior
StreamingEnabled
StreamingIntegrityMode
StreamingMinRadius
StreamingTargetRadius
Terrain
TouchEventsUseCollisionGroups
TouchesUseCollisionGroups
UseImprovedModelLod
UseNewLuauTypeSolver
Methods
GetRealPhysicsFPS
Returns
Code Samples
local Players = game:GetService("Players")
local player = Players.LocalPlayer
while task.wait(1) do
if workspace:GetRealPhysicsFPS() > 65 then
player:Kick()
end
end