Turboism 0.70.1 Windows Package - User Guide
=================================================

Turboism is a Java agent runtime for the Live2D Cubism editor. It launches
through Turboism-owned shortcuts, and by default the NSIS installer also backs
up and modifies the selected official Cubism startup BAT files so existing
Cubism shortcuts load Turboism; that option can be unchecked during
installation. The operation is hash-guarded, idempotent, and restored on
uninstall.

Bundled JavaScript engine
--------------------------
Both standard packages include the complete offline GraalJS engine. A compatible GraalVM runtime is installed separately through the configurator.

1. Directory layout
-------------------
  turboism-agent.jar             Runtime (Java agent)
  config.json                    Runtime configuration (turboism.runtime.config v1)
  cubism-installations.json      Turboism-owned managed-installation state
  configure_turboism.ps1         WinForms plugin and Cubism setup
  launch-cubism-turboism.bat     Managed launcher entry point
  launch-cubism-turboism.ps1     PowerShell launcher implementation
  cubism-launch-common.ps1       Shared inventory/launch helpers
  plugins/                       Bundled first-party plugin jars
  README.txt / README.zh.txt / README.ja.txt / LICENSE.txt

2. Usage
--------
1. Place the whole folder anywhere, for example %LOCALAPPDATA%\Turboism.
2. Run configure_turboism.ps1. It discovers standard Cubism 5.0–5.3
   family candidates (including patch-suffixed names) from CUBISM_ROOT, Windows
   install records, known program locations, and bounded fixed-drive checks.
   You can also add a folder with the file picker. It checks the official
   CubismEditor5.bat, bundled Java launcher, and expected application JAR shape
   before a root is selectable. A family candidate is not exact patch-version
   proof; runtime identity/admission remains fail closed.
3. Select zero or more installations and plugins, then Save. New supported
   installations start selected; later runs preserve your choices. Invalid or
   unsupported entries are visible and removable. Saving zero installations
   leaves a valid framework-only install and creates no ambiguous launch entry.
   NSIS reuses the verified results from its middle discovery page; final
   configuration does not rescan drives or rerun version probes. A failed scan
   leaves a framework-only install for later setup. Silent installs run one
   bounded scan before payload installation; they do not download the optional
   script engine unless the helper is run separately.
4. The configurator creates one clearly named Start Menu entry per selected
   root, plus a separate - D3D entry when that official D3D BAT exists. Each
   entry carries its exact root and version. The generic launcher never picks
   an arbitrary version: with multiple selected roots it shows a picker.
5. To launch explicitly from a command line, use a canonical root:
       launch-cubism-turboism.bat -CubismRoot "%ProgramFiles%\Live2D\Cubism 5.3.02"
   The managed launcher calls that installation's official CubismEditor5.bat
   (or its separately named D3D BAT), inherits only process-scoped Turboism
   JVM options, and restores the caller's environment afterward. Unrelated
   pre-existing JVM options are preserved.
6. Set TURBOISM_HOME to this folder only when the folder is not the launcher
   folder. Plugin choices are stored in config.json; installation choices are
   stored separately in cubism-installations.json.

3. config.json
--------------
  worktreeId:       "turboism-runtime"
  pluginDirs:       ["plugins"]
  disabledPlugins:  ids of disabled plugins (unchecked ones, ascending; optional)

Before any payload update, config.json is validated. The installer changes only
disabledPlugins to apply the current checkbox selection and preserves every
other valid setting; when selection is already current, the original bytes stay
unchanged. Any other parseable Turboism-owned document — a legacy or
unrecognized schemaVersion, unknown fields, or invalid values — is normalized
to v1 (valid values kept, everything else dropped) and published atomically;
only a foreign `format` declaration or an unparseable file stops the update
without changing payload.

4. Uninstall
------------
- If you installed with the NSIS installer (TurboismInstaller-<ver>.exe),
  run uninstall.exe in the Turboism home directory. It removes only Turboism's
  recorded managed shortcuts/state and owned payload files. The confirmation
  page has a check box "Keep config.json (user configuration)" - checked
  by default; uncheck it to delete config.json.
- ZIP manual installs have no uninstaller and do not enable official-BAT
  integration: close Cubism and delete the Turboism folder.

5. FAQ
------
- No installation is selectable: confirm a 5.0–5.3 family root contains
  CubismEditor5.bat, app\jre\bin\java.exe, and app\lib\Live2D_Cubism.jar;
  exact patch admission is still decided by runtime identity checks.
- Multiple versions are listed: use the per-root Start Menu entry or pass
  -CubismRoot explicitly; Turboism never silently chooses the first result.
- The bat window closes immediately: run launch-cubism-turboism.ps1 from a
  command line to see the localized diagnostic.
- Plugins not working: make sure plugin jars are under plugins/ and the plugin id
  is not listed in disabledPlugins in config.json.
- Logs: <Turboism home>\logs\runtime\YYYY-MM-DD\turboism-*.log
