Roblox Luau Execute

A Node.js project for executing Luau scripts, designed for use with Roblox development workflows. This project provides tools and utilities to run and manage Luau scripts programmatically.

Setup

Local Execution:

1. Install roblox-luau-execute via npm:

   npm install rbxluau

2. Ensure you have Roblox Studio installed and opened at least once on your local machine.

3. Start using the package in your Node.js projects!

   npx rbxluau "print('Hello, Roblox!')"

Cloud Execution (CI/CD Pipelines, etc.):

1. Create and log into a throwaway Roblox account to use for script execution on an incognito browser window. Ensure this account has no value and is not linked to any personal information.

2. Disable account session protection. This is necessary for the API to work outside of your local machine.

3. Obtain the .ROBLOSECURITY cookie value from your browser. This cookie is required for authentication when making API requests. Do not log out of this account. Instead, just close the incognito window after obtaining the cookie, as logging out will invalidate the cookie.

4. In your project directory, create a .env file and add the following line, replacing your_roblosecurity_cookie with your actual cookie value:

   ROBLOSECURITY=your_roblosecurity_cookie

5. Additionally, you can also specify multiple cookies by separating them with commas, allowing for load balancing across accounts:

   ROBLOSECURITY=cookie1,cookie2,cookie3

6. Install roblox-luau-execute via npm:

   npm install rbxluau

7. Start using the package in your Node.js projects!

   npx rbxluau "print('Hello, Roblox!')"

Alternative: Using Exported Credentials

For CI/CD environments, you can export your credentials on your local machine and use them as an environment variable instead of the ROBLOSECURITY cookie:

1. After running cloud execution at least once (which creates the .rbxluau folder), export your credentials:

   npx rbxluau export-credentials

2. Copy the JSON output and set it as the RBXLUAU_CREDENTIALS environment variable:

   RBXLUAU_CREDENTIALS='...'

3. Now you can run scripts without needing ROBLOSECURITY in your environment:

   npx rbxluau "print('Hello, Roblox!')"

This approach is particularly useful for CI/CD pipelines since ROBLOSECURITY cookies are prone to expiration and also pose security risks if mishandled.

Getting Started

Prerequisites

• Node.js (v16 or later recommended)
• Roblox Studio (optional, for local execution)

Installation

1. Clone the repository:

   git clone https://github.com/your-username/roblox-luau-execute.git
   cd roblox-luau-execute

2. Install dependencies:

   npm install

Running a Luau Script

You can run a Luau script using the provided demo:

npx rbxluau --script demo/fibonacci.luau

Capture CLI output to a file using the --out option:

npx rbxluau --script demo/fibonacci.luau --out logs/fibonacci.log

Combine --out with --silent to suppress console logs, and --no-exit when embedding the CLI so it resolves without calling process.exit:

npx rbxluau --script demo/fibonacci.luau --out logs/fibonacci.log --silent --no-exit

Or run the demo TypeScript project:

npm run build

Your Luau script can return an exit code by returning a number at the end of the script. For example, returning 1 will set the process exit code to 1.

License

This project is licensed under the MIT License. See the LICENSE file for details.