Generación de código nativo

Con el soporte de Luau para la generación de código nativo, los scripts¹ en tu juego pueden ser compilados directamente en las instrucciones de código de máquina que ejecutan las CPU, en lugar de en el bytecode regular que opera la VM de Luau. Esta característica puede mejorar la velocidad de ejecución para algunos scripts soportados, particularmente aquellos con muchos cálculos numéricos y pocas llamadas a bibliotecas pesadas de Luau o APIs de Roblox.

¹ La generación de código nativo solo es compatible con scripts del lado del servidor y scripts del lado del cliente en dispositivos Android. En el futuro, se pueden soportar más dispositivos.

Habilitar la generación de código nativo

Para habilitar la generación de código nativo para un Script, agrega el --!native comentario en la parte superior:²

--!native

print("¡Hola desde el código nativo!")

Esto habilita la generación de código nativo para todas las funciones en el script, y el ámbito de nivel superior, si se considera rentable. No se requieren cambios adicionales; el comportamiento de los scripts que se ejecutan de forma nativa es exactamente el mismo que antes y solo la performance es diferente. Todas las características del lenguaje Luau y todas las APIs de Roblox siguen siendo compatibles.

Alternativamente, puedes habilitar la generación de código nativo para una función individual agregando el atributo @native:

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

Mejores prácticas

Los siguientes consejos te ayudarán a beneficiarte más de la generación de código nativo:

• Es mejor habilitar esta característica dentro de scripts que realizan muchos cálculos directamente en Luau. Si tienes muchas operaciones matemáticas en tablas y especialmente tipos buffer, el script puede ser un buen candidato.

• Solo las funciones del script se compilan de forma nativa. El código en el ámbito externo superior a menudo se ejecuta solo una vez y no se beneficia tanto como las funciones que se llaman muchas veces, especialmente aquellas que se llaman cada cuadro.

• Se recomienda medir el tiempo que toma un script o una función con y sin compilación nativa para juzgar cuándo es mejor usarla. La herramienta Script Profiler puede medir el rendimiento de las funciones para tomar decisiones informadas.

• Puede ser tentador colocar el comentario --!native en cada script por si acaso algunos de ellos se ejecutan más rápido, pero la generación de código nativo tiene algunas desventajas:

  • Se requiere tiempo de compilación de código, lo que puede aumentar el tiempo de inicio de los servidores.
  • Se ocupa memoria adicional para almacenar el código compilado de forma nativa.
  • Hay un límite en la cantidad total permitida de código compilado de forma nativa en un juego.

Estos problemas se pueden abordar mediante un uso juicioso del atributo @native.

Código a evitar

Si bien todas las características se comportarán igual con o sin la generación de código nativo habilitada, algunas de ellas no se ejecutarán de forma nativa y podrían causar desoptimización o un retroceso a la ejecución interpretada. Estos incluyen:

• Uso de llamadas obsoletas getfenv()/setfenv().
• Uso de varias funciones integradas de Luau como math.asin() con argumentos no numéricos.
• Pasar parámetros de tipo incorrecto a funciones tipadas, por ejemplo, llamar a foo(true) cuando foo se declara como function foo(arg: string). Recuerda siempre usar las anotaciones de tipo correctas.

Al usar el Script Profiler, puedes comparar el tiempo que toma una versión regular de la función frente a la que se compila de forma nativa. Si una función dentro de un --!native script o marcada con @native no parece estar ejecutándose de forma nativa, uno o más factores de la lista anterior pueden estar provocando la desoptimización.

Usa anotaciones de tipo

La generación de código nativo intenta inferir el tipo más probable para una variable dada con el fin de optimizar las rutas de código. Por ejemplo, se asume que a + b se realiza sobre números, o que se accede a una tabla en t.X. Sin embargo, dado el sobrecargado de operadores, a y b pueden ser tablas o tipos Vector3, o t puede ser un tipo de dato de Roblox.

Si bien la generación de código nativo admitirá cualquier tipo, las predicciones incorrectas pueden provocar verificaciones innecesarias, lo que resulta en una ejecución de código más lenta.

Para resolver algunos problemas comunes, se verifican las anotaciones de tipo de Luau en los argumentos de las funciones, pero se recomienda especialmente anotar los argumentos de Vector3:

--!native

-- "v" se asume que es una tabla; la función se ejecuta más lentamente debido a las verificaciones de tabla
local function sumComponentsSlow(v)
	return v.X + v.Y + v.Z
