Dépannage des dysfonctionnements courants du 3DGS sous UE5 par symptôme
Cette page est organisée selon le symptôme observé ; chaque entrée donne les causes possibles, la méthode de vérification et la solution.
Pour consulter les journaux et utiliser les outils de débogage, voir Journaux et diagnostics. Pour les questions d'ordre général (formats pris en charge, différence entre les deux pipelines), voir Questions fréquentes.
Sommaire
| Catégorie | Symptômes couverts |
|---|---|
| Commencez par ces deux étapes | Recommandé pour tout problème |
| Échec du chargement des données | Load sans réaction, invisible après empaquetage, empaquetage d'un projet Blueprint, position GIS incorrecte, fermeture inopinée sur données volumineuses |
| Image absente ou incomplète | Rien de visible, contenu lointain manquant, trous en bordure, SceneCapture vide, occlusion par la surface de l'eau |
| Problèmes de qualité d'image | Rémanence, scintillement, trous, couleurs grisâtres, jointures, ligne dans la scène |
| Anomalies d'éclairage | Surexposition, absence de modelé, ProxyMesh sans effet, ombres coupées, effets masqués |
| Un paramètre modifié n'a aucun effet | Case non cochée, chargement complet, découpe et coupe, harmoniques sphériques, quota de licence |
| Problèmes de performance | Faible fréquence d'images, mémoire vidéo élevée, saccades au chargement, occlusion incorrecte |
| Collision et navigation | Rayon qui n'atteint rien, personnage qui tombe ou traverse, NavMesh non généré |
| Plantages | Erreur d'assertion ArraySliceIndex |
| Problèmes de licence | Status sans coche verte, erreurs de licence diverses |
| Compilation et empaquetage | Binaires manquants, manifeste précompilé manquant, échec d'empaquetage, Android |
| Toujours pas résolu | Ce qu'il faut réunir avant de nous contacter |
Commencez par ces deux étapes
La plupart des problèmes se localisent en deux étapes ; parcourez-les d'abord, quel que soit le symptôme.
- Ouvrez l'Output Log et regardez les journaux du plugin. Un échec de chargement, une erreur de chemin ou un problème de licence y laissent un message explicite. Pour la méthode, voir Consulter les journaux du plugin.
- Vérifiez que les données sont bien chargées. Sélectionnez l'Actor et regardez si MetaInfo contient quelque chose dans le panneau Details (Total Splats supérieur à 0). Un contenu vide signifie que les données ne sont pas entrées : passez directement à Échec du chargement des données.
Échec du chargement des données
Symptôme : Load a été cliqué mais rien n'apparaît
Vérifiez dans l'ordre :
| Cause possible | Vérification | Solution |
|---|---|---|
| Chemin inexistant ou mal saisi | Le journal affiche LCC file :<path> does not exist. | Vérifiez le chemin. Les chemins relatifs prennent Content comme référence |
| Fichier manquant dans les données LCC1 | Le journal affiche Load Meta.lcc error ou meta.lcc file :<path> load error | data.bin et index.bin doivent être présents dans le même répertoire que le .lcc ; l'absence d'un seul fait échouer le chargement |
| Mauvais Actor utilisé | Aucune erreur explicite, mais l'image est vide | .lcc2 avec ALCC2Actor, .lcc avec ALCCActor, et chaque format à fichier unique a son Actor dédié. Voir Questions fréquentes |
| Format non pris en charge | Le journal affiche LCC4Unreal do not support this file format! | Vérifiez que l'extension fait partie des formats pris en charge, voir Présentation |
Le .ply n'est pas au format 3DGS | Le journal indique que le PLY est refusé | Le plugin ne prend en charge que les .ply contenant les attributs 3DGS ; un nuage de points géométrique classique ne peut pas être chargé |
Symptôme : correct dans l'éditeur, invisible après empaquetage
Vérifiez deux choses, dans cet ordre.
1. Un chemin absolu a-t-il été utilisé. Un chemin absolu n'est valable que sur la machine d'origine et n'existe plus après un changement de machine. Passez à un chemin relatif au répertoire Content du projet, par exemple Scenes/Tower/meta.lcc2.
2. Le répertoire de données est-il déclaré dans les réglages d'empaquetage. Les deux réglages ont des usages différents, choisissez selon le besoin :
| Réglage | Usage |
|---|---|
Additional Non-Asset Directories To Copy | Les données sont copiées comme fichiers ordinaires dans le résultat de l'empaquetage |
Additional Non-Asset Directories To Package | Les données sont intégrées au pak |
Utilisez le second pour intégrer les données LCC au pak, et le premier s'il suffit que les données soient distribuées avec le résultat de l'empaquetage. Les deux se trouvent sous ProjectSettings > Packaging.
Réempaquetez après configuration et vérifiez que les données sont réellement présentes dans le résultat. Pour la configuration détaillée, voir Démarrage rapide.
Symptôme : le plugin ne fonctionne pas après l'empaquetage d'un projet Blueprint
Un projet Blueprint uniquement (Blueprint-only) n'est utilisable que dans l'éditeur et ne prend pas en charge l'empaquetage. Un projet C++ est obligatoire pour empaqueter.
Symptôme : position géographique incorrecte, le mode GIS n'a aucun effet
Vérifiez ces points :
- Les données contiennent-elles des informations RTK. Utilisez
GetMetaInfo().IsRTK()pour le déterminer ; le messageThis lcc does not have RTK information!indique que les données ne contiennent pas d'information géographique - Lors d'une activation par code, appelez
SetGeoPlacement(true): cette méthode recharge automatiquement les données pour rendre le réglage effectif. Affecter directementbEnableGeoPlacene déclenche pas le rechargement - En cas de décalage de position, ajustez finement avec
GeoLocationOffset
Pour les étapes de mise en place avec Cesium, voir Intégration avec les plugins tiers et moteur.
Symptôme : fermeture inopinée pendant la navigation dans des données LCC2 très volumineuses
Avec la version v1.0.0, il s'agit d'un défaut connu de cette version (dépassement du GPU Buffer). Passez à une version v2.x ou supérieure.
Symptôme : erreur liée à un tableau lors du chargement d'un PLY volumineux
Défaut connu de la v3.0.0, corrigé en v3.3.0 et versions ultérieures : mettez le plugin à jour.
Les PLY volumineux sont désormais lus en flux et la limite de taille de fichier de 2 GB n'existe plus. Si le chargement échoue toujours, c'est le plus souvent que le nombre de splats dépasse la capacité de la mémoire vidéo, voir Limites de chargement des formats à fichier unique.
Image absente ou incomplète
Symptôme : l'Actor est dans la scène, mais aucun contenu n'est visible
| Cause possible | Vérification | Solution |
|---|---|---|
| Les données ne sont pas chargées | Voir la section précédente | Réglez d'abord le problème de chargement |
LoadMode réglé sur None | Regardez le panneau Details | Repassez à Both |
| La caméra est au-delà de la distance de rendu | Rapprochez-vous pour voir si le contenu apparaît | Augmentez Max Distance |
| Un volume de découpe a supprimé le contenu | Désactivez temporairement bEnabled sur le volume de découpe | Vérifiez le mode de découpe : Inside et Outside font l'inverse l'un de l'autre, voir EClipType |
| Un plan de coupe a supprimé le contenu | Désactivez temporairement le plan de coupe | Vérifiez Mode et l'orientation du plan, voir ESectionType |
| Un volume de chargement a exclu les données du chargement | Désactivez temporairement bEnabled sur le volume de chargement puis rechargez | Vérifiez Mode : Inside et Outside font l'inverse l'un de l'autre, voir Volumes de chargement |
GlobalAlpha vaut 0 | Regardez le panneau Details | Repassez à 1.0 |
Tout est dans les données d'environnement mais OnlyMain est réglé | Changez LoadMode et comparez | Choisissez selon le contenu réel des données, voir ELoadMode |
Symptôme : le contenu lointain est absent et n'apparaît qu'en s'approchant
C'est le comportement normal du LOD et de la limite de distance, pas un dysfonctionnement. Pour afficher aussi le contenu lointain :
- Augmentez Max Distance, au prix d'une baisse de performances
- Baissez Level Factor pour utiliser une précision plus élevée à distance égale
- Un effet de brouillard permet de masquer la limite de distance
Symptôme : des trous apparaissent en bordure d'écran lors des rotations rapides de vue
Le préchargement des nœuds ne suit pas les changements de vue. Sur la pipeline LCC, activez Add Extra Preload Nodes : des nœuds de préchargement supplémentaires sont ajoutés, au prix d'un plus grand nombre de nœuds à rendre.
Symptôme : SceneCapture ou la minimap est vide
Il faut d'abord activer SceneCaptureComponent Support dans les paramètres du projet. Cette option est désactivée par défaut et a un léger coût en performances.
Pour définir par code une stratégie de rendu propre à un SceneCapture, voir SetSceneCaptureRenderMode ; notez que ce groupe d'interfaces ne fonctionne que sur la pipeline LCC.
Symptôme : le 3DGS est occulté par la surface de l'eau
C'est dû au traitement de la profondeur du matériau d'eau à couche unique. Activez SingleLayerWater Support, voir Prise en charge de l'eau à couche unique.
Problèmes de qualité d'image
Symptôme : rémanence et images fantômes pendant les déplacements
C'est causé par la méthode d'anticrénelage. TSR et TAA reposent sur une accumulation temporelle des images précédentes, et le 3DGS laisse facilement une trace de l'image précédente pendant les déplacements.
Essayez dans cet ordre pour trouver l'équilibre entre qualité d'image et rémanence :
None → FXAA → MSAA → TAA → TSR
Quand la scène ne contient que du 3DGS, réglez directement sur None : il n'y a alors ni rémanence, ni coût d'anticrénelage. Pour les valeurs par défaut de chaque pipeline et l'emplacement du réglage, voir Paramètres de performance.
Symptôme : image scintillante, bords instables
Essayez par ordre de bénéfice :
- Vérifiez la méthode d'anticrénelage. C'est la cause la plus fréquente ; TSR est recommandé sur la pipeline LCC2, voir Paramètres de performance.
- Pipeline LCC : baissez Sort Factor pour augmenter la fréquence de tri. Quand la fréquence de tri est trop faible, l'ordre avant/arrière des éléments semi-transparents ne se met à jour que toutes les quelques images, ce qui se traduit par une légère instabilité de l'image.
- Vérifiez Small Splat Threshold : une valeur trop grande rend l'arrière-plan granuleux.
- Quand des structures fines scintillent pendant les travellings de caméra, essayez d'activer Mip Filter : il applique un filtre passe-bas avec compensation d'opacité, plus stable aux différentes échelles.
.ply/.spz/.sogdésactivent cette option par défaut.
Symptôme : image trouée, aspect épars
SplatScale est réglé trop bas. La valeur par défaut 1.0 est le maximum ; le baisser réduit l'overdraw et améliore la fréquence d'images, mais des interstices apparaissent dès que les quads deviennent trop petits. Remontez un peu la valeur.
Symptôme : couleurs grisâtres et plates
Traitez le problème avec les paramètres de couleur, voir Réglages visuels. L'approche courante consiste à augmenter légèrement Contrast, ou à éclaircir les zones sombres avec Gamma. Pour l'interface de code, voir Color Adjustment.
Symptôme : jointures visibles dans l'image (pipeline LCC)
Les fichiers LCC en version 5.0 et supérieure traitent les jointures automatiquement. Pour les données de versions antérieures, activez manuellement la découpe des jointures, qui correspond à la propriété bEnableSeamCutting.
Symptôme : une ligne apparaît dans la scène
Vérifiez l'échelle de l'Actor. Les Actors de la famille LCC (ALCCActor, ALCC2Actor, ASogActor, ASpzActor, APlyActor) ne prennent en charge que la mise à l'échelle uniforme.
N'utilisez pas ce genre d'échelles non uniformes :
- Avec des valeurs négatives, par exemple
(-1, 1, 1) - Avec des axes inégaux, par exemple
(2, 1, 3)
Les trois axes doivent rester identiques, par exemple (1, 1, 1) ou (2, 2, 2). Une mise à l'échelle non uniforme provoque des anomalies de rendu qui se manifestent par une ligne dans l'image.
Anomalies d'éclairage
Symptôme : image surexposée après passage en Lit
Les couleurs des données capturées contiennent déjà l'éclairage du lieu de prise de vue, et la lumière de la scène s'ajoute par-dessus.
- Pipeline LCC2 : baissez la luminosité d'origine avec
LightingScale, voir Normales et éclairage - Vérifiez si l'intensité de l'éclairage de la scène n'est pas trop élevée
Symptôme : aucun modelé en mode Lit, image très plate
C'est le comportement attendu. Les données 3DGS n'ont pas de normales géométriques, et les trois modes Fixed, ViewFacing et Hemispherical construisent les normales par approximation : ils ne peuvent produire qu'une variation de luminosité globale et aucun ne peut produire un modelé qui suit le relief des formes. Pour la définition de chaque mode, voir ELCC2NormalGenerationMode.
Pour un vrai modelé des formes, seul le mode ProxyMesh en est capable : il faut créer et placer un maillage proxy, et disposer d'une licence. Voir Maillage proxy et Normales et éclairage.
Ce qui distingue les trois modes approximatifs, c'est la façon dont la luminosité globale évolue avec l'éclairage et le point de vue, pas la présence d'un modelé :
Fixed: toute la surface partage une normale fixe, parfaitement stable pendant les déplacements de caméraViewFacing: la normale suit la caméra, donc la luminosité globale change lors des rotations de vueHemispherical: la normale est projetée depuis la position à l'écran sur un hémisphère fixe, ce qui donne une transition de luminosité globale plus douce que les deux précédents lors de la rotation d'une lumière directionnelle
Symptôme : le mode ProxyMesh est réglé mais reste sans effet
| Point à vérifier | Vérification |
|---|---|
| NormalMode vaut-il ProxyMesh | Regardez le panneau Details |
| La licence est-elle valide | Regardez le Status dans le panneau du plugin ; une coche verte indique une licence correcte. Vous pouvez aussi appeler GetEffectiveNormalGenerationMode() dans le code : un retour Fixed signifie que le mode a été rétrogradé |
| Le maillage proxy a-t-il un StaticMesh | Le journal affiche l'avertissement has a null StaticMesh |
| Le maillage proxy chevauche-t-il spatialement le 3DGS | L'appariement se fait par la position ; sans recouvrement, il n'y a aucun effet |
Voir Maillage proxy pour les détails.
Symptôme : le modelé apparaît au mauvais endroit
L'écart entre le maillage proxy et la surface réelle du 3DGS est trop important. Améliorez la conformité du maillage proxy, ou passez à un mode de normales approximatif, qui ne donne pas de modelé mais reste plus stable.
Symptôme : les ombres du ProxyMesh n'apparaissent que de près et disparaissent au loin
Les ombres sont coupées par la distance ; c'est un problème du moteur lui-même, pas un défaut du plugin.
Solution : sélectionnez l'Actor ProxyMesh, désactivez puis réactivez Far Shadow (ombres lointaines) pour que les ombres redeviennent complètes. La propriété se trouve dans la catégorie Lighting du StaticMeshComponent.
Symptôme : d'énormes ombres anormales apparaissent en mode Lit
Les modes de normales approximatifs produisent des anomalies sous certains angles d'éclairage. Essayez dans cet ordre :
- Changez de NormalMode pour voir quel mode se comporte normalement
- Ajustez l'angle de la lumière directionnelle
- Passez au mode ProxyMesh avec un maillage proxy bien conforme, c'est la solution la plus efficace
Symptôme : les couleurs changent après activation des ombres
C'est le comportement attendu. Une fois le 3DGS soumis à un éclairage externe, ses couleurs évoluent avec les sources de lumière ; ajustez la couleur et l'intensité de la lumière directionnelle.
Symptôme : la luminosité ne bouge pas, la scène est globalement sombre
Si un plugin de composition comme Composure est utilisé dans le projet, désactivez les options de post-traitement du Component et contrôlez l'exposition avec un Post Process Volume à la place.
Pour les réglages liés à l'exposition, voir Réglages visuels.
Symptôme : les effets Niagara sont invisibles sur le 3DGS
La pipeline LCC2 produit de la profondeur, donc les relations d'occlusion des effets sont correctes et ce problème n'apparaît normalement pas.
Seule la pipeline LCC (données .lcc) peut être concernée, car elle ne produit pas de profondeur et l'ordre avant/arrière des éléments semi-transparents dépend de la priorité de tri. La solution consiste à augmenter le Translucent Sort Priority du Niagara System pour qu'il soit rendu au-dessus du 3DGS.
Symptôme : du contenu désordonné entoure la scène
Ce sont les données d'environnement. Passez LoadMode de Both à OnlyMain pour ne rendre que la partie principale.
Symptôme : le changement de mode d'éclairage reste sans effet
SetLightMode est sans effet en mode nuage de points : l'affectation est ignorée et un avertissement est écrit dans le journal. Repassez d'abord en mode 3DGS.
Symptôme : aucun effet d'éclairage après passage en mode Lit
La pipeline de rendu en avant (Forward Shading) n'a pas de GBuffer et ne permet pas le réeclairage. Régler LightMode sur Lit reste sans effet.
Passez à la pipeline de rendu différé (Deferred Shading) pour utiliser normalement le mode Lit. Décochez l'option dans Project Settings > Rendering > Forward Shading. Notez que le modèle VR d'UE active Forward Shading par défaut : désactivez-le manuellement avec ce modèle.
Un paramètre modifié n'a aucun effet
Symptôme : une valeur de Performance a été modifiée mais rien ne change
Chaque paramètre possède une case à cocher sur sa gauche ; tant qu'elle n'est pas cochée, la valeur par défaut intégrée au plugin est utilisée et la valeur saisie n'a aucun effet. C'est le piège le plus fréquent.
Pour les valeurs par défaut intégrées de chaque paramètre, voir Paramètres de performance.
Symptôme : les paramètres de chargement complet ont été modifiés sans changement
Use Full Load et Full Load Splat Number sont évalués au moment du chargement : rechargez les données après modification pour que le réglage prenne effet.
Pour la différence entre les deux modes de chargement, voir Rendu.
Symptôme : les propriétés d'un volume de découpe ou d'un plan de coupe modifiées à l'exécution restent sans effet
Ce problème n'existe pas dans la version actuelle : les données de découpe et de coupe sont lues à chaque image, donc les propriétés bEnabled, Mode et VolumeType prennent effet à l'image suivante après affectation, de même que les modifications de transformation (position, rotation, échelle).
Si l'effet manque toujours, vérifiez que l'Actor a bien été ajouté aux tableaux ClippingVolumes / SectionPlanes du Component, et que le quota de nombre simultanément actif n'est pas dépassé (50 par catégorie sans licence, l'excédent ne participant pas au rendu et produisant un avertissement).
Les anciennes versions demandaient d'appeler Refresh() manuellement. Cette méthode et SetUpdateComponent() sont désormais dépréciées et sans effet, voir ALCCClippingVolume.
Symptôme : les harmoniques sphériques sont activées mais l'image ne change pas
- Les données sont peut-être de type
Portable, qui ne contient pas d'harmoniques sphériques. Confirmez avec CanSetShcoef() ; pour la définition des types, voir EFileType - SetUseShcoef est silencieusement sans effet en mode nuage de points, repassez d'abord en 3DGS
- Sur LCC2, les harmoniques sphériques peuvent être désactivées seules, via SetUseShcoef
Symptôme : beaucoup de volumes de découpe ont été ajoutés mais une partie seulement prend effet
L'édition gratuite limite chaque catégorie à 50. Le journal contient un message explicite : Unlicensed: enabled clipping volumes limited to 50 .... Pour les explications sur les licences, voir Éditions et licences.
Problèmes de performance
Pour la démarche d'optimisation complète d'une fréquence d'images faible, voir Guide d'optimisation des performances ; cette section ne liste que les vérifications rapides.
Symptôme : fréquence d'images faible
Commencez par déterminer si le goulot d'étranglement est bien le 3DGS. Regardez les trois valeurs Game / Draw / GPU avec stat unit, puis le temps propre à LCC avec stat XGrids. Si la part de temps de LCC est faible, le problème se situe ailleurs dans la scène (éclairage, post-traitement, logique Blueprint) et ajuster les paramètres LCC n'apportera aucune amélioration.
Si le 3DGS est bien la cause, ajustez par ordre de bénéfice :
- Augmentez Level Factor (bénéfice le plus net)
- Réduisez Max Distance
- Réduisez Max Splat Num
- Relevez Start Level pour sauter le niveau le plus fin
- Désactivez les harmoniques sphériques
- Si nécessaire, passez en mode nuage de points
Symptôme : occupation de la mémoire vidéo trop élevée
- Augmentez Level Factor
- Réduisez Max Splat Num
- Sur la pipeline LCC2, ajustez LCC2 GPU Memory Budget
- Ajustez le seuil de libération Max GPU Usage Percetage For Free
Pour les règles d'allocation de la mémoire vidéo et le mécanisme de libération automatique, voir Rendu. Les formats à fichier unique (.sog / .spz / .ply) sont chargés intégralement en une passe et leur occupation de mémoire vidéo reste constante quel que soit le point de vue, voir Limites de chargement des formats à fichier unique.
Symptôme : saccades au chargement
- La première activation de la collision entraîne un coût de bake unique ; activez-la de préférence dès la phase de chargement, pas au milieu des actions du joueur
- Réduisez Max Load Collision Distance pour ne charger que la portée nécessaire
- Ajustez la configuration des threads, voir Paramètres de performance
Symptôme : relations d'occlusion incorrectes quand plusieurs 3DGS s'interpénètrent
- Pipeline LCC : activez le tri de la translucidité entre plusieurs Actors
- Pipeline LCC2 : ajustez le seuil de profondeur pour changer l'endroit où la profondeur est écrite
Collision et navigation
Symptôme : les rayons n'atteignent pas le 3DGS
| Point à vérifier | Traitement |
|---|---|
| Les données contiennent-elles de la collision | Les formats à fichier unique ne contiennent pas de données de collision, voir Prérequis |
| La collision est-elle activée | Cochez bEnableCollision, voir Activation |
| La collision est-elle chargée à cet endroit | Affichez le filaire avec ShowCollision(), voir Visualisation de la collision |
| La distance de détection dépasse-t-elle la portée de chargement de la collision | Augmentez Max Load Collision Distance |
Le message There is neither collision.bin nor collision.lci in the folder indique qu'aucun fichier de collision n'est présent dans le répertoire de données.
LCC1 possède un autre jeu d'interfaces de test de rayon sur les positions du nuage de points, mais elles sont insuffisamment testées : préférez la collision associée aux tests de rayon du moteur, voir ULCCComponent Raycast.
Symptôme : le personnage tombe dès le départ
La collision est chargée dynamiquement par blocs, et les données de collision peuvent ne pas être construites au tout début du jeu ; sans collision sous ses pieds, le personnage tombe.
Solutions :
- Placez le PlayerStart légèrement au-dessus du sol
- Ou n'autorisez le déplacement du personnage qu'après quelques secondes
- Activez la collision dès la phase de chargement, plutôt qu'après le début des actions du joueur
Symptôme : le personnage traverse le décor ou tombe au-delà d'une certaine distance
La collision est chargée en flux selon la distance : au-delà de la portée de chargement, il n'y a pas de corps de collision. Augmentez Max Load Collision Distance(m) pour couvrir la zone d'évolution du personnage.
Un personnage qui se déplace trop vite peut aussi devancer le chargement de la collision ; l'augmentation de la distance de chargement atténue également ce cas.
Symptôme : le NavMesh ne se génère pas du tout
| Point à vérifier | Traitement |
|---|---|
| Les données ne contiennent pas de collision | Vérifiez l'utilisation de .lcc ou .lcc2 ; les formats à fichier unique n'ont pas de données de collision |
| La collision n'est pas activée | Cochez bEnableCollision et vérifiez que CanEverAffectNavigation = true |
| La collision n'est pas encore chargée | Choisissez la collision joueur ou la collision de visibilité dans le mode d'affichage et vérifiez que les corps de collision sont apparus dans la zone cible |
| Portée de chargement de la collision insuffisante | Augmentez Max Load Collision Distance(m) pour couvrir toute la zone d'évolution de l'IA |
| NavMeshBoundsVolume absent ou ne couvrant pas la zone | Placez-le et redimensionnez-le pour couvrir la zone cible |
| Navigation non reconstruite | Exécutez Build → Build Paths et enregistrez le niveau |
Pour la procédure complète, voir Prise en charge du système de navigation.
Plantages
Symptôme : plantage après une erreur d'assertion ArraySliceIndex
L'erreur se présente ainsi :
Assertion failed: ArraySliceIndex >= 0
La cause est que la version actuelle ne prend pas en charge le format Adaptive GBuffer de Substrate.
Solution :
- Ouvrez
ProjectSettings > Renderinget repérez Substrate GBuffer Format (Project). - Passez la valeur à BlendableGBuffer, qui est la valeur par défaut du moteur.
- Redémarrez le moteur.
AdaptiveGBuffer est un format dont l'incompatibilité est connue ; BlendableGBuffer fonctionne normalement.
Problèmes de licence
Regardez d'abord le Status dans le panneau du plugin : une coche verte indique une licence correcte, et les fonctionnalités de l'édition Pro sont alors disponibles. Sans coche verte, la licence n'est pas active ; consultez ensuite le journal pour en déterminer la cause.
Les messages de journal liés à la licence sont assez explicites, traitez-les selon l'indication :
| Message de journal | Signification et traitement |
|---|---|
ProjectID is invalid; generate one in Project Settings | Le projet n'a pas de Project ID. Générez-en un dans Project Settings > Project > Description |
Failed to decode AppKey, please check. | Contenu de l'AppKey incomplet ou copie erronée, copiez-le de nouveau |
Invalid AppKey, please check. | Format de l'AppKey incorrect, vérifiez qu'il s'agit bien de la chaîne complète obtenue sur la plateforme développeurs |
Authorization has expired, please check. | Licence expirée, générez-en une nouvelle sur la plateforme développeurs |
AppKey has expired. Please generate a new one. | Idem |
HTTP request failed / HTTP error! Status: <code> | Problème réseau ou serveur de licences inaccessible, vérifiez le réseau et le pare-feu |
Signature Verification Failed | Échec de la vérification de signature, contactez le support technique |
Pour la procédure de licence, voir Éditions et licences.
Compilation et empaquetage
Symptôme : fichiers binaires manquants ou échec de compilation d'un module
Quand l'une des erreurs suivantes apparaît, régénérez et recompilez le projet en suivant les étapes de cette section :
Missing UnrealGame binary. You may have to build the UE project with your IDE.
Alternatively, build using UnrealBuildTool with the commandline:
UnrealGame <Platform> <Configuration>
*** could not be compiled. Try rebuilding from source manually
La cause est qu'après l'ajout du plugin à un projet C++, le moteur détecte un nouveau module mais les produits de compilation correspondants sont absents. Procédez ainsi :
- Fermez le projet.
- Repérez le fichier
*.uprojectdu projet. - Faites un clic droit sur
*.uprojectet choisissez Generate Visual Studio project files dans le menu. - Attendez la fin de la régénération du projet VS.
- Double-cliquez sur le
*.slnpour ouvrir Visual Studio. - Dans l'explorateur de solutions, faites un clic droit sur le projet et choisissez Set as Startup Project pour qu'il soit bien le projet de démarrage.
- Vérifiez que la configuration est Development Editor et Win64.
- Cliquez sur Debug > Start Without Debugging pour lancer le projet.
- Une fois la compilation réussie, le projet s'ouvre normalement. Ensuite, un double-clic sur le
*.uprojectsuffit et cette procédure n'est plus à refaire.
Si l'échec persiste après ces étapes, supprimez d'abord le répertoire Intermediate du projet, puis reprenez à l'étape 3.
Pour les étapes d'installation du plugin, voir Démarrage rapide.
Symptôme : échec de l'empaquetage
Vérifiez d'abord ces trois points :
- Full Rebuild sous
ProjectSettings > Packagingdoit rester désactivé, et n'exécutez pas Rebuild dans VS. Le plugin ne prend en charge aucune de ces deux méthodes, voir Démarrage rapide - Vérifiez qu'il s'agit bien d'un projet C++ ; un projet Blueprint ne peut pas être empaqueté
- Vérifiez que la version du moteur fait partie des versions prises en charge (UE 5.4 à 5.8)
Pour les erreurs précises, voir les deux sections suivantes.
Symptôme : manifeste précompilé manquant lors de l'empaquetage
L'erreur se présente ainsi :
Missing precompiled manifest for 'LCC4UnrealRuntime',
'\Shipping\LCC4UnrealRuntime\LCC4UnrealRuntime.precompiled'.
This module was most likely not flagged for being included in a precompiled build
- set 'PrecompileForTargets = PrecompileTargetsType.Any;' in LCC4UnrealRuntime.build.cs
to override. If part of a plugin, also check if its 'Type' is correct.
Pourquoi cela se produit : les fichiers mentionnés dans l'erreur sont normalement distribués avec le plugin et se trouvent dans son répertoire Intermediate. L'exécution de Full Rebuild depuis ProjectSettings > Packaging, ou d'un Rebuild dans VS, fait nettoyer le répertoire Intermediate par le moteur, ce qui supprime aussi ces produits précompilés.
LCC4Unreal est un plugin binaire sans code source : les produits supprimés ne peuvent pas être recompilés et ne peuvent être restaurés qu'à partir du paquet du plugin. Ces deux opérations doivent donc être évitées.
Comment corriger :
- Vérifiez que Full Rebuild sous
ProjectSettings > Packagingest désactivé et n'exécutez pas Rebuild dans VS. - Copiez le contenu du répertoire
lcc4unreal/Intermediate/Build/Win64/UnrealGamedu plugin vers le répertoire<project directory>/Intermediate/Build/Win64/<project name>du projet. - Copiez le contenu du répertoire
lcc4unreal/Intermediate/Build/Win64/x64du plugin vers le répertoire<project directory>/Intermediate/Build/Win64/x64du projet. - Redémarrez le moteur puis réempaquetez.
Le nom du répertoire cible de l'étape 2 est le nom du projet, pas
UnrealGame. Par exemple, pour un projet nomméMyProject, le chemin cible estMyProject/Intermediate/Build/Win64/MyProject.
Si l'erreur pointe vers d'autres fichiers : les deux répertoires ci-dessus couvrent les cas courants. Quand l'erreur mentionne un autre fichier, appliquez le même raisonnement : retrouvez ce fichier sous le répertoire Intermediate du plugin, au même chemin relatif, et copiez-le à l'emplacement correspondant du projet.
Si le répertoire Intermediate du plugin a lui aussi été nettoyé : il n'y a plus de source à copier ; retéléchargez le paquet du plugin et écrasez l'installation pour tout restaurer.
Symptôme : la compilation échoue sur un moteur personnalisé
Les paquets du plugin publiés ne conviennent qu'aux moteurs distribués officiellement par Epic. Les branches personnalisées par un éditeur, les moteurs commerciaux dérivés d'UE et les moteurs dont les sources ont été modifiées nécessitent une adaptation dédiée, voir Versions de moteur personnalisées.
Symptôme : erreur lors de l'empaquetage Android
La version actuelle ne prend pas en charge l'empaquetage direct vers la plateforme Android. Il s'agit d'une limite de compatibilité de plateforme, qu'aucune modification de la configuration d'empaquetage ne résoudra.
Pour une utilisation sur un casque VR, passez par un rendu sur PC diffusé en streaming, voir Démarrage rapide - Quest3.
Toujours pas résolu
Réunissez les informations suivantes puis contactez-nous, voir Nous contacter :
- Version du plugin et version du moteur
- Format des données et ordre de grandeur
- Fichier journal complet de l'exécution qui a posé problème, sans filtrage et sans vous limiter aux lignes d'erreur
- Étapes de reproduction
- Modèle de carte graphique et version du pilote
Pour l'emplacement des fichiers journaux et les autres détails, voir Journaux et diagnostics.