Руководство по разработке системы коллизий

LCC Unity SDK имеет встроенную систему коллизий, ориентированную на ускорение построения коллайдеров и обнаружения коллизий — то есть на проблему производительности коллизий. Система Collider Unity не может обрабатывать обнаружение в реальном времени в очень больших сценах.

LCC Unity SDK использует собственную встроенную систему коллизий, больше не полагаясь на компонент MeshCollider Unity и связанные возможности, поэтому она не может напрямую действовать на GameObject в сцене Unity. Официальный формат данных LCC, генерируемый XGrids (LCC Studio), при реконструкции одновременно генерирует данные Mesh, используемые для коллизий, и SDK использует эти коллизионные данные для быстрого и эффективного построения коллизий сцены. Поскольку это собственная система коллизий, использование функции коллизий требует вызова соответствующих методов, предоставляемых SDK.

Примечание:

Встроенная система коллизий SDK несовместима с системой Collider Unity и не может напрямую действовать на объекты Rigidbody в Unity. Коллизии для персонажей, таких как цифровые люди, должны управляться методами обнаружения SDK (см. «Реализация коллизий цифрового человека» ниже).

Для фиксированных сцен можно также извлечь данные Mesh и заранее запечь их в NavMesh, что совместимо с системой Collider Unity; подробнее см. руководство по NavMesh.

Предварительные требования к данным

Предпосылкой для работы обнаружения коллизий является то, что сцена имеет соответствующие коллизионные данные. Данные, реконструированные в более ранних версиях, могут не содержать коллизионных данных; в этом случае вызов SetColliderEnable(true) возвращает false, и все последующие методы обнаружения недоступны.

Поэтому после включения коллизии обязательно проверьте возвращаемое значение:

bool ok = renderer.SetColliderEnable(true);
if (!ok)
{
    Debug.LogWarning("Текущие данные не содержат коллайдера, невозможно включить обнаружение коллизий");
}

Базовый рабочий процесс использования

Базовый рабочий процесс функции коллизий состоит из трёх шагов:

1. Загрузите данные сцены через метод Load().
2. В обратном вызове завершения загрузки включите коллизию через SetColliderEnable(true).
3. Выполняйте обнаружение коллизий через различные методы обнаружения (RaycastMesh / IntersectsSphere / IntersectsCapsule).

// 1. Загружаем сцену
renderer.Load(dataPath, onProgress: null, onComplete: () =>
{
    // 2. Включаем коллизию после завершения загрузки
    if (renderer.SetColliderEnable(true))
    {
        colliderReady = true;
    }
});

void Update()
{
    if (!colliderReady) return;

    // 3. Выполняем обнаружение коллизий каждый кадр
    var capsule = new Capsule(footPos, headPos, 0.3f);
    if (m_manager.IntersectsCapsule(capsule, out Vector3 delta))
    {
        characterController.Move(delta);
    }
}

Примечание:

SetColliderEnable() — метод Renderer, а методы обнаружения (RaycastMesh / IntersectsSphere / IntersectsCapsule / Raycast) находятся в LCCManager. Вызывайте их на соответствующих объектах.

Базовый рабочий процесс системы коллизий

Реализация коллизий цифрового человека

Поскольку система коллизий SDK не действует на Rigidbody Unity, коллизии для цифровых людей (персонажей) должны управляться методами обнаружения. Существуют три распространённых подхода:

• Двухлучевое обнаружение: используйте RaycastMesh() для испускания одного луча вниз и одного вперёд и судите, может ли персонаж идти, на основе результатов возврата лучей (зондирование земли вниз, зондирование препятствий вперёд).
• Обнаружение капсулой: используйте IntersectsCapsule() для обнаружения пересечения капсулы, в которой находится цифровой человек, с коллизионным мешем и судите, может ли он идти. Параметр _delta перегруженной версии возвращает смещение следующей безопасно достижимой точки.
• Обнаружение сферой: используйте IntersectsSphere() для обнаружения пересечения сферы, в которой находится цифровой человек, с коллизионным мешем и судите, может ли он идти. Параметр _delta перегруженной версии также возвращает смещение безопасно достижимой точки.

Три подхода реализации коллизий цифрового человека

Выбор между RaycastMesh и Raycast

SDK предоставляет два типа методов лучевого обнаружения с разными целями:

Raycast() выполняет лучевое обнаружение непосредственно на гауссовых примитивах, с более высокой точностью, но более низкой скоростью, и не рекомендуется для покадровых вызовов, поэтому не подходит для коллизий цифрового человека, только для использования измерительного типа. Для коллизий цифрового человека предпочитайте RaycastMesh(), который зависит от коллизионного меша.

Связанные API

Среди связанных с коллизиями методов ниже SetColliderEnable() находится в Renderer, а остальные методы обнаружения — в LCCManager. Все методы обнаружения доступны только после того, как сцена завершила загрузку и SetColliderEnable(true) был вызван успешно.

SetColliderEnable

// Возвращаемое значение: bool → true=установлено успешно, false=данные не содержат коллайдера или экземпляр не активен
public bool SetColliderEnable(bool _enable)

Переключает функцию коллайдера. После включения IntersectsSphere / IntersectsCapsule / RaycastMesh становятся доступными.

Пример использования:

bool ok = renderer.SetColliderEnable(true);
if (!ok) Debug.LogWarning("Данные не содержат коллайдера");

Описание:

• Данные должны содержать коллизионные (Mesh) данные, иначе возвращается false.
• Требуется, чтобы Renderer находился в активном состоянии.

RaycastMesh (экранные координаты)

// Возвращаемое значение: bool → true=попадание
public bool RaycastMesh(Vector3 mousePos, out HitResult _finalResult, float _disatnce = 70.0f)

Испускает луч из экранных координат для обнаружения коллизионного меша. Использует данные Collider для обнаружения, быстрее, чем Raycast, но с меньшей точностью.

Пример использования:

if (m_manager.RaycastMesh(Input.mousePosition, out HitResult hit))
{
    Debug.Log(hit.hitPos);
}

Описание:

• Требует предварительного успешного включения коллизии.
• Требует предварительного вызова SetColliderEnable(true).

RaycastMesh (Ray + Bounds)

// Возвращаемое значение: bool → true=попадание
public bool RaycastMesh(Ray ray, out HitResult result, out Bounds hitBounds, float maxDist = 70.0f)

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

Пример использования:

Ray ray = Camera.main.ScreenPointToRay(Input.mousePosition);
if (m_manager.RaycastMesh(ray, out HitResult hit, out Bounds bounds))
{
    Debug.Log(bounds.center);
}

Описание:

• Требует предварительного успешного включения коллизии.
• Этот метод обычно используется для двухлучевого обнаружения (вниз, вперёд), чтобы судить, может ли цифровой человек идти.

IntersectsSphere

// Возвращаемое значение: bool → true=пересечение
public bool IntersectsSphere(Sphere sphere)

// Возвращаемое значение: bool → true=пересечение
public bool IntersectsSphere(Sphere sphere, out Vector3 delta)

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

Пример использования:

var sphere = new Sphere(transform.position, 0.5f);
if (m_manager.IntersectsSphere(sphere, out Vector3 delta))
{
    transform.position += delta;
}

Описание:

• Требует предварительного успешного включения коллизии.
• Требует предварительного вызова SetColliderEnable(true).
• Перебирает все активные Renderer.

IntersectsCapsule

// Возвращаемое значение: bool → true=пересечение
public bool IntersectsCapsule(Capsule capsule)

// Возвращаемое значение: bool → true=пересечение
public bool IntersectsCapsule(Capsule capsule, out Vector3 delta)

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

Пример использования:

var capsule = new Capsule(footPos, headPos, 0.3f);
if (m_manager.IntersectsCapsule(capsule, out Vector3 delta))
{
    characterController.Move(delta);
}

Описание:

• Требуется, чтобы данные содержали коллизионные узлы.
• Требует предварительного вызова SetColliderEnable(true).
• Подходит для коллизий персонажа от первого / третьего лица.

Raycast

// Возвращаемое значение: bool → true=попадание
public bool Raycast(Ray _ray, out HitResult _finalResult)

Использует пользовательский Ray для выполнения лучевого обнаружения на гауссовых примитивах, перебирая все активные Renderer и возвращая ближайшее попадание. Не зависит от коллизионного меша; выше точность, но медленнее.

Пример использования:

Ray ray = new Ray(origin, direction);
if (m_manager.Raycast(ray, out HitResult hit))
{
    Debug.Log(hit.hitPos);
}

Описание:

• Не зависит от коллизионного меша, не требует SetColliderEnable.
• Выше точность, но медленнее, не рекомендуется для покадровых вызовов, подходит для приложений измерительного типа, не подходит для коллизий цифрового человека.

HitResult

Результаты попадания вышеуказанных методов обнаружения возвращаются через структуру HitResult:

public struct HitResult {
    public bool isHit;             // Есть ли попадание
    public float distance;         // Расстояние
    public Vector3 hitPos;         // Мировые координаты точки попадания (имя поля hitPos, а не position)
    public Vector3 normal;         // Нормаль попадания
    public float hitAlpha;         // Альфа попавшего эллипсоида
    public float dist2Origin;      // Расстояние до начала луча
    public float scale;            // Масштаб эллипсоида
}

Примечание:

Имя поля мировых координат точки попадания — hitPos, а не position; обращайтесь к нему по фактическому имени поля.