Capacidades de script

Capacidades de script es un sistema que ofrece control sobre las acciones que los scripts pueden realizar dentro del subárbol DataModel.Proporciona un mejor control sobre los scripts de experiencia en lugar de ser un sistema "todo o nada" en el que cualquier script pueda hacer cualquier cosa que otros scripts puedan.

• Este sistema le permite limitar lo que los modelos extraídos de la caja de herramientas pueden hacer y facilita incluir contenido generado por el usuario dentro de la experiencia, incluso aquellos que contienen scripts.
• También puede ayudar a garantizar una mejor seguridad de las experiencias que permiten a los jugadores ejecutar su propio código, que a menudo se ejecuta en un entorno, ambienterestringido o emulado.
• También se puede usar para compartir bibliotecas que restringen lo que pueden hacer ellos mismos.Por ejemplo, una biblioteca que proporciona métodos matemáticos adicionales puede restringirse al conjunto más pequeño de capacidades que necesita para que otros desarrolladores que usen esa biblioteca no tengan que validar toda la base de código para asegurarse de que no incluya código malicioso.

Habilitar capacidades de script

Para habilitar esta función, cambie la configuración de SandboxedInstanceMode de Default a Experimental en el Explorador.

Cuando se complete la prueba beta del cliente, este paso ya no será necesario.

Contenedor de sandboxeado

Este sistema introduce un concepto de un contenedor en una caja de arena .Una instancia de tipo Model , Folder , Script , o descendientes de cualquiera de esas clases tienen una propiedad Sandboxed disponible en la ventana Propiedades del Studio , bajo la sección Permisos .

Activar la propiedad Sandboxed designa a la instancia como un contenedor encapsulado dentro del árbol DataModel, lo que limita las acciones que los scripts dentro de ese contenedor pueden realizar según el conjunto de valores de la propiedad Capabilities.

Capacidades

La propiedad Capabilities es un conjunto de valores que controlan diferentes aspectos de la ejecución, divididos en cuatro grupos:

• Control de ejecución - Especifica si un script puede ejecutarse en el cliente o en el servidor
• Control de acceso a la instancia - Especifica qué DataModel partes puede interactuar un script
• Control de funcionalidad de scripts - Especifica qué scripts de funciones de Luau pueden llamar
• Control de acceso a la API del motor - Especifica qué partes de la API del motor de Roblox se pueden usar

Cuando un script intenta realizar una acción que no está en el conjunto de capacidades para el estado de ejecución actual, se informa un error.Los errores generalmente incluyen la acción que se está intentando, el objetivo de una acción y la primera capacidad que falta, por ejemplo:

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)

Control de ejecución

Este conjunto incluye dos capacidades:

• Ejecutar el script del cliente - LocalScript o Script con un valor de RunContext de Client se permite ejecutar en el cliente
• Ejecutar el script del servidor - Script con un valor de RunContext de Server es permitido ejecutarse en el servidor

Si el script es Enabled , pero la capacidad correspondiente a la ubicación en la que intenta comenzar no está disponible, se muestra un mensaje de advertencia en la ventana Salida .Si un script no se supone que se ejecute en ese contexto, desactivarlo o eliminarlo.

Tenga en cuenta que ModuleScripts no se requiere tener estas capacidades de ejecución para ser requeridas.

Cuando un script no se inicia porque falta la capacidad de control de ejecución, se informa como una advertencia en la Salida, por ejemplo:

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

Control de acceso a instancias

Este conjunto incluye solo una sola capacidad:

• Acceso desde el exterior a escribir - Se permite al script obtener y recibir instancias desde fuera del contenedor acotado

Cuando la capacidad no está disponible, el script solo puede buscar instancias que estén dentro de su propio contenedor de arena.Por ejemplo, si el script se coloca directamente en el contenedor sandboxeado, script.Parent.Parent devuelve nil .

Además, cualquier evento de API de Roblox que pase en un Instance pasa en nil por cualquier Instance fuera del contenedor sandboxeado.Por ejemplo, si el BasePart.Touched es señalado por un toque de una instancia fuera del contenedor sandboxeado, el evento aún se recibe, pero el argumento es nil .

