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. Esse recurso pode ser usado para melhorar a velocidade de execução de alguns scripts no servidor, em particular aqueles que realizam muitos cálculos numéricos sem usar muitas chamadas pesadas da biblioteca Luau ou API do Roblox.

Ativar geração de código nativo

Para ativar 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 ativa 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 mudança 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 permanecem suportados.

Alternativamente, você pode ativar 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 ativar 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 em tipos buffer, o script pode ser um bom candidato.

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

• É recomendável medir o tempo que um script ou 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ê tome decisões informadas.

• Pode ser tentador colocar o comentário --!native em cada script, só para o caso de alguns deles serem executados 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 com um uso judicioso 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 ativada, alguns deles não serão executados nativamente e podem causar desotimização ou um fallback para a execução interpretada. Isso inclui:

• Uso das chamadas obsoletas getfenv()/setfenv().
• Uso de várias funções internas do Luau, como math.asin() com argumentos não numéricos.
• Passagem de parâmetros tipados de forma inadequada para funções tipadas, por exemplo, chamando 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 que foi 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 variável dada a fim de otimizar os caminhos de código. Por exemplo, presume-se que a + b seja realizado em números, ou que uma tabela seja acessada em t.X. No entanto, dado o sobrecarregamento de operadores, 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 disparar verificações desnecessárias, resultando em uma execução de código mais lenta.

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

--!native

-- "v" é assumido como uma tabela; a função executa mais devagar devido às 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.

Além disso, note que ao depurar o 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 estão executando 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 Luau

No perfilador heap 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 pré-definido, a compilação nativa para. e o código restante é executado de forma não nativa. Isso torna essencial a escolha cuidadosa dos scripts para 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 Server através do botão de alternância cliente/servidor.
2. Invocar debug.dumpcodesize() na Command Bar.

Na janela Output, você verá o número total de scripts e funções que foram compilados nativamente até o momento da invocação, a memória consumida por 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 mostra 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 apresentadas como [anonymous] e scripts inteiros mostrados como [top level]. Na coluna final, a porcentagem é computada com relação ao limite de tamanho do código nativo. Note que o tamanho do código nativo 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 uma CPU particular 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 gerará um erro na janela Output do Studio, incluindo: