네이티브 코드 생성

Luau의 네이티브 코드 생성 기능을 통해 게임 내 서버 측 스크립트를 CPU가 실행하는 기계 코드 명령으로 직접 컴파일할 수 있으며, 이는 Luau VM이 작동하는 일반 바이트코드가 아닙니다. 이 기능은 서버의 일부 스크립트, 특히 무거운 Luau 라이브러리나 Roblox API 호출을 많이 사용하지 않고 수치 계산을 많이 수행하는 스크립트의 실행 속도를 개선하는 데 사용할 수 있습니다.

네이티브 코드 생성 활성화

Script에 대해 네이티브 코드 생성을 활성화하려면, 상단에 --!native 주석을 추가하세요:¹

--!native

print("네이티브 코드에서 인사합니다!")

이 경우 스크립트의 모든 함수와 수익성이 있다고 판단되는 최상위 스코프에 대해 네이티브 코드 생성이 활성화됩니다. 추가 변경은 필요하지 않으며, 네이티브로 실행되는 스크립트의 동작은 이전과 완전히 동일하지만 성능만 다릅니다. Luau 언어의 모든 기능과 모든 Roblox API는 계속 지원됩니다.

또는 @native 속성을 추가하여 개별 함수에 대해 네이티브 코드 생성을 활성화할 수 있습니다:

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

모범 사례

다음 팁은 네이티브 코드 생성을 통해 최대한의 이점을 얻는 데 도움이 될 것입니다:

• 많은 계산을 직접 Luau에서 수행하는 스크립트 내에서 이 기능을 활성화하는 것이 가장 좋습니다. 테이블에 대한 수학적 연산이 많고 특히 buffer 유형을 사용한다면, 해당 스크립트는 좋은 후보일 수 있습니다.

• 오직 스크립트의 함수만 네이티브로 컴파일됩니다. 최상위 외부 스코프의 코드는 종종 한 번만 실행되며, 여러 번 호출되는 함수보다 얻는 이득이 적습니다. 특히 프레임마다 호출되는 함수는 더욱 그렇습니다.

• 네이티브 컴파일이 이루어진 경우와 이루어지지 않은 경우 스크립트 또는 함수가 소요하는 시간을 측정하여 언제 그것을 사용하는 것이 최선인지 판단하는 것이 좋습니다. Script Profiler 도구는 함수의 성능을 측정하여 정보에 기반한 결정을 내리는 데 도움이 됩니다.

• 모든 스크립트에 --!native 주석을 배치하여 일부 스크립트가 더 빨리 실행되기를 바라는 것은 유혹적일 수 있지만, 네이티브 코드 생성은 몇 가지 단점이 있습니다:

  • 코드 컴파일 시간이라는 추가 시간이 필요하여 서버의 시작 시간이 증가할 수 있습니다.
  • 네이티브로 컴파일된 코드를 저장하기 위해 추가 메모리가 필요합니다.
  • 게임 내에서 네이티브로 컴파일된 코드의 총 허용량에 제한이 있습니다.

이러한 문제는 @native 속성의 신중한 사용으로 해결할 수 있습니다.

피해야 할 코드

모든 기능은 네이티브 코드 생성을 활성화하거나 비활성화 해도 동일하게 작동하겠지만, 일부는 네이티브로 실행되지 않거나 비최적화를 일으키거나 인터프리트 실행으로 돌아갈 수 있습니다. 여기에는 다음이 포함됩니다:

• 더 이상 사용되지 않는 getfenv()/setfenv() 호출의 사용.
• 비수치 인수를 가진 math.asin()과 같은 다양한 Luau 내장 함수의 사용.
• 잘못된 형식의 인수를 입력하여 타입이 지정된 함수에 전달하는 경우, 예를 들어, foo가 function foo(arg: string)으로 선언된 경우에 foo(true)를 호출하는 것입니다. 항상 올바른 타입 주석을 사용하는 것을 기억하세요.

Script Profiler를 사용할 때는 일반 버전의 함수와 네이티브로 컴파일된 함수가 소요하는 시간을 비교할 수 있습니다. <Typography noWrap>--!native</Typography> 스크립트 내의 함수나 @native로 표시된 함수가 네이티브로 실행되지 않는 경우, 위 목록의 하나 이상의 요인이 비최적화를 유발할 수 있습니다.

타입 주석 사용

네이티브 코드 생성은 주어진 변수에 대해 최적의 타입을 추론하여 코드 경로를 최적화하려고 시도합니다. 예를 들어, a + b는 숫자에서 수행된다고 가정되거나, 테이블은 t.X에서 접근됩니다. 그러나 연산자 오버로딩으로 인해 a와 b는 테이블이나 Vector3일 수 있으며, t는 Roblox 데이터 유형일 수 있습니다.

네이티브 코드 생성은 어떤 타입도 지원하지만, 잘못된 예측은 불필요한 체크를 유발하여 코드 실행 속도를 느리게 만들 수 있습니다.

일부 일반적인 문제를 해결하기 위해, 함수 인수에 대한 Luau 타입 주석이 확인되지만, 특히 Vector3 인수에 대한 주석을 입력하는 것이 권장됩니다:

--!native

-- "v"는 테이블로 가정되어; 테이블 검사로 인해 함수가 느리게 수행됨
local function sumComponentsSlow(v)
	return v.X + v.Y + v.Z
end

-- "v"는 Vector3로 선언되어; 벡터용으로 최적화된 코드가 생성됨
local function sumComponentsFast(v: Vector3)
	return v.X + v.Y + v.Z
end

스튜디오 도구

다음 스튜디오 도구는 --!native 스크립트와 @native 함수에 대해 지원됩니다.

디버깅

일반 디버깅은 지원되지만, 네이티브로 실행 중인 호출 스택 프레임에서 로컬/업밸류의 뷰가 불완전하거나 변수가 누락될 수 있습니다.

또한, 네이티브 컴파일을 위해 선택한 코드를 디버그할 때 중단점을 설정하면 해당 함수의 네이티브 실행이 비활성화된다는 점을 유의하세요.

스크립트 프로파일러

스크립트 프로파일러에서 네이티브로 실행되는 함수는 <native> 표기가 옆에 표시됩니다:

@native로 표시된 함수나 --!native 스크립트 내의 함수가 <native> 주석을 표시하지 않는 경우, 해당 함수는 중단점 배치, 권장되지 않는 코드 사용 또는 타입 주석 불일치로 인해 네이티브로 실행되지 않을 수 있습니다.

Luau 힙

Luau 힙 프로파일러에서는 네이티브 함수가 사용한 메모리가 그래프에서 [native] 요소로 표시됩니다.

크기 분석

네이티브로 컴파일된 각 스크립트는 메모리를 소비합니다. 컴파일된 코드의 크기가 미리 정의된 한계에 도달하면 네이티브 컴파일이 중지되고 나머지 코드는 비네이티브로 실행됩니다. 따라서 네이티브 컴파일을 위해 스크립트를 신중하게 선택하는 것이 필수적입니다.

개별 함수와 스크립트의 네이티브 코드 크기를 모니터링하려면:

1. 클라이언트/서버 전환 버튼을 통해 서버 뷰에 있는지 확인하세요.
2. 명령 바에서 debug.dumpcodesize()를 호출하세요.

출력 창에서 호출 시점까지 네이티브로 컴파일된 스크립트 및 함수의 총 수, 네이티브 코드에서 소비된 메모리 및 네이티브 코드 크기 한도가 표시됩니다. 요약 다음에는 코드 크기별로 내림차순 정렬된 모든 네이티브로 컴파일된 스크립트에 대한 표가 표시됩니다.

각 스크립트에 대해 출력은 컴파일된 함수 수와 네이티브 코드 메모리 소비량을 표시합니다. 그런 다음, 각 함수는 네이티브 코드 크기별로 내림차순으로 나열되며, 익명 함수는 [anonymous]로 표시되고 전체 스크립트는 [top level]로 표시됩니다. 마지막 열에서는 네이티브 코드 크기 한도에 대한 비율이 계산됩니다. 함수의 네이티브 코드 크기는 정확하게 보고되지만, 스크립트의 메모리 소비량은 가장 가까운 페이지 크기로 반올림됩니다.

한계 및 문제 해결

특정 CPU에 명령어로 컴파일하려면 추가 저장 메모리가 필요합니다. 또한 복잡한 함수에 대한 최적화는 수행하는 데 너무 많은 시간이 걸릴 수 있습니다. 내부 한도에 도달하면 스튜디오의 출력 창에 오류가 보고됩니다: