콘텐츠로 이동

Tween - 트윈효과

트위닝

Quad에는 트윈을 도와주는 모듈이 내장되어 있습니다. 이 트윈 모듈은 단순한 Instance들을 넘어서 table 형식도 트윈을 수행할 수 있습니다. 이는 나중에 커스텀 오브젝트를 트윈할 때 유용합니다.
Quad 에서는 실제로 직접적으로 Tween 을 사용할 일은 적으며 추후 설명되는 register:Tween()로 사용하는것이 권장됩니다.

트윈은 일반적으로 다음과 같이 수행합니다. 

1
2
3
4
5
6
7
8
9
Tween.RunTween(myFrame,{
    -- 트윈 옵션
    Easing = Tween.Easing.Expo;
    Direction = Tween.Directions.Out;
    Time = 1;
    ...
},{
    -- 프로퍼티 목록
})
클릭시 움직이는 버튼을 구현합니다.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
local ScreenGUI = script.Parent
local Quad = require(path.to.module).Init()
local Class = Quad.Class
local Mount = Quad.Mount
local Tween = Quad.Tween

local Frame = Class "Frame"
local TextButton = Class "TextButton"
local on = false

Frame "mainFrame" {
    Size = UDim2.fromOffset(300,300);
    BackgroundColor3 = Color3.fromRGB(255,255,255);
    TextButton "Child" {
        Text = "Click Me!";
        BackgroundColor3 = Color3.fromRGB(255,100,255);
        Position = UDim2.fromOffset(80,100);
        Size = UDim2.fromOffset(20,20);
        [Event "MouseButton1Click"] = function(self,x,y)
            on = not on
            Tween.RunTween(self,{
                -- 트윈 옵션입니다. 아래에서 설명됩니다
                Easing = Tween.Easing.Expo;
                Direction = Tween.Directions.Out;
                Time = 1;
            },{
                -- 트윈할 목표 프로퍼티입니다
                Position = on
                    and UDim2.fromOffset(200,100)
                    or UDim2.fromOffset(80,100);
            })
        end;
    };
}

Mount(ScreenGUI, Store.GetObejct("mainFrame"))

트윈 옵션

트윈에는 트윈 옵션이 들어가며, 여기에는 트윈의 방향, 가감속, 시간 등을 설정해줄 수 있습니다.
넣을 수 있는 트윈 옵션은 다음과 같습니다.

Option Time:number?

트윈의 총 길이를 정합니다. 아무 값도 지정하지 않으면 1이 사용됩니다.

Option Easing:string|(index:number)->number?

트윈의 가감속 정도를 결정합니다. 문자열 그대로 사용하거나, Tween.Easings.Linear와 같이 열거형 방식으로 사용할 수 있습니다.
혹은 필요에 따라 함수를 지정할 수도 있습니다. 함수를 Easing 으로 사용하는 경우 첫번째 인자로 1차 진행도 (Linear, 0 에서 1 사이의 값) 값이 주어지며, 계산 결과로 실제 적용될 위치를 반환해야합니다. 반환값은 음수이거나 1 보다 클 수 있습니다.
아무 값도 지정하지 않으면 Exp2가 사용됩니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
type Easing =
    "Linear" // 아무런 가감속이 없는 1차형
    |"Quint" // 5 제곱
    |"Quart" // 네제곱
    |"Cubic" // 세제곱
    |"Quad" // 제곱
    |"Sin" // 사인 파형
    |"Circle" // 사분원
    |"Expo" // 지수형
    |"Elastic" // 탄성
    |"Bounce" // 튀어오름
    |"Back" // 뒤로 가감속
    |"Exp2" // 덜 가파른 지수 i=exp(x)/max, x=-4 to 2
    |"Exp4" // 더 가파른 지수 i=exp(x)/max, x=-4 ~ 4
    |EasingFunction?;
함수에 관한 자세한 설명과 미리보기는 여기에서 확인하세요

Option Direction:string?

트윈이 진행되는 방향입니다. 문자열 그대로 사용하거나, Tween.Directions.Out과 같이 열거형 방식으로 사용할 수 있습니다.
아무 값도 지정하지 않으면 Out이 사용됩니다. 

1
2
3
4
5
6
7
type Direction =
    // 초반에 가속이 이루워지며, 후반에 느려집니다.
    "Out"
    // 초반에는 느리며, 점점 가속이 늘어납니다.
    |"In"
    //중간에서 가장 빠른 속도를 가지며, 후반 초반 모두 감속이 이루워집니다.
    |"InOut"
방향에 관한 자세한 설명과 미리보기는 여기에서 확인하세요

Option CallBack:{[number|"*"|string]:(Item:any, Alpha:number, AbsolutePercent:number)->()}?

선택적인 필드이며, 트윈이 실행중인 도중에 함수를 실행시킬 수 있습니다. 트윈의 진행 정도에 따라서 한번 함수가 실행되거나 트윈 진행중 계속해서 실행되도록 만들 수 있습니다.
인덱스가 숫자인 경우 해당 지점을 넘을 때 함수가 실행되도록 만들 수 있으며, "*" 를 인덱스로 사용하면 모든 부분에서 함수가 실행됩니다.
함수에는 편의상 트윈을 하고있는 오브젝트, 위치값, 시간만을 고려한 1차 위치값이 제공됩니다.

