스크린과 Python

스크린 함수

다음 함수는 스크린과 관련된 여러 작업을 지원합니다.

renpy.call_screen(_screen_name, *args, _with_none=True, _mode='screen', **kwargs)

call screen 문에 대응하는 함수입니다.

_screen_name을 스크린으로 표시한 뒤 상호작용을 시작합니다. 상호작용이 끝나면 스크린을 숨기고 결과를 반환합니다.

위치 인수와 _로 시작하지 않는 키워드 인수는 스크린에 전달합니다.

_with_none이 거짓이면 상호작용이 끝날 때 "with None"을 실행하지 않습니다.

_mode를 전달하면 이 상호작용의 모드로 사용합니다. 그렇지 않으면 "screen"입니다.

renpy.current_screen()

현재 갱신, 렌더링 또는 처리 중인 스크린의 정보를 반환합니다.

반환 객체의 문서화된 필드는 get_screen()을 참고하세요.

renpy.get_adjustment(bar_value)

BarValue인 bar_value를 받아, 사용 중인 ui.adjustment()를 반환합니다. 이 조정 객체에는 다음 속성이 정의되어 있습니다.

value: 바의 현재 값입니다.

range: 바의 현재 범위입니다.

renpy.get_displayable(screen, id, layer=None, base=False): layer의 screen에서 id의 디스플레이어블을 반환합니다. 스크린이 없거나 해당 ID의 위젯이 없으면 None을 반환합니다.

renpy.get_displayable_properties(id, screen=None, layer=None)

layer의 screen에서 id 디스플레이어블의 속성을 반환합니다. screen이 None이면 현재 스크린의 속성을 반환합니다. Python이나 스크린 내부의 속성 코드에서 사용할 수 있습니다.

위젯 속성을 담은 딕셔너리를 반환하므로, 개별 속성을 얻으려면 딕셔너리에 접근해야 합니다.

renpy.get_screen(name, layer=None, tag_only=False)

layer에 있는 name 스크린의 정보를 반환합니다. name은 먼저 태그 이름으로, 그다음 스크린 이름으로 해석합니다. 스크린이 표시 중이 아니면 None을 반환합니다.

이름 리스트를 받을 수도 있으며, 이 경우 표시 중인 첫 스크린을 반환합니다.

tag_only: 참이면 태그만 고려합니다.

이 함수로 스크린이 표시 중인지 확인할 수 있습니다.

if renpy.get_screen("say"):
    text "say 스크린이 표시되어 있습니다."
else:
    text "say 스크린이 숨겨져 있습니다."

이 함수가 반환하는 객체에는 다음 필드가 문서화되어 있습니다.

layer: 스크린을 표시하는 레이어입니다.

name: 스크린 이름입니다.

zorder: 스크린을 표시하는 zorder입니다.

경고

비슷한 다른 함수와 마찬가지로 반환 객체는 호출 직후 잠깐 사용하는 용도입니다. 저장 데이터에 넣거나 롤백에 참여시키는 것은 권장하지 않습니다.

renpy.get_screen_docstring(name, variant=None)

name과 variant에 해당하는 스크린의 독스트링을 반환합니다.

name: 스크린 이름입니다.
variant: 스크린 변형입니다. None이면 기본 변형을 사용합니다.

renpy.get_screen_variable(name, *, screen=None, layer=None)

스크린 스코프의 변수 값을 반환합니다.

name: 값을 반환할 변수 이름입니다.
screen: 변수를 가져올 스크린 이름입니다. None이면 현재 스크린을 사용합니다. 현재 스크린은 스크린을 갱신할 때와 그 안에서 실행하는 액션에서만 정의됩니다.
layer: screen이 None이 아닐 때 스크린을 찾을 레이어입니다.

renpy.hide_screen(tag, layer=None, immediately=False)

hide screen 문에 대응하는 함수입니다.

layer에서 tag의 스크린을 숨깁니다.

immediately가 참이면 'on hide' 이벤트 없이 즉시 숨깁니다.

renpy.set_focus(screen, id, layer='screens')

screen 스크린에서 id 디스플레이어블에 포커스를 주려고 시도합니다. 디스플레이어블을 찾지 못하거나, 창에 포커스가 없거나, 다른 요소가 포커스를 점유하고 있으면 실패합니다.

호출 처리 후 마우스가 조금이라도 움직이면 포커스가 바뀔 수 있습니다.

renpy.set_screen_variable(name, value, *, screen=None, layer=None)

스크린 스코프의 변수에 값을 설정합니다. 값이 즉시 갱신되지는 않습니다. renpy.restart_interaction()을 호출하여 스크린을 갱신하세요.

name: 설정할 변수 이름입니다. 다른 변수의 변경은 최적화 때문에 보이지 않을 수 있으므로 default 문으로 만든 변수여야 합니다.
value: 변수에 설정할 값입니다.
screen: 변수를 가져올 스크린 이름입니다. None이면 현재 스크린을 사용합니다. 현재 스크린은 스크린을 갱신할 때와 그 안에서 실행하는 액션에서만 정의됩니다.
layer: screen이 None이 아닐 때 스크린을 찾을 레이어입니다.

renpy.show_screen(_screen_name, *args, _layer=None, _zorder=None, _tag=None, _widget_properties={}, _transient=False, **kwargs)

show screen 문에 대응하는 함수입니다.

지정한 스크린을 표시합니다. 다음 키워드 인수를 받습니다.

_screen_name

표시할 스크린 이름입니다.

_layer

스크린을 표시할 레이어입니다. show screen 문의 onlayer 절과 같습니다.

_zorder

스크린을 표시할 zorder입니다. 지정하지 않으면 스크린에 연결된 zorder를 사용하며, 그것도 없으면 0입니다.

_tag

스크린을 표시할 태그입니다. 지정하지 않으면 스크린에 연결된 태그를 사용하며, 그것도 없으면 스크린 이름입니다.

show screen 문의 as 절과 같습니다.

_widget_properties

위젯 ID를 속성 이름 -> 속성 값 딕셔너리에 연결하는 맵입니다. 해당 ID의 위젯이 스크린에 표시되면 지정한 속성을 추가합니다.

_transient

참이면 현재 상호작용이 끝날 때 스크린을 자동으로 숨깁니다.

위치 인수와 밑줄로 시작하지 않는 키워드 인수는 스크린에 전달합니다.

renpy.start_predict_screen(_screen_name, *args, **kwargs)

지정한 인수로 _screen_name 스크린의 예측 로딩을 시작합니다. 해당 _screen_name에 대한 이전 예측을 대체합니다. 중지하려면 renpy.stop_predict_screen()를 호출합니다.

예측 로딩은 일반적인 게임 진행 중에 이루어집니다. 완료될 때까지 기다리려면 renpy.pause()의 predict 인수를 사용합니다.

renpy.stop_predict_screen(name): name 스크린의 예측 로딩을 중지합니다.

renpy.variant(name)

name이 현재 Ren'Py 실행 컨텍스트에 맞는 스크린 변형이면 참을 반환합니다. 자세한 내용은 스크린 변형을 참고하세요. if 문의 조건으로 사용하여 선택된 변형에 따라 동작을 바꿀 수 있습니다.

name에 변형 리스트를 지정할 수도 있으며, 하나라도 해당하면 True를 반환합니다.

class ui.adjustment(range=1, value=0, step=None, page=None, changed=None, adjustable=None, ranged=None, force_step=False, raw_changed=None)

조정 객체는 바나 뷰포트로 조절할 수 있는 값을 나타냅니다. 값과 범위, 작은 단계 및 큰 페이지 단위로 값을 조절하는 방법에 관한 정보를 담습니다.

다음 매개변수는 조정 객체의 필드 또는 속성에 대응합니다.

range

조정 범위를 나타내는 숫자입니다.

value

조정 값을 나타내는 숫자입니다.

step

조정 단계 크기를 나타내는 숫자입니다. None이면 page가 설정된 경우 그 값의 1/10, 그렇지 않으면 range의 1/20을 기본값으로 사용합니다.

마우스 휠로 뷰포트를 스크롤할 때 사용합니다.

page

조정 페이지 크기입니다. None이면 뷰포트가 자동으로 설정합니다. 한 번도 설정하지 않으면 range의 1/10을 기본값으로 사용합니다.

