Урок по созданию модов и Lua API

1. Быстрый старт

1.1 Что такое МОД?

МОД — это пакет расширения контента, созданный игроками, который может изменять характеристики существ, навыки, внешний вид скинов и свойства хитбоксов. В игру встроены два примера МОДов — DemoCharacterMod и DemoSkinsMod — они находятся во встроенной директории МОДов игры (см. путь выше). Вы можете скопировать и изменить их, чтобы быстро начать работу.

1.2 Расположение директории МОДов

1.3 Структура директории МОДа

Mods/
├── DemoCharacterMod/           ← Полный пример (хар-ки+навыки+хитбоксы+скины)
│   ├── mod.json                ← Манифест МОДа
│   ├── preview.jpg             ← Превью-изображение
│   ├── CharacterAsset/
│   │   └── allo.txt            ← Конфигурация аллозавра (все 4 типа)
│   └── SkinsAsset/
│       └── Crooked mouth.png   ← Текстура скина
│
├── DemoSkinsMod/               ← Пример МОДа только со скинами
│   ├── mod.json
│   ├── preview.jpg
│   └── SkinsAsset/
│       ├── allo_deser_allo.txt ← Скрипт скина
│       └── deser_allo.png      ← Текстура скина
│
└── MyFirstMod/                 ← Корневая директория вашего МОДа
    ├── mod.json
    └── CharacterAsset/
        └── allo.txt

1.4 Создание mod.json

{
  "Name": "MyFirstMod",
  "Author": "Ваше имя",
  "Version": "1.0",
  "SupportedVersion": "0.6.*",
  "Priority": 0,
  "Description": "Мой первый МОД",
  "PreviewImagePath": "preview.jpg",
  "Tags": "Character"
}

1.5 Обзор внутриигрового интерфейса МОДов

На экране входа нажмите Управление МОДами, чтобы открыть интерфейс МОДов. В нём три вкладки — Локальные МОДы, Мастерская, Управление МОДами — плюс кнопки Создать МОД и Задать директорию, охватывающие весь путь автора от создания до тестирования.

1.6 Создайте свой МОД (рекомендуется новичкам)

В игру встроен инструмент создания МОДов — папки вручную создавать не нужно:
① Войдите в аккаунт (для создания МОДа нужен вход; МОД привязывается к вашему аккаунту).
② Управление МОДами → нажмите Создать МОД.
③ Заполните имя (только буквы/цифры/подчёркивания/дефисы, 1–64 символа), автора, версию, поддерживаемую версию, описание, теги и выберите шаблон.
④ Нажмите Создать — система сгенерирует каркас директории (mod.json и папку примера скрипта для шаблона).
⑤ После этого МОД появится на вкладке Управление МОДами как черновик, ещё не в локальном списке загрузки.

1.7 Редактирование и предпросмотр

① Найдите свой МОД на вкладке Управление МОДами. Если задана директория, МОД синхронизируется в эту внешнюю папку и его можно открыть прямо в текстовом редакторе; иначе редактируйте Lua-скрипты (CharacterAsset/*.txt и др.), PNG-скины и preview.jpg в его папке внутри директории МОДов игры.
② Кнопкой Редактировать в строке меняйте версию, поддерживаемую версию, описание и теги (имя заблокировано).
③ По завершении нажмите Предпросмотр, чтобы отправить черновик в список загрузки Локальных МОДов.

1.8 Тестирование в игре (цикл разработки автора)

1. Создать: Управление МОДами → Создать МОД → выберите шаблон → Создать (генерирует черновик; см. 1.6).
2. Редактировать: правьте скрипты и метаданные в Управлении МОДами (см. 1.7).
3. Предпросмотр: нажмите Предпросмотр, чтобы перенести черновик в список загрузки Локальных МОДов.
4. Включить: перейдите на Локальные МОДы, убедитесь, что статус «Включён» (зелёный) и «Поддерживаемая версия» зелёная (красный — несовместимость с текущей версией игры, исправьте SupportedVersion).
5. Тестировать: войдите в одиночную игру или создайте комнату — изменённые характеристики/навыки/скины вступают в силу немедленно.
6. Итерировать: вернитесь в Управление МОДами и правьте скрипты → создайте локальную Host-комнату, чтобы обновить снимок предпросмотра из последнего черновика → снова войдите в матч для проверки. После однократного включения синхронного предпросмотра не нужны ни перезапуск игры, ни повторное включение предпросмотра.
7. Распространять: когда готово, используйте Экспорт для создания файла .mod для обмена; в Steam также можно Загрузить в Мастерскую для публикации.

1.9 Режим синхронного предпросмотра (тестирование разработки)

Синхронный предпросмотр в Управлении МОДами создаёт отдельный рабочий снимок черновика и регистрирует его в локальном списке загрузки. Исходники автора остаются в директории Управления МОДами; синхронный предпросмотр не публикует и не загружает МОД в Мастерскую.

1.10 Экспорт .mod (обмен и установка)

Экспорт упаковывает текущую рабочую копию из Управления МОДами в сжатый файл .mod и открывает системный выбор места сохранения. Корнем пакета является директория с mod.json; в него входят скрипты, изображения и другие файлы МОДа. Экспорт не включает предпросмотр, не меняет черновик, не делает МОД публичным и не загружает его в Мастерскую.

1. Автор: в Управлении МОДами нажмите Экспорт, сохраните .mod через системный выбор файлов и отправьте его тестерам или игрокам.
2. Получатель: на вкладке Локальные МОДы нажмите Импортировать МОД, выберите полученный .mod (или поддерживаемый .zip), затем убедитесь, что он появился и включён в локальном списке загрузки.
3. Сетевая игра: перед входом или созданием комнаты с МОДами у всех участников должны совпадать содержимое, версия и состояние включения МОДа. Экспортированный пакет не заменяет публикацию в Мастерской.

2. МОД характеристик персонажа

Создайте файл .txt в директории CharacterAsset/ и определите таблицу CharacterAsset для изменения атрибутов существ в игре. Незаполненные поля сохранят исходные значения игры. Ниже приведён полный конфигурационный файл allo.txt из встроенного DemoCharacterMod, показывающий все доступные для изменения поля.

2.1 Полный пример (allo.txt из DemoCharacterMod)

-- Полная настройка характеристик аллозавра (*не удаляйте элементы ниже)
CharacterAsset = {
    name    = "Аллозавр",       -- Название персонажа
    enable  = true,            -- Включить персонажа
    jump    = false,           -- Разрешить прыжки (требуется подходящая анимация)
    race    = "allo",          -- Тег расы (*обязательно, уникальный ключ сопоставления)
    ropoda  = 0,               -- Тип гнезда (-1=нет, 0=теропод, 1=завропод, 2=птицетазовый)
    ropode  = 0,               -- Тип яйца (-1=нет, 0=теропод, 1=завропод, 2=птицетазовый)
    volume  = 2,               -- Класс размера 0~5 (лёгкий→супер)
    rank    = 7,               -- Звёздный рейтинг 0~12 (уровень S1~SS)
    branch  = 3,               -- Классификация семейства 0~25
    habit   = 0,               -- Среда обитания (0=наземный, 1=околоводный, 2=морская рептилия, 3=водный, 4=земноводный, 5=летающий)
    type    = 0,               -- Категория (0=хищный, 1=травоядный, 2=водный, 3=членистоногий, 4=млекопитающее, 5=летающий)
    taste   = 0,               -- Рацион (0=плотоядный, 1=цветы, 2=листья, 3=всеядный)
    spawn   = 0,               -- Размножение (0=яйцекладущий, 1=живородящий)
    health  = 26503.0,         -- Здоровье
    hunger  = 12227.0,         -- Голод
    water   = 3128.0,          -- Жажда
    oxygen  = 474.0,           -- Кислород
    stamina = 100.0,           -- Выносливость
    attack  = 2802.0,          -- Атака
    defend  = 779.0,           -- Защита
    pen     = 5,               -- Уровень пробивания 0~10
    ten     = 3,               -- Уровень стойкости 0~10
    restore = 266.0,           -- Восстановление
    consume = 100.0,           -- Базовое потребление
    weight  = 3600.0,          -- Вес (кг)
    speed   = 27.01,           -- Скорость ходьбы (км/ч)
    swim    = 13.5,            -- Скорость плавания (км/ч)
    flying  = 0.0,             -- Скорость полёта (км/ч)
    runSpeed    = 54.01,       -- Скорость бега (км/ч)
    turnSpeed   = 0.61,        -- Скорость поворота (градусов/сек)
    growtime    = 1560.0,      -- Время взросления (секунды)
    ovumtime    = 1080.0,      -- Интервал формирования яиц (секунды)
    hatching    = 2210.0,      -- Время инкубации яиц (секунды)
    safe        = 1800.0,      -- Период защиты детёныша (секунды)
    skill   = "LifeDrain,3;",  -- Врождённый EX-навык
    gene    = "",              -- Врождённый ген
}

2.2 Классификация и идентификация

2.3 Выживание и бой

2.4 Скорость передвижения (км/ч)

2.5 Временные параметры

2.6 Эффективность органов (0.0 ~ 1.0)

2.7 Размеры тела и врождённые черты

3. МОД навыков

Используйте таблицу CharacterSkill для изменения атакующих навыков персонажа. Каждый навык определяется в формате ключ-значение (ключи можно называть произвольно). Можно объединять с CharacterAsset в одном файле .txt.

3.1 Полный пример (из DemoCharacterMod)

CharacterSkill = {
    attack1 = {
        Race         = "allo",      -- *Обязательно* тег расы
        AttackOrder  = 1,           -- Номер атаки (1=пасть1, 2=пасть2...)
        AttackType   = 0,           -- Тип атаки 0~7 (см. перечисление ниже)
        DamageMode   = 0,           -- Тип урона 0~2 (см. перечисление ниже)
        Area         = nil,         -- Доступная зона nil=без ограничений, {0,1}=только суша+мелководье
        AttackRange  = 1.0,         -- Радиус столкновения атаки (метры)
        Modify       = 2.0,         -- Множитель урона (1=без изменений)
        UseStamina   = 0.01,        -- Расход выносливости в процентах (0=по умолчанию)
        TriggerSkill = "Scars,2;",  -- Навык, срабатывающий при попадании (формат: "Имя,Уровень;")
    },
    attack2 = {
        Race         = "allo",
        AttackOrder  = 2,
        AttackType   = 1,           -- Хвост
        DamageMode   = 1,           -- AOE / по области
        AttackRange  = 3.0,
        Modify       = 0.8,
        UseStamina   = 0.03,
        TriggerSkill = "Blood,2;",
    },
}

3.2 Перечисление AttackType (тип атаки)

3.3 Перечисление DamageMode (тип урона)

3.4 Перечисление Area (доступная зона)

4. МОД хитбоксов (Hitbox)

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

4.1 Константы частей тела

4.2 Пример (из DemoCharacterMod)

CharacterHitGroup = {
    head = {
        Race              = "allo",
        PartType          = BODY_HEAD,
        PenetrationRate   = 0.6,    -- Коэфф. пробивания 0~1 (чем больше, тем легче пробить)
        DamageMultiplier  = 1.5,    -- Множитель урона 0.5~2 (>1 — получает больше урона)
    },
    body = {
        Race              = "allo",
        PartType          = BODY_BODY,
        PenetrationRate   = 0.05,   -- Почти непробиваемо
        DamageMultiplier  = 0.8,    -- Снижение урона на 20%
    },
    belly = {
        Race              = "allo",
        PartType          = BODY_BELLY,   -- Живот (значение=7)
        PenetrationRate   = 0.9,    -- Очень высокое пробивание
        DamageMultiplier  = 1.8,    -- Значительно повышенный урон
    },
}

5. МОД генных БАФФов

МОД генных БАФФов переопределяет значения и настройки существующих генов/навыков/БАФФов через глобальную таблицу CharacterGeneBuff. Как и CharacterAsset, скрипт написан на XLua (.txt) и может располагаться в том же файле или в отдельной подпапке GeneBuff/.

5.1 Структура конфигурации (CharacterGeneBuff)

CharacterGeneBuff = {
    -- Ключ = тег существующего гена для переопределения (TAG см. на странице списка навыков и генов)
    Bleed = {
        Repeat  = "COVER",   -- Опционально: правило перезаписи
        Upgrade = "EXP",     -- Опционально: способ прокачки
        With    = "",        -- Опционально: DSL прикреплённого эффекта, формат tag,уровень;
        Copes   = "",        -- Опционально: тег цели противодействия
        Effects = {          -- *Обязательно* таблица по уровням (заменяет исходные значения по уровням)
            { Level = 1, Probability = 0.55, Effect = 0.03, Duration = 5 },
            { Level = 2, Probability = 0.65, Effect = 0.05, Duration = 7 },
        }
    }
}

5.2 Изменяемые поля верхнего уровня

5.3 Поля Effects по уровням

5.4 Доступные перечисления

5.5 Полный пример (встроенный DemoCharacterMod/GeneBuff/gene_buff.txt)

CharacterGeneBuff = {
    -- ① Переопределить значения по уровням существующего гена Metabolism
    Metabolism = {
        Effects = {
            { Level = 1, Effect = 0.12, Skillful = 0   },
            { Level = 2, Effect = 0.18, Skillful = 100 },
        }
    },
    -- ② Переопределить вероятность срабатывания, значения и длительность существующего гена-навыка Bleed
    Bleed = {
        Effects = {
            { Level = 1, Probability = 0.55, Effect = 0.03, Duration = 5 },
            { Level = 2, Probability = 0.65, Effect = 0.05, Duration = 7 },
        }
    }
}

5.6 Врождённые гены существа

-- В скрипте CharacterAsset существа используйте поле gene, чтобы дать врождённые гены. Формат: ИмяГена,Уровень;
CharacterAsset = {
    race = "allo",
    gene = "Metabolism,2;",
}

5.7 Загрузка и ограничения

• Применяется сразу: после успешного переопределения рождение / срабатывание / исполнение читают переопределённые значения.
• Строгая проверка ссылок: With должен быть tag,уровень, без самоссылки, указанный тег должен существовать, а уровень — быть в диапазоне; Copes должен существовать и не ссылаться на себя. Любая ошибка отклоняет переопределение (никогда не срабатывает молча).
• Нет корректных Effects → это переопределение не применяется.
• Восстановление по сессии: выход / отключение / сброс МОДа автоматически восстанавливает переопределённые гены, предотвращая остаток между матчами.
• Паритет обеих сторон: сервер должен загрузить тот же МОД через GAME_MODS; хэши должны совпадать для входа; /modReload перезагружает значения генов на лету.

6. МОД скинов

Используйте таблицу CharacterSkin для добавления пользовательских скинов. Каждый файл .txt определяет один скин. Файлы текстур помещаются в папку SkinsAsset/ внутри директории МОДа. Смотрите встроенный DemoSkinsMod для полного примера.

6.1 Скрипт скина

CharacterSkin = {
    Race = "allo",                              -- *Обязательно* тег расы
    Name = "Crooked mouth",                      -- *Обязательно* уникальное имя скина (для дедупликации)
    Path = "SkinsAsset/Crooked mouth.png",       -- *Обязательно* путь к текстуре (относительно корня МОДа)
}

6.2 Требования к текстурам

• Формат: PNG или JPG.
• Разрешение: рекомендуется совпадающее с исходной текстурой (обычно 2048×2048 или 4096×4096).
• Путь должен быть относительным от корня МОДа, не используйте абсолютные пути.

6.3 Пример директории с несколькими скинами

MySkinMod/
├── mod.json
├── preview.jpg
└── SkinsAsset/
    ├── allo_crooked.txt   ← CharacterSkin { Race="allo", Name="Crooked mouth", ... }
    ├── crooked_allo.png   ← Файл текстуры
    ├── rex_volcano.txt    ← В одном МОДе можно размещать скины разных рас
    └── volcano_rex.png

7. Продвинутый уровень: Управление и распространение

7.1 Система приоритетов

Когда несколько МОДов изменяют одно и то же поле одной и той же расы, большее значение Priority выполняется позже и побеждает. Значение по умолчанию — 0. МОДы с одинаковым приоритетом выполняются в алфавитном порядке.

7.2 Безопасность песочницы Lua

• os, io: системные команды и файловый ввод-вывод запрещены.
• dofile, loadfile, package: выполнение произвольных локальных файлов и загрузка динамических библиотек запрещены.

7.3 Упаковка в файл .mod

Сожмите все файлы в папке МОДа в ZIP-архив, затем измените расширение на .mod. Убедитесь, что mod.json находится в корне архива. Игра распознаёт как .mod, так и .zip файлы.

7.4 Серверные МОДы

Сервер указывает загружаемые МОДы через переменную окружения GAME_MODS (через запятую):
GAME_MODS=DemoCharacterMod,MySkinMod
Все МОДы, указанные сервером, должны быть установлены и включены у клиента для подключения. Дополнительные МОДы, включённые только у клиента, не будут работать на этом сервере. Администраторы могут использовать /modReload для горячей перезагрузки конфигурации МОДов.