튜토리얼 · 스크립팅 기초

로블록스 TweenService: 파트를 움직이고, 돌리고, 사라지게 하기

트윈은 속성을 현재 값에서 목표 값까지 정해진 시간 동안 부드럽게 바꿉니다. 발판이 미끄러지고, 보석이 돌고, 벽이 서서히 사라집니다. 중간 단계는 TweenService가 알아서 계산하므로, 매 프레임 파트를 옮기는 반복문을 직접 쓸 필요가 없습니다. 이 가이드에서는 모든 트윈에 꼭 필요한 세 줄, TweenInfo의 각 설정이 하는 일, 파트 이동과 회전과 사라지기, 반복, 트윈이 끝날 때까지 기다리기, 그리고 모델(Model) 전체를 트윈하는 요령을 다룹니다.

업데이트: 2026년 11월 20일읽는 데 4분작성:

요약

game:GetService("TweenService")로 서비스를 가져오고, TweenInfo.new(time, easingStyle, easingDirection)로 움직임을 정한 다음, TweenService:Create(part, info, { Position = goal })를 호출하고 받은 트윈에 :Play()를 실행하세요. number, Vector3, CFrame, Color3, UDim2 같은 타입의 속성은 모두 트윈할 수 있습니다. 끝날 때까지 기다리려면 tween.Completed:Wait()를 쓰고, 끝없이 왔다 갔다 하게 하려면 TweenInfo에 반복 횟수 -1을 넣고 reverses를 켜세요.

  • 모든 플레이어가 봐야 하는 파트는 서버에서 트윈하고, 그 플레이어에게만 필요한 효과는 클라이언트에서 트윈하세요.
  • 트윈하는 파트는 고정(Anchored)하세요. 그렇지 않으면 물리가 트윈을 방해합니다.
  • Model에는 트윈할 Position이나 CFrame이 없습니다. NumberValue를 트윈하고 PivotTo로 모델을 옮기세요.
이 페이지의 내용
  1. 작동 방식
  2. 1. TweenInfo
  3. 2. 회전과 사라지기
  4. 3. 반복
  5. 4. 모델
  6. 서버 또는 클라이언트
  7. Common errors
  8. RoCode로
  9. 자주 묻는 질문
  10. 출처와 더 읽을거리

모든 트윈에 필요한 세 줄

Workspace에 Part를 넣고 Anchored를 체크한 다음, 마우스를 올리고 +를 눌러 Script를 넣으세요. 이 스크립트는 파트를 2초 동안 10스터드 들어 올립니다.

Script 위치: Workspace의 파트 이름: Rise
-- Part 안의 Script.
local TweenService = game:GetService("TweenService")

local part = script.Parent :: BasePart

local info = TweenInfo.new(2) -- 2초, 기본 easing
local goal = { Position = part.Position + Vector3.new(0, 10, 0) }

local tween = TweenService:Create(part, info, goal)
tween:Play()

목표는 속성 이름과 그 속성이 끝나야 할 값으로 이루어진 테이블입니다. 여러 속성을 한꺼번에 트윈할 수도 있습니다: { Position = ..., Transparency = 1, Color = Color3.fromRGB(255, 0, 0) }. 트윈은 Play를 호출하는 순간의 값에서 시작하므로, 항상 끝 값만 정하면 됩니다.

트윈할 수 있는 것과 없는 것
타입부드럽게 트윈되나요?예시
number예Transparency, Reflectance, NumberValue의 Value
Vector3, CFrame예Position, Size, CFrame, Orientation
Color3예Color
UDim2, Vector2예GUI의 Size와 Position
boolean, EnumItem마지막에 전환됨CanCollide, Material
string, Instance아니요cannot be tweened due to type mismatch 오류가 납니다

1단계: TweenInfo의 모든 설정

TweenInfo.new는 최대 여섯 개의 값을 이 순서대로 받습니다. 뒤쪽 값은 생략할 수 있습니다.

TweenInfo.new(time, style, direction, repeatCount, reverses, delayTime)
값기본값하는 일
time1한 번 재생하는 데 걸리는 초.
easingStyleQuad움직임의 모양: Linear(일정한 속도), Sine, Quad, Cubic, Back(지나쳤다 돌아옴), Bounce, Elastic, Exponential.
easingDirectionOutOut은 빠르게 시작해서 느려지고, In은 느리게 시작하며, InOut은 둘 다 합니다.
repeatCount0첫 재생 후 몇 번 더 반복할지. -1은 끝없이 반복합니다.
reversesfalse재생할 때마다 처음으로 되돌아올지.
delayTime0시작하기 전에 기다릴 초.
Script 위치: Workspace의 파트 이름: Platform
-- 이름이 Platform인 Part 안의 Script.
-- 12스터드를 끝없이 왔다 갔다 하며, 양 끝에서 부드럽게 움직임.
local TweenService = game:GetService("TweenService")

local platform = script.Parent :: BasePart

local info = TweenInfo.new(
	3, -- 한 방향에 걸리는 초
	Enum.EasingStyle.Sine,
	Enum.EasingDirection.InOut,
	-1, -- 끝없이 반복
	true -- 매번 되돌아옴
)

TweenService:Create(platform, info, { Position = platform.Position + Vector3.new(12, 0, 0) }):Play()

발판이 위에 선 플레이어를 태우고 가야 한다면 주의하세요. 트윈하는 고정 파트는 플레이어 아래에서 움직이지만 플레이어를 함께 데려가지는 않습니다. 이 경우는 움직이는 발판 가이드에서 다룹니다.

2단계: 회전, 크기, 사라지기

파트를 돌리려면 CFrame을 현재 CFrame에 회전을 곱한 값으로 트윈하세요. Orientation을 트윈해도 되지만, CFrame을 쓰면 파트가 제자리에서 돕니다. 여기서는 스크립트가 시작되면 벽이 돌고, 그다음 사라지면서 작아지고, 트윈이 끝나면 삭제됩니다.

Script 위치: Workspace의 파트 이름: FadingWall
-- 이름이 FadingWall인 Part 안의 Script.
local TweenService = game:GetService("TweenService")

local wall = script.Parent :: BasePart

-- 자기 세로축을 기준으로 1초 동안 4분의 1바퀴 회전
local turn = TweenService:Create(wall, TweenInfo.new(1), {
	CFrame = wall.CFrame * CFrame.Angles(0, math.rad(90), 0),
})
turn:Play()
turn.Completed:Wait() -- 회전이 끝나야 다음으로 진행

-- 그다음 동시에 사라지면서 작아짐
local fade = TweenService:Create(wall, TweenInfo.new(0.8, Enum.EasingStyle.Quad, Enum.EasingDirection.In), {
	Transparency = 1,
	Size = wall.Size * 0.2,
})
fade:Play()
fade.Completed:Wait()
wall:Destroy()

Completed는 PlaybackState와 함께 발생합니다. 트윈이 목표에 도달했으면 Completed, tween:Cancel()로 멈췄으면 Cancelled입니다. 끝없이 반복하는 트윈의 Completed는 기다리지 마세요. 절대 끝나지 않습니다.

3단계: 떠다니며 회전하는 아이템

서로 다른 속성에 건 반복 트윈 두 개는 동시에 진행됩니다. CFrame으로 360도 한 바퀴를 트윈하면 시작과 끝이 같은 회전이라 아무 일도 일어나지 않으므로, 회전은 NumberValue를 0에서 360까지 트윈하고 그 값에 맞춰 CFrame을 설정합니다. 이 Script를 고정된 파트에 넣으세요.

Script 위치: Workspace의 파트 이름: FloatingGem
-- 이름이 Gem인 Part 안의 Script. 끝없이 위아래로 떠다니며 회전함.
local TweenService = game:GetService("TweenService")

local FLOAT_HEIGHT = 1.5 -- 처음 놓은 위치보다 높은 스터드
local FLOAT_SECONDS = 1.2 -- 한 방향에 걸리는 초
local SPIN_SECONDS = 3 -- 한 바퀴 전체

local gem = script.Parent :: BasePart
gem.Anchored = true
local baseCFrame = gem.CFrame

local height = Instance.new("NumberValue")
local angle = Instance.new("NumberValue")

local function apply()
	gem.CFrame = baseCFrame * CFrame.new(0, height.Value, 0) * CFrame.Angles(0, math.rad(angle.Value), 0)
end
height.Changed:Connect(apply)
angle.Changed:Connect(apply)

TweenService:Create(height, TweenInfo.new(FLOAT_SECONDS, Enum.EasingStyle.Sine, Enum.EasingDirection.InOut, -1, true), {
	Value = FLOAT_HEIGHT,
}):Play()

TweenService:Create(angle, TweenInfo.new(SPIN_SECONDS, Enum.EasingStyle.Linear, Enum.EasingDirection.In, -1), {
	Value = 360,
}):Play()

회전은 Linear easing을 쓰므로 일정한 속도로 돌고, 매 반복은 다시 0에서 시작하는데 0은 360과 같은 각도라서 끊김이 없습니다. 코인 수집 가이드에서 이런 아이템을 게임에 넣습니다.

4단계: 모델 전체 트윈하기

Model에는 Position이나 CFrame 속성이 없으므로 TweenService:Create(model, ...)로는 움직일 것이 없습니다. 대신 NumberValue를 0에서 1까지 트윈하고, 안에 있는 모든 파트를 함께 옮기는 PivotTo로 모델을 움직이세요.

Script 위치: Workspace의 모델 이름: Elevator
-- 이름이 Elevator인 Model 안의 Script.
-- 모델 전체를 20스터드 위로 올렸다가 되돌림, 모든 파트가 함께 움직임.
local TweenService = game:GetService("TweenService")

local elevator = script.Parent :: Model
local startPivot = elevator:GetPivot()
local endPivot = startPivot * CFrame.new(0, 20, 0)

local progress = Instance.new("NumberValue")
progress.Changed:Connect(function(alpha: number)
	elevator:PivotTo(startPivot:Lerp(endPivot, alpha))
end)

local info = TweenInfo.new(4, Enum.EasingStyle.Quad, Enum.EasingDirection.InOut, -1, true, 2)
TweenService:Create(progress, info, { Value = 1 }):Play()

모델의 파트를 모두 고정하세요. TweenInfo 끝의 2는 매번 재생하기 전의 대기 시간이라서 엘리베이터가 위와 아래에서 잠시 멈춥니다. 문 가이드에서도 같은 방법으로 파트 여러 개로 된 문을 엽니다.

서버일까, 클라이언트일까?

서버 Script에서 실행한 트윈은 서버에서 파트를 바꾸고, 새 값이 모든 플레이어에게 복제되므로 모두가 봅니다. LocalScript의 트윈은 그 플레이어의 화면에서만 파트를 바꿉니다.

트윈을 어디에서 실행할까
실행 위치언제예시
서버 Script변경이 게임에 중요하거나 모두에게 필요할 때.문, 움직이는 장애물, 나타나는 다리
LocalScript그 플레이어만 봐야 하거나 순수한 시각 효과일 때.주운 플레이어에게만 사라지는 아이템, UI

복제는 1초에 여러 번 업데이트를 보내므로 대부분의 플레이어에게 서버 트윈은 부드럽게 보이지만, 아주 빠르거나 아주 많은 서버 트윈은 느린 연결에서 덜 부드러워 보일 수 있습니다. 장식용 움직임이 많을 때(회전하는 코인 수백 개)는 각 클라이언트의 LocalScript에서 트윈을 실행하세요.

자주 발생하는 오류와 해결 방법

Play를 누르기 전에 Output 창을 여세요(Window 메뉴, 그다음 Output).

파트가 전혀 움직이지 않습니다

트윈에 :Play()를 호출했는지, 목표의 속성 이름을 정확히 썼는지(position이 아니라 Position), 스크립트가 실행되는 곳(Workspace의 파트 안이나 ServerScriptService)에 있는 Script인지 확인하세요.

