roblox-studio-hub

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Roblox Studio Hub

A tool for managing multiple Roblox Studio instances and executing Lua code remotely via CLI and HTTP API.

一款用于管理多个Roblox Studio实例，并通过CLI和HTTP API远程执行Lua代码的工具。

Overview

概述

Roblox Studio Hub provides:

Multi-Studio Management - Connect and manage multiple Roblox Studio instances simultaneously
Remote Code Execution - Execute Lua code in Studio with three modes (eval, run, play)
CLI Interface - Full-featured command line interface for all operations
System Service - Run as background service with auto-start on boot

Roblox Studio Hub 提供以下功能：

多Studio管理 - 同时连接并管理多个Roblox Studio实例
远程代码执行 - 以三种模式（eval、run、play）在Studio中执行Lua代码
CLI界面 - 支持所有操作的全功能命令行界面
系统服务 - 作为后台服务运行，支持开机自启

Architecture

架构

┌─────────────────┐     HTTP Long Polling     ┌─────────────────┐
│  Roblox Studio  │ ◄──────────────────────► │   Studio Hub    │
│    (Plugin)     │                           │    (Server)     │
└─────────────────┘                           └────────┬────────┘
                                                       │
                                              ┌────────▼────────┐
                                              │    CLI / API    │
                                              │  localhost:35888│
                                              └─────────────────┘

┌─────────────────┐     HTTP Long Polling     ┌─────────────────┐
│  Roblox Studio  │ ◄──────────────────────► │   Studio Hub    │
│    (Plugin)     │                           │    (Server)     │
└─────────────────┘                           └────────┬────────┘
                                                       │
                                              ┌────────▼────────┐
                                              │    CLI / API    │
                                              │  localhost:35888│
                                              └─────────────────┘

Quick Start

快速开始

1. Install Hub Server

1. 安装Hub服务器

必须保证当前运行在

管理员

权限中, 否则提醒用户并中断本次会话.

bash

undefined

必须保证当前运行在

管理员

权限中, 否则提醒用户并中断本次会话.

bash

undefined

Configure GitHub npm registry

配置GitHub npm注册表

npm config set @white-dragon-tools:registry https://npm.pkg.github.com

Install globally

全局安装

npm install -g @white-dragon-tools/roblox-studio-hub

undefined

npm install -g @white-dragon-tools/roblox-studio-hub

undefined

2. Register as System Service (Recommended)

2. 注册为系统服务（推荐）

bash

undefined

bash

undefined

Register as system service (auto-start on boot)

注册为系统服务（开机自启）

Windows: Run as Administrator

Windows：以管理员身份运行

Mac/Linux: Use sudo

Mac/Linux：使用sudo

roblox-studio-hub install

Check service status

检查服务状态

roblox-studio-hub status

undefined

roblox-studio-hub status

undefined

3. Install Studio Plugin

3. 安装Studio插件

bash

roblox-studio-hub install-plugin

bash

roblox-studio-hub install-plugin

4. Verify Setup

4. 验证安装

bash

roblox-studio-hub status

bash

roblox-studio-hub status

CLI Commands Reference

CLI命令参考

All commands support

-h

--help

for detailed help.

所有命令都支持

-h

或

--help

参数查看详细帮助信息。

Service Management

服务管理

Command	Description
`roblox-studio-hub serve`	Run server in foreground (for debugging)
`roblox-studio-hub install`	Register as system service (auto-start)
`roblox-studio-hub uninstall`	Uninstall system service
`roblox-studio-hub start`	Start system service
`roblox-studio-hub stop`	Stop system service
`roblox-studio-hub status`	Check Hub service status
`roblox-studio-hub update`	Update to latest version (auto-handles service restart)

命令	说明
`roblox-studio-hub serve`	在前台运行服务器（用于调试）
`roblox-studio-hub install`	注册为系统服务（开机自启）
`roblox-studio-hub uninstall`	卸载系统服务
`roblox-studio-hub start`	启动系统服务
`roblox-studio-hub stop`	停止系统服务
`roblox-studio-hub status`	检查Hub服务状态
`roblox-studio-hub update`	更新到最新版本（自动处理服务重启）

Studio Management

Studio管理

Command	Description
`roblox-studio-hub list`	List all connected Studios
`roblox-studio-hub info <studioId>`	Show Studio details
`roblox-studio-hub logs <studioId> [-n limit]`	View Studio logs

命令	说明
`roblox-studio-hub list`	列出所有已连接的Studio
`roblox-studio-hub info <studioId>`	查看Studio详细信息
`roblox-studio-hub logs <studioId> [-n limit]`	查看Studio日志

Code Execution

代码执行

bash

undefined

bash

undefined

Basic usage

基础用法

roblox-studio-hub exec <studioId> <file> [-m mode]

Examples

示例

roblox-studio-hub exec place:123456 script.lua # Execute with eval mode roblox-studio-hub exec local:MyGame test.lua -m run # Server-side test roblox-studio-hub exec path:D:/Projects/MyGame test.lua --mode play # Full play mode

undefined

roblox-studio-hub exec place:123456 script.lua # 以eval模式执行 roblox-studio-hub exec local:MyGame test.lua -m run # 服务器端测试 roblox-studio-hub exec path:D:/Projects/MyGame test.lua --mode play # 完整游玩模式

undefined

Plugin Management

插件管理

bash

roblox-studio-hub install-plugin    # Install Studio plugin

bash

roblox-studio-hub install-plugin    # 安装Studio插件

Update Hub

更新Hub

bash

roblox-studio-hub update

The update command automatically:

Stops running service
Executes npm update
Restarts service

bash

roblox-studio-hub update

更新命令会自动执行以下操作：

停止运行中的服务
执行npm更新
重启服务

Execution Modes

执行模式

Mode	Description	Use Case
`eval`	Direct execution via `loadstring` (default)	Quick scripts, simple tests
`run`	Server-side test via `StudioTestService`	Server logic testing
`play`	Full Play mode (server + client)	Complete game testing

模式	说明	适用场景
`eval`	通过 `loadstring` 直接执行（默认模式）	快速脚本、简单测试
`run`	通过 `StudioTestService` 进行服务器端测试	服务器逻辑测试
`play`	完整游玩模式（服务器+客户端）	完整游戏测试

Studio ID Format

Studio ID格式

Cloud place:
```
place:{placeId}
```
(e.g.,
```
place:123456
```
)
Local file:
```
local:{placeName}
```
(e.g.,
```
local:MyGame
```
)
Custom path:
```
path:{localPath}
```
(e.g.,
```
path:D:/Projects/MyGame
```
)

云端场景：
```
place:{placeId}
```
（例如：
```
place:123456
```
）
本地文件：
```
local:{placeName}
```
（例如：
```
local:MyGame
```
）
自定义路径：
```
path:{localPath}
```
（例如：
```
path:D:/Projects/MyGame
```
）

Common Workflows

常见工作流

Check Connected Studios

检查已连接的Studio

bash

undefined

bash

undefined

List all connected Studios

列出所有已连接的Studio

roblox-studio-hub list

Get details of a specific Studio

获取特定Studio的详细信息

roblox-studio-hub info place:123456

undefined

roblox-studio-hub info place:123456

undefined

Execute Lua Script

执行Lua脚本

bash

undefined

bash

undefined

Create a test script

创建测试脚本

echo "print('Hello from Hub!'); return 42" > test.lua

Execute on a connected Studio

在已连接的Studio上执行

roblox-studio-hub exec place:123456 test.lua

undefined

roblox-studio-hub exec place:123456 test.lua

undefined

View Studio Logs

查看Studio日志

bash

undefined

bash

undefined

View last 100 logs (default)

查看最后100条日志（默认）

roblox-studio-hub logs place:123456

View last 50 logs

查看最后50条日志

roblox-studio-hub logs local:MyGame -n 50

undefined

roblox-studio-hub logs local:MyGame -n 50

undefined

Update Hub to Latest Version

将Hub更新到最新版本

bash

undefined

bash

undefined

Update with automatic service handling

自动处理服务的更新

roblox-studio-hub update

Update plugin if needed

如有需要，更新插件

roblox-studio-hub install-plugin

undefined

roblox-studio-hub install-plugin

undefined

API Reference (for programmatic access)

API参考（用于程序化访问）

Check Hub Status

检查Hub状态

GET /api/status

GET /api/status

List Connected Studios

列出已连接的Studio

GET /api/studios

GET /api/studios

Get Studio Details

获取Studio详细信息

GET /api/studios/:id

GET /api/studios/:id

Get Studio Logs

获取Studio日志

GET /api/studios/:id/logs?limit=100

GET /api/studios/:id/logs?limit=100

Execute Code

执行代码

POST /api/execute
Content-Type: application/json

{
  "studioId": "place:123456",
  "code": "print('Hello'); return 42",
  "mode": "eval",
  "timeout": 30
}

POST /api/execute
Content-Type: application/json

{
  "studioId": "place:123456",
  "code": "print('Hello'); return 42",
  "mode": "eval",
  "timeout": 30
}

Configuration

配置

Environment Variables

环境变量

Variable	Default	Description
`STUDIO_HUB_PORT`	`35888`	Server port

变量	默认值	说明
`STUDIO_HUB_PORT`	`35888`	服务器端口

Troubleshooting

故障排除

Issue	Solution
Studio not connecting	Enable HTTP requests in Studio Settings → Security
Connection timeout	Check firewall, verify port 35888 is open
Code execution fails	Check Lua syntax, review error in response
Studio disconnects	Hub removes inactive Studios after 35s without heartbeat
Service not starting	Run `roblox-studio-hub install` with admin/sudo privileges
Update fails	Run with admin/sudo privileges

问题	解决方案
Studio无法连接	在Studio设置→安全中启用HTTP请求
连接超时	检查防火墙，确认端口35888已开放
代码执行失败	检查Lua语法，查看响应中的错误信息
Studio断开连接	如果35秒内没有心跳，Hub会移除不活跃的Studio
服务无法启动	使用管理员/ sudo权限运行 `roblox-studio-hub install`
更新失败	使用管理员/ sudo权限运行

Additional Resources

额外资源

Reference Files

参考文件

For detailed API documentation and patterns:

references/api-reference.md
- Complete API specification
references/lua-patterns.md
- Common Lua code patterns for testing

如需详细的API文档和代码模式：

references/api-reference.md
- 完整的API规范
references/lua-patterns.md
- 用于测试的常见Lua代码模式