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

Предполагается, что у вас есть минимальный опыт программирования или хотя бы смутное представление о том, что это такое. В качестве текстового редактора рекомендую AkelPad или Notepad++. Травница написана на движке RenPy, так что беглое знакомство с этим движком и/или языком программирования Python будет полезным.

Идеи того, что можно модифицировать в игре описаны от простого к сложному, так что если вы в какой-то точке гайда потерялись и перестали понимать, о чём вообще речь, то можете попробовать пропустить оставшиеся разделы и сразу перейти к последнему содержательному пункту "XX. Проверка мода и его публикация.".

1. Создайте в директории "C:\Program Files (x86)\Steam\steamapps\common\Herbalist\mods" новый каталог с названием "123456789".
2. Запустите игру, зайдите в меню "Модификации" и убедитесь, что среди списка модов появился пункт 123456789, пока что красный.


3. Название, описание и некоторые детали мода хранятся в текстовом файле с именем "descript.ion". Создайте текстовый файл с таким именем внутри вашего каталога "123456789". Требуемая кодировка файла - UTF-8 без BOM.
4. Вашей модификации нужно название-идентификатор, обеспечивающее уникальность. Рекомендованный формат идентификатора: "some_latin_words_mod", то есть английские слова, написанные маленькими буквами, соединённые подчёркиваниями, последнее слово - "mod". Первой строкой в файле "descript.ion" напишите "id=<идентификатор-вашего-мода>".
5. Второй строкой укажите версию модификации в формате "version=<версия-вашего-мода>". Формат версии свободный, можете написать там "1.2.0.1224", "2016-11-15", "0.5-alpha" или просто "1".
Пример: 6. Далее идут локализованные строки для каждого поддерживаемого вами языка:
6.1. Секция начинается с id языка в квадратных скобках. Например, [ru] и [en] для русского и английского. Всегда заполняйте русскую и английскую секцию, даже если не собираетесь поддерживать эти языки.
6.2. title - название мода на данном языке
6.3. (опционально) description - описание мода на данном языке
6.4. (опционально) credits - список авторов мода на данном языке
6.5. (опционально) effects - список областей игры, затронутых модом. В будущем это поле, скорее всего, будет заменено списком тэгов.
Пример:7. Иконка мода
7а. В качестве иконки для отображения внутри игры рекомендованы PNG-изображения размером 620х170. Назовите его "<идентификатор-вашего-мода>.png" и поместите внутрь каталога "123456789".
7б. В качестве иконки для Steam подойдёт любое квадратное PNG-изображение весом менее 1Мб. Назовите его "steam_logo.png" и поместите внутрь каталога "123456789".
8. Запустите игру, зайдите в меню "Модификации" и для каждого поддерживаемого языка убедитесь, что ваш мод больше не красный, а по mouseover'у показывается его описание.


9. Создайте внутри каталога "123456789" подкаталог "<идентификатор-вашего-мода>", это будет основной рабочий каталог вашего мода. За его пределами не должно быть ничего кроме упомянутых выше descript.ion и двух картинок.
10. В рабочем каталоге мода создайте текстовый файл "<идентификатор-вашего-мода>.rpy" в кодировке UTF-8 без BOM. Это и будет основной файл мода, в который вы будете писать код вашего мода.

Файл мода может содержать произвольное число секций с кодом на языке Python и описанием евентов на языке RenPy.
Секция, которая вам понадобится в любом случае - это импорт необходимых функций в ваш namespace из глобального namespace.
Это выглядит примерно так:Далее обычно следуют другие init-python-секции с кодом на языке python и label-секции с описанием евентов на языке RenPy.

Каждую ночь в Амбаре выполняется один и тот же код, прячущий различные предметы в открываемых зонах. Предметы берутся из некоего списка, названного "ambar". Предметы в этом списке имеют веса, характеризующие частоту нахождения данного предмета. Если задать очень большой вес, то предмет будет находиться намного чаще.

Следующий код добавляет предмет ITEM("APPLE") в список "ambar" с весом 2.В результате среди вещей в амбаре, помимо муки и прочих продуктов, будут периодически находиться яблоки. Несмотря на то, что тут всего 5 строчек, если эти 5 строчек записать в rpy-файлом и снабдить описанием, то это может быть уже полностью самодостаточным модом, хоть и очень простым.



Сейчас в игре есть такие взвешенные списки, в которые можно добавлять предметы:

• редкие предметы в Лесу - "forest extras" (там по умолчанию только Грибы)
  
• редкие предметы в Лавке- "shop other" (там по умолчанию только Соль и Губка)
  
• предметы в Амбаре - "ambar" (там по умолчанию только Молоко, Яица, Мука, Сахар и Свечка)
  
• предметы, которые можно !копать - "ambar shovel" (там по умолчанию только Янтарь, Глина и Сковородка)

Фрагменты кода из реальных модов, описывающие добавление предметов во взвешенные списки:

Ещё одна полезная функция - функция добавления предмета в игру, add_to_items().
Для объявления нового предмета понадобится написать такой код:

1. Рекомендованный формат идентификатора предмета - "YOUR_MODID_ITEM_NAME", то есть заглавные английские буквы с подчёркиваниями, причём первые слова - такие же как в названии мода.
2. Категория предмета - произвольная текстовая строка, рекомендованный формат - 1-2 слова в lowercase.
Предметы из следующих категорий автоматически отображаются в списке предметов в соответствующих разделах Книги:

• "cooking"
  
• "food fried"
  
• "food with_apple"
  
• "food with_mushroom"
  
• "food with_sguha"
  
• "food <любая-другая-подгруппа>"
  
• "forest herb"
  
• "forest mushroom"
  
• "forest other"
  
• "forest <любая-другая-подгруппа>"
  
• "household container"
  
• "household edible"
  
• "household instrument"
  
• "household other"
  
• "household <любая-другая-подгруппа>"
  
• "quest doll"
  
• "quest grandma"
  
• "quest helloween"
  
• "quest mushrooms"
  
• "quest pots"
  
• "quest scroll"
  
• "quest <любая-другая-подгруппа>"

.3. Иконка предмета задаётся с помощью параметра "image", значением должен быть СПИСОК png-слоёв. Например,


4. Чтобы озвучить взятие и перекладывание предмета в инвентаре, можно указать параметры "take" и "put". В качестве значения используется путь до ogg-файла. Например,

5. Чтобы озвучить изготовление предмета при смешивании, можно указать СПИСОК звуков "oncraft", из них будет играться случайный. Например,


6. Чтобы задать рецепт получения предмета из нескольких других предметов, нужно указать СПИСОК id этих предметов в параметре "recipe". Например,

Можно указать больше 2 ингридиентов, например, тесто состоит из муки, молока и яиц. Главное, чтобы существовали промежуточные предметы, сумма ингридиентов которых равна ингридиентам данного предмета. Например, recipe=["PUMPKIN_MOD_PUMPKIN", "PUMPKIN_MOD_KNIFE", "CANDLE"] может быть собран из упомянутого выше "PUMPKIN_MOD_PUMPKIN_CUT" и "CANDLE".

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


7. Чтобы назначить цену покупки или продажи в монетах, можно указать параметры "buy_price" и "sell_price". Например,

Если параметр sell_price не указан, то предмет можно продать за 0 монет.
Чтобы предмет было нельзя продать, нужно указать sell_price=None.




8. Чтобы указать событие, случающееся при получении предмета, можно задать параметр "pick" label-именем нужного события. Иначе предмет возьмётся без события. Подробности см. в пункте VI. Получением предмета может быть его крафт или, например, нахождение в амбаре. Если не указать этот параметр, то предмет будет получаться без дополнительного евента.



9. Чтобы указать другое изображение, соответствующее предмету в амбаре или в лесу, можно задать параметр "image_pick". Иначе он будет выглядеть как обычно.



10. Чтобы указать специальную рамочку, мигающую вокруг контура предмета в лесу, можно задать параметр "image_edge". Иначе рамочки не будет.


В итоге, получаем что-то такое:

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


Игра ищет строки вида "TEXT_<что-нибудь>" в файлах локализации. Для русского и английского языков это russian.tsv и english.tsv.
Это tab-separated таблица вида "<ключ><TAB><значение>".

Для предмета "<YOUR_MODID_ITEM_NAME>" будут искаться строки "TEXT_ITEM_NAME_<YOUR_MODID_ITEM_NAME>" и "TEXT_ITEM_DESCR_<YOUR_MODID_ITEM_NAME>". Например, в файле "pumpkin_mod/english.tsv" есть такие строки для предмета "PUMPKIN_MOD_KNIFE":

В идеале, в ваших rpy-файлах вообще не должно быть локализованных строк, только TEXT_ID, который уже ищется в tsv-файлах.



Надписи на ui-виджетах, screen-объектах и реплики переводятся автоматически. Для перевода строки глубоко внутри python-кода можно использовать функцию translate().

Файлы tsv с локализацией нужно добавлять в основной рабочий каталог вашего мода, например "C:\Program Files (x86)\Steam\steamapps\common\Herbalist\mods\1234567890\<идентификатор-вашего-мода>\english.tsv"

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

В скриптах Травницы рекомендовано хранить все реплики в tsv-словарях, всюду используя TEXT_ID вместо настоящего текста, поэтому реплики Слави обычно выглядят примерно так:
Остальные объявленные в игре персонажи, от имени которых можно выводить реплики:

• narr "TEXT_NARRATOR_YOUR_MOD_YOUR_TEXT_ID" - рассказчик, голос за кадром
  
• ba "TEXT_BA_YOUR_MOD_YOUR_TEXT_ID" - Бабушка
  
• bn "TEXT_BN_YOUR_MOD_YOUR_TEXT_ID" - Банник
  
• neko "TEXT_NEKO_YOUR_MOD_YOUR_TEXT_ID" - Кисонька (Мяу? Мяу!)
  
• sj "TEXT_SJ_YOUR_MOD_YOUR_TEXT_ID" - Женя Манж Па Сис Жур, монстр из печки
  
• tm "TEXT_TM_YOUR_MOD_YOUR_TEXT_ID" - Тётя Маша, хозяйка лавки

Отображение/смена эмоции персонажа производится такой командой:
Для Слави, <персонаж>="sl", <место на экране> как правило равно "cleft", а список эмоций Слави: normal, smile, smile2, confused, study, lovely, unhappy, cry, winking, serious, surprised, tired, laughs, dontlike, smile3, smile4, saa, confused2, wot, good, scary, study2, yan.

Для Бабушки (<персонаж>="ba"), Кисоньки (<персонаж>="neko"), Тёти Маши (<персонаж>="tm") типичное положение на экране наоборот, справа, "cright", а список эмоций совсем небольшой: normal, smile, confused.


Нам не нравится мигание рамочки во время смены эмоций, поэтому мы используем команды "window show/hide" вокруг КАЖДОЙ смены эмоции. В результате получается, например, такой код:



Игра ожидает, что для каждого предмета существует событие "event_on_<lower_case_item_id>". При правом клике на предмет будет вызвано такое событие, и в параметрах (i,j) будут переданы координаты предмета в инвентаре. Это, например, позволит его съесть при использовании.

Для предмета ITEM("CANDLE") всё это вместе выглядит вот как-то так:События, связанные с получением предметов (см. пункт IIII.9), параметров i, j не имеют. Например,

Если в событии хочется поменять фон, то делается это так:В качестве команды может выступать:

• $ scene_home_bg() - задник избушки с предметами
  
• $ scene_ambar_bg() - задник амбара с предметами
  
• scene craft_bg - задник зоны крафта
  
• scene shop_bg - задник магазина
  
• scene black - чёрный фон

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

Пример более сложного события, где происходит что-то кроме реплик и спрайтов:
В этом примере кода встречается ещё ряд полезных строчек-команд:

• #<произвольный текст> - комментарии, человекочитаемый текст, который разработчики пишут для себя, чтобы при будущем рефакторинге и отладке понимать, что тут вообще происходит
  
• pause paus - пауза на полсекунды, нужна для последовательной смены нескольких эмоций, в данном случае normal переходит в dontlike, а confused в tired. Вместо paus=0.5 можно указать свой временной интервал, например, одну секунду: pause 1.0
  
• play sound "<имя файла>.ogg" - воспроизведение указанного звукового файла, в вашем случае относительный путь должен рассчитываться относительно рабочей директории мода, например, play sound play sound "pumpkin_mod/halloween_pumpkin.ogg"

Подробнее о командах внутри событий читайте в документации RenPy: https://www.renpy.org/doc/html/quickstart.html


Ряд команд является вызовом функция языка Python и специфичен для данной игры. Такие строки всегда начинаются с символа доллара ("$").
Из представленных выше к ним относятся:

• $ random_sound_play(<список>) - издать случайный звук из python-списка
  
• $ hp_decrease(<число энергии>,<причина>) - игрок теряет указанное число энергии, об этом делается соответствующая пометка, благодаря чему потом можно посчитать статистику потраченной по этой причине энергии. Энергия не может опуститься ниже нуля.
  
• $ remove_item(i,j,pot=<предмет или "NONE">) - (используется в событиях на использование предмета) меняет предмет в инвентаре на другой, соответствует поеданию, использованию, преобразованию, растрачиванию. Третий параметр - либо строка "NONE", либо ITEM ID предмета, которой должен оказаться на месте использованного. Обычно это "DIRTY_POT" (если применялось зелье) или "UNCLEAN_POT" (если применялась еда).

Ещё некоторые полезные функции:

• $ hp_increase(<число энергии>,<причина>) - игрок получает указанное число энергии, об этом делается соответствующая пометка, благодаря чему потом можно посчитать статистику потраченной по этой причине энергии. Энергия не может подняться выше absolutely_max_hp=666.
  
• Сочетанием $hp_increase и $remove_item является функция $ eat_item(i,j,<число энергии>,pot=<предмет или "NONE">) - игрок получает указанное число энергии, а предмет съедается.
  
• $ set_flag(<идентификатор-флага>) / $ unset_flag(<идентификатор-флага>) - управление флагами, см. раздел VII.
  
• $ unlock_book_memory(<идентификатор-воспоминания>) - разблокировать воспоминание в книге, см. раздел VIII.
  
• $ recieve_item_in_event(ITEM(<идентификатор предмета>)) - получить предмет в инвентарь. Если в инвентаре нет места, то предмет заменит какой-то существующий![/list]

Иногда хочется добиться того, чтобы на разных запусках события отличались, например, чтобы повторное использование предмета было другим. RenPy позволяет использовать if-else блоки внутри label для создания подобной логики:
Несколько полезных проверок:

• if hp_is_enough(X): - проверка, что у Слави не менее Х энергии
  
• if money_value_get() < X: - проверка, что у Слави менее X денег
  
• if first_of_item(None): - проверка, что в инвентаре есть пустые ячейки
  
• if not first_of_item(None): - проверка, что в инвентаре НЕТ пустых ячеек
  
• if first_of_item(ITEM("APPLE")): - проверка, что в инвентаре есть предмет Яблоко
  
• if not first_of_item(ITEM("APPLE")): - проверка, что в инвентаре НЕТ предмета Яблоко

Вместо создания собственных логических переменных, предлагается воспользоваться системой флагов Травница:

• set_flag(<идентификатор_флага>) - выставить флаг в True
  
• unset_flag(<идентификатор_флага>) - опустить флаг в False
  
• check_flag(<идентификатор_флага>) - вернуть True, если флаг был выставлен
  
• check_and_set_flag(<идентификатор_флага>) - вернуть True, если флаг был выставлен, одновременно выставив его в True для СЛЕДУЮЩИХ проверок

ВНИМАНИЕ: если идентификатор флага заканчивается на "_today", то ночью он сбрасывается в False автоматически. Остальные флаги всю игру пребывают в том положении, в которое их выставили.

Последний вариант удобно применять в таком коде, когда что-то доступно раз в день или раз за всю игру:



Ещё один полезный функционал, помимо флагов, это счётчики. Почти все действия в игре автоматически увеличивают тот или иной счётчик. Например:

• при покупке яблока счётчик "get_shop_APPLE" увеличивается на 1, а "spent_shop_for_APPLE" увеличивается на стоимость яблока
  
• при срывании травки ITEM("HERB1") в лесу счётчик "get_forest_HERB1" увеличивается на 1, а "tired_forest_pick" увеличивается на энергозатраты
  
• при крафте зелья из банки ITEM("POT") и травки ITEM("HERB1") счётчик "get_craft_HERB1&POT" увеличивается на 1, а "tired_craft_for_HERB1&POT" увеличивается на энергозатраты

И так далее.

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

• if get_counter("get_forest_") >= X: - проверка, что за все игровые дни все начинающиеся на "get_forest_" счётчики суммарно равны не менее Х (то есть за всё время в лесу найдено не менее X любых предметов)
  
• if get_counter_today("get_forest_") >= X: - проверка, что за текущий игровой день все начинающиеся на "get_forest_" счётчики суммарно равны не менее Х (то есть за сегодня в лесу найдено не менее X любых предметов)
  
• if get_exact_counter("get_forest_HERB1") >= X: - проверка, что за все игровые дни значения счётчика "get_forest_HERB1" суммарно равны не менее Х (то есть за всё время в лесу найдено не менее X предметов ITEM("HERB1"))
  
• if get_exact_counter_today("get_forest_HERB1") >= X: - проверка, что за текущий игровой день значения счётчика "get_forest_HERB1" суммарно равны не менее Х (то есть за сегодня в лесу найдено не менее X предметов ITEM("HERB1"))
  
• if all([get_exact_counter("useitem_"+i)>=1 for i in all_in_group("forest herb")]): - проверка, что каждый предмет из группы "forest herb" за игровые дни использовался хоть один раз

На счётчиках и флагах построена проверка замысловатых условий в ачивках и некоторых сценках. Например, вот так организован евент с верёвками в амбаре:
Про функцию add_to_hooks() можно прочитать в разделе [X].

Зимний мод добавляет в игру нового говорящего и новый спрайт.
Рассмотрим эти модификации по отдельности.


Нам понадобится только функция-конструктор персонажа, в неё мы передадим его имя и цвет имени:
Неймспейс персонажа становится частью имени:

Это делается в три этапа.
1. Сначала отдельные слои регистрируются при помощи функции add_to_sprite_layers().
2. Затем бутерброды регистрируются при помощи функции add_to_sprite_composites().
3. Регистрируется небольшая функция отображения эмоции на полное имя спрайта.


В сценарии show-функция используется с указанием неймспейса:
Очевидно, функции add_to_sprite_composites() и add_to_sprite_layers() можно использовать и для расширения существующих персонажей, например Слави.

Описанный в данном разделе метод хорошо подходит для многослойных спрайтов с возможностями расширения реакцией на флаги в show-функции. Если у вас однослойные картинки и вариант определения спрайтов через image кажется вам удобнее - делайте как вам удобнее.

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

Для этого можно зарегистрировать python-функцию, которая принимает на вход 3 ITEM'а (первый предмет, второй предмет, вероятный результат), и возвращает либо None, либо пару ITEM'ов. Делается это так:
Ещё одна модификация рецепта - смена его цены. Чтобы сменить цену одного, некоторых или даже всех рецептов, нужно зарегистрировать python-функцию, которая принимает на вход 2 ITEM'a (what1, what2) и возвращает None или цену крафта в очках энергии. Например, вот так модифицируется цена мытья посуды:
Здесь используется add_to_hooks(<идентификатор-хука>, <на-что-навешивается-хук>, <python-функция>) - одна из самых полезных функций для модификаций поведения, которой будет посвящён отдельный раздел.

Геймплей Травницы очень прямолинейный: предметы смешиваются, локации сменяют друг друга, энергозатраты предсказуемы и так далее.

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

В прошлом разделе вы видели, что навешивая хук на "craft_hp_price" мы можем менять трудозатраты энергии на крафт по своему усмотрению. Аналогично можно поменять затраты энергии и денег и в других местах:

• add_to_hooks(<id>,"ambar_dig_hp_price", ...) - менять затраты энергии на копание
  
• add_to_hooks(<id>,"ambar_reveal_hp_price", ...) - менять затраты энергии на раскрытие вещей в амбаре
  
• add_to_hooks(<id>,"craft_hp_price", ...) - менять затраты энергии на крафт (параметры - what1, what2, **kwargs)
  
• add_to_hooks(<id>,"forest_more_hp_price", ...) - менять затраты энергии на хождение дальше в лес
  
• add_to_hooks(<id>,"forest_pick_hp_price", ...) - менять затраты энергии сбор предмета в лесу (параметры - what, **kwargs)
  
