Как сделать мод для Alem

01Что такое мод в Alem

Почти во всех играх мод — это кусок программы. В Alem не так, и на это есть причина: игра собирается для Android через IL2CPP, а такая сборка физически не умеет запускать чужой C#. Поэтому моддинг здесь устроен иначе — через данные.

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

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

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

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

02Первый мод за пять минут

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

1. Главное меню → МОДЫ.
2. Внизу справа — СОЗДАТЬ ПРИМЕР. Нажмите. В списке появится «Пример мода».
3. Нажмите у него ВЫКЛ, чтобы стало ВКЛ.
4. Начните новую игру и загляните в плавильню — там появился рецепт «Выплавить мифрил». А нож стал слабее.
5. Теперь откройте папку мода (её путь написан прямо на экране «Моды», голубой строкой) и посмотрите файлы внутри. Это и есть весь мод.

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

03Из чего состоит мод

Мод — это папка. Обязателен в ней ровно один файл: mod.json. Всё остальное добавляется по необходимости — берите только те таблицы, которые собираетесь трогать.

МойМод/
  mod.json          ← паспорт, обязателен
  weapons.json      ← оружие
  recipes.json      ← рецепты станков
  apparel.json      ← одежда и броня
  resources.json    ← ресурсы (в том числе свои)
  buildings.json    ← цены и прочность построек
  techs.json        ← дерево технологий
  pawns.json        ← черты (с эффектами), биографии, имена
  events.json       ← свои события с выбором
  plants.json       ← дикие растения на карте
  animals.json      ← дикие звери
  livestock.json    ← домашний скот
  furniture.json    ← своя мебель и станки
  factions.json     ← державы на глобусе
  biomes.json       ← настройка биомов
  quests.json       ← заказы держав
  needs.json        ← свои потребности колонистов
  storytellers.json ← свои рассказчики
  challenges.json   ← свои испытания
  info.json         ← описания для карточки «?»
  loc.json          ← английский перевод ваших строк
  scripts/          ← скрипты на Lua (см. разделы 32–35)
    myrules.lua
  textures/         ← картинки, повторяют пути игры
    Guns/knife/knife-right.png
    Items/mithril.png
    char/hat/3_down.png

mod.json — паспорт

Единственный обязательный файл. Без него папка не считается модом и в списке появится с ошибкой «нет mod.json».

{
 "id": "steppe_pack",
 "name": "Степной набор",
 "author": "Ермахан",
 "version": "1.0",
 "gameVersion": "0.22",
 "desc": "Степное оружие, доспех и новая руда."
}

04Куда класть мод и как его включить

Игра ничего не качает из интернета. Мод — это файл, который уже лежит на устройстве. Есть два пути.

Способ 1. Архивом (для игроков)

1. Соберите папку мода в .zip. Можно паковать и саму папку, и её содержимое — игра разберётся с обоими вариантами.
2. Скачайте файл на телефон.
3. Меню → МОДЫ → ВЫБРАТЬ ФАЙЛ. Откроется системное окно, найдите свой .zip и подтвердите.
4. Мод распакуется и появится в списке. Включите его кнопкой ВКЛ.

Игра также сама показывает архивы, которые нашла в «Загрузках», «Документах» и в своей папке — их можно установить нажатием на имя файла. Если список пуст, это не поломка: начиная с Android 11 система закрывает чужие папки, и надёжен только выбор файла вручную.

Способ 2. Папкой (для авторов)

Распакованную папку мода можно положить прямо в папку модов — архив для этого не нужен. Точный путь написан на экране «Моды» голубой строкой, скопируйте его оттуда. Выглядит он примерно так:

/storage/emulated/0/Android/data/<пакет игры>/files/Mods/

Положили папку → вернулись в игру → ОБНОВИТЬ → мод в списке. Это самый удобный режим работы, пока вы мод пишете: поправил файл, нажал «Обновить», проверил.

Порядок модов

У включённых модов есть стрелки ▲▼. Порядок решает споры: если два мода правят одно и то же, побеждает тот, кто ниже в списке. То же правило действует и для картинок.

05Главное правило: слияние по ключу

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

У каждой таблицы есть ключевое поле (обычно id). Игра берёт вашу запись и ищет свою с таким же ключом:

• Ключ совпал → игра меняет только те поля, которые вы написали. Всё остальное остаётся её.
• Ключа нет → ваша запись добавляется как новая.

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

{
 "weapons": [
  { "id": "knife", "dmg": 9 }
 ]
}

Урон стал 9, а скорость, дальность, цена, картинка и всё прочее у ножа остались игровыми — включая те, что появятся в будущих версиях.

Ключи таблиц

06Как писать JSON, чтобы он не сломался

Все таблицы — это JSON. Формат простой, но придирчивый. Пять правил покрывают почти все ошибки новичков:

1. Кавычки только прямые — ", а не «ёлочки» и не ’. Телефонная клавиатура любит подставлять красивые — следите.
2. Запятая между элементами, но не после последнего. { "a": 1, "b": 2 } — верно; { "a": 1, } — ошибка.
3. Дробные числа через точку: 0.5, не 0,5.
4. Комментариев в JSON нет. Строчку // так нельзя файл не переживёт.
5. Файл в кодировке UTF-8. Иначе русские названия превратятся в кракозябры.

Значения перечислений (тип урона, слот одежды, ресурс) пишутся именами в кавычках, а не числами: "Sharp", "Head", "Iron". Числа сюда писать нельзя — игра ругнётся в лог и возьмёт запасное значение.

07weapons.json — оружие

Файл состоит из двух списков: materials (из чего делают клинки) и weapons (само оружие).

{
 "weapons": [
  {
   "id": "kylysh",
   "name": "Кылыш",
   "melee": true,
   "family": true,
   "dmg": 17,
   "interval": 1.7,
   "range": 1.5,
   "dtype": "Sharp",
   "hitLabel": "Удар кылышем",
   "drawScale": 0.8,
   "craftWork": 6
  }
 ]
}

Материалы клинков

Список materials — из чего игра порождает варианты оружия с "family": true. Ключ записи — key.

{
 "materials": [
  { "key": "iron", "dmgMul": 1.25 }
 ]
}

Здесь dmgMul — множитель урона, res — ресурс, amount — сколько его уходит, name — как называется вариант («железный»).

08recipes.json — рецепты станков

Один список recipes, ключ записи — пара station + id. Один и тот же id у разных станков — законно (простое блюдо есть и на плите, и на костре).

Станки

{
 "recipes": [
  {
   "station": "furnace",
   "id": "mithril_ingot",
   "name": "Выплавить мифрил",
   "in1Type": "SilverOre", "in1": 10,
   "in2Type": "Coal",     "in2": 2,
   "outType": "Mithril",  "outCount": 1,
   "work": 4
  }
 ]
}

09apparel.json — одежда и броня

Один список apparel, ключ — id. Порядок записей в файле = порядок в окне станка.

{
 "apparel": [
  {
   "id": "steppecoat",
   "name": "Степной кафтан",
   "slot": "ArmorOver",
   "armorSharp": 0.3,
   "armorBlunt": 0.22,
   "insCold": 6,
   "maxHp": 130,
   "look": 3,
   "matType": "Leather",
   "matCost": 28,
   "more": [ { "res": "Rivets", "count": 6 } ],
   "tint": "#6B4B2E"
  }
 ]
}

Слоты

Правило простое: всё, что считается бронёй, делается на верстаке, остальное — на швейном столе. Бронёй считается вещь в слоте ArmorOver, а также головной убор из железа или стали.

10resources.json — ресурсы, в том числе свои

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

Работа первая: поправить существующий ресурс

Если id совпал с игровым (список — раздел 17), меняются свойства этого вида:

{
 "resources": [
  { "id": "Steel", "value": 14, "weight": 0.5 }
 ]
}

Работа вторая: завести свой ресурс

Незнакомый id — это новый вид. Он получит собственный номер (модовые номера начинаются с 1000), будет лежать на складах, носиться, гореть, торговаться и съедаться — по тем признакам, которые вы укажете.

{
 "resources": [
  {
   "id": "Mithril",
   "name": "Мифрил",
   "nameEn": "Mithril",
   "weight": 0.3,
   "value": 40,
   "mineral": true,
   "icon": "Items/mithril",
   "shape": "ingot",
   "color": "#8FD8E8"
  }
 ]
}

Признаки

Это не ярлыки для красоты — каждый читается конкретной частью игры: кухней, огнём, торговлей, хирургией, скотом.

Формы заглушек (shape)

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

11buildings.json — цена и прочность построек

Эта таблица не создаёт новые постройки — она перекрывает числа существующих. Ключ — kind плюс необязательный variant.

{
 "buildings": [
  { "kind": "Wall", "costAmount": 4, "hp": 220 },
  { "kind": "Turret", "work": 40,
    "extra": [ { "res": "SteelMechanism", "count": 2 } ] }
 ]
}

Названия видов подсмотрите в файле игры buildings.json — он лежит внутри сборки и покрывает все 53 вида. Правьте только те строки, которые нужны: остальные останутся игровыми.

12techs.json — технологии и ключи доступа

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

{
 "techs": [
  {
   "id": "steppe_smithing",
   "name": "Степная ковка",
   "branch": "Ремёсла",
   "era": 2,
   "cost": 600,
   "desc": "Кылыш и степной кафтан.",
   "prereq": [ "craft_smithy" ],
   "unlocks": [ "weaponfam:kylysh@iron", "apparel:steppecoat" ]
  }
 ]
}

Словарь ключей

13pawns.json — черты, биографии, имена

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

{
 "traits": [
  { "name": "Степняк",
    "desc": "Вырос в седле: ходит на 10% быстрее." },
  { "name": "Белоручка", "blocks": "Уборка",
    "desc": "За грязную работу не берётся." }
 ],
 "traitPairs": [
  { "a": "Степняк", "b": "Белоручка" }
 ],
 "maleNames": [ "Ермахан", "Актос" ],
 "femaleNames": [ "Айгерим" ],
 "lastNames": [ "Сериков" ],
 "nicknames": [ "Белый" ],
 "chronic": [ "Старая рана" ]
}

Эффекты черты

Черта мода — не просто ярлык: у неё может быть настоящий эффект. Блок effects задаёт до двадцати параметров. Проценты пишутся долями (0.15 = +15%), не указанное поле ни на что не влияет, эффекты разных черт складываются.

{
 "traits": [
  { "name": "Кочевник",
    "desc": "Вырос в пути: ходит быстрее и легче терпит холод.",
    "effects": { "moveSpeed": 0.15, "cold": 6, "hunger": -0.12, "mood": -2 } }
 ]
}

14loc.json — английский перевод

В игре две локали. Все ваши названия написаны по-русски — и в английской сборке они останутся русскими, пока вы не дадите перевод. Формат простой: русская строка → английская.

{
 "en": {
  "Кылыш": "Kylysh",
  "Степной кафтан": "Steppe coat",
  "Степная ковка": "Steppe smithing",
  "Удар кылышем": "Kylysh strike",
  "Выплавить мифрил": "Smelt mithril"
 }
}

Ключ — ровно та строка, которую вы написали в таблице, символ в символ. Лишний пробел или другая буква «ё» — и перевод не найдётся.

• Перевод мода не может переписать строки игры — свои названия у неё останутся своими.
• Выключили мод — его строки уходят из таблицы вместе с ним.
• У ресурсов есть более короткий путь: поле nameEn прямо в resources.json.

15Папка textures — свои картинки

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

Как рисовать

• PNG с прозрачностью, пиксель-арт (игра не сглаживает картинки моды — они останутся чёткими).
• Оружие рисуется горизонтально, остриём вправо. Если нарисовать вертикально (выше, чем шире в 1.4 раза), игра сама повернёт картинку на −90° — она считает, что клинок нарисован вверх. Это касается только ближнего боя: лук так и остаётся вертикальным.
• Точка отсчёта у оружия — центр картинки; размер задаётся полем drawScale, а не пикселями. Картинка 400×100 и 800×200 будут в игре одного размера.
• Обломки камня рисуйте квадратными и без «верха»: игра поворачивает их на 0/90/180/270°, чтобы россыпь не выглядела штампованной. Тень с одной стороны выдаст поворот.
• Если два включённых мода кладут картинку по одному пути — побеждает тот, кто ниже в списке модов.

16Облик колониста: слои и номера look

Колонист собирается из слоёв-картинок. Каждый слой — папка, внутри пронумерованные варианты, каждый в четырёх видах.

char/hat/3_down.png   ← вид спереди (обязателен)
char/hat/3_up.png     ← со спины
char/hat/3_left.png   ← влево
char/hat/3_right.png  ← вправо
char/hat/3_down_w.png ← женский вариант (необязателен)

Поле look в apparel.json — это и есть номер варианта в папке своего слоя. Слоты и папки связаны так:

Значит, ваша новая шапка — это "look": 3 плюс файл textures/char/hat/3_down.png.

Правила покраски

• "colorful": true — вещь красится в выбранный цвет при пошиве. Рисуйте её белой: цвет накладывается кодом.
• "tint": "#7A5A38" — вещь всегда одного цвета. Тоже рисуется белой.
• Броня (ArmorOver и железные/стальные шлемы) не красится никогда — её рисуют сразу в нужном цвете.
• Под любым головным убором волосы скрываются автоматически, а под "coversFace": true — ещё и борода.

17Справочник: все ресурсы игры

Эти имена пишутся в полях in1Type, outType, costType, matType, res. Пишите точно, с заглавной буквы.

Сырьё и камень

Руда и металл

Детали и механизмы

Еда

Ткани и шкуры

Медицина

Порох и боеприпасы

Деньги и прочее

Всего встроенных видов — 83. Ваши добавляются сверх них.

18Справочник: ключи и значения

Что открыто с самого начала, без исследований

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

19Сейвы и совместимость

Тут стоит понимать, как игра хранит ваши вещи, — это объясняет все странности при смене набора модов.

Номера ресурсов

В сохранении предмет записан номером: «предмет 5, штук 20». У встроенных видов номера вечные. Ресурсам модов номера выдаются по порядку, начиная с 1000 — а значит, они зависят от того, какие моды включены и в каком порядке.

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

Если мод выключили

Вещи, чей вид больше никто не описывает, изымаются из колонии, а игра пишет об этом письмо. Изъятие затрагивает склады, подсумки, груз караванов и задания — там, где был мифрил, останется пустое место, а не «дерево».

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

Что безопасно менять на середине партии

20Когда что-то не работает

21Чего мод пока не может

Честный список границ — чтобы вы не потратили день на то, чего в игре ещё нет.

• Своего вида работ в приоритетах. Колонист не возьмёт «рыбалку» сам — его отправляет скрипт (alem.task, раздел 34).
• Своего поведения у зверя. Зверь мода ведёт себя как олень, кролик или волк — какой основе вы его научите.
• Постройки со своей работой. Мебель мода берёт поведение нашей постройки (раздел 26): станок, склад, кровать, турель. Совсем новой механики у неё нет.
• Нового биома на глобусе. Биом — это генерация планеты; модом можно только настроить наши пять (раздел 27).
• Своей жилы в горе. Руду расставляет генератор мира. Свой ресурс выдаётся рецептом, растением, торговцем или скриптом.
• Своих окон интерфейса. Есть письма и окно с кнопками (alem.dialog), но не свои экраны.
• Кода на C#. На Android чужой C# не запускается в принципе — это ограничение сборки. Именно поэтому в игру встроен Lua.

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

22Готовый шаблон и чек-лист

Ниже — маленький, но полный мод: новое оружие, доспех, свой ресурс, рецепт, тех, который всё это открывает, и перевод. Скопируйте, переименуйте, правьте.

{
 "id": "steppe_pack",
 "name": "Степной набор",
 "author": "ваше имя",
 "version": "1.0",
 "desc": "Кылыш, степной кафтан и мифрил."
}

{
 "weapons": [
  { "id": "kylysh", "name": "Кылыш", "melee": true, "family": true,
    "dmg": 17, "interval": 1.7, "range": 1.5, "dtype": "Sharp",
    "hitLabel": "Удар кылышем", "drawScale": 0.8, "craftWork": 6 }
 ]
}

{
 "apparel": [
  { "id": "steppecoat", "name": "Степной кафтан", "slot": "ArmorOver",
    "armorSharp": 0.3, "armorBlunt": 0.22, "insCold": 6, "maxHp": 130,
    "look": 3, "matType": "Leather", "matCost": 28,
    "more": [ { "res": "Rivets", "count": 6 } ],
    "tint": "#6B4B2E" }
 ]
}

{
 "resources": [
  { "id": "Mithril", "name": "Мифрил", "nameEn": "Mithril",
    "weight": 0.3, "value": 40, "mineral": true,
    "shape": "ingot", "color": "#8FD8E8" }
 ]
}

{
 "recipes": [
  { "station": "furnace", "id": "mithril_ingot", "name": "Выплавить мифрил",
    "in1Type": "SilverOre", "in1": 10, "in2Type": "Coal", "in2": 2,
    "outType": "Mithril", "outCount": 1, "work": 4 }
 ]
}

{
 "techs": [
  { "id": "steppe_smithing", "name": "Степная ковка", "branch": "Ремёсла",
    "era": 2, "cost": 600, "desc": "Кылыш, кафтан и выплавка мифрила.",
    "unlocks": [ "weaponfam:kylysh@iron", "apparel:steppecoat",
                  "recipe:mithril_ingot" ] }
 ]
}

{
 "en": {
  "Кылыш": "Kylysh",
  "Степной кафтан": "Steppe coat",
  "Степная ковка": "Steppe smithing",
  "Мифрил": "Mithril",
  "Выплавить мифрил": "Smelt mithril",
  "Удар кылышем": "Kylysh strike"
 }
}

Чек-лист перед раздачей мода

• Мод включается и выключается без ошибок в карточке.
• Все новые вещи реально появляются в станках — проверено в новой игре.
• У каждой новой строки есть перевод в loc.json.
• Картинки на месте: в руке, за спиной, на земле, в списке заказов.
• id мода уникален и не совпадает с чужими.
• В архиве лежит папка мода или её содержимое — и внутри есть mod.json.
• В описании написано, для какой версии игры мод и что он меняет.
• Если есть скрипты — в логе нет строк [Lua] … с ошибками.
• Мод проверен на новой партии: звери, растения и державы появляются только при создании карты.

23events.json — свои события

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

{
 "events": [
  {
   "id": "steppe_caravan_gift",
   "category": "good", "weight": 1.2, "cooldownDays": 12, "minDay": 4,
   "title": "Караван из Таавуна",
   "text": "Старший говорит: «{colonist}, степь помнит добро» — и оставляет кумыс.",
   "effects": [
     { "type": "give", "resource": "Kumys", "count": 12 },
     { "type": "mood", "value": 4, "days": 2, "text": "Гостили купцы" }
   ]
  }
 ]
}

Когда событие может выпасть

Письмо и выбор

title и text — заголовок и текст; {colonist} в тексте заменится именем случайного колониста. Дальше одно из двух: либо effects — и событие просто случается, либо choices — ровно два варианта, у каждого свои последствия.

   "choices": [
     { "text": "Купить", "effects": [
        { "type": "take", "resource": "ImperialMark", "count": 200 },
        { "type": "animal", "species": "Верблюд", "count": 1 } ] },
     { "text": "Отказать", "effects": [
        { "type": "relation", "value": -3 } ] }
   ]

Последствия (effects)

24plants.json — дикие растения

Растение мода ведёт себя как ягодный куст: его помечают на сбор, колонист собирает урожай, растение отрастает. Отличается всё остальное — имя, картинка, что даёт, где растёт.

{
 "plants": [
  { "id": "saxaul", "name": "Саксаул",
    "desc": "Корявый пустынный куст: его ветки горят жарко и долго.",
    "texture": "plants/saxaul_full", "emptyTexture": "plants/saxaul_empty",
    "resource": "SaxaulWood", "yieldMin": 8, "yieldMax": 14,
    "work": 2.0, "regrowDays": 4, "scale": 1.2, "blocks": false,
    "biomes": [ "steppe", "desert" ],
    "terrain": [ "sand", "dirt" ], "chance": 0.004 }
 ]
}

25animals.json и livestock.json — звери и скот

Дикие звери

Своё поведение зверю задать нельзя — он берёт его у одного из наших видов (behavior): deer ходит стадом и отбивается, если ранить; rabbit мелкий и пугливый, попадается в силки; wolf — хищник, охотится на дичь и скот.

{
 "animals": [
  { "id": "wild_camel", "name": "Дикий верблюд", "nameFemale": "Дикая верблюдица",
    "desc": "Двугорбый зверь степей. Лягается, если его ранить.",
    "behavior": "deer", "texture": "animals/camel_side",
    "hp": 160, "bodySize": 1.6, "hpMul": 2.4, "speed": 2.6, "scale": 1.25,
    "damageMin": 6, "damageMax": 12,
    "meat": "Beef", "meatMin": 70, "meatMax": 100, "leather": 35,
    "biomes": [ "steppe", "desert" ],
    "groups": 1, "groupMin": 2, "groupMax": 4, "restock": 0.12,
    "tameTo": "Верблюд" }
 ]
}

groups — сколько групп поставить при создании карты, restock — шанс, что зверей этого вида подселят по ходу игры (так они появляются и в начатой партии). tameTo — вид скота, которым зверь станет после приручения; без него приручить нельзя.

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

Домашний скот

Запись в livestock.json добавляет новый вид скота или правит наш. Пустое поле означает «оставить как есть», поэтому для правки хватит одной строки.

{
 "livestock": [
  { "species": "Верблюд", "ruName": "верблюд",
    "femaleName": "Верблюдица", "maleName": "Верблюд", "babyName": "Верблюжонок",
    "spriteKey": "camel", "scale": 1.25, "bodySize": 1.6, "hpMul": 2.5,
    "adultDays": 200, "appetite": 0.8, "pregnancyHours": 960,
    "product": "milk", "productHours": 14, "productAmount": 6,
    "meatType": "Beef", "meat": 120, "leather": 50,
    "price": 420, "maxHerd": 8, "minTempC": -6, "mount": true },

  { "species": "Курица", "price": 75 }
 ]
}

product — milk, egg, wool или none. mount: true делает вид верховым: на нём ездят и он ускоряет караван, как лошадь. Картинки скота кладутся в textures/Animals/<spriteKey>_down.png и остальные стороны.

26furniture.json — своя мебель и станки

Эта таблица добавляет постройки, в отличие от buildings.json, который только меняет числа наших.

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

{
 "furniture": [
  { "id": "steppe_chest", "name": "Сундук кочевника",
    "desc": "Расписной сундук для утвари. Работает как полка-склад.",
    "base": "Shelf", "texture": "furniture/chest",
    "cost": [ { "resource": "Wood", "count": 15 },
              { "resource": "Leather", "count": 5 } ],
    "hp": 130, "research": "building:steppe_chest" },

  { "id": "steppe_hearth", "name": "Очаг юрты", "base": "Brazier",
    "light": 7, "lightColor": "#FF9A50" },

  { "id": "felt_bed", "name": "Войлочная постель",
    "base": "Bed", "variant": "Single" }
 ]
}

Какие основы бывают

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

27factions.json и biomes.json — державы и биомы

Державы

Запись либо правит нашу державу (если name совпал), либо добавляет новую на глобус — со столицей, городами и территорией.

