.:--.-+**+++=-:.
-=*#%%=-#%%%%%%%%%%%#*=:
-*%%%%%#:+%%%%%%%%%%%%%%%%%#+:
.=#%%%%%%*:#%%%%%%%%%##***+++***#*-
-#%%%%%%%+:#%%#*+=-:..:=*********+==-.
:%%%%%%%%*.#+-:. :=++= :=#%%%%%%%%%%-
*.#%%%%%%#.:-=*=*= *#=: .=+=-:+#%%%%%%%%=
+%=-%%%%%%::*%#:+*- : *%%%%#- -*%%%%%%%-
:%%%:+%%%%=-%%%%%#+= .-**#%**%%+.=:+%%%%%#
+%%%#:+%%#.%%%#*: .*++---+%%%:=#=:*%%%%-
*%%%%#:+%+ +#:.. .#%%%%%%#*%#:.%%#=-#%%=
*%%%%%%--= .:--+=: .*%%%%%%%#*: .%%%%*:*%=
=%%%%%%%*. .%%%%#=- :%%%%#: :%%%%%#:*:
.#%%%%%%%#- :*%%%%= *%%%-: +%%%%%%#.
:#%%%%%%%%+. %%#: =%#-::=.#%%%%%%#.
===*#%%%%#=. **. . -#-=%%%%%%#:
:##*+======+=:.- .....:::::=#%*.#%%%%%*.
=#%%%%%%#**++===-==- :=#%%%#.+%%%%#=
.=#%%%%%%%%%%%#+=-+#%%%%%%-=%%%#=.
:+#%%%%*+===*%%%%%%%%%-=%#+:
.:.:+#%%%%%%%%%%%#::-.
.:-----::.
ApertureMapsLib — coremod-библиотека для Forge 1.12.2, которая делает большие прямоугольные (не квадратные) текстуры безопасными и валидными для загрузки в ванильном атласе, также (опционально) чинит несколько едж-кейсов CTM (ConnectedTexturesMod) для паттерн-текстур.
Если вы делаете обои/плитку/панели/узоры, где одна текстура покрывает много блоков (например 7x4, 20x12 тайлов и т.д.), то без специальных мер Minecraft 1.12.2 может:
- выбрасывать исключение при ститчинге атласа (
TextureAtlasSprite):broken aspect ratio and not an animation; - «обрезать» её в атласе: часть вашей текстуры визуально заменяется соседними спрайтами;
- давать мусор/швы на границах при CTM-рендере из-за UV/float погрешностей.
Эта библиотека решает именно такие случаи и подключается без API: включение делается на уровне текстуры через .png.mcmeta.
Если вы строите карту с модом LittleTiles рисуя паттерны текстур с помощью мода, или делаете собственные нестандартные текстуры для блоков, то этот мод-библиотека будет вам полезен.
- Minecraft:
1.12.2 - Forge:
14.23.x(рекомендуется) - Java:
8
Библиотека может работать и с CTM, и без него:
- С CTM: дополнительно применяются патчи к UV-математике CTM для больших паттернов.
- Без CTM: работают только патчи атласа/спрайтов.
По умолчанию CTM считается обязательной зависимостью (но это можно выключить в конфиге). Я добавил эту возможность, если по какой-то причине CTM вам не нужен.
- Положите
ApertureMapsLib*.jarвmods/. - (Рекомендуется) Положите CTM в
mods/.
Библиотека не требует никаких вызовов из кода: она сама читает .mcmeta рядом с текстурами и применяет патчи.
ApertureMapsLib включается точечно: для каждой конкретной текстуры, где вы хотите разрешить не-квадратность и включить безопасный режим атласа.
Для этого рядом с PNG создаётся файл .png.mcmeta и в нём добавляется секция aperturemapslib.
Майнкрафт для каждого спрайта хранит iconName в виде:
modid:blocks/texture_namemodid:items/texture_name- и т.п.
Если iconName = modid:blocks/example, то библиотека будет искать:
assets/modid/textures/blocks/example.png.mcmeta
Важно:
.mcmetaдолжен попасть в jar вашего мода.- JSON читается как UTF-8.
Поддерживаются два формата.
Самый простой вариант: включить библиотеку со стандартными настройками.
{
"aperturemapslib": true
}Пример с ConnectedTexturesMod (CTM) Патерн 10×5 блоков
{
"ctm": {
"ctm_version": 1,
"type": "pattern",
"extra": {
"width": 10,
"height": 5
}
},
"aperturemapslib": {
"enabled": true
}
}Эквивалентно:
enabled=truesquare_reserve=trueguard=true
{
"aperturemapslib": {
"enabled": true,
"square_reserve": true,
"guard": true
}
}Примечания:
enabledпо умолчаниюtrue.square_reserveпо умолчаниюtrue.- Также принимается алиас
square.
- Также принимается алиас
guardпо умолчаниюtrue.
square_reserve=falseвыключает резервирование квадрата в атласе.- Это экономит место, но для больших прямоугольных паттернов почти всегда возвращает баги (обрезка/перекрытие).
guard=falseразрешает ванильному ститчеру применять проблемные пути (поворот/скейл) для этой текстуры.- Обычно нужно только для экспериментов.
Если вы не уверены — используйте просто "aperturemapslib": true.
ApertureMapsLib — это coremod и патчит несколько мест в рантайме.
В 1.12.2 есть ванильная проверка, которая выбрасывает исключение с текстом:
broken aspect ratio and not an animation
Библиотека:
- оставляет ванильное поведение для обычных текстур;
- для managed-текстур (где
.mcmetaсодержитaperturemapslib) отключает это.
Без этого ванильная проверка часто приводит к падению перезагрузки ресурсов на этапе сборки (stitch) атласа (или к missingno, если исключение где-то перехватили).
Самая неприятная проблема: Minecraft пакует все спрайты в один большой атлас через Stitcher. При определённом наборе модов/текстур и размерах атласа прямоугольный спрайт может:
- быть повернутым/скейленным;
- или получить ситуацию, когда «свободная область» рядом с ним заполняется чужими спрайтами, из-за чего в игре вы видите, будто ваш спрайт частично заменён чужими текстурами.
ApertureMapsLib лечит это двумя механизмами.
Square reservation (square_reserve)
- Для managed-спрайта в атласе резервируется квадрат
SxS, гдеS = max(width, height). - Реальная текстура занимает только часть этого квадрата, а остальное остаётся пустым.
- Благодаря этому другие спрайты не смогут «залезть» в область, которая визуально принадлежит вашему паттерну.
Guard (guard)
- Для managed-спрайтов отключаются проблемные пути ститчера (поворот/скейл), которые чаще всего и приводят к нестабильному поведению на больших текстурах.
Компромисс:
- Square reservation тратит больше VRAM (атлас может стать больше). Это цена корректности но если у вас хотя бы средний пк вы не заметите разницу.
Для больших паттерн-текстур CTM иногда упирается в float-погрешности и UV-границы, из-за чего появляются:
- швы,
- мусорные пиксели,
- неверные вырезки паттерна.
Библиотека патчит:
- интерполяцию
Submap(clamp по U/V); - паттерн-трансформацию (малый clamp + обход одного проблемного пути subdivide для managed-паттернов).
Важно:
- Эти CTM-патчи применяются только к
.mcmeta-managed текстурам.
Конфиг создаётся автоматически, если его нет.
Текущий шаблон (дефолт):
# ApertureMapsLib debug config\# Дебаг конфиг ApertureMapsLib
# Core behavior is fixed in code: guard + square reservation are always enabled\# Основная логика защита + square всегда включена в коде
# debug.guard_only=true Unstable guard system (disables square reserve)\# debug.guard_only=true Нестабильная система гвард (отключает square)
# Debug settings\# Дебаг настройки
debug.atlas_dump=true
debug.stitch=false
debug.pattern_samples=false
debug.core.verbose=false
debug.guard_only=false
dependency.ctm.required=truetrue(по умолчанию): CTM считается обязательным. Если CTM нет, библиотека покажет сообщение в игре и объяснит, как отключить требование.false: разрешить запуск без CTM.
debug.atlas_dump- дампит атлас в PNG + список спрайтов.
debug.stitch- логирует расширенную информацию по managed-спрайтам (размеры, UV, поворот, origin).
debug.pattern_samples- печатает ограниченное число сэмплов CTM-паттерна (step/off значения).
debug.core.verbose- максимально подробные core-логи.
debug.guard_only- выключает square reservation и оставляет только guard. Это специально помечено как нестабильный режим.
При debug.atlas_dump=true библиотека пишет:
- папка:
aperturemapslib_debug/ - файлы:
atlas_blocks.pngatlas_blocks_rects.txt
Это самый быстрый способ убедиться, что:
- ваша текстура реально присутствует в атласе;
- вокруг неё зарезервирован квадрат;
- спрайт не повернут;
- соседние текстуры не перекрывают область паттерна.
Если вы ловите странные глитчи, включите по очереди:
debug.stitch=truedebug.core.verbose=truedebug.pattern_samples=true
И приложите к репорту:
- размеры текстуры,
atlas_blocks.png,- кусок
latest.logвокруг стадии stitch.
Square reservation решает баги, но расходует атлас.
Практические советы:
- Включайте
aperturemapslibтолько там, где реально нужно (большие прямоугольные паттерны). - Важно: для блоковых паттернов размеры PNG должны быть кратны 16 по ширине и высоте (
N*16 x M*16), иначе текстура не делится на блоки16x16и паттерн будет некорректным. - Старайтесь не держать десятки огромных текстур одновременно.
- Следите за максимальным размером текстуры на GPU:
- атлас может вырасти до
2048x2048,4096x4096и выше; - если упереться в лимит будет missing sprites.
- атлас может вырасти до
- Для адекватных мипмапов используйте размеры, кратные 16 (и не слишком маленькие для выбранного mipmap level).
- Значит текстура не managed.
- Проверьте путь
.mcmetaи секциюaperturemapslib.
- Убедитесь, что
square_reserve=true. - Убедитесь, что
debug.guard_only=false. - Включите дамп атласа и проверьте, виден ли квадрат резервирования.
- Поставьте CTM.
- Или выставьте в конфиге
dependency.ctm.required=false.
- Нужен JDK 8.
- Сборка:
gradlew build
- Результат:
build/libs/ApertureMapsLib1.12.2-<version>.jar
Jar является coremod’ом (в manifest указан FMLCorePlugin) и должен лежать в mods/.
- Добавьте PNG паттерна.
- Добавьте
.png.mcmetaс"aperturemapslib": true. - Запустите с
debug.atlas_dump=true. - Проверьте
atlas_blocks.png. - Если никаких проблем нету отключите дебаг-флаги перед релизом вашего мода чтобы не спамить лишними логами и дампами.
Если хотите улучшить библиотеку, или найдете неприятный баг, в репорт кладите:
- размер текстуры,
.png.mcmeta,atlas_blocks.pngиatlas_blocks_rects.txt,- кусок
latest.logвокруг stitch.
Лицензия: см. файл LICENSE
Если в README чего-то не хватает или осталось непонятно — спрашивайте напрямую в комментариях, я отвечу.
Библиотека создана при поддержке проекта - KharkivTiles 1:1
KharkivTiles 1:1 - проект по воссозданию города Харьков в Minecraft в масштабе 1:1 с модом LittleTiles.
Телеграм канал проекта:
Если библиотека помогла вашему проекту - буду рад, если вы укажете её в описании или упомянете о проекте =)
Спасибо всем тем кто активно следит за моим проектом, и помогает мне не выгореть. <3
-+***+: -+***+:
-%@@@@@@@#:=%@@@@@@@*.
%@@@@@@@@@@@@@@@@@@@@=
#@@@@@@@@@@@@@@@@@@@@=
:%@@@@@@@@@@@@@@@@@@*
.*@@@@@@@@@@@@@@@%=
:*@@@@@@@@@@@%+.
:*%@@@@@@%=.
.=%@@#-
:.
=.
+.
+.
.#=
-**-:
-:---=%@%*
::=+++=-####=:
.-:---:-:- ##%%%#+-
.. ::%=*+-+:: ##*+=**# .:.
.== ::-.-=-*=+ #+**#%%% -.-
-::---*%%*=. --@:--::.: #@%#***% ..:-+=::.
-::--=-: @%%@@*- -:@:+*=%=+ #+++=*#@ -:::--.+%##*:.
= #==+-: #-+==+*::::+:@:::.-:- #@%@%#*% .--+==*+.+#=-**#+
= =--*== @-@#%%@%%##****+*-*-+ #@#@#*++++***+*+=@@:+%##%#**
= =::-:. @-@###%:-:--:=@##-==* #@%@@@@#---.****=@@:+%*=++=*
=+-:. = #++#=-.@-@*#*#:%+*+-=@**@=+*********+++*:#*-%+@@:+#==**## .::=+
.::==+=#**+ -::=--.@-@*###.+-++==@*+@=%@%#%#%%%%%@@@-#%%@+@@:+%####*%::=*+#@:.
=.-==: #*#+ *--=::.@-***++.=:--:=@--@=%@%=#=*=++=*-@-#*-#+**.+#+-++=% -@%+*#%:
= --:: ::-:.*==#+=.@-@%%@#:%+#*+=@%%@=#@@***####%%%@-##+%*@@.+#+=*##@#*#@####%-
=:**=+ -=+=.-::::..@-@%@@#.=:--:=@=-@=#@@.###****+:@-##*%+@@.+%####*%+++@**++#-
-=::+-=*:+-#:#==*=-.@-@@@@#:#=*+==@*+@=#@@:@@@@@@#+:@-#*-#+@@.+#+-++=%+@@@=+++##*
*++++.::.*=%:=--+--.@-@@@@#.+-+=-=@**@=#@%:@*==#@+ .@-#%%%+@@.+#*+###%+#=%*###%@@
*+=+=-++-=:=:%*+%++.@-@@@@#.+:=-:=@--@=#@%:@+:.*@+ .@-#*-#+@@.+%#*##*%++ %****#@@
....*---*--=====+@##@##*@#@@@@%++****#@%%@#%@%*@#++#@#=+@*%@@@#@@+#@@@@@@%##-@@@@@@@@:...
-========================================================================================
Отдельная благодарность команде Chisel Team за создание ConnectedTexturesMod (CTM), который вдохновил часть решений в этой библиотеке и дал возможность использовать паттерн-текстуры