• add_to_hooks(<id>,"shop_sell_price", ...) - менять стоимость предмета в магазине при продаже (параметры - what, **kwargs)
  
• add_to_hooks(<id>,"shop_buy_price", ...) - менять стоимость предмета в магазине при покупке (параметры - what, **kwargs)

Например, вот так меняется стоимость хождения дальше в лес, если сегодня скушано соответствующее зелье:
Хуки могут не только влиять на стоимость действия, они могут отменять действия, не давать им совершаться. Для этих целей есть семейство целей со словом "before" в названии. Здесь действие не произойдёт, если один из хуков вернёт False:

• add_to_hooks(<id>,"before_ambar_dig", ...) - можно предотвратить копание
  
• add_to_hooks(<id>,"before_ambar_reveal", ...) - можно предотвратить раскрытие вещей в амбаре (параметры - what, **kwargs)
  
• add_to_hooks(<id>,"before_ambar_pick", ...) - можно предотвратить взятие вещей в амбаре (параметры - what, **kwargs)
  
• add_to_hooks(<id>,"before_cat", ...) - можно предотвратить копание
  
• add_to_hooks(<id>,"before_craft", ...) - можно предотвратить крафт предмета (параметры - what1, what2, **kwargs)
  
• add_to_hooks(<id>,"before_use", ...) - можно предотвратить использование предмета (параметры - what, **kwargs)
  
• add_to_hooks(<id>,"before_forest_more", ...) - можно предотвратить хождение дальше в лес
  
• add_to_hooks(<id>,"before_forest_pick", ...) - можно предотвратить сбор предмета в лесу (параметры - what, **kwargs)
  
• add_to_hooks(<id>,"before_buy", ...) - можно предотвратить покупку предмета (параметры - what, **kwargs)
  
• add_to_hooks(<id>,"before_sell", ...) - можно предотвратить продажу предмета (параметры - what, **kwargs)
  
• add_to_hooks(<id>,"before_location_change", ...) - можно предотвратить переход в другую локацию (параметры - id_from, id_to, options_from, options_to, **kwargs)

Например, вот так работает переполнение инвентаря и усталость в лесу:call_without_ui - функция запуска label-события. Как правило, вы хотите, чтобы Славя или другие персонажи как-то комментировали отказ от действия.



Помимо before-хуков, есть ещё after-хуки (в них не предусмотрен return, зато можно, например, сделать call_without_ui после успешно совершённого действия) и cancel-хуки (аналогично, дёргаются в случае заблокированного действия). Например, вот так реализован евент, когда Славя подрывается на 20ой неудаче:
Ещё одна полезная категория хуков - это действия, производимые в начале игры и во время сна. Например, функция регенерации леса привязана следующим образом:
А утренние события случаются так:В данном случае return False означает, что это последнее утреннее событие, дальнейшая проверка хуков не производится. Это нужно чтобы избежать ситуаций, когда несколько раз показывается, как Славя просыпается.

Туториал также построен на хуках:

• сначала выполняются хуки "before_tutorial"
  
• затем выполняются хуки "during_tutorial", нажатие "Пропустить" прерывает их выполнение
  
• если "Пропустить" не было нажато, выполняются хуки "after_tutorial"
  
• если "Пропустить" было нажато, выполняются хуки "on_skip_tutorial"

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

Для регистрации воспоминания в книге, нужно импортировать и использовать функцию add_to_book_memories(<идентификатор-воспоминания>, <png-иконка>, <label-события>).

Например,
Обратите внимание на 1000 в "init 1000 python in pumpkin_mod". Меняя это число вы меняете положение вашей иконке относительно других воспоминаний. Чем число больше, тем иконка будет позже. Это правило касается и многих других функций add_to_<что-нибудь>.



С началом новой игры воспоминание заблокировано. Чтобы разблокировать событие в воспоминаниях, нужно где-то в процессе игры вызвать функцию $unlock_book_memory(<идентификатор-воспоминания>).


Например,
Строчка play music "events/how_did_this_happen.ogg" fadein 0.2 fadeout 0.2 мягко включает музыку "how_did_this_happen", используемую во всяких интересных ситуациях. Эту строчку рекомендовано использовать в начале воспоминаний, наряду с $ unlock_book_memory(...).

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


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

Для обеспечения этого есть два механизма. Во-первых, можно вручную проверить, выполняется ли евент из книги, используя переменную inbook, и завязать на это условие какую-то логику. Например, так сделано в финальном евенте, чтобы событие из книги не предлагало окончить игру:
Второй механизм - это подмена флагов (только флагов!), которая делается автоматически. Внутри книжных евентов set_flag() / unset_flag() / check_flag() работают с временным контекстом. Все изменения будут забыты после выхода из книги. Например, в евенте с зайчьями ушами мы не волнуясь о последствиях меняет флаги:

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



Сделано оно так:Здесь мы зарегистрировали в локации "home" объект с id "scroll" и python-функцией home_items_scroll для отображения.

Более сложный вариант использования add_to_location_items() - добавление кликабельной зоны. Последним параметром передаётся информация о такой зоне - координаты прямоугольной области активной зоны, суффикс имени mouseover-спрайта и id локации, на которую произойдёт переход при нажатии (про локации подробнее в следующем разделе), например:В данном примере третьим параметром передаётся None, то есть без mouseover не отрисовывается ничего.



Если активная зона может быть в разных местах в разное время, как в случае с кисонькой Слави, то можно последним параметром передать python-функцию, возвращающую информацию о зоне:


Внутри Амбара предметы и активные зоны добавляются аналогично, вот так в него добавлена лопата:

С точки зрения игры, Амбар, Книга, Настройки, Лопата, Игра с кисонькой, Лес - это всё объекты одной природы. Они называются локациями, характеризуются вызовом renpy-меток, и как правило могут являть собой либо новые комнаты, либо евент/интерактив в рамках других существующих локаций.

Основная функция, которая используется для регистрации их всех - add_to_game_locations(id, text, renpy_label, tags, image=icon), где id - текстовый идентификатор, text - отображаемый текст, renpy_label - метка renpy-сценария, связанного с локацией, icon - либо имя png-картинки, либо RenPy Displayable, а tags - набор тэгов, на которые завязаны различные хуки:

• "icontransform" - автостилизация иконки локации рамочкой
  
• "homeoutside" - место, куда можно уйти из избушки со сменой фона и ambient'а
  
• "homedoor" - место, при переходе в которое нужно скрипнуть дверью
  
• "nohikki" - место, посещение которого ломает ачивку "Затворница"
  
• "nopoison" - место, в которое нельзя ходить при пищевом отравлении
  
• "nomimi" - место, в которое нельзя ходить зверодевочкам
  
• "noinv" - место, в котором недоступен виджет инвентаря (например, Магазин)
  
• "nomenu" - место, в котором спрятаны все виджеты вообще (например, Игра с кисонькой или Книга)

Параметр image=icon опциональный и нужен только для локаций, видимых за дверью. Для активностей вроде игры с Кисонькой или лопаты он не нужен. Как правило такие активности указываются с одним тэгом "nomenu": Теперь если у нас где-то есть активная зона, связанная с "location_id":"sleep", по клику по ней будет вызываться сон.




Локации, находящиеся прямо за дверью, нужно дополнительно регистрировать через вызов add_to_game_locations_outside(id), например:Регистрировать за дверью можно только локации, у которых есть иконка.


Что может быть в локации? В принципе, что угодно, что вы можете реализовать с использованием RenPy и Python, хоть мини-сценка с выборами, хоть пошаговая РПГ-боёвка, хоть многооконный UI, имитирующий операционную систему[lemmasoft.renai.us]. Несколько наиболее очевидных интерфейсных решений в контексте Травницы:

• локация с активными зонами - возьмите код Амбара за основу
  
• локация с инвентарями - возьмите код Магазина за основу
  
• локация с окошком - возьмите код Настроек за основу
  
• локация со списком локаций - используйте в своём label функцию location_catalogue_iface(text, bg, locations_list)

Для отрисовки кнопок вроде "Дальше в лес" в пользовательских интерфейсах и виджетах можно использовать такие функции:

• overlay_degree_button(text,ret="details",mode=True,clicked=None) - левая верхняя кнопка
  
• overlay_gohome_button(text="TEXT_IFACE_HINT_BACK",ret="gohome",mode=True,clicked=None) - правая верхняя кнопка
  
• overlay_prev_button(text,ret="prev",mode=True,clicked=None) - левая нижняя кнопка
  
• overlay_okay_button(text,ret="return",mode=True,clicked=None) - центральная нижняя кнопка
  
• overlay_next_button(text,ret="next",mode=True,clicked=None) - правая нижняя кнопка

Для отображения характерного чёрного окошка вокруг вашего ui, можно использовать блок with ui_window(title) as w, например:

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

Добавление виджета делается функцией add_to_overlays(id, ui_function), где id - строковый идентификатор, а ui_function - python-функция, отображающая виджет с использованием RenPy API ui. Функция должна принимать один параметр ttparent - объект для отображения mouseover-подсказок.

Например,


Аналогичный код используется в моде, отображающем баффы:
По умолчанию виджеты показываются только в интерактивные моменты игры и убираются во время кат-сцен и в локациях со специальными пометками. Если вы хотите сами осуществлять контроль за тем, когда отображается виджет, можно передать False третьим параметром функции add_to_overlays(), тогда ваша ui-функция будет вызываться постоянно и вам нужно будет разместить внутри if-условие, ограничивающее видимость.



Например, так сделано для подсказок в туториале, их видимость управляется вручную переменной hint_text:

Если вам зачем-то понадобилось добавить в меню Настроек конфигурирование какой-то переменной, например, в значение True/False, то такая возможность есть:

Здесь всё просто - функция регистрации принимает 3 параметра - текстовый идентификатор секции, текст секции и её заголовок:
Текст может быть многострочной python-строкой, тогда каждая строка будет матчиться с переводами по отдельности. Пустой абзац можно задать пустой строкой. Например, четвёртая страница справки задаётся таким вот образом:

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

Для начала установите модификацию "Автоматические тесты и инструменты разработки": http://steamproxy.net/sharedfiles/filedetails/?id=812571180


Активировав этот мод и свой мод, перезагрузите игру, начните играть и войдите в меню, которое находится за дверью избушки. Там появится специальная кнопка, "Запуск автотестов". Запустите тесты и посмотрите отчёт (это может занять немного времени). Тесты направлены на выявление таких проблем как использование несуществующих ogg и png-файлов, отсутствие переводов для строк, типовые ошибки в локализации, jump на несуществующие метки, нарушение некоторых соглашений для моддинга и так далее. Не публикуйте моды, для которых есть проблемы, лучше постарайтесь разобраться, в чём дело, или обратитесь к разработчикам игры или другим мододелам за помощью.


Если всё хорошо, то можно публиковать мод. Для этого откройте cmd.exe и перейдите в папку herbalife, которая находится внутри мода "Автоматические тесты и инструменты разработки". Вероятный путь: Далее, выполните следующую команду: "herbalife.exe <путь-до-папки-мода>". Нужно указывать путь до той папки, непосредственно внутри которой находится descript.ion, например:Вводить ничего не надо, инструмент возьмёт все данные из descript.ion и steam_logo.png.


После того как мод успешно загрузился, нужно найти его в своей мастерской в профиле Steam, протестировать и, если всё в порядке, поменять Права доступа на "открытый". До тех пор он будет виден только вам и разработчикам игры - в таком режиме можно его тестировать.


Чтобы обновить уже загруженный в Steam мод, загруженный как "sharedfiles/filedetails/?id=XXXXXXXXX", нужно дописать к указанной выше команде ключик -u XXXXXXXXX, например, для обновления тыквенного мода я использую следующую команду:

ВНИМАНИЕ: после апдейта мода Права доступа также сбрасываются на "скрытый", пока вы не переключите их на "публичный"! Это сознательно добавленная защита от непроверенных апдейтов.

Документ ещё далёк от завершения. Планируется написать ещё как минимум следующие разделы:

• добавление биомов в лесу
  
• добавление типовых локаций - поподробнее?
  
• добавление страниц и разделов в книгу
  
• добавление переводов

Если у вас есть какие-то вопросы, как по написанным, так и по отсутствующим секциям, спрашивайте в комментариях или обращайтесь к автору в личку, я постараюсь помочь.