Script

In game development, the Roblox engine features a scripting API which allows Lua programs to perform operations on its data model, known as scripts. A script generally refers to an instance of a Lua code container class, while it may also refer to a plugin or a piece of code designed to be run as a script. Scripts change the behavior of the server as well as the client, allowing for complex systems, for example, a round-based game system.

The engine has a set of classes for different types of scripts, each of which has a unique function. The script's source code can be edited in Roblox Studio through its script editor. Instances of Script/LocalScript are executed automatically as soon as a game is running, which can be prevented by setting their Disabled property to true. ModuleScript allows scripts to be split into sections as well as their data to be accessed by multiple other scripts through the require function. Actor, which function as Model, allows parallel execution of scripts contained in them. CoreScript has a higher privilege than other types of scripts with the ability to manipulate the client itself, thus they are not open/editable nor can be created in Roblox Studio in normal circumstances. The engine provides classes for server-client communication: RemoteEvent and RemoteFunction.

The engine converts high-level code into the lower-level bytecode before being able to execute a script. The Task Scheduler handles scripts' execution. Tasks run by scripts are recorded by the MicroProfiler with the label "$Script". The tool can be accessed by pressing Ctrl + F6 and can be paused by pressing Ctrl + P. The Script Performance tool in Roblox Studio can be used to measure each script's performance, similar to using the MicroProfiler.

History[]

On January 15, 2014, ModuleScript was introduced.^[1]
On October 2, 2014, the Script Analysis tool was introduced to Roblox Studio.^[2]
On June 16, 2022, Parallel Luau was released.^[3]
On August 24, 2022, the RunContext property was introduced for the BaseScript class.^[4]
On October 24, 2022, the Script Editor API was released, allowing plugins to control the script editor.^[5]

Roblox Studio[]

Roblox Studio features a built-in script editor. The editor features syntax highlighting, indentation, autocomplete, and bracket matching. The editor also supports Luau's type checking. Roblox Studio also features a debugger tool used to debug scripts which includes breakpoints, variables list and watch expressions.

Behavior[]

Scripts such as Scripts and LocalScripts are executed automatically as soon as a game is running. The Disabled property will prevent a script from running. If set to true at run time, the script will immediately stop, while setting to false will start the script from the beginning. Executed scripts will continue to run even if their Parent property is set to nil unless if they are destroyed or disabled.

Server scripts run in either Workspace or ServerScriptService, while local scripts run in one of these places:

A Player's
- Backpack
- Character
- PlayerGui
- PlayerScripts
The ReplicatedFirst service

Local scripts in ReplicatedFirst are ran earlier than in other places, which is useful for creating custom loading screens.

API[]

Roblox introduces its own globals (e.g. workspace, game, and the script running as script), classes and data types to Lua API which can be accessed by any script.

Security context[]

Scripts and LocalScripts access to Roblox API is designed for game programming; this is controlled by a system known as security context, in which there are types of identities threads run under, known as thread identity. Both Scripts and LocalScripts run with a thread identity of 2 (3 in a place created by Roblox, 4 if authorized), while CoreScripts run with identity of 4. Each identity has different roles with different permissions.

While a CoreScript has access to all of the API and the game's contents, a Script/LocalScript does not for security reasons. If a script tries to access an API member without valid permissions, it will result in an error. Additionally, trying to access a class object with RobloxLocked property set to true (usually under a CoreGui) without Plugin permission (CoreScripts or authorized scripts) will result in an error.

Scripts and LocalScripts are saved onto the place unlike CoreScripts. Both Scripts and LocalScripts are run under a virtual machine different from one that runs CoreScripts.

Modularity[]

Unlike other scripts, ModuleScripts do not execute automatically and instead returns data that can be accessed by other scripts through the require function. This allows scripts to be split into ModuleScripts as sections as well as prevent code from being written more than once than needed (this is known as don't-repeat-yourself principle).

In an environment, a ModuleScript is executed once as a script calls require on it. It cannot be executed again, as the data it returns will only be the data that can be accessed by other scripts in the same environment through the function. Cyclic require calls will result in the thread being hung. There are three main environments: the server, the client and the command bar. The data returned by the module will be different for every environment.

MainModule[]

A script can call require with an ID of a ModuleScript with the name "MainModule" that is uploaded to Roblox as a model asset to access that module. This way, it will retrieve the script, instantiate it with any objects parented to it, execute the script and return the data the script returned.

Client–server model[]

The engine uses the client–server model. In run time, the DataModel is held and controlled by the server, many services of which are replicated to clients automatically including Workspace and ReplicatedStorage. Therefore, there is a difference between server scripts (Scripts with RunContext set to Legacy or Server) which are only ran on the server and local scripts (Scripts with RunContext set to Client or LocalScripts) which are only ran on the client. Because local scripts cannot interact with the server other than in certain cases such as moving the client's character parts, RemoteEvents and RemoteFunctions are used for server-client communication.

Local scripts also have access to client's features such as user inputs (UserInputService and ContextActionService) and render stepping (via RunService), which Scripts do not as the host is server-sided.

Parallel programming model[]

The engine supports parallel code using the actor model. Parallelization allows a workload to be split for each processing unit to execute simultaneously, reducing the time it takes to finish all of the workload.

Scripts contained in an Actor instance are considered parallel (as opposed to serial scripts) and can call the task.desynchronize function to switch to parallel execution state (assigning the current thread to a different worker), and task.synchronize to switch back to serial execution state. A parallel script belongs to the closest Actor parent. Each Actor has its own VM (virtual machine) for its contained scripts (different from the main VM for serial scripts), thus any code in a VM cannot directly access another VM (e.g. using require on the same module will not yield the same data); instead, messages are sent and received between VMs usually through its methods: Actor:BindToMessage/Actor:BindToMessageParallel, and Actor:SendMessage. This is known as the Parallel Luau programming model. There is thread safety for API members which prevent parallel code from accessing in parallel state that would otherwise result in unexpected behavior.

Performance[]

The Task Scheduler handles scripts' execution. Tasks run by scripts are recorded by the built-in profiling tool, MicroProfiler, with the label "$Script". The tool's interface can be accessed by pressing Ctrl + F6. The profiling can be paused by pressing Ctrl + P. This can be used for measuring a script's performance. The Script Performance tool in Roblox Studio can be also used to measure each script's performance, similar to using the MicroProfiler.

Script Performance[]

The Script Performance tool in Roblox Studio lists each script's performance with the script's name, count of how many instances of the script (running the same code), their processing time ("Activity") compared to the whole frame, and their rate of execution from the Task Scheduler. Unlike using the MicroProfiler, a script listed in the tool represents a code that is run by at least one script in the DataModel, which if clicked, selects all instances running the code.

Custom profiling[]

The engine allows custom profiling in the MicroProfiler through two functions of the debug library: debug.profilebegin which starts a label followed by debug.profileend which ends the label (yielding will also end the label as well as other labels). A string must be passed to debug.profilebegin in order to name the label.

Community[]

A DevForum sub-category related to scripting is known as Scripting Support found under Help and Feedback category. A user must become a Member to reply and create topics here.

There is a type of place which mainly focuses around creating and developing scripts, known as a script builder. Script builders allow users to create, modify and run their own scripts, usually only in a sandboxed environment.