{
 "factions": [
  { "name": "Орда Каракум", "archetype": "raiders", "color": "#C07A38",
    "alwaysHostile": true, "tech": 1.8, "citiesMin": 2, "citiesMax": 4 },
  { "name": "Таавун", "archetype": "traders", "relationMin": 5, "relationMax": 25 }
 ]
}

archetype — raiders, tribal, traders, smiths, healers, syndicate: от него зависят караваны, товары и скорость развития. outlaw — «вне закона»: мало поселений и техника с самого низа. tech — стартовый уровень 0…5.

Биомы

Новый биом добавить нельзя — это генерация планеты. Зато наши пять настраиваются:

{
 "biomes": [
  { "id": "steppe", "trees": 0.7, "bushes": 1.5, "richSoil": 0.03,
    "wildlife": 1.4, "temp": 2 }
 ]
}

Имена биомов: forest, temperate, steppe, desert, tundra.

28quests.json — свои заказы держав

Шаблон заказа на поставку: кто просит, что, сколько, за какой срок и чем платит. Письмо, окно «Задания», сдача груза гонцу и штраф за просрочку — всё это делает игра.

{
 "quests": [
  { "id": "steppe_felt_order",
    "archetypes": [ "tribal", "traders" ], "minRelation": 5, "minDay": 6, "weight": 1.2,
    "items": [ "FeltCloth", "DriedMeat" ], "amountMin": 15, "amountMax": 35,
    "daysMin": 6, "daysMax": 10, "moneyMin": 300, "moneyMax": 520,
    "rewards": [ { "resource": "Iron", "min": 15, "max": 30 } ],
    "relation": 12, "research": 120,
    "title": "Кочевникам: {0} × {1}",
    "text": "«{giver}» просят {amount} × {item}. Срок — {days} дн." }
 ]
}

В заголовке {0} — количество, {1} — ресурс. В тексте доступны {giver}, {amount}, {item} и {days}. Ниже игра сама допишет срок, награду и предупреждение о провале.

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

29needs.json — свои потребности

Новая шкала у каждого колониста: сама убывает, видна в окне «Нужды» и портит настроение, когда падает. Чем её наполнять — решает мод.

{
 "needs": [
  { "id": "thirst", "name": "Жажда", "color": "#4FA8E8",
    "start": 85, "drainPerHour": 3.2, "lowAt": 25,
    "moods": [
      { "below": 45, "mood": -3, "text": "Хочется пить" },
      { "below": 20, "mood": -9, "text": "Мучает жажда" }
    ] }
 ]
}

Когда шкала падает ниже lowAt, скриптам приходит on_need_low(имя, id) — там и решается, что делать: отправить к воде, дать выпить, прислать письмо. Значения хранятся в сохранении отдельно по каждому колонисту.

30Рассказчики и испытания

storytellers.json

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

{
 "storytellers": [
  { "name": "Буран", "character": "Беспощадный",
    "styleLine": "бьёт волнами и почти не даёт продохнуть",
    "style": "waves", "tensionPerDay": 15, "raidShare": 0.65,
    "sizeMin": 1.2, "sizeMax": 1.7, "graceMin": 4, "cavalryDay": 18 }
 ]
}

style — calm (по напряжению), waves (кризис, затем передышка), chaos (ровный случайный шанс), relentless. Ноль или пустое поле значит «как у игры», поэтому нашего рассказчика можно поправить одной строкой.

challenges.json

Своё испытание: правила старта и цель. Цель бывает четырёх видов — raids (отбить столько налётов), days (прожить столько дней), wealth (накопить богатство) и script — когда счёт ведёт сам мод.

{
 "challenges": [
  { "id": "steppe_herd", "name": "Хозяин табуна",
    "desc": "Соберите табун из восьми верблюдов и удержите его.",
    "rules": [ "Цель считает мод", "Рассказчик «Буран»" ],
    "goal": "script", "goalValue": 8, "goalText": "Собрать табун из 8 верблюдов",
    "colonists": 3, "difficulty": 2, "graceDays": 4, "starDay": 40,
    "planetSeed": 40404,
    "cargo": [ { "resource": "Food", "count": 120 } ],
    "weapons": [ "bow" ], "startTech": [ "steppe_craft" ] }
 ]
}