트윈하는 동안 파트가 떨어지거나 흔들립니다

파트가 고정되어 있지 않아서 중력과 충돌이 트윈을 방해합니다. Anchored를 체크하세요.

TweenService:Create property cannot be tweened due to type mismatch

목표 값의 타입이 맞지 않습니다. 예를 들어 Vector3 속성에 숫자를 넣은 경우입니다. 오류 페이지(영어)를 보세요.

Unable to cast to Dictionary 또는 Unable to cast value to Object

인수의 순서나 타입이 틀렸습니다. 순서는 항상 Create(instance, tweenInfo, goalTable)입니다. Unable to cast value to Object(영어)를 보세요.

RoCode로 만들기

트윈을 직접 쓰고 싶지 않다면 RoCode가 지금 열려 있는 플레이스에 만들어 줄 수 있습니다. RoCode는 Roblox가 만든 것이 아닌 독립적인 Roblox Studio용 AI 에이전트입니다. 웹 채팅에서 변경 사항을 설명하면 Studio 플러그인이 Explorer에 스크립트를 만들어 주므로 코드를 붙여 넣을 필요가 없습니다.

입력하는 내용

라운드가 시작되면 Workspace의 다리 모델이 NumberValue 트윈과 PivotTo로 옆으로 15스터드 밀려나게 하고, 동시에 빨간 장벽 파트들을 1초 동안 사라지게 해 줘.

RoCode가 하는 일
  • 무언가를 쓰기 전에 Search Game으로 필요한 파트와 모델을 찾을 수 있습니다
  • Create Script로 Script를 작성하고, Check Script로 컴파일을 확인하도록 지시받습니다
  • 변경 묶음마다 앞뒤로 실행 취소 지점을 두므로 Ctrl+Z로 한 묶음씩 되돌릴 수 있습니다

플러그인 3.9 이상에서는 RoCode가 짧은 플레이테스트를 실행하고 오류를 읽을 수 있지만, 움직임은 직접 눈으로 보는 것이 가장 쉬우니 Play를 눌러 확인하세요. RoCode가 Studio에 연결되는 방식.

자주 묻는 질문

Roblox에서 TweenService는 어떻게 쓰나요?

서비스를 가져오고, TweenInfo를 만들고, TweenService:Create(object, info, { Property = goal })를 호출한 뒤 결과에 :Play()를 실행하세요. 첫 번째 섹션에 세 줄짜리 예시가 있습니다.

트윈을 영원히 반복하려면 어떻게 하나요?

TweenInfo.new의 네 번째 값(repeatCount)에 -1을 넣고, 왔다 갔다 해야 한다면 다섯 번째 값에 true를 넣으세요.

트윈이 끝날 때까지 어떻게 기다리나요?

tween:Play() 다음에 tween.Completed:Wait()를 호출하거나, tween.Completed에 함수를 연결하세요.

Model을 트윈할 수 있나요?

직접은 안 됩니다. 4단계처럼 NumberValue를 0에서 1까지 트윈하고, 값이 바뀔 때마다 model:PivotTo(start:Lerp(goal, value))를 호출하세요.

트윈은 어떻게 멈추나요?

tween:Cancel()을 호출하면 멈추고 파트는 그 자리에 남습니다. tween:Pause()를 호출하면 나중에 Play()로 이어서 재생할 수 있습니다.

출처와 더 읽을거리

코드 검증 방법: 이 페이지의 모든 스크립트는 Roblox API 정의를 적용한 Luau의 엄격한 타입 검사기(luau-lsp, 2026년 11월 20일)를 통과합니다. 타입 검사는 잘못 쓴 API 이름과 잘못된 타입을 찾아내지만 게임 로직의 오류는 찾지 못하므로, 게시하기 전에 Studio에서 직접 테스트하세요.

내 게임에서 RoCode를 사용해 보세요.

매일 무료 크레딧, 카드 등록 없이 시작합니다. 플러그인을 설치하고, 원하는 기능을 설명한 뒤, Studio에 만들어진 결과를 확인하세요.