스크롤바를 클릭할 때 사용할 수 있습니다.

다음 매개변수는 조정 객체의 동작을 제어합니다.

adjustable

True이면 바로 이 조정 값을 바꿀 수 있습니다. False이면 바꿀 수 없습니다.

changed 함수를 지정하거나 뷰포트에 연결된 조정 객체이면 기본적으로 조절 가능하며, 그 밖에는 조절할 수 없습니다.

changed

조정 값이 바뀔 때 새 값을 받아 호출되는 함수입니다.

raw_changed

조정 값이 바뀔 때 호출되는 함수입니다. changed와 달리 범위를 벗어날 수 있는 원시 값을 받습니다. 조정 객체와 새 값이라는 두 인수로 호출됩니다.

ranged

뷰포트가 조정 범위를 설정할 때 조정 객체를 받아 호출하는 함수입니다.

배치 과정에서 여러 번 호출될 수 있습니다.

force_step

True이고 연결된 뷰포트나 바를 끌어 값을 바꾸면 다음 단계에 도달했을 때만 값이 바뀝니다. "release"이면 놓은 뒤 가장 가까운 단계로 값을 반올림합니다. False이면 단계 값을 무시하고 끄는 대로 값이 바뀝니다.

change(value): 조정 값을 value로 바꾸고, 이를 사용하는 모든 바와 뷰포트를 갱신합니다.

ui.interact(*, roll_forward=None, mouse=None)

사용자와의 상호작용을 시작하고 결과를 반환합니다. 화면을 다시 그리고 입력 이벤트 처리를 시작합니다. 디스플레이어블이 이벤트에 응답하여 값을 반환하면 ui.interact가 그 값을 반환하고 상호작용이 끝납니다.

직접 호출하는 경우는 드뭅니다. 보통 say, menu, with, pause, call screen 문과 renpy.input() 등 Ren'Py의 여러 기능이 호출합니다. 필요하다면 직접 호출할 수도 있습니다.

상호작용이 끝나면 transient 레이어와 _transient를 참으로 표시한 모든 스크린을 장면 목록에서 제거합니다.

문서화된 인수는 다음과 같습니다. Ren'Py 내부용으로 문서화되지 않은 인수도 있으므로 모든 인수를 키워드로 전달하세요.

roll_forward: 롤포워드가 발생했을 때 이 함수가 반환할 정보입니다. None이면 롤포워드를 무시합니다. 보통 renpy.roll_forward_info()의 결과를 전달해야 합니다.
mouse: 이 함수 실행 중 사용할 마우스 커서 스타일입니다. None이면 메인 메뉴나 게임 메뉴의 활성 여부에 따라 'default', 'mainmenu', 'gamemenu' 중에서 선택합니다.

액션

스크린 언어로 만드는 여러 디스플레이어블은 액션을 인수로 받습니다. 액션은 다음 세 가지 중 하나입니다.

인수를 받지 않는 호출 가능한 Python 객체. 예: 함수 또는 바인딩된 메서드.
Action 클래스를 상속하는 클래스의 객체.
다른 액션들의 리스트.

Action 클래스를 상속하면 버튼의 활성 여부와 선택 여부를 결정하는 메서드를 재정의할 수 있다는 장점이 있습니다.

class Action

새 액션을 정의하려면 이 클래스를 상속합니다. 메서드를 재정의하여 동작을 바꿀 수 있습니다.

__call__(self)

액션이 실행될 때 호출하는 메서드입니다. 대부분의 경우 None이 아닌 값을 반환하면 현재 상호작용이 끝납니다.

기본 메서드는 NotImplementedError를 발생시켜 Ren'Py 오류를 일으키므로 반드시 재정의해야 합니다.

get_sensitive(self)

이 액션을 사용하는 버튼을 활성화할지 결정하기 위해 호출합니다. 활성화할 경우 참을 반환해야 합니다.

이 메서드가 False를 반환해도 __call__은 호출될 수 있습니다.

기본 구현은 True를 반환합니다.

get_selected(self)

