Możliwości skryptów

Możliwości skryptów pozwalają kontrolować, jakie działania mogą wykonywać skrypty wewnątrz poddrzewa DataModel. Zamiast domyślnego systemu "wszystko lub nic", możesz ustawić skrypt, aby mógł uzyskać dostęp tylko do określonych kategorii, takich jak audio, fizyka, przechowywanie danych i inne.

• Ten system pozwala ograniczyć, co modele pobrane z narzędzi mogą robić, i ułatwia włączenie treści generowanych przez użytkowników do gry.
• Może również pomóc w zapewnieniu lepszej bezpieczeństwa gier, które pozwalają na uruchamianie własnego kodu przez graczy, co często odbywa się w ograniczonym lub emulowanym środowisku.
• Może być również wykorzystywane do dzielenia się bibliotekami, które ograniczają, co same mogą robić. Na przykład biblioteka dostarczająca dodatkowe metody matematyczne może być ograniczona do najmniejszego zestawu możliwości, które są jej potrzebne, aby inni deweloperzy korzystający z tej biblioteki nie musieli weryfikować całego kodu, aby upewnić się, że nie zawiera złośliwego kodu.

Włączanie możliwości skryptów

Aby włączyć tę funkcję, zmień właściwość SandboxedInstanceMode z Default na Experimental w oknie Eksploratora i Właściwości.

Kontener w piaskownicy

Możliwości skryptów wprowadzają pojęcie kontenera w piaskownicy. Models, Folders, Scripts lub potomkowie dowolnej z tych klas mają właściwość Sandboxed dostępną w oknie Właściwości.

Włączenie właściwości Sandboxed oznacza instancję jako kontener w piaskownicy wewnątrz drzewa DataModel, co ogranicza działania, które skrypty wewnątrz tego kontenera mogą wykonywać, na podstawie zestawu wartości w właściwości Capabilities.

Możliwości

Właściwość Capabilities to zbiór wartości, które kontrolują różne aspekty wykonywania. Możliwości dzielą się na następujące szerokie kategorie:

• Kontrola wykonania - Określa, czy skrypt może być uruchomiony na kliencie lub serwerze
• Kontrola dostępu do instancji - Określa, z którymi częścią DataModel skrypt może interagować
• Kontrola funkcjonalności skryptu - Określa, które funkcje Luau skrypty mogą wywoływać
• Kontrola dostępu do API silnika - Określa, które części API silnika Roblox mogą być używane

Kiedy skrypt próbuje wykonać akcję, która nie znajduje się w zestawie możliwości, Roblox zgłasza błąd. Błędy zazwyczaj zawierają próbę działania, cel akcji oraz pierwszą brakującą możliwość:

Wątek nie może modyfikować 'Workspace' (brak możliwości AccessOutsideWrite)
Wątek nie może wywołać 'Clone' (brak możliwości CreateInstances)
Wątek nie może wywołać 'GetSecret' (brak możliwości Network)

Kontrola wykonania

Dwie możliwości obsługują kontrolę wykonania:

• RunClientScript - LocalScript lub Script z wartością RunContext równą Client ma pozwolenie na wykonanie na kliencie
• RunServerScript - Script z wartością RunContext równą Server ma pozwolenie na wykonanie na serwerze

Jeśli skrypt jest Enabled, ale możliwość odpowiadająca lokalizacji, w której próbuje się uruchomić, nie jest dostępna, w oknie Wyniki wyświetla się komunikat ostrzegawczy. Jeśli skrypt nie powinien być uruchamiany w tym kontekście, wyłącz lub usuń go.

Należy pamiętać, że ModuleScripts nie muszą mieć tych możliwości wykonania, aby być wymagane.

Gdy skrypt nie może się uruchomić, ponieważ brakuje możliwości kontroli wykonania, jest to zgłaszane jako ostrzeżenie w wynikach, na przykład:

Nie można uruchomić skryptu serwera 'Script' (brak możliwości RunServerScript)

Kontrola dostępu do instancji

Jedna możliwość obsługuje kontrolę dostępu do instancji:

• AccessOutsideWrite - Skrypt ma pozwolenie na pobieranie i odbieranie instancji z zewnątrz kontenera w piaskownicy

Gdy możliwość nie jest dostępna, skrypt może tylko wyszukiwać instancje, które znajdują się w jego własnym kontenerze w piaskownicy. Na przykład, jeśli skrypt jest umieszczony bezpośrednio w kontenerze w piaskownicy, script.Parent.Parent zwraca nil.

Dodatkowo wszelkie zdarzenia API Roblox, które przekazują Instance, zamiast tego przekazują nil dla każdej Instance znajdującej się poza kontenerem w piaskownicy. Na przykład, jeśli BasePart.Touched jest sygnalizowane przez dotyk instancji zewnętrznej kontenera w piaskownicy, zdarzenie wciąż jest odbierane, ale argument to nil.

Unikaj ustawiania tej możliwości; gwarancje piaskownicy są słabsze, gdy skrypty mogą wchodzić w interakcje z dowolną instancją w grze.

Dostęp do usług

Nawet bez AccessOutsideWrite, skrypty w kontenerze w piaskownicy mogą wciąż uzyskiwać dostęp do game, workspace i usług. Ten dostęp jest zapewniony, aby skrypty mogły nadal wywoływać użyteczne metody tych globalnych, takie jak DataModel.GetService, ale dostęp do ich instancji podrzędnych jest nadal weryfikowany.

Wewnętrznie przekazywane instancje

Jeśli instancja jest przekazywana przez wywołanie funkcji, które nie przechodzą przez API Roblox, referencja jest zachowana. Jednakże, jeśli ModuleScript jest przekazywana w ten sposób, nie może zostać zażądana bez AccessOutsideWrite. Dzieje się tak, ponieważ zwrot ModuleScript jest często mutowalny i może być modyfikowany przez skrypt w kontenerze w piaskownicy.

Kontrola funkcjonalności skryptu

Ten zestaw możliwości kontroluje niektóre ogólne aspekty skryptów:

• CreateInstances - Skrypt może tworzyć nowe instancje za pomocą Instance.new, Instance.fromExisting lub Instance:Clone()
• LoadString - Skrypt ma pozwolenie na wywołanie loadstring
• LoadUnownedAsset - Skrypt może wywołać require z identyfikatorem zasobu lub AssetService:LoadAssetAsync()
• ScriptGlobals - Skrypt ma dostęp do shared i _G

Należy pamiętać, że domyślne ograniczenia funkcji wciąż obowiązują. Nawet jeśli LoadString jest włączone, gra musi je również włączyć w ServerScriptService, a jest dostępne tylko na serwerze.

Aby tworzyć nowe instancje, poza CreateInstances, wymagana jest dodatkowa możliwość API silnika zapewniająca dostęp do tej instancji.

Kontrola dostępu do API silnika

Ta ostatnia grupa możliwości kontroluje dostęp skryptów do różnych API silnika:

• Animation - Dostęp do instancji związanych z animacjami
• AssetCreateUpdate - Dostęp do API silnika związanych z tworzeniem lub aktualizowaniem zasobów
• AssetManagement - Dostęp do API silnika związanych z operacjami na zasobach, które nie są odczytem, tworzeniem ani aktualizacją
• AssetRead - Dostęp do API silnika związanych z uzyskiwaniem informacji o zasobach
• Audio - Dostęp do instancji związanych z API audio
• AvatarAppearance - Dostęp do instancji związanych z elementami wizualnymi awatarów
• AvatarBehavior - Dostęp do API silnika związanych z kontrolowaniem lub modyfikowaniem humanoida
• Basic - Dostęp do ogólnych API, które niosą niewielkie ryzyko
• CSG - Dostęp do instancji i funkcji związanych z geometrią konstrukcyjną (CSG)
• CapabilityControl - Dostęp do modyfikowania właściwości Sandboxed i Capabilities instancji
• Capture - Dostęp do API silnika związanych z wykonywaniem zrzutów ekranowych lub nagrywaniem wideo na ekranie użytkownika
• Chat - Dostęp do instancji związanych z czatem w grze
• Consequences - Dostęp do API dotyczących karania użytkowników (wyrzucenia lub zbanowania)
• DataStore - Dostęp do API przechowywania danych i pamięci
• DynamicGeneration - Dostęp do API silnika związanych z dynamiczną modyfikacją zasobów
• Environment - Dostęp do instancji związanych z kontrolą wyświetlania środowiska
• Groups - Dostęp do API silnika związanych z grupami/ społecznościami
• Input - Dostęp do instancji związanych z wejściem użytkownika
• LegacySound - Dostęp do API silnika związanych z dźwiękiem, który będzie usunięty
• LoadOwnedAsset - Dostęp do API silnika związanych z ładowaniem zasobów, które są twoje, udostępnione ci, należące do Robloxa lub są typu łagodnego
• Logging - Dostęp do API logów
• Material - Dostęp do API silnika związanych z materiałami
• Monetization - Dostęp do API silnika związanych z monetyzowaniem gry, z wyłączeniem większości PromptPurchases
• Network - Dostęp do API HTTP
• Physics - Dostęp do instancji związanych z fizyką
• PlatformAvatarEditing - Dostęp do API silnika związanych z tworzeniem lub aktualizowaniem awatarów, lub API w tym pomagającymi
• Players - Dostęp do API silnika związanych z klasą Player lub zwracających/interaktujących z Players.LocalPlayer
• PromptExternalPurchase - Umożliwia dostęp do API silnika powiązanego z wezwanie do zakupu dowolnych zasobów
• RemoteEvent - Dostęp do instancji dla wewnętrznych operacji sieciowych
• SensitiveInput - Dostęp do API silnika związanych z rejestrowaniem czułych danych wejściowych od użytkownika, tj. czujników sprzętowych o wysokiej prywatności.
• ServerCommunication - Dostęp do API silnika związanych z komunikacją między serwerami, takich jak MessagingService
• Social - Dostęp do API silnika związanych z funkcjami społecznymi, takimi jak znajomi i zaproszenia
• Teleport - Dostęp do API silnika związanych z teleportacją
• UI - Dostęp do instancji związanych z interfejsem użytkownika

Możliwości każdej klasy, właściwości, metody i zdarzenia są wyświetlane w Dokumentacji API silnika. Na przykład Player:GetFriendsOnlineAsync() wymaga możliwości Player i Social.

Kilka metod HttpService jest dostępnych bez żadnych możliwości poza możliwością wykonywania skryptów:

• HttpService:JSONDecode()
• HttpService:JSONEncode()
• HttpService:GenerateGUID()

Jeśli właściwość instancji lub metoda zostanie uzyskana bez wymaganej możliwości, zgłaszany jest błąd opisujący brakującą możliwość.

Wreszcie, możliwości nie obejmują każdej instancji w silniku Roblox dzisiaj. Instancje, które nie są wymienione w tej sekcji lub następnej, nie są dostępne do interakcji z kontenera w piaskownicy i zgłaszają błąd mówiący, że możliwość Nieprzypisana nie jest dostępna dla bieżącego skryptu.

Dodatkowym ograniczeniem jest to, że funkcje getfenv() i setfenv() nie są dostępne dla skryptów w kontenerze w piaskownicy. Wywołanie ich z poziomu skryptu w piaskownicy zgłasza:

Wątek nie może wywołać ['getfenv'/'setfenv'] - cel używa API, które nie są dostępne w bieżącej piaskownicy

Tylko dostęp skryptów do instancji jest ograniczony. Same instancje mogą wciąż istnieć i działać samodzielnie wewnątrz kontenera w piaskownicy. Światła wciąż świecą, interfejsy użytkownika są wciąż widoczne, a dźwięki już podłączone mogą grać.

Interakcje między kontenerami

Zagnieżdżone kontenery

Kiedy jeden kontener w piaskownicy jest zagnieżdżony w innym, instancje wewnętrznego kontenera są dostępne dla zewnętrznego.

Możliwości wewnętrznego kontenera są ograniczone przez możliwości zewnętrznego. Na przykład, jeśli zewnętrzny kontener ma możliwości Basic, Audio i CSG, podczas gdy wewnętrzny kontener ma Basic i Network, tylko możliwości Basic są dostępne dla wewnętrznego kontenera w czasie działania.

Jeśli nie ma wspólnych możliwości pomiędzy wewnętrznym a zewnętrznym kontenerem, powstały zestaw możliwości jest pusty.

Funkcje i zdarzenia dawalne

BindableEvent i BindableFunction stanowią najlepszy sposób na komunikację z kontenerem lub pozwalają mu na uruchamianie callbacków z możliwościami, które sam nie ma pozwolenia na bezpośrednie używanie.

Gdy zdarzenie jest wywoływane lub funkcja jest wywoływana, połączenia są realizowane w kontekście funkcji, która je zarejestrowała. Oznacza to, że jeśli zdarzenie lub callback funkcji jest zarejestrowany przez kontener w piaskownicy, jest wywoływany z możliwościami tego kontenera. Jeśli callback jest zarejestrowany przez kod z zewnątrz, gdy skrypty kontenera w piaskownicy je wywołują, wykonują twoje funkcje z możliwościami dostępnymi dla twoich funkcji.

Ważne jest, aby zauważyć, że nawet z możliwością AccessOutsideWrite, skrypty w kontenerach w piaskownicy nie mogą wywoływać zdarzeń lub funkcji spoza swoich kontenerów, jeśli mają większy zestaw możliwości niż kontener sam w sobie.

Gdy skrypt w piaskownicy próbuje wywołać lub zgłosić zdarzenie lub funkcję (BindableEvent, BindableFunction, lub RemoteEvent), których możliwości przodka przewyższają jego własne, błąd wskazuje na właściwość, którą należy sprawdzić.

Jeśli cel nie znajduje się w żadnym kontenerze w piaskownicy:

Wątek nie może uruchomić '<Target>' ponieważ '<Target>' ma ustawioną właściwość Sandboxed na fałsz, ale wywołujący wątek jest w piaskownicy

Aby to rozwiązać, ustaw Sandboxed na true dla celu. Alternatywnie, możesz zmodyfikować źródło wywołującego wątku, aby miało Sandboxed ustawione na false, ale nie jest to zalecane, ponieważ eliminowałoby korzyści bezpieczeństwa, które zapewnia piaskownica.

Jeśli cel jest w piaskownicy, ale ma możliwości, których wywołujący nie ma:

Wątek nie może uruchomić '<Target>' ponieważ '<Target>' ma dodatkowe wartości dla właściwości Capabilities: <First Missing Capability> (i N więcej)

Aby to rozwiązać, zawęź Capabilities celu do podzbioru możliwości wywołującego lub rozszerz Capabilities wywołującego, aby odpowiadał możliwościom celu.

Wymagana moduł

Wewnętrzne ModuleScripts mogą być wymagane przez kontener w piaskownicy jak zwykle. Jednakże, jeśli instancja docelowa znajduje się poza kontenerem, ModuleScript może być wymagane tylko jeśli zestaw możliwości, który jest dostępny dla niej, jest mniejszy lub równy możliwościom dostępnym dla kontenera.

To ograniczenie nie dotyczy możliwości RunClientScript i RunServerScript. Jeśli ModuleScript jest umieszczony w kontenerze z tylko RunClientScript, ale jest wymagany z biegu, który ma możliwość RunServerScript, jest dozwolone, aby powiodło się i uruchomić te funkcje na serwerze.

Gdy require() kończy się niepowodzeniem z powodu niedopasowania możliwości, błąd wskazuje na moduł docelowy i właściwość, którą należy zbadać w sposób podobny do funkcji dawalnych i zdarzeń opisanych w poprzedniej sekcji.

Bezpośrednio wywoływane funkcje

Jeśli ModuleScript w kontenerze w piaskownicy jest wymagany z zewnątrz kontenera, niektóre z zabezpieczeń nie są dostępne. W szczególności, docelowa funkcja ma dostęp do wszystkich instancji dostępnych dla wywołującego. Jeżeli wywołujący nie znajduje się w kontenerze w piaskownicy, wywołanie działa tak, jakby AccessOutsideWrite było do niego dostępne.

Inne ograniczenia możliwości wciąż obowiązują. Jeśli masz możliwość dostępu do DataStore, ale docelowy moduł jej nie ma, nie może wywoływać metod DataStore. Jednak jeśli przekażesz swoją własną funkcję pracującą z DataStore, cel może ją uruchomić podczas tego wywołania. Jeśli cel zaplanuje wątek przy użyciu metod takich jak inne z task, te wątki tracą zdolność do wywoływania tej funkcji.

Instancje mogą być przekazywane do modułu docelowego lub przypisane do pól modułu.

W razie potrzeby zaleca się przypisanie członków tabeli za pomocą rawset, aby uniknąć wywoływania metametod __index/__newindex, które mogą być ustawione na tabeli.

Ogólna rekomendacja to komunikacja za pomocą BindableEvent i BindableFunction, kiedy to możliwe.

Przemieszczanie instancji

Większość instancji nie ma ograniczeń w ruchu między kontenerami. Instancje skryptów jednak mogą być przenoszone tylko do kontenera, który ma ten sam zestaw możliwości lub podzbiór tych możliwości.

Oznacza to, że kontener w piaskownicy z AccessOutsideWrite nie może po prostu zmienić rodzica skryptu wewnątrz siebie na zewnątrz i uzyskać więcej możliwości.