Основы языка

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

Файлы

Сценарий игры на Ren'Py состоит из всех файлов с расширением .rpy, находящихся в директории game/. Ren'Py рассматривает каждый из этих файлов и использует их содержимое в качестве сценария.

Как правило, нет никакой разницы между сценарием, написанным в одном большом файле, и сценарием, разбитым на несколько файлов. Управление может передаваться в пределах сценария (в том числе между файлами) путём перехода или вызова метки в другом файле. Это делает разделение сценария на файлы вопросом личного стиля: одни разработчики предпочитают иметь небольшие файлы (например, один на событие или один на день), в то время как другие предпочитают один большой сценарий.

Чтобы ускорить время загрузки, Ren'Py при запуске компилирует файлы .rpy в файлы .rpyc. Когда файл .rpy изменяется, файл .rpyc будет обновлён при запуске Ren'Py. Однако, если файл .rpyc существует без соответствующего файла .rpy, будет использован файл .rpyc. Это может привести к проблемам, если файл .rpy будет удалён, переименован или перемещён без удаления файла .rpyc — сценарий, который он содержит, всё равно будет выполнен.

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

Базовая директория

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

Базовая директория создаётся внутри "директории проектов" (Projects Directory), которую можно установить в лаунчере при создании новой игры. Например, если ваша директория проектов называется renpygames, а ваша игра — "HelloWorld", то вашей базовой директорией будет renpygames/HelloWorld.

Директория игры

Директория игры — это директория с именем "game" внутри базовой директории. Например, если ваша базовая директория renpygames/HelloWorld, то директория игры будет renpygames/HelloWorld/game.

Директория игры содержит все файлы, используемые игрой. Она, включая все поддиректории, сканируется на наличие файлов .rpy и .rpyc, и они объединяются для формирования игрового сценария. Она сканируется на наличие архивных файлов .rpa, и они автоматически используются игрой. Наконец, когда Ren'Py принимает или рассматривает путь к файлу, этот путь (за очень редкими исключениями) указывается относительно директории игры (но обратите внимание, что config.searchpath может изменить это поведение).

Комментарии

Файл сценария Ren'Py может содержать комментарии. Комментарий начинается со знака решётки (#) и заканчивается в конце строки, содержащей комментарий. Исключением является случай, когда знак решётки является частью строки.

# This is a comment.
show black # this is also a comment.

"# This isn't a comment, since it's part of a string."

Ren'Py игнорирует комментарии, поэтому сценарий обрабатывается так, как будто комментариев в нём не было.

Логические строки

Файл сценария разбивается на логические строки. Логическая строка всегда начинается в начале строки файла. Логическая строка заканчивается в конце строки, за исключением случаев, когда:

Последний символ в строке — обратный слэш (\).
Строка содержит открывающую скобку ((, { или [), которая ещё не была закрыта соответствующей закрывающей скобкой (соответственно, ), } или ]).
Конец строки встречается внутри строки — любой строки, даже в одинарных кавычках, в отличие от правил Python.

После того как логическая строка заканчивается, следующая логическая строка начинается в начале следующей строки файла.

Большинство инструкций в языке Ren'Py состоят из одной логической строки.

"This is one logical line"

"Since this line contains a string, it continues
 even when the line ends."

$ a = [ "Because of parenthesis, this line also",
        "spans more than one line." ]

Пустые строки игнорируются и не считаются логическими строками.

Отступы и блоки

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

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

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

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

"This statement, and the if statement that follows, are part of a block."

if True:

    "But this statement is part of a new block."

    "This is also part of that new block."

"This is part of the first block, again."

Элементы инструкций

Инструкции Ren'Py состоят из нескольких основных частей.

Ключевое слово

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

Имя

Имя начинается с буквы или символа подчёркивания, за которыми следуют ноль или более букв, цифр и символов подчёркивания. Для наших целей символы Unicode в диапазоне от U+00a0 до U+fffd считаются буквами.

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

Имена, начинающиеся с одного символа подчёркивания (_), зарезервированы для внутреннего использования Ren'Py, если иное не указано в документации.

Когда имя начинается с двух символов подчёркивания (__) но не заканчивается ими, оно изменяется на специфичную для файла версию этого имени.

Имя изображения

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

Например, возьмём имя изображения mary beach night happy. Тег изображения — mary, а атрибуты изображения — beach, night и happy.

Слова at, as, behind, onlayer, with и zorder не могут быть использованы в качестве частей имени изображения.

Строка

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

Символ обратного слэша (\) используется для экранирования кавычек, специальных символов, таких как % (записывается как \%), [ (записывается как \[) и { (записывается как \{). Он также используется для включения символов новой строки с помощью последовательности \n.

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

'Strings can\'t contain their delimiter, unless you escape it.'

"There will be a space between the two following
 words."

"There will be a line break between\nthese."

"And there will be three spaces between\ \ \ these."

Поддерживается префикс r, и он следует более-менее тем же правилам, что и в Python. Другие префиксы, такие как u, b или f, не поддерживаются. Строки в тройных кавычках обычно не принимаются в местах, где ожидается обычная строка, а когда принимаются, они обычно дают другой результат — см. Режим монолога в качестве примера.

Примечание

Это относится к строкам, находящимся непосредственно в сценарии Ren'Py, например, в Инструкция say или Внутриигровые меню. Строки, находящиеся внутри инструкций Python или в выражениях (см. ниже), следуют обычным правилам Python.

Простое выражение

Простое выражение — это выражение Python, используемое для включения Python в некоторые части сценария Ren'Py. Простое выражение начинается с:

Имени.
Строки.
Числа.
Любого выражения Python в скобках.

За этим может следовать любое количество:

Точки, за которой следует имя.
Выражения Python в скобках.

Например, 3, (3 + 4), foo.bar и foo(42) — всё это простые выражения. Но 3 + 4 таковым не является, так как выражение заканчивается после строки.

Выражение Python

Выражение Python — это произвольное выражение Python, которое не может содержать двоеточия. Они используются для выражения условий в инструкциях if и while.

Общий синтаксис инструкций

Большинство инструкций Ren'Py имеют общий синтаксис. За исключением Инструкция say, они начинаются с ключевого слова, которое вводит инструкцию. За этим ключевым словом следует параметр, если инструкция его принимает.

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

Если инструкция принимает блок, строка заканчивается двоеточием (:). В противном случае, строка просто заканчивается.

Синтаксис выражений Python

Примечание

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

Многие части Ren'Py принимают выражения Python. Например, определение нового персонажа включает вызов функции Character(). Хотя выражения Python очень мощные, для написания базовой игры на Ren'Py требуется лишь малая часть этой мощи.

Вот краткое изложение выражений Python.

Целое число

Целое число — это число без десятичной точки. 3 и 42 — целые числа.

Число с плавающей точкой

Число с плавающей точкой (сокращение от floating-point number) — это число с десятичной точкой. .5, 7. и 9.0 — все они являются числами с плавающей точкой.

Строка

Строки в Python начинаются с " или ', и заканчиваются тем же символом. \ используется для экранирования конечного символа и для введения специальных символов, таких как перенос строки (\n). В отличие от строк Ren'Py, строки Python не могут занимать несколько строк и не могут быть ограничены символом `.

True, False, None

Существуют три специальных значения. True — это истинное значение, False — ложное. None представляет отсутствие значения.

Кортеж

Кортежи используются для представления контейнеров, где важно количество элементов. Например, можно использовать 2-кортеж (также называемый парой) для представления ширины и высоты, или 4-кортеж (x, y, ширина, высота) для представления прямоугольника.

Кортежи начинаются с левой скобки (, состоят из нуля или более выражений Python, разделённых запятыми, и заканчиваются правой скобкой ). В качестве особого случая, кортеж из одного элемента должен иметь запятую после элемента. Например:

()
(1,)
(1, "#555")
(32, 24, 200, 100)

Список

Списки используются для представления контейнеров, где количество элементов может варьироваться. Список начинается с [, содержит список выражений, разделённых запятыми, и заканчивается ]. Например:

[]
[1]
[1, 2]
[1, 2, 3]

Переменная

Выражения Python могут использовать переменные, которые хранят значения, определённые с помощью инструкций Инструкция Define или Инструкция Default. Имя переменной следует правилам имени, как объяснено в разделе Элементы инструкций. Например:

playername
love_love_points
trebuchet2_range

Доступ к полю

Модули и объекты Python имеют поля, доступ к которым можно получить, указав после выражения (обычно переменной) точку и имя поля. Например:

config.screen_width

состоит из переменной (config), за которой следует доступ к полю (screen_width).

Вызов

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

Character("Eileen", type=adv, color="#0f0")

мы вызываем функцию Character(). Ей передан один позиционный аргумент, строка "Eileen". Ей переданы два именованных аргумента: type со значением переменной adv и color со строковым значением "#0f0".

Вызывать можно не только функции, но и другие объекты, которые широко известны как вызываемые объекты (callables).

При чтении этой документации вы можете увидеть сигнатуру функции, подобную этой:

Sample(name, delay, position=(0, 0), **properties): Пример функции, которая на самом деле не существует в Ren'Py, а используется только в документации.

Эта функция:

Имеет имя "Sample"
Имеет два позиционных параметра, name и delay. В реальной функции типы этих параметров были бы уточнены в документации.
Имеет один именованный аргумент, position, который имеет значение по умолчанию (0, 0).

Поскольку функция заканчивается на **properties, это означает, что она может принимать свойства стиля в качестве дополнительных именованных аргументов. Другие специальные записи — это *args, что означает, что функция принимает произвольное количество позиционных параметров, и **kwargs, что означает, что она принимает широкий спектр именованных параметров, которые обычно объясняются в документации функции.

Когда вы видите символ / отдельно в сигнатуре функции, это означает, что параметры перед ним являются исключительно позиционными и не должны передаваться по ключу. И наоборот, когда вы видите символ * отдельно, это означает, что параметры после него являются исключительно именованными, то есть их следует передавать только с использованием синтаксиса name=value.

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