Guide de développement du système de collision

Le LCC Unity SDK dispose d'un système de collision intégré, axé sur la résolution de l'accélération de la construction des colliders et de la détection de collision — c'est-à-dire le problème de performance de la collision. Le système Collider de Unity ne peut pas gérer la détection en temps réel dans de très grandes scènes.

Le LCC Unity SDK utilise son propre système de collision intégré, ne dépendant plus du composant MeshCollider de Unity ni des capacités associées, de sorte qu'il ne peut pas agir directement sur les GameObjects d'une scène Unity. Le format de données LCC officiel généré par XGrids (LCC Studio) génère des données Mesh utilisées pour la collision pendant la reconstruction, et le SDK utilise ces données de collision pour construire rapidement et efficacement la collision de la scène. Comme il s'agit d'un système de collision auto-construit, l'utilisation de la fonctionnalité de collision nécessite d'appeler les méthodes correspondantes fournies par le SDK.

Remarque :

Le système de collision intégré du SDK est incompatible avec le système Collider de Unity et ne peut pas agir directement sur les objets Rigidbody de Unity. La collision des personnages tels que les humains numériques doit être pilotée par les méthodes de détection du SDK (voir « Implémentation de la collision des humains numériques » ci-dessous).

Pour les scènes fixes, vous pouvez également extraire les données Mesh et les baker à l'avance dans un NavMesh, ce qui peut être compatible avec le système Collider de Unity ; voir le guide NavMesh pour plus de détails.

Prérequis de données

Le prérequis pour que la détection de collision fonctionne est que la scène possède des données de collision correspondantes. Les données reconstruites dans des versions antérieures peuvent ne pas contenir de données de collision ; dans ce cas, l'appel de SetColliderEnable(true) retourne false, et toutes les méthodes de détection ultérieures sont indisponibles.

Par conséquent, après avoir activé la collision, assurez-vous de vérifier la valeur de retour :

bool ok = renderer.SetColliderEnable(true);
if (!ok)
{
    Debug.LogWarning("Les données actuelles ne contiennent aucun collider, impossible d'activer la détection de collision");
}

Flux de travail d'utilisation de base

Le flux de travail de base de la fonctionnalité de collision comporte trois étapes :

1. Chargez les données de la scène via la méthode Load().
2. Dans le callback de fin de chargement, activez la collision via SetColliderEnable(true).
3. Effectuez la détection de collision via les différentes méthodes de détection (RaycastMesh / IntersectsSphere / IntersectsCapsule).

// 1. Charger la scène
renderer.Load(dataPath, onProgress: null, onComplete: () =>
{
    // 2. Activer la collision après la fin du chargement
    if (renderer.SetColliderEnable(true))
    {
        colliderReady = true;
    }
});

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

    // 3. Effectuer la détection de collision à chaque image
    var capsule = new Capsule(footPos, headPos, 0.3f);
    if (m_manager.IntersectsCapsule(capsule, out Vector3 delta))
    {
        characterController.Move(delta);
    }
}

Remarque :

SetColliderEnable() est une méthode de Renderer, tandis que les méthodes de détection (RaycastMesh / IntersectsSphere / IntersectsCapsule / Raycast) se trouvent sur LCCManager. Appelez-les sur les objets correspondants respectivement.

Flux de travail de base du système de collision

Implémentation de la collision des humains numériques

Comme le système de collision du SDK n'agit pas sur le Rigidbody de Unity, la collision des humains numériques (personnages) doit être pilotée par les méthodes de détection. Il existe trois approches courantes :

• Détection à double rayon : utilisez RaycastMesh() pour émettre un rayon vers le bas et un vers l'avant, et jugez si le personnage peut marcher en fonction des résultats de retour des rayons (sondez le sol vers le bas, sondez les obstacles vers l'avant).
• Détection par capsule : utilisez IntersectsCapsule() pour détecter si la capsule dans laquelle se trouve l'humain numérique intersecte le mesh de collision, et jugez s'il peut marcher. Le _delta de la version surchargée retourne le décalage du prochain point atteignable en toute sécurité.
• Détection par sphère : utilisez IntersectsSphere() pour détecter si la sphère dans laquelle se trouve l'humain numérique intersecte le mesh de collision, et jugez s'il peut marcher. Le _delta de la version surchargée retourne également le décalage d'un point atteignable en toute sécurité.

Trois approches d'implémentation de la collision des humains numériques

Choisir entre RaycastMesh et Raycast

Le SDK fournit deux types de méthodes de détection par rayon avec des objectifs différents :

Raycast() effectue la détection par rayon directement sur les primitives gaussiennes, avec une précision plus élevée mais une vitesse plus lente, et n'est pas recommandé pour les appels par image, il ne convient donc pas à la collision des humains numériques, uniquement à une utilisation de type mesure. Pour la collision des humains numériques, préférez RaycastMesh(), qui dépend du mesh de collision.

API associées

Parmi les méthodes liées à la collision ci-dessous, SetColliderEnable() se trouve sur Renderer, tandis que les méthodes de détection restantes se trouvent sur LCCManager. Toutes les méthodes de détection ne sont disponibles qu'après que la scène a fini de charger et que SetColliderEnable(true) a été appelé avec succès.

SetColliderEnable

// Valeur de retour : bool → true=défini avec succès, false=les données ne contiennent aucun collider ou l'instance n'est pas active
public bool SetColliderEnable(bool _enable)

Active/désactive la fonctionnalité de collider. Après l'activation, IntersectsSphere / IntersectsCapsule / RaycastMesh deviennent disponibles.

Exemple d'utilisation :

bool ok = renderer.SetColliderEnable(true);
if (!ok) Debug.LogWarning("Les données ne contiennent aucun collider");

Description :

• Les données doivent contenir des données de collision (Mesh), sinon cela retourne false.
• Nécessite que le Renderer soit dans un état actif.

RaycastMesh (coordonnées écran)

// Valeur de retour : bool → true=impact
public bool RaycastMesh(Vector3 mousePos, out HitResult _finalResult, float _disatnce = 70.0f)

Émet un rayon depuis des coordonnées écran pour détecter le mesh de collision. Utilise les données Collider pour la détection, plus rapide que Raycast mais avec une précision plus faible.

Exemple d'utilisation :

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

Description :

• Nécessite que la collision soit d'abord activée avec succès.
• Nécessite d'abord d'appeler SetColliderEnable(true).

RaycastMesh (Ray + Bounds)

// Valeur de retour : bool → true=impact
public bool RaycastMesh(Ray ray, out HitResult result, out Bounds hitBounds, float maxDist = 70.0f)

Utilise un Ray personnalisé pour la détection du mesh de collision, et retourne également les informations de boîte englobante du nœud impacté.

Exemple d'utilisation :

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

Description :

• Nécessite que la collision soit d'abord activée avec succès.
• Cette méthode est couramment utilisée pour la détection à double rayon (vers le bas, vers l'avant) afin de juger si un humain numérique peut marcher.

IntersectsSphere

// Valeur de retour : bool → true=intersection
public bool IntersectsSphere(Sphere sphere)

// Valeur de retour : bool → true=intersection
public bool IntersectsSphere(Sphere sphere, out Vector3 delta)

Détecte si une sphère intersecte le mesh de collision. La deuxième surcharge retourne en plus le vecteur de pénétration delta (direction et distance de poussée), qui peut être utilisé pour calculer le prochain point atteignable en toute sécurité.

Exemple d'utilisation :

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

Description :

• Nécessite que la collision soit d'abord activée avec succès.
• Nécessite d'abord d'appeler SetColliderEnable(true).
• Itère sur tous les Renderers actifs.

IntersectsCapsule

// Valeur de retour : bool → true=intersection
public bool IntersectsCapsule(Capsule capsule)

// Valeur de retour : bool → true=intersection
public bool IntersectsCapsule(Capsule capsule, out Vector3 delta)

Détecte si une capsule intersecte le mesh de collision. Couramment utilisé pour la détection de collision des contrôleurs de personnage. La deuxième surcharge retourne le vecteur de pénétration delta, qui peut être utilisé comme décalage vers le prochain point atteignable en toute sécurité pour un humain numérique.

Exemple d'utilisation :

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

Description :

• Nécessite que les données contiennent des nœuds de collision.
• Nécessite d'abord d'appeler SetColliderEnable(true).
• Convient à la collision de personnage à la première / troisième personne.

Raycast

// Valeur de retour : bool → true=impact
public bool Raycast(Ray _ray, out HitResult _finalResult)

Utilise un Ray personnalisé pour effectuer la détection par rayon sur les primitives gaussiennes, itérant sur tous les Renderers actifs et retournant l'impact le plus proche. Ne dépend pas du mesh de collision ; précision plus élevée mais plus lent.

Exemple d'utilisation :

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

Description :

• Ne dépend pas du mesh de collision, pas besoin de SetColliderEnable.
• Précision plus élevée mais plus lent, non recommandé pour les appels par image, convient aux applications de type mesure, pas à la collision des humains numériques.

HitResult

Les résultats d'impact des méthodes de détection ci-dessus sont retournés via la struct HitResult :

public struct HitResult {
    public bool isHit;             // S'il y a eu impact
    public float distance;         // Distance
    public Vector3 hitPos;         // Coordonnées mondiales du point d'impact (le nom du champ est hitPos, pas position)
    public Vector3 normal;         // Normale d'impact
    public float hitAlpha;         // Alpha de l'ellipsoïde impacté
    public float dist2Origin;      // Distance par rapport à l'origine du rayon
    public float scale;            // Échelle de l'ellipsoïde
}

Remarque :

Le nom du champ des coordonnées mondiales du point d'impact est hitPos, pas position ; accédez-y par le nom de champ réel.