Geração de código nativo

Com o suporte do Luau para geração de código nativo, scripts do lado do servidor na sua experiência podem ser compilados diretamente nas instruções de código de máquina que as CPUs executam, ao invés do bytecode regular que a VM do Luau opera.Essa característica pode ser usada para melhorar a velocidade de execução para alguns scripts no servidor, em especial aqueles que têm muita computação numérica sem usar muitas chamadas de biblioteca Luau pesada ou da API do Roblox.

Ativar geração de código nativo

Para habilitar a geração de código nativo para um Script , adicione o comentário --!native na parte superior:¹

--!native

print("Hello from native code!")

Isso habilita a geração de código nativo para todas as funções no script e o escopo de alto nível, se for considerado rentável.Não são necessárias alterações adicionais; o comportamento dos scripts executados nativamente é exatamente o mesmo que antes e apenas o desempenho é diferente.Todas as características da linguagem Luau e todas as APIs do Roblox permanecem suportadas.

Alternativamente, você pode habilitar a geração de código nativo para uma função individual adicionando o atributo @native:

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

Melhores práticas

As seguintes dicas ajudarão você a se beneficiar melhor da geração de código nativo:

• É melhor habilitar essa característica dentro de scripts que realizam muita computação diretamente dentro do Luau.Se você tem muitas operações matemáticas em tabelas e especialmente buffer tipos, o script pode ser um bom candidato.

• Apenas as funções do script são compiladas nativamente.O código no topo externo escopo é frequentemente executado apenas uma vez e não se beneficia tanto quanto funções que são chamadas muitas vezes, especialmente aquelas que são chamadas a cada frame.

• Recomenda-se que você meda o tempo que um script ou uma função leva com e sem compilação nativa para julgar quando é melhor usá-lo.A ferramenta Perfilador de Scripts pode medir o desempenho de funções para tomar decisões informadas.

• Pode ser tentador colocar o comentário em cada script apenas no caso de alguns deles serem executados mais rapidamente, mas a geração de código nativo tem alguns inconvenientes:

  • O tempo de compilação de código é necessário, o que pode aumentar o tempo de inicialização dos servidores.
  • Memória extra é ocupada para armazenar código compilado nativamente.
  • Há um limite na quantidade total permitida de código nativamente compilado em uma experiência.

Esses problemas podem ser abordados por um uso judicioso do atributo @native.

Código para evitar

Embora todas as características se comportem da mesma forma com ou sem geração de código nativo ativada, algumas delas não serão executadas nativamente e podem causar uma de‑otimização ou um recurso a uma execução interpretada.Estes incluem:

• Uso de chamadas depreciadas getfenv() / setfenv().
• Uso de várias funções integradas do Luau, como math.asin() com argumentos não numéricos.
• Passar parâmetros mal digitados para funções tipificadas, por exemplo, chamando foo(true) quando foo é declarado como function foo(arg: string) .Lembre-se de sempre usar anotações de tipo correto .

Ao usar o Perfilador de Scripts, você pode comparar o tempo levado por uma versão regular da função versus a compilada nativamente.Se uma função dentro de um script ou marcada com não parece estar sendo executada nativamente, um ou mais fatores da lista acima podem estar ativando a desoptimização.

Usar anotações de tipo

Tentativas de geração de código nativo tentam inferir o tipo mais provável para uma variável dada para otimizar os caminhos de código.Por exemplo, é assumido que a + b seja executado em números ou que uma tabela seja acessada em t.X .Dada a sobrecarga do operador, no entanto, a e b podem ser tabelas ou Vector3 tipos, ou t pode ser um tipo de dado Roblox.

Enquanto a geração de código nativo suportará qualquer digitar, previsões erradas podem desencadear verificações desnecessárias, resultando em uma execução de código mais lenta.

Para resolver alguns problemas comuns, Luau tipo anotações em argumentos de função são verificados, mas é especialmente recomendado anotar Vector3 argumentos:

--!native

-- se "v" for assumido como uma tabela; a função funciona mais lentamente devido a verificações de tabela
local function sumComponentsSlow(v)
	return v.X + v.Y + v.Z
end

-- “v” é declarado como um Vector3; código especializado para vetores é gerado
local function sumComponentsFast(v: Vector3)
	return v.X + v.Y + v.Z
end

Ferramentas de estúdio

A seguinte ferramenta do Studio é suportada para scripts e funções .

Depuração

O diagnóstico geral de scripts é suportado, mas as visualizações para locais/valores locais podem estar incompletas e sem variáveis que estão sendo executadas nativamente a partir de quadros de chamada.

Observe também que, ao depurar código selecionado para compilação nativa, colocar pontos de interrupção desativará a execução nativa dessas funções.

Perfilador de Scripts

No Perfilador de Scripts, funções executando nativamente exibem <native> ao lado delas:

Se uma função marcada ou dentro de um script não mostrar a anotação , essa função pode não estar sendo executada nativamente devido ao posicionamento de ponto de interrupção , uso de código desencorajado ou anotações de tipo incompatíveis .

Pilha Luau

No perfilizador Luau heap, a memória tomada por funções nativas é exibida como [native] elementos no gráfico.

Análise de tamanho

Todo script compilado nativamente consome memória.Quando o tamanho do código compilado atinge um limite predefinido, a compilação nativa para de funcionar e o código restante é executado sem nativamente.Isso torna essencial escolher scripts com cuidado para a compilação nativa.

Para monitorar o tamanho do código nativo de funções e scripts individuais:

1. Certifique-se de estar na visão do Servidor através do botão cliente/servidor de alternância.
2. Invocar debug.dumpcodesize() a partir da Barra de Comando.

Na janela Saída, você verá o número total de scripts e funções que foram compilados nativamente até o ponto de invocação, o número de memória consumido pelo código nativo e o limite de tamanho de código nativo.Após o resumo, você verá uma tabela para cada script compilado nativamente em ordem decrescente de tamanho de código.

Para cada script, o resultado exibe o número de funções compiladas e o consumo de memória de código nativo.Cada função é então listada em ordem decrescente do tamanho do código nativo, com funções anônimas mostradas como [anonymous] e scripts inteiros mostrados como [top level].Na coluna final, a porcentagem é calculada em relação ao limite de tamanho de código nativo.Observe que o tamanho nativo de código de funções é relatado com precisão, mas o consumo de memória para scripts é arredondado para o tamanho da página mais próximo.

Limites e solução de problemas

Compilar código em instruções para um determinado CPU requer memória de armazenamento adicional.Além disso, otimizações para funções complexas podem levar muito tempo para serem executadas.Atingir um limite interno relatará um erro na janela Saída do Studio, incluindo: