Official Factorio Wiki - User contributions [en]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-18T13:11:52Z

Ucrij fender: /* Resolving common errors in modding */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Контроль ===

У більшості модифікацій є файл, який називається <code>control.lua</code>. Цей файл містить сценарії, які змушують мод робити речі під час гри, а не просто додавати суб'єкти до гри. Під час цього етапу запускається control.lua кожного мода, в його власномій інстанції lua (це означає відсутність взаємозв'язку без спеціальних налаштувань), яким він буде володіти на протязі решти сеансу відтворення. Оскільки це запускається щоразу, коли файл збереження створюється або завантажується, вам не потрібно перезапускати гру, щоб побачити зміни, внесені до файлу control.lua. Просто перезапуск або перезавантаження збереження повторно запустить цей етап. '''На цьому етапі є кілька інших застережень. Ознайомитися з ними можна на сторінці [http://lua-api.factorio.com/latest/Data-Lifecycle.html життєвих циклів даних] на веб-сайті API.'''

=== Час виконання(Runtime) ===

На цьому етапі мод встановлюється, і збереження працює. Доступ до всіх таблиць, що надаються в грі, можна зробити всередині обробників подій. (Більше про те, що нижче).

== Основні компоненти будь-якої модифікації Factorio ==

В більшості випадків модифікації мають декілька компонентів, які змушують функціонувати мод.

Модам, що визначають нові сутності, потрібно буде оголосити ці сутності в <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code> , або інший файл необхідний одному з цих трьох.

Модам з ігровими ефектами також знадобиться файл <code>control.lua</code>, щоб додати сценарій.

Моди з налаштованими налаштуваннями користувача будуть використовувати <code>ettings.lua</code> для опису цих параметрів.

Моди, що визначають будь-який ігровий елемент з читабельним іменем, також можуть містити каталог <code>locale</code> та підкаталоги з іменами/описами на одній або кількох мовах.

Мод, який ми будемо робити в цьому підручнику, буде включати в себе як прототипи data.lua, так і сценарії control.lua, щоб ви змогли ознайомитися з обома.

З часом спільнота визначилася з деякими умовами щодо того, як повинна виглядати структура каталогів модів. Дотримуватися їх до точно не потрібно, але слідуючи стандартам, можна покращити читабельність скриптів та полегшити обговорення помилок модів. Детальніше про структуру каталогів нижче.

== Туторіал ==
А тепер мить на яку ви чекали. Тож почнемо робити свій перший мод. Вам знадобиться:

* Власне сама Factorio
* Текстовий редактор або пре-процесор
* Розуміння написаного вище
* Розуміння Lua як мови програмування. Досить знати синтаксис і як він працює. Якщо у вас є попередній досвід програмування, працювати з ним не мусить бути складним.

Після того, як у вас з’явиться все це, ми можемо почати.

Для цього мода ми зробимо набір броні, який залишає вогонь позаду вас під час прогулянки. Броня буде повністю стійка до вогню, але слабша до фізичного пошкодження, ніж важка болня, зробивши її бронею для тактики "стріляй та біжи"(run&gun).

=== Створення структури каталогів ===

Як було згадано раніше, існує загальний неофіційний стандарт того, як робиться структура модифікації. Це в поєднанні зі [[Tutorial:Mod structure|стандартами самої гри]] трохи обмежує нас. Для початку створіть папку у папці [[Application directory|каталогу даних користувача]]/модів. Ця папка повинна мати конкретне ім'я, <code>FireArmor_0.1.0</code>. Закінчивши, каталог моди повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0

Потім всередині FireArmor_0.1.0 створіть два файли, <code>info.json</code> та <code>data.lua</code>. Тепер каталог повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== info.json ===

Потім всередині info.json скопіюйте та вставте в нього:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

Для пояснень:

{| class="wikitable"
! Об'єкт
! Пояснення
|-
| name
| Внутрішнє ім'я модифікації, воно використовується для ідентифікації вашого мода в коді.
|-
| version
| Версія модифікації. Це може бути все, що завгодно, за умови, що це числа розділені точками. Деякі моди починаються з 0.0.1 або 0.1.0, а інші слідують за версіями Factorio і починаються з 0.17.0 (для версії Factorio 0.17.x)
|-
| title
| Примітна назва вашого мода, це відображатиметься на екрані управління модифікаціями та під час надсилання його на портал модів.
|-
| author
| Назвисько(nickname) або ім'я.
|-
| contact
| Контактна інформація, щоб хтось міг знайти вас у разі проблеми.
|-
| homepage
| Ваш власний веб-сайт свого мода. Не вимагається.
|-
| factorio_version
| Версія гри для якої призначений мод, вона повинна відповідати версії, для якої ви розробляєте мод, 0.17 в цьому випадку.
|-
| dependencies
| Будь-які залежності вашого мода. "base" завжди мусить бути тут, тому база спочатку завантажується.
|-
| description
| ''Короткий'' опис модифікації
|}

І це все, щодо info.json! Наступний файл - це data.lua:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

Це досить простий файл, все, що ми робимо тут, - це лише змушуємо гру виконати файл під назвою item.lua в прототипах, який ми збираємося створити. Створіть у FireArmor_0.1.0 папку під назвою <code>prototypes</code>, потім всередині прототипів створіть файл під назвою <code>item.lua</code>. Ваш каталог мод тепер повинен [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 виглядати так]:
* (каталог користувача)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json
*** prototypes
**** item.lua

Зверніть увагу на зазначення каталогів та файлів.

=== Створення прототипу ===

Зараз у Factorio є два способи створення прототипів: короткий і довгий шлях. Довгий шлях вимагає копіювання існуючого визначення з одного з файлів lua за замовчуванням, забезпечених установкою Factorio, а короткий шлях просто використовує функцію lua для копіювання та зміни визначення. В цьому посыбнику ми зробимо це коротким шляхом.
В item.lua, зкопіюйте:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

Ми скопіювали визначення важкої броні, потім змінили її властивості та ввели її в ініціалізацію Factorio з data:extend. Перший рядок коду, мабуть, найцікавіший. <code>table.deepcopy</code> повністю копіює таблицю в іншу з data.raw. <code>data</code> - це таблиця, яка буде використовуватися грою для налаштування всесвіту Factorio. Насправді він містить функцію <code>extend(self,prototypes)</code> та таблицю, яку називають <code>raw</code>. Перший - звичний спосіб додавання нових речей до другого. Фактично в data.raw описані усі прототипи для гри. (Ви можете переглянути реалізацію у файлі [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). Важливо зазначити, що data.raw існує лише на етапі завантаження даних у грі. На етапі управління, коли гра працює, ви не можете прочитати ці дані; натомість ви читаєте оброблені значення через API з різних типів, таких як LuaEntityPrototype.

Окрім визначення прототипу елемента, ми також визначаємо його рецепт. Це необхідно, якщо ви хочете вміти зробити річ. Ми також встановлюємо його як увімкнене, для розблокування не потрібна технологія.

На даний момент мод виглядає [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 приблизно так].

=== Більше data.raw ===

Коли Factorio ініціалізується, всі прототипи поміщаються в таблицю під назвою data.raw. Ця таблиця містить усі типи, а в межах цих типів - окремі сутності. Ви раніше бачили, як ми скопіювали(deepcopied) визначення важкої броні та змінили деякі поля. Насправді переглянемо кожну лінію коду:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

Ми призначаємо змінну(variable) під назвою fireArmor, яка містить нашу копію визначення важкої броні. Зауважте як у data.raw знаходиться таблиця типів, яка містить усі визначення броні, а конкретна броня, яку ми шукаємо, називається важкою бронею. Наприклад, прототипом гравця буде:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Оскільки прототипом гравця(в лапках) є гравець, той тип відповідає його імені. Ви можете визначити новий тип гравця за допомогою модифікації. Ви можете побачити всі прототипи поля для сутності в її довгій декларації в програмі Factorio, за адресою /data/base/prototypes.

Ви, можливо, думаєте в цей момент: "Чи можу я змінити існуючі прототипи Factorio без створення нових?" Ну, відповідь - так! Ви просто отримаєте доступ до таблиці data.raw під час ініціадізації, у data-final-fixes.lua та зміните властивість. Наприклад, встановіть залізній скрині 1000 здоров'я:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

Причина, по якій цей код повинен бути у data-final-fixes.lua або data-updates.lua, полягає в тому, що це останній запуск файлу після запуску всіх файлів мод. Це запобігає (певною мірою) вашим змінам не змішуватись іншими модами. Звичайно, все-таки можливі несумісності. Ви повинні зазначити все, що вам відомо в описі вашого мода. Слід переглянути [http://lua-api.factorio.com/latest/Data-Lifecycle.html документацію розробника] про дані для більшої зрозумілості та точності.

Це також може бути застосоване до інших мод, а не лише до бази Факторио. Ви не можете модифікувати мод до тих пір, поки ви не додасте мод (який ви змінили своїм модом) до залежностей, щоб він завантажився першим.

=== Контрольні сценарії ===

А тепер, щоб доопрацювати мод, ми мусимо зробити це не просто простою бронею. Давайте подумаємо, що ми хочемо зробити броні. Ми хочемо, щоб броня періодично створювала вогонь по землі, коли ми ходимо з обладунками. Подія, яку ми будемо використовувати, називається on_tick, оскільки ми хочемо, щоб вогонь періодично створювався.

У папці мод створіть файл під назвою <code>control.lua</code>. Гра автоматично виконає цей файл, тому додавати до вимог його не потрібно.

Всередині control.lua скопіюйте та вставте наступне:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --поширений трюк, щоб зменшити частоту праці, ми не хочемо, щоб він виконувався не кожнен тік а кожні 30, коротше двічі на секунду
for index,player in pairs(game.connected_players) do --цикл для всих гравців на сервері або в локальній грі
--якщо гравець носить нашу броню
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--створити вогонь на місці стояння гравця
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

За допомогою коментарів lua у вищенаведеному коді досить легко зрозуміти як все працює, як ви отримаєте поточну броню, яку носить гравець, з defines.inventory.character_armor, яка є постійною інвентарем та як створювати вогонь. Прочитати список визначень [http://lua-api.factorio.com/latest/defines.html#defines.inventory можливо тут].

=== Локалізація ===

Якщо ви вже пробували завантажувати Factorio і намагаєтеся з модифікацією, можливо, ви помітили, що назва предмета броні говорить "Unknown key"(невідоме значення). Це означає, що Factorio має внутрішню назву, але він не знає, як він повинен виглядати для користувача. Отже, нам потрібно створити локалізацію для нашого мода.

У папці створіть папку під назвою <code>locale</code>, потім створіть іншу папку всередині, яка називається <code>en</code>([https://uk.wikipedia.org/wiki/ISO_639-1 ISO 639] для більшого), потім файл під назвою <code>config.cfg</code>.

Якщо ви знаєте іншу мову, ви також можете перекласти свій мод, зробивши інші файли кодових мов всередині локалі, наприклад de для німецької.

В config.cfg, вставте наступне:

<pre style="background-color:#AAFFAA!important; color:black">
[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Зверніть увагу, щр це не файл lua. Локальна обробка обробляється файлами конфігурації C, тому формат відрізняється.

== Закінчення підручника ==

Ну, мод закінчений. Оскільки цей мод є лише навчальним, балансу в ньому мало.

Однак ви можете взяти цей мод і змінити його для власного використання, змінюючи рецепти, додаючи технології, що завгодно.

== Вирішення поширених помилок під час модінгу ==

Якщо ви продовжите писати моди з нуля, а не з туторіалів, ви можете зіткнутися з поширеними помилками. Існує кілька типів помилок, з якими ви можете зіткнутися в програмуванні взагалі, і знання способів вирішення цих помилок дозволить вам продовжувати працювати.
=== Синтаксичні помилки ===

Мова програмування lua очікує, що речі будуть викладені певним чином. Якщо ви пропустите дужку, знак або крапку, ви побачите помилку синтаксису. Як приклад:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

Починаючи з версії 0.15, ви побачите помилку, подібну до наведеної вище, кожного разу, коли будете робити помилки синтаксису в межах визначення прототипу. Гра запропонує перезапустити, відключити тривожний мод, відключити всі модни або вийти. Розберемо помилку.

Відразу ми бачимо причину, чому Factorio не запустився. "Failed to load mods:" не вдалося завантажити модифікації. Отже, ми знаємо яка модифікація має помилку. Щоразу, коли у lua-рушія Factorio виникає синтаксична помилка, він надрукує міні стек-стежку, яка слідує за всіма потребами, перелічуючи порядок виклику. По-перше, ми бачимо, що проблема була опосередковано спричинена рядком 1 у data.lua. Тут немає жодних проблем, тому це повинен бути наступний запис, рядок 36 prototypes/item.lua. Після того, як він вказав, де це, він спробує дати вам оцінку, де в рядку проблема. Не довіряйте цій оцінці, лише приблизно довіряйте номеру рядка плюс-мінус кілька рядків.

В лінії 36 файла item.lua можна знайти:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Це не виглядає правильно. Ви можете бачити, чого не вистачає? Ми залишили "знак прирівнювання". Для новачків в програмуванні такі може бути неочевидним.
=== Нелогічні дії та нуль(nil) ===

У lua "нічого" визначається як nil. Це схоже на null в інших мовах програмування. Кожен раз, коли програміст намагається отримати доступ до чогось у таблиці, яка є нульовою, вони отримають помилку на зразок наступного:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

Помилка "attempt to index field ..."(спроба індексувати поле) часто викликана тим, що моддер вибирає з таблиці неіснуючих даних. Ці типи помилок завжди будуть ідентифіковані за їх рядком підпису, "спроба індексувати поле". Якщо ми подивимось на рядок 3 з control.lua, ми побачимо:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

Яке припущення зробив тут моддер? Ну, насправді є дві проблеми. Перше, що моддер припустив, що <code>game.players[23]</code> є дійсним гравцем, що не так. Ці помилки важко налагодити, якщо ви добре не знаєте входів та виходів модуляційного API.

Друга проблема набагато тонкіша, і вона не спрацює. Модер намагається надрукувати таблицю даних користувачів. [http://lua-api.factorio.com/latest/LuaPlayer Гравець] - це таблиця з кількома значеннями. Спробу надрукувати його буде помилкою, замість цього потрібна функція для друку.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-18T08:19:12Z

Ucrij fender: /* The finished tutorial mod */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Контроль ===

У більшості модифікацій є файл, який називається <code>control.lua</code>. Цей файл містить сценарії, які змушують мод робити речі під час гри, а не просто додавати суб'єкти до гри. Під час цього етапу запускається control.lua кожного мода, в його власномій інстанції lua (це означає відсутність взаємозв'язку без спеціальних налаштувань), яким він буде володіти на протязі решти сеансу відтворення. Оскільки це запускається щоразу, коли файл збереження створюється або завантажується, вам не потрібно перезапускати гру, щоб побачити зміни, внесені до файлу control.lua. Просто перезапуск або перезавантаження збереження повторно запустить цей етап. '''На цьому етапі є кілька інших застережень. Ознайомитися з ними можна на сторінці [http://lua-api.factorio.com/latest/Data-Lifecycle.html життєвих циклів даних] на веб-сайті API.'''

=== Час виконання(Runtime) ===

На цьому етапі мод встановлюється, і збереження працює. Доступ до всіх таблиць, що надаються в грі, можна зробити всередині обробників подій. (Більше про те, що нижче).

== Основні компоненти будь-якої модифікації Factorio ==

В більшості випадків модифікації мають декілька компонентів, які змушують функціонувати мод.

Модам, що визначають нові сутності, потрібно буде оголосити ці сутності в <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code> , або інший файл необхідний одному з цих трьох.

Модам з ігровими ефектами також знадобиться файл <code>control.lua</code>, щоб додати сценарій.

Моди з налаштованими налаштуваннями користувача будуть використовувати <code>ettings.lua</code> для опису цих параметрів.

Моди, що визначають будь-який ігровий елемент з читабельним іменем, також можуть містити каталог <code>locale</code> та підкаталоги з іменами/описами на одній або кількох мовах.

Мод, який ми будемо робити в цьому підручнику, буде включати в себе як прототипи data.lua, так і сценарії control.lua, щоб ви змогли ознайомитися з обома.

З часом спільнота визначилася з деякими умовами щодо того, як повинна виглядати структура каталогів модів. Дотримуватися їх до точно не потрібно, але слідуючи стандартам, можна покращити читабельність скриптів та полегшити обговорення помилок модів. Детальніше про структуру каталогів нижче.

== Туторіал ==
А тепер мить на яку ви чекали. Тож почнемо робити свій перший мод. Вам знадобиться:

* Власне сама Factorio
* Текстовий редактор або пре-процесор
* Розуміння написаного вище
* Розуміння Lua як мови програмування. Досить знати синтаксис і як він працює. Якщо у вас є попередній досвід програмування, працювати з ним не мусить бути складним.

Після того, як у вас з’явиться все це, ми можемо почати.

Для цього мода ми зробимо набір броні, який залишає вогонь позаду вас під час прогулянки. Броня буде повністю стійка до вогню, але слабша до фізичного пошкодження, ніж важка болня, зробивши її бронею для тактики "стріляй та біжи"(run&gun).

=== Створення структури каталогів ===

Як було згадано раніше, існує загальний неофіційний стандарт того, як робиться структура модифікації. Це в поєднанні зі [[Tutorial:Mod structure|стандартами самої гри]] трохи обмежує нас. Для початку створіть папку у папці [[Application directory|каталогу даних користувача]]/модів. Ця папка повинна мати конкретне ім'я, <code>FireArmor_0.1.0</code>. Закінчивши, каталог моди повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0

Потім всередині FireArmor_0.1.0 створіть два файли, <code>info.json</code> та <code>data.lua</code>. Тепер каталог повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== info.json ===

Потім всередині info.json скопіюйте та вставте в нього:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

Для пояснень:

{| class="wikitable"
! Об'єкт
! Пояснення
|-
| name
| Внутрішнє ім'я модифікації, воно використовується для ідентифікації вашого мода в коді.
|-
| version
| Версія модифікації. Це може бути все, що завгодно, за умови, що це числа розділені точками. Деякі моди починаються з 0.0.1 або 0.1.0, а інші слідують за версіями Factorio і починаються з 0.17.0 (для версії Factorio 0.17.x)
|-
| title
| Примітна назва вашого мода, це відображатиметься на екрані управління модифікаціями та під час надсилання його на портал модів.
|-
| author
| Назвисько(nickname) або ім'я.
|-
| contact
| Контактна інформація, щоб хтось міг знайти вас у разі проблеми.
|-
| homepage
| Ваш власний веб-сайт свого мода. Не вимагається.
|-
| factorio_version
| Версія гри для якої призначений мод, вона повинна відповідати версії, для якої ви розробляєте мод, 0.17 в цьому випадку.
|-
| dependencies
| Будь-які залежності вашого мода. "base" завжди мусить бути тут, тому база спочатку завантажується.
|-
| description
| ''Короткий'' опис модифікації
|}

І це все, щодо info.json! Наступний файл - це data.lua:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

Це досить простий файл, все, що ми робимо тут, - це лише змушуємо гру виконати файл під назвою item.lua в прототипах, який ми збираємося створити. Створіть у FireArmor_0.1.0 папку під назвою <code>prototypes</code>, потім всередині прототипів створіть файл під назвою <code>item.lua</code>. Ваш каталог мод тепер повинен [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 виглядати так]:
* (каталог користувача)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json
*** prototypes
**** item.lua

Зверніть увагу на зазначення каталогів та файлів.

=== Створення прототипу ===

Зараз у Factorio є два способи створення прототипів: короткий і довгий шлях. Довгий шлях вимагає копіювання існуючого визначення з одного з файлів lua за замовчуванням, забезпечених установкою Factorio, а короткий шлях просто використовує функцію lua для копіювання та зміни визначення. В цьому посыбнику ми зробимо це коротким шляхом.
В item.lua, зкопіюйте:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

Ми скопіювали визначення важкої броні, потім змінили її властивості та ввели її в ініціалізацію Factorio з data:extend. Перший рядок коду, мабуть, найцікавіший. <code>table.deepcopy</code> повністю копіює таблицю в іншу з data.raw. <code>data</code> - це таблиця, яка буде використовуватися грою для налаштування всесвіту Factorio. Насправді він містить функцію <code>extend(self,prototypes)</code> та таблицю, яку називають <code>raw</code>. Перший - звичний спосіб додавання нових речей до другого. Фактично в data.raw описані усі прототипи для гри. (Ви можете переглянути реалізацію у файлі [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). Важливо зазначити, що data.raw існує лише на етапі завантаження даних у грі. На етапі управління, коли гра працює, ви не можете прочитати ці дані; натомість ви читаєте оброблені значення через API з різних типів, таких як LuaEntityPrototype.

Окрім визначення прототипу елемента, ми також визначаємо його рецепт. Це необхідно, якщо ви хочете вміти зробити річ. Ми також встановлюємо його як увімкнене, для розблокування не потрібна технологія.

На даний момент мод виглядає [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 приблизно так].

=== Більше data.raw ===

Коли Factorio ініціалізується, всі прототипи поміщаються в таблицю під назвою data.raw. Ця таблиця містить усі типи, а в межах цих типів - окремі сутності. Ви раніше бачили, як ми скопіювали(deepcopied) визначення важкої броні та змінили деякі поля. Насправді переглянемо кожну лінію коду:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

Ми призначаємо змінну(variable) під назвою fireArmor, яка містить нашу копію визначення важкої броні. Зауважте як у data.raw знаходиться таблиця типів, яка містить усі визначення броні, а конкретна броня, яку ми шукаємо, називається важкою бронею. Наприклад, прототипом гравця буде:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Оскільки прототипом гравця(в лапках) є гравець, той тип відповідає його імені. Ви можете визначити новий тип гравця за допомогою модифікації. Ви можете побачити всі прототипи поля для сутності в її довгій декларації в програмі Factorio, за адресою /data/base/prototypes.

Ви, можливо, думаєте в цей момент: "Чи можу я змінити існуючі прототипи Factorio без створення нових?" Ну, відповідь - так! Ви просто отримаєте доступ до таблиці data.raw під час ініціадізації, у data-final-fixes.lua та зміните властивість. Наприклад, встановіть залізній скрині 1000 здоров'я:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

Причина, по якій цей код повинен бути у data-final-fixes.lua або data-updates.lua, полягає в тому, що це останній запуск файлу після запуску всіх файлів мод. Це запобігає (певною мірою) вашим змінам не змішуватись іншими модами. Звичайно, все-таки можливі несумісності. Ви повинні зазначити все, що вам відомо в описі вашого мода. Слід переглянути [http://lua-api.factorio.com/latest/Data-Lifecycle.html документацію розробника] про дані для більшої зрозумілості та точності.

Це також може бути застосоване до інших мод, а не лише до бази Факторио. Ви не можете модифікувати мод до тих пір, поки ви не додасте мод (який ви змінили своїм модом) до залежностей, щоб він завантажився першим.

=== Контрольні сценарії ===

А тепер, щоб доопрацювати мод, ми мусимо зробити це не просто простою бронею. Давайте подумаємо, що ми хочемо зробити броні. Ми хочемо, щоб броня періодично створювала вогонь по землі, коли ми ходимо з обладунками. Подія, яку ми будемо використовувати, називається on_tick, оскільки ми хочемо, щоб вогонь періодично створювався.

У папці мод створіть файл під назвою <code>control.lua</code>. Гра автоматично виконає цей файл, тому додавати до вимог його не потрібно.

Всередині control.lua скопіюйте та вставте наступне:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --поширений трюк, щоб зменшити частоту праці, ми не хочемо, щоб він виконувався не кожнен тік а кожні 30, коротше двічі на секунду
for index,player in pairs(game.connected_players) do --цикл для всих гравців на сервері або в локальній грі
--якщо гравець носить нашу броню
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--створити вогонь на місці стояння гравця
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

За допомогою коментарів lua у вищенаведеному коді досить легко зрозуміти як все працює, як ви отримаєте поточну броню, яку носить гравець, з defines.inventory.character_armor, яка є постійною інвентарем та як створювати вогонь. Прочитати список визначень [http://lua-api.factorio.com/latest/defines.html#defines.inventory можливо тут].

=== Локалізація ===

Якщо ви вже пробували завантажувати Factorio і намагаєтеся з модифікацією, можливо, ви помітили, що назва предмета броні говорить "Unknown key"(невідоме значення). Це означає, що Factorio має внутрішню назву, але він не знає, як він повинен виглядати для користувача. Отже, нам потрібно створити локалізацію для нашого мода.

У папці створіть папку під назвою <code>locale</code>, потім створіть іншу папку всередині, яка називається <code>en</code>([https://uk.wikipedia.org/wiki/ISO_639-1 ISO 639] для більшого), потім файл під назвою <code>config.cfg</code>.

Якщо ви знаєте іншу мову, ви також можете перекласти свій мод, зробивши інші файли кодових мов всередині локалі, наприклад de для німецької.

В config.cfg, вставте наступне:

<pre style="background-color:#AAFFAA!important; color:black">
[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Зверніть увагу, щр це не файл lua. Локальна обробка обробляється файлами конфігурації C, тому формат відрізняється.

== Закінчення підручника ==

Ну, мод закінчений. Оскільки цей мод є лише навчальним, балансу в ньому мало.

Однак ви можете взяти цей мод і змінити його для власного використання, змінюючи рецепти, додаючи технології, що завгодно.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-18T08:14:44Z

Ucrij fender: /* Locale */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Контроль ===

У більшості модифікацій є файл, який називається <code>control.lua</code>. Цей файл містить сценарії, які змушують мод робити речі під час гри, а не просто додавати суб'єкти до гри. Під час цього етапу запускається control.lua кожного мода, в його власномій інстанції lua (це означає відсутність взаємозв'язку без спеціальних налаштувань), яким він буде володіти на протязі решти сеансу відтворення. Оскільки це запускається щоразу, коли файл збереження створюється або завантажується, вам не потрібно перезапускати гру, щоб побачити зміни, внесені до файлу control.lua. Просто перезапуск або перезавантаження збереження повторно запустить цей етап. '''На цьому етапі є кілька інших застережень. Ознайомитися з ними можна на сторінці [http://lua-api.factorio.com/latest/Data-Lifecycle.html життєвих циклів даних] на веб-сайті API.'''

=== Час виконання(Runtime) ===

На цьому етапі мод встановлюється, і збереження працює. Доступ до всіх таблиць, що надаються в грі, можна зробити всередині обробників подій. (Більше про те, що нижче).

== Основні компоненти будь-якої модифікації Factorio ==

В більшості випадків модифікації мають декілька компонентів, які змушують функціонувати мод.

Модам, що визначають нові сутності, потрібно буде оголосити ці сутності в <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code> , або інший файл необхідний одному з цих трьох.

Модам з ігровими ефектами також знадобиться файл <code>control.lua</code>, щоб додати сценарій.

Моди з налаштованими налаштуваннями користувача будуть використовувати <code>ettings.lua</code> для опису цих параметрів.

Моди, що визначають будь-який ігровий елемент з читабельним іменем, також можуть містити каталог <code>locale</code> та підкаталоги з іменами/описами на одній або кількох мовах.

Мод, який ми будемо робити в цьому підручнику, буде включати в себе як прототипи data.lua, так і сценарії control.lua, щоб ви змогли ознайомитися з обома.

З часом спільнота визначилася з деякими умовами щодо того, як повинна виглядати структура каталогів модів. Дотримуватися їх до точно не потрібно, але слідуючи стандартам, можна покращити читабельність скриптів та полегшити обговорення помилок модів. Детальніше про структуру каталогів нижче.

== Туторіал ==
А тепер мить на яку ви чекали. Тож почнемо робити свій перший мод. Вам знадобиться:

* Власне сама Factorio
* Текстовий редактор або пре-процесор
* Розуміння написаного вище
* Розуміння Lua як мови програмування. Досить знати синтаксис і як він працює. Якщо у вас є попередній досвід програмування, працювати з ним не мусить бути складним.

Після того, як у вас з’явиться все це, ми можемо почати.

Для цього мода ми зробимо набір броні, який залишає вогонь позаду вас під час прогулянки. Броня буде повністю стійка до вогню, але слабша до фізичного пошкодження, ніж важка болня, зробивши її бронею для тактики "стріляй та біжи"(run&gun).

=== Створення структури каталогів ===

Як було згадано раніше, існує загальний неофіційний стандарт того, як робиться структура модифікації. Це в поєднанні зі [[Tutorial:Mod structure|стандартами самої гри]] трохи обмежує нас. Для початку створіть папку у папці [[Application directory|каталогу даних користувача]]/модів. Ця папка повинна мати конкретне ім'я, <code>FireArmor_0.1.0</code>. Закінчивши, каталог моди повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0

Потім всередині FireArmor_0.1.0 створіть два файли, <code>info.json</code> та <code>data.lua</code>. Тепер каталог повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== info.json ===

Потім всередині info.json скопіюйте та вставте в нього:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

Для пояснень:

{| class="wikitable"
! Об'єкт
! Пояснення
|-
| name
| Внутрішнє ім'я модифікації, воно використовується для ідентифікації вашого мода в коді.
|-
| version
| Версія модифікації. Це може бути все, що завгодно, за умови, що це числа розділені точками. Деякі моди починаються з 0.0.1 або 0.1.0, а інші слідують за версіями Factorio і починаються з 0.17.0 (для версії Factorio 0.17.x)
|-
| title
| Примітна назва вашого мода, це відображатиметься на екрані управління модифікаціями та під час надсилання його на портал модів.
|-
| author
| Назвисько(nickname) або ім'я.
|-
| contact
| Контактна інформація, щоб хтось міг знайти вас у разі проблеми.
|-
| homepage
| Ваш власний веб-сайт свого мода. Не вимагається.
|-
| factorio_version
| Версія гри для якої призначений мод, вона повинна відповідати версії, для якої ви розробляєте мод, 0.17 в цьому випадку.
|-
| dependencies
| Будь-які залежності вашого мода. "base" завжди мусить бути тут, тому база спочатку завантажується.
|-
| description
| ''Короткий'' опис модифікації
|}

І це все, щодо info.json! Наступний файл - це data.lua:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

Це досить простий файл, все, що ми робимо тут, - це лише змушуємо гру виконати файл під назвою item.lua в прототипах, який ми збираємося створити. Створіть у FireArmor_0.1.0 папку під назвою <code>prototypes</code>, потім всередині прототипів створіть файл під назвою <code>item.lua</code>. Ваш каталог мод тепер повинен [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 виглядати так]:
* (каталог користувача)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json
*** prototypes
**** item.lua

Зверніть увагу на зазначення каталогів та файлів.

=== Створення прототипу ===

Зараз у Factorio є два способи створення прототипів: короткий і довгий шлях. Довгий шлях вимагає копіювання існуючого визначення з одного з файлів lua за замовчуванням, забезпечених установкою Factorio, а короткий шлях просто використовує функцію lua для копіювання та зміни визначення. В цьому посыбнику ми зробимо це коротким шляхом.
В item.lua, зкопіюйте:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

Ми скопіювали визначення важкої броні, потім змінили її властивості та ввели її в ініціалізацію Factorio з data:extend. Перший рядок коду, мабуть, найцікавіший. <code>table.deepcopy</code> повністю копіює таблицю в іншу з data.raw. <code>data</code> - це таблиця, яка буде використовуватися грою для налаштування всесвіту Factorio. Насправді він містить функцію <code>extend(self,prototypes)</code> та таблицю, яку називають <code>raw</code>. Перший - звичний спосіб додавання нових речей до другого. Фактично в data.raw описані усі прототипи для гри. (Ви можете переглянути реалізацію у файлі [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). Важливо зазначити, що data.raw існує лише на етапі завантаження даних у грі. На етапі управління, коли гра працює, ви не можете прочитати ці дані; натомість ви читаєте оброблені значення через API з різних типів, таких як LuaEntityPrototype.

Окрім визначення прототипу елемента, ми також визначаємо його рецепт. Це необхідно, якщо ви хочете вміти зробити річ. Ми також встановлюємо його як увімкнене, для розблокування не потрібна технологія.

На даний момент мод виглядає [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 приблизно так].

=== Більше data.raw ===

Коли Factorio ініціалізується, всі прототипи поміщаються в таблицю під назвою data.raw. Ця таблиця містить усі типи, а в межах цих типів - окремі сутності. Ви раніше бачили, як ми скопіювали(deepcopied) визначення важкої броні та змінили деякі поля. Насправді переглянемо кожну лінію коду:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

Ми призначаємо змінну(variable) під назвою fireArmor, яка містить нашу копію визначення важкої броні. Зауважте як у data.raw знаходиться таблиця типів, яка містить усі визначення броні, а конкретна броня, яку ми шукаємо, називається важкою бронею. Наприклад, прототипом гравця буде:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Оскільки прототипом гравця(в лапках) є гравець, той тип відповідає його імені. Ви можете визначити новий тип гравця за допомогою модифікації. Ви можете побачити всі прототипи поля для сутності в її довгій декларації в програмі Factorio, за адресою /data/base/prototypes.

Ви, можливо, думаєте в цей момент: "Чи можу я змінити існуючі прототипи Factorio без створення нових?" Ну, відповідь - так! Ви просто отримаєте доступ до таблиці data.raw під час ініціадізації, у data-final-fixes.lua та зміните властивість. Наприклад, встановіть залізній скрині 1000 здоров'я:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

Причина, по якій цей код повинен бути у data-final-fixes.lua або data-updates.lua, полягає в тому, що це останній запуск файлу після запуску всіх файлів мод. Це запобігає (певною мірою) вашим змінам не змішуватись іншими модами. Звичайно, все-таки можливі несумісності. Ви повинні зазначити все, що вам відомо в описі вашого мода. Слід переглянути [http://lua-api.factorio.com/latest/Data-Lifecycle.html документацію розробника] про дані для більшої зрозумілості та точності.

Це також може бути застосоване до інших мод, а не лише до бази Факторио. Ви не можете модифікувати мод до тих пір, поки ви не додасте мод (який ви змінили своїм модом) до залежностей, щоб він завантажився першим.

=== Контрольні сценарії ===

А тепер, щоб доопрацювати мод, ми мусимо зробити це не просто простою бронею. Давайте подумаємо, що ми хочемо зробити броні. Ми хочемо, щоб броня періодично створювала вогонь по землі, коли ми ходимо з обладунками. Подія, яку ми будемо використовувати, називається on_tick, оскільки ми хочемо, щоб вогонь періодично створювався.

У папці мод створіть файл під назвою <code>control.lua</code>. Гра автоматично виконає цей файл, тому додавати до вимог його не потрібно.

Всередині control.lua скопіюйте та вставте наступне:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --поширений трюк, щоб зменшити частоту праці, ми не хочемо, щоб він виконувався не кожнен тік а кожні 30, коротше двічі на секунду
for index,player in pairs(game.connected_players) do --цикл для всих гравців на сервері або в локальній грі
--якщо гравець носить нашу броню
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--створити вогонь на місці стояння гравця
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

За допомогою коментарів lua у вищенаведеному коді досить легко зрозуміти як все працює, як ви отримаєте поточну броню, яку носить гравець, з defines.inventory.character_armor, яка є постійною інвентарем та як створювати вогонь. Прочитати список визначень [http://lua-api.factorio.com/latest/defines.html#defines.inventory можливо тут].

=== Локалізація ===

Якщо ви вже пробували завантажувати Factorio і намагаєтеся з модифікацією, можливо, ви помітили, що назва предмета броні говорить "Unknown key"(невідоме значення). Це означає, що Factorio має внутрішню назву, але він не знає, як він повинен виглядати для користувача. Отже, нам потрібно створити локалізацію для нашого мода.

У папці створіть папку під назвою <code>locale</code>, потім створіть іншу папку всередині, яка називається <code>en</code>([https://uk.wikipedia.org/wiki/ISO_639-1 ISO 639] для більшого), потім файл під назвою <code>config.cfg</code>.

Якщо ви знаєте іншу мову, ви також можете перекласти свій мод, зробивши інші файли кодових мов всередині локалі, наприклад de для німецької.

В config.cfg, вставте наступне:

<pre style="background-color:#AAFFAA!important; color:black">
[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Зверніть увагу, щр це не файл lua. Локальна обробка обробляється файлами конфігурації C, тому формат відрізняється.

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-18T08:02:36Z

Ucrij fender: /* The control scripting */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Контроль ===

У більшості модифікацій є файл, який називається <code>control.lua</code>. Цей файл містить сценарії, які змушують мод робити речі під час гри, а не просто додавати суб'єкти до гри. Під час цього етапу запускається control.lua кожного мода, в його власномій інстанції lua (це означає відсутність взаємозв'язку без спеціальних налаштувань), яким він буде володіти на протязі решти сеансу відтворення. Оскільки це запускається щоразу, коли файл збереження створюється або завантажується, вам не потрібно перезапускати гру, щоб побачити зміни, внесені до файлу control.lua. Просто перезапуск або перезавантаження збереження повторно запустить цей етап. '''На цьому етапі є кілька інших застережень. Ознайомитися з ними можна на сторінці [http://lua-api.factorio.com/latest/Data-Lifecycle.html життєвих циклів даних] на веб-сайті API.'''

=== Час виконання(Runtime) ===

На цьому етапі мод встановлюється, і збереження працює. Доступ до всіх таблиць, що надаються в грі, можна зробити всередині обробників подій. (Більше про те, що нижче).

== Основні компоненти будь-якої модифікації Factorio ==

В більшості випадків модифікації мають декілька компонентів, які змушують функціонувати мод.

Модам, що визначають нові сутності, потрібно буде оголосити ці сутності в <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code> , або інший файл необхідний одному з цих трьох.

Модам з ігровими ефектами також знадобиться файл <code>control.lua</code>, щоб додати сценарій.

Моди з налаштованими налаштуваннями користувача будуть використовувати <code>ettings.lua</code> для опису цих параметрів.

Моди, що визначають будь-який ігровий елемент з читабельним іменем, також можуть містити каталог <code>locale</code> та підкаталоги з іменами/описами на одній або кількох мовах.

Мод, який ми будемо робити в цьому підручнику, буде включати в себе як прототипи data.lua, так і сценарії control.lua, щоб ви змогли ознайомитися з обома.

З часом спільнота визначилася з деякими умовами щодо того, як повинна виглядати структура каталогів модів. Дотримуватися їх до точно не потрібно, але слідуючи стандартам, можна покращити читабельність скриптів та полегшити обговорення помилок модів. Детальніше про структуру каталогів нижче.

== Туторіал ==
А тепер мить на яку ви чекали. Тож почнемо робити свій перший мод. Вам знадобиться:

* Власне сама Factorio
* Текстовий редактор або пре-процесор
* Розуміння написаного вище
* Розуміння Lua як мови програмування. Досить знати синтаксис і як він працює. Якщо у вас є попередній досвід програмування, працювати з ним не мусить бути складним.

Після того, як у вас з’явиться все це, ми можемо почати.

Для цього мода ми зробимо набір броні, який залишає вогонь позаду вас під час прогулянки. Броня буде повністю стійка до вогню, але слабша до фізичного пошкодження, ніж важка болня, зробивши її бронею для тактики "стріляй та біжи"(run&gun).

=== Створення структури каталогів ===

Як було згадано раніше, існує загальний неофіційний стандарт того, як робиться структура модифікації. Це в поєднанні зі [[Tutorial:Mod structure|стандартами самої гри]] трохи обмежує нас. Для початку створіть папку у папці [[Application directory|каталогу даних користувача]]/модів. Ця папка повинна мати конкретне ім'я, <code>FireArmor_0.1.0</code>. Закінчивши, каталог моди повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0

Потім всередині FireArmor_0.1.0 створіть два файли, <code>info.json</code> та <code>data.lua</code>. Тепер каталог повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== info.json ===

Потім всередині info.json скопіюйте та вставте в нього:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

Для пояснень:

{| class="wikitable"
! Об'єкт
! Пояснення
|-
| name
| Внутрішнє ім'я модифікації, воно використовується для ідентифікації вашого мода в коді.
|-
| version
| Версія модифікації. Це може бути все, що завгодно, за умови, що це числа розділені точками. Деякі моди починаються з 0.0.1 або 0.1.0, а інші слідують за версіями Factorio і починаються з 0.17.0 (для версії Factorio 0.17.x)
|-
| title
| Примітна назва вашого мода, це відображатиметься на екрані управління модифікаціями та під час надсилання його на портал модів.
|-
| author
| Назвисько(nickname) або ім'я.
|-
| contact
| Контактна інформація, щоб хтось міг знайти вас у разі проблеми.
|-
| homepage
| Ваш власний веб-сайт свого мода. Не вимагається.
|-
| factorio_version
| Версія гри для якої призначений мод, вона повинна відповідати версії, для якої ви розробляєте мод, 0.17 в цьому випадку.
|-
| dependencies
| Будь-які залежності вашого мода. "base" завжди мусить бути тут, тому база спочатку завантажується.
|-
| description
| ''Короткий'' опис модифікації
|}

І це все, щодо info.json! Наступний файл - це data.lua:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

Це досить простий файл, все, що ми робимо тут, - це лише змушуємо гру виконати файл під назвою item.lua в прототипах, який ми збираємося створити. Створіть у FireArmor_0.1.0 папку під назвою <code>prototypes</code>, потім всередині прототипів створіть файл під назвою <code>item.lua</code>. Ваш каталог мод тепер повинен [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 виглядати так]:
* (каталог користувача)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json
*** prototypes
**** item.lua

Зверніть увагу на зазначення каталогів та файлів.

=== Створення прототипу ===

Зараз у Factorio є два способи створення прототипів: короткий і довгий шлях. Довгий шлях вимагає копіювання існуючого визначення з одного з файлів lua за замовчуванням, забезпечених установкою Factorio, а короткий шлях просто використовує функцію lua для копіювання та зміни визначення. В цьому посыбнику ми зробимо це коротким шляхом.
В item.lua, зкопіюйте:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

Ми скопіювали визначення важкої броні, потім змінили її властивості та ввели її в ініціалізацію Factorio з data:extend. Перший рядок коду, мабуть, найцікавіший. <code>table.deepcopy</code> повністю копіює таблицю в іншу з data.raw. <code>data</code> - це таблиця, яка буде використовуватися грою для налаштування всесвіту Factorio. Насправді він містить функцію <code>extend(self,prototypes)</code> та таблицю, яку називають <code>raw</code>. Перший - звичний спосіб додавання нових речей до другого. Фактично в data.raw описані усі прототипи для гри. (Ви можете переглянути реалізацію у файлі [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). Важливо зазначити, що data.raw існує лише на етапі завантаження даних у грі. На етапі управління, коли гра працює, ви не можете прочитати ці дані; натомість ви читаєте оброблені значення через API з різних типів, таких як LuaEntityPrototype.

Окрім визначення прототипу елемента, ми також визначаємо його рецепт. Це необхідно, якщо ви хочете вміти зробити річ. Ми також встановлюємо його як увімкнене, для розблокування не потрібна технологія.

На даний момент мод виглядає [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 приблизно так].

=== Більше data.raw ===

Коли Factorio ініціалізується, всі прототипи поміщаються в таблицю під назвою data.raw. Ця таблиця містить усі типи, а в межах цих типів - окремі сутності. Ви раніше бачили, як ми скопіювали(deepcopied) визначення важкої броні та змінили деякі поля. Насправді переглянемо кожну лінію коду:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

Ми призначаємо змінну(variable) під назвою fireArmor, яка містить нашу копію визначення важкої броні. Зауважте як у data.raw знаходиться таблиця типів, яка містить усі визначення броні, а конкретна броня, яку ми шукаємо, називається важкою бронею. Наприклад, прототипом гравця буде:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Оскільки прототипом гравця(в лапках) є гравець, той тип відповідає його імені. Ви можете визначити новий тип гравця за допомогою модифікації. Ви можете побачити всі прототипи поля для сутності в її довгій декларації в програмі Factorio, за адресою /data/base/prototypes.

Ви, можливо, думаєте в цей момент: "Чи можу я змінити існуючі прототипи Factorio без створення нових?" Ну, відповідь - так! Ви просто отримаєте доступ до таблиці data.raw під час ініціадізації, у data-final-fixes.lua та зміните властивість. Наприклад, встановіть залізній скрині 1000 здоров'я:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

Причина, по якій цей код повинен бути у data-final-fixes.lua або data-updates.lua, полягає в тому, що це останній запуск файлу після запуску всіх файлів мод. Це запобігає (певною мірою) вашим змінам не змішуватись іншими модами. Звичайно, все-таки можливі несумісності. Ви повинні зазначити все, що вам відомо в описі вашого мода. Слід переглянути [http://lua-api.factorio.com/latest/Data-Lifecycle.html документацію розробника] про дані для більшої зрозумілості та точності.

Це також може бути застосоване до інших мод, а не лише до бази Факторио. Ви не можете модифікувати мод до тих пір, поки ви не додасте мод (який ви змінили своїм модом) до залежностей, щоб він завантажився першим.

=== Контрольні сценарії ===

А тепер, щоб доопрацювати мод, ми мусимо зробити це не просто простою бронею. Давайте подумаємо, що ми хочемо зробити броні. Ми хочемо, щоб броня періодично створювала вогонь по землі, коли ми ходимо з обладунками. Подія, яку ми будемо використовувати, називається on_tick, оскільки ми хочемо, щоб вогонь періодично створювався.

У папці мод створіть файл під назвою <code>control.lua</code>. Гра автоматично виконає цей файл, тому додавати до вимог його не потрібно.

Всередині control.lua скопіюйте та вставте наступне:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --поширений трюк, щоб зменшити частоту праці, ми не хочемо, щоб він виконувався не кожнен тік а кожні 30, коротше двічі на секунду
for index,player in pairs(game.connected_players) do --цикл для всих гравців на сервері або в локальній грі
--якщо гравець носить нашу броню
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--створити вогонь на місці стояння гравця
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

За допомогою коментарів lua у вищенаведеному коді досить легко зрозуміти як все працює, як ви отримаєте поточну броню, яку носить гравець, з defines.inventory.character_armor, яка є постійною інвентарем та як створювати вогонь. Прочитати список визначень [http://lua-api.factorio.com/latest/defines.html#defines.inventory можливо тут].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-18T07:31:49Z

Ucrij fender: /* More on data.raw */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Контроль ===

У більшості модифікацій є файл, який називається <code>control.lua</code>. Цей файл містить сценарії, які змушують мод робити речі під час гри, а не просто додавати суб'єкти до гри. Під час цього етапу запускається control.lua кожного мода, в його власномій інстанції lua (це означає відсутність взаємозв'язку без спеціальних налаштувань), яким він буде володіти на протязі решти сеансу відтворення. Оскільки це запускається щоразу, коли файл збереження створюється або завантажується, вам не потрібно перезапускати гру, щоб побачити зміни, внесені до файлу control.lua. Просто перезапуск або перезавантаження збереження повторно запустить цей етап. '''На цьому етапі є кілька інших застережень. Ознайомитися з ними можна на сторінці [http://lua-api.factorio.com/latest/Data-Lifecycle.html життєвих циклів даних] на веб-сайті API.'''

=== Час виконання(Runtime) ===

На цьому етапі мод встановлюється, і збереження працює. Доступ до всіх таблиць, що надаються в грі, можна зробити всередині обробників подій. (Більше про те, що нижче).

== Основні компоненти будь-якої модифікації Factorio ==

В більшості випадків модифікації мають декілька компонентів, які змушують функціонувати мод.

Модам, що визначають нові сутності, потрібно буде оголосити ці сутності в <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code> , або інший файл необхідний одному з цих трьох.

Модам з ігровими ефектами також знадобиться файл <code>control.lua</code>, щоб додати сценарій.

Моди з налаштованими налаштуваннями користувача будуть використовувати <code>ettings.lua</code> для опису цих параметрів.

Моди, що визначають будь-який ігровий елемент з читабельним іменем, також можуть містити каталог <code>locale</code> та підкаталоги з іменами/описами на одній або кількох мовах.

Мод, який ми будемо робити в цьому підручнику, буде включати в себе як прототипи data.lua, так і сценарії control.lua, щоб ви змогли ознайомитися з обома.

З часом спільнота визначилася з деякими умовами щодо того, як повинна виглядати структура каталогів модів. Дотримуватися їх до точно не потрібно, але слідуючи стандартам, можна покращити читабельність скриптів та полегшити обговорення помилок модів. Детальніше про структуру каталогів нижче.

== Туторіал ==
А тепер мить на яку ви чекали. Тож почнемо робити свій перший мод. Вам знадобиться:

* Власне сама Factorio
* Текстовий редактор або пре-процесор
* Розуміння написаного вище
* Розуміння Lua як мови програмування. Досить знати синтаксис і як він працює. Якщо у вас є попередній досвід програмування, працювати з ним не мусить бути складним.

Після того, як у вас з’явиться все це, ми можемо почати.

Для цього мода ми зробимо набір броні, який залишає вогонь позаду вас під час прогулянки. Броня буде повністю стійка до вогню, але слабша до фізичного пошкодження, ніж важка болня, зробивши її бронею для тактики "стріляй та біжи"(run&gun).

=== Створення структури каталогів ===

Як було згадано раніше, існує загальний неофіційний стандарт того, як робиться структура модифікації. Це в поєднанні зі [[Tutorial:Mod structure|стандартами самої гри]] трохи обмежує нас. Для початку створіть папку у папці [[Application directory|каталогу даних користувача]]/модів. Ця папка повинна мати конкретне ім'я, <code>FireArmor_0.1.0</code>. Закінчивши, каталог моди повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0

Потім всередині FireArmor_0.1.0 створіть два файли, <code>info.json</code> та <code>data.lua</code>. Тепер каталог повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== info.json ===

Потім всередині info.json скопіюйте та вставте в нього:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

Для пояснень:

{| class="wikitable"
! Об'єкт
! Пояснення
|-
| name
| Внутрішнє ім'я модифікації, воно використовується для ідентифікації вашого мода в коді.
|-
| version
| Версія модифікації. Це може бути все, що завгодно, за умови, що це числа розділені точками. Деякі моди починаються з 0.0.1 або 0.1.0, а інші слідують за версіями Factorio і починаються з 0.17.0 (для версії Factorio 0.17.x)
|-
| title
| Примітна назва вашого мода, це відображатиметься на екрані управління модифікаціями та під час надсилання його на портал модів.
|-
| author
| Назвисько(nickname) або ім'я.
|-
| contact
| Контактна інформація, щоб хтось міг знайти вас у разі проблеми.
|-
| homepage
| Ваш власний веб-сайт свого мода. Не вимагається.
|-
| factorio_version
| Версія гри для якої призначений мод, вона повинна відповідати версії, для якої ви розробляєте мод, 0.17 в цьому випадку.
|-
| dependencies
| Будь-які залежності вашого мода. "base" завжди мусить бути тут, тому база спочатку завантажується.
|-
| description
| ''Короткий'' опис модифікації
|}

І це все, щодо info.json! Наступний файл - це data.lua:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

Це досить простий файл, все, що ми робимо тут, - це лише змушуємо гру виконати файл під назвою item.lua в прототипах, який ми збираємося створити. Створіть у FireArmor_0.1.0 папку під назвою <code>prototypes</code>, потім всередині прототипів створіть файл під назвою <code>item.lua</code>. Ваш каталог мод тепер повинен [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 виглядати так]:
* (каталог користувача)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json
*** prototypes
**** item.lua

Зверніть увагу на зазначення каталогів та файлів.

=== Створення прототипу ===

Зараз у Factorio є два способи створення прототипів: короткий і довгий шлях. Довгий шлях вимагає копіювання існуючого визначення з одного з файлів lua за замовчуванням, забезпечених установкою Factorio, а короткий шлях просто використовує функцію lua для копіювання та зміни визначення. В цьому посыбнику ми зробимо це коротким шляхом.
В item.lua, зкопіюйте:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

Ми скопіювали визначення важкої броні, потім змінили її властивості та ввели її в ініціалізацію Factorio з data:extend. Перший рядок коду, мабуть, найцікавіший. <code>table.deepcopy</code> повністю копіює таблицю в іншу з data.raw. <code>data</code> - це таблиця, яка буде використовуватися грою для налаштування всесвіту Factorio. Насправді він містить функцію <code>extend(self,prototypes)</code> та таблицю, яку називають <code>raw</code>. Перший - звичний спосіб додавання нових речей до другого. Фактично в data.raw описані усі прототипи для гри. (Ви можете переглянути реалізацію у файлі [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). Важливо зазначити, що data.raw існує лише на етапі завантаження даних у грі. На етапі управління, коли гра працює, ви не можете прочитати ці дані; натомість ви читаєте оброблені значення через API з різних типів, таких як LuaEntityPrototype.

Окрім визначення прототипу елемента, ми також визначаємо його рецепт. Це необхідно, якщо ви хочете вміти зробити річ. Ми також встановлюємо його як увімкнене, для розблокування не потрібна технологія.

На даний момент мод виглядає [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 приблизно так].

=== Більше data.raw ===

Коли Factorio ініціалізується, всі прототипи поміщаються в таблицю під назвою data.raw. Ця таблиця містить усі типи, а в межах цих типів - окремі сутності. Ви раніше бачили, як ми скопіювали(deepcopied) визначення важкої броні та змінили деякі поля. Насправді переглянемо кожну лінію коду:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

Ми призначаємо змінну(variable) під назвою fireArmor, яка містить нашу копію визначення важкої броні. Зауважте як у data.raw знаходиться таблиця типів, яка містить усі визначення броні, а конкретна броня, яку ми шукаємо, називається важкою бронею. Наприклад, прототипом гравця буде:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Оскільки прототипом гравця(в лапках) є гравець, той тип відповідає його імені. Ви можете визначити новий тип гравця за допомогою модифікації. Ви можете побачити всі прототипи поля для сутності в її довгій декларації в програмі Factorio, за адресою /data/base/prototypes.

Ви, можливо, думаєте в цей момент: "Чи можу я змінити існуючі прототипи Factorio без створення нових?" Ну, відповідь - так! Ви просто отримаєте доступ до таблиці data.raw під час ініціадізації, у data-final-fixes.lua та зміните властивість. Наприклад, встановіть залізній скрині 1000 здоров'я:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

Причина, по якій цей код повинен бути у data-final-fixes.lua або data-updates.lua, полягає в тому, що це останній запуск файлу після запуску всіх файлів мод. Це запобігає (певною мірою) вашим змінам не змішуватись іншими модами. Звичайно, все-таки можливі несумісності. Ви повинні зазначити все, що вам відомо в описі вашого мода. Слід переглянути [http://lua-api.factorio.com/latest/Data-Lifecycle.html документацію розробника] про дані для більшої зрозумілості та точності.

Це також може бути застосоване до інших мод, а не лише до бази Факторио. Ви не можете модифікувати мод до тих пір, поки ви не додасте мод (який ви змінили своїм модом) до залежностей, щоб він завантажився першим.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T17:34:14Z

Ucrij fender: /* Prototype creation */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Контроль ===

У більшості модифікацій є файл, який називається <code>control.lua</code>. Цей файл містить сценарії, які змушують мод робити речі під час гри, а не просто додавати суб'єкти до гри. Під час цього етапу запускається control.lua кожного мода, в його власномій інстанції lua (це означає відсутність взаємозв'язку без спеціальних налаштувань), яким він буде володіти на протязі решти сеансу відтворення. Оскільки це запускається щоразу, коли файл збереження створюється або завантажується, вам не потрібно перезапускати гру, щоб побачити зміни, внесені до файлу control.lua. Просто перезапуск або перезавантаження збереження повторно запустить цей етап. '''На цьому етапі є кілька інших застережень. Ознайомитися з ними можна на сторінці [http://lua-api.factorio.com/latest/Data-Lifecycle.html життєвих циклів даних] на веб-сайті API.'''

=== Час виконання(Runtime) ===

На цьому етапі мод встановлюється, і збереження працює. Доступ до всіх таблиць, що надаються в грі, можна зробити всередині обробників подій. (Більше про те, що нижче).

== Основні компоненти будь-якої модифікації Factorio ==

В більшості випадків модифікації мають декілька компонентів, які змушують функціонувати мод.

Модам, що визначають нові сутності, потрібно буде оголосити ці сутності в <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code> , або інший файл необхідний одному з цих трьох.

Модам з ігровими ефектами також знадобиться файл <code>control.lua</code>, щоб додати сценарій.

Моди з налаштованими налаштуваннями користувача будуть використовувати <code>ettings.lua</code> для опису цих параметрів.

Моди, що визначають будь-який ігровий елемент з читабельним іменем, також можуть містити каталог <code>locale</code> та підкаталоги з іменами/описами на одній або кількох мовах.

Мод, який ми будемо робити в цьому підручнику, буде включати в себе як прототипи data.lua, так і сценарії control.lua, щоб ви змогли ознайомитися з обома.

З часом спільнота визначилася з деякими умовами щодо того, як повинна виглядати структура каталогів модів. Дотримуватися їх до точно не потрібно, але слідуючи стандартам, можна покращити читабельність скриптів та полегшити обговорення помилок модів. Детальніше про структуру каталогів нижче.

== Туторіал ==
А тепер мить на яку ви чекали. Тож почнемо робити свій перший мод. Вам знадобиться:

* Власне сама Factorio
* Текстовий редактор або пре-процесор
* Розуміння написаного вище
* Розуміння Lua як мови програмування. Досить знати синтаксис і як він працює. Якщо у вас є попередній досвід програмування, працювати з ним не мусить бути складним.

Після того, як у вас з’явиться все це, ми можемо почати.

Для цього мода ми зробимо набір броні, який залишає вогонь позаду вас під час прогулянки. Броня буде повністю стійка до вогню, але слабша до фізичного пошкодження, ніж важка болня, зробивши її бронею для тактики "стріляй та біжи"(run&gun).

=== Створення структури каталогів ===

Як було згадано раніше, існує загальний неофіційний стандарт того, як робиться структура модифікації. Це в поєднанні зі [[Tutorial:Mod structure|стандартами самої гри]] трохи обмежує нас. Для початку створіть папку у папці [[Application directory|каталогу даних користувача]]/модів. Ця папка повинна мати конкретне ім'я, <code>FireArmor_0.1.0</code>. Закінчивши, каталог моди повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0

Потім всередині FireArmor_0.1.0 створіть два файли, <code>info.json</code> та <code>data.lua</code>. Тепер каталог повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== info.json ===

Потім всередині info.json скопіюйте та вставте в нього:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

Для пояснень:

{| class="wikitable"
! Об'єкт
! Пояснення
|-
| name
| Внутрішнє ім'я модифікації, воно використовується для ідентифікації вашого мода в коді.
|-
| version
| Версія модифікації. Це може бути все, що завгодно, за умови, що це числа розділені точками. Деякі моди починаються з 0.0.1 або 0.1.0, а інші слідують за версіями Factorio і починаються з 0.17.0 (для версії Factorio 0.17.x)
|-
| title
| Примітна назва вашого мода, це відображатиметься на екрані управління модифікаціями та під час надсилання його на портал модів.
|-
| author
| Назвисько(nickname) або ім'я.
|-
| contact
| Контактна інформація, щоб хтось міг знайти вас у разі проблеми.
|-
| homepage
| Ваш власний веб-сайт свого мода. Не вимагається.
|-
| factorio_version
| Версія гри для якої призначений мод, вона повинна відповідати версії, для якої ви розробляєте мод, 0.17 в цьому випадку.
|-
| dependencies
| Будь-які залежності вашого мода. "base" завжди мусить бути тут, тому база спочатку завантажується.
|-
| description
| ''Короткий'' опис модифікації
|}

І це все, щодо info.json! Наступний файл - це data.lua:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

Це досить простий файл, все, що ми робимо тут, - це лише змушуємо гру виконати файл під назвою item.lua в прототипах, який ми збираємося створити. Створіть у FireArmor_0.1.0 папку під назвою <code>prototypes</code>, потім всередині прототипів створіть файл під назвою <code>item.lua</code>. Ваш каталог мод тепер повинен [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 виглядати так]:
* (каталог користувача)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json
*** prototypes
**** item.lua

Зверніть увагу на зазначення каталогів та файлів.

=== Створення прототипу ===

Зараз у Factorio є два способи створення прототипів: короткий і довгий шлях. Довгий шлях вимагає копіювання існуючого визначення з одного з файлів lua за замовчуванням, забезпечених установкою Factorio, а короткий шлях просто використовує функцію lua для копіювання та зміни визначення. В цьому посыбнику ми зробимо це коротким шляхом.
В item.lua, зкопіюйте:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

Ми скопіювали визначення важкої броні, потім змінили її властивості та ввели її в ініціалізацію Factorio з data:extend. Перший рядок коду, мабуть, найцікавіший. <code>table.deepcopy</code> повністю копіює таблицю в іншу з data.raw. <code>data</code> - це таблиця, яка буде використовуватися грою для налаштування всесвіту Factorio. Насправді він містить функцію <code>extend(self,prototypes)</code> та таблицю, яку називають <code>raw</code>. Перший - звичний спосіб додавання нових речей до другого. Фактично в data.raw описані усі прототипи для гри. (Ви можете переглянути реалізацію у файлі [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). Важливо зазначити, що data.raw існує лише на етапі завантаження даних у грі. На етапі управління, коли гра працює, ви не можете прочитати ці дані; натомість ви читаєте оброблені значення через API з різних типів, таких як LuaEntityPrototype.

Окрім визначення прототипу елемента, ми також визначаємо його рецепт. Це необхідно, якщо ви хочете вміти зробити річ. Ми також встановлюємо його як увімкнене, для розблокування не потрібна технологія.

На даний момент мод виглядає [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 приблизно так].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T17:09:45Z

Ucrij fender: /* info.json */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Контроль ===

У більшості модифікацій є файл, який називається <code>control.lua</code>. Цей файл містить сценарії, які змушують мод робити речі під час гри, а не просто додавати суб'єкти до гри. Під час цього етапу запускається control.lua кожного мода, в його власномій інстанції lua (це означає відсутність взаємозв'язку без спеціальних налаштувань), яким він буде володіти на протязі решти сеансу відтворення. Оскільки це запускається щоразу, коли файл збереження створюється або завантажується, вам не потрібно перезапускати гру, щоб побачити зміни, внесені до файлу control.lua. Просто перезапуск або перезавантаження збереження повторно запустить цей етап. '''На цьому етапі є кілька інших застережень. Ознайомитися з ними можна на сторінці [http://lua-api.factorio.com/latest/Data-Lifecycle.html життєвих циклів даних] на веб-сайті API.'''

=== Час виконання(Runtime) ===

На цьому етапі мод встановлюється, і збереження працює. Доступ до всіх таблиць, що надаються в грі, можна зробити всередині обробників подій. (Більше про те, що нижче).

== Основні компоненти будь-якої модифікації Factorio ==

В більшості випадків модифікації мають декілька компонентів, які змушують функціонувати мод.

Модам, що визначають нові сутності, потрібно буде оголосити ці сутності в <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code> , або інший файл необхідний одному з цих трьох.

Модам з ігровими ефектами також знадобиться файл <code>control.lua</code>, щоб додати сценарій.

Моди з налаштованими налаштуваннями користувача будуть використовувати <code>ettings.lua</code> для опису цих параметрів.

Моди, що визначають будь-який ігровий елемент з читабельним іменем, також можуть містити каталог <code>locale</code> та підкаталоги з іменами/описами на одній або кількох мовах.

Мод, який ми будемо робити в цьому підручнику, буде включати в себе як прототипи data.lua, так і сценарії control.lua, щоб ви змогли ознайомитися з обома.

З часом спільнота визначилася з деякими умовами щодо того, як повинна виглядати структура каталогів модів. Дотримуватися їх до точно не потрібно, але слідуючи стандартам, можна покращити читабельність скриптів та полегшити обговорення помилок модів. Детальніше про структуру каталогів нижче.

== Туторіал ==
А тепер мить на яку ви чекали. Тож почнемо робити свій перший мод. Вам знадобиться:

* Власне сама Factorio
* Текстовий редактор або пре-процесор
* Розуміння написаного вище
* Розуміння Lua як мови програмування. Досить знати синтаксис і як він працює. Якщо у вас є попередній досвід програмування, працювати з ним не мусить бути складним.

Після того, як у вас з’явиться все це, ми можемо почати.

Для цього мода ми зробимо набір броні, який залишає вогонь позаду вас під час прогулянки. Броня буде повністю стійка до вогню, але слабша до фізичного пошкодження, ніж важка болня, зробивши її бронею для тактики "стріляй та біжи"(run&gun).

=== Створення структури каталогів ===

Як було згадано раніше, існує загальний неофіційний стандарт того, як робиться структура модифікації. Це в поєднанні зі [[Tutorial:Mod structure|стандартами самої гри]] трохи обмежує нас. Для початку створіть папку у папці [[Application directory|каталогу даних користувача]]/модів. Ця папка повинна мати конкретне ім'я, <code>FireArmor_0.1.0</code>. Закінчивши, каталог моди повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0

Потім всередині FireArmor_0.1.0 створіть два файли, <code>info.json</code> та <code>data.lua</code>. Тепер каталог повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== info.json ===

Потім всередині info.json скопіюйте та вставте в нього:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

Для пояснень:

{| class="wikitable"
! Об'єкт
! Пояснення
|-
| name
| Внутрішнє ім'я модифікації, воно використовується для ідентифікації вашого мода в коді.
|-
| version
| Версія модифікації. Це може бути все, що завгодно, за умови, що це числа розділені точками. Деякі моди починаються з 0.0.1 або 0.1.0, а інші слідують за версіями Factorio і починаються з 0.17.0 (для версії Factorio 0.17.x)
|-
| title
| Примітна назва вашого мода, це відображатиметься на екрані управління модифікаціями та під час надсилання його на портал модів.
|-
| author
| Назвисько(nickname) або ім'я.
|-
| contact
| Контактна інформація, щоб хтось міг знайти вас у разі проблеми.
|-
| homepage
| Ваш власний веб-сайт свого мода. Не вимагається.
|-
| factorio_version
| Версія гри для якої призначений мод, вона повинна відповідати версії, для якої ви розробляєте мод, 0.17 в цьому випадку.
|-
| dependencies
| Будь-які залежності вашого мода. "base" завжди мусить бути тут, тому база спочатку завантажується.
|-
| description
| ''Короткий'' опис модифікації
|}

І це все, щодо info.json! Наступний файл - це data.lua:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

Це досить простий файл, все, що ми робимо тут, - це лише змушуємо гру виконати файл під назвою item.lua в прототипах, який ми збираємося створити. Створіть у FireArmor_0.1.0 папку під назвою <code>prototypes</code>, потім всередині прототипів створіть файл під назвою <code>item.lua</code>. Ваш каталог мод тепер повинен [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 виглядати так]:
* (каталог користувача)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json
*** prototypes
**** item.lua

Зверніть увагу на зазначення каталогів та файлів.

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T17:08:59Z

Ucrij fender: /* Туторіал */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Контроль ===

У більшості модифікацій є файл, який називається <code>control.lua</code>. Цей файл містить сценарії, які змушують мод робити речі під час гри, а не просто додавати суб'єкти до гри. Під час цього етапу запускається control.lua кожного мода, в його власномій інстанції lua (це означає відсутність взаємозв'язку без спеціальних налаштувань), яким він буде володіти на протязі решти сеансу відтворення. Оскільки це запускається щоразу, коли файл збереження створюється або завантажується, вам не потрібно перезапускати гру, щоб побачити зміни, внесені до файлу control.lua. Просто перезапуск або перезавантаження збереження повторно запустить цей етап. '''На цьому етапі є кілька інших застережень. Ознайомитися з ними можна на сторінці [http://lua-api.factorio.com/latest/Data-Lifecycle.html життєвих циклів даних] на веб-сайті API.'''

=== Час виконання(Runtime) ===

На цьому етапі мод встановлюється, і збереження працює. Доступ до всіх таблиць, що надаються в грі, можна зробити всередині обробників подій. (Більше про те, що нижче).

== Основні компоненти будь-якої модифікації Factorio ==

В більшості випадків модифікації мають декілька компонентів, які змушують функціонувати мод.

Модам, що визначають нові сутності, потрібно буде оголосити ці сутності в <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code> , або інший файл необхідний одному з цих трьох.

Модам з ігровими ефектами також знадобиться файл <code>control.lua</code>, щоб додати сценарій.

Моди з налаштованими налаштуваннями користувача будуть використовувати <code>ettings.lua</code> для опису цих параметрів.

Моди, що визначають будь-який ігровий елемент з читабельним іменем, також можуть містити каталог <code>locale</code> та підкаталоги з іменами/описами на одній або кількох мовах.

Мод, який ми будемо робити в цьому підручнику, буде включати в себе як прототипи data.lua, так і сценарії control.lua, щоб ви змогли ознайомитися з обома.

З часом спільнота визначилася з деякими умовами щодо того, як повинна виглядати структура каталогів модів. Дотримуватися їх до точно не потрібно, але слідуючи стандартам, можна покращити читабельність скриптів та полегшити обговорення помилок модів. Детальніше про структуру каталогів нижче.

== Туторіал ==
А тепер мить на яку ви чекали. Тож почнемо робити свій перший мод. Вам знадобиться:

* Власне сама Factorio
* Текстовий редактор або пре-процесор
* Розуміння написаного вище
* Розуміння Lua як мови програмування. Досить знати синтаксис і як він працює. Якщо у вас є попередній досвід програмування, працювати з ним не мусить бути складним.

Після того, як у вас з’явиться все це, ми можемо почати.

Для цього мода ми зробимо набір броні, який залишає вогонь позаду вас під час прогулянки. Броня буде повністю стійка до вогню, але слабша до фізичного пошкодження, ніж важка болня, зробивши її бронею для тактики "стріляй та біжи"(run&gun).

=== Створення структури каталогів ===

Як було згадано раніше, існує загальний неофіційний стандарт того, як робиться структура модифікації. Це в поєднанні зі [[Tutorial:Mod structure|стандартами самої гри]] трохи обмежує нас. Для початку створіть папку у папці [[Application directory|каталогу даних користувача]]/модів. Ця папка повинна мати конкретне ім'я, <code>FireArmor_0.1.0</code>. Закінчивши, каталог моди повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0

Потім всередині FireArmor_0.1.0 створіть два файли, <code>info.json</code> та <code>data.lua</code>. Тепер каталог повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== info.json ===

Потім всередині info.json скопіюйте та вставте в нього:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

Для пояснень:

{| class="wikitable"
! Об'єкт
! Пояснення
|-
| name
| Внутрішнє ім'я модифікації, воно використовується для ідентифікації вашого мода в коді.
|-
| version
| Версія модифікації. Це може бути все, що завгодно, за умови, що це числа розділені точками. Деякі моди починаються з 0.0.1 або 0.1.0, а інші слідують за версіями Factorio і починаються з 0.17.0 (для версії Factorio 0.17.x)
|-
| title
| Примітна назва вашого мода, це відображатиметься на екрані управління модифікаціями та під час надсилання його на портал модів.
|-
| author
| Назвисько(nickname) або ім'я.
|-
| contact
| Контактна інформація, щоб хтось міг знайти вас у разі проблеми.
|-
| homepage
| Ваш власний веб-сайт свого мода. Не вимагається.
|-
| factorio_version
| Версія гри для якої призначений мод, вона повинна відповідати версії, для якої ви розробляєте мод, 0.17 в цьому випадку.
|-
| dependencies
| Будь-які залежності вашого мода. "base" завжди мусить бути тут, тому база спочатку завантажується.
|-
| description
| ''Короткий'' опис модифікації
|}

І це все, щодо info.json! Наступний файл - це data.lua:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

Це досить простий файл, все, що ми робимо тут, - це лише змушуємо гру виконати файл під назвою item.lua в прототипах, який ми збираємося створити. Створіть у FireArmor_0.1.0 папку під назвою <code>prototypes</code>, потім всередині прототипів створіть файл під назвою <code>item.lua</code>. Ваш каталог мод тепер повинен[https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 виглядати так]:
* (каталог користувача)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json
*** prototypes
**** item.lua

Зверніть увагу на зазначення каталогів та файлів.

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T17:06:44Z

Ucrij fender:

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Контроль ===

У більшості модифікацій є файл, який називається <code>control.lua</code>. Цей файл містить сценарії, які змушують мод робити речі під час гри, а не просто додавати суб'єкти до гри. Під час цього етапу запускається control.lua кожного мода, в його власномій інстанції lua (це означає відсутність взаємозв'язку без спеціальних налаштувань), яким він буде володіти на протязі решти сеансу відтворення. Оскільки це запускається щоразу, коли файл збереження створюється або завантажується, вам не потрібно перезапускати гру, щоб побачити зміни, внесені до файлу control.lua. Просто перезапуск або перезавантаження збереження повторно запустить цей етап. '''На цьому етапі є кілька інших застережень. Ознайомитися з ними можна на сторінці [http://lua-api.factorio.com/latest/Data-Lifecycle.html життєвих циклів даних] на веб-сайті API.'''

=== Час виконання(Runtime) ===

На цьому етапі мод встановлюється, і збереження працює. Доступ до всіх таблиць, що надаються в грі, можна зробити всередині обробників подій. (Більше про те, що нижче).

== Основні компоненти будь-якої модифікації Factorio ==

В більшості випадків модифікації мають декілька компонентів, які змушують функціонувати мод.

Модам, що визначають нові сутності, потрібно буде оголосити ці сутності в <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code> , або інший файл необхідний одному з цих трьох.

Модам з ігровими ефектами також знадобиться файл <code>control.lua</code>, щоб додати сценарій.

Моди з налаштованими налаштуваннями користувача будуть використовувати <code>ettings.lua</code> для опису цих параметрів.

Моди, що визначають будь-який ігровий елемент з читабельним іменем, також можуть містити каталог <code>locale</code> та підкаталоги з іменами/описами на одній або кількох мовах.

Мод, який ми будемо робити в цьому підручнику, буде включати в себе як прототипи data.lua, так і сценарії control.lua, щоб ви змогли ознайомитися з обома.

З часом спільнота визначилася з деякими умовами щодо того, як повинна виглядати структура каталогів модів. Дотримуватися їх до точно не потрібно, але слідуючи стандартам, можна покращити читабельність скриптів та полегшити обговорення помилок модів. Детальніше про структуру каталогів нижче.

== Туторіал ==
А тепер мить на яку ви чекали. Тож почнемо робити свій перший мод. Вам знадобиться:

* Власне сама Factorio
* Текстовий редактор або пре-процесор
* Розуміння написаного вище
* Розуміння Lua як мови програмування. Досить знати синтаксис і як він працює. Якщо у вас є попередній досвід програмування, працювати з ним не мусить бути складним.

Після того, як у вас з’явиться все це, ми можемо почати.

Для цього мода ми зробимо набір броні, який залишає вогонь позаду вас під час прогулянки. Броня буде повністю стійка до вогню, але слабша до фізичного пошкодження, ніж важка болня, зробивши її бронею для тактики "стріляй та біжи"(run&gun).

=== Створення структури каталогів ===

Як було згадано раніше, існує загальний неофіційний стандарт того, як робиться структура модифікації. Це в поєднанні зі [[Tutorial:Mod structure|стандартами самої гри]] трохи обмежує нас. Для початку створіть папку у папці [[Application directory|каталогу даних користувача]]/модів. Ця папка повинна мати конкретне ім'я, <code>FireArmor_0.1.0</code>. Закінчивши, каталог моди повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0

Потім всередині FireArmor_0.1.0 створіть два файли, <code>info.json</code> та <code>data.lua</code>. Тепер каталог повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== info.json ===

Потім всередині info.json скопіюйте та вставте в нього:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

Для пояснень:

{| class="wikitable"
! Об'єкт
! Пояснення
|-
| name
| Внутрішнє ім'я модифікації, воно використовується для ідентифікації вашого мода в коді.
|-
| version
| Версія модифікації. Це може бути все, що завгодно, за умови, що це числа розділені точками. Деякі моди починаються з 0.0.1 або 0.1.0, а інші слідують за версіями Factorio і починаються з 0.17.0 (для версії Factorio 0.17.x)
|-
| title
| Примітна назва вашого мода, це відображатиметься на екрані управління модифікаціями та під час надсилання його на портал модів.
|-
| author
| Назвисько(nickname) або ім'я.
|-
| contact
| Контактна інформація, щоб хтось міг знайти вас у разі проблеми.
|-
| homepage
| Ваш власний веб-сайт свого мода. Не вимагається.
|-
| factorio_version
| Версія гри для якої призначений мод, вона повинна відповідати версії, для якої ви розробляєте мод, 0.17 в цьому випадку.
|-
| dependencies
| Будь-які залежності вашого мода. "base" завжди мусить бути тут, тому база спочатку завантажується.
|-
| description
| ''Короткий'' опис модифікації
|}

І це все, щодо info.json! Наступний файл - це data.lua:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

Це досить простий файл, все, що ми робимо тут, - це лише змушуємо гру виконати файл під назвою item.lua в прототипах, який ми збираємося створити. Створіть у FireArmor_0.1.0 папку під назвою <code>prototypes</code>, потім всередині прототипів створіть файл під назвою <code>item.lua</code>. Ваш каталог мод тепер повинен відповідати [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 цим знімкам github].

Зверніть увагу на зазначення каталогів та файлів.

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T16:49:55Z

Ucrij fender: /* The info.json file */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Контроль ===

У більшості модифікацій є файл, який називається <code>control.lua</code>. Цей файл містить сценарії, які змушують мод робити речі під час гри, а не просто додавати суб'єкти до гри. Під час цього етапу запускається control.lua кожного мода, в його власномій інстанції lua (це означає відсутність взаємозв'язку без спеціальних налаштувань), яким він буде володіти на протязі решти сеансу відтворення. Оскільки це запускається щоразу, коли файл збереження створюється або завантажується, вам не потрібно перезапускати гру, щоб побачити зміни, внесені до файлу control.lua. Просто перезапуск або перезавантаження збереження повторно запустить цей етап. '''На цьому етапі є кілька інших застережень. Ознайомитися з ними можна на сторінці [http://lua-api.factorio.com/latest/Data-Lifecycle.html життєвих циклів даних] на веб-сайті API.'''

=== Час виконання(Runtime) ===

На цьому етапі мод встановлюється, і збереження працює. Доступ до всіх таблиць, що надаються в грі, можна зробити всередині обробників подій. (Більше про те, що нижче).

== Основні компоненти будь-якої модифікації Factorio ==

В більшості випадків модифікації мають декілька компонентів, які змушують функціонувати мод.

Модам, що визначають нові сутності, потрібно буде оголосити ці сутності в <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code> , або інший файл необхідний одному з цих трьох.

Модам з ігровими ефектами також знадобиться файл <code>control.lua</code>, щоб додати сценарій.

Моди з налаштованими налаштуваннями користувача будуть використовувати <code>ettings.lua</code> для опису цих параметрів.

Моди, що визначають будь-який ігровий елемент з читабельним іменем, також можуть містити каталог <code>locale</code> та підкаталоги з іменами/описами на одній або кількох мовах.

Мод, який ми будемо робити в цьому підручнику, буде включати в себе як прототипи data.lua, так і сценарії control.lua, щоб ви змогли ознайомитися з обома.

З часом спільнота визначилася з деякими умовами щодо того, як повинна виглядати структура каталогів модів. Дотримуватися їх до точно не потрібно, але слідуючи стандартам, можна покращити читабельність скриптів та полегшити обговорення помилок модів. Детальніше про структуру каталогів нижче.

== Туторіал ==
А тепер мить на яку ви чекали. Тож почнемо робити свій перший мод. Вам знадобиться:

* Власне сама Factorio
* Текстовий редактор або пре-процесор
* Розуміння написаного вище
* Розуміння Lua як мови програмування. Досить знати синтаксис і як він працює. Якщо у вас є попередній досвід програмування, працювати з ним не мусить бути складним.

Після того, як у вас з’явиться все це, ми можемо почати.

Для цього мода ми зробимо набір броні, який залишає вогонь позаду вас під час прогулянки. Броня буде повністю стійка до вогню, але слабша до фізичного пошкодження, ніж важка болня, зробивши її бронею для тактики "стріляй та біжи"(run&gun).

=== Створення структури каталогів ===

Як було згадано раніше, існує загальний неофіційний стандарт того, як робиться структура модифікації. Це в поєднанні зі [[Tutorial:Mod structure|стандартами самої гри]] трохи обмежує нас. Для початку створіть папку у папці [[Application directory|каталогу даних користувача]]/модів. Ця папка повинна мати конкретне ім'я, <code>FireArmor_0.1.0</code>. Закінчивши, каталог моди повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0

Потім всередині FireArmor_0.1.0 створіть два файли, <code>info.json</code> та <code>data.lua</code>. Тепер каталог повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== info.json ===

Потім всередині info.json скопіюйте та вставте в нього:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

Для пояснень:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a number. Some mods start at 0.0.1 or 0.1.0, while others follow Factorio versions and start at 0.17.0 (for Factorio version 0.17.x)
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| contact
| Put contact info here, so someone can find you in the event of a problem.
|-
| homepage
| The homepage of your mod, put a website here if you have one for the mod. Not required.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 0.17 in this case.
|-
| dependencies
| Any dependencies of your mod. Some form of "base" should always be here, so base gets loaded first.
|-
| description
| A ''short'' description of your mod.
|}

And that's all for info.json! Next, in the data.lua file:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

It's a pretty simple file, all we're doing here is just telling the game to execute the file called item.lua in prototypes, which we're about to create. Create a folder in FireArmor_0.1.0 called <code>prototypes</code>, then inside prototypes, create a file called <code>item.lua</code>. Your mod directory should now match [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 this github snapshot].

Notice how our earlier require used the folder and file name in it?

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T16:48:52Z

Ucrij fender: /* Creation of the directory structure */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Контроль ===

У більшості модифікацій є файл, який називається <code>control.lua</code>. Цей файл містить сценарії, які змушують мод робити речі під час гри, а не просто додавати суб'єкти до гри. Під час цього етапу запускається control.lua кожного мода, в його власномій інстанції lua (це означає відсутність взаємозв'язку без спеціальних налаштувань), яким він буде володіти на протязі решти сеансу відтворення. Оскільки це запускається щоразу, коли файл збереження створюється або завантажується, вам не потрібно перезапускати гру, щоб побачити зміни, внесені до файлу control.lua. Просто перезапуск або перезавантаження збереження повторно запустить цей етап. '''На цьому етапі є кілька інших застережень. Ознайомитися з ними можна на сторінці [http://lua-api.factorio.com/latest/Data-Lifecycle.html життєвих циклів даних] на веб-сайті API.'''

=== Час виконання(Runtime) ===

На цьому етапі мод встановлюється, і збереження працює. Доступ до всіх таблиць, що надаються в грі, можна зробити всередині обробників подій. (Більше про те, що нижче).

== Основні компоненти будь-якої модифікації Factorio ==

В більшості випадків модифікації мають декілька компонентів, які змушують функціонувати мод.

Модам, що визначають нові сутності, потрібно буде оголосити ці сутності в <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code> , або інший файл необхідний одному з цих трьох.

Модам з ігровими ефектами також знадобиться файл <code>control.lua</code>, щоб додати сценарій.

Моди з налаштованими налаштуваннями користувача будуть використовувати <code>ettings.lua</code> для опису цих параметрів.

Моди, що визначають будь-який ігровий елемент з читабельним іменем, також можуть містити каталог <code>locale</code> та підкаталоги з іменами/описами на одній або кількох мовах.

Мод, який ми будемо робити в цьому підручнику, буде включати в себе як прототипи data.lua, так і сценарії control.lua, щоб ви змогли ознайомитися з обома.

З часом спільнота визначилася з деякими умовами щодо того, як повинна виглядати структура каталогів модів. Дотримуватися їх до точно не потрібно, але слідуючи стандартам, можна покращити читабельність скриптів та полегшити обговорення помилок модів. Детальніше про структуру каталогів нижче.

== Туторіал ==
А тепер мить на яку ви чекали. Тож почнемо робити свій перший мод. Вам знадобиться:

* Власне сама Factorio
* Текстовий редактор або пре-процесор
* Розуміння написаного вище
* Розуміння Lua як мови програмування. Досить знати синтаксис і як він працює. Якщо у вас є попередній досвід програмування, працювати з ним не мусить бути складним.

Після того, як у вас з’явиться все це, ми можемо почати.

Для цього мода ми зробимо набір броні, який залишає вогонь позаду вас під час прогулянки. Броня буде повністю стійка до вогню, але слабша до фізичного пошкодження, ніж важка болня, зробивши її бронею для тактики "стріляй та біжи"(run&gun).

=== Створення структури каталогів ===

Як було згадано раніше, існує загальний неофіційний стандарт того, як робиться структура модифікації. Це в поєднанні зі [[Tutorial:Mod structure|стандартами самої гри]] трохи обмежує нас. Для початку створіть папку у папці [[Application directory|каталогу даних користувача]]/модів. Ця папка повинна мати конкретне ім'я, <code>FireArmor_0.1.0</code>. Закінчивши, каталог моди повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0

Потім всередині FireArmor_0.1.0 створіть два файли, <code>info.json</code> та <code>data.lua</code>. Тепер каталог повинен виглядати так:

* (каталог користувача, наприклад .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== The info.json file ===

Then, inside info.json, copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a number. Some mods start at 0.0.1 or 0.1.0, while others follow Factorio versions and start at 0.17.0 (for Factorio version 0.17.x)
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| contact
| Put contact info here, so someone can find you in the event of a problem.
|-
| homepage
| The homepage of your mod, put a website here if you have one for the mod. Not required.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 0.17 in this case.
|-
| dependencies
| Any dependencies of your mod. Some form of "base" should always be here, so base gets loaded first.
|-
| description
| A ''short'' description of your mod.
|}

And that's all for info.json! Next, in the data.lua file:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

It's a pretty simple file, all we're doing here is just telling the game to execute the file called item.lua in prototypes, which we're about to create. Create a folder in FireArmor_0.1.0 called <code>prototypes</code>, then inside prototypes, create a file called <code>item.lua</code>. Your mod directory should now match [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 this github snapshot].

Notice how our earlier require used the folder and file name in it?

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T16:39:55Z

Ucrij fender: /* The tutorial mod */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Контроль ===

У більшості модифікацій є файл, який називається <code>control.lua</code>. Цей файл містить сценарії, які змушують мод робити речі під час гри, а не просто додавати суб'єкти до гри. Під час цього етапу запускається control.lua кожного мода, в його власномій інстанції lua (це означає відсутність взаємозв'язку без спеціальних налаштувань), яким він буде володіти на протязі решти сеансу відтворення. Оскільки це запускається щоразу, коли файл збереження створюється або завантажується, вам не потрібно перезапускати гру, щоб побачити зміни, внесені до файлу control.lua. Просто перезапуск або перезавантаження збереження повторно запустить цей етап. '''На цьому етапі є кілька інших застережень. Ознайомитися з ними можна на сторінці [http://lua-api.factorio.com/latest/Data-Lifecycle.html життєвих циклів даних] на веб-сайті API.'''

=== Час виконання(Runtime) ===

На цьому етапі мод встановлюється, і збереження працює. Доступ до всіх таблиць, що надаються в грі, можна зробити всередині обробників подій. (Більше про те, що нижче).

== Основні компоненти будь-якої модифікації Factorio ==

В більшості випадків модифікації мають декілька компонентів, які змушують функціонувати мод.

Модам, що визначають нові сутності, потрібно буде оголосити ці сутності в <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code> , або інший файл необхідний одному з цих трьох.

Модам з ігровими ефектами також знадобиться файл <code>control.lua</code>, щоб додати сценарій.

Моди з налаштованими налаштуваннями користувача будуть використовувати <code>ettings.lua</code> для опису цих параметрів.

Моди, що визначають будь-який ігровий елемент з читабельним іменем, також можуть містити каталог <code>locale</code> та підкаталоги з іменами/описами на одній або кількох мовах.

Мод, який ми будемо робити в цьому підручнику, буде включати в себе як прототипи data.lua, так і сценарії control.lua, щоб ви змогли ознайомитися з обома.

З часом спільнота визначилася з деякими умовами щодо того, як повинна виглядати структура каталогів модів. Дотримуватися їх до точно не потрібно, але слідуючи стандартам, можна покращити читабельність скриптів та полегшити обговорення помилок модів. Детальніше про структуру каталогів нижче.

== Туторіал ==
А тепер мить на яку ви чекали. Тож почнемо робити свій перший мод. Вам знадобиться:

* Власне сама Factorio
* Текстовий редактор або пре-процесор
* Розуміння написаного вище
* Розуміння Lua як мови програмування. Досить знати синтаксис і як він працює. Якщо у вас є попередній досвід програмування, працювати з ним не мусить бути складним.

Після того, як у вас з’явиться все це, ми можемо почати.

Для цього мода ми зробимо набір броні, який залишає вогонь позаду вас під час прогулянки. Броня буде повністю стійка до вогню, але слабша до фізичного пошкодження, ніж важка болня, зробивши її бронею для тактики "стріляй та біжи"(run&gun).

=== Creation of the directory structure ===

Like this tutorial mentioned earlier, there is a somewhat community standard around for how a mod is laid out. This, combined with [[Tutorial:Mod structure|how the game expects mods to be laid out]], limits us slightly. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>FireArmor_0.1.0</code>. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0

Then, inside FireArmor_0.1.0, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== The info.json file ===

Then, inside info.json, copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a number. Some mods start at 0.0.1 or 0.1.0, while others follow Factorio versions and start at 0.17.0 (for Factorio version 0.17.x)
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| contact
| Put contact info here, so someone can find you in the event of a problem.
|-
| homepage
| The homepage of your mod, put a website here if you have one for the mod. Not required.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 0.17 in this case.
|-
| dependencies
| Any dependencies of your mod. Some form of "base" should always be here, so base gets loaded first.
|-
| description
| A ''short'' description of your mod.
|}

And that's all for info.json! Next, in the data.lua file:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

It's a pretty simple file, all we're doing here is just telling the game to execute the file called item.lua in prototypes, which we're about to create. Create a folder in FireArmor_0.1.0 called <code>prototypes</code>, then inside prototypes, create a file called <code>item.lua</code>. Your mod directory should now match [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 this github snapshot].

Notice how our earlier require used the folder and file name in it?

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T11:12:22Z

Ucrij fender: /* The major components to any Factorio mod */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Контроль ===

У більшості модифікацій є файл, який називається <code>control.lua</code>. Цей файл містить сценарії, які змушують мод робити речі під час гри, а не просто додавати суб'єкти до гри. Під час цього етапу запускається control.lua кожного мода, в його власномій інстанції lua (це означає відсутність взаємозв'язку без спеціальних налаштувань), яким він буде володіти на протязі решти сеансу відтворення. Оскільки це запускається щоразу, коли файл збереження створюється або завантажується, вам не потрібно перезапускати гру, щоб побачити зміни, внесені до файлу control.lua. Просто перезапуск або перезавантаження збереження повторно запустить цей етап. '''На цьому етапі є кілька інших застережень. Ознайомитися з ними можна на сторінці [http://lua-api.factorio.com/latest/Data-Lifecycle.html життєвих циклів даних] на веб-сайті API.'''

=== Час виконання(Runtime) ===

На цьому етапі мод встановлюється, і збереження працює. Доступ до всіх таблиць, що надаються в грі, можна зробити всередині обробників подій. (Більше про те, що нижче).

== Основні компоненти будь-якої модифікації Factorio ==

В більшості випадків модифікації мають декілька компонентів, які змушують функціонувати мод.

Модам, що визначають нові сутності, потрібно буде оголосити ці сутності в <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code> , або інший файл необхідний одному з цих трьох.

Модам з ігровими ефектами також знадобиться файл <code>control.lua</code>, щоб додати сценарій.

Моди з налаштованими налаштуваннями користувача будуть використовувати <code>ettings.lua</code> для опису цих параметрів.

Моди, що визначають будь-який ігровий елемент з читабельним іменем, також можуть містити каталог <code>locale</code> та підкаталоги з іменами/описами на одній або кількох мовах.

Мод, який ми будемо робити в цьому підручнику, буде включати в себе як прототипи data.lua, так і сценарії control.lua, щоб ви змогли ознайомитися з обома.

З часом спільнота визначилася з деякими умовами щодо того, як повинна виглядати структура каталогів модів. Дотримуватися їх до точно не потрібно, але слідуючи стандартам, можна покращити читабельність скриптів та полегшити обговорення помилок модів. Детальніше про структуру каталогів нижче.

== The tutorial mod ==

And now for the moment you've been waiting for. Let's start making your first mod. You'll need:

* A recent install of Factorio
* A text editor, such as Emacs, Vim, Sublime text, etc
* An understanding of the tutorial above
* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.

Once you have all of these things, we can begin.

For this mod, we're going to make a set of armor that leaves behind damaging fire behind you as you walk. It will be fully resistant to fire, but weaker towards physical damage than heavy armor, making it an armor for hit and run attacks.

=== Creation of the directory structure ===

Like this tutorial mentioned earlier, there is a somewhat community standard around for how a mod is laid out. This, combined with [[Tutorial:Mod structure|how the game expects mods to be laid out]], limits us slightly. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>FireArmor_0.1.0</code>. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0

Then, inside FireArmor_0.1.0, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== The info.json file ===

Then, inside info.json, copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a number. Some mods start at 0.0.1 or 0.1.0, while others follow Factorio versions and start at 0.17.0 (for Factorio version 0.17.x)
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| contact
| Put contact info here, so someone can find you in the event of a problem.
|-
| homepage
| The homepage of your mod, put a website here if you have one for the mod. Not required.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 0.17 in this case.
|-
| dependencies
| Any dependencies of your mod. Some form of "base" should always be here, so base gets loaded first.
|-
| description
| A ''short'' description of your mod.
|}

And that's all for info.json! Next, in the data.lua file:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

It's a pretty simple file, all we're doing here is just telling the game to execute the file called item.lua in prototypes, which we're about to create. Create a folder in FireArmor_0.1.0 called <code>prototypes</code>, then inside prototypes, create a file called <code>item.lua</code>. Your mod directory should now match [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 this github snapshot].

Notice how our earlier require used the folder and file name in it?

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T10:54:32Z

Ucrij fender: /* Runtime */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Контроль ===

У більшості модифікацій є файл, який називається <code>control.lua</code>. Цей файл містить сценарії, які змушують мод робити речі під час гри, а не просто додавати суб'єкти до гри. Під час цього етапу запускається control.lua кожного мода, в його власномій інстанції lua (це означає відсутність взаємозв'язку без спеціальних налаштувань), яким він буде володіти на протязі решти сеансу відтворення. Оскільки це запускається щоразу, коли файл збереження створюється або завантажується, вам не потрібно перезапускати гру, щоб побачити зміни, внесені до файлу control.lua. Просто перезапуск або перезавантаження збереження повторно запустить цей етап. '''На цьому етапі є кілька інших застережень. Ознайомитися з ними можна на сторінці [http://lua-api.factorio.com/latest/Data-Lifecycle.html життєвих циклів даних] на веб-сайті API.'''

=== Час виконання(Runtime) ===

На цьому етапі мод встановлюється, і збереження працює. Доступ до всіх таблиць, що надаються в грі, можна зробити всередині обробників подій. (Більше про те, що нижче).

== The major components to any Factorio mod ==

Within the average mod, there are several components that make the mod function.

Mods that define new entities will need to declare these entities in <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code>, or another file <code>require</code>d by one of these three.

Mods with in-game effects will also need a <code>control.lua</code> file, to add scripting.

Mods with configurable user settings will use <code>settings.lua</code> to describe those settings.

Mods that define any game element with a readable name may also provide a <code>locale</code> directory and subdirectories with names/descriptions in one or more languages.

The mod that we'll make in this tutorial will include both data.lua prototypes and control.lua scripting, to give you a feel for both.

Over time, the community has settled on some conventions for how a mod's directory structure should look. Following these to a T is not necessary, but can simplify things and make discussing mod bugs and improvements with other developers easier. More on directory structure below.

== The tutorial mod ==

And now for the moment you've been waiting for. Let's start making your first mod. You'll need:

* A recent install of Factorio
* A text editor, such as Emacs, Vim, Sublime text, etc
* An understanding of the tutorial above
* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.

Once you have all of these things, we can begin.

For this mod, we're going to make a set of armor that leaves behind damaging fire behind you as you walk. It will be fully resistant to fire, but weaker towards physical damage than heavy armor, making it an armor for hit and run attacks.

=== Creation of the directory structure ===

Like this tutorial mentioned earlier, there is a somewhat community standard around for how a mod is laid out. This, combined with [[Tutorial:Mod structure|how the game expects mods to be laid out]], limits us slightly. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>FireArmor_0.1.0</code>. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0

Then, inside FireArmor_0.1.0, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== The info.json file ===

Then, inside info.json, copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a number. Some mods start at 0.0.1 or 0.1.0, while others follow Factorio versions and start at 0.17.0 (for Factorio version 0.17.x)
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| contact
| Put contact info here, so someone can find you in the event of a problem.
|-
| homepage
| The homepage of your mod, put a website here if you have one for the mod. Not required.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 0.17 in this case.
|-
| dependencies
| Any dependencies of your mod. Some form of "base" should always be here, so base gets loaded first.
|-
| description
| A ''short'' description of your mod.
|}

And that's all for info.json! Next, in the data.lua file:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

It's a pretty simple file, all we're doing here is just telling the game to execute the file called item.lua in prototypes, which we're about to create. Create a folder in FireArmor_0.1.0 called <code>prototypes</code>, then inside prototypes, create a file called <code>item.lua</code>. Your mod directory should now match [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 this github snapshot].

Notice how our earlier require used the folder and file name in it?

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T10:50:21Z

Ucrij fender: /* КонтрольControl */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Контроль ===

У більшості модифікацій є файл, який називається <code>control.lua</code>. Цей файл містить сценарії, які змушують мод робити речі під час гри, а не просто додавати суб'єкти до гри. Під час цього етапу запускається control.lua кожного мода, в його власномій інстанції lua (це означає відсутність взаємозв'язку без спеціальних налаштувань), яким він буде володіти на протязі решти сеансу відтворення. Оскільки це запускається щоразу, коли файл збереження створюється або завантажується, вам не потрібно перезапускати гру, щоб побачити зміни, внесені до файлу control.lua. Просто перезапуск або перезавантаження збереження повторно запустить цей етап. '''На цьому етапі є кілька інших застережень. Ознайомитися з ними можна на сторінці [http://lua-api.factorio.com/latest/Data-Lifecycle.html життєвих циклів даних] на веб-сайті API.'''

=== Runtime ===

At this stage, the mod is setup, and the save is running. Access to all tables provided by the game can be done inside of event handlers. (More on those below.)

== The major components to any Factorio mod ==

Within the average mod, there are several components that make the mod function.

Mods that define new entities will need to declare these entities in <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code>, or another file <code>require</code>d by one of these three.

Mods with in-game effects will also need a <code>control.lua</code> file, to add scripting.

Mods with configurable user settings will use <code>settings.lua</code> to describe those settings.

Mods that define any game element with a readable name may also provide a <code>locale</code> directory and subdirectories with names/descriptions in one or more languages.

The mod that we'll make in this tutorial will include both data.lua prototypes and control.lua scripting, to give you a feel for both.

Over time, the community has settled on some conventions for how a mod's directory structure should look. Following these to a T is not necessary, but can simplify things and make discussing mod bugs and improvements with other developers easier. More on directory structure below.

== The tutorial mod ==

And now for the moment you've been waiting for. Let's start making your first mod. You'll need:

* A recent install of Factorio
* A text editor, such as Emacs, Vim, Sublime text, etc
* An understanding of the tutorial above
* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.

Once you have all of these things, we can begin.

For this mod, we're going to make a set of armor that leaves behind damaging fire behind you as you walk. It will be fully resistant to fire, but weaker towards physical damage than heavy armor, making it an armor for hit and run attacks.

=== Creation of the directory structure ===

Like this tutorial mentioned earlier, there is a somewhat community standard around for how a mod is laid out. This, combined with [[Tutorial:Mod structure|how the game expects mods to be laid out]], limits us slightly. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>FireArmor_0.1.0</code>. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0

Then, inside FireArmor_0.1.0, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== The info.json file ===

Then, inside info.json, copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a number. Some mods start at 0.0.1 or 0.1.0, while others follow Factorio versions and start at 0.17.0 (for Factorio version 0.17.x)
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| contact
| Put contact info here, so someone can find you in the event of a problem.
|-
| homepage
| The homepage of your mod, put a website here if you have one for the mod. Not required.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 0.17 in this case.
|-
| dependencies
| Any dependencies of your mod. Some form of "base" should always be here, so base gets loaded first.
|-
| description
| A ''short'' description of your mod.
|}

And that's all for info.json! Next, in the data.lua file:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

It's a pretty simple file, all we're doing here is just telling the game to execute the file called item.lua in prototypes, which we're about to create. Create a folder in FireArmor_0.1.0 called <code>prototypes</code>, then inside prototypes, create a file called <code>item.lua</code>. Your mod directory should now match [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 this github snapshot].

Notice how our earlier require used the folder and file name in it?

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T10:50:10Z

Ucrij fender: /* Control */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== КонтрольControl ===

У більшості модифікацій є файл, який називається <code>control.lua</code>. Цей файл містить сценарії, які змушують мод робити речі під час гри, а не просто додавати суб'єкти до гри. Під час цього етапу запускається control.lua кожного мода, в його власномій інстанції lua (це означає відсутність взаємозв'язку без спеціальних налаштувань), яким він буде володіти на протязі решти сеансу відтворення. Оскільки це запускається щоразу, коли файл збереження створюється або завантажується, вам не потрібно перезапускати гру, щоб побачити зміни, внесені до файлу control.lua. Просто перезапуск або перезавантаження збереження повторно запустить цей етап. '''На цьому етапі є кілька інших застережень. Ознайомитися з ними можна на сторінці [http://lua-api.factorio.com/latest/Data-Lifecycle.html життєвих циклів даних] на веб-сайті API.'''

=== Runtime ===

At this stage, the mod is setup, and the save is running. Access to all tables provided by the game can be done inside of event handlers. (More on those below.)

== The major components to any Factorio mod ==

Within the average mod, there are several components that make the mod function.

Mods that define new entities will need to declare these entities in <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code>, or another file <code>require</code>d by one of these three.

Mods with in-game effects will also need a <code>control.lua</code> file, to add scripting.

Mods with configurable user settings will use <code>settings.lua</code> to describe those settings.

Mods that define any game element with a readable name may also provide a <code>locale</code> directory and subdirectories with names/descriptions in one or more languages.

The mod that we'll make in this tutorial will include both data.lua prototypes and control.lua scripting, to give you a feel for both.

Over time, the community has settled on some conventions for how a mod's directory structure should look. Following these to a T is not necessary, but can simplify things and make discussing mod bugs and improvements with other developers easier. More on directory structure below.

== The tutorial mod ==

And now for the moment you've been waiting for. Let's start making your first mod. You'll need:

* A recent install of Factorio
* A text editor, such as Emacs, Vim, Sublime text, etc
* An understanding of the tutorial above
* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.

Once you have all of these things, we can begin.

For this mod, we're going to make a set of armor that leaves behind damaging fire behind you as you walk. It will be fully resistant to fire, but weaker towards physical damage than heavy armor, making it an armor for hit and run attacks.

=== Creation of the directory structure ===

Like this tutorial mentioned earlier, there is a somewhat community standard around for how a mod is laid out. This, combined with [[Tutorial:Mod structure|how the game expects mods to be laid out]], limits us slightly. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>FireArmor_0.1.0</code>. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0

Then, inside FireArmor_0.1.0, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== The info.json file ===

Then, inside info.json, copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a number. Some mods start at 0.0.1 or 0.1.0, while others follow Factorio versions and start at 0.17.0 (for Factorio version 0.17.x)
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| contact
| Put contact info here, so someone can find you in the event of a problem.
|-
| homepage
| The homepage of your mod, put a website here if you have one for the mod. Not required.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 0.17 in this case.
|-
| dependencies
| Any dependencies of your mod. Some form of "base" should always be here, so base gets loaded first.
|-
| description
| A ''short'' description of your mod.
|}

And that's all for info.json! Next, in the data.lua file:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

It's a pretty simple file, all we're doing here is just telling the game to execute the file called item.lua in prototypes, which we're about to create. Create a folder in FireArmor_0.1.0 called <code>prototypes</code>, then inside prototypes, create a file called <code>item.lua</code>. Your mod directory should now match [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 this github snapshot].

Notice how our earlier require used the folder and file name in it?

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T10:45:08Z

Ucrij fender: /* Migrations */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Міграції(Migrations) ===

[http://lua-api.factorio.com/latest/Migrations.html Міграції] це сценарії, які використовуються для "виправлення" збереження після оновлення модів. Кожного разу, коли прототипи змінюються в межах модифікації, необхідно мігрувати, щоб виправити всі старі екземпляри прототипованої сутності у світі. Це потрібно зробити для всіх оновлених об'єктів, інакше старі об'єкти будуть видалені зі світу, що є непрофесійним резервом, який змушує користувачів не любити вас. Хоча цей посібник не буде обговорювати міграції, є багато ресурсів щодо міграцій, які можна знайти у спільноті та на веб-сайті API.

are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Control ===

Within most mods is a file called <code>control.lua</code>. This file contains scripting that makes the mod do things during the game, rather than just adding entities to the game. During this stage, each mod's control.lua is run, in it's own lua instance (this means no inter-communication without special setup) which it will own for the rest of the play session. Because this is run every time a save file is created or loaded you don't need to restart the game to see changes made to the control.lua file. Simply restarting or reloading a save will re-run this stage. '''There are a few other caveats to this stage, reading the [http://lua-api.factorio.com/latest/Data-Lifecycle.html data life cycle] page on the API site provides the best overview.'''

=== Runtime ===

At this stage, the mod is setup, and the save is running. Access to all tables provided by the game can be done inside of event handlers. (More on those below.)

== The major components to any Factorio mod ==

Within the average mod, there are several components that make the mod function.

Mods that define new entities will need to declare these entities in <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code>, or another file <code>require</code>d by one of these three.

Mods with in-game effects will also need a <code>control.lua</code> file, to add scripting.

Mods with configurable user settings will use <code>settings.lua</code> to describe those settings.

Mods that define any game element with a readable name may also provide a <code>locale</code> directory and subdirectories with names/descriptions in one or more languages.

The mod that we'll make in this tutorial will include both data.lua prototypes and control.lua scripting, to give you a feel for both.

Over time, the community has settled on some conventions for how a mod's directory structure should look. Following these to a T is not necessary, but can simplify things and make discussing mod bugs and improvements with other developers easier. More on directory structure below.

== The tutorial mod ==

And now for the moment you've been waiting for. Let's start making your first mod. You'll need:

* A recent install of Factorio
* A text editor, such as Emacs, Vim, Sublime text, etc
* An understanding of the tutorial above
* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.

Once you have all of these things, we can begin.

For this mod, we're going to make a set of armor that leaves behind damaging fire behind you as you walk. It will be fully resistant to fire, but weaker towards physical damage than heavy armor, making it an armor for hit and run attacks.

=== Creation of the directory structure ===

Like this tutorial mentioned earlier, there is a somewhat community standard around for how a mod is laid out. This, combined with [[Tutorial:Mod structure|how the game expects mods to be laid out]], limits us slightly. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>FireArmor_0.1.0</code>. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0

Then, inside FireArmor_0.1.0, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== The info.json file ===

Then, inside info.json, copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a number. Some mods start at 0.0.1 or 0.1.0, while others follow Factorio versions and start at 0.17.0 (for Factorio version 0.17.x)
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| contact
| Put contact info here, so someone can find you in the event of a problem.
|-
| homepage
| The homepage of your mod, put a website here if you have one for the mod. Not required.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 0.17 in this case.
|-
| dependencies
| Any dependencies of your mod. Some form of "base" should always be here, so base gets loaded first.
|-
| description
| A ''short'' description of your mod.
|}

And that's all for info.json! Next, in the data.lua file:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

It's a pretty simple file, all we're doing here is just telling the game to execute the file called item.lua in prototypes, which we're about to create. Create a folder in FireArmor_0.1.0 called <code>prototypes</code>, then inside prototypes, create a file called <code>item.lua</code>. Your mod directory should now match [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 this github snapshot].

Notice how our earlier require used the folder and file name in it?

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T10:14:18Z

Ucrij fender: /* The data stage */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== Стадія даних ===

Це найбільш обмежена частина ініціалізації програми Factorio, тут ви майже нічого не можете, крім декларування прототипів для технологій та об'єктів. Такі речі, як маніпулювання файлами, які впливають на світ або інше блокуються/недоступні. Насправді будь-які внесені функції або зміни будуть відкинуті, оскільки сеанс Lua припиняється. Ви також не можете взаємодіяти з таблицею даних, але це буде визначено помилкою або ігноруватися. Використовуючи <code>data:extend({})</code>, воно очікуватиме певного формату, докладніше про це пізніше.

Під час запуску цього етапу гра переглядає всі моди для файлу під назвою <code>data.lua</code>. Після того, як data.lua виконано для всіх модів виконується <code>data-updates.lua</code>, і нарешті, ініціалізується <code>data-final-fixes.lua</code>. Ці 3 різні фази на етапі даних дозволяють змінювати дані інших мод без необхідності покладатися на залежності для завантаження останнього. Наприклад, базовий мод створює рецепти стволів для всіх наявних рідин у data-updates.lua. Це означає, що якщо ви додасте рідину в data.lua, базовий мод data-updates.lua додасть для нього рецепти "крафтингу"(barreling recipes,барелінгу), незалежно від відповідності версії вашого моду від бази(base mode). Звичайно, це також означає, що якщо ви додаєте рідину в data-final-fixes.lua, вона створюється після запуску коду барелінгу в data-updates.lua, тому що жоден рецепт не створюється навіть за бажанням, щоб виключити рідину з барелінгу створіть її в data.lua та використовуйте "auto_barrel = false" на рідині. Через такі та подібні модифікаційні взаємодії рекомендується створювати прототипи якомога раніше.

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

=== Migrations ===

[http://lua-api.factorio.com/latest/Migrations.html Migrations] are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Control ===

Within most mods is a file called <code>control.lua</code>. This file contains scripting that makes the mod do things during the game, rather than just adding entities to the game. During this stage, each mod's control.lua is run, in it's own lua instance (this means no inter-communication without special setup) which it will own for the rest of the play session. Because this is run every time a save file is created or loaded you don't need to restart the game to see changes made to the control.lua file. Simply restarting or reloading a save will re-run this stage. '''There are a few other caveats to this stage, reading the [http://lua-api.factorio.com/latest/Data-Lifecycle.html data life cycle] page on the API site provides the best overview.'''

=== Runtime ===

At this stage, the mod is setup, and the save is running. Access to all tables provided by the game can be done inside of event handlers. (More on those below.)

== The major components to any Factorio mod ==

Within the average mod, there are several components that make the mod function.

Mods that define new entities will need to declare these entities in <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code>, or another file <code>require</code>d by one of these three.

Mods with in-game effects will also need a <code>control.lua</code> file, to add scripting.

Mods with configurable user settings will use <code>settings.lua</code> to describe those settings.

Mods that define any game element with a readable name may also provide a <code>locale</code> directory and subdirectories with names/descriptions in one or more languages.

The mod that we'll make in this tutorial will include both data.lua prototypes and control.lua scripting, to give you a feel for both.

Over time, the community has settled on some conventions for how a mod's directory structure should look. Following these to a T is not necessary, but can simplify things and make discussing mod bugs and improvements with other developers easier. More on directory structure below.

== The tutorial mod ==

And now for the moment you've been waiting for. Let's start making your first mod. You'll need:

* A recent install of Factorio
* A text editor, such as Emacs, Vim, Sublime text, etc
* An understanding of the tutorial above
* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.

Once you have all of these things, we can begin.

For this mod, we're going to make a set of armor that leaves behind damaging fire behind you as you walk. It will be fully resistant to fire, but weaker towards physical damage than heavy armor, making it an armor for hit and run attacks.

=== Creation of the directory structure ===

Like this tutorial mentioned earlier, there is a somewhat community standard around for how a mod is laid out. This, combined with [[Tutorial:Mod structure|how the game expects mods to be laid out]], limits us slightly. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>FireArmor_0.1.0</code>. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0

Then, inside FireArmor_0.1.0, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== The info.json file ===

Then, inside info.json, copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a number. Some mods start at 0.0.1 or 0.1.0, while others follow Factorio versions and start at 0.17.0 (for Factorio version 0.17.x)
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| contact
| Put contact info here, so someone can find you in the event of a problem.
|-
| homepage
| The homepage of your mod, put a website here if you have one for the mod. Not required.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 0.17 in this case.
|-
| dependencies
| Any dependencies of your mod. Some form of "base" should always be here, so base gets loaded first.
|-
| description
| A ''short'' description of your mod.
|}

And that's all for info.json! Next, in the data.lua file:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

It's a pretty simple file, all we're doing here is just telling the game to execute the file called item.lua in prototypes, which we're about to create. Create a folder in FireArmor_0.1.0 called <code>prototypes</code>, then inside prototypes, create a file called <code>item.lua</code>. Your mod directory should now match [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 this github snapshot].

Notice how our earlier require used the folder and file name in it?

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T09:43:47Z

Ucrij fender: /* Стадія налаштування */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після ініціалізації settings.lua для всіх модів, виконується ініціалізація <code>settings-updates.lua</code> і нарешті <code>settings-final-fixes.lua</code>. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших модів, без потреби покладатися на залежність для останнього. Усі інші файли для завантаження потрібні. Усі файли, запущені тут, не повинні щось містити, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до прототипів або бібліотеки середовища виконання, оскільки це було завантажене на попередньому етапі. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування модів не охоплені в цьому підручнику, див. [[Tutorial:Mod settings]] для отримання додаткової інформації.

=== The data stage ===

This is the most restricted part of the Factorio init, there's not much you can do here other than declare prototypes for technologies and entities. Things like manipulating files, affecting the world, etc, are blocked/unavailable. In fact, any functions or changes made will be discarded, as the lua session is terminated. You also cannot mess with the data table, it will error or be ignored. When using <code>data:extend({})</code>, it expects a specific format, more on this later.

When running through this stage, the game looks through all mods for a file called <code>data.lua</code>. After data.lua has been executed for all mods, each mod's <code>data-updates.lua</code> is executed, and finally each mod's <code>data-final-fixes.lua</code> is called. These 3 different phases of the data stage allow to change data of other mods without needing to rely on dependencies to load last. For example, the base mod creates barrelling recipes for all (then present) fluids in data-updates.lua. This means that if you add a fluid in data.lua, the base mod's data-updates.lua will add barreling recipes for it, regardless of whether your mod depends on base. Of course this also means that if you add a fluid in data-final-fixes.lua, it is created after the barrelling code runs in data-updates.lua, so no barrelling recipe gets created, even when desired. Because of this and similar mod interactions, it is recommended to create prototypes as early as possible. So, don't use data-final-fixes.lua to exclude a fluid from barreling, instead create it in data.lua and utilize "auto_barrel = false" on the fluid.

All other files to be loaded will need to be required. All the files run here should contain nothing but prototype definitions and code to produce prototype definitions. More on requiring files later.

=== Migrations ===

[http://lua-api.factorio.com/latest/Migrations.html Migrations] are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Control ===

Within most mods is a file called <code>control.lua</code>. This file contains scripting that makes the mod do things during the game, rather than just adding entities to the game. During this stage, each mod's control.lua is run, in it's own lua instance (this means no inter-communication without special setup) which it will own for the rest of the play session. Because this is run every time a save file is created or loaded you don't need to restart the game to see changes made to the control.lua file. Simply restarting or reloading a save will re-run this stage. '''There are a few other caveats to this stage, reading the [http://lua-api.factorio.com/latest/Data-Lifecycle.html data life cycle] page on the API site provides the best overview.'''

=== Runtime ===

At this stage, the mod is setup, and the save is running. Access to all tables provided by the game can be done inside of event handlers. (More on those below.)

== The major components to any Factorio mod ==

Within the average mod, there are several components that make the mod function.

Mods that define new entities will need to declare these entities in <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code>, or another file <code>require</code>d by one of these three.

Mods with in-game effects will also need a <code>control.lua</code> file, to add scripting.

Mods with configurable user settings will use <code>settings.lua</code> to describe those settings.

Mods that define any game element with a readable name may also provide a <code>locale</code> directory and subdirectories with names/descriptions in one or more languages.

The mod that we'll make in this tutorial will include both data.lua prototypes and control.lua scripting, to give you a feel for both.

Over time, the community has settled on some conventions for how a mod's directory structure should look. Following these to a T is not necessary, but can simplify things and make discussing mod bugs and improvements with other developers easier. More on directory structure below.

== The tutorial mod ==

And now for the moment you've been waiting for. Let's start making your first mod. You'll need:

* A recent install of Factorio
* A text editor, such as Emacs, Vim, Sublime text, etc
* An understanding of the tutorial above
* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.

Once you have all of these things, we can begin.

For this mod, we're going to make a set of armor that leaves behind damaging fire behind you as you walk. It will be fully resistant to fire, but weaker towards physical damage than heavy armor, making it an armor for hit and run attacks.

=== Creation of the directory structure ===

Like this tutorial mentioned earlier, there is a somewhat community standard around for how a mod is laid out. This, combined with [[Tutorial:Mod structure|how the game expects mods to be laid out]], limits us slightly. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>FireArmor_0.1.0</code>. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0

Then, inside FireArmor_0.1.0, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== The info.json file ===

Then, inside info.json, copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a number. Some mods start at 0.0.1 or 0.1.0, while others follow Factorio versions and start at 0.17.0 (for Factorio version 0.17.x)
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| contact
| Put contact info here, so someone can find you in the event of a problem.
|-
| homepage
| The homepage of your mod, put a website here if you have one for the mod. Not required.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 0.17 in this case.
|-
| dependencies
| Any dependencies of your mod. Some form of "base" should always be here, so base gets loaded first.
|-
| description
| A ''short'' description of your mod.
|}

And that's all for info.json! Next, in the data.lua file:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

It's a pretty simple file, all we're doing here is just telling the game to execute the file called item.lua in prototypes, which we're about to create. Create a folder in FireArmor_0.1.0 called <code>prototypes</code>, then inside prototypes, create a file called <code>item.lua</code>. Your mod directory should now match [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 this github snapshot].

Notice how our earlier require used the folder and file name in it?

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T09:31:57Z

Ucrij fender: /* The settings stage */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== Стадія налаштування ===
Найперша стадія - це етап налаштувань. В ній визначаються всі параметри модів, які згодом відображаються в інтерфейсі GUI з налаштуваннями ігрового режиму, без інших функцій чи можливостей. Під час запуску цього етапу гра переглядає всі моди для файлів, назви яких були записані в <code>settings.lua</code>. Після того, як settings.lua був виконаний для всіх модів, виконується <code> settings-updates.lua </code> кожного мода, і, нарешті, виклик <code> settings-final-fixes.lua </code> кожного мода. Ці 3 різні фази етапу налаштування дозволяють змінювати налаштування інших мод, не потрібно покладатися на залежність для останнього завантаження. Усі інші файли для завантаження повинні бути потрібні. Усі файли, запущені тут, не повинні містити нічого, крім встановлення визначень та коду для створення визначень параметрів.

Етап налаштувань не має доступу до даних прототипу або часу виконання, оскільки він завантажений перед цими етапами. Очікується, що налаштування матимуть певний формат, а весь додатковий код буде відкинутий після завершення етапу.

Налаштування моди не охоплені в цьому підручнику, див. [[Підручник: Налаштування моди]] для отримання додаткової інформації про них.

This stage is used to define all mod settings that are later shown in the in-game mod settings GUI, and has no other functions or possibilities. When running through this stage, the game looks through all mods for a file called <code>settings.lua</code>. After settings.lua has been executed for all mods, each mod's <code>settings-updates.lua</code> is executed, and finally each mod's <code>settings-final-fixes.lua</code> is called. These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. All other files to be loaded will need to be required. All the files run here should contain nothing but setting definitions and code to produce setting definitions.

The settings stage does not have access to prototype or runtime data because it is loaded before those stages. The settings are expected to have a certain format, and all additional code will be discarded once the stage is over.

Mod settings are not covered in this tutorial, see [[Tutorial:Mod settings]] for further info on them.

=== The data stage ===

This is the most restricted part of the Factorio init, there's not much you can do here other than declare prototypes for technologies and entities. Things like manipulating files, affecting the world, etc, are blocked/unavailable. In fact, any functions or changes made will be discarded, as the lua session is terminated. You also cannot mess with the data table, it will error or be ignored. When using <code>data:extend({})</code>, it expects a specific format, more on this later.

When running through this stage, the game looks through all mods for a file called <code>data.lua</code>. After data.lua has been executed for all mods, each mod's <code>data-updates.lua</code> is executed, and finally each mod's <code>data-final-fixes.lua</code> is called. These 3 different phases of the data stage allow to change data of other mods without needing to rely on dependencies to load last. For example, the base mod creates barrelling recipes for all (then present) fluids in data-updates.lua. This means that if you add a fluid in data.lua, the base mod's data-updates.lua will add barreling recipes for it, regardless of whether your mod depends on base. Of course this also means that if you add a fluid in data-final-fixes.lua, it is created after the barrelling code runs in data-updates.lua, so no barrelling recipe gets created, even when desired. Because of this and similar mod interactions, it is recommended to create prototypes as early as possible. So, don't use data-final-fixes.lua to exclude a fluid from barreling, instead create it in data.lua and utilize "auto_barrel = false" on the fluid.

All other files to be loaded will need to be required. All the files run here should contain nothing but prototype definitions and code to produce prototype definitions. More on requiring files later.

=== Migrations ===

[http://lua-api.factorio.com/latest/Migrations.html Migrations] are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Control ===

Within most mods is a file called <code>control.lua</code>. This file contains scripting that makes the mod do things during the game, rather than just adding entities to the game. During this stage, each mod's control.lua is run, in it's own lua instance (this means no inter-communication without special setup) which it will own for the rest of the play session. Because this is run every time a save file is created or loaded you don't need to restart the game to see changes made to the control.lua file. Simply restarting or reloading a save will re-run this stage. '''There are a few other caveats to this stage, reading the [http://lua-api.factorio.com/latest/Data-Lifecycle.html data life cycle] page on the API site provides the best overview.'''

=== Runtime ===

At this stage, the mod is setup, and the save is running. Access to all tables provided by the game can be done inside of event handlers. (More on those below.)

== The major components to any Factorio mod ==

Within the average mod, there are several components that make the mod function.

Mods that define new entities will need to declare these entities in <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code>, or another file <code>require</code>d by one of these three.

Mods with in-game effects will also need a <code>control.lua</code> file, to add scripting.

Mods with configurable user settings will use <code>settings.lua</code> to describe those settings.

Mods that define any game element with a readable name may also provide a <code>locale</code> directory and subdirectories with names/descriptions in one or more languages.

The mod that we'll make in this tutorial will include both data.lua prototypes and control.lua scripting, to give you a feel for both.

Over time, the community has settled on some conventions for how a mod's directory structure should look. Following these to a T is not necessary, but can simplify things and make discussing mod bugs and improvements with other developers easier. More on directory structure below.

== The tutorial mod ==

And now for the moment you've been waiting for. Let's start making your first mod. You'll need:

* A recent install of Factorio
* A text editor, such as Emacs, Vim, Sublime text, etc
* An understanding of the tutorial above
* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.

Once you have all of these things, we can begin.

For this mod, we're going to make a set of armor that leaves behind damaging fire behind you as you walk. It will be fully resistant to fire, but weaker towards physical damage than heavy armor, making it an armor for hit and run attacks.

=== Creation of the directory structure ===

Like this tutorial mentioned earlier, there is a somewhat community standard around for how a mod is laid out. This, combined with [[Tutorial:Mod structure|how the game expects mods to be laid out]], limits us slightly. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>FireArmor_0.1.0</code>. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0

Then, inside FireArmor_0.1.0, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== The info.json file ===

Then, inside info.json, copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a number. Some mods start at 0.0.1 or 0.1.0, while others follow Factorio versions and start at 0.17.0 (for Factorio version 0.17.x)
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| contact
| Put contact info here, so someone can find you in the event of a problem.
|-
| homepage
| The homepage of your mod, put a website here if you have one for the mod. Not required.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 0.17 in this case.
|-
| dependencies
| Any dependencies of your mod. Some form of "base" should always be here, so base gets loaded first.
|-
| description
| A ''short'' description of your mod.
|}

And that's all for info.json! Next, in the data.lua file:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

It's a pretty simple file, all we're doing here is just telling the game to execute the file called item.lua in prototypes, which we're about to create. Create a folder in FireArmor_0.1.0 called <code>prototypes</code>, then inside prototypes, create a file called <code>item.lua</code>. Your mod directory should now match [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 this github snapshot].

Notice how our earlier require used the folder and file name in it?

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T09:18:51Z

Ucrij fender: /* Послідовність завантаження */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливають на порядок модифікацій, а натомість запобігають завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== The settings stage ===
The very first mod stage that is loaded when Factorio initializes is the settings stage. This stage is used to define all mod settings that are later shown in the in-game mod settings GUI, and has no other functions or possibilities. When running through this stage, the game looks through all mods for a file called <code>settings.lua</code>. After settings.lua has been executed for all mods, each mod's <code>settings-updates.lua</code> is executed, and finally each mod's <code>settings-final-fixes.lua</code> is called. These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. All other files to be loaded will need to be required. All the files run here should contain nothing but setting definitions and code to produce setting definitions.

The settings stage does not have access to prototype or runtime data because it is loaded before those stages. The settings are expected to have a certain format, and all additional code will be discarded once the stage is over.

Mod settings are not covered in this tutorial, see [[Tutorial:Mod settings]] for further info on them.

=== The data stage ===

This is the most restricted part of the Factorio init, there's not much you can do here other than declare prototypes for technologies and entities. Things like manipulating files, affecting the world, etc, are blocked/unavailable. In fact, any functions or changes made will be discarded, as the lua session is terminated. You also cannot mess with the data table, it will error or be ignored. When using <code>data:extend({})</code>, it expects a specific format, more on this later.

When running through this stage, the game looks through all mods for a file called <code>data.lua</code>. After data.lua has been executed for all mods, each mod's <code>data-updates.lua</code> is executed, and finally each mod's <code>data-final-fixes.lua</code> is called. These 3 different phases of the data stage allow to change data of other mods without needing to rely on dependencies to load last. For example, the base mod creates barrelling recipes for all (then present) fluids in data-updates.lua. This means that if you add a fluid in data.lua, the base mod's data-updates.lua will add barreling recipes for it, regardless of whether your mod depends on base. Of course this also means that if you add a fluid in data-final-fixes.lua, it is created after the barrelling code runs in data-updates.lua, so no barrelling recipe gets created, even when desired. Because of this and similar mod interactions, it is recommended to create prototypes as early as possible. So, don't use data-final-fixes.lua to exclude a fluid from barreling, instead create it in data.lua and utilize "auto_barrel = false" on the fluid.

All other files to be loaded will need to be required. All the files run here should contain nothing but prototype definitions and code to produce prototype definitions. More on requiring files later.

=== Migrations ===

[http://lua-api.factorio.com/latest/Migrations.html Migrations] are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Control ===

Within most mods is a file called <code>control.lua</code>. This file contains scripting that makes the mod do things during the game, rather than just adding entities to the game. During this stage, each mod's control.lua is run, in it's own lua instance (this means no inter-communication without special setup) which it will own for the rest of the play session. Because this is run every time a save file is created or loaded you don't need to restart the game to see changes made to the control.lua file. Simply restarting or reloading a save will re-run this stage. '''There are a few other caveats to this stage, reading the [http://lua-api.factorio.com/latest/Data-Lifecycle.html data life cycle] page on the API site provides the best overview.'''

=== Runtime ===

At this stage, the mod is setup, and the save is running. Access to all tables provided by the game can be done inside of event handlers. (More on those below.)

== The major components to any Factorio mod ==

Within the average mod, there are several components that make the mod function.

Mods that define new entities will need to declare these entities in <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code>, or another file <code>require</code>d by one of these three.

Mods with in-game effects will also need a <code>control.lua</code> file, to add scripting.

Mods with configurable user settings will use <code>settings.lua</code> to describe those settings.

Mods that define any game element with a readable name may also provide a <code>locale</code> directory and subdirectories with names/descriptions in one or more languages.

The mod that we'll make in this tutorial will include both data.lua prototypes and control.lua scripting, to give you a feel for both.

Over time, the community has settled on some conventions for how a mod's directory structure should look. Following these to a T is not necessary, but can simplify things and make discussing mod bugs and improvements with other developers easier. More on directory structure below.

== The tutorial mod ==

And now for the moment you've been waiting for. Let's start making your first mod. You'll need:

* A recent install of Factorio
* A text editor, such as Emacs, Vim, Sublime text, etc
* An understanding of the tutorial above
* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.

Once you have all of these things, we can begin.

For this mod, we're going to make a set of armor that leaves behind damaging fire behind you as you walk. It will be fully resistant to fire, but weaker towards physical damage than heavy armor, making it an armor for hit and run attacks.

=== Creation of the directory structure ===

Like this tutorial mentioned earlier, there is a somewhat community standard around for how a mod is laid out. This, combined with [[Tutorial:Mod structure|how the game expects mods to be laid out]], limits us slightly. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>FireArmor_0.1.0</code>. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0

Then, inside FireArmor_0.1.0, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== The info.json file ===

Then, inside info.json, copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a number. Some mods start at 0.0.1 or 0.1.0, while others follow Factorio versions and start at 0.17.0 (for Factorio version 0.17.x)
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| contact
| Put contact info here, so someone can find you in the event of a problem.
|-
| homepage
| The homepage of your mod, put a website here if you have one for the mod. Not required.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 0.17 in this case.
|-
| dependencies
| Any dependencies of your mod. Some form of "base" should always be here, so base gets loaded first.
|-
| description
| A ''short'' description of your mod.
|}

And that's all for info.json! Next, in the data.lua file:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

It's a pretty simple file, all we're doing here is just telling the game to execute the file called item.lua in prototypes, which we're about to create. Create a folder in FireArmor_0.1.0 called <code>prototypes</code>, then inside prototypes, create a file called <code>item.lua</code>. Your mod directory should now match [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 this github snapshot].

Notice how our earlier require used the folder and file name in it?

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T09:15:20Z

Ucrij fender: /* Послідовність завантаження */

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
На етапі завантажування модів, вони завантажуються залежно, потім за алфавітом. Це '''дуже важливо''', щоб зрозуміти, оскільки це може спричинити проблеми, якщо ви нехтуєте цим і намагаєтеся додати модифікацію в інший мод.

Factorio має три види залежності. Існують необхідні та необов'язкові залежності. Третій вид, обмежуючі залежності, не впливає на порядок модифікацій, а натомість запобігає завантаженню гри, якщо знайдеться інший мод. Потрібні залежності завантажуються першими завжди. Гра не ініціалізується, якщо якогось мода немає. Необов'язкові залежності завантажуються спочатку, якщо вони є, але не повинні бути присутніми. Це корисно для включення бонусних функцій, якщо моднифікації використовуються разом. Необхідні залежності повинні використовуватися для бібліотек модифікацій та подібих інфраструктур.

=== The settings stage ===
The very first mod stage that is loaded when Factorio initializes is the settings stage. This stage is used to define all mod settings that are later shown in the in-game mod settings GUI, and has no other functions or possibilities. When running through this stage, the game looks through all mods for a file called <code>settings.lua</code>. After settings.lua has been executed for all mods, each mod's <code>settings-updates.lua</code> is executed, and finally each mod's <code>settings-final-fixes.lua</code> is called. These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. All other files to be loaded will need to be required. All the files run here should contain nothing but setting definitions and code to produce setting definitions.

The settings stage does not have access to prototype or runtime data because it is loaded before those stages. The settings are expected to have a certain format, and all additional code will be discarded once the stage is over.

Mod settings are not covered in this tutorial, see [[Tutorial:Mod settings]] for further info on them.

=== The data stage ===

This is the most restricted part of the Factorio init, there's not much you can do here other than declare prototypes for technologies and entities. Things like manipulating files, affecting the world, etc, are blocked/unavailable. In fact, any functions or changes made will be discarded, as the lua session is terminated. You also cannot mess with the data table, it will error or be ignored. When using <code>data:extend({})</code>, it expects a specific format, more on this later.

When running through this stage, the game looks through all mods for a file called <code>data.lua</code>. After data.lua has been executed for all mods, each mod's <code>data-updates.lua</code> is executed, and finally each mod's <code>data-final-fixes.lua</code> is called. These 3 different phases of the data stage allow to change data of other mods without needing to rely on dependencies to load last. For example, the base mod creates barrelling recipes for all (then present) fluids in data-updates.lua. This means that if you add a fluid in data.lua, the base mod's data-updates.lua will add barreling recipes for it, regardless of whether your mod depends on base. Of course this also means that if you add a fluid in data-final-fixes.lua, it is created after the barrelling code runs in data-updates.lua, so no barrelling recipe gets created, even when desired. Because of this and similar mod interactions, it is recommended to create prototypes as early as possible. So, don't use data-final-fixes.lua to exclude a fluid from barreling, instead create it in data.lua and utilize "auto_barrel = false" on the fluid.

All other files to be loaded will need to be required. All the files run here should contain nothing but prototype definitions and code to produce prototype definitions. More on requiring files later.

=== Migrations ===

[http://lua-api.factorio.com/latest/Migrations.html Migrations] are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Control ===

Within most mods is a file called <code>control.lua</code>. This file contains scripting that makes the mod do things during the game, rather than just adding entities to the game. During this stage, each mod's control.lua is run, in it's own lua instance (this means no inter-communication without special setup) which it will own for the rest of the play session. Because this is run every time a save file is created or loaded you don't need to restart the game to see changes made to the control.lua file. Simply restarting or reloading a save will re-run this stage. '''There are a few other caveats to this stage, reading the [http://lua-api.factorio.com/latest/Data-Lifecycle.html data life cycle] page on the API site provides the best overview.'''

=== Runtime ===

At this stage, the mod is setup, and the save is running. Access to all tables provided by the game can be done inside of event handlers. (More on those below.)

== The major components to any Factorio mod ==

Within the average mod, there are several components that make the mod function.

Mods that define new entities will need to declare these entities in <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code>, or another file <code>require</code>d by one of these three.

Mods with in-game effects will also need a <code>control.lua</code> file, to add scripting.

Mods with configurable user settings will use <code>settings.lua</code> to describe those settings.

Mods that define any game element with a readable name may also provide a <code>locale</code> directory and subdirectories with names/descriptions in one or more languages.

The mod that we'll make in this tutorial will include both data.lua prototypes and control.lua scripting, to give you a feel for both.

Over time, the community has settled on some conventions for how a mod's directory structure should look. Following these to a T is not necessary, but can simplify things and make discussing mod bugs and improvements with other developers easier. More on directory structure below.

== The tutorial mod ==

And now for the moment you've been waiting for. Let's start making your first mod. You'll need:

* A recent install of Factorio
* A text editor, such as Emacs, Vim, Sublime text, etc
* An understanding of the tutorial above
* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.

Once you have all of these things, we can begin.

For this mod, we're going to make a set of armor that leaves behind damaging fire behind you as you walk. It will be fully resistant to fire, but weaker towards physical damage than heavy armor, making it an armor for hit and run attacks.

=== Creation of the directory structure ===

Like this tutorial mentioned earlier, there is a somewhat community standard around for how a mod is laid out. This, combined with [[Tutorial:Mod structure|how the game expects mods to be laid out]], limits us slightly. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>FireArmor_0.1.0</code>. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0

Then, inside FireArmor_0.1.0, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== The info.json file ===

Then, inside info.json, copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a number. Some mods start at 0.0.1 or 0.1.0, while others follow Factorio versions and start at 0.17.0 (for Factorio version 0.17.x)
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| contact
| Put contact info here, so someone can find you in the event of a problem.
|-
| homepage
| The homepage of your mod, put a website here if you have one for the mod. Not required.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 0.17 in this case.
|-
| dependencies
| Any dependencies of your mod. Some form of "base" should always be here, so base gets loaded first.
|-
| description
| A ''short'' description of your mod.
|}

And that's all for info.json! Next, in the data.lua file:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

It's a pretty simple file, all we're doing here is just telling the game to execute the file called item.lua in prototypes, which we're about to create. Create a folder in FireArmor_0.1.0 called <code>prototypes</code>, then inside prototypes, create a file called <code>item.lua</code>. Your mod directory should now match [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 this github snapshot].

Notice how our earlier require used the folder and file name in it?

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

User:Ucrij fender/Tutorial:Modding tutorial/Gangsir/uk

2020-03-15T08:53:45Z

Ucrij fender: Created page with "{{Languages}} <pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>..."

{{Languages}}
<pre style="background-color:#0F0F0F!important;color:#FF0000;border:1px solid red;"> '''Стаття ще не перекладена повністю.''' </pre>
{{Languages}}
Це туторіал по модінгу для Factorio 0.17. В ньому автор пояснить, що твориться за кулісою Factorio, як модифікувати Factorio, де знайти документацію та пояснить поняття.

== Загальні відомості==
Перед початком, декілька зауважень:

<pre style="background-color:#AAFFAA!important; color:black">
Код виділений зеленим кольором, як цей, має бути включеним до складу модифікації цього навчального посібника, звісно якщо читач слідує цьому довіднику. Найкращий спосіб це скопіювати та вставити, для забезпечення вірного відтворення.
Щоразу, коли код доданий до модифікації, коментар Lua з ім'ям файлу буде на початку зеленої коробки. Скопіюйте код у вікні у файл з такою назвою. Наприклад:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Код виділений фіолетовим кольором, як цей, не має бути включеним до складу модифікації, це просто приклади.
</pre>

Цей посібник був оновлений до версії 0.17, тому ''в майбутньому, ви повинні відзначити, що деякі незначні зміни можуть бути внесені'', і варто переглядати журнали змін до поточної версії.

== Термінологія ==

Перш ніж розпочати, слід вияснити кілька термінів та визначень для кращого розуміння.

; Модифікація/Мод/Mod : Сценарій(скрипт) або серія скриптів, що дозволяють змінювати гру через API.
; Суб'єкт/Сутність/Entity : Суб’єкт у Factorio - це все в грі, яке не є типом, змінною, поняттям, подією чи плиткою. Приклади об'єктів включають символи, складальну машину, кусаку і т.д. Це можуть бути "машини" або об'єкти, що рухаються, як гравець.
; Персонаж/Character : Фактична сутність, через яку гравець маніпулює світом.
; Гравець/Player : Усі дані, що визначають гравця, такі як ім'я користувача, положення в таблиці гравців тощо. Усі гравці мають персонажа, але всередині персонажа не має гравців.
; Прототип/Об'єкт/Prototype : Прототип описує якусь сутність, трохи схожу на шаблон. Він визначає статистику(stats, наприклад здоров'я), що таке сутність насправді і т.д. Прототип використовується для створення сутності, і багато функціонально-однакових сутностей будуть використовувати один і той же прототип.
; Поверхня/Surface : Поверхня трохи схожа на вимір(dimension, простір, в математичному значенні). Вона складається з місцевості, наприклад трави, піску, води та всіх структур на поверхні. За замовчуванням у Factorio є лише одна поверхня, яку внутрішньо називають "nauvis" або <code style="background-color:#DDA0DD; color:black">game.surfaces</code>, але модифікації можуть створювати додаткові поверхні за допомогою API.
; Подія/Event : Подія - це повторювана ... подія, що викликається грою всередині. Існує кілька подій, які модифікації можуть підключати до функції, такі як <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, тощо.

Докладніше про це в розділі контрольних сценаріїв.

== Перед початком модифікування ==

Перш ніж ми зможемо почати модифікувати Factorio, ми повинні зрозуміти, що таке Factorio. Ви можете прочитати [[Factorio:About/uk|about page]], але саме так зробив би гравець. Оскільки ми намагаємося стати розробником модів, нам потрібно більш детальне пояснення. Factorio - це гра, написана мовою програмування C++, з API, розробленим Wube (розробниками Factorio) для модифікації Factorio на мові програмування Lua(версії 5.2.1). Це API дозволяє додавати скрипти до процесу ініціалізації Factorio, змінювати його без викриття вихідного коду базової гри або зміни пам'яті. Це може відрізнятися від інших ігор, які пропонують модинг, але це більш професійний і правильний спосіб підтримки модінгу.

Щоб допомогти у використанні цього API, розробники люб'язно надали досить вичерпну документацію на своєму [http://lua-api.factorio.com/latest/ API сайті]. Звикайте використовувати цей сайт, оскільки ви будете часто відвідувати цей сайт, коли розробляєте модифікації. Він містить інформацію про [http://lua-api.factorio.com/latest/Classes.html класи], інформацію про [http://lua-api.factorio.com/latest/Concepts.html поняття] та інформацію про [http://lua-api.factorio.com/latest/events.html події], які ви можете підключити. Вам потрібно буде часто перевіряти цей сайт, тому автор рекомендує зробити закладку на ньому. Окрім цього веб-сайту, існує також багато ресурсів, створених спільнотою, наприклад, цей посібник.

=== Налаштування ===

Найкращий спосіб розробити мод - це розробити його там, де його можна легко перевірити. Крім того, рекомендується використовувати редактор, що дозволяє легко вводити текст та підтримувати мову Lua. Emacs, Vim, Sublime Text, VSCode та Notepad++ - рекомендовані кандидати. Цей автор віддає перевагу Emacs, але це не має значення в самому моді.

== Як Factorio завантажує модифікації ==

=== Послідовність завантаження ===
Within stages, mods are loaded by dependency, then by alphabetical order. This is ''very important'' to understand, as it can cause you problems if you neglect it and try to add inter-mod support to your mod.

Factorio has three kinds of dependencies. There are required dependencies, and optional dependencies. The third kind, restrictive dependencies, does not affect mod order and instead prevents the game from loading if the other mod is found. Required dependencies are loaded first, always. The game will fail to initialize if one of these is not present. Optional dependencies are loaded first if present, but do not have to be present. This is useful for enabling bonus features if mods are used together. Required dependencies should be used for mod libraries, and similar infrastructure.

=== The settings stage ===
The very first mod stage that is loaded when Factorio initializes is the settings stage. This stage is used to define all mod settings that are later shown in the in-game mod settings GUI, and has no other functions or possibilities. When running through this stage, the game looks through all mods for a file called <code>settings.lua</code>. After settings.lua has been executed for all mods, each mod's <code>settings-updates.lua</code> is executed, and finally each mod's <code>settings-final-fixes.lua</code> is called. These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. All other files to be loaded will need to be required. All the files run here should contain nothing but setting definitions and code to produce setting definitions.

The settings stage does not have access to prototype or runtime data because it is loaded before those stages. The settings are expected to have a certain format, and all additional code will be discarded once the stage is over.

Mod settings are not covered in this tutorial, see [[Tutorial:Mod settings]] for further info on them.

=== The data stage ===

This is the most restricted part of the Factorio init, there's not much you can do here other than declare prototypes for technologies and entities. Things like manipulating files, affecting the world, etc, are blocked/unavailable. In fact, any functions or changes made will be discarded, as the lua session is terminated. You also cannot mess with the data table, it will error or be ignored. When using <code>data:extend({})</code>, it expects a specific format, more on this later.

When running through this stage, the game looks through all mods for a file called <code>data.lua</code>. After data.lua has been executed for all mods, each mod's <code>data-updates.lua</code> is executed, and finally each mod's <code>data-final-fixes.lua</code> is called. These 3 different phases of the data stage allow to change data of other mods without needing to rely on dependencies to load last. For example, the base mod creates barrelling recipes for all (then present) fluids in data-updates.lua. This means that if you add a fluid in data.lua, the base mod's data-updates.lua will add barreling recipes for it, regardless of whether your mod depends on base. Of course this also means that if you add a fluid in data-final-fixes.lua, it is created after the barrelling code runs in data-updates.lua, so no barrelling recipe gets created, even when desired. Because of this and similar mod interactions, it is recommended to create prototypes as early as possible. So, don't use data-final-fixes.lua to exclude a fluid from barreling, instead create it in data.lua and utilize "auto_barrel = false" on the fluid.

All other files to be loaded will need to be required. All the files run here should contain nothing but prototype definitions and code to produce prototype definitions. More on requiring files later.

=== Migrations ===

[http://lua-api.factorio.com/latest/Migrations.html Migrations] are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Control ===

Within most mods is a file called <code>control.lua</code>. This file contains scripting that makes the mod do things during the game, rather than just adding entities to the game. During this stage, each mod's control.lua is run, in it's own lua instance (this means no inter-communication without special setup) which it will own for the rest of the play session. Because this is run every time a save file is created or loaded you don't need to restart the game to see changes made to the control.lua file. Simply restarting or reloading a save will re-run this stage. '''There are a few other caveats to this stage, reading the [http://lua-api.factorio.com/latest/Data-Lifecycle.html data life cycle] page on the API site provides the best overview.'''

=== Runtime ===

At this stage, the mod is setup, and the save is running. Access to all tables provided by the game can be done inside of event handlers. (More on those below.)

== The major components to any Factorio mod ==

Within the average mod, there are several components that make the mod function.

Mods that define new entities will need to declare these entities in <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code>, or another file <code>require</code>d by one of these three.

Mods with in-game effects will also need a <code>control.lua</code> file, to add scripting.

Mods with configurable user settings will use <code>settings.lua</code> to describe those settings.

Mods that define any game element with a readable name may also provide a <code>locale</code> directory and subdirectories with names/descriptions in one or more languages.

The mod that we'll make in this tutorial will include both data.lua prototypes and control.lua scripting, to give you a feel for both.

Over time, the community has settled on some conventions for how a mod's directory structure should look. Following these to a T is not necessary, but can simplify things and make discussing mod bugs and improvements with other developers easier. More on directory structure below.

== The tutorial mod ==

And now for the moment you've been waiting for. Let's start making your first mod. You'll need:

* A recent install of Factorio
* A text editor, such as Emacs, Vim, Sublime text, etc
* An understanding of the tutorial above
* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.

Once you have all of these things, we can begin.

For this mod, we're going to make a set of armor that leaves behind damaging fire behind you as you walk. It will be fully resistant to fire, but weaker towards physical damage than heavy armor, making it an armor for hit and run attacks.

=== Creation of the directory structure ===

Like this tutorial mentioned earlier, there is a somewhat community standard around for how a mod is laid out. This, combined with [[Tutorial:Mod structure|how the game expects mods to be laid out]], limits us slightly. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>FireArmor_0.1.0</code>. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0

Then, inside FireArmor_0.1.0, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== The info.json file ===

Then, inside info.json, copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "FireArmor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"contact": "",
"homepage": "",
"factorio_version": "0.17",
"dependencies": ["base >= 0.17"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a number. Some mods start at 0.0.1 or 0.1.0, while others follow Factorio versions and start at 0.17.0 (for Factorio version 0.17.x)
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| contact
| Put contact info here, so someone can find you in the event of a problem.
|-
| homepage
| The homepage of your mod, put a website here if you have one for the mod. Not required.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 0.17 in this case.
|-
| dependencies
| Any dependencies of your mod. Some form of "base" should always be here, so base gets loaded first.
|-
| description
| A ''short'' description of your mod.
|}

And that's all for info.json! Next, in the data.lua file:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

require("prototypes.item")
</pre>

It's a pretty simple file, all we're doing here is just telling the game to execute the file called item.lua in prototypes, which we're about to create. Create a folder in FireArmor_0.1.0 called <code>prototypes</code>, then inside prototypes, create a file called <code>item.lua</code>. Your mod directory should now match [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 this github snapshot].

Notice how our earlier require used the folder and file name in it?

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.lua

local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])

fireArmor.name = "fire-armor"
fireArmor.icons= {
{
icon=fireArmor.icon,
tint={r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
},
}

local recipe = table.deepcopy(data.raw.recipe["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by game to setup the Factorio universe. In fact, it contains the function <code>extend(self,prototypes)</code> and a table called <code>raw</code>. The former is customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw.armor["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. For example, the player's prototype would be:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.player["player"]
</pre>

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw.container['iron-chest'].max_health = 1000
</pre>

The reason why this code must be in data-final-fixes.lua or data-updates.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [http://lua-api.factorio.com/latest/Data-Lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event({defines.events.on_tick},
function (e)
if e.tick % 30 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just every 30 ticks, so twice per second
for index,player in pairs(game.connected_players) do --loop through all online players on the server

--if they're wearing our armor
if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
--create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [http://lua-api.factorio.com/latest/defines.html#defines.inventory here].

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>config.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside config.cfg, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it. Additionally, don't try submitting it to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mods: __FireArmor__/data.lua:1:__FireArmor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, you'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. Whenever the lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
__FireArmor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [http://lua-api.factorio.com/latest/LuaPlayer A player] is a table of several values. Trying to print it will error, instead a function to print it is needed.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 6 of control.lua, inside of an on_tick event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [http://lua-api.factorio.com/latest/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings or other criteria will also cause desyncs, and in some cases can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [http://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, looking at the mods of experienced modders can help significantly when making your own mod.

=== Keeping your mod working ===

As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== See also ==

* [[Modding]]
* [[Modding FAQ]]