Generazione di codice nativo

Con il supporto Luau per la generazione di codice nativo, gli script lato server nel tuo gioco possono essere compilati direttamente nelle istruzioni di codice macchina che le CPU eseguono, piuttosto che nel bytecode regolare su cui opera il VM Luau. Questa funzionalità può essere utilizzata per migliorare la velocità di esecuzione di alcuni script sul server, in particolare quelli che effettuano molti calcoli numerici senza utilizzare troppe chiamate pesanti alle librerie Luau o alle API di Roblox.

Abilitare la generazione di codice nativo

Per abilitare la generazione di codice nativo per un Script, aggiungi il commento --!native nella parte superiore:¹

--!native

print("Ciao dal codice nativo!")

Questo abilita la generazione di codice nativo per tutte le funzioni nello script e l'ambito di primo livello, se considerato conveniente. Non sono necessarie ulteriori modifiche; il comportamento degli script eseguiti nativamente è esattamente lo stesso di prima e solo le prestazioni sono diverse. Tutte le funzionalità del linguaggio Luau e tutte le API di Roblox rimangono supportate.

In alternativa, puoi abilitare la generazione di codice nativo per una funzione individuale aggiungendo l'attributo @native:

@native
local function f(x)
  return (x + 1)
end

Pratiche migliori

I seguenti suggerimenti ti aiuteranno a beneficiare di più dalla generazione di codice nativo:

• È meglio abilitare questa funzionalità all'interno di script che eseguono molti calcoli direttamente in Luau. Se hai molte operazioni matematiche su tabelle e specialmente su tipi buffer, lo script potrebbe essere un buon candidato.

• Solo le funzioni dello script vengono compilate nativamente. Il codice nell'ambito esterno di primo livello viene spesso eseguito solo una volta e non beneficia quanto le funzioni che vengono chiamate molte volte, specialmente quelle chiamate in ogni frame.

• È consigliato misurare il tempo impiegato da uno script o da una funzione con e senza compilazione nativa per giudicare quando è meglio usarlo. Lo strumento Script Profiler può misurare le prestazioni delle funzioni per prendere decisioni informate.

• Potrebbe essere allettante inserire il commento --!native in ogni script nel caso in cui alcuni di essi vengano eseguiti più velocemente, ma la generazione di codice nativo ha alcuni svantaggi:

  • È necessario il tempo di compilazione del codice, il che può aumentare il tempo di avvio dei server.
  • Una memoria extra viene occupata per memorizzare il codice compilato nativamente.
  • C'è un limite sulla quantità totale di codice compilato nativamente consentito in un gioco.

Questi problemi possono essere affrontati con un utilizzo giudizioso dell'attributo @native.

Codice da evitare

Sebbene tutte le funzionalità si comportino allo stesso modo con o senza generazione di codice nativo abilitata, alcune di esse non verranno eseguite nativamente e potrebbero causare de-ottimizzazione o un ritorno all'esecuzione interpretata. Questi includono:

• Uso delle chiamate deprecated getfenv()/setfenv().
• Uso di varie funzioni integrate Luau come math.asin() con argomenti non numerici.
• Passaggio di parametri di tipo errato a funzioni tipizzate, ad esempio chiamando foo(true) quando foo è dichiarato come function foo(arg: string). Ricorda di utilizzare sempre le corrette annotazioni di tipo.

Quando si utilizza lo Script Profiler, puoi confrontare il tempo impiegato da una versione regolare della funzione con quella compilata nativamente. Se una funzione all'interno di uno script --!native o contrassegnata con @native non appare come se stesse eseguendo nativamente, uno o più fattori dall'elenco sopra potrebbero attivare la de-ottimizzazione.

Usa le annotazioni di tipo

La generazione di codice nativo cerca di inferire il tipo più probabile per una determinata variabile al fine di ottimizzare i percorsi di codice. Ad esempio, si presume che a + b venga eseguito su numeri, o che una tabella venga accessibile in t.X. Tuttavia, dato il sovraccarico degli operatori, a e b potrebbero essere tabelle o tipi Vector3, o t potrebbe essere un tipo di dato Roblox.

Sebbene la generazione di codice nativo supporti qualsiasi tipo, le previsioni errate possono attivare controlli inutili, risultando in un'esecuzione del codice più lenta.

Per risolvere alcuni problemi comuni, le annotazioni di tipo Luau sugli argomenti delle funzioni vengono verificate, ma è particolarmente consigliato annotare gli argomenti di tipo Vector3:

--!native

-- "v" è presunto una tabella; la funzione funziona più lentamente a causa dei controlli della tabella
local function sumComponentsSlow(v)
	return v.X + v.Y + v.Z
end

-- "v" è dichiarato essere un Vector3; il codice specializzato per i vettori viene generato
local function sumComponentsFast(v: Vector3)
	return v.X + v.Y + v.Z
end

Strumenti di Studio

I seguenti strumenti di Studio sono supportati per gli script --!native e le funzioni @native.

Debugging

Il debugging generale degli script è supportato, ma le visualizzazioni per le variabili locali/upvalues possono essere incomplete e mancare di variabili dai frame dello stack di chiamate che vengono eseguiti nativamente.

Si noti anche che quando si esegue il debug del codice selezionato per la compilazione nativa, posizionare i punti di interruzione disabiliterà l'esecuzione nativa per quelle funzioni.

Script Profiler

Nel Script Profiler, le funzioni eseguite nativamente visualizzano <native> accanto a loro:

Se una funzione contrassegnata con @native o all'interno di uno script --!native non mostra l'annotazione <native>, quella funzione potrebbe non essere eseguita nativamente a causa della posizione di un punto di interruzione, dell'uso di codice sconsigliato, o di annotazioni di tipo non corrispondenti.

Heap Luau

Nell'heap Luau profiler, la memoria occupata dalle funzioni native viene visualizzata come elementi [native] nel grafico.

Analisi delle dimensioni

Ogni script compilato nativamente consuma memoria. Quando la dimensione del codice compilato raggiunge un limite predefinito, la compilazione nativa si interrompe e il codice rimanente viene eseguito non nativamente. Questo rende essenziale scegliere con attenzione gli script per la compilazione nativa.

Per monitorare la dimensione del codice nativo di singole funzioni e script:

1. Assicurati di essere nella visualizzazione Server tramite il pulsante client/server toggle.
2. Richiama debug.dumpcodesize() dalla Command Bar.

Nella finestra Output, vedrai il numero totale di script e funzioni che sono state compilate nativamente fino al momento dell'invocazione, la memoria consumata dal loro codice nativo e il limite di dimensione del codice nativo. Dopo il riepilogo, vedrai una tabella per ogni script compilato nativamente in ordine decrescente di dimensione del codice.

Per ogni script, l'output visualizza il numero di funzioni compilate e il consumo di memoria del codice nativo. Ogni funzione è quindi elencata in ordine decrescente di dimensione del codice nativo, con funzioni anonime mostrate come [anonymous] e interi script mostrati come [top level]. Nella colonna finale, la percentuale è calcolata rispetto al limite di dimensione del codice nativo. Nota che la dimensione del codice nativo delle funzioni è riportata con precisione, ma il consumo di memoria degli script è arrotondato alla dimensione della pagina più vicina.

Limiti e risoluzione dei problemi

Compilare il codice in istruzioni per una particolare CPU richiede ulteriore memoria di archiviazione. Inoltre, le ottimizzazioni per funzioni complesse possono richiedere troppo tempo per essere eseguite. Raggiungere un limite interno segnalerà un errore nella finestra Output di Studio, incluso: