Ren'Py 문에 대응하는 Python 함수

Ren'Py 스크립트를 Python으로 작성할 수 있도록 각 문에 대응하는 Python 기능이 있습니다. 보통 함수 하나이지만 여러 Python 호출을 조합하여 같은 동작을 구현하는 경우도 있습니다.

원래 문 대신 이 기능을 사용하면 일반적으로 린트 검사와 예측 로딩 최적화가 적용되지 않습니다. 따라서 게임 검사가 어려워지고 동작이 덜 매끄러울 수 있습니다. 경우에 따라 특정 기능이 비활성화되기도 합니다.

대사

경고

이미 본 대사 건너뛰기 같은 일부 기능은 Python 버전에서는 사용할 수 없으며 원래 say 문에서만 지원합니다.

Ren'Py의 say 문은 캐릭터 객체가 있으면 이를 함수처럼 호출하는 것과 같습니다. 캐릭터가 없는 서술도 narrator 캐릭터를 같은 방식으로 사용하여 표시할 수 있습니다.

e "안녕, 세상아."
$ e("안녕, 세상아.")

"그러고 나서 태양이 폭발했다."
$ narrator("그러고 나서 태양이 폭발했다.")

프록시 함수

캐릭터와 함수 객체의 대응 관계는 반대로도 성립합니다. Python 함수를 선언하고 원래 say 문에서 캐릭터 객체 대신 사용할 수 있습니다. 예를 들어 다음 함수는 변수에 따라 두 캐릭터 중 하나를 선택합니다.

define lucy_normal = Character("루시")
define lucy_evil = Character("사악한 루시")

init python:

    def l(what, **kwargs):
        if lucy_is_evil:
            lucy_evil(what, **kwargs)
        else:
            lucy_normal(what, **kwargs)

label start:

    $ lucy_is_evil = False

    l "평소엔 나도 꽤 멀쩡해요."

    $ lucy_is_evil = True

    l "하지만 가끔은 정말 화가 나요!"

이렇게 사용하는 함수는 알 수 없는 키워드 인수를 무시하거나 캐릭터 함수에 전달해야 합니다. 그래야 이후 Ren'Py 버전에서 캐릭터 호출에 키워드 인수가 추가되어도 게임이 계속 동작합니다.

다른 인수와 달리 (interact=False)를 직접 전달하지 않는 한 interact=True를 항상 함수에 전달합니다. 인수를 사용하는 say 문에서는 추가되는 interact를 포함한 인수들이 함수에 전달됩니다. 예를 들어:

e "안녕, 세상아." (what_size=32)

다음 호출로 처리됩니다.

e("안녕, 세상아.", what_size=32, interact=True)

Character 객체를 직접 호출할 때는 의도대로 동작하도록 interact=True를 전달할 필요가 없습니다. 다음도 똑같이 동작합니다.

$ e("안녕, 세상아.", what_size=32)

e가 Character이면 다음과도 같습니다.

$ Character(kind=e, what_size=32)("안녕, 세상아.")

하지만 config.say_arguments_callback을 사용하거나 e가 캐릭터를 감싸는 래퍼가 되도록 하여 다르게 처리할 수 있습니다.

Python으로 say 문을 대체하는 방법이 하나 더 있습니다.

renpy.say(who, what, *args, **kwargs)

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

who: 말할 캐릭터, 서술자를 뜻하는 None 또는 캐릭터 이름 문자열입니다. 문자열이면 스토어 함수 say를 호출합니다.
what: 대사 문자열입니다. 퍼센트 치환을 수행합니다.
interact: 참이면 대사를 표시할 때 Ren'Py가 플레이어의 입력을 기다립니다. 거짓이면 대사를 표시하지만 상호작용은 수행하지 않습니다. 키워드 인수로 전달합니다.

다음 세 줄은 서로 같으므로 이 함수가 필요한 경우는 드뭅니다.

e "안녕, 세상아."
$ renpy.say(e, "안녕, 세상아.")
$ e("안녕, 세상아.") # when e is not a string
$ say(e, "안녕, 세상아.") # when e is a string

대사창 관리

_window 및 _window_auto 변수를 설정하고 다음 두 함수를 사용하여 대사창을 관리합니다.

_window_hide(trans=False, auto=False)

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

trans: False이면 기본 대사창 숨김 화면 전환을 사용합니다. None이면 화면 전환을 사용하지 않습니다. 그 밖의 경우 지정한 화면 전환을 사용합니다.
auto: True이면 window auto hide 문과 같아집니다.

_window_show(trans=False, auto=False)

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

trans: False이면 기본 대사창 표시 화면 전환을 사용합니다. None이면 화면 전환을 사용하지 않습니다. 그 밖의 경우 지정한 화면 전환을 사용합니다.
auto: True이면 window auto show 문과 같아집니다.

선택지 메뉴

menu 문에 대응하는 Python 함수가 있습니다.

class renpy.Choice(value, /, *args, **kwargs)

인수를 가진 메뉴 선택지를 표현합니다. 첫 위치 인수는 반환할 값이고 나머지는 선택 스크린에 전달할 인수입니다.

renpy.display_menu()의 items 리스트에서 스크린에 인수를 전달하는 용도입니다.

value: 선택 스크린에 전달할 값입니다.

위치 인수와 키워드 인수를 이 객체에 저장하고 renpy.display_menu에서 사용합니다.

renpy.display_menu(items, *, interact=True, screen='choice', type='menu', _layer=None, args=None, kwargs=None)

사용자에게 메뉴를 표시합니다. items는 2요소 튜플의 리스트여야 합니다. 각 튜플의 첫 요소는 텍스트 레이블, 두 번째는 선택했을 때 반환할 값입니다. 값이 None이면 첫 요소를 메뉴 제목으로 사용합니다.

선택 인수를 많이 받지만 여기서는 일부만 설명합니다. items 외에는 모두 키워드 인수로 지정해야 합니다.

interact: 거짓이면 메뉴를 표시하지만 상호작용은 수행하지 않습니다.
screen: 메뉴를 표시할 스크린의 이름입니다.
type: "menu" 또는 "nvl"입니다. "nvl"이면 NVL 모드로, 그 밖에는 ADV 모드로 메뉴를 표시합니다.
_layer: 메뉴를 표시할 레이어입니다. 지정하지 않으면 일반 선택 메뉴는 config.choice_layer, NVL 선택 메뉴는 config.nvl_choice_layer가 기본값입니다.
_args: None이 아니면 메뉴에 전달할 위치 메뉴 인수를 담은 튜플이어야 합니다.
_kwargs: None이 아니면 메뉴에 전달할 키워드 메뉴 인수를 담은 딕셔너리여야 합니다.

대부분의 Ren'Py 게임은 메뉴 제목 대신 서술을 사용합니다. 서술과 함께 메뉴를 표시하려면 다음과 같이 작성합니다.

$ narrator("어느 방향으로 가시겠어요?", interact=False)
$ result = renpy.display_menu([ ("동쪽", "east"), ("서쪽", "west") ])

선택지마다 인수를 전달해야 한다면 값으로 renpy.Choice 객체를 사용합니다. 예를 들면 다음과 같습니다.

renpy.display_menu([
    ("동쪽", renpy.Choice("east", icon="right_arrow")),
    ("서쪽", renpy.Choice("west", icon="left_arrow"))
    ])

이미지 표시하기

image, scene, show, hide 문에는 각각 대응하는 Python 함수가 있습니다. 원래 문은 이미지 표시를 참조하세요.

renpy.get_at_list(name, layer=None)

layer의 name 태그 이미지에 적용 중인 트랜스폼 리스트를 반환합니다. 적용 중인 트랜스폼이 없으면 빈 리스트, 이미지가 표시되지 않으면 None을 반환합니다.

layer가 None이면 지정한 태그의 기본 레이어를 사용합니다.

renpy.hide(name, layer=None)

레이어에서 이미지를 숨깁니다. hide 문에 대응하는 Python 함수입니다.

name: 숨길 이미지의 이름입니다. 이미지 태그만 사용하며 해당 태그의 모든 이미지를 숨깁니다. 정확한 이름은 중요하지 않습니다.
layer: 이 함수가 동작할 레이어입니다. None이면 태그의 기본 레이어를 사용합니다.

renpy.image(name, d)

이미지를 정의합니다. image 문에 대응하는 Python 함수입니다.

name: 표시할 이미지의 이름을 나타내는 문자열입니다.
d: 이미지 이름에 연결할 디스플레이어블입니다.

이 함수는 init 블록 안에서만 실행할 수 있습니다. 게임이 시작된 뒤 실행하면 오류가 발생합니다.

renpy.scene(layer='master')

layer의 모든 디스플레이어블을 제거합니다. 표시할 이미지를 지정하지 않은 scene 문과 같습니다.

전체 scene 문은 renpy.scene 호출 뒤에 renpy.show()를 호출하는 것과 같습니다. 예를 들어:

scene bg beach

다음과 같습니다.

$ renpy.scene()
$ renpy.show("bg beach")

renpy.show(name, at_list=[], layer=None, what=None, zorder=0, tag=None, behind=[], atl=None, **kwargs)

레이어에 이미지를 표시합니다. show 문에 대응하는 프로그래밍 방식입니다.

name: 표시할 이미지 이름을 나타내는 문자열입니다.
at_list: 이미지에 적용할 트랜스폼 리스트입니다. at 속성에 대응합니다.
layer: 이미지를 표시할 레이어 이름 문자열입니다. onlayer 속성에 대응합니다. None이면 태그의 기본 레이어를 사용합니다.
what: None이 아니면 이미지를 찾는 대신 이 디스플레이어블을 표시합니다. show expression 문에 대응합니다. what을 지정하면 name으로 이미지에 태그를 연결할 수 있습니다.
zorder: zorder 속성에 대응하는 정수입니다. None이면 기존 zorder가 있을 경우 유지하고, 없으면 0으로 설정합니다.
tag: 표시할 이미지의 이미지 태그를 지정하는 문자열입니다. as 속성에 대응합니다.
behind: 이 이미지보다 앞에 표시할 이미지 태그들의 문자열 리스트입니다. behind 속성에 대응합니다.
atl: None이 아니면 적용할 ATL 트랜스폼입니다. ATL 자체만 사용하며 이전 상태는 적용하지 않습니다.

show a
$ renpy.show("a")

show expression w
# anonymous show expression : no equivalent

show expression w as a
$ renpy.show("a", what=w)
$ renpy.show("y", what=w, tag="a") # in this case, name is ignored

show a at T, T2
$ renpy.show("a", at_list=(T, T2))

show a onlayer b behind c zorder d as e
$ renpy.show("a", layer="b", behind=["c"], zorder="d", tag="e")

renpy.show_layer_at(at_list, layer='master', reset=None, camera=False)

show layer layer at at_list 문에 대응하는 Python 함수입니다. camera가 True이면 camera 문에 대응합니다.

reset: 참이면 표시할 때 트랜스폼 상태를 처음으로 초기화합니다. 거짓이면 상태를 유지하여 새 트랜스폼이 갱신할 수 있습니다. None이면 show layer에서는 참, camera에서는 거짓입니다.

화면 전환

with 문에 대응하는 함수는 renpy.with_statement()입니다.

renpy.with_statement(trans, always=False)

화면 전환을 발생시킵니다. with 문에 대응하는 Python 함수입니다.

trans: 화면 전환입니다.
always: True이면 사용자가 화면 전환을 꺼도 항상 실행합니다.

사용자가 화면 전환을 중단하면 참, 그 밖에는 거짓을 반환합니다.

jump

jump 문에 대응하는 함수는 renpy.jump()입니다.

renpy.jump(label): 현재 문을 끝내고 지정한 레이블로 제어를 이동합니다.

call

call 문에 대응하는 함수는 renpy.call()입니다.

renpy.call(label, *args, from_current=False, **kwargs)

현재 Ren'Py 문을 끝내고 label로 점프합니다. 반환하면 현재 문의 다음 문으로 제어가 넘어갑니다.

레이블은 "global_name" 또는 "global_name.local_name" 형식이어야 합니다. ".local_name" 형식은 허용하지 않습니다.

from_current: 참이면 다음 문이 아니라 현재 문으로 돌아옵니다. 따라서 현재 문을 두 번 실행하게 됩니다. 반드시 키워드 인수로 전달해야 합니다.

renpy.return_statement(value=None): 현재 Ren'Py 수준의 호출에서 반환합니다.

pause

pause 문에 대응하는 함수는 renpy.pause()입니다.

renpy.pause(delay=None, *, predict=False, modal=True, hard=False)

Ren'Py를 일시 정지합니다. 사용자가 클릭해 끝냈으면 참, 시간이 지났거나 건너뛰었으면 거짓을 반환합니다.

delay: 지정하면 Ren'Py를 멈출 초 수입니다.

다음은 키워드 인수로 지정해야 합니다.

predict

True이면 renpy.start_predict() 및 renpy.start_predict_screen()으로 예약한 것을 포함한 모든 예측 로딩이 끝나면 대기를 끝냅니다.

대기 중에는 Ren'Py가 화면 표시의 부드러움보다 예측 로딩을 우선합니다. 따라서 예측 로딩 중에는 애니메이션을 표시하지 않는 것을 권장합니다.

사용자의 클릭이나 건너뛰기, 지정한 delay 시간의 만료 등 다른 방법으로도 대기가 끝납니다.

modal

True이면 모달 스크린이 표시 중일 때 시간 제한 대기가 끝나지 않고 유지됩니다. False이면 모달 스크린이 있어도 대기가 끝납니다.

hard

True이면 Ren'Py가 사용자의 클릭으로 대기를 중단하지 못하게 할 수 있습니다. 플레이어가 건너뛰기를 켜면 강제 대기도 건너뜁니다. 다른 상황에서 강제 대기가 일찍 끝나거나 Ren'Py의 정상 동작을 방해할 수도 있으며 이는 버그로 취급하지 않습니다.

일반적으로 강제 대기는 사용자에게 무례합니다. 게임을 진행하려고 클릭했다면 진행하고 싶다는 명시적인 요청입니다. 이를 무시하는 것은 플레이어 자신보다 그 의도를 더 잘 안다고 가정하는 것입니다.

요점은 renpy.pause를 hard=True로 사용하지 말라는 것입니다.

renpy.pause를 호출하면 현재 화면을 최소 한 프레임 표시하여 플레이어에게 보여 주었음을 보장합니다.

layeredimage

layeredimage 문에는 대응하는 Python 기능이 있습니다. group 문에는 없지만 그룹 이름을 Attribute에 전달하며 auto 기능은 renpy.list_images()로 구현할 수 있습니다.

class Attribute(group, attribute, image=None, default=False, *, prefix=None, variant=None, **kwargs)

속성으로 제어되는 LayeredImage 레이어를 나타냅니다. 한 속성으로 여러 레이어를 제어할 수 있으며 이 경우 해당 레이어를 모두 표시합니다.

group: 속성이 속한 그룹을 나타내는 문자열입니다. None이면 속성과 같은 이름의 그룹을 만듭니다.
attribute: 속성의 이름을 나타내는 문자열입니다.
image: None이 아니면 이 속성을 표시할 때 사용할 디스플레이어블이어야 합니다.
default: True이고 그룹의 다른 속성을 선택하지 않았으면 이 속성을 선택합니다.

다음 키워드 인수도 인식합니다.

at: 이미지에 적용할 트랜스폼 또는 트랜스폼 리스트입니다.
when: When 절에서 설명하는 when 표현식을 담은 문자열입니다. layeredimage에 현재 적용된 속성 집합이 표현식을 만족할 때만 디스플레이어블을 표시합니다.
variant: 속성의 variant를 나타내는 문자열입니다. image가 None일 때 디스플레이어블을 찾는 데 사용합니다.

다른 키워드 인수는 트랜스폼 속성으로 해석합니다. 하나라도 있으면 이미지를 감싸는 트랜스폼을 만듭니다. 예를 들어 pos=(100, 200)으로 이미지를 가로로 100픽셀, 세로로 200픽셀 이동할 수 있습니다.

image를 생략하거나 None으로 지정했고 LayeredImage에 image_format을 지정했다면 image_format으로 이미지 파일명을 생성합니다.

class Condition(condition, image, **kwargs)

조건이 참이면 레이어를 표시하고, 그렇지 않으면 아무것도 표시하지 않습니다.

layeredimage의 if, elif 또는 else 문 하나를 구현합니다. else에서는 condition이 "True"여야 합니다. 여러 Condition을 ConditionGroup에 전달하여 전체 if/elif/else 문을 구현할 수 있습니다.

condition: 레이어 표시 여부를 결정하는 Python 조건 문자열이어야 합니다.
image: None이 아니면 조건이 참일 때 표시할 디스플레이어블이어야 합니다.
when: When 절에서 설명하는 when 표현식 문자열입니다. layeredimage에 현재 적용된 속성 집합이 이 표현식을 만족할 때만 조건을 평가합니다.
at: 이미지에 적용할 트랜스폼 또는 트랜스폼 리스트입니다.

다른 키워드 인수는 트랜스폼 속성으로 해석합니다. 하나라도 있으면 이미지를 감싸는 트랜스폼을 만듭니다. 예를 들어 pos=(100, 200)으로 이미지를 가로로 100픽셀, 세로로 200픽셀 이동할 수 있습니다.

class ConditionGroup(conditions)

Condition 리스트를 받아 하나의 ConditionSwitch()로 조합합니다.

if/elif/else 문을 구현합니다.

class LayeredImage(attributes, at=[], name=None, image_format=None, format_function=<function format_function at 0x700fff282200>, attribute_function=None, offer_screen=None, **kwargs)

적절한 속성 집합으로 표시하면 해당 속성에 연결된 디스플레이어블들을 합성한 결과를 보여 주는 이미지형 객체입니다.

attributes: Attribute, Condition, ConditionGroup 또는 디스플레이어블 객체의 리스트여야 합니다. 각 항목은 이미지의 일부로 표시될 수 있는 디스플레이어블을 나타냅니다. 뒤에서 앞으로 정렬하며 첫 항목이 사용자에게서 가장 멀고 마지막이 가장 가깝습니다. 디스플레이어블을 직접 전달하면 layeredimage의 always 문과 같습니다.
at: 매개변수 적용 후 디스플레이어블에 적용할 트랜스폼 또는 트랜스폼 리스트입니다.
name: layeredimage의 이름입니다. 이미지 구성 요소의 이름을 만드는 데 사용합니다.
image_format: 이미지가 문자열이고 이 인수를 지정했다면 이미지 이름을 image_format에 보간하여 이미지 파일 경로를 만듭니다. 예를 들어 "sprites/eileen/{image}.png"는 sprites의 하위 디렉터리에서 이미지를 찾습니다. auto 그룹은 이미지 파일이 아닌 이미지를 찾으므로 이를 사용하지 않습니다.
format_function: layeredimage.format_function 대신 이미지 정보를 디스플레이어블로 변환할 함수입니다.
attribute_function: None이 아니면 이미지에 지정한 속성 집합을 받아 레이어 선택에 사용할 속성 집합을 반환하는 함수입니다. 속성 자체가 선택된 뒤 표시할 레이어를 결정할 때 호출합니다. 속성 간 복잡한 의존 관계를 표현하거나 속성을 무작위로 선택할 수 있습니다.
offer_screen: 자식의 배치와 가변 크기 자식의 크기 계산에서 사용 가능한 영역을 고려할지 설정합니다. False이면 고려하고 True이면 고려하지 않습니다. None이면 config.layeredimage_offer_screen이 기본값입니다.

추가 키워드 인수에는 트랜스폼 속성을 넣을 수 있습니다. 있으면 결과 이미지를 감싸는 트랜스폼을 만듭니다. 나머지 키워드 인수는 레이어를 담기 위해 생성한 Fixed에 전달합니다. 명시적으로 덮어쓰지 않으면 Fixed의 xfit과 yfit을 참으로 설정하므로 표시하는 모든 레이어 이미지를 포함하는 최소 크기로 줄어듭니다.

LayeredImage는 디스플레이어블이 아니므로 디스플레이어블을 받는 모든 곳에서 사용할 수는 없습니다. 일반적으로 이미지 속성을 포함한 이미지 이름이 필요하기 때문입니다. 따라서 scene 문이나 show 문으로 표시하거나 이미지 이름 문자열을 디스플레이어블로 사용해야 합니다.

add(a)

a: Attribute, Condition, ConditionGroup 또는 디스플레이어블 객체입니다.

지정한 레이어를 생성자의 attributes 인수로 전달한 것처럼 layeredimage의 레이어 목록에 추가합니다.