Эквиваленты операторов

Чтобы позволить писать скрипты Ren'Py на Python, каждый оператор Ren'Py имеет эквивалент на Python. Обычно это функция Python, но это также может быть набор вызовов Python, выполняющих действие, эквивалентное оператору.

Обратите внимание, что использование эквивалентов операторов вместо оригинальных операторов обычно убирает все возможные Lint-проверки и оптимизации прогнозирования, делая вашу игру менее проверяемой и, возможно, менее плавной. В определённых случаях это также может отключать некоторые функции.

Диалог

Предупреждение

Некоторые функции, такие как пропуск уже просмотренных диалогов, недоступны при использовании Python-версии и включаются только при использовании нативного оператора say.

Оператор Инструкция say в Ren'Py эквивалентен вызову объекта персонажа (если он присутствует) как функции. Отображение повествования (то есть когда персонаж не указан) можно выполнить таким же образом, используя персонажа narrator.

e "Hello, world."
$ e("Hello, world.")

"And then the sun exploded."
$ narrator("And then the sun exploded.")

Прокси-функции

Эта эквивалентность персонажей и объектов-функций работает и в другом направлении. Можно объявить функцию Python, а затем использовать эту функцию вместо объекта персонажа в нативном операторе say. Например, следующая функция использует переменную для выбора между двумя персонажами.

define lucy_normal = Character("Lucy")
define lucy_evil = Character("Evil Lucy")

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 "Usually, I feel quite normal."

    $ lucy_is_evil = True

    l "But sometimes, I get really mad!"

Функция, используемая таким образом, должна либо игнорировать неизвестные именованные аргументы, либо передавать их в функцию персонажа. Это позволит игре продолжать работать, если в будущих версиях Ren'Py будут добавлены дополнительные именованные аргументы в вызовы персонажей.

Обратите внимание, что в отличие от других возможных аргументов, interact=True всегда будет передаваться в функцию, если только вручную не передать (interact=False). Say с аргументами передаёт аргументы (включая дополнительный interact) в функцию. Например:

e "Hello, world." (what_size=32)

преобразуется в следующий вызов:

e("Hello, world.", what_size=32, interact=True)

Обратите внимание, что не обязательно передавать interact=True при вызове объекта Character, чтобы он работал как положено. Следующий код работает так же хорошо:

$ e("Hello, world.", what_size=32)

Когда e является Character, это также эквивалентно:

$ Character(kind=e, what_size=32)("Hello, world.")

Но можно использовать config.say_arguments_callback или заставить e оборачивать персонажа для другого поведения.

Есть ещё один способ замены оператора say с помощью Python:

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

Эквивалент оператора say.

who: Либо персонаж, который будет говорить, None для рассказчика, либо строка с именем персонажа. В последнем случае вызывается функция say из store.
what: Строка, содержащая реплику. В этой строке выполняются процентные подстановки.
interact: Если true, Ren'Py ждет ввода от игрока при отображении диалога. Если false, Ren'Py показывает диалог, но не выполняет взаимодействия. (Этот параметр передается как именованный.)

Эта функция редко бывает нужна, так как следующие три строки эквивалентны.

e "Hello, world."
$ renpy.say(e, "Hello, world.")
$ e("Hello, world.") # when e is not a string
$ say(e, "Hello, world.") # 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)

Этот класс инкапсулирует выбор в меню с аргументами. Первый позиционный аргумент — это значение, которое будет возвращено, а остальные аргументы — это аргументы, которые будут переданы на экран выбора.

Предназначен для использования в списке items функции renpy.display_menu() для предоставления аргументов этому экрану.

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: Если false, меню отображается, но взаимодействие не выполняется.
screen: Имя экрана, используемого для отображения меню.
type: Может быть "menu" или "nvl". Если "nvl", меню отображается в режиме NVL. В противном случае оно отображается в режиме ADV.
_layer: Слой для отображения меню. Если не указан, по умолчанию используется config.choice_layer для обычных меню выбора и config.nvl_choice_layer для меню выбора NVL.
_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)

