Capacidades de script são experimentais e estão disponíveis como uma versão beta para clientes.
Capacidades de script permitem que você controle quais ações os scripts podem realizar dentro da subárvore DataModel. Em vez do "sistema tudo ou nada" padrão, você pode definir um script para ter acesso apenas a certas categorias, como áudio, física, armazéns de dados e mais.
- Este sistema permite que você limite o que modelos retirados da caixa de ferramentas podem fazer e torna mais fácil incluir conteúdo gerado por usuários dentro do jogo.
- Também pode ajudar a garantir uma melhor segurança de jogos que permitem que os jogadores executem seu próprio código, que muitas vezes é executado em um ambiente restrito ou emulado.
- Além disso, pode ser usado para compartilhar bibliotecas que restringem o que elas mesmas podem fazer. Por exemplo, uma biblioteca que fornece métodos matemáticos adicionais pode ser restringida ao menor conjunto de capacidades necessárias, de forma que outros desenvolvedores que utilizam essa biblioteca não precisem validar todo o código para garantir que não inclui código malicioso.
Habilitar capacidades de script
Para habilitar esse recurso, altere a propriedade SandboxedInstanceMode de Default para Experimental na janela Explorer e Properties.
Contêiner isolado
Capacidades de script introduzem um conceito de contêiner isolado. Models, Folders, Scripts ou descendentes de qualquer uma dessas classes têm uma propriedade Sandboxed disponível na janela Properties.
Habilitar a propriedade Sandboxed designa a instância como um contêiner isolado dentro da árvore DataModel, o que limita as ações que os scripts dentro desse contêiner podem realizar com base no conjunto de valores na propriedade Capabilities.
Capacidades
A propriedade Capabilities é um conjunto de valores que controlam diferentes aspectos da execução. As capacidades se enquadram nas seguintes categorias amplas:
- Controle de execução - Especifica se um script pode ser executado no cliente ou no servidor
- Controle de acesso a instâncias - Especifica quais partes do DataModel um script pode interagir
- Controle de funcionalidade do script - Especifica quais funções do Luau os scripts podem chamar
- Controle de acesso à API do mecanismo - Especifica quais partes da API do Roblox Engine podem ser usadas
Quando um script tenta realizar uma ação que não está no conjunto de capacidades, o Roblox reporta um erro. Os erros normalmente incluem a ação sendo tentada, o alvo de uma ação e a primeira capacidade que está faltando:
Controle de execução
Duas capacidades tratam do controle de execução:
- RunClientScript - LocalScript ou Script com um valor de RunContext de Client é permitido executar no cliente
Se o script estiver Enabled, mas a capacidade correspondente à localização em que tenta iniciar não estiver disponível, uma mensagem de aviso é exibida na janela Output. Se um script não deveria ser executado nesse contexto, desative ou exclua-o.
Note que ModuleScripts não precisam ter essas capacidades de execução para serem requeridos.
Quando um script falha ao iniciar porque a capacidade de controle de execução está faltando, isso é reportado como um aviso na saída, por exemplo:
Controle de acesso a instâncias
Uma única capacidade trata do controle de acesso a instâncias:
- AccessOutsideWrite - O script tem permissão para buscar e receber instâncias de fora do contêiner isolado
Quando a capacidade não está disponível, o script só pode procurar instâncias que estão dentro do seu próprio contêiner isolado. Por exemplo, se o script for colocado diretamente no contêiner isolado, script.Parent.Parent retornará nil.
Além disso, qualquer evento da API do Roblox que passe um Instance em vez disso passa nil para qualquer Instance fora do contêiner isolado. Por exemplo, se o BasePart.Touched for sinalizado por um toque de uma instância fora do contêiner isolado, o evento ainda é recebido, mas o argumento é nil.
Evite definir essa capacidade; as garantias de isolamento são mais fracas quando scripts podem interagir com qualquer instância em um jogo.
Acesso a serviços
Mesmo sem AccessOutsideWrite, scripts no contêiner isolado ainda podem acessar game, workspace e serviços. Esse acesso é fornecido para que os scripts ainda possam chamar métodos úteis desses globais, como DataModel.GetService, mas o acesso a suas instâncias filhas ainda é validado.
Instâncias passadas internamente
Se uma instância for passada por uma chamada de função que não passa pelas APIs do Roblox, a referência é preservada. No entanto, se um ModuleScript for passado dessa forma, não pode ser exigido sem AccessOutsideWrite. Isso ocorre porque o retorno do ModuleScript é frequentemente mutável e pode ser modificado por um script em um contêiner isolado.
Controle de funcionalidade do script
Este conjunto de capacidades controla alguns aspectos gerais dos scripts:
- CreateInstances - O script pode criar novas instâncias usando Instance.new, Instance.fromExisting, ou Instance:Clone()
- LoadString - O script está autorizado a chamar loadstring
- LoadUnownedAsset - O script está autorizado a chamar require com um ID de ativo ou AssetService:LoadAssetAsync()
Lembre-se de que as restrições de função padrão ainda se aplicam. Mesmo que LoadString esteja habilitado, o jogo ainda precisa habilitá-lo em ServerScriptService, e ele ainda está disponível apenas no servidor.
Para criar novas instâncias, além de CreateInstances, é necessária uma capacidade adicional da API do mecanismo que forneça acesso àquela instância.
Controle de acesso à API do mecanismo
Este último grupo de capacidades controla o acesso do script a várias APIs do mecanismo:
- Animation - Acesso a instâncias relacionadas a animações
- AssetCreateUpdate - Acesso a APIs do mecanismo relacionadas à criação ou atualização de ativos
- AssetManagement - Acesso a APIs do mecanismo relacionadas a operações em ativos que não são leitura, criação ou atualização
- AssetRead - Acesso a APIs do mecanismo relacionadas à obtenção de informações sobre ativos
- Audio - Acesso a instâncias relacionadas às APIs de áudio
- AvatarAppearance - Acesso a instâncias relacionadas aos elementos visuais de avatares
- AvatarBehavior - Acesso a APIs do mecanismo relacionadas ao controle ou modificação do humanoide
- Basic - Acesso a APIs gerais que oferecem pouco risco
- CSG - Acesso a instâncias e funções relacionadas à geometria sólida construtiva (CSG)
- CapabilityControl - Acesso para modificar as propriedades Sandboxed e Capabilities das instâncias
- Capture - Acesso a APIs do mecanismo relacionadas à captura de capturas de tela ou vídeos na tela do usuário
- Chat - Acesso a instâncias relacionadas ao chat dentro do jogo
- Consequences - Acesso a APIs para punir usuários (kicks ou bans)
- DataStore - Acesso a APIs de armazém de dados e memória
- DynamicGeneration - Acesso a APIs do mecanismo relacionadas à modificação dinâmica de ativos
- Environment - Acesso a instâncias relacionadas ao controle de como o ambiente é exibido
- Groups - Acesso a APIs do mecanismo relacionadas a grupos/comunidades
- Input - Acesso a instâncias relacionadas à entrada do usuário
- LegacySound - Acesso a APIs do mecanismo relacionadas a sons que serão descontinuados
- LoadOwnedAsset - Acesso a APIs do mecanismo para carregar ativos que são de sua propriedade, compartilhados com você, que pertencem ao Roblox ou que são do tipo de ativo benigno
- Logging - Acesso à API de logs
- Material - Acesso a APIs do mecanismo relacionadas a materiais
- Monetization - Acesso a APIs do mecanismo relacionadas à monetização de um jogo, excluindo a maioria dos PromptPurchases
- Network - Acesso a APIs de rede HTTP
- Physics - Acesso a instâncias relacionadas à física
- PlatformAvatarEditing - Acesso a APIs do mecanismo relacionadas à criação ou atualização de avatares, ou APIs para auxiliar com isso
- Players - Acesso a APIs do mecanismo relacionadas à classe Player ou que retornam/interagem com Players.LocalPlayer
- PromptExternalPurchase - Permite acesso a APIs do mecanismo relacionadas ao aviso de compra de ativos arbitrários
- RemoteEvent - Acesso a instâncias para operações de rede internas
- SensitiveInput - Acesso a APIs do mecanismo relacionadas à captura de entrada sensível do usuário, ou seja, sensores de hardware de alta privacidade.
- ServerCommunication - Acesso a APIs do mecanismo relacionadas à comunicação entre servidores, como MessagingService
- Social - Acesso a APIs do mecanismo relacionadas a recursos sociais, como amigos e convites
- Teleport - Acesso a APIs do mecanismo relacionadas ao teletransporte
- UI - Acesso a instâncias relacionadas a interfaces de usuário
As capacidades de cada classe, propriedade, método e evento são exibidas na referência da API do mecanismo. Por exemplo, Player:GetFriendsOnlineAsync() requer as capacidades Player e Social.
Vários métodos do HttpService estão disponíveis sem quaisquer capacidades, além da capacidade de executar os scripts:
Se uma propriedade ou método de instância for acessado sem uma capacidade requerida, um erro é reportado descrevendo a capacidade faltante.
Finalmente, as capacidades não cobrem todas as instâncias no Roblox Engine atualmente. Instâncias não listadas nesta seção ou na seguinte não estão disponíveis para interação de um contêiner isolado e geram um erro dizendo que a capacidade Unassigned não está disponível para o script atual.
Uma limitação adicional é que as funções getfenv() e setfenv() não estão disponíveis para scripts em um contêiner isolado. Chamá-las de um script isolado reporta:
Somente o acesso do script a instâncias é limitado. As instâncias em si ainda podem existir e operar por conta própria dentro de um contêiner isolado. Luzes ainda brilham, interfaces de usuário ainda estão visíveis e configurações de áudio que já estão conectadas tocam sons.
Interações entre contêineres
Contêineres aninhados
Quando um contêiner isolado é aninhado dentro de outro, as instâncias do contêiner interno são acessíveis ao externo.
As capacidades do contêiner interno são limitadas pelas capacidades do contêiner externo. Por exemplo, se o contêiner externo tiver capacidades de Basic, Audio e CSG, enquanto o contêiner interno tem Basic e Network, apenas as capacidades Basic estão disponíveis para o contêiner interno em tempo de execução.
Se não houver capacidades em comum entre os contêineres interno e externo, o conjunto de capacidades resultante será vazio.
Funções e eventos vinculáveis
BindableEvent e BindableFunction fornecem a melhor maneira de comunicar-se com o contêiner ou permitir que ele execute callbacks com capacidades que ele mesmo não pode usar diretamente.
Quando um evento é disparado ou uma função é invocada, as conexões são executadas no contexto da função que as registrou. Isso significa que, se o callback de evento ou função for registrado pelo contêiner isolado, ele é chamado com as capacidades desse contêiner. Se o callback for registrado pelo código externo, quando scripts do contêiner isolado o invocarem, eles executam suas funções com capacidades disponíveis para suas funções.
É importante notar que, mesmo com a capacidade AccessOutsideWrite, scripts em contêineres isolados não podem invocar eventos ou funções fora de seus contêineres se eles tiverem um conjunto de capacidades maior do que o próprio contêiner.
Quando um script isolado tenta disparar ou invocar um evento ou função (BindableEvent, BindableFunction ou RemoteEvent) cujas capacidades ancestrais excedem as suas, o erro indica a propriedade a ser inspecionada.
Se o alvo não estiver dentro de nenhum contêiner isolado:
Para resolver isso, defina Sandboxed como true para o alvo. Alternativamente, você pode modificar a origem da thread chamadora para que Sandboxed esteja definido como false, mas isso não é recomendado, pois elimina os benefícios de segurança que o isolamento fornece.
Se o alvo for isolado, mas tiver capacidades que a chamadora não possui:
Para resolver isso, reduza as Capabilities do alvo a um subconjunto das da chamadora, ou expanda as Capabilities da chamadora para corresponder às do alvo.
Requisito de módulo
ModuleScripts internos podem ser requeridos pelo contêiner isolado como de costume. No entanto, se a instância alvo estiver fora do contêiner, o ModuleScript só pode ser requerido se o conjunto de capacidades que está disponível para ele for menor ou igual às capacidades disponíveis para o contêiner.
Essa limitação não se aplica às capacidades RunClientScript e RunServerScript. Se o ModuleScript for colocado em um contêiner com apenas RunClientScript, mas for requerido de um script que possui a capacidade RunServerScript, isso é permitido.
Quando require() falha devido a um conflito de capacidades, o erro nomeia o módulo alvo e a propriedade a ser inspecionada da mesma forma que funções e eventos vinculáveis descritos na seção anterior.
Funções chamadas diretamente
Se um ModuleScript em um contêiner isolado for requerido de fora do contêiner, algumas das proteções não estarão disponíveis. Em particular, a função alvo pode acessar todas as instâncias disponíveis para a chamadora. Se a chamadora não estiver em um contêiner isolado, a chamada atua como se AccessOutsideWrite estivesse disponível para ela.
Outras restrições de capacidade ainda se aplicam. Se você tiver uma capacidade de acesso a DataStore, mas o módulo alvo não, ele não poderá chamar métodos DataStore. No entanto, se você passar sua própria função trabalhando com DataStore, o alvo pode executá-la durante essa chamada. Se o alvo programar uma thread usando métodos como aqueles de task, essas threads perdem a capacidade de chamar essa função.
Instâncias podem ser passadas para o módulo alvo ou atribuídas aos campos do módulo.
Se necessário, recomenda-se atribuir membros da tabela usando rawset para evitar a execução de metamétodos __index/__newindex que podem estar definidos na tabela.
A recomendação geral é comunicar-se com BindableEvent e BindableFunction sempre que possível.
Movimento de instâncias
A maioria das instâncias não tem restrições no movimento entre contêineres. No entanto, instâncias de script só podem ser movidas para um contêiner que tenha o mesmo conjunto de capacidades ou um subconjunto dessas capacidades.
Isso significa que um contêiner isolado com AccessOutsideWrite não pode apenas reposicionar um script dentro de si mesmo para fora e obter mais capacidades.