Evite establecer esta capacidad; las garantías de arena son más débiles cuando los scripts pueden interactuar con cualquier instancia en una experiencia.

Acceso a los servicios

Incluso sin AccessOutsideWrite , los scripts en el contenedor de sandbox aún pueden acceder a game, workspace y servicios.Este acceso se proporciona para que los scripts todavía puedan llamar métodos útiles de esos globales, como DataModel.GetService , pero el acceso a sus instancias hijas sigue siendo válido.

Instancias internamente pasadas

Si una instancia se pasa a través de una llamada de función que no pasa por las API de Roblox, se preserva la referencia.Sin embargo, si se pasa un ModuleScript de esta manera, no se puede requerir sin Acceso fuera de escribir .Esto se debe a que el retorno del ModuleScript a menudo es mutable y se puede modificar por un script en un contenedor de arena.

Control de funcionalidad de scripts

Este conjunto de capacidades controla algunos aspectos generales de los scripts:

• Requisito de activo - Se permite que el script llame a require con una ID de activo
• Cargar cadena - Se permite que el script llame a loadstring
• ScriptGlobals - El script tiene shared y _G disponibles
• Crear instancias - El script puede crear nuevas instancias usando Instance.new, Instance.fromExisting o Instance:Clone()

Tenga en cuenta que las restricciones de función predeterminadas siguen aplicándose.Incluso si LoadString está habilitado, la experiencia aún debe activarla en ServerScriptService , y aún solo está disponible en el servidor.

Para crear nuevas instancias, además de Crear instancias , se requiere una capacidad adicional de API de Motor que proporcione acceso a esa instancia.

Control de acceso a la API del motor

Este último grupo de capacidades controla el acceso de script a varias API de Motor:

• Básico - Acceso a instancias simples y bloques de construcción esenciales
• Audio - Acceso a instancias relacionadas con las API de audio
• Almacén de datos - Acceso a las API de almacén de datos y almacén de memoria
• Red - Acceso a las API de red HTTP
• Física - Acceso a instancias relacionadas con la física
• UI - Acceso a instancias relacionadas con interfaces de usuario
• CSG : acceso a instancias y funciones relacionadas con la geometría sólida constructiva (Geometría constructiva de sólidos)
• Chat : acceso a instancias relacionadas con el chat en la experiencia
• Animación : acceso a instancias relacionadas con las animaciones
• Avatar : acceso a instancias relacionadas con avatares
• Entrada : acceso a instancias relacionadas con la entrada del usuario
• Entorno : acceso a instancias relacionadas con el control de cómo se muestra el entorno
• Evento remoto : acceso a instancias para operaciones de red interna

También hay instancias que están disponibles sin ninguna capacidad además de poder ejecutar los scripts.Estos incluyen los siguientes métodos HttpService :

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

Si una propiedad o método de instancia se accede sin una capacidad requerida, se informa un error que describe la capacidad que falta.

Por último, las capacidades no cubren todas las instancias en el motor Roblox hoy en día.Las instancias no enumeradas en esta sección o en la siguiente no están disponibles para la interacción desde un contenedor de sandbox y lanzan un error diciendo que una capacidad no asignada no está disponible para el script actual.

Una limitación adicional es que las funciones getfenv y setfenv no están disponibles para scripts en un contenedor en modo de arena.

Solo el acceso de script a las instancias está limitado.Las instancias mismas aún pueden existir y operar por sí mismas dentro de un contenedor de arena.Las luces siguen brillando, las interfaces de usuario siguen siendo visibles y las configuraciones de audio que ya están conectadas reproducen sonidos.

Asignaciones de capacidad de API del motor

Aquí está la lista de instancias y métodos (si son diferentes de la capacidad de instancia) para cada capacidad de API de 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

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

  • AudioEmitter , AudioPlayer
  • AudioDeviceOutput , AudioListener

• Almacén de datos * DataStore , OrderedDataStore , GlobalDataStore

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

• Red * 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 (también requiere Básico ), NegateOperation (también requiere Básico ), PartOperation (también requiere Básico ), UnionOperation (también requiere Básico )

• Chat * BubbleChatConfiguration , BubbleChatMessageProperties

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

• Animación * Bone (también requiere 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

• Ingreso * GamepadService , KeyboardService , MouseService

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

• Medio ambiente * Atmosphere , Clouds , Lighting , Sky

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

• Acontecimiento remoto * BaseRemoteEvent , RemoteEvent , UnreliableRemoteEvent

  • RemoteFunction

Interacciones entre contenedores

Contenedores anidados

Cuando un contenedor de sandbox está anidado dentro de otro, las instancias del contenedor interno son accesibles para el exterior.

Las capacidades del contenedor interno están limitadas por las capacidades del exterior.Por ejemplo, si el contenedor exterior tiene capacidades de Básico , Audio y CSG , mientras que el contenedor interno tiene Básico y Red , solo están disponibles las capacidades Básicas para el contenedor interno en tiempo de ejecución.

Si no hay capacidades en común entre los contenedores interno y externo, el conjunto de capacidades resultante está vacío.

Funciones y eventos vinculables

BindableEvent y BindableFunction proporcionan la mejor manera de comunicarse con el contenedor o permitir que se ejecuten llamadas de devolución de llamadas con capacidades que no se le permite usar directamente.

Cuando se activa un evento o una función, se ejecutan conexiones en el contexto de la función que los registró.Esto significa que si el evento o la llamada de función se registra por el contenedor sandboxeado, se llama con las capacidades de ese contenedor.Si el retorno de llamada se registra por el código fuera, cuando se invocan los scripts del contenedor en modo de arena, ejecutan sus funciones con las capacidades disponibles para sus funciones.

Es importante tener en cuenta que incluso con la capacidad Acceso desde el exterior escrito , los scripts en contenedores aislados no pueden invocar eventos o funciones fuera de sus contenedores si tienen un conjunto de capacidades más grande que el propio contenedor.

necesario, obligatoriode módulo

El interno ModuleScripts se puede solicitar al contenedor sandboxeado como de costumbre.Sin embargo, si la instancia objetivo está fuera del contenedor, el ModuleScript solo se puede requerir si el conjunto de capacidades disponible para ella es menor o igual a las capacidades disponibles para el contenedor.

Esta limitación no se aplica a las capacidades Ejecutar cliente de script y Ejecutar script del servidor .Si el ModuleScript se coloca en un contenedor con solo Ejecutar script del cliente pero se requiere desde un script que tenga la capacidad de Ejecutar script del servidor , se le permite tener éxito y ejecutar esas funciones en el servidor.

Funciones llamadas directamente

Si se requiere un ModuleScript en un contenedor enmarcado desde el exterior del contenedor, algunas de las protecciones no están disponibles.En particular, la función objetivo es capaz de acceder a todas las instancias disponibles para el llamador.Si el llamador no está en un contenedor de sandbox, la llamada actúa como si AccessOutsideWrite estuviera disponible para él.

Otras restricciones de capacidad siguen aplicándose.Si tiene una capacidad de acceso de almacén de datos pero el módulo objetivo no lo hace, no puede llamar a los métodos DataStore.Sin embargo, si pasas tu propia función trabajando con DataStore, el objetivo puede ejecutarla durante esa llamada.Si el objetivo programó un hilo usando métodos como los de task , esos hilos pierden la capacidad de llamar esa función.

Las instancias se pueden pasar al módulo objetivo o asignarse a los campos del módulo.

Si es necesario, se recomienda asignar miembros de la tabla usando rawset para evitar ejecutar __index / __newindex metamétodos que se pueden establecer en la tabla.

La recomendación general es comunicarse con BindableEvent y BindableFunction cuando sea posible.

Movimiento de instancias

La mayoría de las instancias no tienen restricciones sobre el movimiento entre contenedores.Sin embargo, las instancias de script solo se pueden mover a un contenedor que tenga el mismo conjunto de capacidades o un subconjunto de esas capacidades.

Esto significa que el contenedor encapsulado con AccessOutsideWrite no puede simplemente re-padrear un script dentro de sí mismo al exterior y obtener más capacidades.