A_Recruiter_Tale_sources/NAMING_CONVENTIONS.md

Правила структуры и нейминга ART

Последнее обновление: 2026-07-21.

Этот документ описывает, как хранить исходники и готовые 3D-ассеты проекта. Главная цель — по одному имени сразу понимать, что это за файл, к какому ассету он относится и является ли он рабочим исходником или готовым результатом.

1. Структура корня

ART/
├── 0_assets/
│   ├── BigMapParts/         # крупные части карты; как в Content Browser
│   ├── Characters/          # персонажи, их анимации и исходники
│   ├── Interior/            # интерьер, пропсы, материалы, AiAssets
│   └── Landscape/           # растительность и ландшафтные ассеты
├── 1_references/            # PureRef-доски, концепты и отдельные референсы
├── 9_misc/                  # редкие служебные материалы, которым пока нет категории
└── NAMING_CONVENTIONS.md

Папки unsorted, temp, new, 123 и похожие не используются. Новый материал сразу кладётся в папку своего ассета. Если назначение пока не ясно, допустима временная папка _inbox внутри подходящего UE-корня, например Interior/_inbox, но её нужно разобрать до следующего коммита.

Имена и регистр папок первого уровня повторяют /Game/Recruiter/3dAssets в Unreal. Нельзя возвращать абстрактные корни 0_characters, 1_indoor, props или environment. Общие ретаргет-исходники лежат в Characters/_shared/0_source, а не в отдельном корне 2_anims.

2. Структура одного ассета

asset_id/
├── 0_source/                # редактируемые исходники и промежуточные данные
│   ├── asset_id.blend
│   ├── asset_id.spp
│   ├── bake/                # bake-сцены, high-poly, служебные карты
│   └── legacy/              # только действительно нужные старые ветки
├── SM_asset_id.fbx          # готовая статическая сетка
├── T_asset_id_D.png         # Base Color
├── T_asset_id_N.png         # Normal
└── T_asset_id_ORM.png       # Occlusion / Roughness / Metallic

Готовые файлы, которые импортируются в Unreal, лежат в корне ассета. Blender, Substance Painter/Designer, ZBrush, Marmoset, PSD, high-poly и bake-файлы лежат только в 0_source.

Adopt аддона намеренно видит только файлы с точным префиксом SM_ вне исходных каталогов. Любой SM_*.fbx внутри 0_source, legacy, old, backup, bake, highpoly, sculpt, anims — ошибка структуры: готовый меш нужно вынести наружу, промежуточный — переименовать без SM_. Операция Move asset переносит управляемый ассет в точное зеркало его ue_path.

Если один исходник обслуживает несколько ассетов, создаётся понятная общая папка, например puzzle_books/0_source или _shared/0_source. Не нужно копировать один и тот же исходник в каждую папку.

3. Общий формат имён

• Используется английский язык и ASCII.
• Папки и идентификаторы ассетов пишутся в lower_snake_case: barrel_a, stone_floor_a, lighting_set_a. Исключение — существующие папки Content Browser (BigMapParts, Characters, Interior, Landscape, AiAssets, Beams и т. п.): их регистр повторяется точно.
• Пробелы, кириллица, амперсанды, скобки и случайные хеши в рабочих именах запрещены.
• Расширения файлов пишутся в нижнем регистре: .fbx, .png, .blend, .spp.
• Имя должно описывать содержимое, а не историю работы. Вместо final2_new_fixed — каноническое имя ассета; историю хранит Git.
• Суффикс _wip допустим только для явно незавершённого ассета. Суффиксы _final, _new, _old, _copy, _tmp, _123 не используются.

4. Префиксы готовых файлов

Тип	Формат	Пример
Static Mesh	SM_<asset_id>	SM_barrel_a.fbx
Skeletal Mesh	SK_<asset_id>	SK_kidri.fbx
Animation	A_<character>_<action>	A_death_idle.fbx
Texture	T_<asset_id>_<map>	T_barrel_a_N.png
Material	M_<asset_id>	M_barrel_a
Material Instance	MI_<asset_id>	MI_barrel_a

Префикс пишется прописными буквами, идентификатор после него — в lower_snake_case.

5. Суффиксы текстур

Суффикс	Значение
_D	Base Color / Diffuse
_N	Normal
_ORM	R: Ambient Occlusion, G: Roughness, B: Metallic
_H	Height / Displacement
_A	Alpha / Opacity
_E	Emissive
_M	Mask
_R	Roughness, если она хранится отдельно

Нельзя смешивать варианты вроде _BaseColor, _albedo, _diff и _D в одном проекте: канонический вариант здесь — _D.

6. Варианты, серии и части

• Художественный вариант: _a, _b, _c — SM_window_a.fbx.
• Нумерованная серия: _01, _02, _03 — SM_fresco_part_01.fbx.
• Состояние ассета: _opened, _closed, _damaged — только когда это отдельный игровой вариант.
• LOD: _LOD0, _LOD1, _LOD2 — только для явно экспортируемых отдельных LOD.
• Для набора с общим атласом используется короткое семейство: candle_set_a, chair_tableware_set_a, lighting_set_a.

Числа без смысла (_1, _123) не добавляются. Если число является частью дизайна, формат и разрядность должны быть одинаковыми во всей серии.

7. Исходники и версии

• Главный редактируемый файл называется по ассету: door_a.blend, window.spp.
• Временные этапы не дублируются рядом с главным файлом. Если старую ветку действительно нужно сохранить, она переносится в 0_source/legacy и получает осмысленное имя.
• .blend1, .painter_lock, каталоги .autosave и файлы *_autosave_N.* не коммитятся как постоянные версии.
• Если автосейв новее основного файла, его сначала нужно открыть и сохранить под каноническим именем, а затем удалить автосейв.
• Архив .zip/.rar удаляется после проверки, что его содержимое уже распаковано и хранится в Git.
• История изменений хранится в Git, а не в копиях old, copy, final_final.

8. Дубликаты и конфликты

1. Совпадение имени — сигнал проверить версии, но не доказательство дубликата.
2. Сначала сравниваются назначение, размер и дата изменения, затем при необходимости SHA-256.
3. Для одного канонического результата остаётся более новая рабочая версия; старая удаляется.
4. Уникальный исходник не удаляется только потому, что рядом есть готовый FBX или PNG: он переносится в 0_source.
5. Один и тот же файл не хранится одновременно в архиве, 0_source и корне ассета.

9. Исключения для связанных пакетов

Нельзя массово переименовывать внутренности следующих каталогов без открытия проекта в родной программе:

• *.resources и .autosave у Substance Designer;
• сторонние библиотеки в Helpers;
• FBX-sidecar-каталоги *.fbm;
• .uasset и их внутреннюю иерархию — такие пакеты переименовываются и перемещаются только через Unreal Editor.

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

10. Чек-лист нового ассета

1. Создать папку <ue_folder>/<asset_id>, где <ue_folder> совпадает с Content Browser.
2. Создать в ней 0_source.
3. Сохранить редактируемый мастер в 0_source/<asset_id>.<ext>.
4. Экспортировать готовые сетки и текстуры в корень ассета с префиксами SM_/SK_/A_/T_.
5. Удалить автосейвы, lock-файлы, распакованные архивы и временные копии.
6. Перед коммитом проверить git status и убедиться, что unsorted не появился снова.