스크린과 스크린 언어

Ren'Py 게임에서 사용자에게 보이는 요소는 이미지와 사용자 인터페이스로 나눌 수 있습니다. 이미지는 scene, show, hide 문으로 표시하며 일반적으로 이야기의 일부입니다. 그 밖의 모든 요소는 사용자 인터페이스에 속하며, 스크린으로 사용자 지정합니다.

스크린은 네 가지 방식으로 표시할 수 있습니다.

스크립트 문을 실행할 때 암시적으로 표시합니다. 예를 들어 say 문은 say 스크린을 표시합니다.
자동으로 표시합니다. 예를 들어 실행을 시작하거나 사용자가 메인 메뉴로 돌아오면 main_menu 스크린을 표시합니다.
버튼, 마우스 버튼, 키보드 키에 연결된 액션으로 표시합니다. 기본적으로 마우스 오른쪽 버튼이나 Escape를 누르면 save 스크린을 표시합니다. save 스크린을 여는 화면 버튼을 정의할 수도 있습니다.
스크린을 표시하는 문으로 명시적으로 표시합니다.

여러 스크린을 동시에 표시할 수 있습니다.

스크린에는 두 가지 주요 기능이 있습니다. 첫째는 텍스트, 바, 이미지로 사용자에게 정보를 표시하는 것입니다. 이런 정보 중 일부는 게임 진행에 필수적입니다. 예를 들어 say 스크린은 캐릭터 이름과 말하는 내용을 포함한 대사를 표시합니다.

둘째는 사용자가 게임과 상호작용하게 하는 것입니다. 버튼과 바를 통해 액션을 실행하고 값을 조절할 수 있습니다. Ren'Py에는 게임 진행, 환경설정, 저장과 불러오기 등의 미리 정의된 액션이 있습니다. 제작자가 Python으로 새 액션을 작성할 수도 있습니다.

스크린은 각 상호작용을 시작하거나 다시 시작할 때 갱신됩니다. with None은 상호작용을 발생시키지 않으므로 스크린도 갱신하지 않습니다. 필요하다면 with Pause(0)만으로 상호작용을 일으킬 수 있습니다.

스크린에는 일부 변수에 값을 제공하는 스코프가 연결됩니다. 변수에는 여러 종류가 있으며, 다음 순서로 이름을 찾습니다.

첫째는 지역 변수입니다. 단독으로 표시하거나 호출하지 않고 use 문으로 다른 스크린에 포함된 스크린에만 존재합니다. 아래의 스크린 변수와 비슷하고 생성 방식도 같지만, 사용되는 스크린 안에서만 접근할 수 있습니다. SetLocalVariable 등의 액션이나 해당 스크린의 Python 블록 또는 한 줄 코드로 설정합니다. SetScreenVariable 같은 액션은 지역 변수에 작동하지 않습니다.
- 지역 매개변수는 use로 사용되는 스크린이 받는 매개변수입니다. 지역 변수와 같은 스코프에 있으며, 아래의 스크린 매개변수와 동작 및 제약이 같습니다.
지역 변수에서 이름을 찾지 못하거나 다른 스크린에서 사용하는 스크린이 아니면 스크린 변수를 찾습니다. 최상위 스크린 내부의 default 또는 Python 문으로 만든 변수입니다. SetScreenVariable 등의 액션, 최상위 스크린의 Python 블록이나 한 줄 코드로 설정할 수 있습니다. 같은 이름의 지역 변수가 없다면 사용되는 스크린에서도 설정할 수 있습니다.
- 스크린 매개변수는 screen 문의 괄호에서 정의하고 전달하는 값입니다. 스크린 변수와 같은 스코프이므로 이름이 겹칠 수 없지만, 액션으로 설정하거나 편집할 수는 없습니다. 액션 실행 때마다를 비롯해 임의의 시점에 원래 값으로 초기화되기 때문입니다. 따라서 SetScreenVariable이나 다른 액션으로 바꿔도 곧바로 초기화됩니다. 내부 Python 블록도 임의의 시점에 실행되므로 그 안에서 정의한 변수 역시 마찬가지입니다. 스크린이 표시될 때만 실행되는 내부 default 문과는 다릅니다.
마지막으로 모든 Ren'Py 전역 변수가 있는 일반 스토어에서 이름을 찾습니다. 이 변수들은 SetVariable 등의 액션으로 설정합니다.

참고

스크린을 직접 표시하기도 하고 다른 스크린 안에서 사용하기도 하면서 액션으로 내부 변수를 설정하려면 SetLocalVariable을 사용합니다. 효율은 훨씬 낮지만 두 경우 모두 작동합니다.

스크린은 외부에서 관찰할 수 있는 부수 효과를 일으켜서는 안 됩니다. Ren'Py는 필요하다고 판단하면 스크린을 여러 번 실행합니다. 처음 표시하기 전 이미지 예측 과정에서도 실행합니다. 따라서 부수 효과가 있으면 예측할 수 없는 시점에 발생할 수 있습니다.

스크린에서 Python 제너레이터를 사용하면 예측할 수 없는 결과가 생길 수 있습니다. 스크린 컨텍스트용 Python 소스를 컴파일하는 인터프리터의 방식에 문제가 있기 때문입니다. 스크린에서 호출하는 Python 함수 안에서는 제너레이터를 쓸 수 있지만, 스크린 자체에서는 사용할 수 없습니다.

스크린 언어

스크린 언어는 대부분 선언적인 방식으로 스크린을 표시합니다. 새 스크린 선언문, 디스플레이어블 추가문, 제어문으로 이루어집니다.

스크린의 예는 다음과 같습니다.

screen say(who, what):
    window id "window":
        vbox:
            spacing 10

            text who id "who"
            text what id "what"

첫 줄은 스크린을 선언하는 Ren'Py 언어의 screen 문입니다. 이름이 say이므로 대사 표시에 사용합니다. who와 what 두 매개변수를 받습니다.

스크린에는 "window" ID의 창이 있습니다. 창 안에는 간격 10픽셀의 세로 박스가 있고, 그 안에는 화자 이름과 대사를 각각 표시하는 두 텍스트 필드가 있습니다.

스크린 언어 문법

대부분의 스크린 언어 문은 공통 문법을 사용합니다. 일부 제어문은 문법이 다릅니다. 문은 줄의 처음에서 해당 문을 시작하는 키워드로 시작합니다.

매개변수를 받으면 키워드 바로 뒤에 놓습니다. 별도 설명이 없으면 공백으로 구분한 단순 표현식입니다.

위치 매개변수 뒤에는 속성 목록이 옵니다. 각 속성은 이름과 그 뒤의 값으로 이루어집니다. 별도 설명이 없으면 값은 단순 표현식이며, 각 속성은 공백으로 구분합니다.

문이 콜론 :으로 끝나면 블록을 받습니다. 블록의 각 줄은 다음 중 하나입니다.

속성 목록.
스크린 언어 문.

screen 문

screen은 새 스크린을 선언하는 Ren'Py 스크립트 언어 문입니다. 스크린 언어의 공통 문법으로 파싱합니다.

매개변수 하나로 스크린 이름을 받습니다. 표현식이 아닌 이름입니다. 다음 속성을 받습니다.

modal: True이면 모달 스크린입니다. 기본 키맵을 제외하고 아래의 디스플레이어블과 상호작용하지 못하게 합니다. 게임 시작 시 한 번 평가합니다.

sensitive: 스크린의 활성 여부를 결정하는 표현식입니다. 상호작용마다 최소 한 번 평가합니다.

tag: 표현식이 아닌 이름으로 파싱합니다. 스크린에 연결할 태그를 지정합니다. 같은 태그의 다른 스크린을 대체하므로 같은 컨텍스트에서 메뉴 스크린 하나만 표시하도록 보장할 수 있습니다.

zorder: 사용자에게 얼마나 가까이 표시할지 제어합니다. 숫자가 클수록 앞에 표시됩니다. 기본값은 0입니다.

variant: 지정한다면 정의할 스크린 변형의 문자열 또는 문자열 리스트여야 합니다. 스크린 변형을 참고하세요.

style_prefix: 아래 설명처럼 스크린 자식의 스타일 접두사를 제공하는 문자열입니다.

layer: 기본적으로 스크린을 표시할 레이어 이름 문자열입니다.

roll_forward

참이면 call screen으로 사용할 때 롤포워드를 활성화합니다. 거짓이면 비활성화하고, None이거나 지정하지 않으면 config.call_screen_roll_forward를 사용합니다.

call screen에서 롤포워드할 때 반환값과 마지막 점프는 보존되지만 다른 부수 효과는 발생하지 않습니다. 따라서 Jump()와 Return()만 포함한 스크린은 roll_forward를 안전하게 활성화할 수 있습니다. 다른 액션의 부수 효과는 롤포워드 중 발생하지 않을 수 있습니다.

스크린 첫 줄이 Python 문자열이면 독스트링으로 사용합니다. renpy.get_screen_docstring()으로 가져올 수 있습니다.

screen hello_world():
     """
     Displays a hello world message.
     """

     tag example
     zorder 1
     modal False

     text "안녕, 세상아."

스크린은 매개변수 목록을 받을 수 있습니다.

screen center_text(s, size=42):
     text s size size

