Capacidades de script

Capacidades de script é um sistema que oferece controle sobre ações que os scripts podem executar dentro da subárvore DataModel.Ele fornece um melhor controle sobre scripts de experiência em vez de ser um sistema "tudo ou nada" onde qualquer script pode fazer qualquer coisa que outros scripts possam.

• Este sistema permite que você limite o que os modelos retirados da caixa de ferramentas podem fazer e facilita incluir conteúdo gerado pelo usuário dentro da experiência, mesmo aqueles que contêm scripts.
• Também pode ajudar a garantir uma melhor segurança de experiências que permitem que os jogadores executem seu próprio código, que muitas vezes é executado em um ambiente restrito ou emulado.
• Também pode ser usado para compartilhar bibliotecas que restringem o que elas próprias podem fazer.Por exemplo, uma biblioteca que fornece métodos matemáticos adicionais pode ser restrita ao menor conjunto de capacidades de que precisa para que outros desenvolvedores que usam essa biblioteca não tenham que validar todo o código para garantir que ele não inclua código malicioso.

Habilitar capacidades de script

Para habilitar essa funcionalidade, altere a configuração SandboxedInstanceMode de Default para Experimental na Explorador.

Quando o teste beta do cliente for concluído, este passo não será mais necessário.

Contêiner sandboxado

Este sistema introduz um conceito de um conteúdo sandboxado .Uma instância do tipo , , ou descendentes de qualquer uma dessas classes tem uma propriedade disponível na janela Propriedades do Studio, na seção Permissões .

Habilitar o design da propriedade Sandboxed designa a instância como um contêiner sandboxado 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 da propriedade Capabilities.

Capacidades

A propriedade Capabilities é um conjunto de valores que controlam diferentes aspectos da execução, divididos em quatro grupos:

• Controle de execução - Especifica se um script pode ser executado no cliente ou no servidor
• Controle de acesso à instância - Especifica quais DataModel partes um script pode interagir
• Controle de funcionalidade de script - Especifica quais scripts de funções Luau podem chamar
• Controle de acesso à API do motor - Especifica quais partes da API do motor Roblox podem ser usadas

Quando um script tenta executar uma ação que não está no conjunto de capacidades para o estado de execução atual, um erro é relatado.Erros geralmente incluem a ação que está sendo tentada, o alvo de uma ação e a primeira capacidade que está faltando, por exemplo:

The current thread cannot modify 'Workspace' (lacking capability AccessOutsideWrite)

The current thread cannot call 'Clone' (lacking capability CreateInstances)

The current thread cannot call 'GetSecret' (lacking capability Network)

Controle de execução

Este conjunto inclui duas capacidades:

• RunClientScript - LocalScript ou Script com um valor de RunContext de Client é permitido executar no cliente
• RunServerScript - Script com um valor de RunContext de Server é permitido executar no servidor

Se o script for Enabled, mas a capacidade correspondente ao local em que ele tenta iniciar não está disponível, uma mensagem de aviso é exibida na janela Saída .Se um script não deveria ser executado nesse contexto, desabilite ou exclua-o.

Observe que ModuleScripts não são necessários ter essas capacidades de execução para serem necessárias.

Quando um script falha ao iniciar porque a capacidade de controle de execução está faltando, ele é relatado como uma advertência na saída, por exemplo:

Cannot start server script 'Script' (lacking capability RunServerScript)

Controle de acesso à instância

Este conjunto inclui apenas uma única capacidade:

• Acesso fora de escrito - O script é permitido obter e receber instâncias de fora do contêiner sandboxed

Quando a capacidade não está disponível, o script só pode pesquisar instâncias que estão dentro de seu próprio contêiner sandboxado.Por exemplo, se o script for colocado diretamente no contêiner sandboxado, script.Parent.Parent retorna nil .

Além disso, qualquer evento da API Roblox que passe em um Instance em vez de passar em um nil para qualquer Instance fora do contêiner sandboxed.Por exemplo, se o BasePart.Touched for sinalizado por um toque de uma instância fora do contêiner sandboxeado, o evento ainda é recebido, mas o argumento é nil .

Evite definir essa capacidade; garantias de sandboxing são mais fracas quando os scripts podem interagir com qualquer instância em uma experiência.

Acesso aos services

Mesmo sem AcessoExternoEscrito , os scripts no contêiner sandbox 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 às instâncias filhas ainda é validado.

Instâncias internamente passadas

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 maneira, ele não pode ser exigido sem AcessoExternoEscrito .Isso ocorre porque o retorno do ModuleScript geralmente é mutável e pode ser modificado por um script em um contêiner sandboxado.

Controle de funcionalidade de script

Este conjunto de capacidades controla alguns aspectos gerais de scripts:

• Requisito de Recurso - O script é permitido chamar require com um ID de recurso
• Carregar String - O script é permitido chamar loadstring
• ScriptGlobals - O script tem shared e _G disponível
• Criar Instâncias - O script pode criar novas instâncias usando Instance.new, Instance.fromExisting ou Instance:Clone()

