Capacités des scripts

Les capacités des scripts vous permettent de contrôler quelles actions les scripts peuvent effectuer à l'intérieur de l'arborescence DataModel. Plutôt que d'utiliser le système par défaut "tout ou rien", vous pouvez configurer un script pour qu'il ne puisse accéder qu'à certaines catégories, telles que l'audio, la physique, les magasins de données, et plus encore.

• Ce système vous permet de limiter ce que les modèles pris dans la boîte à outils peuvent faire et facilite l'inclusion de contenu généré par les utilisateurs dans le jeu.
• Il peut également aider à garantir une meilleure sécurité des jeux qui permettent aux joueurs d'exécuter leur propre code, qui est souvent exécuté dans un environnement restreint ou émulé.
• Il peut aussi être utilisé pour partager des bibliothèques qui restreignent ce qu'elles peuvent faire elles-mêmes. Par exemple, une bibliothèque fournissant des méthodes mathématiques supplémentaires peut être restreinte au plus petit ensemble de capacités dont elle a besoin afin que d'autres développeurs utilisant cette bibliothèque n'aient pas à valider l'ensemble du code de base pour s'assurer qu'il n'inclut pas de code malveillant.

Activer les capacités des scripts

Pour activer cette fonctionnalité, changez la propriété SandboxedInstanceMode de Default à Experimental dans la fenêtre Explorer et Propriétés.

Conteneur sandboxé

Les capacités des scripts introduisent le concept de conteneur sandboxé. Models, Folders, Scripts, ou les descendants de l'une de ces classes ont une propriété Sandboxed disponible dans la fenêtre Propriétés.

L'activation de la propriété Sandboxed désigne l'instance comme un conteneur sandboxé à l'intérieur de l'arborescence DataModel, ce qui limite les actions que les scripts à l'intérieur de ce conteneur peuvent effectuer en fonction de l'ensemble de valeurs dans la propriété Capabilities.

Capacités

La propriété Capabilities est un ensemble de valeurs qui contrôlent différents aspects de l'exécution. Les capacités tombent dans les catégories générales suivantes :

• Contrôle d'exécution - Spécifie si un script peut s'exécuter sur le client ou le serveur
• Contrôle d'accès aux instances - Spécifie avec quelles parties de DataModel un script peut interagir
• Contrôle des fonctionnalités du script - Spécifie quelles fonctions Luau les scripts peuvent appeler
• Contrôle d'accès à l'API de moteur - Spécifie quelles parties de l'API de moteur Roblox peuvent être utilisées

Lorsque un script tente d'effectuer une action qui n'est pas dans l'ensemble de capacités, Roblox rapporte une erreur. Les erreurs incluent généralement l'action tentée, la cible d'une action, et la première capacité qui manque :

Le thread actuel ne peut pas modifier 'Workspace' (manque la capacité AccessOutsideWrite)
Le thread actuel ne peut pas appeler 'Clone' (manque la capacité CreateInstances)
Le thread actuel ne peut pas appeler 'GetSecret' (manque la capacité Network)

Contrôle d'exécution

Deux capacités gèrent le contrôle d'exécution :

• RunClientScript - LocalScript ou Script avec une valeur de RunContext de Client est autorisé à s'exécuter sur le client
• RunServerScript - Script avec une valeur de RunContext de Server est autorisé à s'exécuter sur le serveur

Si le script est Enabled, mais la capacité correspondant à l'emplacement où il essaie de démarrer n'est pas disponible, un message d'avertissement est affiché dans la fenêtre Sortie. Si un script n'était pas censé s'exécuter dans ce contexte, désactivez-le ou supprimez-le.

Notez que ModuleScripts n'ont pas besoin d'avoir ces capacités d'exécution pour être requis.

Lorsque un script échoue à démarrer en raison d'une capacité de contrôle d'exécution manquante, cela est rapporté comme un avertissement dans la sortie, par exemple :

Impossible de démarrer le script serveur 'Script' (manque la capacité RunServerScript)

Contrôle d'accès aux instances

Une seule capacité gère le contrôle d'accès aux instances :