버튼을 선택 상태로 렌더링해야 하면 참을, 그렇지 않으면 거짓을 반환해야 합니다.

기본 구현은 False를 반환합니다.

get_tooltip(self)

별도 툴팁이 지정되지 않았을 때 버튼의 기본 툴팁을 얻습니다. 툴팁 값이나, 알 수 없으면 None을 반환해야 합니다.

기본적으로 None을 반환합니다.

periodic(self, st)

각 상호작용이 시작할 때 한 번 호출하고 이후 주기적으로 호출합니다. 숫자를 반환하면 해당 초가 지나기 전에 다시 호출하며, 더 일찍 호출할 수도 있습니다.

주로 get_selected나 get_sensitive의 값이 바뀌어야 할 때 renpy.restart_interaction()을 호출하는 데 사용합니다.

인수 하나를 받습니다.

st: 이 액션에 연결된 스크린이나 디스플레이어블이 처음 표시된 이후 지난 초입니다.

unhovered(self): 버튼 등의 hovered 매개변수로 이 액션을 사용하면, 객체가 포커스를 잃을 때 이 메서드를 호출합니다.

alt: 이 Action을 사용하는 버튼에 alt 속성이 없을 때 텍스트 음성 변환에 사용할 텍스트입니다. 클래스나 생성자에서 문자열로 설정하거나, 문자열을 반환하는 Python 속성으로 구현할 수 있습니다.

Python에서 액션을 실행하려면 renpy.run()을 사용합니다.

renpy.is_selected(action): 지정한 액션이나 액션 리스트가 선택 상태를 나타내면 참인 값을, 그렇지 않으면 거짓을 반환합니다.

renpy.is_sensitive(action): 지정한 액션이나 액션 리스트가 활성 상태를 나타내면 참인 값을, 그렇지 않으면 거짓을 반환합니다.

renpy.run(action)

액션이나 액션 리스트를 실행합니다. 단일 액션은 인수 없이 호출하고, 리스트는 이 함수로 순서대로 실행하며, None은 무시합니다.

값을 반환한 마지막 액션의 결과를 반환합니다.

BarValue

bar, vbar, hotbar를 만들 때 value 속성으로 BarValue 객체를 지정할 수 있습니다. 객체의 메서드를 호출하여 조정 객체와 스타일을 얻습니다.

class BarValue

새 BarValue를 정의하려면 이 클래스를 상속하고 일부 메서드를 재정의합니다.

get_adjustment(self)

바의 조정 객체를 얻기 위해 호출하는 메서드입니다. ui.adjustment()로 조정 객체를 만들어 반환해야 합니다.

기본 메서드는 NotImplementedError를 발생시켜 Ren'Py 오류를 일으키므로 반드시 재정의해야 합니다.

get_style(self)

이 값을 사용하는 바의 스타일을 결정합니다. 스타일 이름 또는 객체 두 개의 튜플을 반환해야 합니다. 첫 번째는 bar, 두 번째는 vbar에 사용합니다.

기본값은 ("bar", "vbar")입니다.

get_tooltip(self)

별도 툴팁이 지정되지 않았을 때 버튼의 기본 툴팁을 얻습니다. 툴팁 값이나, 알 수 없으면 None을 반환해야 합니다.

기본적으로 None을 반환합니다.

replaces(self, other)

스크린 갱신 등으로 BarValue가 다른 BarValue를 대체할 때 호출됩니다. 다른 값의 상태를 바탕으로 현재 BarValue를 갱신하는 데 사용할 수 있습니다. get_adjustment 전에 호출됩니다.

other와 self의 형식이 같다는 보장은 없습니다.

periodic(self, st)

각 상호작용이 시작할 때 한 번 호출합니다. 초를 나타내는 숫자를 반환하면 그 시간이 지나기 전에 다시 호출하며, 더 일찍 호출할 수도 있습니다. get_adjustment 뒤에 호출됩니다.

AnimatedValue()처럼 시간에 따라 바의 값을 갱신하는 데 사용할 수 있습니다. 그러려면 get_adjustment에서 조정 객체를 저장하고 periodic에서 그 객체의 changed 메서드를 호출해야 합니다.

