Unreal nel browser: servizio Pixel Streaming

Il servizio R47 collega il Viewer Unreal al browser usando le librerie ufficiali Epic Pixel Streaming per Unreal 5.5. Ogni lavoro BIM ottiene un processo Viewer e un signalling dedicati. Il browser riceve video e invia input; la GPU che genera le immagini è quella del server.

1. Componenti e prerequisiti

Servono il Viewer compilato con Unreal 5.5 su Windows o Linux, una GPU con encoder compatibile con Pixel Streaming, Node.js 22 o successivo, il worker engineering Nexsoon e un dominio HTTPS dedicato al player. Il PHP del sito inoltra i comandi al worker autenticato. Un hosting condiviso PHP senza GPU e senza processi persistenti non ospita questo servizio: il worker grafico deve risiedere su un PC, workstation o VPS GPU separato.

Compilare native/unreal/NexsoonViewer con Build-Windows.ps1 oppure Build-Unix.sh. La dipendenza glTFRuntime è inclusa con SHA-256 fissato. Il plugin PixelStreaming è abilitato per Win64 e Linux. La build del Viewer per Mac usa la visualizzazione locale: lo streaming R47 è predisposto per i server Windows e Linux.

2. Installare il servizio Node

cd native/pixel-streaming
npm ci
npm run build

Il lockfile fissa le dipendenze del signalling e del player. Il secondo comando genera public/player.js; il bundle generato non viene caricato nel sito BIM principale. Non pubblicare questa cartella come directory generica del server web: usare soltanto le route del servizio Node dietro proxy.

3. Configurazione privata del server GPU

Definire le seguenti variabili nell’ambiente del servizio. Usare percorsi assoluti della propria installazione e due segreti casuali diversi, di almeno 32 caratteri. Generare un segreto con node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" e ripetere per l’altro.

VariabileValore e funzione
NEXSOON_UNREAL_RUNTIMEEseguibile compilato NexsoonViewer; nessun percorso arriva dal browser.
NEXSOON_UNREAL_HOMECartella privata di scambio, identica a quella del worker.
NEXSOON_STREAM_PUBLIC_URLOrigine HTTPS del dominio dedicato, senza sottocartella.
NEXSOON_STREAM_ADMIN_TOKENSegreto per il controllo dal worker; almeno 32 caratteri.
NEXSOON_STREAM_TICKET_SECRETSecondo segreto per firmare i ticket del player; diverso dal precedente.
NEXSOON_STREAM_PORTPorta pubblica locale, predefinita 8880; ascolta solo 127.0.0.1.
NEXSOON_STREAM_ADMIN_PORTPorta amministrativa locale, predefinita 8881; non esporla nel proxy.
NEXSOON_STREAM_MAX_SESSIONSMassimo processi concorrenti, predefinito 2; dimensionarlo alla VRAM disponibile.
NEXSOON_STREAM_SESSION_SECONDSDurata massima sessione, predefinita 3600 secondi.
NEXSOON_STREAM_IDLE_SECONDSArresto senza player collegato, predefinito 120 secondi.
NEXSOON_STREAM_ICE_JSONConfigurazione JSON iceServers per STUN/TURN della propria infrastruttura.

Il servizio passa alla connessione WebRTC le impostazioni ICE. Su Internet o attraverso NAT/firewall può essere necessario TURN; predisporre credenziali temporanee del proprio servizio TURN e le porte firewall richieste. I segreti amministrativi non sono inviati al player.

Avviare con npm start. Per Linux è incluso nexsoon-stream.service: adattare utente, percorsi e EnvironmentFile al server, quindi installarlo con il gestore servizi. Lo stesso utente del worker e del Viewer deve poter leggere e scrivere la cartella lavori. Su Windows eseguire il processo con il proprio sistema di gestione servizi o una sessione controllata della workstation.

4. Collegare il worker e il sito

Nel servizio del worker engineering impostare NEXSOON_STREAM_ADMIN_URL=http://127.0.0.1:8881 e lo stesso NEXSOON_STREAM_ADMIN_TOKEN. Impostare anche NEXSOON_UNREAL_HOME alla cartella condivisa. Il controllo amministrativo accetta esclusivamente un indirizzo loopback: worker e servizio Node devono essere sulla stessa macchina. Le richieste non seguono redirect né proxy d’ambiente.

Nel gateway PHP mantenere la configurazione HTTPS autenticata del worker già prevista dall’app. I nuovi comandi streaming controllano il proprietario del lavoro prima dell’inoltro; la sola conoscenza dell’ID non concede l’accesso. Configurare il proxy HTTPS del dominio player con nginx.conf.template, inoltrando solo la porta 8880 e preservando gli header WebSocket e Origin. Non registrare i ticket nei log del proxy.

5. Utilizzo nel BIM

  1. Accedere al proprio account sul sito e aprire il progetto.
  2. Aprire il pannello Unreal e scegliere Streaming GPU dal server.
  3. Premere Verifica motore. Il servizio deve risultare configurato.
  4. Premere Trasferisci scena BIM e attendere il completamento del caricamento. Sono trasferiti geometrie visibili, materiali e ID BIM.
  5. Premere Avvia sessione streaming e poi Apri Viewer nel browser. Il player attende il signalling e il motore; il primo caricamento dipende dalla scena e dal server.
  6. Se il browser blocca la riproduzione automatica premere Avvia video.
  7. Usare Aggiorna stato scena prima di inviare selezione e camera o leggere nel BIM la selezione fatta nel Viewer.
  8. Premere Arresta sessione GPU al termine. La chiusura della scheda avvia il periodo di inattività; la sessione viene poi terminata automaticamente.

Il link di accesso è valido 5 minuti per l’apertura. Una sessione già connessa resta attiva fino all’arresto o alla durata massima. Per riconnettersi con un link scaduto, premere nuovamente Avvia sessione streaming: se il processo è ancora attivo viene restituito un nuovo ticket senza avviare un secondo Viewer.

Dopo cambiamenti al progetto trasferire una nuova scena e arrestare la sessione precedente per liberare la GPU. Una nuova scena riceve un lavoro separato; il servizio non mescola i progetti di account diversi.

6. Protezione e gestione processi

I ticket sono firmati e legati al singolo lavoro, trasmessi nel frammento del link e rimossi dalla cronologia della pagina al caricamento. Il collegamento WebSocket verifica origine, firma, scadenza, lavoro e disponibilità della sessione. È consentito un player per sessione. Gli endpoint amministrativi richiedono il bearer token. La capacità massima e la scadenza limitano i processi GPU aperti.

Il processo Unreal riceve un filtro sul solo ID assegnato e scrive il proprio heartbeat nella cartella di quel lavoro. Uno stato pronto di un altro Viewer o di una vecchia sessione non viene considerato una scena caricata. Arresto e perdita del processo di controllo chiudono anche il Viewer; il servizio Linux usa inoltre il gruppo di processi del gestore servizi.

7. Diagnostica

MessaggioVerifica
Servizio non configuratoVariabili del worker, processo Node, porta 8881 e token identico.
GPU occupataArrestare la sessione precedente o dimensionare la capacità del server.
Sessione scadutaGenerare un nuovo collegamento dal pannello.
Player connesso ma senza videoLog stream-viewer.log del lavoro, build Unreal, driver/encoder GPU, WebRTC, firewall e TURN.
Scena pronta ma comandi disabilitatiAggiornare lo stato; verificare heartbeat, ID progetto e sessione corrente.
Importazione fallitaControllare stato del lavoro e risorse GLB; ridurre la scena o correggere l’oggetto sorgente segnalato.

Lo streaming non aumenta il dettaglio di modelli semplificati: persone, veicoli e arredi mantengono geometria e materiali sorgenti. Non sostituisce il kernel di modifica BIM. Per immagini Cycles e video di rendering resta disponibile Blender.

Build e installazione desktop · Comandi del Viewer.