Individuare per sintomo i guasti più comuni del 3DGS in UE5

Questo documento è organizzato in base al sintomo osservato e ogni voce indica le possibili cause, come verificarle e come risolverle.

Per visualizzare i log e usare gli strumenti di debug, vedere Log e diagnostica. Per le domande di consultazione (quali formati sono supportati, la differenza tra le due pipeline), vedere FAQ.

Contenuti

Fare prima queste due cose

La maggior parte dei problemi si può individuare con questi due passi, quindi eseguirli per qualsiasi sintomo.

1. Aprire l'Output Log e leggere il log del plugin. I fallimenti di caricamento, gli errori di percorso e i problemi di licenza lasciano lì informazioni chiare. Vedere Visualizzare il log del plugin.
2. Verificare che i dati siano stati caricati correttamente. Selezionare l'Actor e controllare se MetaInfo nel pannello Details ha contenuto (Total Splats maggiore di 0). Vuoto significa che i dati non sono entrati, quindi passare direttamente a Fallimenti di caricamento dei dati.

Fallimenti di caricamento dei dati

Sintomo: nulla compare dopo aver fatto clic su Load

Verificare in ordine:

Sintomo: tutto corretto nell'editor, invisibile dopo il packaging

Verificare due cose in ordine.

Primo, se è stato usato un percorso assoluto. I percorsi assoluti funzionano solo sulla macchina locale e non esistono più su un'altra. Passare a un percorso relativo, relativo alla directory Content del progetto, per esempio Scenes/Tower/meta.lcc2.

Secondo, se la directory dei dati è configurata nelle impostazioni di packaging. Le due impostazioni servono a scopi diversi, quindi scegliere in base alle esigenze:

Usare la seconda per inserire i dati LCC nel pak e la prima quando i dati devono solo essere distribuiti accanto all'output del pacchetto. Entrambe si trovano in ProjectSettings > Packaging.

Ripetere il packaging dopo averle configurate e verificare che i dati siano realmente nell'output del pacchetto. Per la configurazione dettagliata, vedere Avvio rapido.

Sintomo: il plugin non funziona dopo il packaging di un progetto Blueprint

I progetti di soli Blueprint sono supportati solo nell'editor, non per il packaging. Per il packaging serve un progetto C++.

Sintomo: la posizione geografica è errata, la modalità GIS non ha effetto

Verificare questi punti:

• Se i dati contengono informazioni RTK. Usare GetMetaInfo().IsRTK() per verificarlo; il log che mostra This lcc does not have RTK information! significa che i dati non hanno informazioni geografiche
• Quando si abilita da codice, chiamare SetGeoPlacement(true), che ricarica automaticamente così l'impostazione ha effetto. Assegnare direttamente bEnableGeoPlace non innesca un ricaricamento
• Usare GeoLocationOffset per la regolazione fine quando la posizione è spostata

Per i passi di configurazione con Cesium, vedere Integrazione con plugin di terze parti e del motore.

Sintomo: crash durante la navigazione di dati LCC2 molto grandi

Sulla v1.0.0 si tratta di un difetto noto di quella versione (un overrun del GPU Buffer). Aggiornare alla v2.x o superiore.

Sintomo: errore relativo agli array durante il caricamento di un PLY grande

Difetto noto della v3.0.0, corretto dalla v3.3.0 in poi; aggiornare la versione.

Inoltre, quando un PLY non ha armoniche sferiche, i file oltre 2 GB possono non caricarsi, quindi si consiglia la conversione nel formato LCC2.

Nulla visualizzato o visualizzato in parte

Sintomo: l'Actor è nella scena ma non si vede alcun contenuto

Sintomo: il contenuto lontano è assente e compare solo avvicinandosi

È il risultato normale del LOD e del limite di distanza, non un guasto. Per visualizzare anche il contenuto lontano:

• Aumentare Max Distance, a costo di prestazioni inferiori
• Ridurre Level Factor così che alla stessa distanza venga usata una precisione maggiore
• La nebbia può aiutare a nascondere il limite della distanza

Sintomo: buchi al bordo dello schermo ruotando rapidamente la vista

Il precaricamento dei nodi non tiene il passo con il cambio di vista. La pipeline LCC può abilitare Add Extra Preload Nodes, che aggiunge nodi di precaricamento extra al prezzo di più nodi da renderizzare.

Sintomo: SceneCapture o la minimappa sono vuoti

Abilitare prima SceneCaptureComponent Support nelle impostazioni del progetto. È disabilitato per impostazione predefinita e ha un leggero costo prestazionale.

Per impostare da codice la strategia di rendering di un SceneCapture separatamente, vedere SetSceneCaptureRenderMode; questo gruppo di interfacce funziona solo sulla pipeline LCC.

Sintomo: il 3DGS è occluso dalla superficie dell'acqua

Causato dalla gestione della profondità del materiale single layer water. Abilitare SingleLayerWater Support, vedere Single Layer Water Support.

Problemi di qualità dell'immagine

Sintomo: ghosting e scie durante il movimento

Causato dal metodo di anti-aliasing. TSR e TAA si basano sui fotogrammi precedenti per l'accumulo temporale, quindi un 3DGS in movimento lascia facilmente dietro di sé il fotogramma precedente.

Provarli in ordine e trovare l'equilibrio tra qualità e ghosting:

None → FXAA → MSAA → TAA → TSR

Quando la scena contiene solo 3DGS si può impostare direttamente None, cosa che elimina il ghosting e risparmia il costo dell'anti-aliasing. Per il valore predefinito di ogni pipeline e dove impostarlo, vedere Parametri di prestazione.

Sintomo: l'immagine sfarfalla e i bordi tremolano

Provare in ordine di beneficio:

1. Controllare il metodo di anti-aliasing. È la causa più comune, e per la pipeline LCC2 si consiglia TSR, vedere Parametri di prestazione.
2. Pipeline LCC: ridurre Sort Factor per ordinare più spesso. Quando la frequenza di ordinamento è troppo bassa, l'ordine delle trasparenze si aggiorna solo ogni pochi fotogrammi, cosa che si manifesta come un leggero tremolio.
3. Controllare Small Splat Threshold; un valore troppo grande rende granuloso il fondo.
4. Per le strutture fini che sfarfallano mentre la camera si avvicina e si allontana, provare ad abilitare Mip Filter, che applica un filtro passa-basso con compensazione dell'opacità ed è più stabile a scale diverse. .ply / .spz / .sog lo hanno disabilitato per impostazione predefinita.

Sintomo: l'immagine ha buchi e appare rarefatta

SplatScale è impostato su un valore troppo basso. Il valore predefinito 1.0 è il limite superiore; ridurlo abbassa l'overdraw e aumenta il frame rate, ma i quad più piccoli lasciano scoperti dei buchi. Riportarlo un po' più in alto.

Sintomo: i colori appaiono grigi e piatti

Intervenire con i parametri di colore, vedere Impostazioni visive. L'approccio consueto consiste nell'aumentare leggermente Contrast, oppure nello schiarire le zone scure con Gamma. Per l'interfaccia di codice, vedere Regolazione del colore.

Sintomo: giunzioni evidenti nell'immagine (pipeline LCC)

La versione 5.0 e superiori del file LCC gestisce le giunzioni automaticamente. Per i dati delle versioni precedenti, abilitare manualmente Taglio delle giunzioni, che corrisponde alla proprietà bEnableSeamCutting.

Sintomo: compare una linea attraverso la scena

Controllare la scala dell'Actor. La famiglia di Actor LCC (ALCCActor, ALCC2Actor, ASogActor, ASpzActor, APlyActor) supporta solo la scalatura uniforme.

Non usare una scalatura non uniforme come questa:

• Con valori negativi, per esempio (-1, 1, 1)
• Con assi diversi tra loro, per esempio (2, 1, 3)

I tre assi devono restare uguali, per esempio (1, 1, 1) o (2, 2, 2). La scalatura non uniforme causa anomalie di rendering che si manifestano come una linea nell'immagine.

Problemi di illuminazione

Sintomo: sovraesposizione dopo il passaggio a Lit

I colori dei dati acquisiti hanno già l'illuminazione del luogo di acquisizione incorporata, e le luci della scena ne aggiungono un altro strato sopra.

• Pipeline LCC2: ridurre la luminosità originale con LightingScale, vedere Normali e illuminazione
• Verificare se l'intensità dell'illuminazione della scena sia troppo alta

Sintomo: nessuna resa del rilievo in modalità Lit, l'immagine appare piatta

È il comportamento previsto. I dati 3DGS non hanno normali geometriche, e Fixed, ViewFacing e Hemispherical costruiscono tutti le normali per approssimazione, quindi possono produrre solo variazioni di luminosità complessiva e nessuno di essi può produrre una resa che segue il rilievo. Per la definizione di ogni modalità, vedere ELCC2NormalGenerationMode.

Solo ProxyMesh può produrre una vera resa del rilievo. Richiede la realizzazione e il posizionamento di una mesh proxy e richiede una licenza. Vedere Proxy Mesh e Normali e illuminazione.

La differenza tra le tre modalità approssimate riguarda il modo in cui la luminosità complessiva cambia con illuminazione e vista, non la presenza della resa del rilievo:

• Fixed: tutta l'area condivide un'unica normale fissa, completamente stabile durante il movimento della camera
• ViewFacing: le normali seguono la camera, quindi la luminosità complessiva cambia ruotando la vista
• Hemispherical: le normali sono mappate dalla posizione su schermo su un emisfero fisso, quindi la luminosità complessiva varia in modo più uniforme rispetto alle altre due mentre una luce direzionale ruota

Sintomo: la modalità ProxyMesh è impostata ma non ha effetto

Vedere Proxy Mesh.

Sintomo: la resa del rilievo compare nel posto sbagliato

La mesh proxy si discosta troppo dalla superficie reale del 3DGS. Migliorare l'aderenza della mesh proxy, oppure passare a una modalità di normali approssimate, che non ha resa del rilievo ma è più stabile.

Sintomo: le ombre di ProxyMesh compaiono solo da vicino e scompaiono in lontananza

Le ombre vengono tagliate dalla distanza. È un problema del motore, non un difetto del plugin.

Soluzione: selezionare l'Actor ProxyMesh e disattivare e riattivare Far Shadow per ripristinare le ombre complete. La proprietà si trova nella categoria Lighting di StaticMeshComponent.

Sintomo: ombre anomale enormi in modalità Lit

Le modalità di normali approssimate producono anomalie ad alcuni angoli di illuminazione. Provare in ordine:

1. Cambiare NormalMode per trovare quale modalità si comporta correttamente
2. Regolare l'angolo della luce direzionale
3. Passare alla modalità ProxyMesh con una mesh proxy ben aderente, che dà il risultato migliore

Sintomo: i colori sono cambiati dopo l'abilitazione delle ombre

È il comportamento previsto. Una volta che il 3DGS riceve illuminazione esterna, i suoi colori cambiano con la sorgente luminosa, quindi regolare colore e intensità della luce direzionale.

Sintomo: la luminosità non è regolabile, tutta la scena è scura

Quando il progetto usa un plugin di composizione come Composure, disattivare le opzioni relative alla post-elaborazione sul Component e controllare invece l'esposizione tramite un Post Process Volume.

Per le impostazioni relative all'esposizione, vedere Impostazioni visive.

Sintomo: gli effetti Niagara non sono visibili sul 3DGS

La pipeline LCC2 produce la profondità, quindi l'occlusione degli effetti è corretta e questo problema normalmente non si verifica.

Solo la pipeline LCC (dati .lcc) può presentarlo, perché non produce profondità e l'ordine delle trasparenze deve essere deciso dalla priorità di ordinamento. La soluzione consiste nell'aumentare Translucent Sort Priority sul Niagara System così che venga renderizzato sopra il 3DGS.

Sintomo: contenuto disordinato attorno all'esterno della scena

Sono i dati dell'ambiente. Cambiare LoadMode da Both a OnlyMain per renderizzare solo la parte principale.

Sintomo: cambiare la modalità di illuminazione non produce alcun effetto

SetLightMode non ha effetto in modalità nuvola di punti: salta l'assegnazione e stampa un avviso. Tornare prima alla modalità 3DGS.

Sintomo: nessun effetto di illuminazione dopo il passaggio alla modalità Lit

La pipeline di rendering forward (Forward Shading) non dispone del GBuffer, pertanto la rilluminazione non è disponibile. Impostare LightMode su Lit non avrà alcun effetto.

Passare alla pipeline di rendering differito (Deferred Shading) per utilizzare correttamente la modalità Lit. Deselezionare Project Settings > Rendering > Forward Shading. Nota: il template VR di UE abilita Forward Shading per impostazione predefinita ed è necessario disattivarlo manualmente.

Le modifiche ai parametri non hanno effetto

Sintomo: i valori sotto Performance sono stati cambiati ma nulla è cambiato

Ogni parametro ha una casella alla sua sinistra e, mentre non è spuntata, il plugin usa il proprio valore predefinito interno e il valore inserito non ha effetto. È la trappola più comune di tutte.

Per il valore predefinito interno di ogni parametro, vedere Parametri di prestazione.

Sintomo: cambiare i parametri del caricamento completo non produce alcun effetto

Use Full Load e Full Load Splat Number vengono valutati al momento del caricamento, quindi dopo averli cambiati i dati vanno ricaricati.

Per la differenza tra i due metodi di caricamento, vedere Rendering.

Sintomo: cambiare a runtime le proprietà di un volume di taglio o di un piano di sezione non produce alcun effetto

bEnabled, Mode e VolumeType non hanno un setter, quindi dopo averli assegnati a runtime va chiamato Refresh() su quell'Actor. Lo stesso vale per la modifica a runtime del transform (posizione, rotazione).

Modificare le proprietà nel pannello Details dell'editor aggiorna automaticamente e non richiede alcuna chiamata manuale.

Vedere ALCCClippingVolume.

Sintomo: le armoniche sferiche sono abilitate ma l'immagine non è cambiata

• I dati possono essere di tipo Portable, che non contiene armoniche sferiche. Verificarlo con CanSetShcoef(); per le definizioni dei tipi, vedere EFileType
• SetUseShcoef viene ignorato senza avvisi in modalità nuvola di punti, quindi tornare prima al 3DGS
• LCC2 può disabilitare completamente le armoniche sferiche con SetUseShcoef

Sintomo: sono stati aggiunti molti volumi di taglio ma solo alcuni hanno effetto

L'edizione gratuita limita ogni tipo a 50. Il log lo indica esplicitamente: Unlicensed: enabled clipping volumes limited to 50 .... Per le licenze, vedere Edizioni e licenze.

Problemi di prestazioni

Per il flusso di lavoro completo di regolazione di un frame rate basso, vedere Guida alle prestazioni; questa sezione elenca solo le verifiche rapide.

Sintomo: frame rate basso

Verificare prima se il collo di bottiglia sia il 3DGS. Usare stat unit per leggere Game / Draw / GPU, poi stat XGrids per leggere il costo di LCC stesso. Quando la quota di LCC è bassa, il problema è altrove nella scena (illuminazione, post-elaborazione, logica Blueprint) e regolare i parametri LCC non porta alcun miglioramento.

Una volta confermato il 3DGS come causa, regolare in ordine di beneficio:

1. Aumentare Level Factor (il beneficio più evidente)
2. Ridurre Max Distance
3. Ridurre Max Splat Num
4. Aumentare Start Level per saltare il Level più fine
5. Disabilitare le armoniche sferiche
6. Passare alla modalità nuvola di punti se necessario

Sintomo: l'uso della memoria video è troppo alto

• Aumentare Level Factor
• Ridurre Max Splat Num
• Regolare LCC2 GPU Memory Budget sulla pipeline LCC2
• Regolare la soglia di rilascio Max GPU Usage Percetage For Free

Per le regole di allocazione della memoria video e il meccanismo di rilascio automatico, vedere Rendering. I formati a file singolo (.sog / .spz / .ply) si caricano interamente in una volta, quindi il loro uso della memoria video è costante e non cambia con la vista, vedere Limiti di caricamento dei formati a file singolo.

Sintomo: scatti durante il caricamento

• Abilitare le collisioni la prima volta ha un costo di baking una volta sola, quindi abilitarle durante la fase di caricamento e non nel mezzo dell'interazione del giocatore
• Ridurre Max Load Collision Distance per caricare solo l'estensione necessaria
• Regolare la configurazione dei thread, vedere Parametri di prestazione

Sintomo: occlusione errata quando più 3DGS si compenetrano

• Pipeline LCC: abilitare l'ordinamento delle trasparenze tra più Actor
• Pipeline LCC2: regolare la soglia di profondità per cambiare dove viene scritta la profondità

Collisioni e navigazione

Sintomo: i line trace non colpiscono il 3DGS

Il log che mostra There is neither collision.bin nor collision.lci in the folder significa che nella directory dei dati non c'è alcun file di collisione.

LCC1 ha un altro insieme di interfacce di test dei raggi contro le posizioni della nuvola di punti, ma non sono sufficientemente testate, quindi si consiglia di usare le collisioni insieme ai test dei raggi del motore, vedere Test dei raggi di ULCCComponent.

Sintomo: il personaggio cade proprio all'avvio

Le collisioni vengono caricate dinamicamente a blocchi, quindi i dati di collisione possono non essere ancora costruiti all'avvio del gioco, e il personaggio cade quando non ha collisioni sotto i piedi.

Come gestirlo:

• Posizionare PlayerStart un po' sopra il terreno
• Oppure ritardare il movimento del personaggio di alcuni secondi
• Abilitare le collisioni durante la fase di caricamento e non dopo l'inizio dell'interazione del giocatore

Sintomo: il personaggio attraversa il terreno o cade dopo essersi allontanato di una certa distanza

Le collisioni vengono caricate in streaming in base alla distanza, quindi le aree oltre l'estensione di caricamento non hanno corpi di collisione. Aumentare Max Load Collision Distance(m) per coprire l'area di attività del personaggio.

Le collisioni possono anche non tenere il passo quando il personaggio si muove troppo velocemente, cosa che si attenua allo stesso modo aumentando la distanza di caricamento.

Sintomo: la NavMesh non viene generata affatto

Per il flusso di lavoro completo, vedere Supporto del Navigation System.

Crash

Sintomo: crash dopo un errore di assertion ArraySliceIndex

L'errore si presenta così:

Assertion failed: ArraySliceIndex >= 0

La causa è che la versione corrente non supporta il formato Adaptive GBuffer di Substrate.

Soluzione:

1. Aprire ProjectSettings > Rendering e trovare Substrate GBuffer Format (Project).
2. Cambiare il valore in BlendableGBuffer. È il valore predefinito del motore.
3. Riavviare il motore.

AdaptiveGBuffer è un formato notoriamente incompatibile, mentre BlendableGBuffer funziona correttamente.

Problemi di licenza

Controllare prima Status nel pannello del plugin: un segno di spunta verde significa che la licenza è a posto e le funzionalità dell'edizione Pro sono disponibili. Qualsiasi cosa diversa da un segno di spunta verde significa che la licenza non ha avuto effetto, quindi leggere il log per verificarne il motivo.

Le informazioni sulle licenze nel log sono piuttosto esplicite, quindi agire in base a quanto indicato:

Per il flusso di lavoro delle licenze, vedere Edizioni e licenze.

Build e packaging

Sintomo: binari mancanti o build del modulo fallita

Quando compare uno degli errori seguenti, rigenerare e ricompilare il progetto seguendo i passi di questa sezione:

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 causa è che dopo l'aggiunta del plugin a un progetto C++ il motore rileva i nuovi moduli ma manca l'output di build corrispondente. Procedere così:

1. Chiudere il progetto.
2. Individuare il file *.uproject del progetto.
3. Fare clic destro su *.uproject e selezionare Generate Visual Studio project files.
4. Attendere il completamento della rigenerazione del progetto VS.
5. Fare doppio clic su *.sln per aprire Visual Studio.
6. Fare clic destro sul progetto in Solution Explorer e selezionare Set as Startup Project per assicurarsi che sia il progetto di avvio.
7. Verificare che la configurazione sia Development Editor e Win64.
8. Fare clic su Debug > Start Without Debugging per avviare il progetto.
9. Una volta superata la build, il progetto si apre normalmente. In seguito basta fare doppio clic su *.uproject e questa procedura non serve ogni volta.

Quando fallisce ancora dopo i passi precedenti, eliminare prima la directory Intermediate del progetto, poi ripetere dal passo 3.

Per i passi di installazione del plugin, vedere Avvio rapido.

Sintomo: il packaging fallisce

Verificare prima questi tre punti:

• Full Rebuild in ProjectSettings > Packaging deve restare disabilitato, e non eseguire Rebuild in VS. Il plugin non supporta né l'uno né l'altro, vedere Avvio rapido
• Verificare che sia usato un progetto C++, perché i progetti Blueprint non possono essere pacchettizzati
• Verificare che la versione del motore sia nell'intervallo supportato (UE 5.4 ~ 5.8)

Per errori specifici, vedere le due sezioni seguenti.

Sintomo: precompiled manifest mancante durante il packaging

L'errore si presenta così:

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.

Perché si verifica: i file citati nell'errore vengono distribuiti con il plugin e si trovano nella sua directory Intermediate. Eseguire Full Rebuild in ProjectSettings > Packaging, oppure Rebuild in VS, fa sì che il motore pulisca la directory Intermediate e cancelli con essa quegli output precompilati.

LCC4Unreal è un plugin binario senza codice sorgente, quindi gli output cancellati non possono essere ricompilati e si possono ripristinare solo dal pacchetto del plugin. Per questo motivo evitare entrambe le operazioni.

Come risolverlo:

1. Verificare che Full Rebuild in ProjectSettings > Packaging sia disabilitato e non eseguire Rebuild in VS.
2. Copiare il contenuto della directory del plugin lcc4unreal/Intermediate/Build/Win64/UnrealGame in <directory del progetto>/Intermediate/Build/Win64/<nome del progetto>.
3. Copiare il contenuto della directory del plugin lcc4unreal/Intermediate/Build/Win64/x64 in <directory del progetto>/Intermediate/Build/Win64/x64.
4. Riavviare il motore e ripetere il packaging.

Nota: il nome della directory di destinazione al passo 2 è il nome del progetto, non UnrealGame. Per un progetto chiamato MyProject, il percorso di destinazione è MyProject/Intermediate/Build/Win64/MyProject.

Se l'errore indica altri file: le due directory precedenti coprono i casi più comuni. Quando l'errore menziona un altro file, procedere allo stesso modo: trovare quel file nella directory Intermediate del plugin allo stesso percorso relativo e copiarlo nella posizione corrispondente del progetto.

Se anche la directory Intermediate del plugin è stata pulita: non resta nulla da cui copiare, quindi scaricare di nuovo il pacchetto del plugin ed estrarlo sopra i file esistenti per ripristinarli.

Sintomo: la build fallisce su un motore personalizzato

I pacchetti del plugin distribuiti funzionano solo con i motori pubblicati da Epic. I branch personalizzati dai fornitori, i motori commerciali derivati da UE e i motori con codice sorgente modificato localmente richiedono tutti una build personalizzata, vedere Versioni personalizzate del motore.

Sintomo: errori durante il packaging per Android

La versione corrente non supporta il packaging diretto per la piattaforma Android. È una limitazione di compatibilità della piattaforma e non si può risolvere cambiando la configurazione di packaging.

Per usarlo su un dispositivo VR, eseguirlo su PC e usare lo streaming, vedere Avvio rapido - Quest3.

Problema ancora irrisolto

Raccogliere le informazioni seguenti e contattarci, vedere Contattaci:

• Versione del plugin e versione del motore
• Formato e dimensione approssimativa dei dati
• Il file di log completo dell'esecuzione in cui il problema si è verificato, non filtrato e non solo le righe di errore
• Passi per riprodurre il problema
• Modello della scheda grafica e versione del driver

Per la posizione del file di log e altri dettagli, vedere Log e diagnostica.