매개변수가 없어도 빈 괄호를 지정해야 합니다. 괄호 없는 스크린을 다른 스크린에서 use하면 use 문 절의 동작 차이가 적용됩니다. 다른 스크린에서 use하지 않더라도 괄호를 생략하면 내부 처리 효율이 떨어집니다. 매개변수에 관한 스크린 최적화 절을 참고하세요.

사용자 인터페이스 문

사용자 인터페이스 문은 디스플레이어블을 만들어 스크린이나 이를 감싸는 디스플레이어블에 추가합니다. 정보를 표시하고, 사용자와 게임의 상호작용을 지원하며, 여러 이벤트에 게임이 반응하도록 합니다.

모든 사용자 인터페이스 문은 다음 공통 속성을 받습니다.

at

트랜스폼, 트랜스폼 리스트 또는 at 안에 직접 정의한 익명 트랜스폼입니다.

transform hello_t:
    align (0.7, 0.5) alpha 0.0
    linear 0.5 alpha 1.0

screen hello_title():
    text "안녕하세요." at hello_t
    text "안녕하세요." at transform:
        align (0.2, 0.5) alpha 0.0
        linear 0.5 alpha 1.0

이 트랜스폼으로 디스플레이어블을 감쌉니다. 트랜스폼을 스크린에 직접 추가한 경우에만 show, hide, replace, replaced 외부 이벤트를 전달합니다.

예를 들어 트랜스폼으로 vbox를 감싸 스크린에 직접 추가하면 이벤트를 받습니다. 그러나 vbox 내부의 textbutton을 감싼 트랜스폼에는 이벤트를 전달하지 않습니다.

하나의 문에 at 속성과 at transform을 함께 지정할 수 있습니다. 속성이 먼저 와야 하며 먼저 적용됩니다.

screen title():
    add "title background":
        at sepia

    text "게임 제목":
        at sepia, truecenter
        at transform:
            alpha 0.0
            linear 0.5 alpha 1.0

default_focus

지정한 값이 참이면 기본적으로 포커스를 받습니다. 여러 디스플레이어블에 지정하면 값을 비교해 가장 큰 값을 가진 것이 기본이 됩니다.

마지막 상호작용이 마우스 클릭, 이동, 터치가 아닌 경우에만 기본 포커스를 사용합니다.

extra_alt

자체 음성 출력용 추가 대체 텍스트입니다. 정의되어 있고 자체 음성 출력이 켜져 있으면 '?' 키를 누를 때 읽어 줍니다.

extra_alt는 더 구체적인 extra_alt가 없는 모든 자식에 상속됩니다.

추가 대체 텍스트는 시각 장애가 있는 플레이어에게 디스플레이어블 그룹의 추가 정보를 제공하기 위한 것입니다.

focus: 문자열이나 정수를 받아 포커스용 이름을 붙입니다. Ren'Py는 상호작용 시작 시 포커스를 줄 대상을 결정할 때 이름 사이의 구조적 유사성을 찾습니다. 이름이 있는 박스의 세 번째 버튼이 상호작용 종료 시 포커스되어 있었다면, 다음 시작 시 같은 이름의 박스에서 세 번째 버튼을 강조합니다.

group_alt

자체 음성 출력용 그룹 접두사입니다. 같은 접두사의 디스플레이어블에 처음 포커스를 주면 읽고, 다른 접두사의 디스플레이어블에 포커스를 줄 때까지 다시 읽지 않습니다.

group_alt는 더 구체적인 group_alt가 없는 모든 자식에 상속됩니다.

id

사용자 인터페이스 문의 식별자입니다. 스크린을 표시할 때 해당 식별자의 디스플레이어블에 속성 값을 전달할 수 있습니다. 일부 스크린은 특정 식별자의 디스플레이어블이 반드시 필요합니다.

ID로 생성하면 Displayable 객체의 id 속성에 문자열로 저장합니다.

prefer_screen_to_id: 참이면 스크린과 디스플레이어블 식별자 양쪽에서 지정한 속성 중 스크린 것을 사용합니다. 기본값인 거짓이면 디스플레이어블 것을 사용합니다. Character가 설정한 속성을 스크린이 덮어쓸지 결정하는 데 사용할 수 있습니다.

style: 적용할 스타일 이름 문자열입니다. 스타일은 스타일 속성의 기본값을 제공합니다.

style_prefix

더 구체적인 스타일이나 접두사가 지정되지 않은 모든 자식과 이 디스플레이어블에 스타일 접두사를 제공합니다.

스타일 이름은 접두사, 밑줄, 접미사를 이어 만듭니다. 접미사는 style_suffix로 지정하거나 디스플레이어블에 따라 결정합니다.

예를 들어 vbox의 접두사가 "pref"이면 스타일은 "pref_vbox"입니다. 더 구체적인 스타일이나 접두사가 없으면 내부 버튼은 "pref_button"을 사용합니다.

이렇게 접근한 스타일이 없으면 자동 생성합니다. 접두사를 None으로 설정하면 자신과 자식에서 제거합니다.

style_group: 이전 Ren'Py 버전에서 사용하는 style_prefix의 별칭입니다.

style_suffix

style_prefix와 합쳐 이름을 만드는 접미사입니다. "small_button"이고 접두사가 "pref"이면 "pref_small_button"을 사용합니다.

접두사가 없으면 스타일 이름으로 직접 사용합니다. 접미사는 디스플레이어블 하나에만 적용되며 자식에게는 적용되지 않습니다.

tooltip

툴팁을 지정합니다. 포커스를 얻으면 GetTooltip()에서 값을 얻을 수 있습니다. 자세한 내용은 툴팁 절을 참고하세요.

tooltip에 전달한 객체는 동등성 비교를 지원해야 합니다. 그렇지 않으면 무한 반복이 발생할 수 있습니다.

arguments: 디스플레이어블에 전달할 추가 위치 인수의 튜플 또는 리스트입니다.

properties: 디스플레이어블에 전달할 추가 속성의 딕셔너리입니다.

많은 사용자 인터페이스 문은 스타일 속성 그룹이나 트랜스폼 속성을 받습니다. 속성에는 적용 시점을 결정하는 스타일 접두사를 붙일 수 있습니다. 예를 들어 텍스트에 hover_size를 지정하면 마우스를 올렸을 때 크기를 설정합니다.

사용자 인터페이스 문은 따옴표 없는 변수 이름을 받는 as 절을 지원합니다. 생성한 디스플레이어블을 해당 변수에 대입합니다. 끌어 놓기 문서에 예제가 있습니다.

Bar

데이터를 표시하거나 조절하는 가로 바를 만듭니다. 다음 속성을 받습니다.

value: 바의 현재 값입니다. 바 값 객체나 숫자입니다.

range: 바의 최댓값입니다. value가 숫자이면 필수이며, value가 바 값 객체이면 무시합니다.

adjustment: 이 바가 조절하는 ui.adjustment() 객체입니다.

changed: 지정하면 Python 함수여야 합니다. 조정 값이 바뀌면 그 값을 받아 호출됩니다.

hovered: 바가 포커스를 얻을 때 실행할 액션입니다.

unhovered: 바가 포커스를 잃을 때 실행할 액션입니다.

released: 바의 버튼을 놓을 때 실행할 액션입니다. 값이 바뀌지 않았어도 호출됩니다.

action: 바의 값이 바뀔 때 실행할 액션입니다.

value와 adjustment 중 하나는 반드시 지정해야 합니다. 다음도 받습니다.

자식을 받지 않습니다.

screen volume_controls():
    frame:
        has vbox

        bar value Preference("sound volume") released Play("sound", "audio/sample_sound.ogg")
        bar value Preference("music volume")
        bar value Preference("voice volume")

Button

실행하면 액션을 수행하는 화면 영역을 만듭니다. 매개변수 없이 다음 속성을 받습니다.

action: 버튼을 실행할 때 수행할 액션입니다. 클릭하거나 선택 후 Enter를 누르면 실행합니다. sensitive가 없거나 None이면 활성 여부도, selected가 없거나 None이면 선택 여부도 이 액션으로 결정합니다.

alternate: 대체 방식으로 실행할 때의 액션입니다. 마우스 플랫폼에서는 오른쪽 클릭, 터치 플랫폼에서는 길게 누르기입니다.

hovered: 버튼이 포커스를 얻을 때 실행할 액션입니다.

unhovered: 버튼이 포커스를 잃을 때 실행할 액션입니다.

selected: 버튼의 선택 여부를 결정하는 표현식입니다. 상호작용마다 최소 한 번 평가합니다. 없거나 None이면 액션으로 결정합니다.

sensitive: 버튼의 활성 여부를 결정하는 표현식입니다. 상호작용마다 최소 한 번 평가합니다. 없거나 None이면 액션으로 결정합니다.

keysym: 누르면 이 버튼의 액션을 실행할 키보드 키를 나타내는 키심 문자열입니다.

alternate_keysym: 누르면 이 버튼의 대체 액션을 실행할 키보드 키를 나타내는 키심 문자열입니다.

다음도 받습니다.

자식 하나를 받습니다. 0개나 2개 이상이면 암시적으로 fixed에 넣고 그 fixed를 버튼에 추가합니다.

Dismiss

dismiss 문은 다른 디스플레이어블에 포커스가 없을 때 포커스를 얻고, 실행하면 액션을 수행하는 특수한 디스플레이어블을 만듭니다. 이 점에서 say 문의 동작과 매우 비슷합니다.

드물게 사용하며, 주로 팝업처럼 모달 프레임 바깥을 클릭하면 닫히게 하는 용도입니다.

다음 속성을 받습니다.

action: dismiss를 실행할 때 수행할 액션입니다. 필수 속성입니다.

keysym: 누르면 dismiss의 액션을 실행하는 키를 나타내는 키심 문자열입니다. 기본 "dismiss" 키심을 대체합니다.

modal: 기본적으로 모달이므로 뒤쪽 디스플레이어블이 이벤트를 처리하지 못하게 합니다.

다음도 받습니다.

공통 속성
hover_sound와 activate_sound 스타일 속성.

dismiss 사용 예는 다음과 같습니다.

screen dismiss_test():

    dismiss action Return()

    frame:
        modal True

        align (.5, .3)
        padding (20, 20)

        has vbox

        text "매우 중요한 안내입니다.":
            xalign 0.5
            textalign 0.5

        # Dismiss can be confusing on its own, so we'll add a button as well.
        textbutton "닫기":
            xalign 0.5
            action Return()

nearrect와 함께 사용하는 방법도 참고하세요.

Fixed

자식을 추가할 수 있는 영역을 만듭니다. 기본적으로 사용 가능한 영역 전체를 채우지만 xmaximum과 ymaximum으로 바꿀 수 있습니다.

자식은 각자의 위치 스타일 속성에 따라 배치합니다. 적절하게 배치하지 않으면 겹칠 수 있습니다.

fixed 문은 매개변수 없이 다음 속성 그룹을 받습니다.

개수 제한 없이 자식을 받아 fixed에 추가합니다.

명시적으로 fixed를 만들 필요가 없는 경우가 많습니다. 각 스크린 자체가 fixed 안에 있으며, 많은 스크린 언어 문도 자식이 둘 이상이면 자동으로 fixed를 만듭니다.

screen ask_are_you_sure:
    fixed:
         text "계속하시겠습니까?" xalign 0.5 yalign 0.3
         textbutton "예" xalign 0.33 yalign 0.5 action Return(True)
         textbutton "아니요" xalign 0.66 yalign 0.5 action Return(False)

Frame

프레임은 버튼, 바, 텍스트 같은 사용자 인터페이스 요소를 표시하기 위한 배경이 있는 창입니다. 다음 속성 그룹을 받습니다.

자식 하나를 받습니다. 0개나 2개 이상이면 이를 담을 fixed를 만듭니다.

screen test_frame():
    frame:
        xpadding 10
        ypadding 10
        xalign 0.5
        yalign 0.5

        vbox:
            text "화면"
            null height 10
            textbutton "전체 화면" action Preference("display", "fullscreen")
            textbutton "창 모드" action Preference("display", "window")

Grid

자식을 격자로 표시합니다. 각 자식에게 가장 큰 자식의 크기와 같은 영역을 제공합니다.

두 매개변수를 받습니다. 첫 번째는 열 수, 두 번째는 행 수입니다. 격자가 가득 차지 않으면 남는 셀을 null로 채웁니다.

자식 배치에 관한 속성은 다음과 같습니다.

transpose: 기본값인 False이면 행부터, True이면 열부터 채웁니다.

right_to_left: True이면 기본 좌우 방향 대신 오른쪽에서 왼쪽으로 채웁니다.

bottom_to_top: True이면 기본 위아래 방향 대신 아래에서 위로 채웁니다.

다음도 받습니다.

반드시 (columns * rows)개의 자식을 지정해야 합니다. 개수가 다르면 오류입니다.

screen grid_test:
     grid 2 3:
         text "왼쪽 위"
         text "오른쪽 위"

         text "왼쪽 가운데"
         text "오른쪽 가운데"

         text "왼쪽 아래"
         text "오른쪽 아래"

Hbox

보이지 않는 가로 박스 안에 자식을 나란히 표시합니다. 매개변수 없이 다음 속성 그룹을 받습니다.

UI 디스플레이어블 자식이 박스에 추가됩니다.

screen hbox_text():
    hbox:
         text "왼쪽"
         text "오른쪽"

Imagebutton

마우스를 올리면 상태가 바뀌는 이미지 버튼을 만듭니다. 매개변수 없이 다음 속성을 받습니다.

auto

버튼에 사용할 이미지를 자동 정의합니다. %s가 포함된 문자열이어야 합니다. 이미지 속성이 생략되면 %s를 해당 속성 이름으로 바꿔 기본값으로 사용합니다.

예를 들어 auto가 "button_%s.png"이고 idle을 생략하면 기본값은 "button_idle.png"입니다. auto가 "button %s"이면 button idle 이미지를 사용합니다.

auto의 동작은 config.imagemap_auto_function으로 사용자 지정할 수 있습니다.

insensitive: 버튼이 비활성일 때의 이미지입니다.

idle: 포커스가 없을 때의 이미지입니다.

hover: 포커스가 있을 때의 이미지입니다.

selected_idle: 선택되었고 idle 상태일 때의 이미지입니다.

selected_hover: 선택되었고 hover 상태일 때의 이미지입니다.

action: 버튼을 실행할 때 수행할 액션입니다. sensitive가 없거나 None이면 활성 여부도, selected가 없거나 None이면 선택 여부도 결정합니다.

alternate: 대체 방식으로 실행할 때의 액션입니다. 마우스 플랫폼에서는 오른쪽 클릭, 터치 플랫폼에서는 길게 누르기입니다.

hovered: 버튼이 포커스를 얻을 때 실행할 액션입니다.

unhovered: 버튼이 포커스를 잃을 때 실행할 액션입니다.

selected: 선택 여부를 결정하는 표현식입니다. 상호작용마다 최소 한 번 평가합니다. 없거나 None이면 액션으로 결정합니다.

sensitive: 활성 여부를 결정하는 표현식입니다. 상호작용마다 최소 한 번 평가합니다. 없거나 None이면 액션으로 결정합니다.

keysym: 누르면 버튼의 액션을 실행할 키보드 키의 키심 문자열입니다.

alternate_keysym: 누르면 버튼의 대체 액션을 실행할 키보드 키의 키심 문자열입니다.

다음도 받습니다.

자식을 받지 않습니다.

screen gui_game_menu():
     vbox xalign 1.0 yalign 1.0:
          imagebutton auto "save_%s.png" action ShowMenu('save')
          imagebutton auto "prefs_%s.png" action ShowMenu('preferences')
          imagebutton auto "skip_%s.png" action Skip()
          imagebutton auto "afm_%s.png" action Preference("auto-forward mode", "toggle")

Input

사용자가 텍스트를 입력하는 영역을 만듭니다. Return을 누르면 상호작용이 텍스트를 반환합니다. call screen으로 호출했다면 _return에 저장합니다.

지원 라이브러리의 제약 때문에 Android와 웹에서는 알파벳 문자만 입력할 수 있습니다.

input 문은 매개변수 없이 다음 속성을 받습니다.

value

입력에서 사용할 입력 값 객체입니다. InputValue는 기본값의 출처, 텍스트 변경과 Enter 입력 시 동작, 기본 편집 가능 여부를 결정합니다.

default, changed와 동시에 지정해서는 안 됩니다.

default: 기본 입력 텍스트입니다.

length: 입력 텍스트의 최대 길이입니다.

pixel_width: 최대 픽셀 너비입니다. 문자를 입력해 이 너비를 넘게 되면 해당 키 입력을 무시합니다.

allow: 입력 가능한 문자들을 담은 문자열입니다. 기본적으로 모두 허용합니다.

exclude: 입력할 수 없는 문자들을 담은 문자열입니다. 기본값은 "{}"입니다.

copypaste: True이면 복사와 붙여넣기를 허용합니다. 기본적으로 비활성화되어 있습니다.

prefix: 사용자 입력 앞에 붙이는 변경 불가능한 문자열입니다.

suffix: 사용자 입력 뒤에 붙이는 변경 불가능한 문자열입니다.

changed: 문자열이 바뀌면 사용자 입력을 받아 호출하는 Python 함수입니다.

mask: 지정하면 표시되는 각 문자를 대체할 문자열입니다. 비밀번호를 가릴 수 있습니다.

caret_blink: False가 아니면 기본 커서의 깜박임 주기입니다. config.input_caret_blink보다 우선합니다.

multiline: 참이면 키보드로 커서를 다음 줄로 이동할 수 있습니다. 기본 키는 Shift+Enter이며 config.keymap['input_next_line']으로 바꿀 수 있습니다.

action

None이 아니면 입력이 활성 상태일 때 Enter를 누르면 실행할 액션입니다. 입력 값을 반환하는 기본 동작을 대체합니다.

보통 입력을 변수에 저장하는 value와 함께 사용하여 액션이 그 값에 접근하게 합니다.

arrowkeys: 기본값인 True이면 화살표 키로 커서를 좌우 이동할 수 있습니다. False이면 화살표 키를 무시하여 포커스 변경 등 다른 용도로 사용할 수 있습니다.

다음도 받습니다.

자식을 받지 않습니다.

screen input_screen():
    window:
        has vbox

        text "이름을 입력해 주세요."
        input default "조지프 P. 블로 변호사"

Key

지정한 키 또는 리스트의 키 중 하나를 누르면 액션을 실행하는 키 연결을 만듭니다. 여기서 키는 넓은 의미로 조이스틱과 마우스 이벤트도 포함합니다.

연결할 키 문자열을 위치 매개변수 하나로 받습니다. 가능한 키심은 키맵 사용자 지정을 참고하세요. 두 속성을 받습니다.

action: 키를 누르면 실행할 액션입니다. 필수 속성입니다.

capture: 기본값인 참이면 이벤트를 점유해 다른 디스플레이어블이 처리하지 못합니다. 거짓이고 액션이 상호작용을 끝내지 않으면 다른 디스플레이어블도 처리합니다.

자식을 받지 않습니다.

screen keymap_screen():
    key "game_menu" action ShowMenu('save')
    key "p" action ShowMenu('preferences')
    key ["s", "w"] action Screenshot()

Label

label 스타일의 창을 만들고 그 안에 텍스트를 넣습니다. 프레임 안의 요소에 이름표를 붙이는 데 사용합니다.

이름표 텍스트를 위치 인수 하나로 받습니다. 다음 속성을 받습니다.

text_style: 버튼 텍스트에 사용할 스타일 이름입니다. 지정하지 않았고 style이 문자열이면 뒤에 "_text"를 붙인 이름을 기본 텍스트 스타일로 사용합니다.

text_-: text 접두사의 다른 속성은 접두사를 제거한 뒤 텍스트 디스플레이어블에 전달합니다.

다음도 받습니다.

자식을 받지 않습니다.

screen display_preference():
    frame:
        has vbox

        label "화면"
        textbutton "전체 화면" action Preference("display", "fullscreen")
        textbutton "창 모드" action Preference("display", "window")

Mousearea

마우스의 진입과 이탈에 반응하는 화면 영역입니다. 버튼과 달리 포커스를 받지 않으므로 안에 버튼을 둘 수 있습니다. mousearea는 매개변수 없이 다음 속성을 받습니다.

hovered: 마우스가 영역에 들어올 때 실행할 액션입니다.

unhovered: 마우스가 영역에서 나갈 때 실행할 액션입니다.

focus_mask: Displayable 또는 None인 focus_mask 스타일 속성입니다. 디스플레이어블이면 불투명 부분 위에 마우스가 있을 때만 hover 상태가 됩니다. 그 디스플레이어블 자체는 표시하지 않습니다.

다음도 받습니다.

자식을 받지 않습니다.

보통 크기와 위치를 제어하는 area 속성을 지정합니다. 크기를 제어하지 않으면 화면 전체를 차지하므로 활용도가 떨어집니다.

참고

Ren'Py 게임은 키보드와 조이스틱으로도 플레이할 수 있으므로 mousearea 기능을 다른 방법으로도 제공하는 것이 좋습니다.

screen button_overlay():
    mousearea:
        area (0, 0, 1.0, 100)
        hovered Show("buttons", transition=dissolve)
        unhovered Hide("buttons", transition=dissolve)

screen buttons():
    hbox:
        textbutton "저장" action ShowMenu("save")
        textbutton "설정" action ShowMenu("preferences")
        textbutton "건너뛰기" action Skip()
        textbutton "자동 진행" action Preference("auto-forward", "toggle")

label start:
    show screen button_overlay

Nearrect

nearrect는 자식 하나를 받아 사각형 근처에 배치합니다. 보통 CaptureFocus()로 캡처한 포커스 사각형을 사용합니다. 툴팁과 드롭다운/풀다운 메뉴에 사용할 수 있습니다.

다음 속성을 받습니다.

rect: 지정하면 아래 설명처럼 자식을 상대 배치할 (x, y, w, h) 사각형이어야 합니다.

focus

지정하면 문자열이어야 합니다. GetFocusRect()에 해당하는 기능에 전달해 사각형을 찾습니다. 해당 이름의 포커스 사각형이 있으면 자식을 렌더링합니다.

"tooltip"을 전달하면 툴팁을 표시하며 마지막으로 포커스를 받은 디스플레이어블의 위치를 사용합니다.

지정하면 rect보다 우선합니다.

preferred_side: "left", "top", "right", "bottom" 중 하나로 선호 위치를 지정합니다. 그쪽에 공간이 없으면 반대쪽을 사용합니다. 기본값은 "bottom"입니다.

prefer_top: 사용이 권장되지 않습니다. preferred_side "top"과 같습니다.

invert_offsets: True이고 선호 방향에 공간이 부족하면 반대편에 배치하므로 xoffset과 yoffset에 -1을 곱합니다. 기본값은 False입니다.

다음도 받습니다.

Nearrect는 사각형 안이 아닌 근처에 자식을 배치한다는 점에서 다른 레이아웃과 다릅니다. preferred_side가 "top" 또는 "bottom"이면 전체 가용 너비와 사각형 위아래 공간 중 큰 높이로 먼저 렌더링합니다. "left", "right"이면 너비와 높이를 바꾸어 적용합니다. 이후 각각 y 또는 x 위치를 다음처럼 계산합니다.

preferred_side 쪽에 자식이 들어가면 사각형에 바로 붙여 놓습니다.
그렇지 않고 preferred_side의 반대쪽에 들어가면 그쪽에 놓습니다.
양쪽 모두 들어가지 않으면 preferred_side 쪽에 바로 붙여 놓습니다.

x 위치는 자식의 xpos, xanchor 및 이를 설정하는 xalign 등의 속성으로 일반 규칙에 따라 계산합니다. 좌우 배치의 y 위치는 ypos, yanchor를 사용합니다. pos는 사각형의 해당 x 또는 y 좌표 기준이며, 실수이면 너비 또는 높이에 대한 비율입니다.

마지막에 xoffset과 yoffset을 일반적으로 적용합니다.

자식이 트랜스폼이면 show, hide 이벤트를 받습니다. 다만 위치는 즉시 바뀝니다. Nearrect는 스크린 최상위에 두고 위치와 트랜스폼을 자체가 아닌 자식에 적용할 때 가장 잘 작동합니다.

드롭다운 메뉴에 사용할 수 있습니다.

default difficulty = "쉬움"

screen select_difficulty():

    # This frame can be a very complex layout, if required.
    frame:
        align (.5, .3)
        padding (20, 20)

        has vbox

        # This is the button that is clicked to enable the dropdown
        textbutton "난이도: [difficulty]":

            # This action captures the focus rectangle, and in doing so,
            # displays the dropdown.
            action CaptureFocus("diff_drop")

        textbutton "완료":
            action Return()

    # All sorts of other screen elements could be here, but the nearrect needs
    # to be at the top level, and the last thing shown, apart from its child.

    # Only if the focus has been captured, display the dropdown.
    # You could also use showif instead of basic if
    if GetFocusRect("diff_drop"):

        # If the player clicks outside the frame, dismiss the dropdown.
        # The ClearFocus action dismisses this dropdown.
        dismiss action ClearFocus("diff_drop")

        # This positions the displayable near (usually under) the button above.
        nearrect:
            focus "diff_drop"

            # Finally, this frame contains the choices in the dropdown, with
            # each using ClearFocus to dismiss the dropdown.
            frame:
                modal True

                has vbox

                textbutton "쉬움" action [ SetVariable("difficulty", "쉬움"), ClearFocus("diff_drop") ]
                textbutton "보통" action [ SetVariable("difficulty", "보통"), ClearFocus("diff_drop") ]
                textbutton "어려움" action [ SetVariable("difficulty", "어려움"), ClearFocus("diff_drop") ]
                textbutton "악몽" action [ SetVariable("difficulty", "악몽"), ClearFocus("diff_drop") ]

드롭다운 스타일을 더 다듬으면 좋지만 여기서는 생략합니다.

Null

화면에 빈 영역을 넣어 요소 사이에 공간을 둘 수 있습니다. 매개변수 없이 다음 속성을 받습니다.

width: 빈 영역의 픽셀 단위 너비입니다.

height: 빈 영역의 픽셀 단위 높이입니다.

다음도 받습니다.

자식을 받지 않습니다.

screen text_box():
    vbox:
         text "제목입니다."
         null height 20
         text "본문입니다."

Side

격자의 모서리나 가운데에 디스플레이어블을 배치합니다. 자식 위치를 공백으로 구분한 문자열 하나를 매개변수로 받습니다. 각 요소는 다음 중 하나여야 합니다.

'c', 't', 'b', 'l', 'r', 'tl', 'tr', 'bl', 'br'

'c'는 가운데, 't'는 위쪽, 'tl'은 왼쪽 위, 'br'은 오른쪽 아래이며 나머지도 같은 방식입니다.

다음 속성을 받습니다.

spacing: 격자 행과 열 사이의 간격입니다.

다음 속성 그룹을 받습니다.

렌더링은 가운데, 변, 모서리의 최소 크기를 찾는 세 단계로 시작합니다.

먼저 가운데에 (0, 0) 공간을 주어 최소 크기를 구합니다.
다음으로 각 변에 인접한 가운데 변의 최소 크기와 나머지 방향의 0을 제공합니다. 't', 'b'에는 (center_min_width, 0), 'l', 'r'에는 (0, center_min_height)를 줍니다.
마지막으로 모서리에는 인접한 변의 최소 크기를 제공합니다. 예를 들어 'tl'에는 (left_min_width, top_min_height)를 줍니다.

어떤 디스플레이어블도 제공된 크기보다 커질 수 있습니다. 알맞은 크기를 보장하려면 모서리나 변에 xminimum, yminimum으로 최소 크기를 지정해야 할 수 있습니다.

크기를 계산한 뒤 각 행과 열이 가장 큰 자식을 담을 수 있는 격자를 만듭니다. xfill이나 yfill을 지정하면 Side가 가용 영역을 채우도록 가운데에 추가 공간을 줍니다.

이후 지정된 순서로 자식을 렌더링하여 일반 배치 알고리즘으로 해당 셀에 놓습니다. 자식은 위치 목록의 항목에 대응하므로 개수가 같아야 합니다.

screen side_test():
     side "c tl br":
          text "가운데"
          text "왼쪽 위"
          text "오른쪽 아래"

텍스트

텍스트를 표시합니다. 표시할 텍스트 하나를 매개변수로 받고 다음 속성 그룹도 받습니다.

자식을 받지 않습니다.

screen hello_world():
    text "안녕, 세상아." size 40

Textbutton

텍스트 문구가 있는 버튼을 만듭니다. 버튼에 넣을 텍스트 하나를 매개변수로 받으며 다음 속성을 받습니다.

action: 버튼을 실행할 때 수행할 액션입니다. sensitive가 없거나 None이면 활성 여부도, selected가 없거나 None이면 선택 여부도 결정합니다.

alternate: 대체 방식으로 실행할 때의 액션입니다. 마우스 플랫폼에서는 오른쪽 클릭, 터치 플랫폼에서는 길게 누르기입니다.

hovered: 포커스를 얻을 때 실행할 액션입니다.

unhovered: 포커스를 잃을 때 실행할 액션입니다.

selected: 선택 여부를 결정하는 표현식입니다. 상호작용마다 최소 한 번 평가합니다. 없거나 None이면 액션으로 결정합니다.

sensitive: 활성 여부를 결정하는 표현식입니다. 상호작용마다 최소 한 번 평가합니다. 없거나 None이면 액션으로 결정합니다.

keysym: 누르면 버튼의 액션을 실행할 키보드 키의 키심 문자열입니다.

alternate_keysym: 누르면 버튼의 대체 액션을 실행할 키보드 키의 키심 문자열입니다.

text_style: 버튼 텍스트의 스타일 이름입니다. 지정하지 않았고 style이 문자열이면 "_text"를 붙여 기본 텍스트 스타일로 사용합니다.

text_-: text 접두사의 다른 속성은 접두사를 제거한 뒤 텍스트 디스플레이어블에 전달합니다.

다음도 받습니다.

자식을 받지 않습니다.

screen textbutton_screen():
    vbox:
        textbutton "와인" action Jump("wine")
        textbutton "여자" action Jump("women")
        textbutton "노래" action Jump("song")

Timer

시간이 지나면 액션을 실행하는 타이머를 만듭니다. 만료 시간을 초 단위 위치 매개변수 하나로 받고 다음 속성을 받습니다.

action: 시간이 지나면 실행할 액션입니다. 필수 속성입니다.

repeat: True이면 만료 후 반복합니다.

modal: True이면 모달 스크린에 가려졌을 때 실행하지 않습니다. 거짓이거나 지정하지 않으면 가려져 있어도 실행합니다.

자식을 받지 않습니다.

screen timer_test():
    vbox:
         textbutton "예." action Jump("yes")
         textbutton "아니요." action Jump("no")

    timer 3.0 action Jump("too_slow")

Transform

자식에 트랜스폼을 적용합니다. 매개변수 없이 다음 속성 그룹을 받습니다.

자식 하나를 받아야 합니다.

Vbar

bar의 세로 버전입니다. 속성은 bar와 같습니다.

screen volume_controls():
     frame:
         has hbox

         vbar value Preference("sound volume")
         vbar value Preference("music volume")
         vbar value Preference("voice volume")

Vbox

보이지 않는 세로 박스에 자식을 위아래로 표시합니다. 매개변수 없이 다음 속성 그룹을 받습니다.

UI 디스플레이어블 자식이 박스에 추가됩니다.

screen vbox_test():
    vbox:
         text "위쪽."
         text "아래쪽."

Viewport

끌기, 마우스 휠, 스크롤바로 스크롤하는 화면 영역입니다. 화면보다 큰 요소의 일부를 표시할 수 있습니다. 다음 속성을 받습니다.

child_size: 자식에게 렌더링용으로 제공할 크기인 (xsize, ysize) 튜플입니다. 자식이 스스로 크기를 계산할 수 있으면 보통 생략합니다. 어느 요소든 None이면 자식의 해당 크기를 사용합니다.

mousewheel

다음 중 하나여야 합니다.

False: 마우스 휠을 무시합니다. 기본값입니다.
True: 세로로 스크롤합니다.
"horizontal": 가로로 스크롤합니다.
"change": 실제로 움직일 수 있을 때만 세로로 스크롤합니다. 그렇지 않으면 휠 이벤트를 나머지 인터페이스에 전달합니다. 예를 들어 change를 지정하고 뷰포트 앞에 key "viewport_wheeldown" action Return()을 놓으면 맨 아래를 지나 스크롤할 때 스크린이 반환합니다.
"horizontal-change": 가로 스크롤과 change 모드를 결합합니다.

draggable: True이면 마우스로 끌어 스크롤할 수 있습니다. 변형을 지정할 수도 있으며, 해당 변형이 적용될 때 끌 수 있습니다. 예: draggable "touch".

edgescroll

마우스가 뷰포트 가장자리에 도달할 때의 스크롤을 제어합니다. None이 아니면 두 요소 또는 세 요소의 튜플이어야 합니다.

첫 요소는 가장자리에서 스크롤이 시작되는 거리입니다. 단위는 픽셀입니다.
두 번째는 최대 스크롤 속도입니다. 단위는 초당 픽셀입니다.
선택적인 세 번째 요소는 포인터와 가장자리 사이 거리에 따라 속도를 조정하는 함수입니다. -1.0부터 1.0 사이 숫자를 받아 같은 범위의 숫자를 반환해야 합니다. 기본 함수는 입력을 그대로 반환해 비례 스크롤을 구현합니다. 입력 부호에 따라 -1.0 또는 1.0만 반환하면 일정 속도 스크롤이 됩니다.

xadjustment: x축에 사용할 ui.adjustment()입니다. 생략하면 새 조정 객체를 만듭니다.

yadjustment: y축에 사용할 ui.adjustment()입니다. 생략하면 새 조정 객체를 만듭니다.

xinitial: 초기 가로 오프셋입니다. 정수이면 픽셀 수, 실수이면 가능한 오프셋의 비율입니다.

yinitial: 초기 세로 오프셋입니다. 정수이면 픽셀 수, 실수이면 가능한 오프셋의 비율입니다.

scrollbars

None이 아니면 스크롤바를 함께 추가합니다. side 레이아웃을 만들어 가운데에 뷰포트를 놓습니다. scrollbars가 "horizontal"이면 아래에 가로 스크롤바, scrollbars가 "vertical"이면 오른쪽에 세로 스크롤바, scrollbars가 "both"이면 둘 다 만듭니다.

scrollbars가 None이 아니면 viewport는 접두사가 있는 속성을 받습니다.

viewport_ 속성은 뷰포트로 전달합니다.
side_ 속성은 side로 전달합니다.
scrollbar_ 속성은 가로 스크롤바가 있으면 전달합니다.
vscrollbar_ 속성은 세로 스크롤바가 있으면 전달합니다.

접두사가 없는 속성도 받습니다. 위치 스타일 속성은 side로, 나머지는 뷰포트로 전달합니다.

arrowkeys: 참이면 방향키로 스크롤할 수 있습니다. 일반적인 포커스 변경보다 우선하지만, 뷰포트의 한계에 도달하면 방향키가 포커스를 바꿉니다.

pagekeys: 참이면 Page Up과 Page Down으로 위아래 스크롤할 수 있습니다. 기본 롤백 및 롤포워드 기능은 비활성화됩니다.

다음 스타일 속성 그룹도 받습니다.

자식 하나를 받습니다. 0개나 2개 이상이면 이를 담을 fixed를 만듭니다.

스크롤 가능하게 하려면 ID를 지정한 뒤 그 ID로 XScrollValue()와 YScrollValue()를 사용하는 것이 보통 가장 좋습니다.

screen viewport_example():
    side "c b r":
         area (100, 100, 600, 400)

         viewport id "vp":
             draggable True

             add "washington.jpg"

         bar value XScrollValue("vp")
         vbar value YScrollValue("vp")

Vpgrid

vpgrid는 뷰포트와 격자를 하나로 결합합니다. 격자처럼 여러 자식을 받으며, 뷰포트 안에서 표시되는 자식만 렌더링하도록 최적화되어 있습니다.

모든 자식의 크기가 같다고 가정하고 첫 자식에서 크기를 가져옵니다. 표시가 잘못된 것 같으면 모든 자식의 크기가 같은지 확인하세요.

cols와 rows 중 하나 이상을 지정해야 합니다. 하나를 생략하거나 None이면 크기, 간격, 자식 수로 나머지를 자동 결정합니다. 행이나 열이 덜 채워지면 null로 남은 공간을 채웁니다.

다음 속성을 받습니다.

cols: 격자의 열 수입니다.

rows: 격자의 행 수입니다.

transpose: 참이면 열부터 채웁니다. 기본값은 cols와 rows에 따라 다릅니다. cols를 지정하면 열부터, 그렇지 않으면 행부터 채웁니다.

viewport의 모든 속성과 다음 스타일 속성 그룹도 받습니다.

scrollbar를 지정하면 뷰포트와 같은 방식으로 접두사 속성을 전달합니다. viewport_ 속성은 vpgrid 자체에 전달합니다.

screen vpgrid_test():

    vpgrid:

        cols 2
        spacing 5
        draggable True
        mousewheel True

        scrollbars "vertical"

        # Since we have scrollbars, this positions the side, rather than
        # the vpgrid.
        xalign 0.5

        for i in range(1, 101):

            textbutton "버튼 [i]":
                xysize (200, 50)
                action Return(i)

Window

게임 내 대사를 표시하기 위한 배경이 있는 창입니다. 다음 속성 그룹을 받습니다.

자식 하나를 받습니다. 0개나 2개 이상이면 이를 담을 fixed를 만듭니다.

screen say(who, what):
    window id "window"
        vbox:
            spacing 10

            text who id "who"
            text what id "what"

이미지맵 문

시각적으로 생각하는 사람에게 특히 편리한 스크린 제작 방식은 이미지맵입니다. imagemap 문으로 최대 여섯 이미지를 지정하고, hotspot과 hotbar로 이미지에서 사각형 영역을 나누어 액션과 값을 적용합니다.

다음은 이미지맵을 사용하는 환경설정 스크린 예제입니다.

screen preferences():

    tag menu
    use navigation

    imagemap:
        auto "gui_set/gui_prefs_%s.png"

        hotspot (740, 232, 75, 73) action Preference("display", "fullscreen") alt _("전체 화면으로 표시")
        hotspot (832, 232, 75, 73) action Preference("display", "window") alt _("창 모드로 표시")
        hotspot (1074, 232, 75, 73) action Preference("transitions", "all") alt _("모든 화면 전환 사용")
        hotspot (1166, 232, 75, 73) action  Preference("transitions", "none") alt _("화면 전환 사용 안 함")

        hotbar (736, 415, 161, 20) value Preference("music volume") alt _("음악 음량")
        hotbar (1070, 415, 161, 20) value Preference("sound volume") alt _("효과음 음량")
        hotbar (667, 535, 161, 20) value Preference("voice volume") alt _("음성 음량")
        hotbar (1001, 535, 161, 20) value Preference("text speed") alt _("대사 표시 속도")

Imagemap

이미지맵을 지정합니다. 매개변수 없이 다음 속성을 받습니다.

auto

이미지맵의 이미지를 자동 정의합니다. %s를 포함하는 문자열이어야 합니다. 이미지 속성을 생략하면 %s를 그 속성 이름으로 바꿔 기본값으로 사용합니다.

예를 들어 auto가 "imagemap_%s.png"이고 idle을 생략하면 "imagemap_idle.png"가 기본값입니다. auto가 "imagemap %s"이면 imagemap idle 이미지를 사용합니다.

auto의 동작은 config.imagemap_auto_function으로 사용자 지정할 수 있습니다.

ground: hotspot이나 hotbar에 속하지 않는 부분의 이미지입니다.

insensitive: hotspot이나 hotbar가 비활성일 때의 이미지입니다.

idle: hotspot이 선택되지 않고 포커스가 없을 때, 그리고 포커스 없는 hotbar의 빈 부분에 사용할 이미지입니다.

hover: hotspot이 선택되지 않고 포커스가 있을 때, 그리고 포커스 있는 hotbar의 빈 부분에 사용할 이미지입니다.

selected_idle: hotspot이 선택되었고 포커스가 없을 때, 그리고 포커스 없는 hotbar의 채워진 부분에 사용할 이미지입니다.

selected_hover: hotspot이 선택되었고 포커스가 있을 때, 그리고 포커스 있는 hotbar의 채워진 부분에 사용할 이미지입니다.

alpha: 기본값인 참이면 hover 이미지의 불투명 부분에 마우스가 있을 때만 포커스를 받습니다. 거짓이면 사각형 경계 안 어디서든 포커스를 받습니다.

cache: 기본값인 참이면 디스크 공간을 조금 더 사용해 hotspot 데이터를 캐시하여 성능을 높입니다.

다음 속성 그룹을 받습니다.

이미지맵은 fixed를 만들므로 hotspot과 hotbar 외의 자식도 추가할 수 있습니다.

Hotspot

이미지맵 일부로 이루어진 버튼입니다. 버튼 영역을 나타내는 (x, y, width, height) 튜플 하나를 매개변수로 받으며 다음 속성도 받습니다.

action: 실행할 액션입니다. 버튼의 활성 및 선택 여부도 결정합니다.

alternate: 대체 방식으로 실행할 때의 액션입니다. 마우스 플랫폼에서는 오른쪽 클릭, 터치 플랫폼에서는 길게 누르기입니다.

hovered: 포커스를 얻을 때 실행할 액션입니다.

unhovered: 포커스를 잃을 때 실행할 액션입니다.

selected: 선택 여부를 결정하는 표현식입니다. 상호작용마다 최소 한 번 평가합니다. 없거나 None이면 액션으로 결정합니다.

sensitive: 활성 여부를 결정하는 표현식입니다. 상호작용마다 최소 한 번 평가합니다. 없거나 None이면 액션으로 결정합니다.

keysym: 누르면 버튼의 액션을 실행할 키보드 키의 키심 문자열입니다.

alternate_keysym: 누르면 버튼의 대체 액션을 실행할 키보드 키의 키심 문자열입니다.

다음도 받습니다.

hotspot은 fixed를 만들어 자식을 추가할 수 있습니다. fixed의 크기가 hotspot과 같으므로 자식은 hotspot 기준으로 배치됩니다.

자체 음성 출력이 작동하도록 alt 스타일 속성을 지정해야 합니다.

Hotbar

이미지맵 일부로 이루어진 바입니다. 영역을 나타내는 (x, y, width, height) 튜플 하나를 매개변수로 받으며 다음 속성도 받습니다.

value: 현재 값입니다. 바 값 객체나 숫자입니다.

range: 최댓값입니다. value가 숫자이면 필수입니다.

adjustment: 이 바가 조절하는 ui.adjustment() 객체입니다.

value와 adjustment 중 하나는 필수입니다. 다음도 받습니다.

자식을 받지 않습니다.

자체 음성 출력이 작동하도록 alt 스타일 속성을 지정해야 합니다.

add 문

add 문은 이미 존재하는 디스플레이어블을 스크린에 추가한다는 점이 특별합니다. 따라서 사용자 인터페이스 문의 공통 속성을 받지 않습니다.

Add

이미지나 다른 디스플레이어블을 추가합니다. 선택적으로 트랜스폼 속성을 받습니다. 하나 이상 지정하면 이미지를 감쌀 Transform을 만들어 속성을 전달합니다.

디스플레이어블이 None이면 아무것도 추가하지 않습니다.

자식을 받지 않습니다.

screen add_test():
    add "logo.png" xalign 1.0 yalign 0.0

고급 디스플레이어블

흔히 쓰는 문 외에도 고급 디스플레이어블에 대응하는 문이 있습니다. 대응 방식은 단순합니다. 디스플레이어블의 위치 매개변수는 문의 위치 매개변수, 키워드 인수와 관련 스타일 속성은 스크린 언어 속성이 됩니다.

고급 디스플레이어블 문은 다음과 같습니다.

Areapicker

개발 도구용으로, 사용자가 화면의 사각형 영역을 선택하게 합니다. 다음 속성을 받습니다.

cols: None이 아니라면 화면을 이 열 수의 격자로 나눕니다. 기본값은 None입니다.

rows: None이 아니라면 화면을 이 행 수의 격자로 나눕니다. 기본값은 None입니다.

position: None이 아니라면 처음 클릭한 위치를 격자에 맞춘 x, y 좌표로 호출할 함수입니다. 기본값은 None입니다.

changed: 선택 영역을 바꿀 때마다 사각형 (x, y, width, height) 튜플을 받아 호출됩니다.

finished: 선택을 끝내면 사각형 (x, y, width, height) 튜플을 받아 호출됩니다.

persist: 참이면 선택 완료 후 선택 영역에 자식을 표시합니다. 기본값인 거짓이면 완료 후 숨깁니다.

다음 속성 그룹을 받습니다.

공통 속성

자식 하나를 받으며 선택 영역에 표시합니다.

Drag

화면에서 끌 수 있는 Drag를 만듭니다. 스크린 언어가 제공하는 d를 제외한 클래스의 모든 속성을 받습니다.

다음 속성도 받습니다.

공통 속성
hover_sound와 activate_sound 스타일 속성.
focus_mask 스타일 속성.

자식 하나를 받습니다. child 스타일 속성으로 자식과 포커스 상태별 변형을 지정할 수도 있습니다.

Draggroup

DragGroup을 만듭니다. DragGroup과 같은 속성 및 다음 속성을 받습니다.

공통 속성

Drag 0개 이상을 자식으로 받습니다. Drag가 아닌 자식도 받을 수 있으며, 이 경우 fixed처럼 작동합니다.

has 문

자식 하나만 받는 문에서 fixed 대신 사용할 컨테이너를 지정합니다. 자식 하나를 받는 문 안에서만 사용할 수 있습니다. has 뒤 같은 줄에는 여러 자식을 받는 컨테이너 디스플레이어블을 만드는 문이 와야 합니다.

has 문은 자신이 포함된 블록의 파싱 방식을 바꿉니다. 블록의 자식들은 부모 대신 컨테이너에 추가됩니다. has 뒤에는 부모의 키워드 인수를 지정할 수 없습니다. 한 블록에 여러 has 문을 쓸 수 있습니다.

다음 문의 자식으로 지정할 수 있습니다.

button
frame
window

다음 문을 컨테이너로 지정할 수 있습니다.

fixed
grid
hbox
side
vbox

screen volume_controls():
     frame:
         has vbox

         bar value Preference("sound volume")
         bar value Preference("music volume")
         bar value Preference("voice volume")

제어문

조건부 실행, 반복, 다른 스크린 포함, 이벤트 발생 시 액션 실행, 임의 Python 실행을 위한 제어문이 있습니다.

Default

default는 스크린 인수로 전달되지 않았고 use로 호출한 스크린에서 상속되지 않은 변수에 기본값을 설정합니다.

screen scheduler():
    default club = None
    vbox:
         text "무엇을 하고 싶으세요?"
         textbutton "미술 동아리" action SetScreenVariable("club", "art")
         textbutton "글쓰기 동아리" action SetScreenVariable("club", "writing")

         if club:
             textbutton "선택" action Return(club)

For

for는 Python의 for와 비슷하지만 else 절을 지원하지 않습니다. continue와 break는 지원합니다. 변수뿐 아니라 중첩 가능한 튜플 패턴에도 대입할 수 있습니다.

$ numerals = [ 'I', 'II', 'III', 'IV', 'V' ]

screen five_buttons():
    vbox:
        for i, numeral in enumerate(numerals):
            textbutton numeral action Return(i + 1)

for 문은 index 절을 받습니다.

screen five_buttons():
    vbox:
        for i, numeral index numeral in enumerate(numerals):
            textbutton numeral action Return(i + 1)

index를 지정하면 리스트의 각 행에서 고유하고 해시 및 비교가 가능한 값을 반환하는 표현식이어야 합니다. Ren'Py는 이 값으로 트랜스폼과 상태를 올바른 반복 항목에 연결합니다. 반복하는 리스트에 요소를 추가하거나 제거할 때 이상한 동작이 보이면 사용해 보세요.

If

스크린 언어의 if는 Python/Ren'Py의 if와 같습니다. if, elif, else 절을 지원합니다.

screen skipping_indicator():
    if renpy.is_skipping():
         text "건너뛰는 중입니다."
    else:
         text "건너뛰지 않고 있습니다."

On

on은 이벤트가 발생하면 액션을 실행합니다. 이벤트 이름 문자열 하나를 받으며 다음 중 하나여야 합니다.

"show"
스크린이 표시될 때 발생합니다. 같은 태그의 스크린이 이미 있으면 대신 "replace"가 발생합니다.
"hide"
스크린이 숨겨질 때 발생합니다. 같은 태그의 다른 스크린으로 대체되면 대신 "replaced"가 발생합니다.
"replace"
같은 태그의 스크린을 대체하며 표시될 때 발생합니다.
"replaced"
같은 태그의 다른 스크린으로 대체될 때 발생합니다.

그다음 이벤트 발생 시 실행할 액션을 action 속성으로 받습니다.

screen preferences():
    frame:
        has hbox

        text "화면"
        textbutton "전체 화면" action Preferences("display", "fullscreen")
        textbutton "창 모드" action Preferences("display", "window")

    on "show" action Show("navigation")
    on "hide" action Hide("navigation")

Use

use로 다른 스크린을 포함할 수 있습니다. 사용할 스크린 이름을 받으며, 선택적으로 괄호 안의 인수 목록이 뒤따릅니다.

사용되는 스크린에 괄호가 없으면 현재 스크린의 스코프를 읽고 쓸 수 있고, use로 전달한 키워드 인수로 갱신합니다. 괄호가 있으면 매개변수에 인수를 대입한 결과로 스코프를 초기화합니다.

screen file_slot(slot):
    button:
        action FileAction(slot)

        has hbox

        add FileScreenshot(slot)
        vbox:
            text FileTime(slot, empty="빈 슬롯.")
            text FileSaveName(slot)


 screen save():
     grid 2 5:
         for i in range(1, 11):
              use file_slot(i)

id와 as 절을 받을 수 있습니다. 매개변수 목록이 있으면 그 뒤에 놓아야 하며, 블록이 아닌 첫 줄에 있어야 합니다.

id는 같은 태그의 두 스크린이 같은 스크린을 use할 때만 유용합니다. 한 스크린이 다른 스크린을 대체하면 사용되는 스크린의 상태를 이전 것에서 새것으로 옮깁니다.

transform t1():
    xpos 150
    linear 1.0 xpos 0

screen common():
    text "테스트" at t1

screen s1():
    tag s
    use common id "common"
    text "s1" ypos 100

screen s2():
    tag s
    use common id "common"
    text "s2" ypos 100

label start:
    show screen s1
    pause
    show screen s2
    pause
    return

as 뒤에는 변수 이름이 와야 합니다. 사용되는 스크린이 끝나면 그 안의 main 변수에 연결된 값을 지정한 변수에 대입합니다. 예를 들면 다음과 같습니다.

screen child():
    add MyCreatorDefinedDisplayable() as main

screen parent():
    use child as mycdd

    # Here, the MyCreatorDefinedDisplaybale instance is assigned to cdd.

스크린 이름 대신 expression과 이름을 반환하는 표현식을 지정할 수 있습니다. 매개변수가 필요하면 pass로 표현식과 구분해야 합니다.

screen ed(num):
    text "에드"
    text "함장"

screen kelly(num):
    text "켈리"
    text "부함장"

screen bortus(num):
    text "보터스"
    text "제2부함장"

screen crew():
    hbox:
        for i, member in enumerate(party):
            vbox:
                use expression member.screen pass (i + 1)

use와 transclude

use는 스크린 언어 문으로 이루어진 블록도 받을 수 있습니다. 이때 사용되는 스크린은 transclude를 포함할 수 있습니다. transclude는 use 블록의 문들로 대체됩니다.

이를 통해 재사용 가능한 레이아웃을 정의할 수 있습니다. 예를 들어 다음 스크린은

screen movable_frame(pos):
    drag:
        pos pos

        frame:
            background Frame("movable_frame.png", 10, 10)
            top_padding 20

            transclude

다른 구성 요소를 감싸는 재사용 요소입니다. 사용 예는 다음과 같습니다.

screen test:
    use movable_frame((0, 0)):
        text "이 창을 드래그할 수 있어요."

    use movable_frame((0, 100)):
        vbox:
            text "이 창도 드래그할 수 있어요."
            textbutton "알겠어요!" action Return(True)

use와 transclude는 제작자 정의 스크린 언어 문의 기반입니다.

Python

한 줄 및 여러 줄 Python 문으로 코드를 실행할 수 있습니다. Python은 스크린 스코프에서 실행됩니다.

Python 코드는 스크린 밖에서 관찰할 수 있는 부수 효과를 일으켜서는 안 됩니다. Ren'Py는 필요에 따라 스크린을 여러 번 실행하며, 처음 표시하기 전 이미지 예측 과정에서도 실행합니다. 따라서 부수 효과가 있으면 예측할 수 없는 시점에 발생할 수 있습니다.

screen python_screen:
    python:
        test_name = "테스트 %d" % test_number

    text test_name

    $ test_label = "test_%d" % test_label

    textbutton "테스트 실행" action Jump(test_label)

showif 문

showif는 조건을 받아 참이면 자식을 표시하고 거짓이면 숨깁니다. 자식에 트랜스폼이 있으면 표시와 숨기기를 관리하는 ATL 이벤트를 전달해 애니메이션을 만들 수 있게 합니다.

showif는 표시와 숨기기를 관리하는 디스플레이어블로 자식을 감쌉니다.

여러 showif를 if처럼 showif/elif/else 구조로 묶을 수 있습니다. if와 달리 조건이 거짓이어도 Python을 포함한 모든 블록을 실행합니다. 숨길 자식도 만들어야 하기 때문입니다.

자식에게 세 이벤트를 전달합니다.

appear: 처음 스크린을 표시할 때 조건이 참이면 전달하여 자식을 즉시 표시합니다.
show: 조건이 거짓에서 참으로 바뀌면 전달합니다.
hide: 조건이 참에서 거짓으로 바뀌면 전달합니다.

앞의 조건이 하나라도 참이면 elif 조건은 항상 거짓으로 취급하고, else는 앞의 조건이 모두 거짓일 때만 참으로 취급합니다.

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

transform cd_transform:
    # This is run before appear, show, or hide.
    xalign 0.5 yalign 0.5 alpha 0.0

    on appear:
        alpha 1.0
    on show:
        zoom .75
        linear .25 zoom 1.0 alpha 1.0
    on hide:
        linear .25 zoom 1.25 alpha 0.0

screen countdown():
    default n = 3

    vbox:
        textbutton "3" action SetScreenVariable("n", 3)
        textbutton "2" action SetScreenVariable("n", 2)
        textbutton "1" action SetScreenVariable("n", 1)
        textbutton "0" action SetScreenVariable("n", 0)

    showif n == 3:
        text "셋" size 100 at cd_transform
    elif n == 2:
        text "둘" size 100 at cd_transform
    elif n == 1:
        text "하나" size 100 at cd_transform
    else:
        text "발사!" size 100 at cd_transform

label start:
    call screen countdown

스크린 관련 문

screen 문 외에도 스크린과 관련된 Ren'Py 스크립트 문이 세 개 있습니다.

Show Screen

show screen은 스크린을 표시합니다. 스크린 이름, 선택적인 절들, 스크린에 전달할 선택적인 Python 인수를 받습니다. renpy.show_screen()과 renpy.call_screen()에는 별도의 추가 키워드가 있습니다.

show screen은 다음 절을 받으며 일부는 show 문과 비슷합니다.

as

as는 이름을 받습니다. 생략하면 screen 문에서 연결한 태그, 그것도 없으면 스크린 이름을 사용합니다.

onlayer

표시할 레이어입니다.

zorder

표시할 zorder입니다. 생략하면 스크린에 연결된 값, 그것도 없으면 0입니다.

expression

expression을 지정하면 뒤의 표현식을 스크린 이름으로 평가합니다. 인수를 전달하려면 pass로 표현식과 구분합니다.

$ screen_name = "my_screen"
show screen expression screen_name
# Or if you need to pass some arguments
show screen expression screen_name pass ("Foo", message="Bar")

with

show 문의 with 절과 같은 방식으로 해석합니다.

show screen clock_screen with dissolve

nopredict

nopredict는 값을 받지 않으며 스크린 예측을 막습니다. 예측 중에는 스크린 인수를 평가하므로, 인수 평가가 예상치 못한 부수 효과를 일으키지 않게 해야 합니다.

경고

스크린 인수 평가가 부수 효과를 일으키면 게임이 예상치 못하게 작동할 수 있습니다.

이렇게 표시한 스크린은 명시적으로 숨길 때까지 유지되므로 오버레이로 사용할 수 있습니다.

show screen overlay_screen
show screen clock_screen(hour=11, minute=30)

if rare_case:
    show rare_screen nopredict

Hide Screen

hide screen은 표시 중인 스크린을 숨깁니다. 스크린 태그를 받아 먼저 지정한 레이어에서 같은 태그를 찾습니다. onlayer를 참고하세요. 없으면 표시 태그와 관계없이 같은 이름의 스크린을 해당 레이어에서 찾습니다. 그것도 없으면 아무 일도 하지 않습니다.

show screen A
show screen B as A # B replaces A (which hides it)
hide screen A # hides B, tagged as A

show screen A as B
show screen B as C

hide screen B
# hides the A screen, shown as B
# the B screen, shown as C, stays shown

hide screen B
# hides the B screen

onlayer도 받으며 기본값은 screens 레이어입니다.

with 절은 show 문의 with 절과 같은 방식으로 해석합니다.

show screen처럼 hide screen도 expression을 받아 임의의 표현식을 스크린 이름으로 사용할 수 있습니다.

hide screen rare_screen
hide screen clock_screen with dissolve
hide screen overlay_screen
$ screen_name = "some_screen"
hide screen expression screen_name

Call Screen

call screen은 스크린을 표시하고 현재 상호작용이 끝나면 다시 숨깁니다. 스크린이 값을 반환하면 전역 _return에 저장합니다.

이미지맵 표시에 사용할 수 있습니다. Return()으로 _return에 값을 넣거나 Jump()로 레이블에 이동할 수 있습니다.

여러 선택적 절을 받으며 대부분 show screen과 비슷합니다.

as

as는 이름을 받습니다. 생략하면 screen 문에서 연결한 태그, 그것도 없으면 스크린 이름을 사용합니다.

onlayer

표시할 레이어입니다.

zorder

표시할 zorder입니다. 생략하면 스크린에 연결된 값, 그것도 없으면 0입니다.

nopredict

스크린 예측을 막습니다. 예측 중에는 스크린 인수를 평가하므로, 인수 평가가 예상치 못한 부수 효과를 일으키지 않게 해야 합니다.

경고

스크린 인수 평가가 부수 효과를 일으키면 게임이 예상치 못하게 작동할 수 있습니다.

expression

show screen처럼 call screen도 expression으로 임의의 표현식을 스크린 이름으로 사용할 수 있습니다. pass로 인수도 전달할 수 있습니다.

with

call screen의 with 절은 스크린을 표시할 때 화면 전환을 실행합니다.

표시 전에 with None을 실행하지 않으므로 앞의 모든 show와 hide 문이 함께 반영됩니다. with None이 필요하면 직접 추가하세요.

스크린 호출은 상호작용이며 암시적인 with None을 발생시킵니다. 따라서 call screen 뒤의 with 문으로는 이미 사라진 스크린에 사라지는 전환을 적용할 수 없습니다. 아래 예처럼 특수 키워드 인수 _with_none=False를 전달하면 암시적 with None을 끌 수 있습니다.

[ With(dissolve), Return() ] 액션 리스트 등 다른 전환 실행 방식도 사용할 수 있습니다.

call screen my_imagemap

call screen my_screen(side_effect_function()) nopredict

# Shows the screen with dissolve
call screen my_other_screen with dissolve
# The screens instantly hides with None, then the pixellate transition executes
with pixellate

# Shows the screen with dissolve and hides it with pixellate.
call screen my_other_screen(_with_none=False) with dissolve
with pixellate

$ screen_name = "my_screen"
call screen expression screen_name pass (foo="bar")

스크린 변형

Ren'Py는 Windows, Mac, Linux PC 같은 마우스 중심 기기와 Android 스마트폰, 태블릿 같은 터치 중심 기기에서 실행됩니다. 스크린 변형은 여러 버전의 스크린을 제공해 현재 하드웨어에 가장 맞는 것을 사용하게 합니다.

config.variants의 순서대로 변형을 검색하고 존재하는 첫 번째를 사용합니다.

RENPY_VARIANT 환경 변수가 있으면 값을 공백으로 나눈 뒤 None을 추가해 config.variants를 초기화합니다. "medium tablet touch"나 "small phone touch"로 설정하면 Android용 스크린을 PC에서 테스트할 수 있습니다.

환경 변수가 없으면 다음 목록에서 현재 플랫폼에 해당하는 항목을 순서대로 골라 자동 구성합니다.

"steam_deck": Steam Deck이나 동등한 하드웨어에서 실행하면 참입니다.
"steam_big_picture": Steam Big Picture 모드에서 실행하면 참입니다.
"large": 비교적 작은 텍스트도 편하게 읽고 버튼도 쉽게 클릭할 수 있는 큰 화면입니다. 컴퓨터 화면에 사용합니다.
"medium": 조금 작은 텍스트는 읽을 수 있지만 편하게 누르려면 버튼을 키워야 할 수 있는 화면입니다. 태블릿에 사용합니다.
"small": 텍스트를 키워야 읽을 수 있는 화면입니다. 휴대폰과 TV에 사용합니다. TV는 물리적으로 커도 멀리 있어 읽기 어려운 경우가 많습니다.
"tablet": 화면 대각선이 6인치 이상인 터치 기기에 정의됩니다. 일반적으로 "tablet" 대신 "medium"을 사용해야 합니다.
"phone": 화면 대각선이 6인치 미만인 터치 기기에 정의됩니다. 작은 기기에서는 쉽게 선택할 만큼 버튼을 크게 해야 합니다. 일반적으로 "phone" 대신 "small"을 사용해야 합니다.
"touch": 터치스크린 기기에 정의됩니다.
"tv": TV 기반 기기에 정의됩니다.
"firetv": Amazon Fire TV 콘솔에 정의됩니다. "tv"와 "small"도 정의됩니다.
"chromeos": Chromebook에서 Android 앱으로 실행할 때 정의됩니다.
"android": 모든 Android 기기에 정의됩니다.
"ios": iPad와 iPhone 같은 iOS 기기에 정의됩니다. iPad는 "tablet"과 "medium", iPhone은 "phone"과 "small"도 정의됩니다.
"mobile": Android, iOS, 모바일 웹 브라우저 같은 모바일 플랫폼에 정의됩니다.
"pc": Windows, Mac OS X, Linux에 정의됩니다. PC는 마우스와 키보드가 있어 버튼에 마우스를 올리고 정확하게 가리킬 수 있다고 가정합니다.
"web": 웹 브라우저 안에서 실행할 때 정의됩니다.
None: 항상 정의됩니다.

스크린 변형 정의 예는 다음과 같습니다.

# A variant hello_world screen, used on small touch-based
# devices.
screen hello_world():
     tag example
     zorder 1
     modal False
     variant "small"

     text "안녕, 세상아." size 30

함께 보기

스크린 액션, 값, 함수: 스크린에서 사용하는 액션과 도구의 종합 목록입니다.

스크린 언어 최적화: 스크린 효율을 최대한 높이는 유용한 방법입니다.

스크린과 Python: Ren'Py 기본 도구 사용을 넘어 기능을 확장하는 방법입니다.