• AccessOutsideWrite - Le script est autorisé à récupérer et recevoir des instances de l'extérieur du conteneur sandboxé

Lorsque la capacité n'est pas disponible, le script ne peut rechercher que les instances qui sont à l'intérieur de son propre conteneur sandboxé. Par exemple, si le script est placé directement dans le conteneur sandboxé, script.Parent.Parent retourne nil.

De plus, tout événement d'API Roblox qui passe une Instance passe à la place nil pour toute Instance en dehors du conteneur sandboxé. Par exemple, si le BasePart.Touched est signalé par un contact d'une instance en dehors du conteneur sandboxé, l'événement est toujours reçu, mais l'argument est nil.

Évitez de définir cette capacité ; les garanties de sandboxing sont plus faibles lorsque les scripts peuvent interagir avec n'importe quelle instance dans un jeu.

Accès aux services

Même sans AccessOutsideWrite, les scripts dans le conteneur sandboxé peuvent toujours accéder à game, workspace, et aux services. Cet accès est fourni afin que les scripts puissent appeler les méthodes utiles de ces globaux, comme DataModel.GetService, mais l'accès à leurs instances enfants est toujours validé.

Instances passées en interne

Si une instance est passée à travers un appel de fonction qui ne passe pas par les APIs Roblox, la référence est préservée. Cependant, si un ModuleScript est passé de cette manière, il ne peut pas être requis sans AccessOutsideWrite. Cela est dû au fait que le retour du ModuleScript est souvent mutable et peut être modifié par un script dans un conteneur sandboxé.

Contrôle des fonctionnalités du script

Cet ensemble de capacités contrôle certains aspects généraux des scripts :

• CreateInstances - Le script peut créer de nouvelles instances en utilisant Instance.new, Instance.fromExisting, ou Instance:Clone()
• LoadString - Le script est autorisé à appeler loadstring
• LoadUnownedAsset - Le script est autorisé à appeler require avec un ID d'actif ou AssetService:LoadAssetAsync()
• ScriptGlobals - Le script a shared et _G disponibles

Gardez à l'esprit que les restrictions de fonction par défaut s'appliquent toujours. Même si LoadString est activé, le jeu doit encore l'activer dans ServerScriptService, et il est encore uniquement disponible sur le serveur.

Pour créer de nouvelles instances, en plus de CreateInstances, une capacité API moteur supplémentaire fournissant l'accès à cette instance est nécessaire.

Contrôle d'accès à l'API du moteur

Ce dernier groupe de capacités contrôle l'accès des scripts à diverses APIs du moteur :

• Animation - Accès aux instances liées aux animations
• AssetCreateUpdate - Accès aux APIs moteur liées à la création ou à la mise à jour d'actifs
• AssetManagement - Accès aux APIs moteur liées aux opérations sur les actifs qui ne sont pas lus, créés ou mis à jour
• AssetRead - Accès aux APIs moteur concernant les informations sur les actifs
• Audio - Accès aux instances liées aux APIs audio
• AvatarAppearance - Accès aux instances liées aux éléments visuels des avatars
• AvatarBehavior - Accès aux APIs moteur liées au contrôle ou à la modification du humanoïde
• Basic - Accès aux APIs générales offrant peu de risque
• CSG - Accès aux instances et fonctions liées à la géométrie solide constructive (CSG)
• CapabilityControl - Accès à la modification des propriétés Sandboxed et Capabilities des instances
• Capture - Accès aux APIs moteur liées à la capture d'écrans ou de vidéos sur l'écran de l'utilisateur
• Chat - Accès aux instances liées au chat en jeu
• Consequences - Accès aux APIs pour punir les utilisateurs (kicks ou bans)
• DataStore - Accès aux APIs de magasin de données et de mémoire
• DynamicGeneration - Accès aux APIs moteur liées à la modification dynamique des actifs
• Environment - Accès aux instances liées au contrôle de l'affichage de l'environnement
• Groups - Accès aux APIs moteur relatives aux groupes/communautés
• Input - Accès aux instances liées à l'entrée utilisateur
• LegacySound - Accès aux APIs moteur liées aux sons qui seront dépréciés
• LoadOwnedAsset - Accès aux APIs moteur pour charger des actifs qui vous appartiennent, vous sont partagés, sont la propriété de Roblox, ou sont d'un type d'actif bénin
• Logging - Accès à l'API de journaux
• Material - Accès aux APIs moteur liées aux matériaux
• Monetization - Accès aux APIs moteur relatives à la monétisation d'un jeu, excluant la plupart des PromptPurchases
• Network - Accès aux APIs de réseau HTTP
• Physics - Accès aux instances liées à la physique
• PlatformAvatarEditing - Accès aux APIs moteur liées à la création ou à la mise à jour des avatars, ou aux APIs pour aider à cela
• Players - Accès aux APIs moteur relatives à la classe Player ou qui retournent/interagissent avec Players.LocalPlayer
• PromptExternalPurchase - Permet l'accès aux APIs moteur liées à la demande d'achat d'actifs arbitraires
• RemoteEvent - Accès aux instances pour les opérations de réseau internes
• SensitiveInput - Accès aux APIs moteur liées à la capture d'entrées sensibles de l'utilisateur, c'est-à-dire des capteurs matériels à haute confidentialité.
• ServerCommunication - Accès aux APIs moteur liées à la communication entre serveurs, comme MessagingService
• Social - Accès aux APIs moteur relatives aux fonctionnalités sociales, telles que les amis et les invitations
• Teleport - Accès aux APIs moteur liées à la téléportation
• UI - Accès aux instances liées aux interfaces utilisateur

Les capacités de chaque classe, propriété, méthode, et événement sont affichées dans la référence de l'API du moteur. Par exemple, Player:GetFriendsOnlineAsync() nécessite les capacités Player et Social.

Plusieurs méthodes de HttpService sont disponibles sans aucune capacité, si ce n'est la possibilité d'exécuter les scripts :

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

Si une propriété ou une méthode d'instance est accédée sans une capacité requise, une erreur est rapportée décrivant la capacité manquante.

Enfin, les capacités ne couvrent pas toutes les instances dans le moteur Roblox aujourd'hui. Les instances non listées dans cette section ou la suivante ne sont pas disponibles pour l'interaction depuis un conteneur sandboxé et génèrent une erreur indiquant qu'une capacité Non assignée n'est pas disponible pour le script actuel.

Une limitation supplémentaire est que les fonctions getfenv() et setfenv() ne sont pas disponibles pour les scripts dans un conteneur sandboxé. Les appeler depuis un script sandboxé rapporte :

Le thread actuel ne peut pas appeler ['getfenv'/'setfenv'] - la cible utilise des APIs non disponibles dans le sandbox actuel

Seulement l'accès des scripts aux instances est limité. Les instances elles-mêmes peuvent toujours exister et fonctionner par elles-mêmes à l'intérieur d'un conteneur sandboxé. Les lumières brillent toujours, les interfaces utilisateur sont toujours visibles, et les configurations audio déjà câblées émettent des sons.

Interactions entre conteneurs

Conteneurs imbriqués

Lorsque un conteneur sandboxé est imbriqué à l'intérieur d'un autre, les instances du conteneur interne sont accessibles pour le conteneur externe.

Les capacités du conteneur interne sont limitées par les capacités du conteneur externe. Par exemple, si le conteneur externe a des capacités de Basic, Audio et CSG, tandis que le conteneur interne a Basic et Network, seules les capacités Basic sont disponibles pour le conteneur interne au moment de l'exécution.

S'il n'y a pas de capacités communes entre le conteneur interne et le conteneur externe, l'ensemble de capacités résultant est vide.

Fonctions et événements liés

BindableEvent et BindableFunction fournissent le meilleur moyen de communiquer avec le conteneur ou de lui permettre d'exécuter des rappels avec des capacités qu'il n'est pas lui-même autorisé à utiliser directement.

Lorsque un événement est déclenché ou une fonction est invoquée, les connexions s'exécutent dans le contexte de la fonction qui les a enregistrées. Cela signifie que si le rappel d'événement ou de fonction est enregistré par le conteneur sandboxé, il est appelé avec les capacités de ce conteneur. Si le rappel est enregistré par le code extérieur, lorsque les scripts du conteneur sandboxé les invoquent, ils exécutent vos fonctions avec les capacités disponibles pour vos fonctions.

Il est important de noter que même avec la capacité AccessOutsideWrite, les scripts dans les conteneurs sandboxés ne peuvent pas invoquer des événements ou des fonctions en dehors de leurs conteneurs s'ils ont un ensemble de capacités plus important que celui du conteneur lui-même.

Lorsque un script sandboxé essaie de déclencher ou d'invoquer un événement ou une fonction (BindableEvent, BindableFunction, ou RemoteEvent) dont les capacités ancestrales dépassent les siennes, l'erreur nomme la propriété à inspecter.

Si la cible n'est pas à l'intérieur d'un conteneur sandboxé :

Le thread actuel ne peut pas déclencher '<Target>' puisque '<Target>' a la propriété Sandboxed définie sur false mais le thread appelant est sandboxé

Pour résoudre cela, définissez Sandboxed sur true pour la cible. Alternativement, vous pouvez modifier la source du thread appelant pour que Sandboxed soit défini sur false, mais cela n'est pas recommandé car cela élimine les bénéfices de sécurité que fournit le sandboxing.

Si la cible est sandboxée mais a des capacités que l'appelant n'a pas :

Le thread actuel ne peut pas déclencher '<Target>' puisque '<Target>' a des valeurs supplémentaires pour la propriété Capacités : <First Missing Capability> (et N de plus)

Pour résoudre cela, rétrécissez les Capabilities de la cible à un sous-ensemble de celles de l'appelant, ou étendez les Capabilities de l'appelant pour qu'elles correspondent à celles de la cible.

Requérir des modules

Les ModuleScripts internes peuvent être requis par le conteneur sandboxé comme d'habitude. Cependant, si l'instance cible est en dehors du conteneur, le ModuleScript ne peut être requis que si l'ensemble de capacités qui lui est disponible est plus petit ou égal aux capacités disponibles pour le conteneur.

Cette limitation ne s'applique pas aux capacités RunClientScript et RunServerScript. Si le ModuleScript est placé dans un conteneur ayant seulement RunClientScript mais est requis depuis un script qui a la capacité RunServerScript, il est autorisé à réussir et à exécuter ces fonctions sur le serveur.

Lorsque require() échoue en raison d'un désaccord de capacité, l'erreur nomme le module cible et la propriété à inspecter de la même manière que les fonctions et événements liés décrits dans la section précédente.

Fonctions appelées directement

Si un ModuleScript dans un conteneur sandboxé est requis depuis l'extérieur du conteneur, certaines protections ne sont pas disponibles. En particulier, la fonction cible est capable d'accéder à toutes les instances disponibles pour l'appelant. Si l'appelant ne se trouve pas dans un conteneur sandboxé, l'appel agit comme si AccessOutsideWrite était disponible pour lui.

D'autres restrictions de capacité s'appliquent toujours. Si vous avez une capacité d'accès DataStore, mais que le module cible ne l'a pas, il ne peut pas appeler les méthodes DataStore. Cependant, si vous passez votre propre fonction travaillant avec DataStore, la cible peut l'exécuter pendant cet appel. Si la cible planifie un thread utilisant des méthodes comme celles de task, ces threads perdent la capacité d'appeler cette fonction.

Les instances peuvent être passées au module cible ou assignées aux champs du module.

Si nécessaire, il est recommandé d'assigner des membres de tableau en utilisant rawset pour éviter d'exécuter les méthodes métatables __index/__newindex qui pourraient être définies sur le tableau.

La recommandation générale est de communiquer avec BindableEvent et BindableFunction chaque fois que cela est possible.

Mouvement des instances

La plupart des instances n'ont pas de restrictions sur le mouvement entre les conteneurs. Les instances de script, cependant, ne peuvent être déplacées que dans un conteneur qui a le même ensemble de capacités ou un sous-ensemble de ces capacités.

Cela signifie qu'un conteneur sandboxé avec AccessOutsideWrite ne peut pas simplement changer le parent d'un script à l'intérieur et obtenir plus de capacités.