end

-- "v" se declara como un Vector3; se genera código especializado para vectores
local function sumComponentsFast(v: Vector3)
	return v.X + v.Y + v.Z
end

Herramientas de Studio

Las siguientes herramientas de Studio son compatibles con scripts --!native y funciones @native.

Depuración

La depuración general de scripts es compatible, pero las vistas para locales/upvalues pueden estar incompletas y faltar variables de los marcos de pila de llamadas que se están ejecutando de forma nativa.

También ten en cuenta que al depurar código seleccionado para la compilación nativa, colocar puntos de interrupción desactivará la ejecución nativa para esas funciones.

Script Profiler

En el Script Profiler, las funciones que se ejecutan de forma nativa muestran <native> junto a ellas:

Si una función marcada con @native o dentro de un --!native script no muestra la anotación <native>, esa función puede no estar ejecutándose de forma nativa debido a la colocación de puntos de interrupción, uso de código desaconsejado, o anotaciones de tipo desajustadas.

Heap de Luau

En el perfilador de heap de Luau, la memoria ocupada por funciones nativas se muestra como elementos [native] en el gráfico.

Análisis de tamaño

Cada script compilado de forma nativa consume memoria. Cuando el tamaño del código compilado alcanza un límite predefinido, la compilación nativa se detiene y el código restante se ejecuta de forma no nativa. Esto hace que sea esencial elegir scripts cuidadosamente para la compilación nativa.

Para monitorear el tamaño del código nativo de funciones y scripts individuales:

1. Asegúrate de estar en la vista Servidor a través del botón de alternar cliente/servidor.
2. Invoca debug.dumpcodesize() desde la Barra de Comandos.

En la ventana de Salida, verás el número total de scripts y funciones que han sido compilados de forma nativa hasta el momento de la invocación, la memoria consumida por su código nativo y el límite de tamaño del código nativo. Después del resumen, verás una tabla para cada script compilado de forma nativa en orden descendente de tamaño de código.

Para cada script, la salida muestra el número de funciones compiladas y el consumo de memoria del código nativo. Cada función se lista luego en orden descendente de tamaño de código nativo, con funciones anónimas mostradas como [anónimo] y scripts completos mostrados como [nivel superior]. En la última columna, se calcula el porcentaje con respecto al límite de tamaño de código nativo. Ten en cuenta que el tamaño del código nativo de las funciones se informa con precisión, pero el consumo de memoria para los scripts se redondea al tamaño de página más cercano.

Límites y solución de problemas

Compilar código en instrucciones para una CPU particular requiere memoria de almacenamiento adicional. Además, las optimizaciones para funciones complejas pueden tardar demasiado tiempo en realizarse. Alcanzar un límite interno informará un error en la ventana de Salida de Studio, incluyendo:

Este error significa que un solo bloque de código dentro de una función utilizó más de 64K instrucciones. Esto se puede evitar simplificando la función o dividiéndola en funciones individuales más pequeñas.

Este error significa que una sola función contiene más de 32K bloques internos de código. Los bloques internos de código no se mapean exactamente a los bloques de control de flujo en tu script, pero este error se puede evitar simplificando el control de flujo en la función o dividiéndola en funciones individuales más pequeñas.

Este error significa que, en total, la función ha alcanzado un límite de 1 millón de instrucciones para todo el script. En algunos casos, la función reportada en sí misma puede tener muchas instrucciones, o el límite puede haber sido alcanzado por funciones anteriores en el script. Para evitar este problema, se recomienda mover funciones particularmente grandes a un script no nativo separado o usar @native en las otras funciones. También puedes intentar marcar ese script separado con --!native, pero 1 millón de instrucciones ocupa mucha memoria y puedes exceder el límite de memoria.

A veces, una función contiene partes complejas de código que el compilador de código nativo no puede manejar actualmente. Para evitar este error, inspecciona expresiones complejas en el código y divídelas o simplifícalas, pero también considera abrir un informe de error con un ejemplo del código que falló por esta razón.

Este error significa que se ha alcanzado el límite de memoria general para los datos de código nativo. Para evitar esto, intenta eliminar --!native de los scripts que consumen más memoria, permitiendo que más scripts más pequeños se ajusten al límite. Alternativamente, mueve funciones grandes o que se llaman con poca frecuencia a un módulo no nativo separado.