콘텐츠로 이동

# 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` 또는 오브젝트를 넣어 멈출 수 있습니다. 오브젝트를 넣으면 그 오브젝트에 실행중인 모든 트윈을 멈춥니다.

> 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 에서 확인할 수 있습니다

맨위로