Базовая информация о моддинге

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

Для работы вам понадобится удобный для вас текстовый редактор, например: стандартный блокнот, Notepad++ или что-то ещё подобное.

Лично я использую вышеупомянутый Notepad++ (скачать). Он бесплатен, достаточно удобен и в нём есть множество упрощающих работу функций: вкладки, поиск по файлам, подсветка кода и тому подобное. Но, опять же, выбирайте именно то, в чём вам будет удобно работать.

Для редактирования спрайтов нужен какой-нибудь графический редактор. Мне вполне хватило возможностей стандартного Paint`а, но вы можете работать в Photoshop`е или GIMP`е, ежели вам так будет удобнее.

Хочу заранее заметить, что это руководство писалось в Windows 7 - в некоторых других операционных системах могут быть некоторые нюансы работы, о которых мне неизвестно.

Все создаваемые текстовые файлы должны быть сохранены в кодировке UTF-8.
Создание мода: подготовка
В первую очередь нужно открыть папку с установленной игрой. При наличии официальной стим-версии проще всего сделать это через клиент Steam следующим образом:

Переходим в раздел "Библиотека", в левом меню находим Starbound и щёлкаем по нему правой кнопкой мыши. В выпавшем меню выбираем "Свойства", в новом окошке переходим во вкладку "Локальные файлы" и нажимаем кнопку "Просмотреть локальные файлы" - после этого у вас откроется папка с игрой.

Переходим в папку mods, создаём в ней новую директорию и называем как нибудь, например: "MyMod". Используем только символы латинского алфавита и цифры.

В этой директории создаём текстовый файл "_metadata" без какого либо расширения.

Файлу задаём следующее содержание:

{ "name" : "My Mod Name", "description" : "My Mod Description", "author" : "My Name", "version" : "1.0" }

"name" - название вашего мода.

"description" - это описание вашего мода. Поле много строчное. Если нет желания возиться с этим текстом, то поле можно не заполнять.

"author" - ваше имя или псевдоним.

"version" - это текущая версия вашего мода. Можно обновлять если вы делаете крупный мод и периодически его дополняете. Лично я этим не заморачиваюсь, а потому оставляю версию без изменений.

В этих полях можно использовать и кириллицу.

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

Создаём в папке с нашим модом новую директорию, называем её "objects".
Создаём в этой папке текстовый файл: "mypic.object".
mypic - это название указано как пример. Вы можете использовать у себя любое другое название, главное, чтобы оно нигде не использовалось ранее в файлах игры и содержало только латинские символы.

Также понадобятся два png файла - сам плакат (mypic.png) и его иконка (mypic_icon.png, тоже самое изображение, но в ещё меньшем размере) для инвентаря. Для пробы можно взять те, что я подготовил заранее.

Основная картинка - сохраняем в mods/MyMod/objects, назвав файл "mypic.png"


Иконка - сохраняем в mods/MyMod/objects, назвав файл "mypic_icon.png"

Содержимое файла "mypic.object":

{ "objectName" : "mypic", "colonyTags" : ["pretty"], "rarity" : "Common", "description" : "Full description", "shortdescription" : "Short description", "race" : "generic", "category" : "decorative", "price" : 1000, "printable" : true, "apexDescription" : "Apex comment", "avianDescription" : "Avian comment", "floranDescription" : "Floran comment", "glitchDescription" : "Gltch comment", "humanDescription" : "Human comment", "hylotlDescription" : "Hylotl comment", "novakidDescription" : "Novakid comment", "inventoryIcon" : "mypic_icon.png", "orientations" : [ { "image" : "mypic.png", "imagePosition" : [0, 0], "frames" : 1, "animationCycle" : 0.5, "spaceScan" : 0.1, "anchors" : [ "background" ] } ] }

"objectName" - это уникальное название объекта, т.е. - ID. Пишем только латиницей.

"colonyTags" - этот параметр обозначает какой колонист может появиться в комнате с объектом. Можно указывать несколько вариантов подобным образом - ["crafting","electronic"].
Возможные варианты можно глянуть здесь. Тэги с колонистами, это те, что Tenants - Yes.

"rarity" - редкость объекта. Пишем только латиницей, выбирая из заготовленных вариантов: "Common" (Обычный), "Uncommon" (Необычный), "Rare" (Редкий), "Legendary" (Легендарный).

"description" - подробное описание объекта.

"shortdescription" - название объекта.

"race" - к какой расе относится объект. "generic" - это общий вариант.
Известные мне варианты: "apex", "avian", "floran", "frogg", "generic", "glitch", "human", "hylotl".

"category" - категория объекта.

"price" - стоимость. Указываем только цифры.

"printable" - можно ли копировать объект на принтере. true - можно, false - нельзя.

"apexDescription", "avianDescription", "floranDescription", "glitchDescription", "humanDescription", "hylotlDescription", "novakidDescription" - комментарий игрового персонажа об объекте. Зависит от расы и произносится при клике на объект в режиме исследования (по умолчанию - N).

"inventoryIcon" - название файла-иконки объекта, используется в игровом инвентаре.

Далее идёт отдельная группа параметров "orientations", отвечающая за поведение объекта в игре.

"image" - это путь к png файлу, изображающему объект.

"imagePosition" - это координаты "центра" объекта.
"0, 0" обозначает самый центр изображения. "-5, -5" отклонит центр на 5 пиксов влево и 5 пиксов вниз.

"frames", "animationCycle" - в данном примере эти поля нас не интересуют, а потому оставляем их без изменений.

"anchors" - область на которую можно ставить объект. Мне известны следующие варианты: top - объект крепится к потолку. bottom - объект крепится к полу. background - объект крепится к заднему фону.

Правильно указав всю техническую информацию в файле "mypic.object" и подготовив графические файлы, мы добавили объект в игру. Самый простой способ добыть его - использовать консоль в игре.

Включаем игру, заходим на своего персонажа и вводим в консоль следующие команды:
/admin
/spawnitem mypic
В данном случае "mypic" - это название объекта, которое вы указали в поле "objectName".
Режим админа можно отключить повторным вводом команды /admin

Способ получения простой, но крайне топорный. Лучше добавим возможность создания картинки через стандартное окно крафта, доступное игровому персонажу.
Создание мода: крафтинг
Создаём в папке с нашим модом новую директорию, называем её "recipies". В ней создаём текстовый файл "mypic.recipe" со следующим содержимым:

{ "input" : [ { "item" : "money", "count" : 1 } ], "output" : { "item" : "mypic", "count" : 1 }, "groups" : [ "plain" ] }
"input" - это то, что требуется для крафта.

"output" - это то, что получится в результате крафта. В дополнительном параметре "item" указываем уникальное имя нашего объекта.

"groups" - это место или "станция", где происходит крафт. В данном случае - это базовое окно крафта (по умолчанию - C).

Рецепт создали, осталось "выучить" его.

Переходим в папку с нашим модом и создаём новый текстовый файл - "player.config.patch" с таким содержимым:

[ { "op" : "add", "path" : "/defaultBlueprints/tier1/-", "value" : { "item" : "mypic" } } ]

Всё, теперь через окно базового крафта можно создавать добавленный в игре декоративный объект.

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

Для чего конкретно это может понадобиться? .pak архив позволит хранить и передавать ваш мод одним файлом. Это обязательно нужно для загрузки вашего мода во всякие сторонние базы модов, типа "nexusmods/starbound" (прямую ссылку приводить не буду ибо там сплошная похабщина фурривая).

Также, вы можете распаковывать готовые моды и стандартные игровые файлы - в них можно смотреть как реализован тот или иной элемент, а также можно достать игровые спрайты, дабы использовать их шаблоном для своих.

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

Открыть консоль можно следующей манипуляцией:

На белом (пустом) пространстве окна нажимайте правой кнопкой мыши с зажатой клавишей Shift. В открывшемся меню выбирайте пункт "quot;Открыть меню команд" (если не зажать Shift, то этот пункт не будет виден) - после этого откроется окно для ввода консольных команд.
.pak - распаковка
Для распаковки архива используется подобная команда:

"win32\asset_unpacker.exe" "<путь к файлу для распаковки>" "<название директории, куда будут распакованы файлы>"

("win32\asset_unpacker.exe") - это путь к скрипту, ответственному за работу с .pak файлами. Тут ничего менять не нужно.

("<путь к файлу для распаковки>") - это полный путь к файлу, который следует распаковать, например - "assets\packed.pak".

("<название директории, куда будут распакованы файлы>") - это название директории, куда будут распакованы файлы из архивы. Если директории с указанным названием нет в папке с игрой, то она будет автоматически создана.

А теперь на практике. Команда
"win32\asset_unpacker.exe" "assets\packed.pak" "UnpackedAssets"
позволит распаковать архив со стандартными игровыми файлами.

После того, как вы введёте команду в консоль и нажмёте Enter, в директории с игрой появится новая папка "UnpackedAssets", в которой находятся все распакованные файлы. Обязательно дождитесь появления в консоли сообщения об окончании процесса распаковки. Сам процесс довольно длителен - у меня идёт примерно 6-7 минут.
.pak - упаковка
Для упаковки архива используется подобная команда:

"win32\asset_packer.exe" "<папка, которую надо упаковать>" "<куда положить архив>"

("win32\asset_unpacker.exe") - это путь к скрипту, ответственному за работу с .pak файлами. Тут ничего менять не нужно.

("<папка, которую надо упаковать>") - это путь к папке с вашим модом, который вы хотите упаковать в архив.

("<куда положить архив>") - это путь, куда автоматически будет размещён готовый архив. В этом же параметре указывается желаемое название архива. В конце обязательно указывайте .pak.

Пример готовой команды:

"win32\asset_packer.exe" "mods\pink_bed" "mods\pinkbed.pak"

После того, как вы введёте команду в консоль и нажмёте Enter, в папке mods появится новый архив pinkbed.pak с вашим модом внутри.

Этот файл можно давать его друзьям - если они положат этот архив в свою папку mods, то смогут играть с вашей модификацией.
Изменение игровых объектов
Изменение уже существующих в игре объектов - это один из самых простых видов модифицирования игры.

В первую очередь нужно распаковать стандартные игровые файлы, а затем найти в них предмет, который вы хотите изменить. Для примера использую какую-нибудь флэшку-дополнение для Набора Экологической Защиты (EPP).

Файлов довольно много, можно конечно в ручную их перебрать в поисках нужного объекта, но я предпочитаю пользоваться функцией поиска по файлам в Notepad+. Открываем программу, нажимаем Ctrl + F или в верхнем меню щёлкаем "Поиск", а затем "Найти".

В появившемся окошке переходим во вкладку "Найти в файлах".

В поле "Найти" вписываем ID или название нужного объекта. Рекомендую искать по ID - поиск будет более точный. ID предметов можно узнавать здесь - http://starbounder.org (официальная вики игры).

В поле "Папка" указываем путь к распакованным игровым файлам.

Ставим отметку "Во всех подпапках".

Всё указали? Кликаем "Найти всё".



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

Для ускорения процесса поиска можно искать только по определённым папкам с игровыми файлами.

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

Для примера я искал флэшку, дающую иммунитет к отравлению, её файл - "items/augments/back/poisonblockaugment.augment", следовательно, что нужно копировать его по точно такому же пути, воссозданному в папке с модом:

mymod/items/augments/back/poisonblockaugment.augment. Обязательно сохраняйте оригинальное название и расширение файла.

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

Следует учесть, что уже существующие в инвентаре флэшки не изменятся. Флэшки с обновлёнными параметрами нужно будет купить, выбить из монстров или "создать" через /spawnitem. Подобная особенность актуальна для большинства используемых игровых предметов.
О создании своих спрайтов
Для создания своего спрайта для своего объекта вам понадобится какой-нибудь графический редактор.

Готовый спрайт нужно сохранять в формате PNG.

Следует учесть, что в самой игре спрайт показывается несколько большим размером, чем он есть на самом деле. Если не ошибаюсь, то размер увеличивается в три раза. Иногда из-за этого создаётся впечатление, что спрайт «размазан».

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

Объект минимального размера занимает 1 игровой блок, размер спрайта для такого объекта - 8 на 8 пиксов. Очевидно, что объект со спрайтом размера 16 на 8 пиксов займёт в игре два блока в ширину и один высоту, а 16 на 16 – два блока в ширину и два высоту.

Перед тем как начать рисовать свою картинку-спрайт, заранее определитесь с тем, какого размера должен быть ваш объект в игре, дабы не пришлось перерисовывать готовое изображение из-за логического не соответствия размера объекта (обычная лампочка не может быть больше человека, кресло не может быть меньше пятки и так далее). Я сам сталкивался с такой ошибкой - было обидно за потраченное на рисование время.
Пример: Огнестрел для одной руки
В папке objects создаём новый текстовый файл "myrevolver.activeitem".

Также понадобится спрайт пистолета. Для пробы можно взять тот, что я подготовил. Сохраняем его в папку objects, назвав "myrevolver".

Содержимое файла "myrevolver.activeitem":

{ "itemName" : "myrevolver", "price" : 640, "maxStack" : 1, "rarity" : "Common", "description" : "Big gun", "shortdescription" : "My Revolver", "tooltipKind" : "gun", "category" : "pistol", "twoHanded" : false, "itemTags" : ["weapon","ranged","pistol"], "level" : 1, "inventoryIcon" : "myrevolver.png", "animation" : "/items/active/weapons/ranged/gun.animation", "animationParts" : { "butt" : "", "middle" : "myrevolver.png", "barrel" : "", "muzzleFlash" : "/items/active/weapons/ranged/muzzleflash.png" }, "animationCustom" : { "sounds" : { "fire" : ["/sfx/gun/revolver2.ogg"] } }, "baseOffset" : [0.5, 0.25], "muzzleOffset" : [1.4, 0.3], "scripts" : ["/items/active/weapons/ranged/gun.lua"], "elementalType" : "physical", "primaryAbility" : { "scripts" : ["/items/active/weapons/ranged/gunfire.lua"], "class" : "GunFire", "fireTime" : 0.6, "baseDps" : 6.25, "energyUsage" : 18.75, "inaccuracy" : 0.025, "projectileCount" : 1, "fireType" : "auto", "projectileType" : "standardbullet", "projectileParameters" : { "knockback" : 6 }, "stances" : { "idle" : { "armRotation" : 0, "weaponRotation" : 0, "twoHanded" : false, "allowRotate" : true, "allowFlip" : true }, "fire" : { "duration" : 0, "armRotation" : 3, "weaponRotation" : 3, "twoHanded" : false, "allowRotate" : false, "allowFlip" : false }, "cooldown" : { "duration" : 0.15, "armRotation" : 3, "weaponRotation" : 3, "twoHanded" : false, "allowRotate" : false, "allowFlip" : false } } }, "builder" : "/items/buildscripts/buildunrandweapon.lua" }

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

"objectName" - это уникальное название объекта, т.е. - ID. Пишем только латиницей.

"inventoryIcon" - если есть желание создать уникальную иконку оружия для инвентаря, то тут нужно указать путь к файлу иконки. Если иконки нет, то указываем основной спрайт оружия.

animationParts > "middle" - путь к спрайту пистолета.

animationParts > "muzzleFlash" - путь к спрайту, изображающему стрельбу, т.е. вспышку, вырывающуюся из дула оружия. В данном случае используется уже имеющийся в игре спрайт.

animationCustom > sounds > "fire" - путь к звуковому файлу, изображающему выстрел. В данном случае используется уже имеющийся в игре звук.

"baseOffset" - координаты рукоятки. Персонажи будут держать пистолет за указанную точку. "0, 0" - центр спрайта.

"muzzleOffset" - координаты дула. В этой точке будет появляться вспышка при стрельбе. "0, 0" - центр спрайта.

primaryAbility > "fireTime" - скорость стрельбы.

primaryAbility > "baseDps" - базовый урон.

primaryAbility > "energyUsage" - количество энергии, потребляемой на один выстрел.

primaryAbility > "inaccuracy" - погрешность стрельбы.
Пример: Огнестрел для двух рук
В папке objects создаём новый текстовый файл "myrifle.activeitem".

Также понадобится спрайт винтовки. Для пробы можно взять тот, что я подготовил. Сохраняем его в папку objects, назвав "myrifle".

Содержимое файла "myrifle.activeitem":

{ "itemName" : "myrifle", "price" : 960, "maxStack" : 1, "rarity" : "Common", "description" : "Fast gun", "shortdescription" : "My Rifle", "tooltipKind" : "gun", "category" : "assaultRifle", "twoHanded" : true, "itemTags" : ["weapon","ranged","assaultrifle"], "level" : 1, "inventoryIcon" : "myrifle.png", "animation" : "/items/active/weapons/ranged/gun.animation", "animationParts" : { "butt" : "", "middle" : "myrifle.png", "barrel" : "", "muzzleFlash" : "/items/active/weapons/ranged/muzzleflash.png" }, "animationCustom" : { "sounds" : { "fire" : ["/sfx/gun/ar1.ogg"] } }, "baseOffset" : [0.6, 0.15], "muzzleOffset" : [2.2, 0.125], "scripts" : ["/items/active/weapons/ranged/gun.lua"], "elementalType" : "physical", "primaryAbility" : { "scripts" : ["/items/active/weapons/ranged/gunfire.lua"], "class" : "GunFire", "fireTime" : 0.11, "baseDps" : 10.5, "energyUsage" : 31.5, "inaccuracy" : 0.02, "projectileCount" : 1, "fireType" : "auto", "projectileType" : "standardbullet", "projectileParameters" : { "knockback" : 5 }, "stances" : { "idle" : { "armRotation" : 0, "weaponRotation" : 0, "twoHanded" : true, "allowRotate" : true, "allowFlip" : true }, "fire" : { "duration" : 0, "armRotation" : 3, "weaponRotation" : 3, "twoHanded" : true, "allowRotate" : false, "allowFlip" : false }, "cooldown" : { "duration" : 0.11, "armRotation" : 3, "weaponRotation" : 3, "twoHanded" : true, "allowRotate" : false, "allowFlip" : false } } }, "altAbilityType" : "spray", "builder" : "/items/buildscripts/buildunrandweapon.lua" }

Большинство параметров по назначению идентичны огнестрелу для одной руки. Основное отличие в том, что есть возможность добавить второй режим огня для правой кнопки мыши - для этого используется параметр altAbilityType.

Простым образом можно указывать уже созданные разработчиками альтернативные режимы, вот известные мне вариации:

"altAbilityType" : "spray",
"altAbilityType" : "piercingshot",
"altAbilityType" : "grenadelauncher",
"altAbilityType" : "burstshot",
Пример: Контейнер-хранилище
Основной файл

Иконка

То что находится в /* */ или после // - комментарий. Игровой движок не обрабатывает подобные фрагменты.

Файл goldensafe.object:

{ "objectName" : "goldensafe", /* Уникальное название, т.е. ID. Пишем только латиницей */ "colonyTags" : ["storage"], /* Типы возможных колонистов в комнате с объектом */ "rarity" : "Rare", /* Редкость. Варианты: "Common" (Обычный), "Uncommon" (Необычный), "Rare" (Редкий), "Legendary" (Легендарный) */ "category" : "storage", "price" : 900, /* Стоимость. */ "description" : "Золотой сейф. Довольно тяжёлый.", /* Игровое описание. Можно использовать кирилицу */ "shortdescription" : "Золотой сейф", /* Игровое название. Можно использовать кирилицу */ "race" : "generic", /* Раса, к которой относится объект. Варианты: "generic", "apex", "avian", "floran", "frogg", "glitch", "human", "hylotl", "novakid" */ "health" : 5, /* Здоровье обьекта. Влияет на то, сколько времени нужно на снос установленного объекта манипулятором */ "printable" : false, /* Клонирование объекта на принтере. true - можно, false - нельзя */ "objectType" : "container", "tooltipKind" : "container", "apexDescription" : "Я обезьянко.", /* Комментарий Апексов */ "avianDescription" : "Чирик-чирик.", /* Комментарий Авиан */ "floranDescription" : "Я цветочег.", /* Комментарий Флоран */ "glitchDescription" : "Я ведроид.", /* Комментарий Глитчей */ "humanDescription" : "А я серый и ущербный на фоне остальных.", /* Комментарий Людей */ "hylotlDescription" : "Буль буль.", /* Комментарий Хилотлов */ "novakidDescription" : "Я - сгусток энергии в газовом облаке. Наука, самка собаки!", /* Комментарий Новакидов */ "inventoryIcon" : "goldensafe_icon.png", /* Путь к иконке объекта для инвентаря. Актуально, если в основном графическом файле объекта несколько кадров */ "orientations" : [ { "dualImage" : "goldensafe.png:<color>.<key>", /* Путь к основному графическому файлу */ "imagePosition" : [-8, 0], "spaceScan" : 0.1, "anchors" : [ "bottom" ], /* Куда ставится объект. top - к потолку. bottom - к полу. background - к задней стене. */ "collision" : "platform" /* Это значит, что на объект можно запрыгнуть */ } ], "openSounds" : [ "/sfx/objects/chest_small_open.ogg" ], /* Звук открытия контейнера */ "closeSounds" : [ "/sfx/objects/chest_small_close.ogg" ], /* Звук закрытия */ "slotCount" : 64, /* Количество слотов в контейнере */ "uiConfig" : "/interface/chests/chest<slots>.config", "frameCooldown" : 5, "autoCloseCooldown" : 3600 }

Файл goldensafe.frames:

{ "frameGrid" : { "size" : [24, 16], "dimensions" : [3, 1], "names" : [ [ "default.0", "default.1", "default.2" ] ] }, "aliases" : { "default.default" : "default.0" } }

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

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

Надеюсь, что данное руководство поможет кому-нибудь сделать свой первый успешный шажок в мир моддинга Starbound.

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

Полезные ссылки:
Официальный форум Chucklefish, посвящённый моддингу в Starbound
Форум в Steam, посвящённый моддингу в Starbound
Статья о моддинге на англоязычной вики по Starbound

Пожалуйста, сообщайте о найденных в руководстве ошибках и неточностях.

Успехов в создании ваших модификаций!


История изменений руководства:

27 февраля 2017
Руководство создано.

11 марта 2017
Добавлены примеры огнестрельного оружия.

16 марта 2017
Добавлен пример контейнера.

20 марта 2017
Добавлен раздел "Изменение игровых объектов".

28 марта 2017
Добавлен раздел "О создании своих спрайтов".
Упрощён основной пример руководства (убран этап создания необязательного для работы файла .frames).