Option OnStepped:(Item:any, Alpha:number, AbsolutePercent:number)->()?

CallBack 에 "*" 를 넣은것과 동일한 효과를 가지는 별칭입니다

Option Ended:(Item:any, Alpha:number, AbsolutePercent:number)->()?

CallBack 에 1을 넣은것과 동일한 효과를 가지는 별칭입니다

Option Getter:(Item:any, Property:string)->any?

선택적인 필드이며, 트윈이 값을 얻으려 할 때 사용할 함수입니다.
함수에 트윈하고 있는 오브젝트, 프로퍼티 이름이 제공됩니다.

Warning

register:Tween() 와 호환되지 않습니다.

Option Getter:(Item:any, Property:string, Value:Lerpable)->any?

선택적인 필드이며, 트윈이 값을 설정하려 할 때 사용할 함수입니다. 함수에 트윈하고 있는 오브젝트, 프로퍼티 이름, 설정할 값이 제공됩니다.

Warning

register:Tween() 와 호환되지 않습니다.

트윈 함수

Quad 의 트윈에는 트윈을 멈추거나 트윈중인지 확인하는 등의 작업을 할 수 있는 여러 함수들이 제공됩니다.
Tween 안의 모든 함수와 값들은 다음과 같습니다.

Tween.RunTween(Item:any, Option:tweenOptions, Properties:{[string]:Lerpable}, Ended?, OnStepped?, Setter?, Getter?)->TweenHandler

트윈을 실행합니다. 트윈 옵션에 대한 정보는 TweenOptions 문서에서 찾을 수 있습니다. Ended, OnStepped, Setter, Getter 값이 설정되면 Option 안의 값보다 우선적으로 사용됩니다. 기능은 TweenOptions의 내용과 같습니다. 나중에 트윈을 중단시킬 수 있도록 TweenHandler 가 제공됩니다. 다른 트윈이 변경중인 속성이 다시 트윈하도록 호출되면, 이전 트윈에서 해당 속성은 트윈이 중단되며 새로운 트윈으로 덮어쓰기 됩니다. 

1
2
3
4
5
Tween.RunTween(myFrame,{
    Time = 1;
},{
    Position = UDim2.new(1,0,1,0);
})

Tween.RunTweens(Items:{[number]:any}, Option:tweenOptions, Properties:{[string]:Lerpable}, Ended?, OnStepped?, Setter?, Getter?)

Tween.RunTween 와 같으나 여러 오브젝트를 한꺼번에 트윈합니다. 아무것도 반환하지 않습니다

1
2
3
4
5
Tween.RunTween({myFrame1, myFrame2, myFrame3},{
    Time = 1;
},{
    Position = UDim2.new(1,0,1,0);
})

Tween.StopTween(ItemOrHandler:TweenHandler|any)

트윈을 멈춥니다. TweenHandler 또는 오브젝트를 넣어 멈출 수 있습니다. 오브젝트를 넣으면 그 오브젝트에 실행중인 모든 트윈을 멈춥니다.

1
2
3
4
5
6
7
local Handler = Tween.RunTween(myFrame,{
    Time = 1;
},{
    Position = UDim2.new(1,0,1,0);
})

Tween.StopTween(Handler)

1
2
3
4
5
6
7
local Handler = Tween.RunTween(myFrame,{
    Time = 1;
},{
    Position = UDim2.new(1,0,1,0);
})

Tween.StopTween(myFrame)

Tween.StopPropertyTween(Item:any, PropertyName:string)

오브젝트에 특정 프로퍼티의 트윈을 중단시킵니다. TweenHandler 는 사용할 수 없습니다.

Tween.StopPropertyTween(ItemOrHandler:IsTweening|any)->boolean

해당 오브젝트 또는 TweenHandler 로 트윈이 진행중인지 여부를 판단합니다.

Tween.IsPropertyTweening(Item:any, PropertyName:string)

해당 오브젝트의 프로퍼티가 트윈중이지 여부를 판단합니다. TweenHandler 는 사용할 수 없습니다.

Tween.Easings: { [string]: EasingFunction }

이징 함수들이 담겨있습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
type Easing =
    "Linear" // 아무런 가감속이 없는 1차형
    |"Quint" // 5 제곱
    |"Quart" // 네제곱
    |"Cubic" // 세제곱
    |"Quad" // 제곱
    |"Sin" // 사인 파형
    |"Circle" // 사분원
    |"Expo" // 지수형
    |"Elastic" // 탄성
    |"Bounce" // 튀어오름
    |"Back" // 뒤로 가감속
    |"Exp2" // 덜 가파른 지수 i=exp(x)/max, x=-4 to 2
    |"Exp4" // 더 가파른 지수 i=exp(x)/max, x=-4 ~ 4
    |EasingFunction?;
그래프와 미리보기는 Easings 에서 확인할 수 있습니다

Tween.Easings: { [string]: EasingFunction }

이징 함수들이 담겨있습니다.

1
2
3
4
5
6
7
type Direction =
    // 초반에 가속이 이루워지며, 후반에 느려집니다.
    "Out"
    // 초반에는 느리며, 점점 가속이 늘어납니다.
    |"In"
    //중간에서 가장 빠른 속도를 가지며, 후반 초반 모두 감속이 이루워집니다.
    |"InOut"
자세한 정보는 Easings 에서 확인할 수 있습니다