Generazione di codice nativo

Con il supporto di 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 hanno molte operazioni di calcolo numerico senza utilizzare troppe chiamate pesanti alle librerie Luau o all'API di Roblox.

Abilitare la generazione di codice nativo

Per abilitare la generazione di codice nativo per un Script, aggiungi il commento --!native in cima:¹

--!native

print("Ciao dal codice nativo!")

Questo abilita la generazione di codice nativo per tutte le funzioni nello script e per lo scope di livello superiore, se ritenuto proficuo. Non sono necessarie ulteriori modifiche; il comportamento degli script che vengono 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 singola funzione aggiungendo l'attributo @native:

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

Migliori pratiche

I seguenti suggerimenti ti aiuteranno a trarre il massimo vantaggio dalla generazione di codice nativo:

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

• Solo le funzioni dello script vengono compilate nativamente. Il codice nello scope esterno di livello superiore viene spesso eseguito solo una volta e non beneficia tanto quanto le funzioni che vengono chiamate molte volte, specialmente quelle che vengono chiamate ad ogni frame.

• Si consiglia di misurare il tempo che uno script o una funzione impiega con e senza compilazione nativa per giudicare quando è meglio utilizzarla. Lo strumento Script Profiler può misurare le prestazioni delle funzioni per prendere decisioni informate.

• Potrebbe essere allettante posizionare 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 un tempo di compilazione del codice che può aumentare il tempo di avvio dei server.
  • Viene occupata memoria extra 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 uso 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 deprecate getfenv()/setfenv().
• Uso di varie funzioni integrate di Luau come math.asin() con argomenti non numerici.
• Passaggio di parametri di tipo improprio a funzioni tipizzate, ad esempio chiamando foo(true) quando foo è dichiarata come function foo(arg: string). Ricorda di utilizzare sempre le corrette annotazioni di tipo.

Quando utilizzi lo Script Profiler, puoi confrontare il tempo impiegato da una versione regolare della funzione rispetto a quella compilata nativamente. Se una funzione all'interno di uno script --!native o contrassegnata con @native non sembra essere eseguita 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 data variabile al fine di ottimizzare i percorsi del codice. Ad esempio, si presume che a + b venga eseguito su numeri, o che una tabella venga accessibile in t.X. Tuttavia, data l'overloading degli operatori, a e b potrebbero essere tabelle o tipi Vector3, o t potrebbe essere un tipo di dato di Roblox.

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

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

--!native

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

-- "v" è dichiarato essere un Vector3; viene generato codice specializzato per i vettori
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 variabili locali/upvalues potrebbero essere incomplete e mancare di variabili dai frame dello stack di chiamata che vengono eseguiti nativamente.

Nota anche che quando si esegue il debugging del codice selezionato per la compilazione nativa, posizionare breakpoint disabiliterà l'esecuzione nativa per quelle funzioni.

Script Profiler

Nel Script Profiler, le funzioni che vengono eseguite nativamente mostrano <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 dei breakpoint, dell'uso di codice sconsigliato o di annotazioni di tipo non corrispondenti type annotations.

Heap di Luau

Nell'analizzatore heap di Luau, 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 ferma 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 di commutazione client/server.
2. Invoca debug.dumpcodesize() dalla Command Bar.

Nella finestra Output, vedrai il numero totale di script e funzioni che sono stati compilati nativamente fino al punto di invocazione, la memoria consumata dal loro codice nativo e il limite della 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 mostra 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 della dimensione del codice nativo. Nota che la dimensione del codice nativo delle funzioni è riportata con precisione, ma il consumo di memoria per gli script è arrotondato alla dimensione della pagina più vicina.

Limiti e risoluzione dei problemi

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