From 2dccaed5eecf8d7c744b15482a6df8bf447c304d Mon Sep 17 00:00:00 2001 From: unknown Date: Fri, 12 Jul 2024 13:45:44 +0700 Subject: [PATCH 1/8] new guide version --- massmeta/modularization_guide.md | 244 +++++++++++++++++++------------ 1 file changed, 148 insertions(+), 96 deletions(-) diff --git a/massmeta/modularization_guide.md b/massmeta/modularization_guide.md index c7e3fa5ac6bd2..3d6f058f8a6bc 100644 --- a/massmeta/modularization_guide.md +++ b/massmeta/modularization_guide.md @@ -1,12 +1,12 @@ # Руководство по модуляризации кода - MassMeta style, v0.3 -Соблюдение этого Гайда - залог успешного мержа вашей фичи в репозиторий. +Соблюдение этого Гайда - залог успешного мержа Вашей фичи в репозиторий. ## Вступление -Проект **МассМета** - это, постоянно обновляющаяся, модульная ветка от проекта /TG/station. Тут мы добавляем свои фичи и по возможности откатываем неудачные. Прочитав эту инструкцию - Вы поймете как правильно нужно внедрить к нам Вашу фичу, чтоб ее могли увидеть в свет другие игроки нашего сервера. +Проект **МассМета** 🧰 - это, постоянно обновляющаяся, модульная ветка от проекта /TG/station. Тут мы добавляем свои фичи и по возможности откатываем неудачные. Прочитав эту инструкцию - Вы поймете как правильно нужно внедрить к нам Вашу идею, чтоб ее могли увидеть в свет другие игроки нашего сервера. -Несоблюдение данного руководства приведёт к стогнации код-базы проекта, как это было до. Осознав наши прошлые ошибки - было принято решение привести проект к модульности подобно той, как на серверах Skyrat, однако доработанной под наши конкретные нужды. [Оригинальное руководство](https://github.com/NovaSector/NovaSector/blob/master/modular_nova/readme.md) (на англ.) +Несоблюдение данного руководства приведёт к стагнации код-базы проекта, как это было до. Осознав наши прошлые ошибки - было принято решение привести проект к модульности подобно той, как на серверах Skyrat, однако доработанной под наши нужды. [Оригинальное руководство](https://github.com/NovaSector/NovaSector/blob/master/modular_nova/readme.md) (на англ.) ⚠️ **Все Баг-фиксы, изменение не Наших карт и тем более уже рефакторы кода - Вам нужно будет заливать именно в апстрим /TG/station !** @@ -18,13 +18,13 @@ * Запустите билд с Вашей **Фичей** и посмотрите как она себя ведёт, если ли какие-либо аномалии. * Если Ваша Фича предполагает взаимодействие нескольких игроков, то можете воспользоваться **Гостевым аккаунтом**. Для этого выйдите из BYOND-хаба и зайдите на локалку как Guest-[много циферок]. -Как только Вы считаете, что уже досконально проверили своё творение, то создавайте PR на наш репозиторий, там Вам уже подскажут как можно доработать тот или иной момент. +Как только Вы считаете, что уже достаточно проверили своё творение, то создавайте PR на наш репозиторий, там Вам уже подскажут как можно доработать тот или иной момент. ### Про платформу GitHub -Это одна из многих видов Систем Контроля Версий. Проект /TG/station располагается именно на нем. Сам Git одновременно и достаточно проработан в плане алгоритмов, он ими же и ограничен. Они не всегда могут однозначно разрешить определенные изменения в коде, что приводит к конфликтам, которые придется Вам резолвить вручную. +Это одна из многих видов Систем Контроля Версий. Проект /TG/station располагается именно на нем. Сам Git одновременно и достаточно проработан в плане алгоритмов, он ими же и ограничен. Они не всегда могут однозначно самостоятельно разрешить определенные изменения в коде, что приводит к конфликтам, которые нужно резолвить вручную. -Подробнее про сам Гит и как с ним работать [тут](https://git-scm.com/book/ru/v2). +Подробнее про сам Git и как с ним работать [тут](https://git-scm.com/book/ru/v2). ## Суть Конфликта ⚔️ @@ -59,46 +59,42 @@ var/something = 4 >>>>>> their-feature:foobar.dm ``` -В данном случае в череду коммитов /TG/station внедряется дополнительный, про который известно только нам самим. ГитХаб, видя поднобное несоотвествие - даёт нам сделать выбор. +В данном случае в череду коммитов /TG/station внедряется дополнительный, про который известно только нам самим. ГитХаб, видя подобное несоответствие - даёт нам сделать выбор. -Например нам нужно оставить только Наше изменение, то просто удаляем все что нам добавил гит и оставляем только нужное, +Например, нам нужно оставить только Наше изменение, то просто удаляем все что нам добавил гит и оставляем только нужное, ```byond var/something = 2 //MASSMETA EDIT ``` -Подобного рода конфликты разрешаются именно ручками, однако есть другие другие подходы к модульному коду, описанные ниже в данном руководстве. +Подобного рода конфликты разрешаются именно ручками, однако есть другие подходы к модульному коду, описанные ниже в данном руководстве. Подробнее про [Ветвления и Слияния](https://git-scm.com/book/ru/v2/Ветвление-в-Git-Основы-ветвления-и-слияния). ## Протокол модуляризации 🛠️ -У Вашего модуля должно быть коротное и информативное название. Например, `DNA-FEATURE-WINGS` или `XENOARCHEAOLOGY` или `SHUTTLE_TOGGLE`. +У Вашего модуля должно быть короткое и информативное название в документации, например - `SHUTTLE_TOGGLE`. -Мы будем использовать его в будущей документации, как **уникальный ID**. Он должен быть единым во всех ваших изменениях/дополнениях, где все пометки ДОЛЖНЫ быть абсолютно одинаковыми, что необходимо для удобного поиска! +Этим уникальным **ID** Вы назовёте: -Создаёте модульную папку, в которой вы будете локально работать, с названием как ID твоего модуля. Например, `modular_meta/features/shuttle_toggle/`. +- свою модульную папку `modular_meta/features/shuttle_toggle/`, в которой вы будете локально работать. -### Виды модуляризации +- а также в дальнейшем Вы будете помечать все **Немодульные** изменения в коде /TG/station. -Модуляризация существует трех типов: +Теперь подробнее про виды модуляризации. -* **Не Модульная** - изменения в оригинальных файлах /TG/station, как в примере выше. -* **Полностью Модульная** - дополнительный код либо переопределения кода в модульной папке проекта МассМета. -* **Смешанная** - иногда в Вашем модуле могут применяться оба типа. +### Не Модульные Изменения -#### Не Модульная - -Время от времени наступает момент, когда редактирование основных файлов становится неизбежным. +Время от времени наступает момент, когда редактирование **оригинальных** файлов /TG/station становится неизбежным. Пожалуйста, не забудьте записать факт их изменения под пунктом "TG Proc/File Changes" в **`readme.md`** вашего модуля. -В этих случаях мы решили применить следующую стандартизацию с примерами: +В этих случаях мы решили применять следующую стандартизацию: - **Добавление:** ```byond - //MASSMETA EDIT ADDITION BEGIN - SHUTTLE_TOGGLE - (Optional Reason/comment) + //MASSMETA EDIT ADDITION BEGIN (shuttle_toggle) var/adminEmergencyNoRecall = FALSE var/lastMode = SHUTTLE_IDLE var/lastCallTime = 6000 @@ -108,7 +104,7 @@ var/something = 2 //MASSMETA EDIT - **Удаление:** ```byond - //MASSMETA EDIT REMOVAL BEGIN - SHUTTLE_TOGGLE - (Optional Reason/comment) + //MASSMETA EDIT REMOVAL BEGIN (shuttle_toggle) /* for(var/obj/docking_port/stationary/S in stationary) if(S.id = id) @@ -117,72 +113,82 @@ var/something = 2 //MASSMETA EDIT //MASSMETA EDIT REMOVAL END ``` - И для любых удалений, которые перемещаются в другие файлы, допишите например: (Moved to modular_meta/features/shuttle_toggle/randomverbs.dm) - - **Изменения:** ```byond - //MASSMETA EDIT CHANGE BEGIN - SHUTTLE_TOGGLE - (Optional Reason/comment) - //if(SHUTTLE_STRANDED, SHUTTLE_ESCAPE) - MASSMETA EDIT - ORIGINAL + //MASSMETA EDIT CHANGE BEGIN (shuttle_toggle) + /* ORIGINAL + if(SHUTTLE_STRANDED, SHUTTLE_ESCAPE) + */ if(SHUTTLE_STRANDED, SHUTTLE_ESCAPE, SHUTTLE_DISABLED) //MASSMETA EDIT CHANGE END return 1 ``` + + Если предполагается **"Масштабное"** изменений кода, то такое переопределение уже надо перемещать в модуль. И на месте удаления допишите: (Moved to: modular_meta/features/shuttle_toggle/randomverbs.dm) - При небольшом локальном изменении кода хорошим тоном будет в комментарии указать то что было там до вашего вмешательства. + ⚠️ Обязательно оставляем все что было до вашего вмешательства под пометкой **ORIGINAL**! -#### Полностью Модульная +### Полностью Модульные Изменения -В нашем проекте присуствует папка **`modular_meta/`**, там будут храниться все наши "Модульные" изменения кода /TG/station. +В нашем проекте присутствует папка **`modular_meta/`**, там будут храниться все наши **"Модульные"** изменения кода /TG/station. 💡 Она полностью независима и этим мы гарантируем, что кодеры с /TG/station не будут туда вмешиваться. -В этой папке есть еще несколько подпапок: -| Папка/Файл | -| ---------------------- | -| **~meta_defines/** 📂 | -| **features/** 📂 | -| **master_files/** 📂 | -| **tools/** 📂 | +В этой папке есть еще несколько подпапок и файлов: + +| Папка/Файл | +| ------------------------------- | +| **~meta_defines/** 📂 | +| **features/** 📂 | +| **reverts/** 📂 | +| **tools/** 📂 | +| **modular_meta_defines.dm** 📄 | +| **modular_meta_features.dm** 📄 | +| **modular_meta_reverts.dm** 📄 | +| **modularization_guide.md** 📝 | +| **module_template.md** 📝 | +| **readme.md** 📝 | -Теперь подробнее про каждую из них: +Теперь подробнее про каждую из Папок: - **`~meta_defines/`** 📂 Здесь лежат все наши модульные "определения" (они же defines). - Вынесена отдельно из папки **`features/`** вследствии нюансов связанных с самим проектом /TG/station. (т.к. сам byond работает с дефайнами только в директории **`code/__DEFINES/`**, туда идет переопределение нашего файла.) - - Если у вас есть **define**, который используется более чем в одном файле, то он **обязательно** должен быть объявлен в этих файлах. + Вынесена отдельно из папки **`features/`** вследствии нюансов связанных с самим проектом /TG/station. (т.к. сам byond работает с дефайнами только в директории **`code/__DEFINES/`**, туда идёт переопределение наших файлов.) - Пожалуйста, не забудьте записать факт их добавления под пунктом "Defines:" в **`readme.md`** вашего модуля. + Если у вас есть **define**, который используется более чем в одном файле вашего кода, то он **обязательно** должен быть объявлен в файле этой папки. - 💡 Единожды используемый **define** (в рамках одного файла) достаточно объявить вверху и внизу файла. + 💡 Если **define** применяется только в рамках одного файла, то его достаточно объявить вверху и внизу файла. ```byond #define MY_DEFINE - //some code here + //some code with MY_DEFINE here #undef MY_DEFINE ``` - Эти файлы в папке включены в **`modular_meta/modular_meta_defines.dm`**. + + 📌 Пожалуйста, не забудьте записать факт их добавления под пунктом "Defines:" в **`readme.md`** вашего модуля. + + Все файлы в папке включены в **`modular_meta/modular_meta_defines.dm`**. - **`features/`** 📂 - Здесь лежат все наши НОВЫЕ модульные файлы, каждый в своем конкретном модуле со своим уникальным **module_id**. + Здесь лежат все модульные файлы **"Наших Фич"**, каждая в своем конкретном модуле со своим уникальным **module_id**. Подробнее про строение папок отдельных модулей расскажем ниже. - Только `includes.dm` файлы каждого модуля включены в **`modular_meta.dm`**. + Только `includes.dm` файлы каждого модуля включены в **`modular_meta_features.dm`**. -- **`master_files/`** 📂 +- **`reverts/`** 📂 - Здесь лежат все наши Модульные Перепределения кода, картинок и звуковых фалов /TG/Station. + Папка аналогичная `features/`, но там располагаются откаты плохих по нашему мнению фич, введёных апстримом /TG/station. - Пожалуйста, не забудьте записать факт их добавления под пунктом "Modular Overrides:" в **`readme.md`** вашего модуля. + Такой модуль именовать уже обязательно с припиской "revert", например вот так: **revert_module_id**. - Подробнее про оссобености этой папки ниже. + ⚠️ Обязательно укажите в файле **`readme.md`** модуля ссылку на пиар, который откатываевается! - Эти файлы в этой папке включены в **`modular_meta_master.dm`**. + Только `includes.dm` файлы каждого модуля включены в **`modular_meta_reverts.dm`**. - **`tools/`** 📂 @@ -192,86 +198,132 @@ var/something = 2 //MASSMETA EDIT К ним идет прямое обращение только в файле: **`.github/workflows/ci_suite.yml`**. -### Подробнее про модульные папки (в features) - -Чтобы сохранить общий стиль и обеспечить удобную навигацию по большинству модулей, а также контролировать количество файлов и папок в репозитории, вы должны следовать этой схеме. +## Подробнее про наполнение папок (features/ и reverts/) -⚠️ Папка вашего модуля дожна именоваться уникальным **module_id**! +Чтобы сохранить общий стиль и обеспечить удобную навигацию по большинству модулей, а также контролировать количество файлов и папок в репозитории, Dы должны следовать этой схеме. -⚠️ В этих файлах не должно быть закомментированного кода, тем более полностью закомментированных файлов! (Вы всегда можете посмотреть что было именно в этом файле просто нажав в GitHub "Посмотреть историю изменений".) +⚠️ Каждый модуль обязан содержать в себе файл документации модуля - `readme.md`. | Папка/Файл | Содержимое | | ------------------ | ---------------------------------------------------------- | | **code/** 📁 | Файлы кода: **`.dm`** | -| **icon/** 📁 | Иконки или картинки: **`.dmi`** и **`.png`** | +| **icon/** 📁 | Файлы иконок или картинок: **`.dmi`** и **`.png`** | | **sound/** 📁 | Звуковые файлы: **`.ogg`** и **`.waw`** | | **string/** 📁 | Файлы строк: **`.txt`** и **`.json`** | | **includes.dm** 📄 | Перечисление всех файлов в папке **code/** | | **readme.md** 📝 | Полная документация к модулю, [пример](module_template.md) | -📌 У проектов **Skyrat** стандартно все новые файлы сразу включаются в общий файл **`tgstation.dme`**, что я считаю достаточно трудным для дальнейшней поддрежки, да и в целом это не особо согласуется с их модульным принципом. +⛔ У проектов **Skyrat** присуствует папка `master_files/`, однако у нас в проекте её НЕТ! Все переопредения кода у нас помещается полностью в модуль с особыми пометками! Поянения будут позже. + +❗ Также у проектов **Skyrat** стандартно все новые файлы сразу включаются в общий файл **`tgstation.dme`**, что я считаю достаточно трудным для дальнейшней поддрежки, да и в целом это не особо согласуется с их модульным принципом. У нашего проекта другой поход в этом моменте, как Вы видите. + +### Подробнее про папку **`code/`** + +⚠️ В этих файлах не должно быть закомментированного кода, тем более полностью закомментированных файлов! А вот пояснения к коду оставлять можно, порой даже и нужно. -### Подробнее про файлы-переопределение (в master_files) +Здесь располагается код двух типов: -С помощью файлов в этой папке мы косвенно изменяем основной код /TG/station. Это позволяет нам очень изящно внедрять свои коррективы, не вмешиваясь напрямую в их код. Тем самым не нарушая их череду коммитов и не создавая для нам сами **Конфликтов Слияния**. +#### Абсолютно новые функции и объекты 🆕 + +Просто ложите все свои новые файлы кода в папку `code/` своего модуля. + +#### Расширение возможностей функций и Переопределение объектов /TG/station 🔀 + +С помощью этих файлов мы косвенно изменяем основной код /TG/station. Это позволяет нам очень изящно внедрять свои коррективы, не вмешиваясь напрямую в их код. Тем самым не нарушая их череду коммитов и не создавая для нам самих **Конфликтов Слияния**. Однако это является и минусом такого подхода. Гитхаб не сможет нам оперативно подсказать где файл поменялся ещё и где следует ввести уже измененое/дополнительное переопределение. Иногда прямые изменения кода через `//MASSMETA EDIT` предпочтительнее. Просто постарайтесь использовать здравый смысл в этом вопросе. -⚠️ В данной папке требуется обязательно соблюдать **Иерархию** папок файловой системы /TG/station. Это не позволит нам запутаться на какой именно файл мы воздействуем. +⚠️ У данных файлов НЕ НАДО соблюдать **Иерархию** аналогичной папки `code/` у /TG/station! Просто ложите вместе со всеми файлами в модуль. -#### Общие советы к такому подходу 💡 +Эти файлы выносите в "отдельную группу" с помощью пометки `"master_"`, например: `master_tg_filename.dm`. -Обратите внимание, что можно модульно добавлять код перед или за основной процедурой (proc), не редактируя исходную процедуру, а обращаясь к родительской процедуре с помощью `. = ..()` или `..()`. Аналогичным образом можно добавить новый var к существующему datum или obj, не редактируя напрямую файлы офф ТГ. +Над каждым блоком таких функций/объектов подписывайте в каком **оригинальном** файле /TG/station эта функция расположена. -Например не стоит: вставлять всю TG-процедуру в модульную переопределённую процедуру, внести всего одно небольшое изменение, а затем объявить её "полностью модульной". Эти процедуры - абсолютный кошмар для поддержки, потому что как только что-то изменится, вам придется обновлять переопределенную процедуру. +- **Пример модульного переопределения объекта** 💡 -Иногда вы даже не будете догадываться, что до вас вообще в другом модуле уже внедрили подобное переопределение, а оно ведь компилируется без ошибок! Это часто приводит к непониманию того и из-за чего у Вас всё ломается. + Например, Вы решили модульно переопределить иконку и описание у мольберта (easel). -Лучшими кандидатами для модульных переопределений процедур являются те, в которые вы можете просто добавить что-то после вызова родителя или ловко вплести вызов родителя в середину, чтобы достичь желаемого эффекта. + Оригинальный объект в коде /TG/station по пути `code/modules/art/paintings.dm`: -Производительность также следует учитывать, когда вы переопределяете горячую (часто вызываемую) процедуру (например, Life()), поскольку каждый дополнительный вызов увеличивает накладные расходы сервера. В таких случаях редактирование `//MASSMETA EDIT` намного критичны к общей производительности кода. Однако для большинства процедур об этом даже и не нужно беспокоиться. + ```byond + /obj/structure/easel + name = "easel" + desc = "Only for the finest of art!" + icon = 'icons/obj/art/artstuff.dmi' + icon_state = "easel" + density = TRUE + resistance_flags = FLAMMABLE + max_integrity = 60 + var/obj/item/canvas/painting = null + ``` -#### Пример подобной инъекции + Для этого создайте новый файл желательно с таким же именем как у оригинала и расположите в папке `code/` вашего модуля: `massmeta/features/art/code/master_paintings.dm`. -Для простоты предположим, что вы хотите заставить оружие искрить при выстреле для имитации дульной вспышки и вы хотите, чтобы это можно было использовать с всеми видами оружия, использующими эту функцию. + Наполнение даного файла будет выглядеть примерно так: -В модульном файле можно начать с добавления переменной `var`. + ```byond + //ORIGINAL: code/modules/art/paintings.dm + /obj/structure/easel + desc = "Let yourself draw!" + icon = 'massmeta/features/art/icons/artstuff.dmi' + icon_state = "new_easel" + ``` -```byond -/obj/item/gun - var/muzzle_flash = TRUE -``` + Теперь у вашего мольберта уже Новая иконка и описание. Даже код /TG/station менять не пришлось! 🎉 -Теперь у Вас будет у кадого наследника доступна эта переменная. После этого, допустим, вы захотите проверить `var` и вызвать искры после выстрела. -Исходная процедура, что вызывается при стрельбе, является: +- **Пример модульного добавления фич в функции** 💡 -```byond -/obj/item/gun/proc/shoot_live_shot(mob/living/user, pointblank = 0, atom/pbtarget = null, message = 1) -``` + Для простоты предположим, что вы хотите заставить оружие искрить при выстреле для имитации дульной вспышки и вы хотите, чтобы это можно было использовать с всеми видами оружия, использующими эту функцию. -вы можете переопределить в `master_files/` также и дочернюю процедуру /obj/item/gun/shoot_live_shot(), которая будет вставлена в цепочку наследования связанных с ней процедур. + В модульном файле можно начать с добавления переменной `var`. -```byond -/obj/item/gun/shoot_live_shot(mob/living/user, pointblank = 0, atom/pbtarget = null, message = 1) - . = ..() //. is the default return value, we assign what the parent proc returns to it, as we call it before ours - if(muzzle_flash) - spawn_sparks(src) //For simplicity, I assume you've already made a proc for this -``` + ```byond + /obj/item/gun + var/muzzle_flash = TRUE + ``` -Этим мы добились того, что оружие при выстреле ещё и искрит, при том не вмешиваясь в функции /TG/station напрямую. + Теперь у Вас будет у каждого наследника доступна эта переменная. После этого, допустим, вы захотите проверить `var` и вызвать искры после выстрела. + Исходная процедура, что вызывается при стрельбе, является: + + ```byond + /obj/item/gun/proc/shoot_live_shot(mob/living/user, pointblank = 0, atom/pbtarget = null, message = 1) + ``` + + вы можете переопределить также и дочернюю процедуру /obj/item/gun/shoot_live_shot(), которая будет вставлена в цепочку наследования связанных с ней процедур. + + ```byond + /obj/item/gun/shoot_live_shot(mob/living/user, pointblank = 0, atom/pbtarget = null, message = 1) + . = ..() //. is the default return value, we assign what the parent proc returns to it, as we call it before ours + if(muzzle_flash) + spawn_sparks(src) //For simplicity, I assume you've already made a proc for this + ``` + + Этим мы добились того, что оружие при выстреле ещё и искрит, при том не вмешиваясь в функции /TG/station напрямую! 🎉 + +### Общие советы к такому подходу 💡 + +Обратите внимание, что можно модульно добавлять код перед или за основной процедурой (proc), не редактируя исходную процедуру, а обращаясь к родительской процедуре с помощью `. = ..()` или `..()`. Аналогичным образом можно добавить новый var к существующему datum или obj, не редактируя напрямую файлы офф ТГ, как это было показано в примерах выше. + +Например НЕ стоит: вставлять всю TG-процедуру в модульную переопределённую процедуру, внести всего одно небольшое изменение, а затем объявить её "полностью модульной". Эти процедуры - абсолютный кошмар для поддержки, потому что как только что-то изменится, вам придется обновлять переопределенную процедуру. + +Иногда вы даже не будете догадываться, что до вас вообще в другом модуле уже внедрили подобное переопределение, а оно ведь компилируется без ошибок! Это часто приводит к непониманию того и из-за чего у Вас всё ломается. + +Лучшими кандидатами для модульных переопределений процедур являются те, в которые вы можете просто добавить что-то после вызова родителя или ловко вплести вызов родителя в середину, чтобы достичь желаемого эффекта. + +Производительность также следует учитывать, когда вы переопределяете горячую (часто вызываемую) процедуру (например, Life()), поскольку каждый дополнительный вызов увеличивает накладные расходы сервера. В таких случаях редактирование `//MASSMETA EDIT` намного критичны к общей производительности кода. Однако для большинства процедур об этом даже и не нужно беспокоиться. -### Карты 🗺️ +## Карты 🗺️ ⚠️ В нашем репозитории не предполагается держать модульные карты (которые с применением авто-мапперов). Используются карты: -* Оригинальные с офф ТГ (без изменений) -* Заимствованные с других билдов (некоторые желательно не менять, уточните) -* Наши самодельные = полностью независимые (например: ProtoBoxStation) +* 🔴 Оригинальные с офф ТГ (МЫ ИХ НИКАК НЕ МЕНЯЕМ!) +* 🟡 Заимствованные с других билдов (некоторые желательно не менять, т.к. мы можем подтягивать обновления в других билдов, уточните!) +* 🟢 Наши самодельные, они же полностью независимые, например, ProtoBoxStation (меняем и чиним как хотим) Все наши Новые карты лежат по пути **`massmeta/_maps/map_files/`** (не в модульной папке). -К каждой карте идёт дополнительно **`.json`** файл в **`massmeta/_maps/`**, не забудьте добавить его тоже! +К каждой карте идёт дополнительно **`.json`** файл-конфигурации в **`massmeta/_maps/`**, не забудьте добавить его тоже! ## Модульный TGUI (TG User Interface) @@ -279,7 +331,7 @@ var/something = 2 //MASSMETA EDIT ВСЕ файлы TGUI находятся в папке `/tgui/packages/tgui/interfaces/` и ее подкаталогах. Нет какой-то конкретной папки для Наших TGUI файлов! -Пожалуйста, не забудьте записать факт их добавления/изменения под пунктом "TGUI Files:" в **`readme.md`** вашего модуля. +📌 Пожалуйста, не забудьте записать факт их добавления/изменения под пунктом "TGUI Files:" в **`readme.md`** вашего модуля. ### Изменение оригинальных файлов /TG/station @@ -328,9 +380,9 @@ var/something = 2 //MASSMETA EDIT // THIS IS A MASSMETA UI FILE ``` -Таким образом, они легко идентифицируются как модульные файлы TGUI `.tsx` и `.jsx`. +Таким образом, они легко идентифицируются как НАШИ модульные файлы TGUI `.tsx` и `.jsx`. -Собственно ничего больше делать и не нужно, комментарии `// MASSMETA EDIT` в модульном файле TGUI излишне. +Собственно ничего больше делать и не нужно, комментарии `// MASSMETA EDIT` в таком файле TGUI излишне. + -## Module ID: - - +## Module ID: ### Description: - + ### TG Proc/File Changes: - N/A - ### Modular Overrides: - N/A - @@ -28,14 +28,14 @@ E.g: ### Defines: - N/A - + ### TGUI Files: - N/A - + ### Credits: - N/A - + From 25c76ca0925ca9270b4881511e161befa65b51b0 Mon Sep 17 00:00:00 2001 From: unknown Date: Sun, 14 Jul 2024 16:55:15 +0700 Subject: [PATCH 4/8] what . = ..() you meant? --- massmeta/modularization_guide.md | 37 ++++++++++++++++++-------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/massmeta/modularization_guide.md b/massmeta/modularization_guide.md index c989286818409..5e600fe537c58 100644 --- a/massmeta/modularization_guide.md +++ b/massmeta/modularization_guide.md @@ -1,10 +1,10 @@ -# Руководство по модуляризации кода - MassMeta style, v0.3 +# Руководство по модуляризации кода – MassMeta style, v0.3 Соблюдение этого Гайда – залог успешного мержа Вашей фичи в репозиторий. ## Вступление -Проект **МассМета** 🧰 – это, постоянно обновляющаяся, модульная ветка от проекта [/TG/station](https://github.com/tgstation/tgstation). Тут мы добавляем свои фичи и по возможности откатываем неудачные. Прочитав эту инструкцию - Вы поймете как правильно нужно внедрить к нам Вашу идею, чтоб ее могли увидеть в свет другие игроки нашего сервера. +Проект **МассМета** 🧰 – это, постоянно обновляющаяся, модульная ветка от проекта [/TG/station](https://github.com/tgstation/tgstation). Тут мы добавляем свои фичи и по возможности откатываем неудачные. Прочитав эту инструкцию – Вы поймете как правильно нужно внедрить к нам Вашу идею, чтоб ее могли увидеть в свет другие игроки нашего сервера. Несоблюдение данного руководства приведёт к стагнации код-базы проекта, как это было до. Осознав наши прошлые ошибки - было принято решение привести проект к модульности подобно той, как на серверах Skyrat, однако доработанной под наши нужды. [Оригинальное руководство](https://github.com/NovaSector/NovaSector/blob/master/modular_nova/readme.md) (на англ.) @@ -209,10 +209,11 @@ var/something = 2 //MASSMETA EDIT | **code/** 📁 | Файлы кода: **`.dm`** | | **icon/** 📁 | Файлы иконок и картинок: **`.dmi`** и **`.png`** | | **sound/** 📁 | Звуковые файлы: **`.ogg`** и **`.waw`** | -| **string/** 📁 | Файлы строк: **`.txt`** и **`.json`** | | **includes.dm** 📄 | Перечисление всех файлов в папке **code/** | | **readme.md** 📝 | Полная документация к модулю, [пример](module_template.md) | +⚠️ Файлы строк: **`.txt`** и **`.json`** вы помещаете в папку `strings/massmeta/`, т.к. код /TG/station не может работать нормально со всеми файлами-строк вне этой папки. Укажите факт из добавления в **`readme.md`** вашего модуля. + ⛔ У проектов **Skyrat** присуствует папка `master_files/`, однако у нас в проекте её НЕТ! Все переопредения кода у нас помещается полностью в модуль с особыми пометками! Пояснения будут позже. ❗ Также у проектов **Skyrat** стандартно все новые файлы сразу включаются в общий файл **`tgstation.dme`**, что я считаю достаточно трудным для дальнейшней поддрежки, да и в целом это не особо согласуется с их модульным принципом. У нашего проекта другой поход в этом моменте, как Вы видите. @@ -227,7 +228,7 @@ var/something = 2 //MASSMETA EDIT Просто ложите все свои новые файлы кода в папку `code/` своего модуля. -#### Расширение возможностей функций и Переопределение объектов /TG/station 🔀 +#### Переопределение объектов и функций /TG/station 🔀 С помощью этих файлов мы косвенно изменяем основной код /TG/station. Это позволяет нам очень изящно внедрять свои коррективы, не вмешиваясь напрямую в их код. Тем самым не нарушая их череду коммитов и не создавая для нас самих в будущем **Конфликтов Слияния**. @@ -237,7 +238,7 @@ var/something = 2 //MASSMETA EDIT Эти файлы выносите в "отдельную группу" с помощью пометки `"master_"`, например: `master_tg_filename.dm`. -Над каждым блоком таких функций/объектов подписывайте в каком **оригинальном** файле /TG/station эта функция расположена. Таким образом нам будет проще смекнуть что к чему. +Над каждым блоком таких функций/объектов подписывайте в каком **оригинальном** файле /TG/station они расположены. Таким образом нам будет проще смекнуть что к чему. 📌 Пожалуйста, не забудьте записать факт таких переопределений под пунктом "Modular Overrides:" в **`readme.md`** вашего модуля. @@ -277,7 +278,7 @@ var/something = 2 //MASSMETA EDIT Для простоты предположим, что вы хотите заставить оружие искрить при выстреле для имитации дульной вспышки и вы хотите, чтобы это можно было использовать со всеми видами оружия, использующими эту функцию. - В модульном файле объекта можно начать с добавления переменной `var`. + В модульном файле объекта можно начать с добавления новой переменной `var/muzzle_flash`. ```byond /obj/item/gun @@ -286,34 +287,38 @@ var/something = 2 //MASSMETA EDIT Теперь у Вас будет **у каждого** наследника этого объекта доступна эта переменная. После этого, допустим, вы захотите проверить `var` и вызвать искры после выстрела. - Исходная процедура, что вызывается при стрельбе, является: + У этого объекта уже есть процедура, что вызывается при стрельбе: ```byond /obj/item/gun/proc/shoot_live_shot(mob/living/user, pointblank = 0, atom/pbtarget = null, message = 1) ``` - Вы можете переопределить также и дочернюю процедуру /obj/item/gun/shoot_live_shot(), которая будет вставлена в цепочку наследования связанных с ней процедур. + Теперь мы начинаем добавлять код для работы нашей фичи в дочернюю процедуру `/obj/item/gun/shoot_live_shot()`. ```byond /obj/item/gun/shoot_live_shot(mob/living/user, pointblank = 0, atom/pbtarget = null, message = 1) - . = ..() //. is the default return value, we assign what the parent proc returns to it, as we call it before ours + . = ..() if(muzzle_flash) - spawn_sparks(src) //For simplicity, I assume you've already made a proc for this + spawn_sparks(src) ``` + Тут мы обязательно вызываем такую конструкцию `. = ..()`, она по сути своей устанавливает возвращаемое значение текущей функции на возвращаемое значение родительской функции. После данной конструкции добаляем весь наш **Новый** код. Он будет вставлен до всей функции родителя. + Этим мы добились того, что оружие при выстреле ещё и искрит, при том не вмешиваясь в функции /TG/station напрямую! 🎉 -### Общие советы к такому подходу 💡 +### **`. = ..()`** для чайников + +Как вы уже могли заметить, у языка DM заложена парадигма ООП, нас в данном случае интересует процесс наследования объектов и их функций. -Обратите внимание, что можно модульно добавлять код перед или за основной процедурой (proc), не редактируя исходную процедуру, а обращаясь к родительской процедуре с помощью `. = ..()` или `..()`. Аналогичным образом можно добавить новый var к существующему datum или obj, не редактируя напрямую файлы офф ТГ, как это было показано в примерах выше. +- `.` – это возвращаемое значение нашей функции по умолчанию. Изначально оно равно `null`. -Например НЕ стоит: вставлять всю TG-процедуру в модульную переопределённую процедуру, внести всего одно небольшое изменение, а затем объявить её "полностью модульной". Эти процедуры - абсолютный кошмар для поддержки, потому что как только что-то изменится, вам придется обновлять переопределенную процедуру. + Через это можно обращаться к нашей же функции через `.()`, например, для реализации рекурсии. -Иногда вы даже не будете догадываться, что до вас вообще в другом модуле уже внедрили подобное переопределение, а оно ведь компилируется без ошибок! Это часто приводит к непониманию того и из-за чего у Вас всё ломается. +- `..` – это родительская функция. -Лучшими кандидатами для модульных переопределений процедур являются те, в которые вы можете просто добавить что-то после вызова родителя или ловко вплести вызов родителя в середину, чтобы достичь желаемого эффекта. + Через `..()` Вы обращаетесь к родительской функции, этим вызывая её в нужном месте Вашей функции-наследника. -Производительность также следует учитывать, когда вы переопределяете горячую (часто вызываемую) процедуру (например, Life()), поскольку каждый дополнительный вызов увеличивает накладные расходы сервера. В таких случаях редактирование `//MASSMETA EDIT` намного критичны к общей производительности кода. Однако для большинства процедур об этом даже и не нужно беспокоиться. + Однако, если вы сделаетете подобый манёвр `. = ..()`, то вызов родителя будет произведен только когда наша функция завершит свою работу. ## Карты 🗺️ From 4d04a29c1515c484a1b50d265f154f838f7e0121 Mon Sep 17 00:00:00 2001 From: unknown Date: Sun, 14 Jul 2024 18:35:03 +0700 Subject: [PATCH 5/8] removed extra info --- massmeta/modularization_guide.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/massmeta/modularization_guide.md b/massmeta/modularization_guide.md index 5e600fe537c58..6a86b8a16dec4 100644 --- a/massmeta/modularization_guide.md +++ b/massmeta/modularization_guide.md @@ -312,13 +312,11 @@ var/something = 2 //MASSMETA EDIT - `.` – это возвращаемое значение нашей функции по умолчанию. Изначально оно равно `null`. - Через это можно обращаться к нашей же функции через `.()`, например, для реализации рекурсии. - - `..` – это родительская функция. Через `..()` Вы обращаетесь к родительской функции, этим вызывая её в нужном месте Вашей функции-наследника. - Однако, если вы сделаетете подобый манёвр `. = ..()`, то вызов родителя будет произведен только когда наша функция завершит свою работу. +И теперь, если вы сделаетете подобый манёвр `. = ..()`, то вызов родителя будет произведен только когда наша функция завершит свою работу. ## Карты 🗺️ From 4fc846183e8e940a794204989a5da2e7fc63ef51 Mon Sep 17 00:00:00 2001 From: unknown Date: Sun, 14 Jul 2024 18:50:41 +0700 Subject: [PATCH 6/8] lil fix --- massmeta/modularization_guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/massmeta/modularization_guide.md b/massmeta/modularization_guide.md index 6a86b8a16dec4..84c452629e3a0 100644 --- a/massmeta/modularization_guide.md +++ b/massmeta/modularization_guide.md @@ -312,7 +312,7 @@ var/something = 2 //MASSMETA EDIT - `.` – это возвращаемое значение нашей функции по умолчанию. Изначально оно равно `null`. -- `..` – это родительская функция. +- `..` – это возвращаемое значение родительской функции. Через `..()` Вы обращаетесь к родительской функции, этим вызывая её в нужном месте Вашей функции-наследника. @@ -320,7 +320,7 @@ var/something = 2 //MASSMETA EDIT ## Карты 🗺️ -⚠️ В нашем репозитории не предполагается держать модульные карты (которые с применением авто-мапперов). +⚠️ В нашем репозитории пока не предполагается держать модульные карты (которые с применением авто-мапперов). Используются карты: * 🔴 Оригинальные с офф ТГ (МЫ ИХ НИКАК НЕ МЕНЯЕМ!) From 12981474001d7e330442146d411265d5a82f5af6 Mon Sep 17 00:00:00 2001 From: unknown Date: Tue, 16 Jul 2024 23:26:22 +0700 Subject: [PATCH 7/8] lil fix --- massmeta/modularization_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/massmeta/modularization_guide.md b/massmeta/modularization_guide.md index 84c452629e3a0..98766b66486d7 100644 --- a/massmeta/modularization_guide.md +++ b/massmeta/modularization_guide.md @@ -316,7 +316,7 @@ var/something = 2 //MASSMETA EDIT Через `..()` Вы обращаетесь к родительской функции, этим вызывая её в нужном месте Вашей функции-наследника. -И теперь, если вы сделаетете подобый манёвр `. = ..()`, то вызов родителя будет произведен только когда наша функция завершит свою работу. +И теперь, если вы сделаетете подобый манёвр `. = ..()`, то Вы вызовите родительскую функцию. ## Карты 🗺️ From e9462817057155dbc86e0ca2b1a977f2694c4961 Mon Sep 17 00:00:00 2001 From: unknown Date: Thu, 18 Jul 2024 17:26:58 +0700 Subject: [PATCH 8/8] about . = ..() and Maps - done --- massmeta/modularization_guide.md | 106 ++++++++++++++++++++----------- massmeta/module_template.md | 4 +- 2 files changed, 71 insertions(+), 39 deletions(-) diff --git a/massmeta/modularization_guide.md b/massmeta/modularization_guide.md index 98766b66486d7..a41c7f99387cc 100644 --- a/massmeta/modularization_guide.md +++ b/massmeta/modularization_guide.md @@ -1,6 +1,6 @@ # Руководство по модуляризации кода – MassMeta style, v0.3 -Соблюдение этого Гайда – залог успешного мержа Вашей фичи в репозиторий. +**Соблюдение этого Гайда – залог успешного мержа Вашей фичи в репозиторий.** ## Вступление @@ -30,20 +30,20 @@ Начнём сразу с показательного примера. -Предположим в оригинальном файле **`foobar.dm`** в каталоге /TG/station было так: +Предположим, что в какой-то строчке оригинального файла **`foobar.dm`** /TG/station было так: ```byond var/something = 1 ``` -И тут нам потребовалось изменить значение с **1** на **2** под нашу фичу в проекте, +Однако, под наши нужны нам потребовалось изменить значение с **1** на **2** под какую-то фичу в проекте, ```diff - var/something = 1 + var/something = 2 //MASSMETA EDIT ``` -Но внезапно наш доблестный ТГ К*дер вносит свои изменения (commit: their-feature) в основную код-базу, меняя её у себя с **1** на **4**, +Но неожиданно апстрим /TG/station вносит свои изменения (commit: their-feature) в эту же строку файла, меняя её у себя с **1** на **4**, ```diff - var/something = 1 @@ -61,7 +61,7 @@ var/something = 4 В данном случае в череду коммитов /TG/station внедряется дополнительный, про который известно только нам самим. ГитХаб, видя подобное несоответствие - даёт нам сделать выбор. -Например, нам нужно оставить только Наше изменение, то просто удаляем все что нам добавил гит и оставляем только нужное, +Например, нам нужно оставить только Наше изменение, то просто удаляем все что нам добавил ГитХаб и оставляем только нужное, ```byond var/something = 2 //MASSMETA EDIT @@ -73,7 +73,7 @@ var/something = 2 //MASSMETA EDIT ## Протокол модуляризации 🛠️ -У Вашего модуля должно быть короткое и информативное название в документации, например - `SHUTTLE_TOGGLE`. +У Вашего модуля должно быть короткое и информативное название в документации, например - **`shuttle_toggle`**. Этим уникальным **ID** Вы затем назовёте: @@ -87,7 +87,7 @@ var/something = 2 //MASSMETA EDIT Время от времени наступает момент, когда редактирование **оригинальных** файлов /TG/station становится неизбежным. -Пожалуйста, не забудьте записать факт их изменения под пунктом "TG Proc/File Changes" в **`readme.md`** вашего модуля. +📌 Пожалуйста, не забудьте записать факт их изменения под пунктом **"Original TG Changes"** в **`readme.md`** вашего модуля. В этих случаях мы решили применять следующую стандартизацию: @@ -135,20 +135,20 @@ var/something = 2 //MASSMETA EDIT 💡 Она полностью независима и этим мы гарантируем, что кодеры с /TG/station не будут туда вмешиваться. -В этой папке есть еще несколько подпапок и файлов: +В этой папке есть ещё несколько подпапок и файлов: | Папка/Файл | | ------------------------------- | -| **~meta_defines/** 📂 | -| **features/** 📂 | -| **reverts/** 📂 | -| **tools/** 📂 | +| **~meta_defines/** 📂 | +| **features/** 📂 | +| **reverts/** 📂 | +| **tools/** 📂 | | **modular_meta_defines.dm** 📄 | | **modular_meta_features.dm** 📄 | | **modular_meta_reverts.dm** 📄 | -| **modularization_guide.md** 📝 | -| **module_template.md** 📝 | -| **readme.md** 📝 | +| **modularization_guide.md** 📝 | +| **module_template.md** 📝 | +| **readme.md** 📝 | Теперь подробнее про каждую из Папок: @@ -168,7 +168,7 @@ var/something = 2 //MASSMETA EDIT #undef MY_DEFINE ``` - 📌 Пожалуйста, не забудьте записать факт их добавления под пунктом "Defines:" в **`readme.md`** вашего модуля. + 📌 Пожалуйста, не забудьте записать факт их добавления под пунктом **"Defines:"** в **`readme.md`** вашего модуля. Все файлы в папке включены в **`modular_meta/modular_meta_defines.dm`**. @@ -182,9 +182,11 @@ var/something = 2 //MASSMETA EDIT - **`reverts/`** 📂 - Папка аналогичная `features/`, но там располагаются откаты плохих по нашему мнению фич, введёных апстримом /TG/station. + Папка аналогичная `features/`, но там располагаются недавние откаты плохих и возвраты хороших по нашему мнению фич, введёных апстримом /TG/station. + + ❗ Если фича была уже выпилена давно или же апстрим произвел её полное удаление сразу, то она уже может рассматриваться как самостоятельный модуль. Такое помещаем её уже в папку `features/`! - Такой модуль именовать уже обязательно с припиской "revert", например вот так: **revert_module_id**. + Такой модуль именовать уже обязательно с припиской **"revert_"**, например вот так: **revert_module_id**. ⚠️ Обязательно укажите в файле **`readme.md`** модуля ссылку на пиар, который откатываевается! @@ -228,19 +230,23 @@ var/something = 2 //MASSMETA EDIT Просто ложите все свои новые файлы кода в папку `code/` своего модуля. +💡 Можете разбивать Ваш под по подпапкам, если в этом есть нужда. + +Не забывайте проставлять все ваши пути к иконкам и звуку правильно! + #### Переопределение объектов и функций /TG/station 🔀 -С помощью этих файлов мы косвенно изменяем основной код /TG/station. Это позволяет нам очень изящно внедрять свои коррективы, не вмешиваясь напрямую в их код. Тем самым не нарушая их череду коммитов и не создавая для нас самих в будущем **Конфликтов Слияния**. +С помощью этих файлов мы косвенно изменяем основной код /TG/station. Это позволяет нам очень изящно внедрять свои коррективы, не вмешиваясь напрямую в основной код. Тем самым не нарушая их череду коммитов и не создавая для нас самих в будущем **Конфликтов Слияния**. -Однако это является и минусом такого подхода. Гитхаб не сможет нам оперативно подсказать где файл поменялся ещё и следует учесть измененое или дополнительное переопределение. Иногда прямые изменения кода через `//MASSMETA EDIT` предпочтительнее. Просто постарайтесь использовать здравый смысл в этом вопросе. +Однако это является и минусом такого подхода. Гитхаб не сможет нам оперативно подсказать где файл поменялся из-за вмешательства апстрима и где следует учесть измененое или дополнительное переопределение. Иногда прямые изменения кода через `//MASSMETA EDIT` предпочтительнее. Старайтесь использовать здравый смысл в этом вопросе. ⚠️ У данных файлов **Не надо соблюдать Иерархию** аналогичной папки `code/` у /TG/station! Просто ложите вместе со всеми файлами в модуль. Эти файлы выносите в "отдельную группу" с помощью пометки `"master_"`, например: `master_tg_filename.dm`. -Над каждым блоком таких функций/объектов подписывайте в каком **оригинальном** файле /TG/station они расположены. Таким образом нам будет проще смекнуть что к чему. +⚠️ Над каждым блоком таких функций/объектов **подписывайте в каком оригинальном файле /TG/station они расположены**. Таким образом нам будет проще смекнуть что к чему. -📌 Пожалуйста, не забудьте записать факт таких переопределений под пунктом "Modular Overrides:" в **`readme.md`** вашего модуля. +📌 Пожалуйста, не забудьте записать факт таких переопределений под пунктом **"Modular Overrides:"** в **`readme.md`** вашего модуля. - **Пример модульного переопределения объекта** 💡 @@ -260,7 +266,7 @@ var/something = 2 //MASSMETA EDIT var/obj/item/canvas/painting = null ``` - Для этого создайте новый файл желательно с таким же именем как у оригинала и расположите в папке `code/` вашего модуля: `massmeta/features/art/code/master_paintings.dm`. + Для этого создайте новый файл желательно с таким же именем как у оригинала и расположите в папке `code/` вашего модуля: `code/master_paintings.dm`. Для выполнения нашей цели, наполнение даного файла будет выглядеть примерно так: @@ -272,11 +278,13 @@ var/something = 2 //MASSMETA EDIT icon_state = "new_easel" ``` - Теперь у вашего мольберта уже Новая иконка и описание. Даже код /TG/station менять не пришлось! 🎉 + Теперь при компилировании проекта, данное переопределение подменит эти переменные у оригинального объекта мольберта. Тем самым в готовом проекте у мольберта будет уже Новая иконка и описание. Даже код /TG/station менять не пришлось! 🎉 -- **Пример модульного добавления фич в функции** 💡 +- **Пример модульного добавления фичи в функцию** 💡 - Для простоты предположим, что вы хотите заставить оружие искрить при выстреле для имитации дульной вспышки и вы хотите, чтобы это можно было использовать со всеми видами оружия, использующими эту функцию. + Для простоты предположим, что вы хотите заставить оружие искрить при выстреле для имитации дульной вспышки. + + Также Вы хотите, чтобы это можно было использовать со всеми видами оружия, использующими эту функцию. В модульном файле объекта можно начать с добавления новой переменной `var/muzzle_flash`. @@ -285,7 +293,7 @@ var/something = 2 //MASSMETA EDIT var/muzzle_flash = TRUE ``` - Теперь у Вас будет **у каждого** наследника этого объекта доступна эта переменная. После этого, допустим, вы захотите проверить `var` и вызвать искры после выстрела. + Теперь у Вас будет **у каждого** наследника этого объекта доступна эта переменная. После этого, допустим, вы захотите проверять её и вызвать искры после выстрела. У этого объекта уже есть процедура, что вызывается при стрельбе: @@ -293,7 +301,7 @@ var/something = 2 //MASSMETA EDIT /obj/item/gun/proc/shoot_live_shot(mob/living/user, pointblank = 0, atom/pbtarget = null, message = 1) ``` - Теперь мы начинаем добавлять код для работы нашей фичи в дочернюю процедуру `/obj/item/gun/shoot_live_shot()`. + Теперь мы начинаем **добавлять код** для работы нашей фичи в дочернюю процедуру `/obj/item/gun/shoot_live_shot()`. ```byond /obj/item/gun/shoot_live_shot(mob/living/user, pointblank = 0, atom/pbtarget = null, message = 1) @@ -302,13 +310,15 @@ var/something = 2 //MASSMETA EDIT spawn_sparks(src) ``` - Тут мы обязательно вызываем такую конструкцию `. = ..()`, она по сути своей устанавливает возвращаемое значение текущей функции на возвращаемое значение родительской функции. После данной конструкции добаляем весь наш **Новый** код. Он будет вставлен до всей функции родителя. + Тут мы обязательно вызываем такую конструкцию **`. = ..()`**, она по сути своей говорит, что мы наследуемся от родительской функции. После данной конструкции добаляем весь наш **Новый** код. - Этим мы добились того, что оружие при выстреле ещё и искрит, при том не вмешиваясь в функции /TG/station напрямую! 🎉 + Теперь при компилировании проекта, данные "добавления" допишутся в оригинальный объект и функцию. Этим мы добились того, что оружие при выстреле ещё и искрит, при том не вмешиваясь в функции /TG/station напрямую! 🎉 ### **`. = ..()`** для чайников -Как вы уже могли заметить, у языка DM заложена парадигма ООП, нас в данном случае интересует процесс наследования объектов и их функций. +Как вы уже могли заметить, у языка DM частично заложена парадигма ООП, нас в данном случае интересует процесс наследования объектов и их функций. + +💡 Вы также можете нажать F1 в Dream Maker и прочитать подробный мануал на английском. - `.` – это возвращаемое значение нашей функции по умолчанию. Изначально оно равно `null`. @@ -316,28 +326,48 @@ var/something = 2 //MASSMETA EDIT Через `..()` Вы обращаетесь к родительской функции, этим вызывая её в нужном месте Вашей функции-наследника. -И теперь, если вы сделаетете подобый манёвр `. = ..()`, то Вы вызовите родительскую функцию. +И теперь, если вы сделаетете подобый манёвр `. = ..()`, то Вы вызовите родительскую функцию и присвоите её значение возвращаемому значению нашей функции. После этого можете свободно дополнять свою `.` чем хотите. + +Так же в случае, если Вы не хотите возвращать родительский вывод, то Вы можете сохранить его в любую переменную или просто использовать `..()` + +Мы так же можем вообще не вызывать `..()` - тогда функция оверрайдится полностью. Но я бы не рекомендовал делать подобное, ради перемещения ориг. функции в модуль и дальнейшей модификации её уже там, ибо когда /TG/station поменяет её у себя, то пиши пропало. + +Также учтите, что вы не сможете при модульном дополнии функции использовать те переменные, которые были объявленны в функции оригинале! ## Карты 🗺️ -⚠️ В нашем репозитории пока не предполагается держать модульные карты (которые с применением авто-мапперов). +### Не Модульное Изменение Карт Используются карты: -* 🔴 Оригинальные с офф ТГ (МЫ ИХ НИКАК НЕ МЕНЯЕМ!) -* 🟡 Заимствованные с других билдов (некоторые желательно не менять, т.к. мы можем подтягивать обновления в других билдов, уточните!) +* 🔴 Оригинальные с офф ТГ (без прямых наших изменений) +* 🟡 Заимствованные с других билдов (некоторые желательно не менять, т.к. мы можем подтягивать обновления в других билдов) * 🟢 Наши самодельные, они же полностью независимые, например, ProtoBoxStation (меняем и чиним как хотим) Все наши Новые карты лежат по пути **`massmeta/_maps/map_files/`** (не в модульной папке). К каждой карте идёт дополнительно **`.json`** файл-конфигурации в **`massmeta/_maps/`**, не забудьте добавить его тоже! +### Модульное Изменение Карт (Авто-мапперы) + +⚠️ Не изменяйте оригинальные карты /TG/station напрямую, Вы стокнётесь потом с таким же хаосом, как если вы бы меняли файлы иконок! Для внесения изменений ипользуйте способы ниже. + +Когда вы добавляете новый элемент на карту, то вы должны сперва определеить масштаб переделок. + +- Если это **небольшое изменение на 1 предмет**, то используйте простой автоматизатор области. + + Автомаппер простых областей использует записи точек отсчета, чтобы поместить один элемент в область карты, которая имеет определенный смысл. + +- Если речь идет об **изменении целой комнаты**, то используйте автоматизатор шаблонов. + + Автомаппер использует готовые шаблоны для переопределения участков карты, используя координаты для определения начального местоположения. Примеры смотрите в файле automapper_config.toml. + ## Модульный TGUI (TG User Interface) **TGUI** - еще один исключительный случай, поскольку он использует Javascript, который не может быть модульным, нежели же код DM. ВСЕ файлы TGUI находятся в папке `/tgui/packages/tgui/interfaces/` и ее подкаталогах. Нет какой-то конкретной папки для Наших TGUI файлов! -📌 Пожалуйста, не забудьте записать факт их добавления/изменения под пунктом "TGUI Files:" в **`readme.md`** вашего модуля. +📌 Пожалуйста, не забудьте записать факт их добавления/изменения под пунктом **"TGUI Files:"** в **`readme.md`** вашего модуля. ### Изменение оригинальных файлов /TG/station @@ -402,4 +432,6 @@ Here are a couple PR's that are great examples of the guide being followed, refe Терпение и труд – ТГ к*дера перетрут. Если мы будем последовательны, то в конечном итоге это избавит НАС от будущих болей в области ГМ, когда Нам (Вам) же придется разрешать конфликты вручную. Благодаря более скрупулезному документированию будет сразу понятно, какие изменения были сделаны, где и с помощью каких функций, и все станет гораздо менее двусмысленным и запутанным. -Желаю удачи в ТГ к*динге. Помните, что сообщество всегда готово помочь вам, если вдруг понадобится помощь. +Желаю удачи в ТГ кодинге. Помните, что сообщество всегда готово помочь Вам, если вдруг понадобится помощь. + +Оригинальное руководство: Skyrat/NovaSector. Перевод + дополнения: Artemchik542. Рецензент текста: SmArtKar. diff --git a/massmeta/module_template.md b/massmeta/module_template.md index cf16182e9afd0..28c7491a4beae 100644 --- a/massmeta/module_template.md +++ b/massmeta/module_template.md @@ -8,7 +8,7 @@ Если Вы делаете модуль Реверта фичи, то обязательно укажте ссылку на оригинальный пиар /TG/station, который вы вернули. --> -### TG Proc/File Changes: +### Original TG Changes: - N/A + ### Credits: