스크립트 기능 | 설명서 - Roblox 크리에이터 허브

스크립트 기능은 실험적이며 클라이언트 베타로 제공됩니다.

스크립트 기능을 사용하면 DataModel 서브트리 내에서 스크립트가 수행할 수 있는 행동을 제어할 수 있습니다. 기본 "모두 또는 아무것도" 방식을 넘어서, 스크립트가 오디오, 물리학, 데이터 저장소 등과 같은 특정 카테고리에만 접근하도록 설정할 수 있습니다.

이 시스템은 툴박스에서 가져온 모델이 수행할 수 있는 작업을 제한할 수 있게 하며, 사용자 생성 콘텐츠를 게임에 포함하는 것을 더 쉽게 만들어 줍니다.
또한, 플레이어가 자신의 코드를 실행할 수 있는 게임의 보안을 강화하는 데 도움이 될 수 있습니다. 이러한 코드는 종종 제한된 또는 에뮬레이트된 환경에서 실행됩니다.
자신이 직접 수행할 수 있는 작업을 제한하는 라이브러리를 공유하는 데도 사용할 수 있습니다. 예를 들어 추가 수학 메소드를 제공하는 라이브러리는 다른 개발자들이 악의적인 코드가 포함되지 않았음을 확인하기 위해 전체 코드베이스를 검증하지 않아도 되도록 필요한 최소한의 기능만을 제한할 수 있습니다.

스크립트 기능 활성화

이 기능을 활성화하려면, 탐색기 및 속성 창에서 SandboxedInstanceMode 속성을 Default에서 Experimental로 변경합니다.

샌드박스화된 컨테이너

스크립트 기능은 샌드박스화된 컨테이너라는 개념을 도입합니다. Models, Folders, Scripts 또는 해당 클래스의 하위 클래스에는 속성 창에서 사용할 수 있는 Sandboxed 속성이 있습니다.

Sandboxed 속성을 활성화하면 해당 인스턴스가 DataModel 트리 내에서 샌드박스화된 컨테이너로 지정되어, 해당 컨테이너 내의 스크립트가 수행할 수 있는 작업이 Capabilities 속성의 설정 값에 따라 제한됩니다.

기능

Capabilities 속성은 실행의 다양한 측면을 제어하는 값의 집합입니다. 기능은 다음과 같은 넓은 카테고리에 속합니다:

실행 제어 - 스크립트가 클라이언트 또는 서버에서 실행될 수 있는지를 지정합니다.
인스턴스 접근 제어 - 스크립트가 상호작용할 수 있는 DataModel 부분을 지정합니다.
스크립트 기능 제어 - 스크립트가 호출할 수 있는 Luau 함수를 지정합니다.
엔진 API 접근 제어 - Roblox 엔진 API의 어떤 부분이 사용될 수 있는지를 지정합니다.

스크립트가 기능 집합에 없는 작업을 시도하면 Roblox가 오류를 보고합니다. 오류에는 일반적으로 시도한 작업, 작업의 대상, 그리고 누락된 첫 번째 기능이 포함됩니다:


현재 스레드는 'Workspace'를 수정할 수 없습니다. (AccessOutsideWrite 기능 부족)
현재 스레드는 'Clone'을 호출할 수 없습니다. (CreateInstances 기능 부족)
현재 스레드는 'GetSecret'을 호출할 수 없습니다. (Network 기능 부족)

실행 제어

두 가지 기능이 실행 제어를 처리합니다:

RunClientScript - LocalScript 또는 Script에서 RunContext 값이 Client인 경우 클라이언트에서 실행할 수 있습니다.
RunServerScript - Script에서 RunContext 값이 Server인 경우 서버에서 실행할 수 있습니다.

스크립트가 Enabled인 경우, 그러나 시작할 위치에 해당하는 기능이 사용 가능하지 않으면, 출력 창에 경고 메시지가 표시됩니다. 스크립트가 해당 컨텍스트에서 실행될 수 없으려면 비활성화하거나 삭제해야 합니다.

ModuleScripts는 이러한 실행 기능을 필요로 하지 않습니다.

스크립트가 실행 제어 기능이 부족하여 시작에 실패하면, 출력에 경고로 보고됩니다. 예:


서버 스크립트 'Script'를 시작할 수 없습니다. (RunServerScript 기능 부족)

인스턴스 접근 제어

인스턴스 접근 제어를 처리하는 단일 기능:

AccessOutsideWrite - 스크립트가 샌드박스화된 컨테이너 외부에서 인스턴스를 가져오고 받을 수 있습니다.

이 기능이 사용 가능하지 않은 경우, 스크립트는 자신의 샌드박스화된 컨테이너 내에 있는 인스턴스만 조회할 수 있습니다. 예를 들어, 스크립트가 샌드박스화된 컨테이너에 직접 배치된 경우, script.Parent.Parent는 nil을 반환합니다.

또한, 샌드박스화된 컨테이너 밖의 Instance를 전달하는 Roblox API 이벤트는 nil을 전달합니다. 예를 들어, 샌드박스화된 컨테이너 밖의 인스턴스의 터치가 BasePart.Touched 신호를 발생시키면, 이벤트는 여전히 수신되지만 인수가 nil입니다.

이 기능을 설정하지 않는 것이 좋습니다. 스크립트가 게임의 모든 인스턴스와 상호작용할 수 있을 경우 샌드박싱 보장이 약해집니다.

서비스에 대한 접근

AccessOutsideWrite 없이도, 샌드박스화된 컨테이너에 있는 스크립트는 여전히 game, workspace, 및 서비스에 접근할 수 있습니다. 이 접근은 스크립트가 DataModel.GetService와 같은 유용한 메소드를 호출할 수 있도록 제공되지만, 그 하위 인스턴스에 대한 접근은 여전히 검증됩니다.

내부 전달된 인스턴스

함수 호출을 통해 전달된 인스턴스는 참조가 유지됩니다. 그러나 ModuleScript가 이 방식으로 전달되면, AccessOutsideWrite 없이 요구될 수 없습니다. 이는 ModuleScript의 반환 값이 종종 변경 가능하며 샌드박스화된 컨테이너의 스크립트에 의해 수정될 수 있기 때문입니다.

스크립트 기능 제어

이 기능 집합은 스크립트의 일반적 측면을 제어합니다:

CreateInstances - 스크립트는 Instance.new, Instance.fromExisting, 또는 Instance:Clone()을 사용하여 새로운 인스턴스를 생성할 수 있습니다.
LoadString - 스크립트는 loadstring을 호출할 수 있습니다.
LoadUnownedAsset - 스크립트는 자산 ID로 require를 호출하거나 AssetService:LoadAssetAsync()를 호출할 수 있습니다.
ScriptGlobals - 스크립트는 shared 및 _G에 접근할 수 있습니다.

기본 함수 제한이 여전히 적용된다는 점을 유의하세요. LoadString이 활성화되어 있더라도, 게임에서 ServerScriptService에서 이를 활성화해야 하며, 여전히 서버에서만 사용할 수 있습니다.

새로운 인스턴스를 생성하려면, CreateInstances 외에도 해당 인스턴스에 대한 접근을 제공하는 추가 엔진 API 기능이 필요합니다.

엔진 API 접근 제어

마지막으로, 이 기능 그룹은 스크립트의 다양한 엔진 API 접근을 제어합니다:

Animation - 애니메이션 관련 인스턴스 접근
AssetCreateUpdate - 자산 생성 또는 업데이트 관련 엔진 API 접근
AssetManagement - 읽기, 생성 또는 업데이트가 아닌 자산 관련 작업을 위한 엔진 API 접근
AssetRead - 자산에 대한 정보 얻기 관련 엔진 API 접근
Audio - 오디오 API 관련 인스턴스 접근
AvatarAppearance - 아바타의 시각적 요소 관련 인스턴스 접근
AvatarBehavior - 휴머노이드 제어 또는 수정 관련 엔진 API 접근
Basic - 위험이 적은 일반 API 접근
CSG - 구성 솔리드 기하학(CSG) 관련 인스턴스 및 기능 접근
CapabilityControl - 인스턴스의 Sandboxed 및 Capabilities 속성 수정 접근
Capture - 사용자의 화면에서 스크린샷 또는 비디오를 캡처하는 데 관련된 엔진 API 접근
Chat - 게임 내 채팅 관련 인스턴스 접근
Consequences - 사용자 처벌을 위한 API 접근 (퇴장 또는 금지)
DataStore - 데이터 저장소 및 메모리 저장소 API 접근
DynamicGeneration - 자산을 동적으로 수정하는 관련 엔진 API 접근
Environment - 환경 표시 제어와 관련된 인스턴스 접근
Groups - 그룹/커뮤니티 관련 엔진 API 접근
Input - 사용자 입력 관련 인스턴스 접근
LegacySound - 더 이상 사용되지 않을 사운드 관련 엔진 API 접근
LoadOwnedAsset - 자신이 소유한, 공유받은, Roblox가 소유한 자산 또는 무해한 자산 유형을 로드하기 위한 엔진 API 접근
Logging - 로그 API 접근
Material - 소재 관련 엔진 API 접근
Monetization - 대부분의 PromptPurchases를 제외한 게임 수익화 관련 엔진 API 접근
Network - HTTP 네트워킹 API 접근
Physics - 물리학과 관련된 인스턴스 접근
PlatformAvatarEditing - 아바타 생성 또는 업데이트, 또는 이를 돕는 API에 대한 엔진 API 접근
Players - Player 클래스 또는 Players.LocalPlayer를 반환/상호작용하는 엔진 API 접근
PromptExternalPurchase - 임의의 자산 구매를 유도하는 엔진 API 접근
RemoteEvent - 내부 네트워킹 작업을 위한 인스턴스 접근
SensitiveInput - 사용자로부터 민감한 입력을 캡처하는 관련 엔진 API 접근, 즉 높은 개인 정보 보호 하드웨어 센서.
ServerCommunication - MessagingService와 같은 서버 간 통신 관련 엔진 API 접근
Social - 친구 및 초대와 같은 소셜 기능 관련 엔진 API 접근
Teleport - 텔레포트 관련 엔진 API 접근
UI - 사용자 인터페이스와 관련된 인스턴스 접근

각 클래스, 속성, 메소드 및 이벤트의 기능은 엔진 API 참조에서 표시됩니다. 예를 들어, Player:GetFriendsOnlineAsync()는 Player 및 Social 기능이 요구됩니다.

여러 HttpService 메소드는 스크립트를 실행할 수 있는 조건만 갖추면 기능 없이 사용 가능합니다:

필요한 기능 없이 인스턴스 속성 또는 메소드를 접근하면, 누락된 기능을 설명하는 오류가 보고됩니다.

마지막으로, 기능은 현재 Roblox 엔진의 모든 인스턴스를 포함하지 않습니다. 이 섹션 또는 다음 섹션에 나열되지 않은 인스턴스는 샌드박스화된 컨테이너에서 상호작용할 수 없으며, 현재 스크립트에 대해 Unassigned 기능이 사용 불가능하다는 오류가 발생합니다.

추가적인 제한 사항으로는 getfenv() 및 setfenv() 함수가 샌드박스화된 컨테이너의 스크립트에서 사용할 수 없다는 것입니다. 샌드박스화된 스크립트에서 호출하면 다음과 같은 오류가 발생합니다:


현재 스레드는 ['getfenv'/'setfenv']를 호출할 수 없습니다 - 대상은 현재 샌드박스에서 사용할 수 없는 API를 사용합니다.

스크립트 접근은 인스턴스에 제한됩니다. 인스턴스 자체는 여전히 샌드박스화된 컨테이너 안에서 존재하고 독립적으로 작동할 수 있습니다. 조명은 여전히 밝혀지고, 사용자 인터페이스는 여전히 보이며, 이미 연결된 오디오 설정이 소리를 재생합니다.

컨테이너 간 상호작용

중첩된 컨테이너

하나의 샌드박스화된 컨테이너가 다른 컨테이너 내에 중첩될 경우, 내부 컨테이너의 인스턴스는 외부에서 접근할 수 있습니다.

내부 컨테이너의 기능은 외부 컨테이너의 기능에 의해 제한됩니다. 예를 들어, 외부 컨테이너가 Basic, Audio 및 CSG 기능을 갖고 있지만, 내부 컨테이너가 Basic 및 Network 기능을 가지고 있다면, 실행 시 내부 컨테이너에 사용 가능한 기능은 단지 Basic뿐입니다.

내부 및 외부 컨테이너 간에 공통 기능이 없으면, 결과적인 기능 집합은 비어 있습니다.

바인더 함수 및 이벤트

BindableEvent 및 BindableFunction은 컨테이너와 통신하거나 컨테이너가 직접 사용할 수 없는 기능으로 콜백을 실행할 수 있게 해줍니다.

이벤트가 발생하거나 함수가 호출되면, 연결은 이를 등록한 함수의 맥락에서 실행됩니다. 즉, 이벤트나 함수 콜백이 샌드박스화된 컨테이너에 의해 등록된 경우, 해당 컨테이너의 기능으로 호출됩니다. 외부 코드가 콜백을 등록한 경우, 샌드박스화된 컨테이너 스크립트가 이를 호출하면 기능이 호출자의 기능을 사용할 수 있는 맥락에서 실행됩니다.

AccessOutsideWrite 기능이 있더라도, 샌드박스화된 컨테이너의 스크립트는 기능 집합이 더 큰 경우 외부 컨테이너의 이벤트나 함수를 호출할 수 없다는 점에 주목하는 것이 중요합니다.

샌드박스화된 스크립트가 기능 집합이 자신의 것보다 더 큰 이벤트나 함수(BindableEvent, BindableFunction, 또는 RemoteEvent)를 발생시키거나 호출하려 할 때, 오류 메시지는 확인해야 할 속성을 지정합니다.

대상이 어떤 샌드박스화된 컨테이너 내부에 있지 않으면:


현재 스레드는 '<Target>'을 발생시킬 수 없습니다. '<Target>'은 샌드박스 속성이 false로 설정되어 있지만 호출 스레드는 샌드박스화되어 있습니다.

이를 해결하려면 대상의 Sandboxed를 true로 설정해야 합니다. 또는 호출 스레드의 소스를 수정하여 Sandboxed를 false로 설정할 수도 있습니다. 그러나 이는 샌드박싱이 제공하는 보안 혜택을 제거하므로 권장되지 않습니다.

만약 대상이 샌드박스화되어 있지만 호출자가 부족한 기능을 가지고 있다면:


현재 스레드는 '<Target>'을 발생시킬 수 없습니다. '<Target>'은 Capabilities 속성에 대한 추가 값이 있습니다: <First Missing Capability> (그리고 N개 더)

이것을 해결하기 위해 대상의 Capabilities를 호출자의 하위 집합으로 조정하거나, 호출자의 Capabilities를 대상에 맞게 확대해야 합니다.

모듈 요구

내부 ModuleScripts는 샌드박스화된 컨테이너에서 일반적으로 요구할 수 있습니다. 그러나 대상 인스턴스가 컨테이너 밖에 있는 경우, 사용 가능한 기능 집합이 컨테이너에 대해 작거나 같은 경우에만 ModuleScript를 요구할 수 있습니다.

이 제한은 RunClientScript 및 RunServerScript 기능에는 적용되지 않습니다. ModuleScript가 RunClientScript만 있는 컨테이너에 배치되어 있지만 RunServerScript 기능이 있는 스크립트에서 요구될 경우, 성공적으로 실행할 수 있도록 허용됩니다.

require()가 기능 불일치로 실패할 때, 오류 메시지에는 대상 모듈과 요구할 속성이 Bindable 함수 및 이벤트에 설명된 것과 유사하게 나열됩니다.

직접 호출된 함수

샌드박스화된 컨테이너의 ModuleScript가 컨테이너 외부에서 요구될 경우, 일부 보호 기능이 적용되지 않습니다. 특히, 대상 함수는 호출자에게 사용 가능한 모든 인스턴스에 접근할 수 있습니다. 호출자가 샌드박스화된 컨테이너에 있는 경우, 호출은 AccessOutsideWrite가 사용 가능한 것처럼 작용합니다.

다른 기능 제한은 여전히 적용됩니다. DataStore 접근 기능이 있지만 대상 모듈이 이를 가지지 않는 경우 DataStore 메소드를 호출할 수 없습니다. 그렇지만 호출자가 DataStore를 사용하는 자신의 함수를 전달하면, 대상은 해당 호출 중에 실행할 수 있습니다. 대상이 task와 같은 메소드를 사용하여 스레드를 예약하면, 해당 스레드는 해당 함수를 호출할 수 있는 능력을 잃습니다.

인스턴스는 대상 모듈에 전달되거나 모듈 필드에 할당될 수 있습니다.

필요한 경우, rawset을 사용하여 표의 멤버를 할당하는 것이 좋습니다. 이는 테이블에서 설정된 __index/__newindex 메타메서드를 실행하지 않도록 합니다.

전반적으로 가능한 경우 BindableEvent 및 BindableFunction을 사용하여 통신하는 것이 좋습니다.

인스턴스 이동

대부분의 인스턴스는 컨테이너 간 이동에 대한 제한이 없습니다. 그러나 스크립트 인스턴스는 같은 기능 집합 또는 그 하위 집합을 가진 컨테이너로만 이동할 수 있습니다.

즉, AccessOutsideWrite 기능을 가진 샌드박스화된 컨테이너는 스크립트를 자신의 외부로 이동하고 더 많은 기능을 얻을 수 없습니다.