Экраны и язык экранов

То, что видит пользователь в игре на Ren'Py, можно разделить на изображения и пользовательский интерфейс. Изображения показываются пользователю с помощью инструкций scene, show и hide и обычно являются частью повествования. Всё остальное, что видит пользователь, — это часть пользовательского интерфейса, который настраивается с помощью экранов.

Экраны могут отображаться четырьмя способами:

  • Неявно, при выполнении инструкций сценария. Например, инструкция say вызовет отображение экрана say.

  • Автоматически. Например, Ren'Py отобразит экран main_menu при запуске или когда пользователь вернётся в главное меню.

  • Как действие, связанное с кнопкой, кнопкой мыши или клавишей на клавиатуре. По умолчанию экран save показывается, когда пользователь нажимает правую кнопку мыши или клавишу Escape. Также можно определить наэкранную кнопку, которая будет показывать экран save.

  • Явно, с помощью инструкций, вызывающих отображение экранов.

Одновременно может отображаться более одного экрана.

У экранов есть две основные функции. Первая — отображение информации пользователю. Информация может отображаться с помощью текста, шкал (баров) и изображений. Часть информации, отображаемой таким образом, жизненно важна для игрового процесса. Например, экран say используется для отображения диалогов, включая имя персонажа и то, что он говорит.

Другая функция экрана — позволить пользователю взаимодействовать с игрой. Кнопки и шкалы (бары) позволяют пользователю вызывать действия и настраивать значения. Ren'Py включает в себя набор предопределённых действий, позволяющих пользователю продвигаться по игре, управлять настройками, загружать и сохранять игры и выполнять множество других действий. Разработчик игры также может писать новые действия на Python.

Экраны обновляются в начале каждого взаимодействия и каждый раз при перезапуске взаимодействия. Обратите внимание, что инструкция with None не вызывает взаимодействия и, следовательно, не обновит экран. При необходимости для этого будет достаточно with Pause(0).

С экраном связана область видимости, которая задаёт значения некоторым переменным. В экранах существуют различные типы переменных, которые разрешаются в порядке, указанном в следующем списке:

  • Во-первых, локальные переменные. Они существуют только в экране, который включается в другой с помощью инструкции use, а не отображается (или вызывается) сам по себе. Они очень похожи на экранные переменные (см. ниже) и создаются так же, за исключением того, что локальные переменные доступны только для используемого экрана. Они устанавливаются с помощью SetLocalVariable и других действий, либо через блок или строку Python в используемом экране. Действия, такие как SetScreenVariable, не будут работать с локальными переменными.

    • Локальные параметры — это параметры, принимаемые используемым экраном. Они находятся в той же области видимости, что и локальные переменные, и подчиняются тем же правилам и ограничениям, что и параметры экрана — см. ниже.

  • Если имя не может быть найдено среди локальных переменных — или если мы не находимся в экране, который используется другим экраном — имя ищется среди экранных переменных. Это переменные, созданные с помощью внутриэкранных инструкций 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"

Первая строка — это инструкция screen, инструкция языка Ren'Py, используемая для объявления экрана. Имя экрана — say, так что это экран, используемый для отображения диалогов. Он принимает два параметра: who и what.

Экран содержит окно с идентификатором "window". В этом окне находится вертикальный блок (vbox), и расстояние между элементами в этом блоке составляет 10 пикселей. Он содержит два текстовых поля: одно для отображения имени говорящего, а другое — для отображения его реплики.

Синтаксис языка экранов

Большинство инструкций языка экранов имеют общий синтаксис. (Некоторые управляющие инструкции имеют другой синтаксис.) Инструкция начинается в начале строки с ключевого слова.

Если инструкция принимает параметры, они следуют сразу за ключевым словом. Параметры — это простые выражения, разделённые пробелами, если не указано иное.

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

Если инструкция заканчивается двоеточием ::, она принимает блок. Каждая строка в блоке может быть одним из двух:

  • Списком свойств.

  • Инструкцией языка экранов.

Инструкция screen

Инструкция screen — это инструкция языка сценариев Ren'Py, которая используется для объявления нового экрана. Она разбирается в соответствии с общим синтаксисом языка экранов.

Она принимает один параметр — имя экрана. Это имя, а не выражение. Она принимает следующие свойства:

modal

Если True, экран является модальным. Модальный экран не позволяет пользователю взаимодействовать с отображаемыми объектами под ним, за исключением стандартной раскладки клавиш. Это свойство вычисляется один раз при запуске игры.

sensitive

Выражение, определяющее, является ли экран чувствительным (активным) или нет. Это выражение вычисляется как минимум один раз за взаимодействие.

tag

Интерпретируется как имя, а не как выражение. Указывает тег, связанный с этим экраном. Отображение экрана заменяет другие экраны с таким же тегом. Это можно использовать, чтобы гарантировать, что в одном и том же контексте отображается только один экран меню.

zorder

Это свойство контролирует, насколько близко к пользователю отображается экран. Чем больше число, тем ближе экран к пользователю. По умолчанию равно 0.

variant

Если присутствует, должна быть строкой или списком строк, указывающей вариант определяемого экрана. См. Варианты экранов.

style_prefix

Строка, которая используется как префикс для стиля дочерних элементов этого экрана, как описано ниже.

layer

Строка, задающая имя слоя, на котором экран отображается по умолчанию.

roll_forward

Если true, прямая перемотка будет включена, когда экран используется в инструкции call screen. Если false, прямая перемотка отключена, а если None или не указано, используется значение config.call_screen_roll_forward.

При прямой перемотке из инструкции call screen, возвращаемые значения и терминальные переходы сохраняются, но другие побочные эффекты не происходят. Это означает, что если экран содержит только действия Jump() и Return(), то включать roll_forward безопасно. Другие действия могут иметь побочные эффекты, которые не проявятся во время прямой перемотки.

Если первая строка экрана является строкой Python, она используется как docstring для экрана. Docstring можно получить с помощью renpy.get_screen_docstring().

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

     tag example
     zorder 1
     modal False

     text "Hello, World."

Экран может принимать список параметров:

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

Если у экрана нет параметров, ему всё равно следует указать пустые скобки. Если какой-либо другой экран use-ит экран без скобок, различия в поведении описаны в разделе, касающемся инструкции use. Если ни один другой экран не use-ит данный экран, отсутствие скобок приводит к чистой неэффективности во внутренней работе Ren'py, см. раздел об оптимизации экранов касательно параметров.

Инструкции пользовательского интерфейса

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

Все инструкции пользовательского интерфейса принимают следующие общие свойства:

at

Это может быть transform, список transform-ов или анонимный transform (transform, определённый непосредственно в at)

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

screen hello_title():
    text "Hello." at hello_t
    text "Hello." at transform:
        align (0.2, 0.5) alpha 0.0
        linear 0.5 alpha 1.0

Эти transform-ы используются для обёртывания этого отображаемого объекта. Внешние события show, hide, replace и replaced доставляются transform-у тогда и только тогда, когда он добавлен непосредственно на экран.

Например, если vbox обёрнут в transform и добавлен непосредственно на экран, события доставляются этому transform-у. Но если transform оборачивает textbutton, который добавлен в vbox, этот второй transform не получает событий.

Одна и та же инструкция может иметь и свойство at, и at transform. Свойство должно идти первым и применяется первым.

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

    text "The Title of the Game":
        at sepia, truecenter
        at transform:
            alpha 0.0
            linear 0.5 alpha 1.0
default_focus

Если задано и имеет значение true, отображаемый объект получает фокус по умолчанию. Когда несколько отображаемых объектов имеют это свойство, их значения сравниваются, и объект с наибольшим значением default_focus становится фокусом по умолчанию.

Фокус по умолчанию используется только тогда, когда последнее взаимодействие не было щелчком мыши, движением мыши или касанием.

extra_alt

Используется для указания дополнительного альтернативного текста для Самоозвучивание (самоозвучивания). Если определено, дополнительный альтернативный текст озвучивается игроку при нажатии клавиши '?', когда самоозвучивание включено.

Свойство extra_alt наследуется всеми дочерними элементами отображаемого объекта, если у них не задан более конкретный extra_alt.

Дополнительный альтернативный текст предназначен для предоставления игрокам с нарушениями зрения дополнительной информации о группах отображаемых объектов.

focus

Принимает строку или целое число и даёт отображаемому объекту имя для целей фокусировки. Ren'Py ищет структурное сходство между именами фокуса при решении, какому отображаемому объекту дать фокус в начале взаимодействия. Если блоку дано имя фокуса, и третья кнопка в этом блоке была в фокусе в конце взаимодействия, то в начале следующего взаимодействия будет выделена третья кнопка блока с таким же именем.

group_alt

Используется для указания префикса группы для Самоозвучивание (самоозвучивания). Когда самоозвучивание включено, префикс группы озвучивается при первом фокусе на отображаемом объекте с этим префиксом, но не будет повторяться до тех пор, пока фокус не перейдет к отображаемому объекту с другим префиксом группы.

Свойство group_alt наследуется всеми дочерними элементами отображаемого объекта, если у них не задан более конкретный group_alt.

id

Идентификатор для инструкции пользовательского интерфейса. При отображении экрана можно передать значения свойств для отображаемых объектов с заданным идентификатором. Некоторые экраны требуют создания отображаемого объекта с определённым идентификатором.

Когда отображаемый объект создаётся с id, этот id сохраняется как строка в атрибуте с именем id на объекте Displayable.

prefer_screen_to_id

Если true, то когда свойство задано и экраном, и через идентификатор отображаемого объекта, используется свойство экрана. Если false (по умолчанию), используется свойство отображаемого объекта. (Это можно использовать, чтобы определить, переопределяет ли экран свойства, установленные персонажем Character.)

style

Строка, задающая имя стиля, применяемого к этому отображаемому объекту. Стиль задаёт значения по умолчанию для свойств стиля.

style_prefix

Задаёт префикс для стиля этого отображаемого объекта и всех его дочерних элементов, если у этих дочерних элементов не задан более конкретный стиль или префикс стиля.

Имя стиля создаётся путём конкатенации префикса стиля, подчёркивания и суффикса стиля. Суффикс стиля либо указывается с помощью style_suffix, либо определяется типом отображаемого объекта.

Например, если vbox имеет префикс стиля "pref", ему будет присвоен стиль "pref_vbox". Если не задан более конкретный стиль или префикс стиля, кнопка внутри этого vbox будет иметь стиль "pref_button".

Стили, к которым обращаются таким образом, создаются автоматически, если стиль не существует. Установка префикса None удаляет префикс для этого отображаемого объекта и его дочерних элементов.

style_group

Псевдоним для style_prefix, использовавшийся в старых версиях Ren'Py.

style_suffix

Указывает суффикс, который объединяется со style_prefix для создания имени стиля. Если это "small_button", а префикс стиля — "pref", будет использоваться стиль "pref_small_button".

Если префикс стиля не используется, это значение используется напрямую как имя стиля. Суффикс стиля применяется только к одному отображаемому объекту, а не к объекту и всем его дочерним элементам.

tooltip

Назначает всплывающую подсказку этому отображаемому объекту. Когда отображаемый объект получает фокус, значение этого свойства будет доступно через функцию GetTooltip(). См. раздел Всплывающие подсказки (Tooltips) для более подробной информации.

Объекты, передаваемые в tooltip, должны поддерживать сравнение на равенство. Если равенство не поддерживается, может возникнуть бесконечный цикл.

arguments

Кортеж или список, содержащий дополнительные позиционные аргументы, которые передаются отображаемому объекту.

properties

Словарь, содержащий дополнительные свойства, передаваемые отображаемому объекту.

Многие инструкции пользовательского интерфейса принимают классы свойств стиля или свойств transform. Эти свойства могут иметь связанный с ними префикс стиля, который определяет, когда они применяются. Например, если тексту присвоено свойство hover_size, оно устанавливает размер текста при наведении на него курсора.

Инструкции пользовательского интерфейса принимают конструкцию as, которая принимает имя переменной без кавычек. Отображаемый объект, созданный инструкцией, присваивается этой переменной. (Пример можно найти в документации по drag and drop.)

Bar

Создаёт горизонтально-ориентированную шкалу (бар), которую можно использовать для просмотра или изменения данных. Принимает следующие свойства:

value

Текущее значение шкалы. Это может быть либо объект bar value, либо число.

range

Максимальное значение шкалы. Обязательно, если value является числом.

adjustment

Объект ui.adjustment(), который настраивает эта шкала.

changed

Если указано, должна быть функцией Python. Функция вызывается со значением настройки (adjustment), когда оно изменяется.

hovered

Действие, выполняемое, когда шкала получает фокус.

unhovered

Действие, выполняемое, когда шкала теряет фокус.

released

Действие, выполняемое, когда кнопка на шкале отпущена. Оно будет выполнено, даже если шкала не изменила своего значения.

Должно быть указано одно из свойств 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, для определения состояния выбора будет использоваться действие (action).

sensitive

Выражение, определяющее, является ли кнопка активной или нет. Это выражение вычисляется как минимум один раз за взаимодействие. Если не указано или равно None, для определения активности будет использоваться действие (action).

keysym

Строка, задающая keysym, описывающий клавишу, при нажатии которой выполняется действие этой кнопки.

alternate_keysym

Строка, задающая keysym, описывающий клавишу, при нажатии которой выполняется альтернативное действие этой кнопки.

Также принимает:

Принимает одного дочернего элемента. Если передано ноль, два или более дочерних элементов, они неявно добавляются в fixed, который, в свою очередь, добавляется к кнопке.

Dismiss

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

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

Принимает следующие свойства:

action

Действие, выполняемое при активации dismiss. Это свойство обязательно.

keysym

Строка, задающая keysym, описывающий клавишу, при нажатии которой выполняется действие этого dismiss. Это заменяет keysym "dismiss" по умолчанию.

modal

По умолчанию dismiss является модальным, предотвращая обработку событий отображаемыми объектами "за" ним.

Также принимает:

Вот пример использования dismiss:

screen dismiss_test():

    dismiss action Return()

    frame:
        modal True

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

        has vbox

        text "This is a very important message.":
            xalign 0.5
            textalign 0.5

        # Dismiss сам по себе может быть непонятен, поэтому добавим и кнопку.
        textbutton "Dismiss":
            xalign 0.5
            action Return()

Смотрите также, как dismiss используется совместно с nearrect.

Fixed

Создаёт область, в которую можно добавлять дочерние элементы. По умолчанию, fixed расширяется, чтобы заполнить доступное пространство, но свойства xmaximum и ymaximum могут это изменить.

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

Инструкция fixed не принимает параметров и принимает следующие группы свойств:

Принимает любое количество дочерних элементов, которые добавляются в fixed.

Часто нет необходимости явно создавать отображаемый объект fixed. Каждый экран содержится внутри fixed, и многие инструкции языка экранов автоматически создают fixed, если у них два или более дочерних элемента.

screen ask_are_you_sure:
    fixed:
         text "Are you sure?" xalign 0.5 yalign 0.3
         textbutton "Yes" xalign 0.33 yalign 0.5 action Return(True)
         textbutton "No" xalign 0.66 yalign 0.5 action Return(False)

Frame

Фрейм — это окно с фоном, предназначенное для отображения элементов пользовательского интерфейса, таких как кнопки, шкалы и текст. Принимает следующие группы свойств:

Принимает один дочерний элемент. Если передано ноль, два или более дочерних элементов, то для их содержания создаётся fixed.

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

        vbox:
            text "Display"
            null height 10
            textbutton "Fullscreen" action Preference("display", "fullscreen")
            textbutton "Window" action Preference("display", "window")

Grid

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

Принимает два параметра. Первый — количество столбцов в сетке, а второй — количество строк. Если сетка не заполнена полностью, оставшиеся ячейки заполняются отображаемым объектом null.

Grid принимает несколько свойств, связанных с размещением дочерних элементов:

transpose

Если False (по умолчанию), строки заполняются раньше столбцов. Если True, то сначала заполняются столбцы.

right_to_left

Если True, ячейки заполняются справа налево, а не по умолчанию слева направо.

bottom_to_top

Если True, ячейки заполняются снизу вверх, а не по умолчанию сверху вниз.

Также принимает:

Должно быть передано (количество столбцов * количество строк) дочерних элементов. Передача другого количества элементов является ошибкой.

screen grid_test:
     grid 2 3:
         text "Top-Left"
         text "Top-Right"

         text "Center-Left"
         text "Center-Right"

         text "Bottom-Left"
         text "Bottom-Right"

Hbox

Отображает свои дочерние элементы бок о бок в невидимом горизонтальном блоке. Не принимает параметров, но принимает следующие группы свойств:

Дочерние отображаемые объекты пользовательского интерфейса добавляются в блок.

screen hbox_text():
    hbox:
         text "Left"
         text "Right"

Imagebutton

Создаёт кнопку, состоящую из изображений, которые меняются при наведении на них курсора. Не принимает параметров, но принимает следующие свойства:

auto

Используется для автоматического определения изображений, используемых этой кнопкой. Это должна быть строка, содержащая %s. Если это так и одно из свойств изображения опущено, %s заменяется на имя этого свойства, и полученное значение используется по умолчанию.

Например, если auto равно "button_%s.png", а idle опущено, то idle по умолчанию будет "button_idle.png". Аналогично, если auto равно "button %s", будет использоваться изображение button idle.

Поведение auto можно настроить, изменив config.imagemap_auto_function.

insensitive

Изображение, используемое, когда кнопка неактивна.

idle

Изображение, используемое, когда кнопка не в фокусе.

hover

Изображение, используемое, когда кнопка в фокусе.

selected_idle

Изображение, используемое, когда кнопка выбрана и не в фокусе.

selected_hover

Изображение, используемое, когда кнопка выбрана и в фокусе.

action

Действие, выполняемое при активации кнопки. Это также определяет, является ли кнопка активной, если sensitive не указано или равно None, и выбрана ли она, если selected не указано или равно None.

alternate

Действие, выполняемое при альтернативной активации кнопки. Альтернативная активация происходит, когда игрок щёлкает правой кнопкой мыши на кнопке на платформах с мышью или когда игрок долго нажимает на кнопку на сенсорных платформах.

hovered

Действие, выполняемое, когда кнопка получает фокус.

unhovered

Действие, выполняемое, когда кнопка теряет фокус.

selected

Выражение, определяющее, выбрана ли кнопка или нет. Это выражение вычисляется как минимум один раз за взаимодействие. Если не указано или равно None, для определения состояния выбора будет использоваться действие (action).

sensitive

Выражение, определяющее, является ли кнопка активной или нет. Это выражение вычисляется как минимум один раз за взаимодействие. Если не указано или равно None, для определения активности будет использоваться действие (action).

keysym

Строка, задающая keysym, описывающий клавишу, при нажатии которой выполняется действие этой кнопки.

alternate_keysym

Строка, задающая 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

Создаёт область для ввода текста, позволяющую пользователю вводить текст. Когда пользователь нажимает Enter, текст будет возвращён взаимодействием. (Когда экран вызывается через call screen, результат будет помещён в переменную _return.)

Из-за ограничений в поддерживающих библиотеках, на платформе Android и в вебе отображаемый объект input ограничен алфавитными символами.

Инструкция input не принимает параметров, и у неё есть следующие свойства:

value

Объект input value, который использует это поле ввода. Объекты InputValue определяют, откуда берётся значение по умолчанию, что происходит при изменении текста, что происходит при нажатии Enter и является ли текст редактируемым по умолчанию.

Это свойство не следует указывать одновременно с default и changed.

default

Текст по умолчанию в этом поле ввода.

length

Максимальная длина текста в этом поле ввода.

pixel_width

Максимальная ширина поля ввода в пикселях. Если ввод символа приведёт к превышению этой ширины, нажатие клавиши игнорируется.

allow

Строка, содержащая символы, которые разрешено вводить в это поле. (По умолчанию разрешены все символы.)

exclude

Строка, содержащая символы, которые запрещено вводить в это поле. (По умолчанию "{}").

copypaste

Если True, становится возможным копирование и вставка в это поле ввода. (По умолчанию отключено.)

prefix

Неизменяемая строка для добавления в начало текста, который ввёл пользователь.

suffix

Неизменяемая строка для добавления в конец текста, который ввёл пользователь.

changed

Функция Python, которая вызывается с тем, что ввёл пользователь, когда строка изменяется.

mask

Если задано, строка, которая заменяет каждый отображаемый символ в тексте. Это можно использовать для маскировки пароля.

Если не False, то это период мигания курсора по умолчанию. Переопределяет config.input_caret_blink.

multiline

Если True, становится возможным перемещать курсор на следующую строку с помощью клавиатуры (по умолчанию Shift+Enter, можно изменить, изменив config.keymap['input_next_line']).

action

Если не None, это действие, которое выполняется при нажатии Enter, когда поле ввода активно. Это переопределяет действие по умолчанию, которое заключается в возвращении введённого значения.

Обычно это используется с value, которое сохраняет ввод в переменную, чтобы действие могло получить к ней доступ.

arrowkeys

