Version 1.1.0 · Spear / friendlyspear

CUI Forge is a local editor for Rust CUI JSON. Use it to inspect a layout, adjust elements, preview output from your UI builder and export the result. The editor runs in your browser with a small local Node.js server.

Start with the quick start below. The later sections cover existing plugins, artwork, live updates and troubleshooting.

1. Install and start

Requirements

• Node.js 22.12 or newer installed on your computer.
• A desktop browser. The release has been checked in Google Chrome on macOS; other browser and operating-system combinations have not been verified in this release.
• The complete extracted CUI-Forge-1.1.0.zip download.

The prebuilt download needs no npm installation or build step. You do not need Unity, another Codefling product, an activation key or a running Rust server to use the editor.

Open the editor

1. Extract the entire ZIP into a folder you can keep.
2. Start the launcher for your operating system:

3. Open http://127.0.0.1:4173 in your browser.
4. Keep the terminal window open while using the app. Press Ctrl+C in that window to stop it.

You can also start it directly. Open a terminal in the extracted folder and run:

node server/server.mjs

If macOS blocks the launcher, use this terminal command. You do not need to disable system security settings. Opening index.html directly is unsupported; use the local address above.

The illustrated manual is available at http://127.0.0.1:4173/guide/index.html while the app is running. Guide in the top bar opens the in-app help.

2. Your first layout

1. Open Templates in the left rail.
2. Choose Event notice and use New project. This keeps your current project separate.
3. Open Layers and select the notice text.
4. Change its text in Properties. Drag it on the canvas or use the transform fields for an exact position.
5. Click an empty canvas area to show canvas settings in the inspector. Open Gameplay captures and choose a reference frame.
6. Use Match canvas to match the reference dimensions and review the notice against the native HUD.
7. Open Export → CUI JSON to download the layout.
8. Also use Export → Project file to keep an editable backup.

The examples contain sample names, counts, schedules and statuses. They are layout examples; they do not read data from a game server.

3. Find your way around

New project in Templates creates a separate project. Apply replaces the current canvas; Undo is available. Export a project backup before replacing work you want to keep.

4. Work with an existing plugin

Import the JSON your builder produces

Export a complete CUI snapshot from your plugin or development code. For an Oxide CuiElementContainer, the serialized document is normally obtained with:

string json = CuiHelper.ToJson(elements);

Import the resulting JSON using the top-bar import button, drop the JSON file onto the editor, or paste the document into the JSON tab.

Import serialized CUI JSON rather than a complete .cs plugin source file. A project backup uses a different format and should be imported through Projects → Import.

Include the elements needed to resolve the hierarchy. If your widget attaches to a panel created elsewhere in your plugin, include that parent in the snapshot or create a local parent fixture for previewing. Missing parents can otherwise produce misleading placement.

Edit placement

• Select an element through Layers or the canvas.
• Drag to move it and use the resize handles to change its rectangle.
• Use Transform for exact anchors and offsets.
• Use an anchor preset to change attachment while preserving the current visible rectangle.
• Shift-click to add or remove elements from the selection.

Rust uses Unity's bottom-left coordinate origin. The inspector's Position field uses top-left coordinates for easier editing; the raw offsets retain Unity's signs.

Anchors are relative to the parent rectangle. Offsets adjust the edges around those anchors. For example, a fixed-size notification attached to the top-right should use top-right anchors and offsets that place it inside the screen. Stretch anchors are useful for panels that should grow with their parent.

Changing the browser window size does not change the document's resolution. Use the canvas presets or Width/Height fields to test another target resolution. Presets include 720p, 1080p, 1440p, 4K and ultrawide.

Check interactions

Switch to Play using the status bar. CUI button commands are logged locally, and close targets are simulated. Return to Design to continue editing.

Play mode does not execute Rust commands, query server data or enforce permissions. Your plugin must validate permissions, cooldowns, costs and gameplay conditions on the server.

5. Use the included examples

Importable CUI examples are also included in the download's examples folder. sample-data.json describes example builder inputs; it is not a CUI document to import into the canvas.

Replace sample commands and values with your own plugin logic before using an example in production.

6. Add artwork and gameplay references

Map CUI images

Open Assets to import your own images. Supported asset types include PNG, JPG, WebP, GIF, SVG and AVIF. Import Folder retains paths for matching. Connect a folder on disk uses the local server and is available in the downloaded edition.

The editor does not include an extracted Rust texture pack. Map the artwork your layout uses:

FileStorage IDs belong to a particular Rust server. A Steam ID alone does not provide the avatar image. Import the appropriate image when previewing either reference.

Importing artwork into CUI Forge makes it available to the browser preview. Your plugin still needs to make that artwork available to the Rust client. Raw CUI JSON exports retain image references; they do not upload or embed the editor's asset library.

Check placement against gameplay

With no element selected, open Gameplay captures in the background inspector. Eight included references cover gameplay, interiors, inventory and loot situations. You can also import your own captures and record source notes, FOV and UI scale when known.

• Use full frame preserves the capture's proportions without cropping, extra dimming or blur.
• Match canvas sets the document to the source image dimensions.
• If the aspect ratios differ, the full-frame reference is letterboxed and an aspect warning appears.

Use a capture from the target resolution and settings when checking overlap with the hotbar, vitals or open loot panels. The included footage has no recorded numeric FOV or UI scale. It provides visual context, rather than a calibration for every player's settings.

Gameplay backgrounds are editor references. They are excluded from CUI JSON exports. A PNG preview can include the background if you enable that option.

7. Preview live builder output

The downloaded local edition can receive complete CUI snapshots through HTTP or watch a JSON file. The static browser demo has no local bridge or disk-folder connection.

Publish over HTTP

Keep CUI Forge running, then publish a JSON file from a terminal in that file's folder:

curl --data-binary @ui.json http://127.0.0.1:4173/api/cui/publish

On Windows PowerShell, use curl.exe for this command.

Open Live in the editor and click Apply on the waiting update. Auto-apply is off by default; enable it if you want incoming snapshots to replace the current document automatically. Applied updates can be undone.

Publishing keeps the snapshot in memory and sends it to connected editor tabs on that local server. It does not write to your watched file.

Watch a file

1. Open Live.
2. Enter the absolute path to your builder's .json output.
3. Click Watch.
4. Run your builder so it writes a complete document to that file.
5. Apply the received update, or enable auto-apply.

Use Pause to stop watching. The watcher reads the file and never changes it. For frequent updates, writing to a temporary file and renaming it into place avoids reading a partially written document. Watched files and HTTP publishes are limited to 12 MiB.

Optional C# helper

integrations/CuiForgeBridge.cs is a helper for an existing development or test project. It is not a standalone Oxide plugin to install on your server.

Specify the downloaded edition's endpoint explicitly:

bool accepted = CuiForgeBridge.Publish(
    CuiHelper.ToJson(elements),
    "http://127.0.0.1:4173/api/cui/publish");

The helper's default HTTP endpoint uses port 5173 for the source development server. The prebuilt release uses 4173. Its HTTP calls are synchronous; keep them in development tooling, outside a production server's gameplay loop. The helper has not been compiled and validated against a Rust/Oxide server for this release.

Publish full snapshots. Incremental update and destroyUi streams are not a substitute for a complete preview document.

The bridge is local to your computer. A remote server's 127.0.0.1 refers to that server, not your workstation. Transfer exported JSON locally rather than exposing the editor port publicly.

8. Export and back up your work

Open Export and choose the output you need:

Portable project backups

Enable Include imported assets when exporting a project to another browser or computer. This embeds the imported textures used by that project, excluding unused library images. Connected disk images must still be accessible during export.

Restore the backup with Projects → Import. New project backups use format version 2; version 1 backups remain importable.

Transparent PNGs

In PNG preview, turn off Include background for transparent output. Your CUI's own panels keep their authored opacity. Choose 1× or 2× resolution; exports above 50 megapixels are refused. If a render fails, try 1× and check for missing or inaccessible images.

Autosave and storage

Projects are saved in the current browser's site storage. The exact address and port matter: localhost, 127.0.0.1, different ports and the hosted demo each have separate storage.

Export backups before changing browsers, changing the address, clearing site data or moving computers. If autosave reports Not saved, export a project file before closing the page. Clearing site data can delete projects, imported artwork and captures.

Image mappings are shared by projects within the same local library. Replacing a mapping can change every project that uses that reference.

9. Keyboard shortcuts

Use Cmd on macOS and Ctrl on Windows/Linux for the shortcuts below. Editor shortcuts are ignored while typing in a field or code editor.

10. Troubleshooting

11. Rendering limits and final checks

CUI Forge is a browser preview. It follows anchor/offset geometry, but text metrics, UI scale, blur, custom materials, sliced images, radial fills and animation can differ from Rust. Scroll views, sliders and toggles are approximate. Rotated elements can also have selection bounds that differ from their visible shape.

Before releasing a plugin, test the exported layout in a real Rust client and test server. Check:

• Target resolutions, aspect ratios and UI scale.
• Longer player names, translations and text wrapping.
• Bright and dark scenes, native HUD overlap and open inventory/loot screens.
• Custom images, fonts and material appearance.
• Cursor/keyboard capture, button commands, close targets and unload cleanup.
• Permissions and gameplay conditions enforced on the server.

The template values and screenshot backgrounds do not establish live-server behavior. Rust-client compatibility has not been established by the release's browser checks.

12. Privacy, updates and support

The default app uses its local loopback server and browser storage. It has no analytics, online activation, silent update checks or automatic diagnostic uploads. After installation, local editing and local images require no external network access.

External image URLs are disabled by default. Enable them through Guide → Limits & privacy only when you want the browser to request images from their hosts. Those hosts receive the image request and your IP address. Optional online item artwork additionally requires starting the server with CUI_FORGE_ONLINE_ICONS=1; see the included docs/NETWORK.md for details. External images are disabled in the static demo.

To update, export project backups, stop the old server and extract the new complete download into its own folder. Start the new version and use the same browser and address, or import your backups. Keep the previous version until you have checked your projects.

For help, open the product's Support tab on Codefling. Include:

• CUI Forge version, operating system and browser version.
• The steps that reproduce the problem and the error text.
• A small JSON example or project backup, with private player/server data removed.
• A screenshot when the issue concerns placement or rendering.

You may use the editor to create and sell your own CUI layouts and plugin code without royalties to Spear. The editor itself may not be redistributed or resold. Third-party assets retain their own licences. Read LICENSE.txt and THIRD-PARTY-NOTICES.txt in the download for the full terms.