Возвращает список трансформаций, применяемых к изображению с тегом name на слое layer. Возвращает пустой список, если трансформации не применяются, или None, если изображение не показано.

Если layer равен None, используется слой по умолчанию для данного тега.

renpy.hide(name, layer=None)

Скрывает изображение со слоя. Python-эквивалент оператора hide.

name: Имя изображения, которое нужно скрыть. Используется только тег изображения, и любое изображение с этим тегом будет скрыто (точное имя не имеет значения).
layer: Слой, на котором работает эта функция. Если None, используется слой по умолчанию, связанный с тегом.

renpy.image(name, d)

Определяет изображение. Эта функция является Python-эквивалентом оператора image.

name: Имя изображения для отображения, строка.
d: Отображаемый объект, который будет связан с этим именем изображения.

Эту функцию можно запускать только из блока init. Запуск этой функции после начала игры является ошибкой.

renpy.scene(layer='master')

Удаляет все отображаемые объекты со слоя layer. Это эквивалентно оператору scene, когда оператору 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 Transform. Принимается только сам ATL, предыдущее состояние не применяется.

show a
$ renpy.show("a")

show expression w
# анонимный show expression: эквивалента нет

show expression w as a
$ renpy.show("a", what=w)
$ renpy.show("y", what=w, tag="a") # в этом случае name игнорируется

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=True, camera=False)

Python-эквивалент оператора show layer layer at at_list. Если camera равно True, это эквивалент оператора camera.

reset: Если true, состояние трансформации сбрасывается к началу при ее показе. Если false, состояние трансформации сохраняется, позволяя новой трансформации обновить это состояние.

Переходы

Эквивалентом оператора Инструкция with является функция renpy.with_statement().

renpy.with_statement(trans, always=False)

Вызывает переход. Это Python-эквивалент оператора with.

trans: Переход.
always: Если True, переход всегда будет происходить, даже если пользователь отключил переходы.

Эта функция возвращает true, если пользователь решил прервать переход, и false в противном случае.

Переход (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: Если true, управление вернется к текущему оператору, а не к оператору, следующему за текущим. (Это приведет к тому, что текущий оператор будет выполнен дважды. Этот параметр должен передаваться как именованный аргумент.)

renpy.return_statement(value=None): Приводит к тому, что Ren'Py возвращается из текущего вызова уровня Ren'Py.

Пауза

Эквивалентом оператора Инструкция Pause является функция renpy.pause().

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

Вызывает паузу в Ren'Py. Возвращает true, если пользователь кликнул для завершения паузы, и false, если пауза завершилась по тайм-ауту или была пропущена.

delay: Если указано, количество секунд, на которое Ren'Py должен приостановиться.

Следующие параметры должны передаваться как именованные аргументы:

predict

Если True, когда все предсказание — включая предсказание, запланированное с помощью renpy.start_predict() и renpy.start_predict_screen() — будет завершено, пауза закончится.

Это также заставляет Ren'Py отдавать приоритет предсказанию над плавностью отображения на время паузы. Из-за этого рекомендуется не отображать анимации во время предсказания.

Пауза все равно может завершиться и другими способами — когда пользователь кликает или пропускает, или когда истекает задержка (если она есть).

modal

Если True, пауза с таймером не завершится (будет удерживаться), пока отображается модальный экран. Если False, пауза завершится, даже если отображается модальный экран.

hard

Когда True, Ren'Py может запретить пользователю прерывать паузу кликом. Если игрок включает пропуск, жесткая пауза будет пропущена. Могут быть и другие обстоятельства, при которых жесткая пауза завершится раньше или помешает Ren'Py работать должным образом; это не будет считаться багами.

В целом, использовать жесткие паузы — это грубо. Когда пользователь кликает, чтобы продвинуться в игре, это явный запрос — пользователь хочет, чтобы игра продвинулась. Переопределять этот запрос — значит предполагать, что вы понимаете, чего хочет игрок, лучше, чем сам игрок.

tl;dr — не используйте 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, это должен быть displayable, который отображается, когда показан этот атрибут.
default: Если True, и не выбран никакой другой атрибут для этой группы, выбирается этот атрибут.

Также распознаются следующие именованные аргументы:

at: Трансформация или список трансформаций, которые применяются к изображению.
when: Строка, содержащая выражение when, описанное в разделе When. Displayable отображается только тогда, когда выражение удовлетворяется набором атрибутов, в данный момент применённых к layeredimage.
variant: Строка, задающая вариант атрибута. Используется как часть поиска displayable, когда image равно None.

Остальные именованные аргументы интерпретируются как свойства трансформации. Если какие-либо из них присутствуют, создаётся трансформация, которая оборачивает изображение. (Например, pos=(100, 200) можно использовать для смещения изображения на 100 пикселей по горизонтали и 200 по вертикали.)

Если параметр image опущен или равен None, и для LayeredImage был задан параметр image_format, image_format используется для генерации имени файла изображения.

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

Когда условие истинно, слой отображается. В противном случае ничего не отображается.

Используется для реализации одной инструкции if, elif или else в layeredimage (для else, condition должен быть "True"). Несколько Condition затем могут быть переданы в ConditionGroup, чтобы эмулировать полную конструкцию if/elif/else.

condition: Это должна быть строка, содержащая условие Python, которое определяет, будет ли отображаться слой.
image: Если не None, это должен быть displayable, который отображается, когда условие истинно.
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 0x7b24a9406d40>, attribute_function=None, offer_screen=None, **kwargs)

Это объект, подобный изображению, который при показе с правильным набором атрибутов отображает displayable, созданный путём составления вместе displayable'ов, связанных с этими атрибутами.

attributes: Это должен быть список объектов Attribute, Condition, ConditionGroup или displayable. Каждый из них представляет displayable, который может отображаться или не отображаться как часть изображения. Элементы в этом списке расположены в порядке от заднего к переднему, где первый элемент находится дальше от зрителя, а последний — ближе всего. Передача displayable напрямую эквивалентна инструкции always в layeredimage.
at: Трансформация или список трансформаций, которые применяются к displayable после его параметризации.
name: Имя layeredimage. Используется как часть имён компонентов изображения.
image_format: Когда данное изображение является строкой, и этот параметр указан, имя изображения интерполируется в image_format для создания имени файла изображения. Например, "sprites/eileen/{image}.png" будет искать изображение в подкаталоге sprites. (Это не используется автоматическими группами, которые ищут изображения, а не файлы изображений.)
format_function: Функция, которая используется вместо layeredimage.format_function для форматирования информации об изображении в displayable.
attribute_function: Если не None, функция, которая вызывается с набором атрибутов, переданных изображению, и возвращает набор атрибутов, используемый для выбора слоёв. Она вызывается при определении слоёв для отображения, после того как сами атрибуты были выбраны. Может использоваться для выражения сложных зависимостей между атрибутами или для случайного выбора атрибутов.
offer_screen: Определяет, учитывается ли доступная область при размещении и определении размеров дочерних элементов (когда они имеют переменный размер). Если False, доступная область учитывается, а если True — нет. Если None, по умолчанию используется config.layeredimage_offer_screen.

Дополнительные именованные аргументы могут содержать свойства трансформации. Если какие-либо из них присутствуют, создаётся трансформация, которая оборачивает результирующее изображение. Оставшиеся именованные аргументы передаются в Fixed, который создаётся для хранения слоя. Если не переопределено явно, xfit и yfit для Fixed установлены в true, что означает, что он будет сжиматься до наименьшего размера, который вмещает все отображаемые изображения слоёв.

LayeredImage не является displayable и не может быть использован во всех местах, где можно использовать displayable. Это связано с тем, что он требует указания имени изображения (обычно включающего атрибуты изображения). Таким образом, он должен отображаться либо через инструкцию scene или show, либо через строку с именем изображения, используемую как displayable.

add(a)

a: Объект Attribute, Condition, ConditionGroup или displayable.

Этот метод добавляет предоставленный слой в список слоёв layeredimage так, как если бы он был передан в аргументе attributes конструктору.