Если True (по умолчанию), клавиши со стрелками могут использоваться для перемещения курсора влево и вправо внутри поля ввода. Если False, клавиши со стрелками игнорируются, что делает их доступными для других целей, например, для изменения фокуса.

Также принимает:

Эта инструкция не принимает дочерних элементов.

screen input_screen():
    window:
        has vbox

        text "Введите ваше имя."
        input default "Джозеф П. Блоу, эсквайр"

Key

Создаёт привязку клавиши, которая запускает действие при нажатии клавиши или одной из клавиш в заданном списке. "Клавиша" здесь используется в широком смысле, поскольку она также поддерживает события от джойстика и мыши.

Key принимает один позиционный параметр — строку, задающую клавишу для привязки. Смотрите раздел Настройка раскладки клавиатуры для описания доступных keysyms. Принимает два свойства:

action

Задаёт действие, которое выполняется при нажатии клавиши. Это обязательное свойство.

capture

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

Не принимает дочерних элементов.

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

Label

Создаёт окно в стиле label, а затем помещает текст внутрь этого окна. Вместе эта комбинация используется для подписи элементов внутри frame.

Принимает один позиционный аргумент — текст метки. Принимает свойство:

text_style

Имя стиля, используемого для текста кнопки. Если не указано, и свойство style является строкой, то к этой строке добавляется "_text" для получения стиля текста по умолчанию.

text_-

У других свойств с префиксом text этот префикс отбрасывается, и они передаются отображаемому объекту text.

Также принимает:

Не принимает дочерних элементов.

screen display_preference():
    frame:
        has vbox

        label "Дисплей"
        textbutton "Полноэкранный" action Preference("display", "fullscreen")
        textbutton "Оконный" action Preference("display", "window")

Mousearea

Mousearea — это область экрана, которая может реагировать на наведение или увод курсора мыши. В отличие от кнопки, mousearea не получает фокус, поэтому можно иметь mousearea с кнопками внутри. Инструкция mousearea не принимает параметров, но имеет следующие свойства:

hovered

Действие, которое выполняется, когда мышь входит в область mousearea.

unhovered

Действие, которое выполняется, когда мышь покидает область mousearea.

focus_mask

Стилевое свойство focus_mask, которое может быть отображаемым объектом или None. Если это отображаемый объект, mousearea будет считаться наведённой только если мышь находится над непрозрачной частью этого отображаемого объекта. (Этот отображаемый объект не показывается пользователю.)

Также принимает:

Не принимает дочерних элементов.

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

Примечание

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

Nearrect принимает следующие свойства:

rect

Если задано, должен быть прямоугольником (x, y, w, h), относительно которого позиционируется дочерний элемент, как описано ниже.

focus

Если задано, должна быть строкой. Эта строка передаётся в эквивалент GetFocusRect() для нахождения прямоугольника. Если прямоугольник фокуса с таким именем найден, дочерний элемент отрисовывается.

Передача "tooltip" в это свойство использует местоположение последнего отображаемого объекта, который был в фокусе при отображении всплывающей подсказки.

Если присутствует, переопределяет rect.

preferred_side

Одно из значений: "left", "top", "right", "bottom", чтобы предпочесть это положение для nearrect. Если с одной стороны недостаточно места, используется противоположная сторона. По умолчанию, предпочтительной стороной является "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 (соотв. по Y) вычисляется с использованием обычных правил, используя свойства xpos и xanchor (соотв. ypos, yanchor) дочернего элемента, а также свойства, которые их устанавливают, например xalign. Свойства pos относятся к координате X (соотв. Y) прямоугольника, и в случае числа с плавающей запятой — к его ширине (соотв. высоте).

В конце позиционирования, свойства xoffset и yoffset применяются как обычно.

Если дочерний элемент nearrect является transform, ему передаются события show и hide. Однако позиция изменится мгновенно. Nearrect лучше всего работает в верхней части экрана, с transform'ами и позиционированием, применяемыми к его дочернему элементу, а не к самому nearrect.

Одно из применений nearrect — для выпадающих меню:

default difficulty = "Лёгкая"

screen select_difficulty():

    # Этот frame может быть очень сложной компоновкой, если потребуется.
    frame:
        align (.5, .3)
        padding (20, 20)

        has vbox

        # Это кнопка, на которую нужно нажать, чтобы открыть выпадающий список.
        textbutton "Сложность: [difficulty]":

            # Это действие захватывает прямоугольник фокуса и, делая это,
            # отображает выпадающий список.
            action CaptureFocus("diff_drop")

        textbutton "Готово":
            action Return()

    # Здесь могли бы быть любые другие элементы экрана, но nearrect должен
    # быть на верхнем уровне, и последним, что показывается, кроме его дочернего элемента.

    # Только если фокус был захвачен, отображать выпадающий список.
    # Можно использовать showif вместо обычного if.
    if GetFocusRect("diff_drop"):

        # Если игрок кликает вне frame, закрыть выпадающий список.
        # Действие ClearFocus закрывает этот выпадающий список.
        dismiss action ClearFocus("diff_drop")

        # Это позиционирует отображаемый объект рядом с (обычно под) кнопкой выше.
        nearrect:
            focus "diff_drop"

            # Наконец, этот frame содержит варианты выбора в выпадающем списке,
            # причём каждый использует ClearFocus для закрытия списка.
            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

Инструкция null вставляет пустую область на экран. Это можно использовать для создания отступов между элементами. Инструкция 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' нижний правый, и так далее.

Side принимает следующие свойства:

spacing

Промежуток между строками и столбцами сетки.

Side принимает следующие группы свойств:

При отрисовке сначала определяются размеры углов, затем сторон, а затем центра. Углы и стороны отрисовываются с доступной областью 0, поэтому может потребоваться задать им минимальный размер (с помощью xminimum или yminimum), чтобы они вообще отрисовались. Порядок размещения дочерних элементов контролируется сверху вниз при их добавлении (т.е. также в порядке подстрок в аргументе), последний будет самым верхним. Это можно отключить с помощью config.keep_side_render_order.

Дочерние элементы соответствуют записям в списке мест, поэтому их должно быть столько же, сколько записей в списке.

screen side_test():
     side "c tl br":
          text "Центр"
          text "Верх-Лево"
          text "Низ-Право"

Text

Инструкция text отображает текст. Она принимает один параметр — текст для отображения. Также принимает следующие группы свойств:

Не принимает дочерних элементов.

screen hello_world():
    text "Привет, мир." size 40

Textbutton

Создаёт кнопку, содержащую текстовую метку. Кнопка принимает один параметр — текст, который будет включён в кнопку. Она принимает следующие свойства:

action

Действие, которое выполняется при активации кнопки. Оно также контролирует, активна ли кнопка, если sensitive не задано или равно None, и выбрана ли кнопка, если selected не задано или равно None.

alternate

Действие, которое выполняется, если кнопка активирована альтернативным способом. Альтернативная активация происходит, когда игрок щелкает правой кнопкой мыши по кнопке на платформе с мышью или когда игрок долго нажимает на кнопку на сенсорной платформе.

hovered

Действие, выполняемое, когда кнопка получает фокус.

unhovered

Действие, выполняемое, когда кнопка теряет фокус.

