Guía de desarrollo del sistema de colisiones

El LCC Unity SDK tiene un sistema de colisiones integrado, centrado en resolver la aceleración de la construcción de colliders y la detección de colisiones — es decir, el problema de rendimiento de la colisión. El sistema Collider de Unity no puede manejar la detección en tiempo real en escenas muy grandes.

El LCC Unity SDK usa su propio sistema de colisiones integrado, que ya no depende del componente MeshCollider de Unity ni de capacidades relacionadas, por lo que no puede actuar directamente sobre GameObjects en una escena de Unity. El formato de datos LCC oficial generado por XGrids (LCC Studio) genera datos de malla usados para la colisión durante la reconstrucción al mismo tiempo, y el SDK usa estos datos de colisión para construir rápida y eficientemente la colisión de la escena. Debido a que es un sistema de colisiones propio, usar la función de colisión requiere llamar a los métodos correspondientes proporcionados por el SDK.

Nota:

El sistema de colisiones integrado del SDK es incompatible con el sistema Collider de Unity y no puede actuar directamente sobre objetos Rigidbody en Unity. La colisión para personajes como humanos digitales debe ser impulsada por los métodos de detección del SDK (consulta "Implementación de colisión de humanos digitales" a continuación).

Para escenas fijas, también puedes extraer los datos de malla y hornearlos en un NavMesh con anticipación, lo que puede ser compatible con el sistema Collider de Unity; consulta la guía de NavMesh para más detalles.

Requisitos previos de los datos

El requisito previo para que la detección de colisiones funcione es que la escena tenga los datos de colisión correspondientes. Los datos reconstruidos en versiones anteriores pueden no contener datos de colisión; en ese caso, llamar a SetColliderEnable(true) devuelve false, y todos los métodos de detección posteriores no están disponibles.

Por lo tanto, después de activar la colisión, asegúrate de comprobar el valor de retorno:

bool ok = renderer.SetColliderEnable(true);
if (!ok)
{
    Debug.LogWarning("Los datos actuales no contienen ningún collider, no se puede activar la detección de colisiones");
}

Flujo de trabajo de uso básico

El flujo de trabajo básico de la función de colisión tiene tres pasos:

1. Carga los datos de la escena mediante el método Load().
2. En la devolución de llamada de finalización de carga, activa la colisión mediante SetColliderEnable(true).
3. Realiza la detección de colisiones mediante los diversos métodos de detección (RaycastMesh / IntersectsSphere / IntersectsCapsule).

// 1. Carga la escena
renderer.Load(dataPath, onProgress: null, onComplete: () =>
{
    // 2. Activa la colisión después de que la carga finalice
    if (renderer.SetColliderEnable(true))
    {
        colliderReady = true;
    }
});

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

    // 3. Realiza la detección de colisión en cada fotograma
    var capsule = new Capsule(footPos, headPos, 0.3f);
    if (m_manager.IntersectsCapsule(capsule, out Vector3 delta))
    {
        characterController.Move(delta);
    }
}

Nota:

SetColliderEnable() es un método de Renderer, mientras que los métodos de detección (RaycastMesh / IntersectsSphere / IntersectsCapsule / Raycast) están en LCCManager. Llámalos en los objetos correspondientes respectivamente.

Flujo de trabajo básico del sistema de colisiones

Implementación de colisión de humanos digitales

Debido a que el sistema de colisiones del SDK no actúa sobre el Rigidbody de Unity, la colisión para humanos digitales (personajes) debe ser impulsada por los métodos de detección. Hay tres enfoques comunes:

• Detección de doble rayo: usa RaycastMesh() para disparar un rayo hacia abajo y otro hacia adelante, y juzga si el personaje puede caminar según los resultados de retorno del rayo (sondea el suelo hacia abajo, sondea obstáculos hacia adelante).
• Detección de cápsula: usa IntersectsCapsule() para detectar si la cápsula en la que está el humano digital interseca con la malla de colisión, y juzga si puede caminar. El _delta de la versión sobrecargada devuelve el desplazamiento del siguiente punto alcanzable de forma segura.
• Detección de esfera: usa IntersectsSphere() para detectar si la esfera en la que está el humano digital interseca con la malla de colisión, y juzga si puede caminar. El _delta de la versión sobrecargada también devuelve el desplazamiento de un punto alcanzable de forma segura.

Tres enfoques de implementación para la colisión de humanos digitales

Elegir entre RaycastMesh y Raycast

El SDK proporciona dos tipos de métodos de detección de rayos con propósitos diferentes:

Raycast() realiza la detección de rayos directamente sobre primitivas gaussianas, con mayor precisión pero menor velocidad, y no se recomienda para llamadas por fotograma, por lo que no es adecuado para la colisión de humanos digitales, solo para uso de tipo medición. Para la colisión de humanos digitales, prefiere RaycastMesh(), que depende de la malla de colisión.

