More animations

Better Seraph 0.1.0 — документация

Физика волос для Vintage Story, настраиваемая через имена костей. Мод читает имя и накладывает физику сам — код трогать не нужно. Плюс две системы поведения под головными уборами: скрытие прядей и заморозка физики.

Документация состоит из трёх частей: формат имён, флаги, поведение под уборами.

ЧАСТЬ 1. Формат имени кости

Имя делится символом @ на две части, в конце — обязательный хвост phys:

LWSmega@zf40b15l20r5.own.nod3.stiff0,5phys

• до @ — имя кости, любое (LWSmega). Мод его не трогает и использует как идентификатор пряди в конфигах;
• после @ — данные физики;
• phys на конце — по нему мод опознаёт кость волос.

⚠️ Обязательно: кейфрейм для каждой кости

Правильного имени недостаточно. Чтобы кость попала в аниматор и получила Joint ID, она должна быть в хотя бы одном кейфрейме любой анимации (достаточно одного нулевого кадра). Без этого прядь висит неподвижно, без ошибок. Правило: имя даёт настройки, кейфрейм даёт Joint ID — нужно и то, и другое.

⚠️ Обязательно: убирайте пустые грани

У каждого куба оставляйте только видимые грани с реальной текстурой (#hair). Не оставляйте граней с #null и вырожденным UV ([48,48,48,48]) — Blockbench иногда создаёт их при копировании кубов. Они невидимы в обычном состоянии, но при пересборке меша (например, при надевании шлема) начинают чернеть и мигать.

Сторона (первая буква после @)

Пределы наклона

После стороны — максимальные углы наклона в градусах. Пары «буква + число», порядок свободный: f вперёд, b назад, l влево, r вправо. Пример: f40b15l20r5 — вперёд 40°, назад 15°, влево 20°, вправо 5°.

Дробные числа — через запятую

Точка занята под разделитель флагов, поэтому дробные значения пишутся запятой: .tilt0,8, .stiff0,5, f15,5.

ЧАСТЬ 2. Флаги (через точку)

Поведение

Силы (абсолютные значения)

Задают силу эффекта. Не указан флаг — берётся значение по умолчанию. Значение абсолютное: не зависит от глобальных настроек мода.

Пружина

Приоритет: если заданы и .w, и .stiff, побеждает .stiff.

Цепочки

Одна прядь висит на другой и запаздывает, создавая волну по длине. Поддерживаются двухзвенные.

Корень: LWSbase@zf2b2l5r5.c1phys
Звено: LWSbase2@zf2b2l10r10.c2(LWSbase).w30phys

Автоматически

Форму пряди (ширину, края для смещения пивота) мод читает из самого куба в шейпе. В имя это писать не нужно.

Примеры имён

Простая прядь: LWSfront@pf40b15l20r20phys
Коса (от своего пивота): LWSkos@zf45b4l45r45.ownphys
Ленивая тяжёлая прядь: LWSheavy@pf30b20l20r20.stiff0,15.run20phys
Звено цепи с волной: LWStail2@zf10b10l10r10.c2(LWStail).w30phys

Если что-то не работает

Мод пишет в лог понятную причину, если имя разобрано неверно. Прядь с ошибкой остаётся статичной, но игру не роняет. Проверьте лог, если прядь не двигается — и не забудьте про кейфрейм и про пустые грани.

Better Seraph — hair behaviour under headwear

Two independent systems for how hair reacts to worn helmets and hats:

• Hiding — the strand disappears under headwear (real removal from the mesh);
• Freezing — the strand stays visible but stops moving (fully or on one axis).

Both are set up with files in your mod and work with any headwear, including modded. Hiding and freezing the same strand under the same headwear makes no sense — a hidden strand isn't visible.

Hiding: config/hairhide.json

Place the file in assets/<yourmod>/config/hairhide.json:

{ "HidePhysics": { "armor-head-*": ["BShair_long"], "clothes-head-tophat": ["BShair_bun"] } }

• key — headwear item code mask (* = any tail);
• value — names of shape elements (wrappers/groups) removed under this headwear.

Hiding is recursive: hide a wrapper bone and the whole strand with its contents disappears. Hide by wrapper name, not an individual bone — then editing limits inside won't break hiding. Removing the headwear restores the strand automatically.

Installing the hiding system

Hiding works through a behavior attached to the player via a patch. Put this in assets/<yourmod>/patches/:

[ { "op": "addmerge", "path": "/client/behaviors/-", "value": { "code": "bettseraphHairHide" }, "file": "game:entities/humanoid/player.json", "side": "Server" } ]

Freezing: config/hairfreeze.json

File in assets/<yourmod>/config/hairfreeze.json:

{ "FreezePhysics": { "armor-head-plate-*": ["BShair_long", "BShair_side:lr"] } }

• key — headwear code mask (as with hiding);
• value — strands by name before @ (the same part as in .c2(name)).

Freezing per axis

You can add an axis suffix to a strand name:

Axes are in body space, not world space. A frozen axis dampens both movement and wind on that axis; the spring eases the strand to rest without a jerk. If several rules match one headwear, the axes accumulate.

"BShair_long:fb" — freeze front-back only.
"BShair_bun" — freeze fully.
"*" in the list — the whole hairstyle.

Headwear code masks

Mask keys are the same for both systems. Useful armor masks:

The armor material is always at the end of the code, so armor-head-plate-* matches plate helmets of any metal.

Mod compatibility

Both files are gathered from all installed mods: each hairstyle author places their own hairhide.json / hairfreeze.json in their own mod, and the rules merge. Typos in strand names go to the log.

Better Seraph — поведение волос под головными уборами

Две независимые системы для реакции волос на надетые шлемы и шапки:

• Скрытие — прядь исчезает под убором (честное удаление из меша);
• Заморозка — прядь остаётся видимой, но перестаёт двигаться (целиком или по одной оси).

Обе настраиваются файлами в вашем моде и работают с любым головным убором, включая модовые. Одну и ту же прядь под одним убором нет смысла и прятать, и морозить — спрятанное не видно.

Скрытие: config/hairhide.json

Файл кладётся в assets/<вашмод>/config/hairhide.json:

{ "HidePhysics": { "armor-head-*": ["BShair_long"], "clothes-head-tophat": ["BShair_bun"] } }

• ключ — маска кода головного предмета (* = любой хвост);
• значение — имена элементов шейпа (обёрток/групп), которые удаляются под этим убором.

Скрытие рекурсивно: прячете кость-обёртку — исчезает вся прядь с содержимым. Прячьте по имени обёртки, а не отдельной кости — тогда правки лимитов внутри не сломают скрытие. Снятие убора возвращает прядь автоматически.

Установка системы скрытия

Скрытие работает через behavior, который вешается на игрока патчем. Положите в assets/<вашмод>/patches/ файл:

[ { "op": "addmerge", "path": "/client/behaviors/-", "value": { "code": "bettseraphHairHide" }, "file": "game:entities/humanoid/player.json", "side": "Server" } ]

Заморозка: config/hairfreeze.json

Файл в assets/<вашмод>/config/hairfreeze.json:

{ "FreezePhysics": { "armor-head-plate-*": ["BShair_long", "BShair_side:lr"] } }

• ключ — маска кода убора (как у скрытия);
• значение — пряди по имени до @ (та же часть, что в .c2(имя)).

Заморозка по осям

К имени пряди можно добавить суффикс оси:

Оси — в системе тела, не мира. Замороженная ось гасит и движение, и ветер по этой оси; пружина плавно уводит прядь в покой, без рывка. Если под убор подошло несколько правил, оси накапливаются.

"BShair_long:fb" — заморозить только перёд-зад.
"BShair_bun" — заморозить целиком.
"*" в списке — вся причёска.

Маски кодов уборов

Ключи-маски одинаковы для обеих систем. Полезные маски брони:

Материал брони всегда в конце кода, поэтому armor-head-plate-* ловит латные шлемы любого металла.

Совместимость модов

Оба файла собираются со всех установленных модов: каждый автор причёски кладёт свои hairhide.json / hairfreeze.json в свой мод, и правила объединяются. Опечатки в именах прядей попадают в лог.