Документация по моддингу на русском

Overview

Практически дословный перевод официальной документации по созданию модов к игре Transport Fever.Оригинал на английском языке доступен по ссылке: Transport Fever Wiki: Mod development[transportfever.com].Перевод документации не завершенЕсли вы нашли ошибку в тексте, пожалуйста, сообщайте о ней в комментариях.Не стесняйтесь оценивать руководство, добавлять в избранное и комментировать.

Transport Fever может быть модифицирован и расширен с помощью модов. Этот гайд поможет объяснить как файлы с игровыми ресурсами организованы и как моды могут быть созданы.

Transport Fever хранит все файлы ресурсов в папке под названием res. Там находятся различные типы ресурсов: 3D меши/модели (к примеру транспорт), текстуры, конструкции (к примеру станции), улицы или железные дороги и множество других. Большинство этих файлов это скрипты на языке Lua, они представлены как текстовые файлы с расширением .lua, так что вы сможете легко редактировать их любым текстовым редактором. Однако изменение этих файлов на прямую в установленной игре НЕ рекоммендуемый путь для модификации Transport Fever!

Лучше всего – это создать мод (модификацию). С точки зрения файловой системы, мод – это директорая содержащая необходимые данные и скриптовые файлы. Имена директорий называются специальным образом, они уникальны и содержат номер версии мода. В следующем разделе “Структура директорий” это будет описано более детально.

Есть два пути для модификации функционала игры и его контента:

Файловый: Позволяет добавлять, заменять или удалять (скрывать) контент на уровне файлов. Основная идея в том, что игра видит и работает с файлами мода как со своими собственными. Если в игре и моде будут 2 одинаковых файла, то приоритет будет отдан файлу из мода.
Скриптовый: Позволяет модифицировать игровую конфигурацию и контент с помощью скриптов Lua. Этот путь к примеру позволяет настраивать вместимость всего транспорта в игре без копирования всех файлов и изменении их индивидуально.

В Transport Fever моды не активируются глобально, а доступны для каждой игры индивидуально. Другими словами, каждая сохраненная игра запоминает какие моды были активированы для нее. Это дает преимущество, для сохраненных игр с разным набором активных модов. Однако, это так же означает что контент который загружается вне сохраненных игр не может быть модифицирован (для примера – главное меню игры).

Структура директорий

Важное замечание

Все файлы (модели, меши, скрипты и т.п.) должны быть конвертированы в кодировку UTF-8. Так же рекомендуется использовать нижний регистр в именах файлов что бы избежать проблем с регистром в разных операционных системах и файловых системах.

Структура мода

В установленной папке с игрой (обычно это C:Program Files (x86)SteamSteamAppscommonTransport Fever на Windows системе) структура папок выглядит примерно таким образом:

Transport Fever dlcs … mods … res … …

Все моды должны быть установлены в поддиректорию mods. Структура директорий мода должна быть такой:

Transport Fever mods urbangames_sample_mod_1 (1) config (2) (необязательно) … documents (3) (необязательно) … res (4) (необязательно) … mod.lua (5) image_00.tga (6) (необязательно) strings.lua (7) (необязательно) workshop_preview.jpg (8) (необязательно) filesystem.lua (9) (необязательно)

Где:

Директория мода имеет название вида <идентификатор>_<версия>. Идентификатор необходимо описывать конкретно, что бы он содержал имя автора (или организации) и имя мода (можно использовать нижнее подчеркивание вместо пробелов). Версия это обычное целочисленное (положительное число) начинающееся с единицы. Для примера: spacex_rocket_hangar_1.
Необязательная папка содержащая подключаемые конфигурационные файлы (Lua файлы). Эти файлы могут быть подключены из других Lua файлов, т.е. конфигурационная директория добавляется к Lua package.path списку.
Содержит документацию автора мода или информацию предназначенную для пользователя, к примеру readme файлы или мануалы по использованию мода. Эта директория игнорируется игрой.
Основной контент (такой как модели, текстуры и другое) находится в этой директории. Все что находится тут можно представить таким образом, как будто это было бы скопировано (и перезаписано) в базовой res/ папке.
Основной файл содержащий метаданные (имя мода, описание и другое), а так же код скриптов. В разделе “Скриптинг” описано более подробно.
Изображение размером 240×135 пикселей отображаемое в игре.
Содержит переводы для текстов мода.
Изображение отображаемое в Steam Workshop когда мод опубликован.
Определяет список файлов и папок которые должны быть удалены (скрыты) из базовой игры.

Версии

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

mod.lua

Базовый файл описывающий структуру мода. В разделе “Скриптинг” описано более подробно.

function data() return { info = { — поставив два дефиса можно писать комментарии в скрипте name = _(“Sample mod”), — (1) description = _(“modDesc”), minorVersion = 0, — (2) severityAdd = “WARNING”, — (3) severityRemove = “CRITICAL”, }, — options = .. — runFn = .. — checkActiveFn = .. } end

Имя мода и его описание. Текст _(“keyName”) указывает на то, что ключевое слово keyName будет переведено на язык игрока (смотрите strings.lua ниже).
Минорная версия, начинается с нуля. Значение должно быть увеличено после незначительных модификаций мода (к примеру, после изменений языковых файлов).
Определяет какой тип предупреждений будет показан при добавлении (add) и удалении (remove) мода в существующих сохраненных играх. Значение может быть: NONE (ничего не отображать), WARNING (предупреждение) или CRITICAL (критический уровень).

strings.lua

function data() return { en = { — так как не указан Sample mod ключ, то он будет выведен “как есть” modDesc = “This is a sample mod.”, }, ru = { [“Sample mod”] = “Пример мода”, modDesc = “Описание мода на русском языке”, } } end

Этот файл содержит строки для перевода, выглядит как список пар ключей и значений для каждого языка. Если ключ не найден в файле, будет использован английский перевод по умолчанию (en). Если и в английском переводе не найдено ключа, он сам будет отображен игроку (Sample mod в примере выше). Список доступных языковых кодов можно увидеть в папке res/strings/ (для примера en, ru).

filesystem.lua

function data() return { — удаляемые (на самом деле просто скрываемые) папки из игры и все что в них содержится hiddenDirs = { “res/models/model/vehicle/truck/” }, — удаляемые файлы из игры hiddenFiles = { “res/models/model/vehicle/train/borsig_1860.mdl”, “res/models/model/vehicle/train/br75_4.mdl” } } end

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

Базовая конфигурация

Все основные аспекты игрового мира могут быть сконфигурированы с помощью файла base_config.lua, который может быть найден в папке res/config/.

Он имеет следующую структуру:

game.config.costs = { — основные настройки цен } game.config.cargotypes = { — таблица типов грузов } game.config.terrain = { — конфигурация генератора карты, шейдеров, текстур и растительности } game.config.environment = { — освещение, туман, скайбокс (контейнер для неба) и карта окружения } game.config.audio = { — настройки окружения источников звука и музыкальных дорожек } game.config.world = { — города и производства }

Большинство параметров говорят сами за себя или объясняются в комментариях внутри файла.

Модели

Формат моделей содержит геометрическую информацию для различных уровней детализации (LOD – Levels Of Detail; см. на Wikipedia[ru.wikipedia.org]) и другие метаданные (технические данные).
Для каждого LOD существует раздельная иерархия состоящая из мешей (обычно организованы в группы), анимации, событий и настроек материалов.

Метаданные содержат всю необходимую информацию, чтобы дать модели желаемые свойства в игре.

function data() return { — необязательно: ‘boundingInfo’ и ‘collider’ lods = { }, metadata = { }, } end

LODs

LOD состоит из следующих записей в таблице:

children
matConfigs
animations
events
visibleFrom
visibleTo
static
Metadata

Метаданные

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

Основное

description
availability
cost
maintenance
particleSystem
soundConfig

Транспорт

transportVehicle
waterVehicle
roadVehicle
railVehicle
airVehicle
car

Постройки

transportNetworkProvider
vehicleDepot
streetTerminal
autoGroundTex

Остальное

person
tree
rock
signal

Сооружения

Концепция сооружений, созданная в Transport Fever очень мощная. Она позволяет конфигурировать и создавать множество различных типов сооружений и игровых элементов в одном формате. Для примера это: станции, склады, производства, городские сооружения и множество других элементов. Все они хранятся в файлах формата .con в папке res/construction/.

Введение

Формат в основном содержит метаданные и функцию для обновления состояния. Сооружения конфигурируются и создаются внутри функции, которая может возвращать различные конфигурации в зависимости от входящих параметров. Это позволяет возвращать совершенно разные сооружения.

function data() return { — определяем тип нашей постройки (см. доступные типы ниже) type = “INDUSTRY”, — другие метаданные — … params = { — параметры изменяемые игроком }, — функция обновления состояния, которая принимает параметры params и на основе этих параметров возвращает результат updateFn = function(params) — переменная для результата local result = { } — устанавливаем в переменную какие-нибудь модели result.models = { { id = “industry/chemical_plant/building_small.mdl”, transf = transf.transl(vec3.new(20, -10 , 0)) } } — другие действия, типа выравнивание поверхности, улиц, путей, списка товаров и т.п. — возвращаем результат работы функции return result end } end

Сооружения: метаданные

Сперва вам необходимо определиться с типом сооружения, установив значение ниже для ключа type.

Доступные типы построек:

STREET_STATION
RAIL_STATION
AIRPORT
HARBOR
STREET_STATION_CARGO
RAIL_STATION_CARGO
HARBOR_CARGO
STREET_DEPOT
RAIL_DEPOT
WATER_DEPOT
INDUSTRY
ASSET_DEFAULT
ASSET_TRACK
TOWN_BUILDING

Ключи description, availability и soundConfig в метаданных описываются таким же образом как и модели (см. предыдущий раздел “Модели”).

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

params = { { — внутренний ключ-указатель key = “numTerminalsIndex”, — название настройки видимое игроку name = _(“Number of terminals”), — массив мозможных значений values = { _(“1”), _(“2”), _(“3”) } }, }

Обратите внимание: key используется для получения результата выбора игрока (в виде индекса который начинается с нуля, т.е. _(“1”) будет равен нулю, _(“2”) – единице и так далее), который передается в функцию обновления updateFn через params.

Продолжая пример конфигурации аэропорта:

updateFn = function(params) — создаем переменную (local) с именем numTerminals (количество терминалов) — используем параметры params и наш ключ numTerminalsIndex который мы указали выше — прибавляя к нему единицу (так как передается индекс начинающийся с нуля, который выбрал игрок) local numTerminals = params.numTerminalsIndex + 1 — тут остальная логика для работы с объявленной выше переменной numTerminals end

В дальнейшем вы сможете добавить другие ключи в метаданные:

buildMode
Описывает, может ли сооружение быть построено в единственном экземпляре (значение SINGLE) или в любом количестве (значение MULTI) до закрытия меню строительства (что бы игрок не открывал несколько раз окно для постройки одного и того же сооружения, к примеру деревьев). Так же можно указать значение “кисть” (BRUSH).
categories
Опциональный список категорий, используемый для группировки сооружений в меню построек.
order
Используется для сортировки вашего сооружения в списке.
skipCollision
Параметр который определяет, могут ли объекты проходить сквозь сооружение.
autoRemovable
Параметр который определяет, может ли сооружение быть уничтожено, если что-то столкнется с ним.
townBuildingParams
Параметр используется для настройки сооружений в городах. Изучите файлы игры для более подробной информации.

Сооружения: функция обновления

В процессе перевода

Миссии

В процессе перевода

Работа со звуком

В процессе перевода

Карты

В процессе перевода

Публикация в Steam Workshop

Если вы хотите поделиться своим модом с другими игроками, вы можете загрузить его в Мастерскую Steam. Просто следуйте следующим шагам:

1. Добавление тегов

Убедитесь что вы включили в файл mod.lua описание ваших тегов. По тегам игроки в Steam смогут найти ваш мод.

Пример, как это может выглядеть:

function data() return { info = { — список тегов через запятую tags = { “building”, “depot” } — другие данные в блоке info }, — options = .. — runFn = .. — checkActiveFn = .. } end

2. Добавление превью

Что бы добавить превью, которое будет отображаться в Мастерской Steam, необходимо добавить файл workshop_preview.jpg в папку с модом. Его размер не должен превышать 1 Мб и иметь соотношение сторон 16:9 (к примеру 320×180 пикселей).

3. Копирование мода в папку staging_area

Скопируйте папку с вашим модом в директорию staging_area по адресу:

C:Program Files (x86)Steamuserdata<ваш_Steam_ID>446800localstaging_area.

4. Публикация

Запустите игру и выберите “Опубликовать мод” в главном меню. Слева, выберите мод который вы хотите опубликовать. Заполните необходимые поля. Для продолжения нажиме кнопку “Публикация”. Поздравляем, с этого момента ваш мод должен быть доступен для всех желающих в Мастерской Steam!

Примеры

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

urbangames_no_costs_1
Устанавливает стоимость всех элементов в игре в ноль (скриптинг)
urbangames_vehicles_no_end_year_1
Устанавливает значение “снято с конвеера” для каждого транспорта в ноль, делая их доступными для покупки навсегда (скриптинг)

Transport Fever Guide

Overview

Оглавление

Структура директорий

Базовая конфигурация

Модели

Сооружения

Сооружения: метаданные

Сооружения: функция обновления

Миссии

Работа со звуком

Карты

Публикация в Steam Workshop

Примеры