An AI assistant for Roblox Studio, with support for multiple providers and a local companion.
Inspect your place, edit Luau scripts, build scenes, and use external tools from one Studio panel. Choose your AI provider and connect the local bridge when your task needs web or file access.
Quick Start · Providers · Auto Retry · How It Works · Limitations · Documentation
Repository: AlFarrizi-Studio/ForgePilot
- Chat inside Studio. Text and supported reasoning appear as provider data arrives, without a typing queue after the response finishes.
- Build and Plan modes. New chats default to Build. Switch to Plan for inspection and planning without applying changes.
- Place inspection. Read the Workspace hierarchy, instance properties, script source, selection, Lighting settings, and UI structure.
- Roblox tools. Create and edit parts, models, terrain, Luau scripts, and GUI elements through validated tool calls.
- External tools through the bridge. Search the web, fetch URLs, read and search local files, download files, edit files, and run terminal commands within the configured permissions.
- Provider choice. The bundled 9router catalog contains 82 presets across OAuth, free/free-tier, and API key categories. Direct API and custom endpoint profiles are also available.
- Readable activity panels. Questions, provider limits, Thinking, tool calls, tool results, and web activity can be expanded or closed. Long results use a bounded scroll area.
- Approval choices. Approve an action once, decline it, or choose Always Approve. The saved preference can be disabled in Settings → Agent.
- No task count caps. Tool calls and build actions continue until the task finishes, is stopped, or encounters a blocking error.
- Provider logos and interface icons. The package includes upstream provider images and native fallback icons for Thinking, Custom Provider, web, terminal, and tools.
- Keyboard controls. Enter sends a chat message; Shift+Enter inserts a new line. The send button becomes Stop while the agent is working.
- Auto Retry. Recover from temporary provider errors and interrupted streams, with a visible countdown, bounded retries, and an OpenCode preset. Open Retry: On/Off in chat to configure it.
- Roblox Studio on Windows or macOS. Linux launchers are included for an existing, working Wine/Vinegar installation; there is no official native Linux Studio build.
- Node.js 22 or newer, including npm and npx, for the installer and local services.
- An internet connection for the initial 9router download and online AI providers.
- An account or API key for your selected provider, when required.
Extract the entire release ZIP before starting. The RBXM alone does not include the bridge or launchers. ForgePilot's Node runtime uses built-in modules, so npm install in the project root is not required.
Close Roblox Studio and run the installer for your operating system:
| Operating system | Installer |
|---|---|
| Windows | Install-ForgePilot.cmd |
| macOS | Install-ForgePilot.command |
| Linux | sh scripts/linux/Install-ForgePilot.sh |
Alternatively, run this command from the extracted ForgePilot directory:
npm run install:pluginThe installer detects the Studio plugins folder, verifies the plugin checksum, backs up the previous version, and copies the plugin. It does not start either local service or change your system PATH.
If automatic detection does not find your installation, specify the folder shown by Studio's Plugins Folder command:
npm run install:plugin -- --plugin-dir "/path/to/Plugins"9router and the ForgePilot bridge run separately. Open each launcher in its own terminal:
| Operating system | 9router launcher | Bridge launcher |
|---|---|---|
| Windows | Start-9Router.cmd |
Start-ForgePilot-Bridge.cmd |
| macOS | Start-9Router.command |
Start-ForgePilot-Bridge.command |
| Linux | sh scripts/linux/Start-9Router.sh |
sh scripts/linux/Start-ForgePilot-Bridge.sh |
The same npm commands work across all three platforms. In the first terminal:
npm run start:routerIn a second terminal:
npm run start:bridge| Service | Default address | Purpose |
|---|---|---|
| 9router dashboard | http://127.0.0.1:20128/dashboard | Provider connections, OAuth sign-in, and models |
| ForgePilot bridge | http://127.0.0.1:20129 |
Local tools and streaming relay |
Keep the required terminals open during your session. npm start starts only the bridge. Stopping one service does not stop the other. Direct API profiles can work without 9router; external tools still require the bridge.
- Open Roblox Studio, then Plugins → ForgePilot. Allow HTTP requests if Studio prompts you.
- Open Settings → Agent Access. Enter the bridge URL and the pairing token printed in the bridge terminal, then select Connect bridge.
- Open AI & Provider and add a provider profile.
- For a router profile, connect the provider account or API key in the 9router dashboard. For a direct profile, enter the API endpoint and authentication details.
- Refresh the connection status and available models where supported. Select a model, save the profile, and run Test connection.
- Open Chat and send a message. Use Build to make changes, or select Plan for inspection and planning.
The bridge generates a new token at startup. Pair again after restarting the bridge or Studio. See the installation guide for custom ports and upgrades.
The bridge defaults to file access permitted by your operating system account. To restrict file operations to one workspace and disable terminal execution, start it with:
npm run start:bridge -- --workspace-only --workspace "/path/to/project"The bundled catalog is a snapshot of 9router: 21 OAuth, 16 free/free-tier, and 45 API key presets. A listed preset does not guarantee current availability, account eligibility, or model access.
| Connection type | Setup | Credentials |
|---|---|---|
| OAuth through 9router | Select Sign in / Connect in 9Router, complete the provider login or device-code flow, then refresh status and models. | Provider account; router client API key if required |
| Free/free-tier through 9router | Connect the selected service in the dashboard and choose an available model. | Account or API key if required by the service |
| API key through 9router | Add the provider API key to its connection in the dashboard. | Provider key in 9router; separate router client API key if required |
| Direct API / Custom Provider | Configure the base URL, protocol or adapter, endpoint path, model ID, and authentication in ForgePilot. | Credentials required by that API |
The dashboard password, provider OAuth login, router client API key, and bridge pairing token serve different purposes. Use the credential required by each screen. Provider keys for router connections belong in the router dashboard.
A connected account does not prove that a model supports chat, tool calling, reasoning, or image input. Test the connection and check the capabilities you need. Custom REST profiles require request and response mappings; model IDs must match the endpoint.
Plugin API keys and bridge tokens are kept for the current plugin session. Non-secret preferences and profiles may persist. OAuth credentials are managed by 9router. Keep credentials out of chat messages and repository commits.
See the provider guide for authentication flows, model selection, and capability checks.
| Control | Behavior |
|---|---|
| Enter | Send the current chat draft once, including existing line breaks. |
| Shift+Enter | Insert a new line at the caret or replace the selected text. The draft stays in the composer. |
| Question | Open the arrow, choose an option or enter an answer, then select Submit answer. Custom answers carry the actual text to the waiting task. |
| Answered question | Collapse automatically. Reopen to read the prompt and answer; Close folds the result again. |
| Provider limit | Start compact with a live countdown/status preview. Open the arrow for facts and retry controls; Close folds the panel while recovery continues. |
| Approve / Decline / Always Approve | Approve once, reject once, or save automatic approval for enabled tools within the conversation's mode. |
| Stop | Cancel an active task, including long sequences of tool calls or build actions. |
Always Approve is off by default. Clicking it also approves the pending action. It persists across Studio sessions and can be turned off in Settings → Agent → Always Approve to restore confirmation prompts.
ForgePilot has no numeric per-task cap on tool calls, build actions, or the number of tool rounds. Provider quotas, context/output limits, per-request timeouts, and the runtime limits listed in Troubleshooting still apply.
Auto Retry applies to both streaming and complete-response requests. Click Retry: On/Off beside New chat, or open Settings → Retry. The shortcut opens settings; the Enable Auto Retry switch controls whether requests are retried.
The OpenCode preset uses a 2-second base delay, doubles the delay after each failure, adds up to 25% jitter, and caps local fallback waits at 30 seconds. New installations default to 5 additional retries: at most 6 requests for one provider turn. Existing preferences are preserved; select OpenCode to use this preset after upgrading.
| Failure | Behavior |
|---|---|
| HTTP 408/429, temporary 5xx errors, provider overload | Retry when classified as temporary |
| Network disconnect, idle timeout, stream ending before completion | Retry the current provider turn |
| Invalid credentials, permission, model, endpoint, or request | Report the failure without repeating it |
| Roblox code error such as an invalid method | Requires a code fix; repeating an HTTP request cannot repair plugin code |
| Provider wait exceeds Maximum Automatic Wait | Stop automatic recovery and show the required wait; default limit: 120 seconds |
| User presses Stop or Cancel Retry | Cancel the countdown and prevent further attempts |
Provider retry/reset headers and known cooldowns take priority over local backoff. The 30-second OpenCode cap does not shorten a required provider cooldown. Adaptive, Exponential, Linear, and Custom strategies remain available, together with per-provider overrides.
The retry card shows the actual error category, attempt count, and countdown. A retry replaces partial text and reasoning from that provider turn. Incomplete tool calls are discarded before execution; completed build actions and earlier conversation turns are preserved. If all retries fail, useful partial output remains visible beside the error.
Retries may consume provider quota or incur charges. They do not replenish credits, bypass account limits, guarantee a successful response, or replay already completed tools. See the 3.5.0 patch and upgrade guide for overwrite installation and publishing instructions.
Connection, streaming, tool, and capability tests keep their status separate from chat. Diagnostic requests use one attempt, a maximum 15-second request timeout, and a 60-second operation deadline. Stop test cancels an active check. Errors, cancellation, and timeouts release the editor controls without changing your chat retry preferences.
While a chat task is running, the provider footer explains that configuration is temporarily locked. Editing becomes available when the task and its cleanup finish. Dropdowns close when their panel is hidden, disabled, detached, or destroyed, including when the plugin widget is closed.
| Component | Responsibility |
|---|---|
| Studio plugin | Chat UI, place context, conversation mode, Roblox tools, and validation of requested actions |
| Provider adapter | Formats model requests and interprets text, reasoning, tool calls, and supported attachments |
| 9router | Connects supported provider accounts and exposes their models through the local router API |
| Local bridge | Relays streaming requests and executes available web, file, download, and terminal tools |
For each turn, ForgePilot assembles the conversation, place context, selected mode, and tools that are actually available. It sends the request through the selected adapter and displays incoming text immediately. When the model requests a tool, the plugin validates its name, arguments, mode, and permissions, applies the approval preference, and returns the real result to the model. This loop continues until completion, cancellation, a provider output limit, or an error.
Roblox actions run inside Studio. External actions run on your computer through the bridge. When the bridge is unavailable, the interface and AI receive setup guidance with a link to the ForgePilot repository.
Streaming timeouts measure inactivity, rather than total response duration. Incoming provider data, including heartbeats, keeps an active stream alive beyond two minutes. If the upstream connection goes silent, closes before completion, or reports an error, partial text remains visible and the chat becomes usable again. Certain output-limit responses can trigger up to three automatic continuation turns before a visible notice asks you to continue manually.
See How It Works and Architecture for the detailed flow.
| Area | What to expect |
|---|---|
| Plugin without the bridge | API chat and Roblox tools remain available. Web search, URL fetch, local files, downloads, and terminal tools require the bridge. |
| Tool calling | Native tool calling is used when supported. Otherwise, a validated JSON action format is available; success depends on the model following that format. |
| Image input | Requires both a compatible model and adapter. Reading image bytes through the bridge does not give a text-only model vision. |
| Audio, video, and documents | Support depends on the model, adapter, and capability checks. ForgePilot does not include a universal media generator. |
| Web search | Uses DuckDuckGo HTML or a configured SearXNG JSON endpoint. Challenges, rate limits, and pages requiring login or JavaScript may prevent useful results. |
| Downloaded assets | Downloads create local files. They do not automatically publish assets or create Roblox asset IDs. |
| Local access | Follows OS permissions, bridge scope, conversation mode, and tool permissions. Both services bind to localhost by default. Full access does not grant administrator privileges. |
| Provider availability | Models, pricing, quotas, OAuth access, and rate limits are controlled by each provider. A free-tier label does not imply unlimited or permanent free access. |
| Linux | Node launchers are provided. Studio requires a separately configured Wine/Vinegar installation. |
| Release verification | Automated Luau simulations, Node tests, and build checks are included. Native Studio execution, Windows/macOS launcher execution, and live provider/OAuth sessions were not verified in the release environment. |
For size limits, timeout settings, connection errors, and recovery steps, see Troubleshooting.
| Path | Contents |
|---|---|
plugin/ |
Built RBXM/RBXMX plugins and Luau source in plugin/src/ |
scripts/ |
OS-specific installers and separate router/bridge launchers |
runtime/ |
Node entry points, plugin folder detection, and process management |
bridge/ |
Local server, provider catalog, and bridge tests |
assets/ |
Provider logos and upstream license information |
tests/ |
Luau simulation harness, fixtures, and verification reports |
docs/ |
Setup, architecture, troubleshooting, and publishing guides |
tools/ |
Release packaging utilities |
SHA256SUMS.txt |
Package checksums, including the plugin checksum checked by the installer |
Run the Node test suite from the project root:
npm testFollow CONTRIBUTING.md for Luau verification and rebuilding the plugin. Read the publishing guide before preparing a GitHub Release; the release packager regenerates checksums and validates the archive.
| Guide | Purpose |
|---|---|
| Installation | Setup, plugin paths, service arguments, and upgrades |
| Providers | OAuth, API keys, custom endpoints, models, and capabilities |
| How It Works | Chat lifecycle and tool execution |
| Architecture | Internal components and integration contracts |
| Troubleshooting | Limits, errors, and recovery |
| Test Report | Automated checks and verification scope |
| Release Notes | Changes in the packaged release |
| 3.5.0 Patch and Upgrade | Provider menu fixes, icon, Sky fix, Auto Retry, and overwrite instructions |
| Changelog | Version history |
This README and the 3.5.0 patch guide are in English. Other detailed guides are currently in Indonesian.
The retry preset follows the OpenCode retry implementation, with a bounded fallback wait and ForgePilot cancellation controls.
The provider catalog and 75 original provider PNGs come from the referenced 9router snapshot. Its upstream MIT license is retained in assets/9router-LICENSE.txt. Provider names and logos belong to their respective owners.
See THIRD-PARTY-NOTICES.md for sources and attribution. This package does not assign a new license to ForgePilot's own source code.