alt: 이 BarValue를 사용하는 바에 alt 속성이 없을 때 텍스트 음성 변환에 사용할 텍스트입니다. 클래스나 생성자에서 문자열로 설정하거나, 문자열을 반환하는 Python 속성으로 구현할 수 있습니다.

InputValue

입력란을 만들 때 value 속성으로 InputValue 객체를 지정할 수 있습니다. 텍스트 조회와 설정, 편집 가능 여부 결정, Enter 키 처리를 위해 객체의 메서드를 호출합니다.

class InputValue

새 InputValue를 정의하려면 이 클래스를 상속하고 일부 또는 모든 메서드를 재정의한 뒤 default 필드 값을 설정합니다.

editable: 참이 아니면 입력란을 전혀 편집할 수 없게 합니다.

default: 참이면 기본적으로 편집 가능한 입력란이 될 수 있습니다. 즉, 스크린이 표시될 때 커서를 받을 수 있습니다.

get_text(self): 입력란의 기본 텍스트를 반환합니다. 반드시 구현해야 합니다.

set_text(self, s): 입력 텍스트가 바뀌면 새 텍스트를 받아 호출됩니다. 반드시 구현해야 합니다.

enter(self): 사용자가 Enter를 누르면 호출됩니다. None 이외의 값을 반환하면 그 값이 상호작용 결과가 됩니다. renpy.IgnoreEvent를 발생시켜 입력을 무시할 수도 있습니다. 그 밖에는 Enter 입력을 다른 디스플레이어블에 전달합니다.

InputValue의 메서드로 다음 액션을 사용할 수 있습니다.

Enable(): 입력란의 텍스트 편집을 활성화하는 액션을 반환합니다.

Disable(): 입력란의 텍스트 편집을 비활성화하는 액션을 반환합니다.

Toggle(): 입력란의 텍스트 편집을 전환하는 액션을 반환합니다.

제작자 정의 스크린 언어 문

Ren'Py는 사용자 정의 스크린 언어 문을 지원합니다. 이 문들은 스크린 언어의 use 문을 감쌉니다. 위치 인수는 그대로 위치 인수로, 속성은 키워드 인수로 전달하며, 문이 블록을 받으면 use 문도 블록을 받습니다. 예를 들어 다음 사용자 정의 문은

titledwindow "테스트 창":
    icon "icon.png"

    text "테스트입니다."

아래와 같이 바뀝니다.

use titledwindow("테스트 창", icon="icon.png"):
    text "테스트입니다."

제작자 정의 스크린 언어 문은 python early 블록에서 등록해야 합니다. 또한 정의가 담긴 파일을 사용하는 파일보다 먼저 불러와야 합니다. Ren'Py는 파일 경로의 유니코드 정렬 순서로 불러오므로 등록 파일 이름 앞에 01 같은 작은 숫자를 붙이는 것이 일반적으로 좋습니다.

제작자 정의 스크린 언어 문은 renpy.register_sl_statement 함수로 등록합니다.

class renpy.register_sl_displayable(name, displayable, style, nchildren=0, scope=False, *, replaces=False, default_keywords={}, default_properties=True, unique=False)

디스플레이어블을 만드는 스크린 언어 문을 등록합니다.

name

스크린 언어 문의 이름입니다. 새 문을 시작할 Ren'Py 키워드 문자열입니다.

displayable

호출하면 디스플레이어블 객체를 반환하는 함수입니다. 모든 위치 인수, 속성, 스타일 속성을 이 함수의 인수로 전달합니다. 아래에서 설명하는 다른 키워드 인수도 전달합니다.

반드시 Displayable을 반환해야 합니다. 여러 디스플레이어블을 반환한다면 가장 바깥쪽 디스플레이어블의 _main 속성을 자식이 추가되어야 하는 주 디스플레이어블로 설정해야 합니다.

style

이 디스플레이어블의 기본 스타일 이름입니다. style 속성을 지정하지 않으면 스타일 접두사를 앞에 붙입니다. 계산된 스타일은 displayable 함수에 style 키워드 인수로 전달합니다.

nchildren

디스플레이어블의 자식 수입니다. 다음 중 하나입니다.

0: 자식을 받지 않습니다.
1: 자식을 하나 받습니다. 여러 자식을 지정하면 Fixed 안에 넣습니다.
"many": 여러 자식을 받습니다.

unique

반환하는 디스플레이어블을 다른 곳에서 참조하지 않는다면 참으로 설정해야 합니다.

다음 인수는 키워드로 전달해야 합니다.

replaces: 참이고 기존 디스플레이어블을 대체한다면 기존 디스플레이어블을 새 디스플레이어블의 매개변수로 전달합니다.
default_keywords: 디스플레이어블에 전달할 기본 키워드 인수 모음입니다.
default_properties: 참이면 ui와 position 속성을 기본적으로 추가합니다.

다음 메서드로 위치 인수와 속성을 추가할 수 있는 객체를 반환합니다. 각 메서드는 자신이 호출된 객체를 반환하므로 연속해서 연결할 수 있습니다.

add_positional(name): name이라는 위치 인수를 추가합니다.

add_property(name): name이라는 속성을 추가합니다. 속성은 키워드 인수로 전달됩니다.

add_style_property(name): name으로 끝나고 다양한 스타일 속성 접두사가 붙는 속성 모음을 추가합니다. 예를 들어 ("size")로 호출하면 size, idle_size, hover_size 등을 정의합니다.

add_prefix_style_property(prefix, name): prefix, 스타일 속성 접두사, name으로 이루어진 이름의 속성 모음을 추가합니다. 예를 들어 접두사 text_와 이름 size로 호출하면 text_size, text_idle_size, text_hover_size 등을 만듭니다.

add_property_group(group, prefix='')

prefix가 붙은 속성 그룹을 추가합니다. Group은 다음 문자열 중 하나입니다.

"bar"
"box"
"button"
"position"
"text"
"window"

각각 스타일 속성 그룹에 대응합니다. Group을 "ui"로 지정하면 공통 UI 속성을 추가합니다.

copy_properties(name): name 스크린 문에 전달할 수 있는 모든 스타일과 위치/키워드 인수를 추가합니다.

class renpy.register_sl_statement(name, children='many', screen=None)

Ren'Py에 사용자 정의 스크린 언어 문을 등록합니다.

name: 단어여야 하며, 사용자 정의 스크린 언어 문의 이름입니다.
children: 이 사용자 정의 문이 받는 자식 수입니다. 0, 1, 또는 0개 이상을 뜻하는 "many"여야 합니다.
screen: 사용할 스크린입니다. 지정하지 않으면 name입니다.

위치 인수와 속성을 추가할 수 있는 객체를 반환합니다. renpy.register_sl_displayable이 반환한 객체와 같은 .add_ 메서드가 있습니다.

제작자 정의 스크린 언어 문의 예로 위의 titledwindow 문을 구현해 보겠습니다. 먼저 일찍 불러오는 파일의 python early 블록에서 문을 등록해야 합니다. 보통 01custom.rpy 같은 이름이면 충분히 일찍 불러옵니다. 등록 호출은 다음과 같습니다.

python early:
    renpy.register_sl_statement("titledwindow", children=1).add_positional("title").add_property("icon").add_property("pos")

그런 다음 사용자 정의 문을 구현하는 스크린을 정의합니다. 어느 파일에 정의해도 됩니다. 예를 들면 다음과 같습니다.

screen titledwindow(title, icon=None, pos=(0, 0)):
    drag:
        pos pos

        frame:
            background "#00000080"

            has vbox

            hbox:
                if icon is not None:
                    add icon

                text title

            null height 15

            transclude

add_property_group 같은 큰 속성 그룹을 사용할 때는 적절한 곳에 properties 키워드와 **properties 문법을 사용하는 것이 좋습니다. 예를 들면 다음과 같습니다.

screen titledwindow(title, icon=None, **properties):
    frame:
        # When background not in properties it will use it as default value.
        background "#00000080"

        properties properties

        has vbox

        hbox:
            if icon is not None:
                add icon

            text title

        null height 15

        transclude

사용자 정의 스크린 언어 문은 변수 이름을 받는 as 절을 지원합니다. 지정하면 스크린 스코프에서 해당 변수에 main 값을 대입합니다.