트랜스폼

트랜스폼은 디스플레이어블을 다른 디스플레이어블로 바꾸는 데 사용합니다. 트랜스폼에는 여러 종류가 있으며 만드는 방법도 다양합니다. 내장 트랜스폼은 화면에서 이미지의 배치 위치를 제어하고, 사용자 정의 트랜스폼은 이동, 확대·축소, 회전부터 복잡한 색상 효과까지 더 다양한 효과를 만들 수 있습니다.

빠르게 시작하기

show 문이나 scene 문의 at 절에 트랜스폼을 전달하면 이미지에 적용할 수 있습니다. 다음 예제는 eileen happy 이미지에 right 트랜스폼을 적용합니다.

show eileen happy at right

여러 트랜스폼을 쉼표로 구분하여 적용할 수 있습니다. 트랜스폼은 왼쪽에서 오른쪽 순서로 적용됩니다.

show eileen happy at halfsize, right

간단한 ATL 트랜스폼:

transform slide_right:
    xalign 0.0
    linear 1.0 xalign 1.0

label start:
    show eileen happy at slide_right
    pause

Python으로 트랜스폼 표시:

label start:
    $ renpy.show("eileen happy", at_list=right)
    pause

At()을 사용하는 간단한 Python 트랜스폼:

init python:
    def show_eileen_rotated():
        rotated = Transform(rotate=45)
        show_stmt = At("eileen happy", rotated)
        renpy.show("eileen", what=show_stmt)

label start:
    $ show_eileen_rotated()
    pause

내장 트랜스폼

Ren'Py는 기본적으로 여러 트랜스폼을 제공합니다. 이 트랜스폼들은 화면에서 대상을 배치하는 데 사용합니다. 다음 그림은 각 내장 트랜스폼이 이미지를 배치하는 위치를 보여 줍니다.

              +-----------------------------------------------------------+
              | topleft, reset               top                 topright |
              |                                                           |
              |                                                           |
              |                                                           |
              |                                                           |
              |                          truecenter                       |
              |                                                           |
              |                                                           |
              |                                                           |
              |                                                           |
offscreenleft | left                   center, default              right | offscreenright
              +-----------------------------------------------------------+

offscreenleft와 offscreenright 트랜스폼은 이미지를 화면 가장자리 밖에 배치합니다. 대상을 화면 밖으로 이동할 때 사용할 수 있습니다. 이동한 뒤에는 리소스를 소모하지 않도록 숨기는 것도 잊지 마세요.

제공되는 트랜스폼은 다음과 같습니다.

center: 가로로 가운데 정렬하고 화면 아래쪽에 맞춥니다.

default: 가로로 가운데 정렬하고 화면 아래쪽에 맞춥니다. config.default_transform으로 이를 재정의하면 show 문이나 scene 문으로 표시하는 이미지의 기본 배치를 바꿀 수 있습니다.

left: 화면의 왼쪽 아래 모서리에 맞춥니다.

offscreenleft: 화면 아래쪽에 맞추어 디스플레이어블을 화면 왼쪽 밖에 배치합니다.

offscreenright: 화면 아래쪽에 맞추어 디스플레이어블을 화면 오른쪽 밖에 배치합니다.

reset: 트랜스폼의 각 속성을 기본값으로 초기화하고 그 전에 설정한 속성을 모두 제거합니다.

right: 화면의 오른쪽 아래 모서리에 맞춥니다.

top: 가로로 가운데 정렬하고 화면 위쪽에 맞춥니다.

topleft: 화면의 왼쪽 위 모서리에 맞춥니다.

topright: 화면의 오른쪽 위 모서리에 맞춥니다.

truecenter: 가로와 세로로 모두 가운데 정렬합니다.

ATL - 애니메이션 및 변형 언어

Animation and Transformation Language(ATL)는 애니메이션 생성, 화면에서 디스플레이어블 이동, 위치 설정, 변형 적용 등을 수행하는 고수준 언어입니다. 이러한 동작은 시간의 흐름이나 이벤트에 따라 바뀔 수 있습니다.

아래의 transform 문으로 만드는 ATL 트랜스폼 객체는 디스플레이어블이며 그 용도로 사용할 수 있습니다. 단, 자식 디스플레이어블을 설정하지 않으면 투명합니다. 스크린의 add 요소, show expression 문, renpy.show() 함수에 전달할 수 있습니다.

Ren'Py 스크립트 문

ATL 코드를 포함할 수 있는 Ren'Py 스크립트 문은 세 가지입니다.

transform 문

transform 문은 게임의 디스플레이어블에 애니메이션을 적용하고 배치하는 데 사용할 새 트랜스폼을 만듭니다. 트랜스폼은 재사용할 수 있으며, show 문과 scene 문의 at 절로 게임 전반의 이미지 및 다른 디스플레이어블에 적용할 수 있습니다.

트랜스폼은 디스플레이어블로서 직접 표시할 수도 있습니다. 다만 전역 이미지 네임스페이스에 존재하는 다른 디스플레이어블과 달리(이미지 정의 참조), 트랜스폼은 적절한 이름 있는 스토어 또는 기본 스토어의 변수로 생성됩니다.

트랜스폼은 게임이 시작되는 초기화 시점에 생성됩니다.

구문

기본 형식:

transform <transform_name>:
    <atl_block>

매개변수가 있는 형식:

transform <transform_name>( <parameters> ):
    <atl_block>

사용법

이름

유형

설명

transform_name

단어

트랜스폼 이름입니다.

점을 구분자로 사용하는 유효한 Python 식별자여야 합니다.

(예: my_transform 또는 sprites.bounce)

parameters

--

(선택 사항) 트랜스폼의 매개변수입니다.

atl_block

블록

트랜스폼을 정의하는 ATL 코드 블록입니다.

매개변수를 추가하면 트랜스폼을 유연하게 재사용할 수 있습니다. 매개변수는 Python 함수의 매개변수와 비슷하게 동작합니다.

