update scripting docs

doc/ru/scripting.md

@@ -60,6 +60,58 @@
 - quat - массив из четырех чисел - кватернион
 - matrix - массив из 16 чисел - матрица
 
+## Пространства имён
+
+В настоящее время, движок использует иерархию пространств имён, минимизирующую конфликты между отдельными модулями, скриптами, да и паками.
+
+Актуальна следующая структура:
+
+- Глобальное пространство (оно же - _G), являющееся корневым, запись в которое, вне модулей ядра движка, является крайне нежелательным для вашего же времени, что может уйти на лишние часы отладки.
+    - Пространство пака - создаётся каждый раз при загрузке контента для каждого, включённого в конфигурацию, пака. Это пространство используют модули, а также скрипты предметов и блоков.
+        - Пространство [компонента](scripting/ecs.md#пользовательские-компоненты).
+        - Пространство [UI-документа](scripting/ui.md)
+- Изолированное пространство имён генератора мира.
+
+## Модули
+
+Модуль - глобальный объект со сроком жизни, ограниченным сроком жизни контента, используемый как для взаимодействия разных паков, так и для вместо глобальных переменных в пределах самого пака. 
+
+Модуль должен находиться в `контентпак/modules/**` (допускаются вложенные папки, что нужно будет указывать)
+
 ```lua
-require "контентпак:имя_модуля" -- загружает lua модуль из папки modules (расширение не указывается)
+local имя_модуля = require "контентпак:имя_модуля" -- импортирует модуль
+
+-- если модуль находится в том же паке, в котором импортируется, можно использовать сокращённый вариант:
+local имя_модуля = require "имя_модуля"
+
+-- при использовании вложенных папок:
+local имя_модуля = require "контентпак:путь/к/имя_модуля" -- путь не включает `modules`
+local имя_модуля = require "путь/к/имя_модуля" -- если в том же паке
 ```
+
+Модуль будет иметь пространство имён того пака, в котором находится, независимо от пространства имён, из которого был выполнен первый импорт.
+
+При создании модуля следует придерживаться следующего подхода, которого и ожидает *require*:
+
+```lua
+local this = {
+    имя_переменной = ... -- публичные переменные
+}
+
+-- приватные переменные модуля
+local имя_переменной = ...
+
+-- приватные функции модуля
+local function имя_функции(...)
+    ...
+end
+
+-- публичные функции модуля
+function this.имя_функции(...)
+    ...
+end
+
+return this -- результат, который и будет возвращать и кешировать require
+```
+
+При повторном импорте модуль не будет перезагружен - вместо этого require вернёт кешированный результат.