Tenha em mente que as restrições de função padrão ainda se aplicam.Mesmo que Carregar String esteja habilitado, a experiência ainda precisa habilitá-lo em ServerScriptService e ainda está disponível apenas no servidor.

Para criar novas instâncias, além de CriarInstâncias , é necessária uma capacidade adicional da API do Motor fornecendo acesso a essa instância.

Controle de acesso ao API do motor

Este último grupo de capacidades controla o acesso de script a várias interfaces de API do Motor:

• Básico - Acesso a instâncias simples e blocos de construção essenciais
• Áudio - Acesso a instâncias relacionadas a APIs de áudio
• Armazenamento de Dados - Acesso às APIs de armazenamento de dados e memória
• Rede - Acesso às APIs de rede HTTP
• Física - Acesso a instâncias relacionadas à física
• UI - Acesso a instâncias relacionadas a interfaces de usuário
• CSG : acesso a instâncias e funções relacionadas à geometria sólida construtiva (GSC - Geometria Sólida Construtiva)
• Chat : acesso a instâncias relacionadas ao chat na experiência
• Animação : acesso a instâncias relacionadas a animações
• Avatar : acesso a instâncias relacionadas a avatares
• Entrada : acesso a instâncias relacionadas à entrada do usuário
• Ambiente : acesso a instâncias relacionadas ao controle de como o ambiente é exibido
• Evento Remoto : acesso a instâncias para operações de rede interna

Há também instâncias que estão disponíveis sem quaisquer capacidades além de serem capazes de executar os scripts.Estes incluem os seguintes métodos HttpService :

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

Se uma propriedade ou método de instância for acessado sem uma capacidade necessária, um erro é relatado descrevendo a capacidade que falta.

Finalmente, as capacidades não cobrem todas as instâncias no Roblox Engine hoje.Instâncias não listadas nesta seção ou na seguinte não estão disponíveis para interação a partir de um contêiner sandboxed e lançam um erro dizendo que uma capacidade não designada não está disponível para o script atual .

Uma limitação adicional é que getfenv e setfenv funções não estão disponíveis para scripts em um contêiner sandboxado.

Apenas o acesso de script a instâncias é limitado.As próprias instâncias ainda podem existir e operar por si só dentro de um contêiner sandboxado.As luzes ainda brilham, as interfaces do usuário ainda são visíveis e os conjuntos de áudio que já estão ligados tocam sons.

Designações de capacidade da API do motor

Aqui está a lista de instâncias e métodos (se diferente da capacidade de instância) para cada capacidade da API do Motor:

• Básico * Attachment

  • Beam , ParticleEmitter , Smoke , Sparkles , Trail
  • SurfaceAppearance , Decal , FaceInstance , Texture
  • Light , PointLight , SpotLight
  • Part , MeshPart , CornerWedgePart , TriangleMeshPart , TrussPart , WedgePart
  • FloatCurve , RotationCurve , EulerRotationCurve , Vector3Curve
  • Tween , TweenService
  • Wire
  • WorldModel
  • CollectionService , Debris , RunService

• Áudio * AudioAnalyzer , AudioChorus , AudioCompressor , AudioDistortion , AudioEcho , AudioEqualizer , AudioFader , AudioFader , AudioFilter , AudioFlanger , AudioLimiter , AudioPitchShifter , AudioReverb

  • AudioEmitter , AudioPlayer
  • AudioDeviceOutput , AudioListener

• Armazenamento de Dados * DataStore , OrderedDataStore , GlobalDataStore

  • DataStoreService , MemoryStoreService
  • DataStoreGetOptions , DataStoreIncrementOptions , DataStoreInfo , DataStoreKey , DataStoreKeyInfo , DataStoreObjectVersionInfo , DataStoreOptions , DataStoreSetOptions
  • MemoryStoreHashMap , MemoryStoreQueue , MemoryStoreSortedMap

• Rede * HttpService:GetAsync() , HttpService:RequestAsync() , HttpService:PostAsync() , HttpService:UrlEncode() , HttpService:GetSecret()

• Física * AlignOrientation , AlignPosition , DynamicRotate

  • JointInstance , Motor , Motor6D
  • AngularVelocity , LinearVelocity , LineForce , Torque , VectorForce
  • Weld
  • Constraint , BallSocketConstraint , CylindricalConstraint , HingeConstraint , NoCollisionConstraint , PlaneConstraint , PrismaticConstraint , RigidConstraint , RodConstraint , RopeConstraint , SlidingBallConstraint , SpringConstraint , TorsionSpringConstraint , UniversalConstraint , WeldConstraint

• UI * BasePlayerGui , PlayerGui , BillboardGui , GuiBase , GuiBase2d , GuiBase3d , LayerCollector , ScreenGui , SurfaceGui , SurfaceGuiBase , UIBase

  • CanvasGroup , Frame , ScrollingFrame
  • GuiButton , GuiLabel , GuiObject , ImageButton , ImageLabel
  • Dialog , DialogChoice , ProximityPrompt
  • TextBox , TextButton , TextFilterResult , TextFilterTranslatedResult , TextLabel , TextService , GetTextBoundsParams
  • Path2D
  • UIComponent , UICorner , UIDragDetector , UIFlexItem , UIGradient , UIGridLayout , UIGridStyleLayout , UILayout , UIListLayout , UIPadding , UIPageLayout , UIScale , UIStroke , UITableLayout
  • UIConstraint , UIAspectRatioConstraint , UISizeConstraint , UITextSizeConstraint
  • VideoFrame , ViewportFrame

• CSG * GeometryService

  • BasePart métodos: BasePart:IntersectAsync() , BasePart:SubtractAsync() , BasePart:UnionAsync()
  • IntersectOperation (também requer Básico ), NegateOperation (também requer Básico ), PartOperation (também requer Básico ), UnionOperation (também requer Básico )

• Bate-papo * BubbleChatConfiguration , BubbleChatMessageProperties

  • ChannelTabsConfiguration
  • ChatInputBarConfiguration , ChatWindowConfiguration , ChatWindowMessageProperties
  • TextChannel , TextChatCommand , TextChatConfigurations , TextChatMessage , TextChatMessageProperties , TextChatService , TextSource

• Animação * Bone (também requer Básico )

  • Animation , AnimationClip , AnimationClipProvider , AnimationController , AnimationRigData , AnimationTrack , Animator
  • CurveAnimation
  • FaceControls , IKControl
  • Keyframe , KeyframeMarker , KeyframeSequence
  • MarkerCurve
  • PoseBase , Pose , NumberPose

• Avatar * Accessory , AccessoryDescription

  • Accoutrement , Clothing , Shirt , Pants
  • BaseWrap , WrapDeformer , WrapLayer , WrapTarget
  • BodyColors , BodyPartDescription , CharacterAppearance , ShirtGraphic
  • CharacterMesh
  • Humanoid , HumanoidDescription

• Entrada * GamepadService , KeyboardService , MouseService

  • ContextActionService , TouchInputService , UserInputService
  • InputObject , Mouse , PlayerMouse

• Ambiente * Atmosphere , Clouds , Lighting , Sky

  • BloomEffect , BlurEffect , ColorCorrectionEffect , ColorGradingEffect , DepthOfFieldEffect , PostEffect , SunRaysEffect

• Evento Remoto * BaseRemoteEvent , RemoteEvent , UnreliableRemoteEvent

  • RemoteFunction

Interações entre contêineres

Contêineres aninhados

Quando um container sandboxado é 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 externo.Por exemplo, se o contêiner externo tiver capacidades de Básico , Áudio e CSG , enquanto o contêiner interno tem Básico e Rede , apenas Básico capacidades estarão disponíveis para o contêiner interno em tempo de execução.

Se não houver capacidades em comum entre os contêineres internos e externos, o conjunto de capacidades resultante está vazio.

Funções e eventos bindáveis

BindableEvent e BindableFunction fornecem a melhor maneira de se comunicar com o contêiner ou permitir que ele execute chamadas com capacidades que ele mesmo não é permitido usar diretamente.

Quando um evento ou uma função é disparada, as conexões são executadas no contexto da função que os registrou.Isso significa que, se o evento ou função de chamada for registrado pelo contêiner sandboxado, ele é chamado com as capacidades desse contêiner.Se o retorno de chamada for registrado pelo código fora, quando os scripts de contêiner em sandbox invocam eles, eles executam suas funções com capacidades disponíveis para suas funções.

É importante notar que, mesmo com a capacidade Acesso Externo Escrito , os scripts em contêineres sandboxados não podem invocar eventos ou funções fora de seus contêineres se tiverem um conjunto de capacidades maior que o próprio contêiner.

necessitar/requisitarde módulo

O interno ModuleScripts pode ser solicitado pelo contêiner sandboxado como de costume.No entanto, se a instância alvo estiver fora do contêiner, o ModuleScript só pode ser exigido se o conjunto de capacidades disponível para ela 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 necessário por um script que tenha a capacidade RunServerScript , ele é permitido ter sucesso e executar essas funções no servidor.

Funções chamadas diretamente

Se um ModuleScript em um contêiner sandboxado for necessário de fora do contêiner, algumas das proteções não estarão disponíveis.Em particular, a função alvo é capaz de acessar todas as instâncias disponíveis para o chamador.Se o chamador não estiver em um contêiner sandboxado, a chamada atua como se AcessoExternoEscreva estivesse disponível para ele.

Outras restrições de capacidade ainda se aplicam.Se você tiver uma capacidade de acesso ao Armazenamento de Dados , mas o módulo alvo não tiver, ele não será capaz de 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 agendar um subprocesso usando métodos como os de task, esses subprocessos 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, é recomendado atribuir membros da tabela usando rawset para evitar executar __index / __newindex metodos metálicos que possam ser definidos na tabela.

A recomendação geral é se comunicar com BindableEvent e BindableFunction sempre que possível.

Movimento de instâncias

A maioria das instâncias não tem restrições de movimento entre contêineres.No entanto, as 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 o contêiner sandboxado com AcessoExternoEscrever não pode apenas re-paisar um script dentro de si mesmo para o exterior e obter mais capacidades.