현재 지원하지 않는 항목:

위치 전용 매개변수(/ 사용)

필수 키워드 전용 매개변수(* 뒤에 기본값 없이 지정)

*args (가변 위치 매개변수)

**kwargs (가변 키워드 매개변수)

참고

트랜스폼에 기본값이 없는 매개변수가 있으면 트랜스폼으로 사용하기 전에 해당 매개변수 모두에 값을 제공해야 합니다.

관련 항목: ATL 커링과 일부 매개변수 전달

예제

transform left_to_right:
    xalign 0.
    linear 2 xalign 1.
    repeat

transform ariana.left:
    xalign .3

transform animated_ariana_disp(duration=1.0):
    "ariana"
    pause duration
    "ariana_reverse"
    pause duration
    repeat

label start:
    show eileen happy at left_to_right
    pause
    show animated_ariana_disp
    pause

ATL 블록이 있는 image 문

스크립트에 ATL 코드를 넣는 두 번째 방법은 image 문의 일부로 사용하는 것입니다. 한 줄 형식의 image 문과 마찬가지로 공백을 포함할 수 있는 이미지 이름을 지정한 트랜스폼에 연결합니다. 매개변수를 전달할 방법이 없으므로 트랜스폼이 애니메이션을 정의할 때만 유용합니다.

구문

image <image_name>:
    <atl_block>

사용법

이름

유형

설명

image_name

단어(하나 이상)

이미지 이름입니다.

atl_block

블록

트랜스폼을 정의하는 ATL 코드 블록입니다.

예제

image animated_ariana_img:
    "ariana"
    pause 1.
    "ariana_reverse"
    pause 1.
    repeat

ATL 블록이 있는 scene 문과 show 문

ATL을 사용하는 마지막 방법은 show 문이나 scene 문의 일부로 사용하는 것입니다. 표시하는 이미지를 즉석에서 생성한 ATL 트랜스폼으로 감싸 해당 이미지에 적용합니다.

구문

show <image_name>:
    <atl_block>

scene <image_name>:
    <atl_block>

사용법

이름

유형

설명

image_name

단어(하나 이상)

이미지 이름입니다.

atl_block

블록

트랜스폼을 정의하는 ATL 코드 블록입니다.

예제

show eileen happy:
    xalign 1.

scene bg washington:
    zoom 2.

ATL 구문과 문

ATL 문은 한 줄로 작성하거나 자신이 속한 ATL 블록 안에 별도의 블록을 만들 수 있습니다. 각 문에서 설명하는 일부 예외를 제외하면 ATL 블록의 문들은 위에서 아래 순서로 실행됩니다.

ATL 문에서 표현식을 평가해야 하는 경우, 해당 ATL 문을 실행할 때가 아니라 트랜스폼을 처음 실행할 때 평가합니다. 즉, show 문을 사용하거나 스크린의 일부로 트랜스폼을 표시할 때입니다.

ATL 문은 다음과 같습니다.

속성 설정 문

트랜스폼 속성의 값을 설정하는 문입니다.

구문

<property_name> <property_value>

사용법

이름

유형

설명

property_name

단어

트랜스폼 속성의 이름입니다(예: xalign, alpha 등).

property_value

속성에 따라 다름

속성의 값입니다.

하나 이상의 속성 이름을 나열하고 각 이름 뒤에 설정할 새 값을 작성합니다. 트랜스폼 속성 목록, 각 속성의 의미와 허용하는 값은 트랜스폼 속성 목록을 참조하세요.

예제

transform rightoid:
    xalign .9

transform ariana.left:
    xanchor .3 xpos 100

숫자 문

지정한 시간 동안 ATL 블록의 실행을 멈춥니다. "pause" 키워드는 생략할 수 있습니다.

구문

pause <duration>

사용법

이름

유형

설명

"pause"

키워드

(선택 사항) 일시 정지를 나타내는 키워드입니다.

duration

float, int (표현식)

멈출 시간으로, 초 단위입니다.

예제

transform pause_example(duration=0.5):
    xalign 0.0

    # Pause for 2.0 seconds.
    pause 2.0
    xalign 1.0

    # Pause for `duration` seconds.
    pause duration
    xalign 0.5

    # Pause for 3.0 seconds.
    3.0

    repeat

보간 문

보간 문은 트랜스폼에 부드러운 애니메이션을 적용하는 주요 방법입니다. 시간이 흐르면서 속성값이 시작값에서 지정한 값으로 바뀝니다.

워핑 함수로 시간에 따른 보간 진행 방식을 제어합니다.

구문

기본 형식:

<warper_name> <duration> <atl_property> [<atl_property> ...]

워퍼 함수를 사용하는 형식:

warp <warper_function> <duration> <atl_property> [<atl_property> ...]

블록 형식:

<warper_name> <duration>:
    <atl_property>
    <atl_property>
    ...

사용법

이름

유형

설명

warper_name

단어

내장 워퍼 이름입니다.

warper_function

str, function (표현식)

서명이 (t: float) -> float인 워핑 함수입니다.

duration

float, int (표현식)

보간 시간으로, 초 단위입니다.

atl_property

속성 설정 문

보간할 속성입니다.

보간은 지정한 시간 동안, 그리고 최소 한 프레임 동안 지속됩니다.

트랜스폼 속성을 지정할 때 각 속성에 주는 값은 보간 문이 끝났을 때 설정될 값입니다.

트랜스폼 표현식 문을 보간할 수도 있습니다. 이 경우 속성 설정 문 하나만 포함하는 ATL 트랜스폼이어야 합니다. 트랜스폼의 속성들은 해당 보간 문에 직접 작성한 것처럼 처리됩니다.

예제

기본 사용법:

show logo base:
    xalign 0.0 yalign 0.0

    # Take 2.0 seconds to move things to the bottom-left corner.
    linear 2.0 yalign 1.0

워퍼 함수 사용:

show logo base(warper_expr="easein"):
    xalign 0.0 yalign 0.0

    # Use the warper in the parameter to move to the right side of the screen.
    warp warper_expr 1.0 xalign 1.0

여러 속성 사용:

show logo base:
    xalign 0.0 yalign 0.0

    # Changes xalign and yalign at the same time.
    linear 2.0 xalign 0.5 yalign 0.5

    # The same thing, using a block.
    linear 2.0:
        xalign 0.5
        yalign 0.5

제작자가 정의한 워퍼:

init python:
    def my_warper(t):
        return t**4.4

    my_warpers = [my_warper]

transform custom_warper_example:
    xpos 0
    warp my_warper 3 xpos 100
    warp my_warpers[0] 5 xpos 520

속성 보간

스플라인 이동(곡선 경로) 사용:

<atl_property> knot <knot_value> [knot <knot_value> ...]
이름

유형

설명

knot_value

속성에 따라 다름 (표현식)

속성 제어점의 값입니다.

시작점은 보간을 시작할 때의 속성값이며, 끝점은 <atl_property>에 지정한 값입니다. 매듭점은 스플라인을 제어하는 데 사용합니다.

매듭점이 하나면 이차 베지어 곡선, 두 개면 삼차 베지어 곡선, 세 개 이상이면 Catmull-Rom을 사용합니다. 앞의 두 경우에는 매듭점이 단순한 제어점입니다. Catmull-Rom에서는 첫 번째와 마지막 매듭점이 제어점이며 표시되는 경로 밖에 놓이는 경우가 많습니다. 나머지 매듭점은 경로가 통과하는 점입니다.
transform spline_motion_single_property:
    # Start at the bottom right, zoomed out a bit.
    zoom 0.5 xalign 1.0 yalign 1.0

    # Move from to the bottom center, overshooting a bit. Quadratic Bezier curve.
    linear 2.0 xalign 0.5 knot 0.0

    # Move to the top, slowing down at the center. Cubic Bezier curve.
    linear 2.0 yalign 0.0 knot 0.2 knot 0.8

    # Move to the left, oscillating first. Catmull-Rom spline.
    linear 2.0 xalign 0.0 knot 1.0 knot 0.5 knot 0.0

transform spline_motion_multi_property:
    # Start at the bottom right, zoomed out a bit.
    zoom 0.5 align (1.0, 0.0)

    # Use a spline motion to move (x, y) simultaneously in a slight S shape.
    linear 2.0 align (0.5, 1.0) knot (0.0, .33) knot (1.0, .66)

원운동 사용:

<atl_property> clockwise
<atl_property> counterclockwise
<atl_property> circles <number_of_circles>
이름

유형

설명

number_of_circles

int (표현식)

원운동에서 완전히 회전할 횟수입니다.

시작 위치와 끝 위치(pos, align, angle, radius 등으로 설정)를 비교하고 극좌표의 중심(around)을 결정합니다. 그런 다음 Ren'Py는 지정한 회전 방향으로 시작 각도에서 끝 각도까지 이동하는 데 필요한 각도를 계산합니다. circles 절을 지정하면 Ren'Py가 해당 횟수만큼 완전히 회전하도록 합니다.
show logo base:
    xalign 1.0 yalign 0.0

    # Set the location to circle around.
    anchor (0.5, 0.5)

    # Use circular motion to bring us to spiral out to the top of
    # the screen. Take 2 seconds to do so.
    linear 2.0 yalign 0.0 clockwise circles 3

트랜스폼 표현식 사용:

<transform_expression>
이름

유형

설명

transform_expression

트랜스폼 (표현식)

보간 목표가 되는 트랜스폼입니다.

이 경우 속성 설정 문 하나만 포함하는 ATL 트랜스폼이어야 합니다. 트랜스폼의 속성들은 해당 보간 문에 직접 작성한 것처럼 처리됩니다.
show logo base:
    xalign 1.0 yalign 0.0

    # Move to the location specified in the truecenter transform in 1.0 seconds
    ease 1.0 truecenter

pass 문

pass 문은 아무 동작도 하지 않습니다.

구문

pass
예를 들어 두 choice 문 묶음(아래 참조)이 서로 바로 이어질 때 이를 구분하고 싶다면 사용할 수 있습니다. 구문상 블록이 필요하지만 내용을 비워 두어야 하는 경우에도 유용합니다. 예를 들어 choice 블록 중 하나가 아무 동작도 하지 않도록 만들 수 있습니다.

repeat 문

repeat 문은 자신이 속한 블록을 처음부터 다시 실행하게 합니다.

구문

기본 형식:
repeat
count 매개변수가 있는 형식:
repeat <count>

사용법

이름

유형

설명

count

int (표현식)

(선택 사항) 블록을 실행할 횟수입니다.

repeat 2로 끝나는 블록은 처음 실행한 것을 포함해 최대 두 번 실행됩니다. repeat 1은 반복하지 않습니다.

repeat 문은 블록의 마지막 문이어야 합니다.

예제

show logo base:
    xalign 0.0
    linear 1.0 xalign 1.0
    linear 1.0 xalign 0.0
    repeat

block 문

block 문은 ATL 문으로 이루어진 블록을 담습니다. 반복할 문들을 한데 묶는 데 사용할 수 있습니다.

구문

block:
    <atl_block>

예제

show logo base:
    alpha 0.0 xalign 0.0 yalign 0.0
    linear 1.0 alpha 1.0

    block:
        linear 1.0 xalign 1.0
        linear 1.0 xalign 0.0
        repeat

parallel 문

parallel 문은 병렬로 실행할 ATL 블록 묶음을 정의합니다.

구문

parallel:
    <atl_block>

사용법

이름

유형

설명

"parallel"

키워드

하나 이상의 parallel 블록입니다.

atl_block

블록

이 병렬 분기에서 실행할 ATL 블록입니다.

parallel 블록을 여러 개 사용하면 모두 동시에 실행됩니다. 마지막 블록이 끝나면 parallel 문도 끝납니다.

각 parallel 블록은 독립적이어야 하며 서로 다른 트랜스폼 속성을 수정해야 합니다. 예를 들어 한 블록에서 가로 이동(xalign)을 제어하고 다른 블록에서 세로 이동(yalign)을 제어할 수 있습니다. 두 블록이 같은 속성을 동시에 바꾸려고 하면 동작을 예측할 수 없으므로 피해야 합니다.

한 블록 안에 여러 parallel 블록이 연속해서 나타나면 모두 하나의 병렬 묶음으로 합칩니다.

예제

show logo base:
    parallel:
        xalign 0.0
        linear 1.3 xalign 1.0
        linear 1.3 xalign 0.0
        repeat
    parallel:
        yalign 0.0
        linear 1.6 yalign 1.0
        linear 1.6 yalign 0.0
        repeat

choice 문

choice 문은 선택 가능한 후보 묶음 중 하나를 정의합니다. Ren'Py는 묶음에서 하나를 선택하여 연결된 ATL 블록을 실행한 뒤, 묶음의 마지막 choice 다음부터 실행을 이어갑니다.

구문

기본 형식:
choice:
    <atl_block>
가중치가 있는 형식:
choice <weight>:
    <atl_block>

사용법

이름

유형

설명

"choice"

키워드

하나 이상의 선택 후보입니다.

weight

float (표현식)

(선택 사항) 이 선택 후보의 가중치입니다. 기본값은 1.0입니다.

atl_block

블록

이 선택 후보에서 실행할 ATL 블록입니다.

한 블록 안에 여러 choice 문이 연속해서 나타나면 모두 하나의 선택 묶음으로 합칩니다. simple_expression을 지정하면 해당 블록의 부동 소수점 가중치로 사용하고, 지정하지 않으면 1.0으로 간주합니다.

pass 문을 사용하면 연속된 choice 블록들을 별개의 선택 묶음으로 나누거나 빈 choice 블록을 만들 수 있습니다.

예제

image eileen random:
    choice:
        "eileen happy"
    choice:
        "eileen vhappy"
    choice 2.0:
        # More likely to be chosen.
        "eileen concerned"

    pause 1.0
    repeat

animation 문

animation 문은 ATL 블록의 첫 번째 문이어야 하며, 일반적인 표시 시간 기준(st) 대신 애니메이션 시간 기준(at)을 사용한다고 Ren'Py에 알립니다. 자세한 내용은 시간 기준을 참조하세요.

구문

animation

사용법

애니메이션 시간 기준은 같은 태그를 가진 이미지나 스크린이 표시될 때 시작합니다. 주로 이미지를 다른 이미지로 교체해도 애니메이션이 같은 시점에서 이어지는 것처럼 보이게 할 때 사용합니다.

예제

image eileen happy moving:
    animation
    "eileen happy"
    xalign 0.0
    linear 5.0 xalign 1.0
    repeat

image eileen vhappy moving:
    animation
    "eileen vhappy"
    xalign 0.0
    linear 5.0 xalign 1.0
    repeat

label start:
    show eileen happy moving
    pause
    show eileen vhappy moving
    pause
이 예제에서는 첫 번째 pause가 끝나면 Eileen의 표정이 바뀌지만 위치는 바뀌지 않습니다. 두 애니메이션이 같은 애니메이션 시간을 공유하므로 스프라이트를 같은 위치에 배치하기 때문입니다. animation 문이 없으면 플레이어가 클릭할 때 위치가 초기화됩니다.

on 문

on 문은 이벤트 핸들러를 정의합니다.

구문

이벤트 하나를 처리할 때:
on <event_name>:
    <atl_block>
여러 이벤트를 처리할 때:
on <event_name>, <event_name>, ...:
    <atl_block>

사용법

이름

유형

설명

event_name

단어

처리할 하나 이상의 이벤트 이름입니다.

atl_block

블록

이벤트가 발생하면 실행할 ATL 블록입니다.

연속된 on 블록은 모두 하나의 문으로 합칩니다. on 문은 이벤트 이름 하나 또는 쉼표로 구분한 이벤트 이름 목록을 처리할 수 있습니다.

이 문은 이벤트를 처리하는 데 사용합니다. 이벤트를 처리하기 시작하면 다른 이벤트의 처리는 끝나고 새 이벤트의 처리가 즉시 시작됩니다. 새 이벤트 없이 이벤트 핸들러가 끝나면 default 이벤트가 발생합니다. 단, 이미 default 이벤트를 처리하고 있다면 발생하지 않습니다.

on 문은 자체적으로 실행이 끝나지 않습니다. 다만 time 문이나 이를 감싸는 이벤트 핸들러로 끝낼 수 있습니다.

예제

show logo base:
    on show:
        alpha 0.0
        linear .5 alpha 1.0
    on hide:
        linear .5 alpha 0.0

transform pulse_button:
    on hover, idle:
        linear .25 zoom 1.25
        linear .25 zoom 1.0

디스플레이어블 문

디스플레이어블 문은 실행될 때 트랜스폼의 자식 디스플레이어블을 설정하거나 교체합니다. 디스플레이어블을 다른 것으로 바꿀 때 선택적으로 화면 전환 효과를 추가할 수도 있습니다.

구문

기본 형식:
<displayable>
화면 전환이 있는 형식:
<displayable> with <transition>

사용법

이름

유형

설명

displayable

디스플레이어블 (표현식)

표시할 새 자식 이미지 또는 시각적 요소입니다.

transition

화면 전환 (표현식)

(선택 사항) 디스플레이어블을 바꿀 때 사용할 화면 전환입니다.

(예: dissolve, fade)

참고

이 위치에서 모든 화면 전환을 사용할 수 있는 것은 아닙니다. 특히 딕셔너리 화면 전환, move- 및 ease- 화면 전환은 동작하지 않습니다.

트랜스폼을 디스플레이어블로 사용: 이미 자식 디스플레이어블을 가진 다른 ATL 트랜스폼을 전달하면, 현재 ATL 블록은 그 트랜스폼의 애니메이션이 끝날 때까지 기다렸다가 실행을 이어갑니다.

경고

자식이 없는 트랜스폼을 전달하면 현재 트랜스폼이 투명해져 아무것도 표시하지 않습니다. 자식이 없는 ATL 트랜스폼은 트랜스폼 표현식 문으로 해석되어 다른 결과가 나올 수도 있습니다.

처음 사용하는 경우: 디스플레이어블이 이미지 파일명("logo.png")이나 내용이 있는 디스플레이어블처럼 실제로 보이는 대상인지 항상 확인하세요.

예제

image atl example:
    "logo_base.png"

    pause 1.0

    "logo_bw.png" with Dissolve(0.5, alpha=True)

트랜스폼 표현식 문

다른 ATL 트랜스폼을 현재 ATL 블록의 일부로 포함하는 문입니다.

구문

<transform_expression>

사용법

이름

유형

설명

transform_expression

트랜스폼 (표현식)

보간 목표가 되는 트랜스폼입니다.

ATL 트랜스폼에 자식이 전달되지 않은 경우에만 적용됩니다. 자식을 전달하는 방법은 페이지 앞부분을 참조하세요. 자식이 있으면 디스플레이어블 문으로 해석합니다. 지정한 ATL 트랜스폼의 내용을 이 문이 있는 위치에 삽입합니다.

예제

transform move_right:
    linear 1.0 xalign 1.0

image atl example:
    # Display logo_base.png
    "logo_base.png"

    # Run the move_right transform.
    move_right

한 줄 contains 문

현재 ATL 트랜스폼의 자식을 표현식의 값으로 설정하거나 교체하는 문으로, 애니메이션에 유용합니다.

구문

contains <displayable>

사용법

이름

유형

설명

displayable

디스플레이어블, 트랜스폼 (표현식)

자식 디스플레이어블 또는 트랜스폼입니다.

디스플레이어블 문은 덜 명시적이고 트랜스폼 표현식 문과 구분이 모호할 수 있지만, 자식을 교체할 때 화면 전환을 사용할 수 있습니다. contains 문은 다른 ATL 트랜스폼의 코드를 삽입하는 대신 그 트랜스폼을 자식으로 포함하려는 경우에 특히 유용합니다.

참고

ATL 트랜스폼이 다른 ATL 트랜스폼을 자식으로 포함하게 하려면 이 문을 사용합니다. 특히 자식의 코드를 직접 삽입하는 대신 별도의 트랜스폼 객체로 유지해야 할 때 유용합니다.

그 밖의 경우에는 디스플레이어블 문이 자식 디스플레이어블을 설정하는 더 간단한 방법이며, 이전 자식을 새 자식으로 교체할 때 재생할 화면 전환을 지정할 수 있다는 장점도 있습니다.

예제

transform an_animation:
    "1.png"
    pause 2
    "2.png"
    pause 2
    repeat

image move_an_animation:
    contains an_animation

    # If we didn't use contains, we'd still be looping
    # and would never reach here.
    xalign 0.0
    linear 1.0 yalign 1.0

블록 contains 문

contains 블록은 한 줄 형식과 마찬가지로 트랜스폼의 자식을 설정하지만 방식이 다릅니다.

구문

contains:
    <atl_block>

사용법

연속된 하나 이상의 contains 블록을 모두 하나의 contains 문으로 묶고, Fixed()로 감싸 트랜스폼의 자식으로 설정합니다.

각 블록은 사용할 디스플레이어블을 정의해야 하며, 그렇지 않으면 오류가 발생합니다. contains 문은 자식의 실행이 끝날 때까지 기다리지 않고 즉시 실행됩니다.

예제

image test double:
    contains:
        "logo.png"
        xalign 0.0
        linear 1.0 xalign 1.0
        repeat

    contains:
        "logo.png"
        xalign 1.0
        linear 1.0 xalign 0.0
        repeat

function 문

function 문은 ATL에서 Python 코드를 사용할 수 있게 합니다.

구문

function <func>

사용법

이름

유형

설명

func

function (표현식)

호출할 함수입니다. 서명은 (trans: Transform, st: float, at: float) -> float | None입니다.

함수의 서명은 Transform()에서 사용하는 함수와 같습니다.

첫 번째 인수는 트랜스폼 객체입니다. 이 객체의 속성으로 트랜스폼 속성을 설정할 수 있습니다.

두 번째 인수는 표시 시간 기준이며, 함수의 실행이 시작된 뒤 지난 초 수입니다.

세 번째 인수는 애니메이션 시간 기준이며, 같은 태그를 가진 대상이 화면에 표시된 뒤 지난 초 수입니다.

함수가 숫자를 반환하면 해당 초만큼 지난 뒤 다시 호출됩니다. 0초는 가능한 한 빨리 호출하라는 뜻입니다. 함수가 None을 반환하면 다음 ATL 문으로 제어가 넘어갑니다.

이 함수는 첫 번째 인수의 트랜스폼 객체를 변경하는 것 외에는 부수 효과가 없어야 합니다. 예측 로딩 과정에서 언제든 어떤 값으로든 호출될 수 있습니다.

function은 트랜스폼 속성이 아니며, Transform()의 function 매개변수와 동작이 정확히 같지는 않다는 점에 유의하세요.

예제

init python:
    def slide_vibrate(trans, st, at, /):
        if st > 1.0:
            trans.xalign = 1.0
            trans.yoffset = 0
            return None
        else:
            trans.xalign = st
            trans.yoffset = random.randrange(-10, 11)
            return 0

label start:
    show logo base:
        function slide_vibrate
        pause 1.0
        repeat

time 문

time 문은 제어 문입니다.

구문

time <value>

사용법

이름

유형

설명

value

float/int (표현식)

블록 실행 시작부터 지난 시간으로, 초 단위입니다.

문에 지정한 시간에 도달하면 다음 문이 실행되기 시작합니다. 이전 문이 실행 중이어도 제어가 넘어가며 해당 문은 즉시 종료됩니다.

지정한 시간 전에 time 문에 도달하면 트랜스폼이 멈추고 time 문이 제어권을 가져올 시점까지 기다립니다.

한 블록에 time 문이 여러 개 있으면 지정한 시간이 순서대로 엄격히 증가해야 합니다.

예제

image backgrounds:
    "bg band"
    xoffset 0
    block:
        linear 1 xoffset 10
        linear 1 xoffset 0
        repeat # control would never exit this block

    time 2.0
    xoffset 0
    "bg whitehouse"

    time 4.0
    "bg washington"

event 문

event 문은 지정한 이름의 이벤트를 발생시킵니다.

구문

event <event_name>

사용법

이름

유형

설명

event_name

단어

발생시킬 이벤트의 이름입니다.

블록 안에서 이벤트가 발생하면 해당 이름의 이벤트 핸들러가 있는지 확인합니다. 있으면 그 핸들러로 제어가 넘어갑니다. 없으면 이 블록을 감싸는 이벤트 핸들러로 이벤트가 전파됩니다.

외부 이벤트

다음 이벤트는 ATL 트랜스폼 안에서 자동으로 발생합니다.

start

더 높은 우선순위의 이벤트가 발생하지 않은 상태에서 on 문에 진입할 때 발생하는 가상 이벤트입니다.

show

같은 태그의 이미지가 없는 상태에서 show 문이나 scene 문으로 트랜스폼을 표시할 때 발생합니다.

replace

show 문으로 같은 태그의 이미지를 교체하여 트랜스폼을 표시할 때 발생합니다.

hide

hide 문이나 이에 해당하는 Python 코드로 트랜스폼을 숨길 때 발생합니다.

scene 문으로 트랜스폼을 제거하거나, 게임 메뉴를 나갈 때처럼 트랜스폼이 속한 컨텍스트를 벗어나는 경우에는 발생하지 않습니다.

replaced

트랜스폼이 다른 트랜스폼으로 교체될 때 발생합니다. 이미지는 ATL 블록이 끝날 때까지 실제로 숨겨지지 않습니다.

hover, idle, selected_hover, selected_idle, insensitive, selected_insensitive

이 트랜스폼을 포함하는 버튼이나 이 트랜스폼에 포함된 버튼이 해당 이름의 상태에 진입할 때 발생합니다.

ATL 커링과 일부 매개변수 전달

transform 문으로 정의한 ATL 트랜스폼의 매개변수는 서로 다른 시점에 설정할 수 있습니다. ATL 트랜스폼을 함수처럼 호출해도 결과는 여전히 트랜스폼이며, 전달한 값은 해당 매개변수의 새 기본값처럼 취급됩니다.

예를 들면 다음과 같습니다.

transform screamer(child, screamee, wait_time=2, flash_time=.1):
    child
    pause wait_time
    screamee
    pause flash_time
    child

# doing this doesn't raise an error (it would if it were a Python function)
define shorter_screamer = screamer(wait_time=1)

define eileen_excited_screamer = screamer(screamee="eileen excited", flash_time=.2)

label start:
    show hhannahh happy at screamer(screamee="hhannahh surprised", wait_time=1.5)
    "이런 방법이 있어요"

    show eileen vhappy at eileen_excited_screamer
    "이런 방법도 있어요"

    show patricia sad at eileen_excited_screamer(screamee="patricia wow")
    "이렇게 해도 돼요"

shorter_screamer 트랜스폼도 screamer 트랜스폼과 마찬가지로 show eileen at screamer처럼 직접 사용할 수는 없습니다. screamee 매개변수에 값이 없기 때문입니다.

레이블이나 스크린과 마찬가지로, transform 문으로 직접 만든 트랜스폼의 매개변수 기본값은 정의할 때가 아니라 호출할 때 평가됩니다.

반면 다른 트랜스폼을 호출하여 얻은 트랜스폼(위 예제의 shorter_screamer나 patricia에 적용한 트랜스폼)은 모든 매개변수 기본값이 이미 평가된 상태입니다. 원래 트랜스폼의 기본값을 평가한 경우(shorter_screamer의 flash_time이나 patricia 트랜스폼의 wait_time)와 같은 줄의 앞선 호출에서 값을 전달한 경우(shorter_screamer의 wait_time, patricia 트랜스폼의 screamee 및 flash_time) 모두 마찬가지입니다.

특수 child 매개변수

ATL 트랜스폼에 "child"라는 매개변수가 있고 이 매개변수가 값을 받으면, 매개변수의 종류나 값을 받는 방식과 관계없이 트랜스폼의 자식도 동시에 해당 값으로 설정됩니다. 위치 인수와 키워드 인수 모두 해당하며, 위치 전용인지 키워드 전용인지, 기본값이 있는지 필수인지도 관계없습니다.

매개변수의 기본값은 여기에 해당하지 않습니다. 반드시 외부에서 값을 받아야 합니다.

반대로 해당 ATL 트랜스폼을 트랜스폼으로 사용하면 child= 키워드 인수가 전달됩니다. 따라서 자식이 설정되는 것과 함께, 이 값을 받을 매개변수가 있다면 트랜스폼이 실행될 때 자식의 값을 갖습니다. 키워드로 전달하므로 위치 전용 매개변수는 제외됩니다.

예를 들어 전달받은 자식과 다른 디스플레이어블을 번갈아 표시할 수 있습니다.

transform lucy_jump_scare(child):
    # the child is implicitly set as the child of the transform
    pause 5

    # Jump scare
    "lucy mad"
    pause .2

    # Go back to the original child
    child

원래 자식을 contains 블록 안에 넣는 데 사용할 수도 있습니다.

transform marquee(width, height=1.0, duration=2.0, child=None):
    xcenter 0.5
    ycenter 0.5

    crop (0, 0, 0.5, 500)

    contains:
        child
        xanchor 0.0 xpos 1.0
        linear duration xanchor 1.0 xpos 0.0

키워드로 값을 받을 수 있는 old_widget 및 new_widget 매개변수는 ATL 화면 전환에서 특별한 용도로 사용합니다. 따라서 위치 전용 매개변수이면 안 됩니다.

워퍼

워퍼는 보간 문이 경과했다고 간주하는 시간을 바꾸는 함수입니다. t를 t'로 변환하는 함수로 정의하며, t와 t'는 부동 소수점 수입니다. 지정한 시간 동안 t는 0.0에서 1.0까지 변합니다. 지속 시간이 0이면 실행 시 t는 1.0입니다. t'는 0.0에서 시작해 1.0에서 끝나야 하지만 그 사이에는 더 크거나 작은 값도 가질 수 있습니다. 기본적으로 다음 워퍼가 정의되어 있습니다.

pause: 기다린 뒤 새 값으로 즉시 바꿉니다. t == 1.0이면 t' = 1.0이고, 그 밖의 경우 t' = 0.0입니다.
linear: 선형으로 보간합니다. t' = t
ease: 느리게 시작해 빨라진 뒤 다시 느려집니다. t' = .5 - math.cos(math.pi * t) / 2.0
easein: 빠르게 시작한 뒤 느려집니다. t' = math.cos((1.0 - t) * math.pi / 2.0)
easeout: 느리게 시작한 뒤 빨라집니다. t' = 1.0 - math.cos(t * math.pi / 2.0)

또한 Robert Penner의 이징 함수 대부분을 지원합니다. 위 이름들과 맞추기 위해 함수 이름을 일부 변경했습니다. 이 표준 함수들의 그래프는 https://easings.net/에서 볼 수 있습니다.

Ren'Py 이름	easings.net 이름
ease_back	easeInOut_back
ease_bounce	easeInOut_bounce
ease_circ	easeInOut_circ
ease_cubic	easeInOut_cubic
ease_elastic	easeInOut_elastic
ease_expo	easeInOut_expo
ease_quad	easeInOut_quad
ease_quart	easeInOut_quart
ease_quint	easeInOut_quint
easein_back	easeOut_back
easein_bounce	easeOut_bounce
easein_circ	easeOut_circ
easein_cubic	easeOut_cubic
easein_elastic	easeOut_elastic
easein_expo	easeOut_expo
easein_quad	easeOut_quad
easein_quart	easeOut_quart
easein_quint	easeOut_quint
easeout_back	easeIn_back
easeout_bounce	easeIn_bounce
easeout_circ	easeIn_circ
easeout_cubic	easeIn_cubic
easeout_elastic	easeIn_elastic
easeout_expo	easeIn_expo
easeout_quad	easeIn_quad
easeout_quart	easeIn_quart
easeout_quint	easeIn_quint

이 워퍼들은 위 함수들을 포함하는 읽기 전용 모듈 _warper에서 접근할 수 있습니다. Dissolve()처럼 시간 워핑 함수를 받는 Ren'Py 기능에 유용하며 다음과 같이 사용할 수 있습니다.

with Dissolve(1, time_warp=_warper.easein_quad)

python early 블록에서 renpy.atl_warper 데코레이터로 새 워퍼를 정의할 수 있습니다. 이 블록은 해당 워퍼를 사용하는 모든 파일보다 먼저 파싱되는 파일에 두어야 합니다. 작성 방법은 다음과 같습니다.

python early hide:

    @renpy.atl_warper
    def linear(t):
        return t

트랜스폼 교체

ATL 트랜스폼, 내장 트랜스폼 또는 Transform 클래스로 정의한 트랜스폼을 이 범주에 속하는 다른 트랜스폼으로 교체하면, 새 트랜스폼이 기존 트랜스폼의 속성을 상속합니다. 다른 종류의 트랜스폼에는 이 상속이 적용되지 않습니다.

show 문의 at 목록에 트랜스폼이 여러 개 있으면, 어느 한쪽 목록이 끝날 때까지 마지막부터 처음 순서로 서로 대응시킵니다. 예를 들면 다음과 같습니다.

show eileen happy at a, b, c
"대사!"
show eileen happy at d, e

c 트랜스폼은 e로, b 트랜스폼은 d로 교체되며, a 트랜스폼을 교체하는 것은 없습니다.

교체 시 두 트랜스폼의 종류가 모두 상속을 지원하면 기존 트랜스폼의 속성값을 새 트랜스폼에 복사합니다. 기존 트랜스폼에 애니메이션이 적용되어 있다면 현재의 중간값을 상속합니다. 예를 들면 다음과 같습니다.

transform bounce:
    linear 3.0 xalign 1.0
    linear 3.0 xalign 0.0
    repeat

transform headright:
    linear 15 xalign 1.0

label example:
    show eileen happy at bounce
    pause
    show eileen happy at headright
    pause

이 예제에서는 플레이어가 클릭할 때까지 이미지가 왼쪽과 오른쪽을 왕복합니다. 클릭하면 bounce 트랜스폼의 xalign 속성으로 headright 트랜스폼의 xalign 속성을 초기화하므로 플레이어가 클릭한 순간의 위치에서 이미지가 이동하기 시작합니다.

위치 속성(xpos, ypos, xanchor, yanchor 및 이를 설정하는 xalign, radius/angle 등)에는 특별한 상속 규칙이 있습니다. 자식에 설정한 값이 부모에 설정한 값을 덮어씁니다. 디스플레이어블은 위치를 하나만 가질 수 있으며 명시적으로 설정하는 위치가 우선하기 때문입니다.

마지막으로 show 문에 at 절이 없으면 같은 트랜스폼을 그대로 사용하므로 상속할 필요가 없습니다. 모든 트랜스폼 속성을 초기화하려면 디스플레이어블을 숨겼다가 다시 표시합니다. 위치는 유지하면서 디스플레이어블에 적용된 애니메이션을 중단하려면 다음과 같이 사용할 수 있습니다.

show eileen happy at some_animation
"와, 반중력은 이런 느낌이군요!"

show eileen:
    pass
"그래도 가만히 있는 게 좋아요."

시간 기준

시간 기준에는 혼동하기 쉬운 두 종류가 있습니다.

st (표시 시간 기준): 이 디스플레이어블을 화면에 처음 표시할 때 시작합니다.
at (애니메이션 시간 기준): 같은 태그의 이미지를 표시한 뒤 숨기지 않은 상태로 이어지는 시간입니다.

태그 없이 디스플레이어블을 표시하면 st와 at은 같습니다.

참고

트랜스폼은 기본적으로 st를 사용합니다. animation으로 at으로 전환할 수 있습니다.

Transform 클래스

Transform 클래스는 가장 간단한 ATL 트랜스폼과 같은 역할을 합니다.

class Transform(child=None, *, function=None, reset=False, **properties)

자식에 자르기, 회전, 크기 조절, 알파 블렌딩 등의 연산을 적용하는 트랜스폼을 만듭니다. 트랜스폼 객체에는 트랜스폼 속성에 대응하는 필드가 있으며 이를 자식에 적용합니다.

child: 트랜스폼을 적용할 자식입니다.
reset: True이면 트랜스폼을 표시할 때 교체되는 이전 트랜스폼의 속성을 상속하지 않고 속성을 기본값으로 초기화합니다.

function(trans: Transform, st: float, at: float, /) → float | None

None이 아니면 트랜스폼을 렌더링할 때 이 함수를 다음 세 위치 인수로 호출합니다.

트랜스폼 객체.
초 단위의 표시 시간 기준.
초 단위의 애니메이션 시간 기준.

함수는 다시 호출될 때까지의 지연 시간을 초 단위로 반환해야 합니다. None을 반환하면 다음 상호작용이 시작될 때 다시 호출합니다.

이 함수는 첫 번째 인수의 Transform 객체를 변경하는 것 외에는 부수 효과가 없어야 합니다. 예측 로딩 과정에서 언제든 어떤 값으로든 호출될 수 있습니다.

추가 키워드 인수는 트랜스폼 속성에 설정할 값입니다. 이 속성들은 트랜스폼을 그릴 때마다 설정되므로 Transform 객체를 만든 뒤에는 변경할 수 없습니다. 다만 다른 트랜스폼 속성에 대응하는 필드는 이후에도 설정하거나 변경할 수 있습니다. function 매개변수로 전달한 함수 안에서 바꾸거나, update() 메서드를 호출하기 직전에 바꾸면 됩니다.

hide_request: 트랜스폼이 숨겨지는 중임을 나타내기 위해 함수 호출 시 이 속성을 참으로 설정합니다.

hide_response: hide_request가 참이면 이 값을 거짓으로 설정하여 트랜스폼이 숨겨지지 않도록 할 수 있습니다.

original_child: 트랜스폼을 만들 때 설정된 자식 디스플레이어블로, set_child를 호출하기 전의 자식입니다. 생성 시 자식이 없었다면 None일 수 있습니다.

set_child(child): 새 child를 인수로 이 메서드를 호출하면 트랜스폼의 자식이 바뀝니다.

update(): function 인수로 전달한 함수 밖에서 트랜스폼 속성 필드를 갱신했다면 변경 사항이 반영되도록 이 메서드를 호출해야 합니다.

unique():

새로 만든 트랜스폼을 고유한 객체로 표시하려면 이 메서드를 호출합니다. 일반적으로 트랜스폼은 디스플레이어블에 추가될 때 복사되면서 상태가 초기화됩니다. 이 메서드는 그 동작을 막습니다. 여러 번 사용해도 상태를 유지하거나 function 인수의 함수 밖에서 접근해야 하는 트랜스폼을 만들 때 유용합니다.

이 함수는 Transform을 반환합니다.

Python에서 디스플레이어블에 트랜스폼 적용

Python에서 디스플레이어블 d에 트랜스폼 t를 적용하는 방법은 여러 가지입니다.

가장 범용적이며 권장하는 방법은 At(d, t)입니다(아래 참조). 모든 트랜스폼에서 동작합니다.
t(child=d)는 모든 ATL 트랜스폼에서 동작합니다.
t(d)는 모든 Python 트랜스폼과 위치 매개변수가 없는 ATL 트랜스폼에서 동작합니다.

At(d, *args)

디스플레이어블 d에 args의 각 트랜스폼을 적용합니다. 왼쪽에서 오른쪽 순서로 적용하므로 가장 오른쪽 인수가 가장 바깥쪽 트랜스폼이 됩니다.

transform birds_transform:
    xpos -200
    linear 10 xpos 800
    pause 20
    repeat

image birds = At("birds.png", birds_transform)

참고

transform 문으로 정의한 트랜스폼처럼 아직 값을 받지 않은 매개변수가 남아 있으면 결과를 표시하지 못할 수 있습니다.

참고

결과가 여전히 다른 디스플레이어블에 적용할 수 있는 트랜스폼일 수 있습니다. 이 경우 기존 자식을 덮어씁니다. ATL 트랜스폼은 자식이 설정되어 있어도 트랜스폼으로 사용할 수 있으므로 이에 해당합니다.

호출 가능한 객체를 트랜스폼으로 사용

마지막으로 단순한 Python 호출 가능 객체도 트랜스폼으로 사용할 수 있습니다. 이 객체는 디스플레이어블 하나를 인수로 받아 새 디스플레이어블을 반환해야 합니다. 예를 들면 다음과 같습니다.

init python:

    # this transform uses the right and left transforms
    def right_or_left(d):
        if switch:
            return At(d, right)
        else:
            return At(d, left)

따라서 Flatten()처럼 디스플레이어블을 받아 디스플레이어블을 반환하는 일부 내장 기능도 트랜스폼이며 그 용도로 사용할 수 있습니다.