Skip to main content

​
Overview

The mod preview feature allows you to view Spine animations for character mods before syncing them to the game. This helps you verify that mods look correct and make informed decisions about which mods to enable.

​
How it works

The mod preview uses an external tool called BD2ModPreview to display Spine animations. This approach is necessary because:
  • Python doesn’t have a native Spine runtime
  • Embedding a web-based preview would add ~100MB to the app size (via QtWebEngine/Chromium)
  • A standalone executable keeps the main app lightweight and fast
From src/services/mod_preview.py:10-14: 
# this is the best way to handle spine animations
# python does not have a spine runtime 
# and using qtwebengine makes the app bigger ~+100MB and makes it slower because of the chromium
class BD2ModPreview(QObject):
    errorOccurred = Signal(str)

​
BD2ModPreview tool

The preview tool is a separate executable (BD2ModPreview.exe) that:
  • Loads Spine animation files from mod folders
  • Renders animations in real-time
  • Supports playback controls (play, pause, loop)
  • Displays multiple animations if available

​
Tool location

The manager looks for the preview tool in two locations (see src/services/mod_preview.py:22-28):
  1. User tools directory - For updated versions: user_tools/BD2ModPreview.exe
  2. Bundled tools directory - Fallback to bundled version: tools/BD2ModPreview.exe
def refresh_path(self):
    # if it has a updated version in user's path
    self._tool_path = app_paths.user_tools_path / "BD2ModPreview.exe"
    
    # fallback: to bundled mod preview
    if not self._tool_path.is_file():
        self._tool_path = app_paths.tools_path / "BD2ModPreview.exe"
This allows users to update the preview tool independently of the main application.

​
Previewing mods

1

Select a mod

In the mod manager, select a character mod (Idle, Cutscene, Dating, or NPC type).
2

Open preview

Right-click the mod and select Preview, or use the preview button/icon.
3

View animation

The BD2ModPreview tool launches in a separate window and loads the mod’s Spine animation.
4

Interact with preview

Use the preview tool’s controls to:
  • Play/pause the animation
  • Switch between multiple animations (if the mod has multiple)
  • Adjust playback speed
  • View animation details

​
What can be previewed

The preview feature works with mods that contain Spine animation data:

​
Supported mod types

  • Idle mods - Character idle stance animations
  • Cutscene mods - Character cutscene animations
  • Dating mods - Dating scene character animations
  • NPC mods - NPC character animations (if they have Spine data)

​
Preview requirements

For a mod to be previewable, it must contain:
  • Spine skeleton data (.skel or .json files)
  • Spine atlas files (.atlas or .atlas.txt)
  • Associated texture images (PNG files)
Scene mods (special illustrations) typically cannot be previewed as they don’t use Spine animations.

​
Launching the preview

The preview is launched as a separate process (see src/services/mod_preview.py:44-52): 
def launch_preview(self, path: str) -> None:
    if not self._tool_path.exists():
        return self.errorOccurred.emit("BD2ModPreview.exe not found. Please update or reinstall the tool.")
    
    try:
        subprocess.Popen([self._tool_path.as_posix(), path])
    except Exception as error:
        logger.error(f"An error occurred while launching BD2ModPreview", exc_info=error)
        self.errorOccurred.emit(f"An error occurred while launching BD2ModPreview: {error}")
The mod’s folder path is passed to BD2ModPreview, which automatically detects and loads the Spine files inside.

​
Preview tool version

The manager can check the BD2ModPreview version (see src/services/mod_preview.py:30-42): 
def get_version(self) -> str | None:
    try:
        result = subprocess.run(
            [str(self._tool_path), "--version"],
            capture_output=True,
            text=True,
            timeout=3
        )
        version = result.stdout.strip()
        return version if version else None
    except Exception as error:
        logger.warning(f"Error checking Mod Preview version", exc_info=error)
        return None
This allows the manager to:
  • Display the current preview tool version
  • Notify users when updates are available
  • Troubleshoot compatibility issues

​
Error handling

The preview feature handles common errors:

​
Tool not found

If BD2ModPreview.exe is missing:
BD2ModPreview.exe not found. Please update or reinstall the tool.The preview tool may be missing or corrupted. Try reinstalling BD2 Mod Manager or downloading the latest version.

​
Launch failure

If the tool fails to start:
  • Check that the mod folder exists and contains valid Spine data
  • Ensure you have permissions to execute the preview tool
  • Verify that required DLL files are present

​
Invalid mod data

If the preview tool opens but shows errors:
  • The mod may be corrupted or incomplete
  • Spine files may be in an unsupported format
  • Required texture files may be missing

​
Preview from mod manager

The preview request is triggered from the mod manager controller (see src/controllers/mod_manager_controller.py:86): 
self.view.modPreviewRequested.connect(self.modPreviewRequested.emit)
This signal chain allows:
  1. User clicks preview in the view
  2. View emits modPreviewRequested signal
  3. Controller forwards the signal
  4. Main application launches BD2ModPreview with the mod path

​
Benefits of previewing

​
Verify mod quality

Preview animations to ensure:
  • Animations play smoothly
  • Character appearance matches expectations
  • No visual glitches or missing textures
  • Multiple animation variants (if included)

​
Compare mods

Preview multiple mods for the same character to:
  • Choose your favorite version
  • Compare different artists’ styles
  • Decide which mods to keep enabled

​
Test before syncing

Preview new mods before enabling them:
  1. Add a new mod to the manager
  2. Preview it without enabling
  3. Enable and sync only if you like it
  4. Save time by avoiding unnecessary syncs
Previewing mods doesn’t require them to be enabled or synced, so you can check out new mods risk-free.

​
Updating BD2ModPreview

Keep the preview tool up to date:
1

Check current version

The mod manager may display the BD2ModPreview version in settings or about dialog.
2

Download latest version

Download the latest BD2ModPreview from the official releases or community sources.
3

Place in user tools directory

Copy BD2ModPreview.exe to the user tools directory. The manager will automatically use this version instead of the bundled one.
4

Restart mod manager

Restart the mod manager to ensure it detects the new version.

​
Technical details

The preview system uses:
  • Subprocess module - Launches BD2ModPreview as a separate process
  • Path validation - Ensures mod folder exists before launching
  • Error signals - Communicates errors back to the UI via Qt signals
  • Version checking - Executes --version flag to get tool version
This architecture keeps the preview functionality modular and maintainable, allowing independent updates to both the main manager and the preview tool.

Build docs developers (and LLMs) love

Get started for freeTalk to us