Geração de código nativo

Com o suporte do Luau para geração de código nativo, scripts do lado do servidor em seu jogo podem ser compilados diretamente nas instruções de código de máquina que as CPUs executam, em vez de bytecode regular que a VM Luau opera. Este recurso pode ser usado para melhorar a velocidade de execução de alguns scripts no servidor, em particular aqueles que têm muitos cálculos numéricos sem usar muitas chamadas pesadas da biblioteca Luau ou da API do Roblox.

Habilitar geração de código nativo

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

--!native

print("Olá do código nativo!")

Isso habilita a geração de código nativo para todas as funções no script, e o escopo de nível superior, se considerado lucrativo. Nenhuma alteração adicional é necessária; o comportamento dos scripts que executam nativamente é exatamente o mesmo de antes e apenas o desempenho é diferente. Todos os recursos da linguagem Luau e todas as APIs do Roblox continuam sendo suportados.

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 mais da geração de código nativo:

• É melhor habilitar esse recurso dentro de scripts que realizam muitos cálculos diretamente no Luau. Se você tiver muitas operações matemáticas em tabelas e especialmente tipos buffer, o script pode ser um bom candidato.

• Apenas as funções do script são compiladas nativamente. O código no escopo externo superior é 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 quadro.

• É recomendável que você meça o tempo que um script ou uma função leva com e sem compilação nativa para julgar quando é melhor usá-la. A ferramenta Script Profiler pode medir o desempenho das funções para que você possa tomar decisões informadas.

• Pode ser tentador colocar o comentário --!native em todos os scripts, apenas para o caso de alguns deles executarem mais rápido, mas a geração de código nativo tem algumas desvantagens:

  • O tempo de compilação do 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 compilado nativamente em um jogo.

Esses problemas podem ser abordados pelo uso criterioso do atributo @native.

Código a evitar

Embora todos os recursos se comportem da mesma forma com ou sem a geração de código nativo habilitada, alguns deles não serão executados nativamente e podem causar desotimização ou um retorno à execução interpretada. Estes incluem:

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

Ao usar o Script Profiler, você pode comparar o tempo gasto por uma versão regular da função em comparação com a compilada nativamente. Se uma função dentro de um script --!native ou marcada com @native não parecer estar executando nativamente, um ou mais fatores da lista acima podem estar acionando a desotimização.

Use anotações de tipo

A geração de código nativo tenta inferir o tipo mais provável para uma determinada variável a fim de otimizar os caminhos de código. Por exemplo, assume-se que a + b é realizado em números, ou que uma tabela é acessada em t.X. Dada a sobrecarga de operadores, no entanto, a e b podem ser tabelas ou tipos Vector3, ou t pode ser um tipo de dado do Roblox.

Embora a geração de código nativo suporte qualquer tipo, previsões incorretas podem acionar verificações desnecessárias, resultando em uma execução de código mais lenta.

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

--!native

-- "v" é assumido como uma tabela; a função executa 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 do Studio

As seguintes ferramentas do Studio são suportadas para scripts --!native e funções @native.

Depuração

A depuração geral de scripts é suportada, mas as visualizações para locais/upvalues podem estar incompletas e faltar variáveis de quadros da pilha de chamadas que estão executando nativamente.

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

Script Profiler

No Script Profiler, funções que executam nativamente exibem <native> ao lado delas:

Se uma função marcada como @native ou dentro de um script --!native não mostrar a anotação <native>, essa função pode não estar executando nativamente devido à colocação de pontos de interrupção, uso de código desencorajado ou anotações de tipo incompatíveis.

Heap do Luau

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

Análise de tamanho

Cada script compilado nativamente consome memória. Quando o tamanho do código compilado atinge um limite predefinido, a compilação nativa para. e o código restante é executado de forma não nativa. 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 que você está na visualização Servidor através do botão de alternância cliente/servidor.
2. Chame debug.dumpcodesize() a partir da Barra de Comando.

Na janela Output, você verá o número total de scripts e funções que foram compilados nativamente até o ponto de invocação, a memória consumida pelo seu código nativo e o limite de tamanho do 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, a saída exibe o número de funções compiladas e o consumo de memória do código nativo. Cada função é então listada em ordem decrescente de tamanho de código nativo, com funções anônimas mostradas como [anônimo] e scripts inteiros mostrados como [nível superior]. Na coluna final, a porcentagem é calculada em relação ao limite de tamanho do código nativo. Observe que o tamanho do código nativo das 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 uma CPU específica requer memória de armazenamento adicional. Além disso, otimizações para funções complexas podem levar muito tempo para serem realizadas. Atingir um limite interno resultará em um erro na janela Output do Studio, incluindo: