Steam Workshop & Plugin Publishing Guide

TransBox features a built-in, intuitive Workshop Hub standalone window. Whether you are a user looking to browse and subscribe to community MODs, or a developer publishing and updating your own extensions, everything can be accomplished seamlessly within the TransBox desktop client—without requiring any external CLI tools or third-party uploaders!

Also see Chinese workshop-publish: Steam Workshop remains; selfpub / non-Steam installs use %APPDATA%/transbox/extensions/ and app extensions/ with Zip export. Selfpub UI lives under src/transbox/ui/qml/selfpub/ (license/account), not UGC upload.

---

1. Overview of Workshop Hub

You can open the Workshop Hub window anytime within TransBox:

• Shortcut 1: Click "Workshop Hub" from the title bar quick menu;
• Shortcut 2: Navigate to Settings → Extension Workshop, and click the "Workshop Hub" button at the top.

The Hub is divided into three primary views:

1. Browse Workshop: Real-time search, tag filtering, paginated grid view, item details, one-click subscription, and live download progress tracking;
2. My Subscriptions: Centralized management of all subscribed MODs on your local machine, showing disk size, update status, one-click re-download, local folder access, or unsubscription;
3. Publish & Update: Automatic mod.json metadata inspection, smart tag mapping, preview image selection, new item creation or incremental updates (via Published File ID picker), and 5-stage live upload progress tracking.

---

2. Pre-Publish Checklist

The technical checks (directory layout / id / version / entrypoint / size / icon / locales) now live in Packaging & size limit § Pre-package self-check. This section lists only the publish-specific items:

• [ ] Workshop Preview Image: preview.png / preview.jpg, 16:9 or 4:3, under 1MB;
• [ ] Encoding: source and data files all saved as UTF-8;
• [ ] No hardcoded credentials: API keys, private tokens and absolute local paths go through config_schema so the user configures them in the UI;
• [ ] Local verification: placed inside extensions/, enabled in the client, every feature tested.

---

3. In-App One-Click Publishing Workflow

Open Workshop Hub → Publish & Update tab. Complete the upload in three easy steps:

Select Plugin Directory ──▶ Auto-Inspect mod.json ──▶ Pick Preview & Check Tags ──▶ Click Upload (New / Update)

Step 1: Select Content Folder (Automatic Metadata Inspection)

1. Click the "Browse..." button next to "Content Folder";
2. Select your local tested plugin folder containing mod.json;
3. Intelligent Auto-Population:
   • Automatically populates the title (prefers name_en in English environments, fallback to name);
   • Automatically extracts description text (prefers description_en or description);
   • Automatically maps official Steam Content Type tags (asr → ASR Engines, theme → Themes, assistant → AI Assistant, etc.);
   • Automatically identifies supports_glossary and toggles the "Glossary-ready" capability badge;
   • Injects id=<plugin_id> into Steam item metadata for community indexing.

Step 2: Choose Preview Image & Change Note

1. Preview Image: Click "Browse..." next to "Preview Image" and choose your banner (.png, .jpg, .jpeg, .webp);
2. Review Type & Capabilities: Confirm that the content type dropdown matches your plugin type. Check "Glossary-ready" if specialized terminology injection is supported;
3. Change Note: Enter a brief summary of the release or update (e.g., v1.0.0 Initial release with full-duplex streaming).

Step 3: Publish New vs. Update Existing

Handle the "Published File ID" field according to your goal:

A. Publishing a Brand New Item

• Leave "Published File ID" completely empty;
• Verify your title, description, and preview image, then click "Upload to Workshop";
• TransBox will invoke ISteamUGC.create_item() to register a new Workshop item under your Steam account and stream the contents.

B. Updating an Existing Item

• Click the "Select..." button next to "Published File ID";
• A picker window "My Published Items" will display all TransBox Workshop items published under your account;
• Filter by title or ID, then click the item to populate the Published File ID (or paste it manually);
• Enter your "Change Note" and click "Upload to Workshop". Steam will update the existing item in place, preserving existing subscriber counts, reviews, and favorites!

---

4. Upload Status & 5-Stage Progress Indicators

During upload, the client displays a smooth progress bar and clear status feedback:

Stage	Name	Progress Range	Description
Stage 1	Prepare Config	0% ~ 15%	Initializes the Steam UGC session and locks item language metadata
Stage 2	Prepare Content	15% ~ 30%	Validates directory structure and computes file checksums
Stage 3	Upload Content	30% ~ 85%	Incrementally streams code and assets to Steam CDN repositories
Stage 4	Upload Preview	85% ~ 95%	Uploads workshop banner image and thumbnail
Stage 5	Commit Changes	95% ~ 100%	Finalizes the transaction and updates item visibility

Steam Legal Agreement Prompt

If this is the first time your Steam account publishes an item to the TransBox Workshop, Steam may require you to accept the Steam Workshop Legal Agreement. The client automatically detects needsLegal: true and opens the Steam Overlay directly to the agreement page. Once accepted, your item becomes publicly accessible to the community!

---

5. Player-Side Subscription & Instant Hot-Reload

TransBox provides a friction-free installation pipeline:

Click "Subscribe" in Workshop Hub
        │
        ▼
Steam Multi-threaded Download (Live percentage progress in UI)
        │
        ▼
Steam triggers ItemInstalled Callback
        │
        ▼
TransBox automatically reloads Plugin Registry (No app restart required!)

1. One-Click Subscription:
   • In Workshop Hub → Browse, click "Subscribe" on any card;
   • The download starts immediately, displaying live percentage and file size in both the browse grid and the "My Subscriptions" panel;
2. Instant Hot-Reload:
   • Once downloaded, TransBox catches the installation notification via event hooks and calls refreshPlugins();
   • No client restart required! The new engine, theme, glossary, or assistant plugin is immediately ready to be activated in Settings.

---

6. Offline & Manual Distribution (Zip Export)

For air-gapped environments, GitHub Releases, or manual distribution on our website:

1. One-Click Export:
   • Go to Settings → Extension Workshop;
   • Click "Export" on any installed plugin card;
   • TransBox creates a standardized zip package: transbox_mod_<id>_v<version>.zip;
2. Manual Zip Packaging:
   • If compressing manually, ensure mod.json is located directly at the root of the archive (do not wrap inside an extra subfolder);
3. Offline Installation:
   • Users simply click "Open Local MOD Directory" in Settings;
   • Extract the zip folder into extensions/;
   • Click "Refresh" to load the plugin instantly.