RobloxUI CLI

数分钟内搭建一个 Roblox 项目并连接到 Roblox Studio。robloxui init 可创建一个 Roblox-TS 或 Luau/Wally 项目，预配置了 Rojo、mise 固定的工具链、一个最小化玩家生成点，以及用于 AI 工具的 Roblox Studio MCP 服务器。后续可通过 robloxui add 添加市场组件（robloxui.pencicta.com）。

快速开始

npx robloxui init

根据提示（项目名称、类型、主题）进行操作，然后：

cd my-game
npm run dev          # compiles and syncs into Studio

在 Roblox Studio 中： 打开项目文件夹中的 game.rbxl → Rojo 插件 → 连接 → 按下 播放。

就这样——一个带有生成点和空客户端挂载的可游玩场所，已准备好用于 UI。

robloxui init

搭建一个空的 Roblox-TS 或 Luau/Wally 项目，包含一个最小化玩家生成点，并预配置了 RobloxUI 组件、工具链和 Studio 连接。

robloxui init --name my-game --flavor roblox-ts --yes
robloxui init --name . --flavor luau-wally --yes   # scaffold in cwd
robloxui init --name my-game --flavor roblox-ts --yes --theme  # include the theme

创建内容：Rojo 配置、mise.toml 工具链固定、标准 DataModel 服务（Lighting、ServerStorage、SoundService、StarterGui、StarterPack、StarterCharacterScripts）、一个最小化玩家生成点、空客户端挂载、src/shared + src/server 文件夹，以及一个 game.rbxl 场所文件。RobloxUI 主题为可选加入：使用 --theme（或回答提示）也会连接规范的 robloxui/theme 令牌。初始化会在需要时使用官方安装程序引导 mise。

现有项目会被检查，但不会替换自定义 Rojo 映射。非交互模式会拒绝模糊的类型或目标输入。

连接到 Roblox Studio

一次性设置

1. 运行 npx robloxui init —— mise 和固定工具会自动引导

2. 安装 Rojo Studio 插件（Roblox Studio → 插件 → 搜索“Rojo”）

Roblox-TS 工作流

在项目中运行一个命令：

npm run dev          # compiles and syncs into Studio

在 Studio 中： 打开 game.rbxl → Rojo 插件 → 连接 → 按下 播放。

Luau / Wally 工作流

npm run dev                                # installs/syncs the Wally project into Studio

对于你自己的（非 RobloxUI）Wally 包，将其添加到 wally.toml 并运行 wally install —— RobloxUI 主题本身已随附，无需依赖。

Studio MCP（AI 工具）

Init 可以将 Roblox Studio MCP 服务器连接到你的 AI 工具（opencode.json、.mcp.json、.cursor/mcp.json 或 .vscode/mcp.json）。在 Studio 中启用一次：助理 → ⋯ → 管理 MCP 服务器 → 启用 Studio 作为 MCP 服务器 —— 然后你的代理就可以读取游戏树、编辑脚本、插入模型并运行测试。

先决条件

• Node.js ≥ 20.12（CLI 测试/构建工具链所需）

• mise 会在 PATH 中不存在时使用官方安装程序引导

• Rojo CLI + Rojo Studio 插件

• Wally —— 仅 Luau 项目

当引导被禁用时，在项目中运行 mise install 来安装固定的工具。

其他内容

以下部分涵盖市场工作流——安装组件、身份验证、浏览目录和故障排除。在需要超过脚手架功能之前，可以跳过这些部分。

身份验证

运行一次 robloxui login。两种流程：

robloxui login                     # browser device flow (recommended)
robloxui login --token <key>       # manual API key (CI / headless)

浏览器流程会打印一个短代码——打开 URL，批准，完成。你的令牌会保存到 ~/.config/robloxui/config.json（Linux/macOS）或 %APPDATA%\robloxui\config.json（Windows）。

CI / 无头机器：在 Dashboard → Developer 生成一个密钥，然后粘贴。

robloxui whoami      # check who you're logged in as
robloxui logout      # remove saved token

限制 —— 免费用户每天 2 次下载。Pro 订阅用户可无限使用。详见 https://robloxui.pencipta.com/pricing。

robloxui add <slug...>

安装一个或多个组件。

robloxui add primary-button
robloxui add button card dialog --yes   # non-interactive (CI)
robloxui add button --theme             # also install the theme package

CLI 将：

1. 预检查 slug、身份验证、目标、类型、包管理器和工具，在网络或写入之前

2. 检测 你的项目类型（rojo.json → Roblox-TS，wally.toml → Luau）

3. 提示 安装路径（默认：src/client/ui/components/）以及是否安装主题

4. 获取 来自 API 的组件源码 + 元数据

5. 暂存并验证 所有文件；冲突默认停止（--force 是显式的）

6. 写入 源码，并在请求时以事务方式安装主题

robloxui list / robloxui search

robloxui list                        # browse all components
robloxui search dialog               # search by name/description
robloxui list --framework tsx        # filter by framework
robloxui list --category buttons --limit 20

robloxui info <slug>

robloxui info primary-button

输出：框架、类别、依赖、主题令牌、使用示例和确切的 robloxui add 命令。

项目检测

主题永远不会自动安装：非交互式运行会跳过，交互式运行会询问。组件可以独立运行，因为它们嵌入了自己的设计令牌。

故障排除

每个 CLI 失败都会打印恢复提示（重试 + 手动命令 + 保留的路径）。常见修复：

链接

• RobloxUI 市场

• 定价

• 文档

• npm 包