Текст

Ren'Py содержит несколько способов отображения текста. Инструкции say и menu в первую очередь предназначены для отображения текста пользователю. Пользовательский интерфейс часто содержит текст, отображаемый с помощью инструкций языка экранов text, textbutton и label. Эти функции, наряду с другими, создают отображаемые объекты (displayables) Text() и выводят их на экран.

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

1. Перевод текста.

2. Интерполяция данных в текст.

3. Стилизация текста с использованием стилей и текстовых тегов.

4. Разметка стилизованного текста.

5. Отрисовка текста на экране.

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

Управляющие символы

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

(обратная косая черта)

Символ обратной косой черты используется для вставки управляющих последовательностей при написании строки в Ren'Py или Python. Некоторые распространённые управляющие последовательности:

\" (обратная косая черта-двойная кавычка)

Включает двойную кавычку в строку, заключённую в двойные кавычки.

\' (обратная косая черта-одинарная кавычка)

Включает одинарную кавычку в строку, заключённую в одинарные кавычки.

\ (обратная косая черта-пробел)

Включает дополнительный пробел в строку Ren'Py. По умолчанию в тексте скрипта Ren'Py соседние пробельные символы объединяются в один пробел.

\n (обратная косая черта-n)

Включает символ новой строки в текст.

\\ (двойная обратная косая черта)

Включает символ обратной косой черты в текст.

\% (обратная косая черта-процент)

Включает защищённый символ процента в текст. Также можно написать %%: оба варианта защиты в итоге приведут к выводу одного символа %.

[ (левая квадратная скобка)

Левая квадратная скобка используется для введения интерполяции значения в текст. Чтобы включить одну левую квадратную скобку в ваш текст, удвойте её — напишите [[.

{ (левая фигурная скобка)

Левая фигурная скобка используется для введения текстового тега. Чтобы включить левую фигурную скобку в ваш текст, удвойте её — напишите {{.

【 (левая линзовидная скобка)

Левая линзовидная скобка используется для введения текста ruby/фуриганы. Чтобы включить левую линзовидную скобку в ваш текст, удвойте её — напишите 【【.

Интерполяция данных

Ren'Py поддерживает интерполяцию данных в текстовую строку перед её отображением. Например, если имя игрока хранится в переменной playername, можно написать такую строку диалога:

g "Welcome to the Nekomimi Institute, [playername]!"

Ren'Py будет искать переменные в следующем порядке:

• При использовании на экране — локальные переменные экрана.

• Переменные, найденные в пространстве имён interpolate.

• Переменные, найденные в глобальном пространстве имён.

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

g "My first name is [player.names[0]]."

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

g "I like you [100.0 * points / max_points:.2] percent!"

Форматирование строк в Ren'Py заимствовано из синтаксиса форматирования строк PEP 3101. Ren'Py использует [ для введения интерполяции строк, потому что { уже был занят текстовыми тегами.

Наряду с флагами преобразования !s и !r, поддерживаемыми Python, Ren'Py поддерживает несколько дополнительных флагов. Флаг преобразования !q гарантирует, что текстовые теги будут правильно экранированы, так что отображение строки не приведёт к нежелательным конструкциям форматирования. Например:

g "Don't pull a fast one on me, [playername!q]."

Флаг !t переводит интерполированную строку:

if points > 5:
    $ mood = _("happy")
else:
    $ mood = _("annoyed")

g "I'm [mood!t] to see you."

Флаг !i выполняет дополнительную интерполяцию для интерполированной строки:

define earned_points_info = _("[points]{image=points.png} earned points")
g "I'm happy to see you you have [earned_points_info!ti]."

Это следует использовать для подстановки текста, внутри которого есть своя подстановка. Это часто полезно в языке экранов, см. Const Text.

Флаг !u переводит текст в верхний регистр, а флаг !l — в нижний. Флаг !c действует только на первый символ, делая его заглавным. Эти флаги можно комбинировать, например, !cl сделает заглавным первый символ, а остальной текст переведёт в нижний регистр.

Следует отметить, что:

• порядок, в котором указаны флаги, не меняет результат: !cl сделает то же самое, что и !lc.

• Дополнительные восклицательные знаки будут проигнорированы и не обойдут предыдущее правило: !l!c сделает то же самое, что и !c!l или !cl.

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

1. r/s (repr или str)

2. t (перевод)

3. i (рекурсивная интерполяция)

4. q (экранирование)

5. u (верхний регистр)

6. l (нижний регистр)

7. c (капитализация первого символа)

Стили и текстовые теги

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

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

Существует два типа текстовых тегов. Некоторые теги являются самозакрывающимися, в то время как другие позволяют использовать закрывающий тег. Закрывающий тег начинается с косой черты (/), и теги закрываются в порядке "последним вошёл — первым вышел". Каждый закрывающий тег должен соответствовать соответствующему открывающему. В противном случае Ren'Py выдаст предупреждение.

Например:

# Эта строка корректна.
"Plain {b}Bold {i}Bold-Italic{/i} Bold{/b} Plain"

# Эта строка некорректна и вызовет неправильное поведение.
"Plain {b}Bold {i}Bold-Italic{/b} Italic{/i} Plain"

Не обязательно закрывать все текстовые теги. Ren'Py закроет все теги, которые остались открытыми в конце текстового блока. Например:

"{size=+20}This is big!"

Некоторые текстовые теги принимают аргумент. В этом случае за именем тега следует знак равенства (=) и аргумент. Аргумент не может содержать символ правой фигурной скобки (}). Значение аргумента зависит от конкретного текстового тега.

Общие текстовые теги

Теги, которые применяются ко всему тексту:

a

Тег-якорь создаёт гиперссылку между собой и своим закрывающим тегом. Хотя поведение гиперссылки контролируется свойством стиля hyperlink_functions, обработчик по умолчанию имеет следующее поведение.

• Когда аргумент начинается с jump:, остальная часть аргумента — это метка для перехода.

• Когда аргумент начинается с call:, остальная часть аргумента — это метка для вызова. Как обычно, вызов завершает текущую инструкцию Ren'Py.

• Когда аргумент начинается с call_in_new_context:, остальная часть аргумента — это метка для вызова в новом контексте (с помощью renpy.call_in_new_context()).

• Когда аргумент начинается с show:, остальная часть аргумента — это экран для показа.

• Когда аргумент начинается с showmenu:, остальная часть аргумента — это игровой экран меню для показа.

• В противном случае аргумент — это URL-адрес, который открывается системным веб-браузером.

Если в аргументе нет раздела протокола, к нему добавляется config.hyperlink_protocol. Если config.hyperlink_protocol установлен в "jump", {a=label} и {a=jump:label} становятся эквивалентными. Создатели могут определять новые протоколы с помощью config.hyperlink_handlers.

label test:

    e "Why don't you visit {a=https://renpy.org}Ren'Py's home page{/a}?"

    e "Or {a=jump:more_text}here for more info{/a}."

    return

label more_text:

    e "In Hot Springs, Arkansas, there's a statue of Al Capone you can take a picture with."

    e "That's more info, but not the kind you wanted, is it?"

    return

alpha

Тег alpha отображает текст между собой и своим закрывающим тегом с указанной непрозрачностью. Непрозрачность должна быть значением от 0.0 до 1.0, что соответствует полной невидимости и полной непрозрачности соответственно. Если перед значением стоит префикс + или -, непрозрачность будет изменена на эту величину, а не полностью заменена. Если перед значением стоит префикс *, непрозрачность будет умножена на эту величину.

"{alpha=0.1}This text is barely readable!{/alpha}"
"{alpha=-0.1}This text is 10 percent more transparent than the default.{/alpha}"
"{alpha=*0.5}This text is half as opaque as the default.{/alpha}"

alt

Тег alt предотвращает отрисовку текста, но оставляет его доступным для системы преобразования текста в речь.

g "Good to see you! {image=heart.png}{alt}heart{/alt}"

См. также персонажа alt.

art

Тег альтернативного верхнего текста ruby (art) помечает текст между собой и своим закрывающим тегом как альтернативный верхний текст ruby. См. раздел о Тексте Ruby для получения дополнительной информации.

b

Тег полужирного начертания (bold) отображает текст между собой и своим закрывающим тегом полужирным шрифтом.

"An example of {b}bold test{/b}."

color

Тег цвета (color) отображает текст между собой и своим закрывающим тегом указанным цветом. Цвет должен быть в формате #rgb, #rgba, #rrggbb или #rrggbbaa.

"{color=#f00}Red{/color}, {color=#00ff00}Green{/color}, {color=#0000ffff}Blue{/color}"

cps

Тег символов в секунду (characters per second) устанавливает скорость отображения текста для текста между тегом и его закрывающим тегом. Если аргумент начинается со звёздочки, он воспринимается как множитель к текущей скорости текста. В противном случае аргумент задаёт скорость отображения текста в символах в секунду.

"{cps=20}Fixed Speed{/cps} {cps=*2}Double Speed{/cps}

feature

Тег feature включает или отключает функции разметки OpenType. Имя функции является частью тега, отделённой двоеточием. Аргументом должно быть 1 для включения функции или 0 для её отключения. Например, чтобы отключить лигатуры, используйте следующее:

"{feature:liga=0}Traffic{/feature} is light today."

Список функций разметки можно найти здесь.

font

Тег шрифта (font) отображает текст между собой и своим закрывающим тегом указанным шрифтом. Аргументом является имя файла шрифта для использования.

"Try out the {font=mikachan.ttf}mikachan font{/font}."

i

Тег курсива (italics) отображает текст между собой и своим закрывающим тегом курсивом.

"Visit the {i}leaning tower of Pisa{/i}."

image

Тег изображения (image) — это самозакрывающийся тег, который вставляет изображение в текст. Изображение должно быть высотой с одну строку текста. Аргументом должно быть либо имя файла изображения, либо имя изображения, определённого с помощью инструкции image.

g "Good to see you! {image=heart.png}{alt}heart{/alt}"

k

Тег кернинга (kerning) настраивает кернинг символов между собой и своим закрывающим тегом. Он принимает в качестве аргумента число с плавающей точкой, указывающее количество пикселей кернинга для добавления к каждой кернинговой паре. (Число может быть отрицательным для уменьшения кернинга.)

"{k=-.5}Negative{/k} Normal {k=.5}Positive{/k}"

noalt

Тег noalt предотвращает озвучивание текста системой преобразования текста в речь. Часто используется в сочетании с тегом alt для предоставления доступных и визуальных опций.

g "Good to see you! {noalt}<3{/noalt}{alt}heart{/alt}"

outlinecolor

Тег цвета обводки (outlinecolor) изменяет цвет всех обводок (включая тени) на заданный. Цвет должен быть в формате #rgb, #rgba, #rrggbb или #rrggbbaa. Он изменяет только существующие обводки, а не добавляет их.

"Let's have a {outlinecolor=#00ff00}Green{/outlinecolor} outline."

plain

Тег обычного текста (plain) гарантирует, что к тексту не будет применено полужирное начертание, курсив, подчёркивание или зачёркивание.

"{b}This is bold. {plain}This is not.{/plain} This is bold.{/b}"

rb

Тег нижнего текста ruby (rb) помечает текст между собой и своим закрывающим тегом как нижний текст ruby. См. раздел о Тексте Ruby для получения дополнительной информации.

rt

Тег верхнего текста ruby (rt) помечает текст между собой и своим закрывающим тегом как верхний текст ruby. См. раздел о Тексте Ruby для получения дополнительной информации.

s

Тег зачёркивания (strikethrough) рисует линию через текст между собой и своим закрывающим тегом.

g "It's good {s}to see you{/s}."

shader

Тег шейдера (shader) применяет текстовый шейдер к участку текста. Аргументом является имя шейдера для применения.

"This text is {shader=jitter:u__jitter=1.0, 3.0}jittery{/shader}."

См. Текстовые шейдеры для получения дополнительной информации.

size

Тег размера (size) изменяет размер текста между собой и своим закрывающим тегом. Аргументом должно быть целое число, которому опционально предшествует + или -. Если аргумент — просто целое число, размер устанавливается в это количество пикселей по высоте. В противном случае размер увеличивается или уменьшается на эту величину.

"{size=+10}Bigger{/size} {size=-10}Smaller{/size} {size=24}24 px{/size}."

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

"{size=*2}Twice as big{/size} {size=*0.5}half as big.{/size}"

space

Тег пробела (space) — это самозакрывающийся тег, который вставляет горизонтальное пространство в строку текста. В качестве аргумента он принимает целое число, указывающее количество пикселей пространства для добавления.

"Before the space.{space=30}After the space."

u

Тег подчёркивания (underline) подчёркивает текст между собой и своим закрывающим тегом.

g "It's good to {u}see{/u} you."

vspace

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

"Line 1{vspace=30}Line 2"

#

Текстовые теги, начинающиеся с #, игнорируются, но могут быть включены для различения строк при переводе.

"New{#playlist}"

Теги диалогового текста

Текстовые теги, которые применяются только к диалогам:

w

Тег ожидания (wait) — это самозакрывающийся тег, который ждёт, пока пользователь нажмёт кнопку мыши для продолжения. Если ему передан аргумент, он интерпретируется как число, и ожидание автоматически заканчивается через указанное количество секунд.

"Line 1{w} Line 1{w=1.0} Line 1"

p

Тег паузы в абзаце (paragraph pause) — это самозакрывающийся тег, который завершает текущий абзац и ждёт, пока пользователь нажмёт кнопку мыши для продолжения. Если ему передан аргумент, он интерпретируется как число, и ожидание автоматически заканчивается через указанное количество секунд.

"Line 1{p}Line 2{p=1.0}Line 3"

nw

Тег no-wait — это самозакрывающийся тег, который заставляет текущую строку диалога автоматически закрываться, как только будет отображён конец строки.

g "Looks like they're{nw}"
show trebuchet
g "Looks like they're{fast} playing with their trebuchet again."

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

g "I'm gonna fall in a few seconds!{nw=2}"
show g_gone

Тег no-wait будет ждать завершения самоозвучивания перед переходом к следующему действию.

fast

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

g "Looks like they're{nw}"
show trebuchet
g "Looks like they're{fast} playing with their trebuchet again."

При наличии тега {fast} озвучка будет продолжаться с предыдущей строки.

done

Текст после тега done не отображается. Зачем это может понадобиться? Чтобы избежать "прыжков" текста, когда adjust_spacing имеет значение True.

При наличии тега done строка диалога не добавляется в буфер истории. Если присутствует тег nw, он должен стоять перед тегом done.

g "Looks like they're{nw}{done} playing with their trebuchet again."
show trebuchet
g "Looks like they're{fast} playing with their trebuchet again."

clear

Тег clear имеет смысл только на отдельной строке в режиме монолога NVL. Он делает то же самое, что и инструкция nvl clear, но не завершает блок текста.

"""
Block 1 on page 1.

Block 2 on page 1.

{clear}

Block 1 on page 2.

etc.
"""

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

Теги стилей

Ren'Py поддерживает текстовые теги, которые обращаются к стилям. Это текстовые теги, у которых имя тега пустое. В этом случае аргумент воспринимается как имя стиля. Например, тег {=mystyle} обратится к стилю mystyle.

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

• antialias

• font

• size

• bold

• italic

• underline

• strikethrough

• color

• black_color

• kerning

Неанглийские языки

Шрифт по умолчанию в Ren'Py содержит символы для английского и многих других языков. Из-за соображений размера он не содержит символов, необходимых для отображения других языков, включая китайский, японский и корейский. Чтобы поддерживать эти языки, проект должен сначала изменить используемые шрифты.

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

define gui.language = "korean-with-spaces"

Это значение можно изменить с "unicode" по умолчанию в файле gui.rpy.

В японском языке существует несколько правил переноса строк. Мы рекомендуем начинать с "japanese-normal" и переходить к "japanese-loose" или "japanese-strict" для большего или меньшего количества возможностей для переноса соответственно.

define gui.language = "japanese-loose"

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

define gui.language = "greedy"

Более быстрый алгоритм переноса строк может не понадобиться, если игра не отображает огромные объёмы текста, как, например, в режиме NVL.

Алгоритмы переноса строк можно дополнительно настроить с помощью функции renpy.language_tailor().

Вертикальный текст

Когда установлено свойство стиля vertical, Ren'Py будет выводить текст в вертикальной ориентации. Текст пишется сверху вниз, справа налево.

Есть два текстовых тега, которые взаимодействуют с вертикальным текстом.

horiz

Включает текст с горизонтальной ориентацией внутрь вертикального текста.

vert

Включает текст с вертикальной ориентацией внутрь горизонтального текста. (Это не поворачивает текст в вертикальную ориентацию.)

Примечание

Если шрифт не содержит информации о межсимвольном расстоянии для вертикального текста, Ren'Py попытается синтезировать эту информацию из информации для горизонтального текста. Расстояние может не оставаться постоянным между релизами Ren'Py.

Текст Ruby

Текст ruby (также известный как фуригана или интерлинейные аннотации) — это способ размещения маленького текста над символом или словом. Для поддержки текста ruby в вашей игре требуется выполнить несколько шагов.

Во-первых, вы должны настроить стили для текста ruby. Требуются следующие изменения стилей:

1. Одно из свойств line_leading или ruby_line_leading должно быть использовано для оставления достаточного вертикального пространства для текста ruby.

2. Необходимо создать новый именованный стиль. Свойства этого стиля, такие как size, должны быть установлены соответствующим образом для текста ruby.

3. yoffset нового стиля должен быть установлен, чтобы переместить текст ruby над базовой линией.

4. Поле ruby_style стиля текста должно быть установлено в только что созданный стиль, как для текста диалога, так и для окна истории.

Например:

style ruby_style is default:
    size 12
    yoffset -20
    color None # Использовать тот же цвет, что и у родительского текста.

style say_dialogue:
    ruby_line_leading 12
    ruby_style style.ruby_style

style history_text:
    ruby_line_leading 12
    ruby_style style.ruby_style

(Используйте style.style_name для ссылки на стиль в этих целях.)

После настройки Ren'Py текст ruby можно включать двумя способами.

Линзовидные скобки. Текст ruby можно написать, заключив его в полноширинные линзовидные скобки (【】), с полноширинным или полуширинным символом вертикальной черты (｜ или |), разделяющим нижний текст от верхнего. Например:

e "Ruby can be used for furigana (【東｜とう】 【京｜きょう】)."

e "It's also used for translations (【東京｜Tokyo】)."

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

Теги {rt} и {rb}. Тег {rt} используется для пометки одного или нескольких символов, которые будут отображаться как текст ruby. Если тексту ruby предшествует текст, заключённый в тег {rb}, то текст ruby центрируется над этим текстом. В противном случае он центрируется над предшествующим символом.

Например:

e "Ruby can be used for furigana (東{rt}とう{/rt} 京{rt}きょう{/rt})."

e "It's also used for translations ({rb}東京{/rb}{rt}Tokyo{/rt})."

Создатель несёт ответственность за то, чтобы текст ruby не выходил за границы текста. Может потребоваться добавить ведущие или пробелы слева и справа от текста, чтобы предотвратить возникновение этих ошибок.

Ren'Py также поддерживает альтернативный текст ruby, который является вторым типом верхнего текста ruby. Он вводится с помощью тега {art} (вместо {rt}) и свойства altruby_style (вместо ruby_style).

Шрифты

Ren'Py поддерживает масштабируемые шрифты в форматах OpenType, TrueType, WOFF и WOFF2.

Масштабируемые шрифты указываются путем передачи имени файла шрифта в виде строки. Шрифты ищутся в директории game и в архивных файлах. Если шрифт не найден, поиск производится с использованием префикса fonts/. Например, при поиске "test.ttf", Ren'Py сначала будет искать game/test.ttf, а затем game/fonts/test.ttf. (Он также будет искать в архивных файлах.)

Ren'Py поддерживает коллекции TrueType/OpenType, которые определяют более одного шрифта. При доступе к коллекции используйте индекс шрифта, начинающийся с 0, за которым следует знак @ и имя файла. Например, "0@font.ttc" — это первый шрифт в коллекции, "1@font.ttc" — второй, и так далее.

Хотя Ren'Py поддерживает файлы шрифтов любого размера (в зависимости от ограничений системной памяти), инструменты сжатия WOFF2 могут испытывать проблемы с очень большими файлами шрифтов. См. github bug 6605 для обсуждения этого вопроса.

Замена шрифта

Переменная config.font_replacement_map используется для сопоставления шрифтов. Комбинация имени файла шрифта, жирности и курсива сопоставляется с аналогичной комбинацией. Это позволяет использовать шрифт с настоящим курсивом вместо автоматически сгенерированного курсива.

Одним из таких сопоставлений может быть замена курсивной версии шрифта DejaVu Sans на официальную наклонную версию (вам потребуется загрузить наклонный шрифт из интернета):

init python:
    config.font_replacement_map["DejaVuSans.ttf", False, True] = ("DejaVuSans-Oblique.ttf", False, False)

Это сопоставление может улучшить вид курсивного текста.

Имена и псевдонимы шрифтов

Переменная config.font_name_map используется для присвоения имён или псевдонимов шрифтам. Это позволяет достичь двух вещей: во-первых, сделать диалоги с использованием тега {font} короче и проще в использовании, и, во-вторых, позволить использовать Группы шрифтов с этими тегами.

define config.font_name_map["jap"] = "electroharmonix.ttf"
define config.font_name_map["tjap"] = FontGroup().add("OrthodoxHerbertarian.ttf", "A", "Z").add("electroharmonix.ttf", None, None)

label yamato:
    e "Sorry, what does {font=jap}Black holes and revelations{/font} mean ?"
    y "You pronounce it {font=tjap}Black Holes And Revelations{/font}." # the capital letters appear in OrthodoxHerbertarian

Группы шрифтов

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

Чтобы создать группу шрифтов, создайте объект FontGroup и вызовите на нём метод .add один или несколько раз. Группу FontGroup можно использовать везде, где можно использовать имя шрифта. Метод add принимает начало и конец диапазона кодовых точек Unicode, и используется первый диапазон, покрывающий точку.

Например:

style default:
    font FontGroup().add("english.ttf", 0x0020, 0x007f).add("japanese.ttf", 0x0000, 0xffff)

class FontGroup

Группа шрифтов, которую можно использовать как единый шрифт.

add(font, start, end, target=None, target_increment=False)

Связывает диапазон символов со шрифтом (font).

start

Начало диапазона. Может быть односимвольной строкой или целым числом, обозначающим кодовую точку Unicode. Если start равно None, то шрифт используется по умолчанию.

end

Конец диапазона. Может быть односимвольной строкой или целым числом, обозначающим кодовую точку Unicode. Игнорируется, если start равно None.

target

Если задан, связывает данный диапазон символов с определёнными символами из указанного шрифта, в зависимости от target_increment. Может быть односимвольной строкой или целым числом, обозначающим кодовую точку Unicode. Игнорируется, если символ уже был добавлен.

target_increment

Если True, диапазон [start, end] сопоставляется с диапазоном [target, target+end-start]. Если False, каждый символ из диапазона связывается с целевым символом (target).

Если несколько вызовов .add() включают один и тот же символ, приоритет имеет первый вызов.

Возвращает FontGroup, чтобы можно было выстраивать цепочки из нескольких вызовов .add().

remap(cha, target)

Переназначает один или набор символов на один целевой символ.

cha

Символ или символы для переназначения. Может быть односимвольной строкой, целым числом (кодовая точка Unicode) или итерируемым объектом из них.

target

Символ, на который нужно переназначить. Может быть односимвольной строкой или целым числом (кодовая точка Unicode).

Любой заданный символ, который уже был переназначен (с помощью add или remap), будет проигнорирован. Однако, если у FontGroup нет шрифта по умолчанию, любой заданный символ должен был быть добавлен ранее.

Этот метод также возвращает FontGroup по тем же причинам.

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

Шрифты на основе изображений

Примечание

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

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

renpy.register_bmfont(name=None, size=None, bold=False, italics=False, underline=False, filename=None)

Эта функция регистрирует BMFont с указанными данными. Обратите внимание, что size, bold, italic и underline являются рекомендательными (используются для сопоставления) и не изменяют внешний вид шрифта.

Пожалуйста, ознакомьтесь с домашней страницей BMFont для получения инструмента, который создаёт шрифты BMFont. Ren'Py ожидает, что параметр filename будет указывать на файл в текстовом формате BMFont, описывающий 32-битный шрифт. Альфа-канал должен содержать информацию о шрифте, в то время как красный, зелёный и синий каналы должны быть установлены в единицу. Файлы изображений, кернинг и другая управляющая информация считываются из файла BMFont.

Мы рекомендуем включать Latin и General Punctuation в ваш BMFont, чтобы обеспечить отрисовку всего интерфейса Ren'Py.

name

Имя регистрируемого шрифта, строка.

size

Размер регистрируемого шрифта, целое число.

bold

Жирность регистрируемого шрифта, логическое значение.

italics

Курсивность регистрируемого шрифта, логическое значение.

underline

Игнорируемый параметр.

filename

Файл, содержащий управляющую информацию BMFont.

renpy.register_mudgefont(name=None, size=None, bold=False, italics=False, underline=False, filename=None, xml=None, spacewidth=10, default_kern=0, kerns={})

Эта функция регистрирует MudgeFont с указанными данными. Обратите внимание, что size, bold, italic и underline являются рекомендательными (используются для сопоставления) и не изменяют внешний вид шрифта.

Пожалуйста, ознакомьтесь с домашней страницей MudgeFont для получения инструмента, который создаёт шрифты MudgeFont. Ren'Py предполагает, что коды символов, найденные в XML-файле MudgeFont, являются номерами символов Unicode, и игнорирует отрицательные коды символов.

name

Имя регистрируемого шрифта, строка.

size

Размер регистрируемого шрифта, целое число.

bold

Жирность регистрируемого шрифта, логическое значение.

italics

Курсивность регистрируемого шрифта, логическое значение.

underline

Игнорируемый параметр.

filename

Файл, содержащий изображение MudgeFont, строка. Обычно это TGA-файл, но может быть PNG или другой формат, поддерживаемый Ren'Py.

xml

XML-файл, содержащий информацию, сгенерированную инструментом MudgeFont.

spacewidth

Ширина символа пробела, целое число в пикселях.

default_kern

Межсимвольный интервал по умолчанию (кернинг), в пикселях.

kerns

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

renpy.register_sfont(name=None, size=None, bold=False, italics=False, underline=False, filename=None, spacewidth=10, baseline=None, default_kern=0, kerns={}, charset='!"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~')

Эта функция регистрирует SFont с указанными данными. Обратите внимание, что size, bold, italic и underline являются рекомендательными (используются для сопоставления) и не изменяют внешний вид шрифта.

Подробнее об SFont.

name

Имя регистрируемого шрифта, строка.

size

Размер регистрируемого шрифта, целое число.

bold

Жирность регистрируемого шрифта, логическое значение.

italics

Курсивность регистрируемого шрифта, логическое значение.

underline

Игнорируемый параметр.

filename

Файл, содержащий изображение sfont, строка.

spacewidth

Ширина символа пробела, целое число в пикселях.

baseline

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

default_kern

Межсимвольный интервал по умолчанию (кернинг), в пикселях.

kerns

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

charset

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

! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
@ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _
` a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~

Пример использования BMFont:

init python:
    renpy.register_bmfont("bmfont", 22, filename="bmfont.fnt")

define ebf = Character('Eileen', what_font="bmfont", what_size=22)

label demo_bmfont:

    ebf "Finally, Ren'Py supports BMFonts."

Текстовые отображаемые объекты

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

class ParameterizedText(style='default', **properties)

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

Например, можно сделать:

show text "Hello, World" at truecenter
with dissolve
pause 1
hide text
with dissolve

Вы можете использовать ParameterizedText напрямую для определения схожих изображений с другими свойствами стиля. Например, можно написать:

image top_text = ParameterizedText(xalign=0.5, yalign=0.0)

label start:
    show top_text "This text is shown at the center-top of the screen"

class Text(text, slow=None, scope=None, substitute=None, slow_done=None, *, tokenized=False, **properties)

Displayable, который отображает текст на экране.

text

Текст для отображения на экране. Это может быть строка или список строк и displayable-объектов.

slow

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

scope

Если не None, это должен быть словарь, который предоставляет дополнительную область видимости (scope) для интерполяции текста.

substitute

Если true, выполняется интерполяция текста. Если false, она не выполняется. Если None, это контролируется config.new_substitutions.

slow_done

Если не None, и если включен режим медленного текста (см. параметр slow), это функция или вызываемый объект, который вызывается без аргументов, когда текст завершает свое отображение.

tokenized

Если true, text должен быть списком токенов, а не строкой. Токены описаны на странице Пользовательские теги текста.

**properties

Как и другие Displayable, Text принимает свойства стиля, включая (среди многих других) свойство mipmap.

Утилитарные функции для текста

renpy.filter_text_tags(s, allow=None, deny=None)

Возвращает копию s с отфильтрованными тегами текста. Должен быть указан ровно один из именованных аргументов allow или deny.

allow

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

deny

Множество тегов, которые запрещены. Если тег отсутствует в этом списке, он остается в строке.

renpy.substitute(s, scope=None, translate=True)

Применяет перевод и форматирование нового стиля к строке s.

scope

Если не None, это область видимости (scope), которая используется при форматировании, в дополнение к стандартному хранилищу.

translate

Определяет, происходит ли перевод.

Возвращает переведенную и отформатированную строку.

renpy.transform_text(s, function)

Преобразует s, оставляя текстовые теги и интерполяцию без изменений.

function

Функция, которая вызывается со строками, соответствующими фрагментам текста, и должна возвращать другую строку, которая заменяет этот фрагмент текста.

init python:
    def upper(s):
        return s.upper()

$ upper_string = renpy.transform_text("{b}Not Upper{/b}", upper)

Особенности медленного вывода текста

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

К сожалению, это означает, что возможны артефакты рендеринга при наложении символов друг на друга. Чтобы минимизировать эти артефакты рендеринга, убедитесь, что свойства line_leading и line_spacing достаточно велики, чтобы строки не перекрывались. Если нижние части символов на первой строке обрезаются, особенно если line_spacing отрицательное, рассмотрите возможность увеличения line_overlap_split.

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

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

Логирование переполнения текста

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

1. Установите переменную config.debug_text_overflow в true.

2. Установите свойства стиля xmaximum и ymaximum либо на отображаемом объекте Text, либо на содержащем его контейнере.

3. Запустите игру.

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

Вариативные шрифты

Ren'Py поддерживает вариативные шрифты OpenType. Эти шрифты могут поддерживать несколько осей, таких как начертание (weight) и ширина (width), и в зависимости от значения этих осей отображение шрифта может меняться. Вариативные шрифты также могут иметь именованные экземпляры, которые предоставляют разные значения для осей. Например, именованный экземпляр "bold", скорее всего, предоставит жирную версию шрифта, в то время как "regular" будет более обычной версией.

Для использования вариативных шрифтов требуется использование текстового формировщика harfbuzz, управляемого свойством стиля shaper. После его установки свойство instance выбирает именованный экземпляр, а свойство axis устанавливает значение одной или нескольких осей.

Их также можно установить в системе GUI. Например, можно использовать:

define gui.text_font = "nunito.ttf"
define gui.text_instance = "light"
define gui.text_axis = {"width" : 125}

Это начнёт с экземпляра "light" и сделает его широким.

Если экземпляр не указан, Ren'Py по умолчанию будет использовать "regular" для нежирного текста и "bold" для жирного текста.

Есть два текстовых тега, которые поддерживают использование вариативных шрифтов.

instance

Тег instance изменяет используемый экземпляр. Например:

"This is {instance=heavy}heavy{/instance} text."

Когда используется тег instance, свойства осей переопределяются.

axis

Тег axis изменяет значение одной или нескольких осей. Например:

"This is {axis:width=125}wide{/axis} text."

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

"This is {axis:width=125}{axis:weight=200}wide and bold{/axis}{/axis} text."

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

Чтобы получить доступные экземпляры и оси шрифта, используйте функцию renpy.variable_font_info(). Эта функция предназначена для вызова из консоли. Чтобы получить к ней доступ, нажмите shift+O, чтобы открыть консоль, а затем введите:

renpy.variable_font_info("nunito.ttf")

Это отобразит информацию для шрифта nunito.ttf.

renpy.variable_font_info(font)

Возвращает информацию о вариативном шрифте или None, если шрифт не является вариативным.

font

Имя файла, содержащего шрифт.

Возвращаемое значение — это объект со следующими полями:

instance

Словарь, где ключи — это имена именованных начертаний шрифта. (Например, 'light', 'regular', 'bold' и 'heavy'.) Значения можно игнорировать.

axis

Словарь, который сопоставляет имена осей шрифта с объектами со следующими полями:

minimum

Минимальное значение оси.

default

Значение оси по умолчанию.

maximum

Максимальное значение оси.

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

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