API relacionadas

Entre los métodos relacionados con la colisión a continuación, SetColliderEnable() está en Renderer, mientras que los demás métodos de detección están en LCCManager. Todos los métodos de detección solo están disponibles después de que la escena termine de cargarse y se haya llamado con éxito a SetColliderEnable(true).

SetColliderEnable

// Valor de retorno: bool → true=configurado correctamente, false=los datos no contienen collider o la instancia no está activa
public bool SetColliderEnable(bool _enable)

Activa o desactiva la función de collider. Después de activarla, IntersectsSphere / IntersectsCapsule / RaycastMesh pasan a estar disponibles.

Ejemplo de uso:

bool ok = renderer.SetColliderEnable(true);
if (!ok) Debug.LogWarning("Los datos no contienen collider");

Descripción:

• Los datos deben contener datos de colisión (Mesh), de lo contrario devuelve false.
• Requiere que el Renderer esté en estado activo.

RaycastMesh (coordenadas de pantalla)

// Valor de retorno: bool → true=impacto
public bool RaycastMesh(Vector3 mousePos, out HitResult _finalResult, float _disatnce = 70.0f)

Dispara un rayo desde coordenadas de pantalla para detectar la malla de colisión. Usa datos Collider para la detección, más rápido que Raycast pero con menor precisión.

Ejemplo de uso:

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

Descripción:

• Requiere que la colisión se active correctamente primero.
• Requiere llamar a SetColliderEnable(true) primero.

RaycastMesh (Ray + Bounds)

// Valor de retorno: bool → true=impacto
public bool RaycastMesh(Ray ray, out HitResult result, out Bounds hitBounds, float maxDist = 70.0f)

Usa un Ray personalizado para la detección de malla de colisión, y también devuelve la información de la caja delimitadora del nodo impactado.

Ejemplo de uso:

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

Descripción:

• Requiere que la colisión se active correctamente primero.
• Este método se usa comúnmente para la detección de doble rayo (hacia abajo, hacia adelante) para juzgar si un humano digital puede caminar.

IntersectsSphere

// Valor de retorno: bool → true=interseca
public bool IntersectsSphere(Sphere sphere)

// Valor de retorno: bool → true=interseca
public bool IntersectsSphere(Sphere sphere, out Vector3 delta)

Detecta si una esfera interseca con la malla de colisión. La segunda sobrecarga devuelve además el vector de penetración delta (dirección y distancia de expulsión), que puede usarse para calcular el siguiente punto alcanzable de forma segura.

Ejemplo de uso:

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

Descripción:

• Requiere que la colisión se active correctamente primero.
• Requiere llamar a SetColliderEnable(true) primero.
• Itera sobre todos los Renderers activos.

IntersectsCapsule

// Valor de retorno: bool → true=interseca
public bool IntersectsCapsule(Capsule capsule)

// Valor de retorno: bool → true=interseca
public bool IntersectsCapsule(Capsule capsule, out Vector3 delta)

Detecta si una cápsula interseca con la malla de colisión. Se usa comúnmente para la detección de colisiones del controlador de personaje. La segunda sobrecarga devuelve el vector de penetración delta, que puede usarse como desplazamiento al siguiente punto alcanzable de forma segura para un humano digital.

Ejemplo de uso:

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

Descripción:

• Requiere que los datos contengan nodos de colisión.
• Requiere llamar a SetColliderEnable(true) primero.
• Adecuado para la colisión de personajes en primera / tercera persona.

Raycast

// Valor de retorno: bool → true=impacto
public bool Raycast(Ray _ray, out HitResult _finalResult)

Usa un Ray personalizado para realizar la detección de rayos sobre primitivas gaussianas, iterando sobre todos los Renderers activos y devolviendo el impacto más cercano. No depende de la malla de colisión; mayor precisión pero más lento.

Ejemplo de uso:

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

Descripción:

• No depende de la malla de colisión, no necesita SetColliderEnable.
• Mayor precisión pero más lento, no se recomienda para llamadas por fotograma, adecuado para aplicaciones de tipo medición, no adecuado para la colisión de humanos digitales.

HitResult

Los resultados de impacto de los métodos de detección anteriores se devuelven mediante el struct HitResult:

public struct HitResult {
    public bool isHit;             // Si hubo impacto
    public float distance;         // Distancia
    public Vector3 hitPos;         // Coordenadas de mundo del punto de impacto (el nombre del campo es hitPos, no position)
    public Vector3 normal;         // Normal del impacto
    public float hitAlpha;         // Alfa del elipsoide impactado
    public float dist2Origin;      // Distancia al origen del rayo
    public float scale;            // Escala del elipsoide
}

Nota:

El nombre del campo de las coordenadas de mundo del punto de impacto es hitPos, no position; accede a él mediante el nombre de campo real.