#World, tweens and effects

This page covers how scripts look at the world (raycasts, nearby objects), change how it looks (lighting, tweens) and add sound.

#Raycasting

workspace:Raycast(origin, direction, [raycastParams]) casts a ray from origin along direction. The length of direction is the range. It returns a RaycastResult, or nil if nothing was hit.

local params = RaycastParams.new()
params.FilterDescendantsInstances = {workspace.Baseplate}
params.FilterType = Enum.RaycastFilterType.Exclude        -- or Include

local result = workspace:Raycast(Vector3.new(0, 10, 0), Vector3.new(0, -50, 0), params)
if result then
    print(result.Instance:FullName(), result.Position, result.Normal, result.Distance, result.Material)
end

#RaycastResult

#RaycastParams

#The classic API

Kept for compatibility. Ray.new(origin, direction) with workspace:FindPartOnRay, :FindPartOnRayWithIgnoreList and :FindPartOnRayWithWhitelist return hitPart, hitPosition, hitNormal, hitMaterial.

#Finding nearby objects

workspace:GetPartBoundsInRadius(position, radius) returns every object within radius studs of position. It compares positions only (not sizes) and includes non-physical objects.

#Lighting

game.Lighting, or the global Lighting.

Lighting changes made by a server script show up for every player.

task.every(0.03, function()
    Lighting.ClockTime = (Lighting.ClockTime + 0.1) % 24
end)

#Tweens

A tween smoothly animates properties from their current values to new ones.

#The short way

inst:TweenTo(goals, seconds, [style], [direction]) creates a tween, plays it and returns it. The defaults are 1 second, "Quad" and "Out".

platform:TweenTo({ Position = platform.Position + Vector3.new(0, 20, 0) }, 3, "Quad", "InOut")

#The Roblox way

Use this form for repeats and reversing.

local info = TweenInfo.new(3, Enum.EasingStyle.Quad, Enum.EasingDirection.InOut, -1, true)
local tween = TweenService:Create(platform, info, { Position = platform.Position + Vector3.new(0, 20, 0) })
tween.Completed:On(function(state) print(state) end)   -- "Completed" or "Cancelled"
tween:Play()
tween:Await()                                                -- yields until it completes or is cancelled

#TweenInfo.new(time, easingStyle, easingDirection, repeatCount, reverses, delayTime)

#What can be tweened

#The tween object

A tween nobody holds a reference to is freed once it has finished. One that is still playing is kept alive.

#Sound

There are two ways to play audio.

#Sound.play: fire and forget

Sound.play(name, [volume], [options]) starts a sound and returns a handle. Names are either built in ("swoosh", "footstep", "jump") or uploads ("sound/<id>"; upload audio on the hub).

options is a table: { Loop = true, Speed = 1, Position = Vector3.new(0, 5, 0), Range = 60 }. With Position the sound is positional.

local handle = Sound.play("sound/42", 0.8, { Loop = true, Position = door.Position, Range = 50 })
task.wait(10)
Sound.stop(handle)

#Sound objects

Create a Sound instance for music or anything you want to change while it plays. Set SoundId, then Playing = true:

local music = Instance.Create("Sound", { Name = "Music", SoundId = "sound/1", Loop = true, Volume = 0.5, Parent = workspace })
music.Playing = true      -- play
music.Volume = 0.2        -- changes take effect while it plays
music.Playing = false     -- stop

A Sound inside a part is positional. A Sound in the Workspace plays everywhere. See Instances and parts for every property.