fparkan/docs/specs/msh-animation.md

MSH animation

MSH animation описывает связку Res8 + Res19 и runtime-правила сэмплирования/смешивания поз.

Связанные страницы:

• MSH core
• Render pipeline

1. Ресурсы анимации

1.1. Res8 (пул ключей)

struct AnimKey24 {
    float   pos_x;
    float   pos_y;
    float   pos_z;
    float   time;
    int16_t qx;
    int16_t qy;
    int16_t qz;
    int16_t qw;
};

Декодирование quaternion-компонент: q = s16 / 32767.0.

1.2. Res19 (карта кадров)

uint16_t map_words[]; // size/2 элементов

Res19.attr2 хранит глобальную длину таймлайна (число кадров).

1.3. Связь с Res1

Для каждого узла:

• anim_map_start (hdr2) — начало блока в Res19 или 0xFFFF.
• fallback_key (hdr3) — индекс fallback-ключа в Res8.

2. Сэмплирование узла

Вход: время t, текущий узел.
Выход: quat(w,x,y,z) и pos(x,y,z).

2.1. Индекс кадра

Движок использует x87-совместимое округление для выражения t - 0.5.
Для 1:1 повторения нужно сохранить ту же политику плавающей точки.

2.2. Выбор key index

1. Если кадр вне диапазона frame_count -> fallback_key.
2. Если anim_map_start == 0xFFFF -> fallback_key.
3. Иначе берётся map_words[anim_map_start + frame]:
   • если значение >= fallback_key, тоже используется fallback_key;
   • иначе используется значение из map.

2.3. Интерполяция

Если выбран fallback, возвращается ровно этот ключ без интерполяции.

Иначе:

1. Берутся соседние ключи k0 и k1.
2. Если t точно равен k0.time или k1.time, возвращается соответствующий ключ.
3. Иначе:
   • alpha = (t - k0.time) / (k1.time - k0.time)
   • pos = lerp(k0.pos, k1.pos, alpha)
   • quat = slerp_like(k0.quat, k1.quat, alpha)

Кватернион в runtime хранится в порядке [w, x, y, z].

3. Смешивание двух сэмплов

При blending между позами A и B:

1. Выбираются валидные стороны по blend и валидности времени.
2. Если активна одна сторона, берётся она.
3. Если активны обе:
   • применяется shortest-path flip для qB;
   • выполняется quaternion blend;
   • позиция смешивается линейно.

Матрица строится из quaternion, а translation подставляется отдельным шагом.

4. Каноника writer

Рекомендуемые правила:

1. Ключи узлов писать подряд в Res8 в порядке узлов.
2. fallback_key узла указывает на последний ключ его трека.
3. Для узлов с map выделять блок длины frame_count в Res19.
4. Для статических узлов: anim_map_start = 0xFFFF, один ключ с time=0.
5. Res8.attr1 = key_count, Res8.attr3 = 4.
6. Res19.attr1 = map_word_count, Res19.attr2 = frame_count, Res19.attr3 = 2.

5. Валидация перед сохранением

• Res8.size % 24 == 0
• Res19.size % 2 == 0
• каждый fallback_key < key_count
• для узла с map: anim_map_start + frame_count <= map_word_count
• внутри трека времена ключей строго возрастают

6. Статус валидации

• Форматные проверки включены в tools/msh_doc_validator.py.
• Корпусная валидация анимационных инвариантов включена в прогон tools/msh_doc_validator.py на полном retail-наборе.

7. Статус покрытия и что осталось до 100%

Закрыто:

1. Контракт Res8 + Res19 и fallback-логика выбора ключа.
2. Базовая интерполяция поз и blending двух сэмплов.
3. Канонические инварианты writer path для существующих ассетов.

Осталось:

1. Полная фиксация численного поведения на всех FP-edge-case (включая платформенные различия округления).
2. Полный writer-профиль для авторинга новых анимаций без опоры на reference copy-through.
3. Набор runtime parity-тестов «frame-by-frame pose equivalence» на длинных анимациях.