Plugin Management

Discover, configure, enable, disable, and manage Turboism plugins safely.

Turboism provides several complementary ways to manage plugins:

  • the in-Cubism Plugin Market (Turboism menu → Plugin Market…) or turboism.dev/plugins to discover and install first-party and catalog plugins;
  • background auto-updates for verified first-party plugins;
  • Manage Plugins… to enable, disable, uninstall, or stage local plugin JARs;
  • Plugin Settings… in a dedicated two-pane window to configure plugin options.

Every installer and ZIP package already ships the reviewed first-party plugin bundle. Additional plugins, or bundled plugins you removed, can be installed from the Plugin Market.

All plugin lifecycle and file changes are staged and applied safely. Staged updates apply after Cubism restarts, while plugins marked with hot-reload support can update immediately.

The Turboism top menu

In Cubism Editor, all framework and plugin controls are centralized under the top-level Turboism menu (previously named "插件"/Plugins). Its items are:

  1. Plugin Market… — browse and install first-party and curated plugins from the live catalog.
  2. Manage Plugins… — view installed plugins, toggle enable/disable state, install local JARs, and uninstall plugins.
  3. Plugin Settings… — open the dedicated two-pane settings window to configure options for all installed plugins.
  4. Check for Updates — check for new Turboism releases.
  5. Turboism Settings… — configure framework-level preferences (updates, runtime logging, locale, and launch options).
  6. Keybindings… — inspect and customize action keyboard shortcuts.
  7. Logs… — open runtime and diagnostic log directories.
  8. Plugin actions — action items contributed by active plugins.
  9. About — view the installed Turboism version and build identity.

Plugin Market and automatic updates

Since 0.67.0, first-party plugins can be installed and kept up-to-date without reinstalling the framework:

  • Open Turboism → Plugin Market… or visit turboism.dev/plugins to browse available plugins.
  • First-party plugins auto-update in the background after signature verification.
  • Plugins marked hot-reload apply immediately without interrupting your modeling workflow.
  • Other plugin updates apply the next time Cubism restarts.
  • Users can disable automatic plugin updates anytime in framework settings.
  • Since 0.67.4, the plugin management windows show how many plugins are installed and how many are available in the market.
  • Plugins whose declared API range does not include the running Turboism API are marked as incompatible in the market.

Plugin details: API range and Cubism versions

In Turboism → Manage Plugins…, double-click a plugin or press Enter to view its details. Since 0.67.2, the details show:

  • the plugin's SDK API compatibility range, for example [0.67.0,1.0.0);
  • the exact Cubism Editor versions the plugin declares, listed separately as versions with available features, versions with full functionality, and versions with partial functionality. Missing or invalid declarations are shown as Not declared.

First-party plugin JARs carry these declarations in META-INF/turboism/cubism-versions.json, generated from reviewed capability requirements. See Compatibility for the per-plugin ranges.

Plugin API ranges start at the minimum Turboism framework version the plugin needs and end before 1.0.0. Most official plugins require 0.67.0; some require 0.67.2 or 0.67.4 because they use newer SDK additions (see First-Party Plugins). Legacy plugins declaring [0.1.0,0.2.0) are rejected.

Plugin Settings

To configure plugin-specific options, select Turboism → Plugin Settings…:

  • Opens a dedicated two-pane window: the left pane lists installed plugins, and the right pane displays the active plugin's configuration form.
  • Settings are validated before being saved to config/<pluginId>/.
  • Built-in framework settings remain separate under Turboism → Turboism Settings….

Managed local JAR installation

To install a custom or locally built plugin JAR:

  1. Build or obtain a plugin JAR from a source you trust.
  2. In Cubism, choose Turboism → Manage Plugins….
  3. Choose Install from JAR….
  4. Select the local .jar file.
  5. Confirm the dialog that marks the JAR as a local/unverified source.
  6. Confirm that the operation is shown as pending.
  7. Close Cubism normally and restart through the same Turboism home.
  8. Check the plugin list in Manage Plugins… and Runtime logs for the effective state.

Before staging, Runtime treats the selected JAR as untrusted local input. It opens a regular non-symlink JAR under bounded archive limits (raw size, per-entry size, total expansion, entry count, and compression ratio), inspects exactly one descriptor and the plugin content, then snapshots the payload into pending state.

The staging journal persists the raw JAR SHA-256 and size, the descriptor hash, the plugin ID, and the version. On the next startup, Runtime revalidates the staged JAR against that identity before applying it.

Replace or update a plugin

  • First-party plugins: update automatically in the background or via the Plugin Market….
  • Local/third-party plugins: install the newer JAR with the same plugin ID through Manage Plugins… → Install from JAR… to stage a replacement intent.

Recommended procedure for local replacements:

  1. Back up the current JAR and the plugin's persistent configuration/data.
  2. Install the newer JAR through plugin management.
  3. Restart Cubism.
  4. Verify the displayed version, lifecycle state, configuration migration, and logs.

Startup preflight revalidates the staged JAR, and a failed apply restores the previous plugin files from a private backup. There is no retained historical version list, and no complete user-facing rollback or purge UI.

Disable or enable a plugin

In Turboism → Manage Plugins…, toggle the active state for any installed plugin.

  • The desired state is persisted in config.json under disabledPlugins and applies after Cubism restarts.
  • The Runtime-owned turboism.core shell is built-in framework code and cannot be disabled.
  • Disabled plugins are skipped during the next startup discovery.
  • Rerunning or upgrading the installer preserves your disabledPlugins list: it never silently re-enables plugins you previously disabled.

Uninstall a plugin

  1. Open Turboism → Manage Plugins….
  2. Select the plugin and choose Uninstall.
  3. Confirm the pending operation.
  4. Restart Cubism.
  5. Confirm that the plugin is no longer loaded.
  6. Decide whether to retain or remove its persistent data.

Removing the plugin JAR does not automatically erase every plugin-owned file:

  • retain config/<pluginId>/ and data/<pluginId>/ if settings or data may be needed after reinstall;
  • cache/<pluginId>/, state/<pluginId>/, and logs/<pluginId>/ can be removed while Turboism is stopped;
  • deleting configuration or persistent data is irreversible without a backup.

Manual installation (advanced fallback)

Manual installation is a fallback for testing trusted plugin JARs outside the UI. It copies a JAR directly into <turboism.home>/plugins/ instead of going through managed staging. Ordinary users should prefer the Plugin Market or managed installation.

A plugin JAR is the JAR built from plugin source. It is not the Turboism installer executable or archive.

Install a plugin JAR manually

  1. Fully close Cubism and Turboism. Plugin JARs are scanned at startup, so changes require a full stop and restart.
  2. Identify the exact Turboism home used by the launcher.
  3. Create or open <turboism.home>/plugins/.
  4. Copy the plugin JAR directly into the root of <turboism.home>/plugins/, and keep at most one JAR for each plugin ID. Do not place it in a nested folder and do not use a symlink.
  5. Start Cubism again through the same Turboism home.
  6. Check the plugin state in Manage Plugins… and Runtime logs.

The plugins/ location depends on the installation:

  • Windows installer default: %LOCALAPPDATA%\Turboism\plugins\
  • custom home: <selected Turboism directory>/plugins/

Replace or update a manually installed plugin

  1. Stop Cubism and Turboism first.
  2. Back up the old JAR and the plugin's config/<pluginId>/ and data/<pluginId>/ content.
  3. Remove the old same-ID JAR before copying the replacement. Two JARs with the same plugin ID fail with DUPLICATE_PLUGIN_ID.
  4. Restart with the same Turboism home and verify the version, state, and logs.

Uninstall a manually installed plugin

  1. Stop Cubism and Turboism.
  2. Remove the plugin JAR from <turboism.home>/plugins/.
  3. Restart and confirm the plugin is no longer loaded.
  4. Remove config/<pluginId>/ or data/<pluginId>/ only while Turboism is stopped, and only with a backup.

JAR rejection

A managed JAR can be rejected for reasons including:

  • a symbolic link or non-regular source path;
  • a size, entry, expansion, or compression-ratio limit violation;
  • malformed or ambiguous ZIP paths;
  • duplicate entries or special files;
  • more or fewer than one META-INF/turboism/plugin.json;
  • descriptor ID, version, or API-range inconsistencies;
  • copied SDK, Runtime, test, or Live2D classes;
  • native or installer payloads;
  • nested JAR content;
  • missing entrypoint classes, declared resources, or i18n catalogs.

Rebuild the JAR from the current plugin source. Do not edit the archive manually or disable inspection.

Current limitations

Plugin management does not currently provide:

  • arbitrary unverified third-party signature authority or uncurated store uploads;
  • retained arbitrary historical version rollbacks;
  • a complete user-facing purge or repair UI;
  • system-level modification of Cubism installations or launchers.