Developer Overview

TransBox exposes seven practical plugin capabilities for Steam Workshop and local extensions. This document tells you what you can build, which type to pick, and where to start.

Audience: MOD authors, engineers integrating private ASR/MT/TTS, and AI agents implementing plugins directly from this documentation.

---

1. What You Can Build

What you want to do	Recommended type	Barrier	Entry point
Force-translate game/industry terms	glossary	No code	terms.json or terms.txt
Change subtitle colors / opacity	theme	JSON	theme.json
Replace backplates, audio bars, decorations, and other visual components	theme + QML	Medium	ui_extensions
Text cleanup, sensitive-word filters, audio effects	middleware	Python	file.py:ClassName
Integrate a private speech recognizer	asr	Python	Subclass BaseASRProvider
Integrate DeepL / LLM / local translation	mt	Python	Subclass BaseMTEngineProvider
Integrate Edge-TTS / SoVITS, etc.	tts	Python	Subclass BaseTTSProvider
Translate the UI into more languages	i18n	No code	xx.json dictionary

There is also a built-in type, caption_bridge (browser captions); third parties generally do not implement it.

---

2. Overall Flow

Your folder (containing mod.json)
        │
        ▼
PluginRegistry scan
  · Application extensions/ directory
  · %APPDATA%/transbox/extensions/
  · Steam Workshop content/<AppID=1316080>/
        │
        ▼
Dispatch by type
  glossary/i18n/theme → data mount
  asr/mt/tts/middleware → load Python class via importlib
        │
        ▼
User toggles the switch in Extension Workshop
  · Engine classes: select as the current engine in Settings
  · Themes / language packs: switch takes effect on enable (often mutually exclusive)
  · Middleware / glossaries: attach into the pipeline

Lifecycle: discovery → parse mod.json → (on enable) instantiate and initialize(config) → use → disable with shutdown().

---

3. Quick Start

1. Copy extensions/example_custom_mt/ or example_glossary_gaming/.
2. Change id / name in mod.json (id must be globally unique).
3. Drop it into the local extensions directory → Settings → Extension Workshop → Refresh → Enable.
4. For engine types: also select your engine under ASR/MT/TTS settings.
5. Once stable, export a zip. See Workshop Packaging & Publishing.

---

4. Documentation Map

Page	Contents
Local Source & Dev Environment	Python/uv, get it running
Architecture & Lifecycle	Pipeline insertion points, enable/disable behavior
Plugin Spec (required reading)	mod.json, base-class APIs, templates, AI contract
UI Slots & HostContext	Replaceable slots, injected properties
Workshop Packaging & Publishing	Hot debugging, export, Steam publishing facts

---

5. Design Principles (read before writing code)

1. Only implement abstract methods documented here — do not invent hooks that do not exist.
2. entrypoint must point at a real file and class name; if the class name is omitted, the default class name is Plugin.
3. Declare configuration with config_schema, and read it in initialize/update_config via self._config["key"].
4. Do not pip install runtime dependencies into the host environment; for heavy dependencies, attach a local HTTP service instead.
5. Glossary separators, slot names, and Steam upload procedures follow the Plugin Spec. Do not trust outdated blog posts.