Для цели script скрипт сам считает прогресс и объявляет исход — см. alem.challenge_progress, alem.win и alem.lose в разделе 34.

31info.json — описания для карточки «?»

У каждой вещи, постройки, растения и зверя в игре есть кнопка «?» — окно с описанием сверху и характеристиками снизу. Характеристики игра считает сама, а описание берёт отсюда.

{
 "entries": {
  "res:Kumys":    { "ru": "Кислый напиток из кобыльего молока.",
                    "en": "A sour drink of mare's milk." },
  "weapon:saber": { "ru": "Изогнутый клинок для конного боя.",
                    "en": "A curved blade for fighting from the saddle." }
 }
}

Ключи: res:<ресурс>, weapon:<id>, apparel:<id>, build:<вид>, plant:<id>, animal:wild:<id>. У растений, зверей и мебели есть путь короче — поле desc прямо в их таблице.

32Скрипты на Lua: первый скрипт

Таблицы описывают вещи. Скрипт описывает правила: «если случилось это — сделай то». Файлы .lua кладутся в папку scripts/ внутри мода и грузятся по алфавиту.

-- Голодная зима: если зимой мало еды, приходит письмо и портится настроение
function on_day(day)
  if alem.season() == "winter" and alem.resource("Food") < 50 then
    alem.letter("Голодная зима", "Старики говорят: духи уходят из холодных домов.")
    alem.mood_all(-4, 2, "Страх голода")
  end
end

Это весь скрипт. Lua — простой язык: переменные, if, циклы и функции. Всё, что нужно знать для модов, помещается в этот раздел и два следующих.

Что нужно помнить сразу

• Каждый мод живёт отдельно — переменные одного мода не видны другому.
• Ошибка не роняет игру. Она попадает в лог строкой [Lua] … с именем мода. После трёх ошибок подряд скрипты этого мода выключаются до перезапуска.
• Бесконечный цикл не повесит игру — вызов прервётся по лимиту в 200 000 шагов, а в лог попадёт ошибка.
• Песочница. Скрипту недоступны файлы, интернет и что-либо за пределами таблицы alem. Нет io, require, os.execute.
• Изменения подхватываются при перезапуске игры или при смене набора модов.

alem.on("on_day", function(day)
  -- этот обработчик не мешает соседнему файлу
end)

33Хуки: когда игра зовёт скрипт

34Команды alem.*

Узнать

Сделать

Память мода

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

alem.set("deaths", alem.get("deaths", 0) + 1)
if alem.get("deaths", 0) == 3 then alem.event("cursed_land") end

Хранить можно строки, числа и true/false. Ключи у каждого мода свои — чужие не перепутаются.

35Правила и границы скриптов

Пример: жажда и водопой

Связка «таблица + скрипт» выглядит так. В needs.json заведена шкала «Жажда», а скрипт решает, как её утолять:

function on_need_low(name, need)
  if need ~= "thirst" then return end
  local cx, cy = alem.colony_center()
  alem.task(name, cx, cy, 6, function(who)
    if alem.resource("Kumys") > 0 then
      alem.take("Kumys", 1)
      alem.need(who, "thirst", 100)
      alem.memory(who, 3, 1, "Пил кумыс")
    else
      alem.need(who, "thirst", 65)   -- вода утоляет хуже
    end
  end)
end

Чего скрипт не может

• Отменить или изменить урон. on_hit приходит уже после расчёта: можно добить, поджечь, отравить или вылечить — но не «не дать попасть».
• Завести новый вид работ. Колониста на своё занятие отправляет alem.task, а не список приоритетов.
• Сделать своё окно интерфейса. Есть письма и alem.dialog — до пяти кнопок.
• Достучаться до внутренностей игры. Наружу выведены только команды из раздела 34; всё остальное закрыто песочницей.