selected

Выражение, которое определяет, выбрана кнопка или нет. Это выражение вычисляется как минимум один раз за взаимодействие. Если не задано или равно None, для определения выбранности будет использоваться action.

sensitive

Выражение, которое определяет, активна кнопка или нет. Это выражение вычисляется как минимум один раз за взаимодействие. Если не задано или равно None, для определения активности будет использоваться action.

keysym

Строка, задающая keysym, описывающий клавишу на клавиатуре, нажатие которой вызывает действие этой кнопки.

alternate_keysym

Строка, задающая keysym, описывающий клавишу на клавиатуре, нажатие которой вызывает альтернативное действие этой кнопки.

text_style

Имя стиля, используемого для текста кнопки. Если не указано, и свойство style является строкой, то к этой строке добавляется "_text" для получения стиля текста по умолчанию.

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, таймер не сработает, если он заблокирован модальным экраном. Если False или не задано, таймер сработает, даже если он заблокирован модальным экраном.

Timer не принимает дочерних элементов.

screen timer_test():
    vbox:
         textbutton "Да." action Jump("yes")
         textbutton "Нет." action Jump("no")

    timer 3.0 action Jump("too_slow")

Transform

Применяет 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 displayable'ы добавляются в box.

screen vbox_test():
    vbox:
         text "Верх."
         text "Низ."

Viewport

Viewport — это область экрана, которую можно прокручивать перетаскиванием, колесиком мыши или с помощью полос прокрутки. Её можно использовать для отображения части чего-то, что больше экрана. Она принимает следующие свойства:

child_size

Размер, который предлагается дочернему элементу для отрисовки. Кортеж (xsize, ysize). Обычно это можно опустить, если дочерний элемент может вычислить свой собственный размер. Если какой-либо компонент равен None, используется размер дочернего элемента.

mousewheel

Должно быть одним из:

False

Игнорировать колесо мыши. (По умолчанию.)

True

Прокручивать по вертикали.

"horizontal"

Прокручивать по горизонтали.

"change"

Прокручивать viewport по вертикали, только если это приведёт к его перемещению. Если нет, событие колеса мыши передаётся остальной части интерфейса. (Например, если указано "change", размещение key "viewport_wheeldown" action Return() перед viewport'ом приведёт к возврату с экрана, если viewport прокрутится ниже дна.)

"horizontal-change"

Комбинирует горизонтальную прокрутку с режимом change.

draggable

Если True, перетаскивание мыши будет прокручивать viewport. Это также может быть вариант, в этом случае viewport будет перетаскиваемым, если этот вариант активен. (Например, draggable "touch".)

edgescroll

Управляет прокруткой, когда мышь достигает края viewport'а. Если не None, должен быть кортежем из двух или трех элементов:

  • Первый элемент кортежа — это расстояние от края viewport'а, с которого начинает действовать прокрутка, в пикселях.

  • Второй элемент — максимальная скорость прокрутки в пикселях в секунду.

  • Если присутствует, третий элемент — это функция, которая корректирует скорость прокрутки в зависимости от того, насколько близко указатель находится к краю. Функция должна принимать число от -1.0 до 1.0 и возвращать число в том же диапазоне. Функция по умолчанию возвращает свой ввод и реализует пропорциональную прокрутку. Функция, которая возвращала бы -1.0 или 1.0 в зависимости от знака своего ввода, реализовала бы прокрутку с постоянной скоростью.

xadjustment

ui.adjustment(), используемый для оси x viewport'а. Если опущен, создается новый adjustment.

yadjustment

ui.adjustment(), используемый для оси y viewport'а. Если опущен, создается новый adjustment.

xinitial

Начальное горизонтальное смещение viewport'а. Может быть целым числом, задающим количество пикселей, или float'ом, задающим долю возможного смещения.

yinitial

Начальное вертикальное смещение viewport'а. Может быть целым числом, задающим количество пикселей, или float'ом, задающим долю возможного смещения.

scrollbars

Если не None, вместе с этим viewport'ом добавляются полосы прокрутки. Это работает путем создания компоновки side и размещения созданного viewport'а в центре. Если scrollbars равно "horizontal", горизонтальная полоса прокрутки размещается под viewport'ом. Если scrollbars равно "vertical", вертикальная полоса прокрутки размещается справа от viewport'а. Если scrollbars равно "both", создаются и горизонтальная, и вертикальная полосы прокрутки.

Когда scrollbars не None, viewport принимает свойства с префиксами:

  • Свойства, начинающиеся с viewport_, передаются viewport'у.

  • Свойства, начинающиеся с side_, передаются side.

  • Свойства, начинающиеся с scrollbar_, передаются горизонтальной полосе прокрутки, если она существует.

  • Свойства, начинающиеся с vscrollbar_, передаются вертикальной полосе прокрутки, если она существует.

Также принимаются свойства без префиксов. Свойства стиля позиции передаются side, в то время как другие свойства без префиксов передаются viewport'у.

arrowkeys

Если true, viewport можно прокручивать с помощью клавиш со стрелками влево, вправо, вверх и вниз. Это имеет приоритет над обычной функцией этих клавиш, которая заключается в изменении фокуса. Однако клавиши со стрелками будут изменять фокус, когда viewport достигает своих пределов.

pagekeys

Если true, viewport можно прокручивать вверх и вниз с помощью клавиш pageup и pagedown. Это отключает обычную функциональность этих клавиш, которая заключается в вызове отката (rollback) и перемотки вперед (rollforward).

Кроме того, он принимает следующие группы стилевых свойств:

Принимает один дочерний элемент. Если предоставлены ноль, два или более дочерних элементов, создается fixed для их размещения.

Чтобы сделать viewport прокручиваемым, часто лучше всего присвоить ему id и затем использовать XScrollValue() и YScrollValue() с этим id.

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 (viewport grid) объединяет viewport и сетку (grid) в один отображаемый объект. Vpgrid принимает несколько дочерних элементов (как и сетка) и оптимизирован так, чтобы отрисовывались только те дочерние элементы, которые видны в пределах viewport.

Vpgrid предполагает, что все дочерние элементы имеют одинаковый размер, который определяется размерами первого дочернего элемента. Если vpgrid отображается некорректно, убедитесь, что все дочерние элементы имеют одинаковый размер.

Для vpgrid должно быть задано хотя бы одно из свойств cols и rows. Если одно из них опущено или равно None, другое определяется автоматически на основе размера, отступов и количества дочерних элементов. Если строка или столбец оказываются неполными, для заполнения оставшегося пространства используются null displayable.

Vpgrid принимает следующие свойства:

cols

Количество столбцов в сетке.

rows

Количество строк в сетке.

transpose

Если true, столбцы заполняются раньше строк. Значение по умолчанию зависит от свойств cols и rows. Если задано cols, столбцы заполняются раньше строк, в противном случае — строки раньше столбцов.

Кроме того, vpgrid принимает все свойства, которые может принимать viewport, и следующие группы стилевых свойств:

Если задано свойство scrollbar, свойства с префиксами передаются в vpgrid так же, как и во viewport. (Свойства с префиксом 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 "Button [i]":
                xysize (200, 50)
                action Return(i)

Window

Window — это окно с фоном, предназначенное для отображения внутриигровых диалогов. Оно принимает следующие группы свойств:

Оно принимает один дочерний элемент. Если передано ноль, два или более дочерних элементов, создаётся контейнер fixed для их размещения.

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

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

Инструкции для карт изображений

Удобный способ создания экрана, особенно для тех, кто мыслит визуально, — это использование карт изображений (imagemap). При создании imagemap инструкция imagemap используется для указания до шести изображений. Изображения для hotspot и hotbar используются для выделения прямоугольных областей из основного изображения и назначения им действий и значений.

Вот пример экрана настроек, использующего imagemap.

screen preferences():

    tag menu
    use navigation

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

        hotspot (740, 232, 75, 73) action Preference("display", "fullscreen") alt _("Display Fullscreen")
        hotspot (832, 232, 75, 73) action Preference("display", "window") alt _("Display Window")
        hotspot (1074, 232, 75, 73) action Preference("transitions", "all") alt _("Transitions All")
        hotspot (1166, 232, 75, 73) action  Preference("transitions", "none") alt _("Transitions None")

        hotbar (736, 415, 161, 20) value Preference("music volume") alt _("Music Volume")
        hotbar (1070, 415, 161, 20) value Preference("sound volume") alt _("Sound Volume")
        hotbar (667, 535, 161, 20) value Preference("voice volume") alt _("Voice Volume")
        hotbar (1001, 535, 161, 20) value Preference("text speed") alt _("Text Speed")

Imagemap

Инструкция imagemap используется для определения карты изображений. Она не принимает параметров и имеет следующие свойства:

auto

Используется для автоматического определения изображений для этого imagemap. Это должна быть строка, содержащая %s. Если это так, и одно из свойств изображения опущено, %s заменяется на имя этого свойства, и полученное значение используется по умолчанию.

Например, если auto равно "imagemap_%s.png", а idle не указано, то idle по умолчанию станет "imagemap_idle.png". Если auto равно "imagemap %s", будет использовано изображение imagemap idle.

Поведение auto можно настроить, изменив config.imagemap_auto_function.

ground

Изображение, используемое для частей imagemap, которые не являются hotspot или hotbar.

insensitive

Изображение, используемое, когда hotspot или hotbar неактивны.

idle

Изображение, используемое, когда hotspot не выбран и не в фокусе, а также для пустой части hotbar без фокуса.

hover

Изображение, используемое, когда hotspot не выбран, но находится в фокусе, а также для пустой части hotbar в фокусе.

selected_idle

Изображение, используемое, когда hotspot выбран, но не в фокусе, а также для заполненной части hotbar без фокуса.

selected_hover

Изображение, используемое, когда hotspot выбран и находится в фокусе, а также для заполненной части hotbar в фокусе.

alpha

Если true (по умолчанию), hotspot получает фокус только тогда, когда курсор мыши находится над непрозрачной областью изображения hover. Если false, hotspot получает фокус, как только курсор оказывается в его прямоугольных границах.

cache

Если true (по умолчанию), данные hotspot кэшируются для улучшения производительности ценой некоторого дополнительного места на диске.

Она принимает следующие группы свойств:

Imagemap создаёт контейнер fixed, что позволяет добавлять в него любые дочерние элементы (а не только hotspot и hotbar).

Hotspot

Hotspot — это кнопка, представляющая собой часть содержащего её imagemap. Она принимает один параметр — кортеж (x, y, width, height), задающий область imagemap, которая является кнопкой. Она также принимает следующие свойства:

action

Действие, выполняемое при активации кнопки. Оно также определяет, является ли кнопка активной (sensitive) и выбранной (selected).

alternate

Действие, которое выполняется, если hotspot активирован альтернативным способом. Альтернативная активация происходит, когда игрок нажимает на hotspot правой кнопкой мыши (на платформах с мышью) или совершает долгое нажатие (на сенсорных платформах).

hovered

Действие, выполняемое при получении кнопкой фокуса.

unhovered

Действие, выполняемое при потере кнопкой фокуса.

selected

Выражение, определяющее, выбрана кнопка или нет. Это выражение вычисляется как минимум один раз за интеракцию. Если не указано или равно None, для определения выбранности используется действие.

sensitive

Выражение, определяющее, активна кнопка или нет. Это выражение вычисляется как минимум один раз за интеракцию. Если не указано или равно None, для определения активности используется действие.

keysym

Строка, задающая keysym, описывающий клавишу на клавиатуре, которая при нажатии вызывает действие этой кнопки.

alternate_keysym

Строка, задающая keysym, описывающий клавишу на клавиатуре, которая при нажатии вызывает альтернативное действие этой кнопки.

Она также принимает:

Hotspot создаёт контейнер fixed, что позволяет добавлять в него дочерние элементы. Этот fixed имеет ту же область, что и hotspot, а значит, дочерние элементы будут позиционироваться относительно hotspot.

Для hotspot следует указывать стилевое свойство alt, чтобы функция самоозвучивания Ren'Py работала корректно.

Hotbar

Hotbar — это полоса (bar), состоящая из части содержащего её imagemap. Она принимает один параметр — кортеж (x, y, width, height), задающий область imagemap, которая является полосой. Она также принимает следующие свойства:

value

Текущее значение полосы. Это может быть либо объект значения полосы, либо число.

range

Максимальное значение полосы. Требуется, если value является числом.

adjustment

Объект ui.adjustment(), который настраивает эта полоса.

Необходимо указать либо value, либо adjustment. Кроме того, эта функция принимает:

Не принимает дочерних элементов.

Для hotbar следует указывать стилевое свойство alt, чтобы функция самоозвучивания Ren'Py работала корректно.

Инструкция Add

Инструкция add является особенной, поскольку она добавляет на экран уже существующий отображаемый объект. В результате она не принимает свойств, общих для инструкций пользовательского интерфейса.

Add

Добавляет изображение или другой отображаемый объект на экран. Опционально принимает свойства трансформации. Если хотя бы одно свойство трансформации задано, создается Transform для обертывания изображения, и свойства передаются этой трансформации.

Если отображаемый объект равен None, на экран ничего не добавляется.

Не принимает дочерних элементов.

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

Продвинутые отображаемые объекты

Помимо часто используемых инструкций, язык экранов содержит инструкции, соответствующие продвинутым отображаемым объектам (displayables). Соответствие между отображаемым объектом и инструкцией простое. Позиционные параметры отображаемых объектов становятся позиционными параметрами инструкции. Именованные аргументы и соответствующие стилевые свойства становятся свойствами языка экранов.

Продвинутые инструкции для отображаемых объектов:

Areapicker

Предназначен для использования в инструментах разработки; позволяет пользователю выбрать прямоугольную область на экране. Принимает следующие свойства:

cols

Если не None (по умолчанию), делит экран на сетку с указанным количеством столбцов.

rows

Если не None (по умолчанию), делит экран на сетку с указанным количеством строк.

position

Если не None (по умолчанию), это функция, вызываемая с x и y координатами места, где пользователь впервые нажал, округленными до сетки.

changed

Вызывается с прямоугольником — кортежем (x, y, width, height) — всякий раз, когда пользователь изменяет выбранную область.

finished

Вызывается с прямоугольником — кортежем (x, y, width, height) — когда пользователь завершает выбор области.

persist

Если true, дочерний элемент будет показан в выбранной области после завершения выбора. Если false (по умолчанию), дочерний элемент будет скрыт после завершения выбора.

Принимает следующую группу свойств:

Areapicker принимает один дочерний элемент. Дочерний элемент отображается на экране в выбранной области.

Drag

Создаёт Drag, который можно перетаскивать по экрану. За исключением d, который предоставляется языком экранов, он принимает все свойства, определённые в этом классе.

Он также принимает следующие свойства:

Drag принимает один дочерний элемент, или можно использовать стилевое свойство child для предоставления дочернего элемента и его вариантов в фокусе.

Draggroup

Создаёт DragGroup. Принимает те же свойства, что и DragGroup, а также следующие свойства:

Группа перетаскивания (drag group) может иметь ноль или более объектов drag в качестве дочерних элементов. Она также может иметь в качестве дочерних элементов не-drag объекты, и в этом случае она функционирует как fixed.

Инструкция Has

Инструкция has позволяет указать контейнер для использования, вместо fixed, для инструкций, принимающих только один дочерний элемент. Инструкция has может использоваться только внутри инструкции, которая принимает один дочерний элемент. За ключевым словом has следует (на той же строке) другая инструкция, которая должна создавать отображаемый объект-контейнер, способный принимать более одного дочернего элемента.

Инструкция has изменяет способ парсинга блока, в котором она находится. Дочерние отображаемые объекты, созданные в этом блоке, добавляются в контейнер, а не в родительский отображаемый объект. Именованные аргументы для родительского отображаемого объекта не допускаются после инструкции has. В одном блоке можно использовать несколько инструкций has.

Инструкция has может быть предоставлена как дочерняя для следующих инструкций:

  • button

  • frame

  • window

Инструкции has можно передать следующие инструкции в качестве контейнера.

  • 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 "What would you like to do?"
         textbutton "Art Club" action SetScreenVariable("club", "art")
         textbutton "Writing Club" action SetScreenVariable("club", "writing")

         if club:
             textbutton "Select" action Return(club)

For

Инструкция for похожа на инструкцию for в Python, за исключением того, что она не поддерживает конструкцию 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 использует это значение, чтобы гарантировать, что трансформации и другое состояние будут связаны с правильной итерацией. Если вы наблюдаете странное поведение при добавлении или удалении элементов из списка, по которому вы итерируетесь, возможно, вам стоит использовать конструкцию index.

If

Инструкция if в языке экранов аналогична инструкции if в Python/Ren'Py. Она поддерживает конструкции if, elif и else.

screen skipping_indicator():
    if renpy.is_skipping():
         text "Skipping."
    else:
         text "Not Skipping."

On

Инструкция on позволяет экрану выполнять действие при возникновении события. Она принимает один параметр — строку с названием события. Это должно быть одно из следующих значений:

  • "show"

    Это событие происходит, когда экран отображается (обратите внимание, что если экран с таким же тегом уже отображается, событием будет "replace").

  • "hide"

    Это событие происходит, когда экран скрывается (обратите внимание, что если он заменяется экраном с таким же тегом, событием будет "replaced").

  • "replace"

    Это событие происходит, когда экран отображается, заменяя экран с таким же тегом.

  • "replaced"

    Это событие происходит, когда экран заменяется экраном с таким же тегом.

Затем она принимает свойство action, указывающее действие, которое нужно выполнить при возникновении события.

screen preferences():
    frame:
        has hbox

        text "Display"
        textbutton "Fullscreen" action Preferences("display", "fullscreen")
        textbutton "Window" action Preferences("display", "window")

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

Use

Инструкция use позволяет одному экрану включать в себя другой. Инструкция use принимает имя используемого экрана. За ним может опционально следовать список аргументов в скобках.

Если у используемого экрана нет скобок, он имеет доступ на чтение и запись к области видимости текущего экрана, обновлённой любыми именованными аргументами, переданными через инструкцию use. В противном случае его область видимости инициализируется результатом присваивания аргументов этим параметрам.

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

        has hbox

        add FileScreenshot(slot)
        vbox:
            text FileTime(slot, empty="Empty Slot.")
            text FileSaveName(slot)


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

Инструкция use может принимать конструкции-свойства, id и as. Эти свойства должны располагаться после списка параметров, если он присутствует, и должны находиться на первой строке инструкции, а не в её блоке.

Конструкция id полезна только тогда, когда два экрана с одним и тем же тегом используют один и тот же экран. В этом случае, когда один экран заменяет другой, состояние используемого экрана передается от старого к новому.

transform t1():
    xpos 150
    linear 1.0 xpos 0

screen common():
    text "Test" 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 "Ed"
    text "Captain"

screen kelly(num):
    text "Kelly"
    text "First Officer"

screen bortus(num):
    text "Bortus"
    text "Second Officer"

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 "You can drag me."

    use movable_frame((0, 100)):
        vbox:
            text "You can drag me too."
            textbutton "Got it!" action Return(True)

Конструкции use и transclude лежат в основе определяемых разработчиком инструкций языка экранов.

Python

Язык экранов также включает однострочные и многострочные инструкции Python, которые могут выполнять код Python. Python выполняется в области видимости экрана.

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

screen python_screen:
    python:
        test_name = "Test %d" % test_number

    text test_name

    $ test_label = "test_%d" % test_label

    textbutton "Run Test" action Jump(test_label)

Инструкция Showif

Инструкция showif принимает условие. Она показывает свои дочерние элементы, когда условие истинно, и скрывает их, когда условие ложно. Когда у дочерних элементов showif есть трансформации, она будет передавать им события ATL для управления процессом показа и скрытия, чтобы Ren'Py мог анимировать этот процесс.

Инструкция showif оборачивает свои дочерние элементы в отображаемый объект, который управляет процессом показа и скрытия.

Несколько инструкций showif можно сгруппировать в единую конструкцию showif/elif/else, подобно инструкции if. В отличие от инструкции if, showif выполняет все свои блоки, включая Python, даже если условие ложно. Это связано с тем, что инструкции showif необходимо создать дочерние элементы, которые она будет скрывать.

Showif передает своим дочерним элементам три события:

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 "Three" size 100 at cd_transform
    elif n == 2:
        text "Two" size 100 at cd_transform
    elif n == 1:
        text "One" size 100 at cd_transform
    else:
        text "Liftoff!" size 100 at cd_transform

label start:
    call screen countdown

Экранные операторы

Помимо оператора screen, существуют три оператора языка сценариев Ren'Py, которые работают с экранами.

Show Screen

Оператор show screen вызывает отображение экрана. Он принимает имя экрана, серию необязательных выражений (clauses) и опциональные Python-аргументы, которые передаются экрану. renpy.show_screen() и renpy.call_screen() принимают дополнительные специфические ключевые слова.

Оператор show screen принимает следующие выражения, некоторые из которых похожи на выражения оператора Инструкция show:

as

Выражение as принимает имя. Если не указано, по умолчанию используется тег, связанный с экраном (см. Инструкция screen). Если и он не указан, по умолчанию используется имя экрана.

onlayer

Слой, на котором будет показан экран.

zorder

Z-порядок для отображения экрана. Если не указан, по умолчанию используется z-порядок, связанный с экраном. Если и он не указан, по умолчанию равен 0.

expression

Если задано ключевое слово expression, выражение, следующее за ним, будет вычислено как имя экрана. Чтобы передать аргументы экрану с ключевым словом expression, отделите выражение и аргументы ключевым словом pass:

$ screen_name = "my_screen"
show screen expression screen_name
# Или если нужно передать какие-то аргументы
show screen expression screen_name pass ("Foo", message="Bar")
with

Интерпретируется так же, как и выражение with оператора show:

show screen clock_screen with dissolve
nopredict

Ключевое слово nopredict не принимает значений. Оно предотвращает предзагрузку экрана. Во время предзагрузки экрана вычисляются его аргументы. Убедитесь, что вычисление аргументов экрана не вызывает непредвиденных побочных эффектов.

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

Если вычисление аргументов экрана вызывает побочные эффекты, ваша игра может вести себя непредсказуемым образом.

Экраны, показанные таким образом, отображаются до тех пор, пока их явно не скроют. Это позволяет использовать их для наложения (overlays).

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 заменяет A (что скрывает его)
hide screen A # скрывает B, помеченный тегом A

show screen A as B
show screen B as C

hide screen B
# скрывает экран A, показанный как B
# экран B, показанный как C, остаётся видимым

hide screen B
# скрывает экран B

Он также принимает выражение onlayer, которое по умолчанию устанавливается на слой screens.

Выражение with интерпретируется так же, как и выражение with оператора Инструкция show.

Подобно оператору 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.

Это можно использовать для отображения imagemap. Imagemap может поместить значение в переменную _return с помощью действия Return() или перейти к метке с помощью действия Jump().

Оператор call screen принимает различные необязательные выражения, большинство из которых аналогичны выражениям оператора Show Screen:

as

Выражение as принимает имя. Если не указано, по умолчанию используется тег, связанный с экраном (см. Инструкция screen). Если и он не указан, по умолчанию используется имя экрана.

onlayer

Слой, на котором будет показан экран.

zorder

Z-порядок для отображения экрана. Если не указан, по умолчанию используется z-порядок, связанный с экраном. Если и он не указан, по умолчанию равен 0.

nopredict

Это ключевое слово предотвращает предзагрузку экрана. Во время предзагрузки экрана вычисляются его аргументы. Убедитесь, что вычисление аргументов экрана не вызывает непредвиденных побочных эффектов.

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

Если вычисление аргументов экрана вызывает побочные эффекты, ваша игра может вести себя непредсказуемым образом.

expression

Подобно оператору show screen, call screen также принимает ключевое слово expression, позволяя использовать произвольное выражение в качестве имени экрана. Оно также используется с ключевым словом pass, позволяющим передавать аргументы экрану.

with

В операторе call screen выражение with вызывает переход (transition) при показе экрана.

Это не вызывает with None перед показом экрана, поэтому все операторы show и hide перед экраном будут выполнены. Если вам нужен with None, добавьте его.

Поскольку вызов экрана является взаимодействием, а взаимодействия вызывают неявный with None, использование оператора with после инструкции call screen не заставит экран исчезнуть с помощью перехода, так как экран уже будет скрыт. Чтобы отключить неявный переход with None, передайте специальный ключевой аргумент _with_none=False экрану, как в примере ниже.

Другие способы вызова переходов также работают, например, список действий [ With(dissolve), Return() ].

call screen my_imagemap

call screen my_screen(side_effect_function()) nopredict

# Показывает экран с переходом dissolve
call screen my_other_screen with dissolve
# Экран мгновенно скрывается с None, затем выполняется переход pixellate
with pixellate

# Показывает экран с переходом dissolve и скрывает его с переходом 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, так и на новых устройствах с сенсорным экраном, таких как смартфоны и планшеты на базе Android. Варианты экранов позволяют игре предоставлять несколько версий одного экрана и использовать ту версию, которая лучше всего подходит для оборудования, на котором она запущена.

Ren'Py выбирает вариант экрана для использования, просматривая варианты в том порядке, в котором они перечислены в config.variants. Используется первый найденный существующий вариант.

Если присутствует переменная окружения RENPY_VARIANT, config.variants инициализируется путем разделения значения переменной по пробелам, а затем добавления None. Установка RENPY_VARIANT в значение вроде "medium tablet touch" или "small phone touch" позволяет тестировать на ПК экраны, предназначенные для устройств Android.

Если переменная окружения отсутствует, список вариантов составляется автоматически, проходя по следующему списку по порядку и выбирая элементы, которые применимы к текущей платформе.

"steam_deck"

True, если игра запущена на Steam Deck или эквивалентном оборудовании.

"steam_big_picture"

True, если игра запущена в режиме Steam Big Picture.

"large"

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

"medium"

Экран, на котором можно читать мелкий текст, но кнопки, возможно, придётся увеличить для удобства нажатия. Используется для планшетов.

"small"

Экран, на котором текст необходимо увеличить, чтобы его можно было прочитать. Используется для телефонов и телевизоров. (Телевизор может быть физически большим, но он часто находится далеко, что затрудняет чтение.)

"tablet"

Определяется на устройствах с сенсорным экраном, у которых диагональ экрана 6 дюймов или более. (В целом, вместо "tablet" следует использовать "medium".)

"phone"

Определяется на устройствах с сенсорным экраном, у которых диагональ экрана меньше 6 дюймов. На таком маленьком устройстве важно делать кнопки достаточно большими, чтобы пользователь мог легко их выбирать. (В целом, вместо "phone" следует использовать "small".)

"touch"

Определяется на устройствах с сенсорным экраном.

"tv"

Определяется на устройствах телевизионного типа.

"firetv"

Определяется на консоли Amazon Fire TV. ("tv" и "small" также определены.)

"chromeos"

Определяется при запуске в виде приложения Android на Chromebook.

"android"

Определяется на всех устройствах Android.

"ios"

Определяется на устройствах iOS, таких как iPad (где также определены "tablet" и "medium") и iPhone (где также определены "phone" и "small").

"mobile"

Определяется на мобильных платформах, таких как Android, iOS и мобильные веб-браузеры.

"pc"

Определяется на Windows, Mac OS X и Linux. Ожидается, что на ПК есть мышь и клавиатура, позволяющие наводить курсор на кнопки и точно указывать.

"web"

Определяется при запуске в веб-браузере.

None

Определяется всегда.

Пример определения варианта экрана:

# Вариант экрана hello_world, используемый на маленьких
# устройствах с сенсорным экраном.
screen hello_world():
     tag example
     zorder 1
     modal False
     variant "small"

     text "Hello, World." size 30

Смотрите также

Экранные действия, значения и функции : полный список действий и других инструментов для использования с экранами.

Оптимизация языка экранов : несколько полезных способов сделать экраны максимально эффективными.

Экраны и Python : перейти от использования стандартных инструментов Ren'Py к его расширению.