Spine Animation Visualizer for VS Code

A VS Code extension that allows you to preview and test Spine animations directly in your editor.

Features

• 🎬 Live Preview: View Spine animations in real-time within VS Code

• 🎨 Skin Switching: Easily switch between different skins

• ▶️ Animation Control: Play and test different animations

• 🔍 Auto-Detection: Automatically finds and loads atlas and PNG files using assetCollection.json

• 📁 Manual Selection: Fallback to manual file selection when needed

• 🎯 Activity Bar Integration: Dedicated sidebar for animation controls

• 🔎 Zoom Controls: Zoom in / zoom out, fit-to-screen and reset view controls in the preview

• 🛠️ Auto-fix Missing Frames: Detects missing atlas frames at load time and inserts temporary 1x1 placeholder frames so animations can still be previewed; a report with required frame names is produced for the art team.

• How it works: The preview detects "Region not found" errors, inserts temporary 1x1 transparent dummy frames into atlas data (in-memory), and retries loading so animations can be played even when atlas frames are missing.

• Retries & limits: The extension will retry automatically (default up to 10 attempts), adding one dummy frame per retry until the animation loads or the limit is reached.

• Reporting: After load completes (or max retries reached) a missing-frames report is written to the extension Output channel; reports can be exported in Text, CSV or JSON formats for the art team.

Requirements

Before using this extension, you need to include the required Spine runtime libraries:

1. Download pixi.min.js from PixiJS
2. Download pixi-spine.js from pixi-spine releases
3. Place both files in the media folder of this extension

Installation

From Source

1. Clone this repository
2. Run npm install
3. Add the required libraries to the media folder (see Requirements)
4. Run npm run compile
5. Press F5 to open a new VS Code window with the extension loaded

From VSIX

1. Package the extension: vsce package
2. Install the .vsix file in VS Code

Usage

Automatic Mode (with assetCollection.json)

1. Open a Spine JSON file in VS Code
2. Click the Play icon (▶️) in the editor toolbar
3. The extension will automatically:
   • Locate your assetCollection.json file
   • Find the matching atlas files
   • Extract required PNG files
   • Load and display the animation

Manual Mode

1. Open a Spine JSON file
2. Click the Play icon or run command "Spine: Preview Spine Animation"
3. If auto-detection fails, click "Select Files Manually"
4. Select your .atlas files (can select multiple)
5. Select your .png files (can select multiple)
6. Animation will load in a new editor panel

Controls

The Spine Visualizer sidebar (accessible from the Activity Bar) provides:

• Animation List: Click any animation to play it
• Skin List: Click any skin to apply it
• Reload: Refresh the current animation
• Change Files: Select different files

The preview panel itself includes the following on-screen controls:

• Zoom In / Zoom Out: Increase or decrease the display scale
• Fit to Screen: Automatically scale and center the animation to fit the preview
• Reset View: Reset zoom and centering to defaults
• Ctrl + Mouse Wheel: Quick zoom using Ctrl + wheel

Asset Collection Format

The extension supports assetCollection.json files with the following structure:

{
  "sources": [
    {
      "fileName": "assets/global/common/symbols/initial/Initial_Symbols.json",
      "type": "spineSequence",
      "atlasList": [
        "Initial_Symbols.atlas",
        "Initial_Symbol_Blur.atlas",
        "Initial_Symbol_FX.atlas"
      ]
    }
  ]
}

Spine JSON Detection

The extension automatically detects Spine JSON files by looking for:

{
  "skeleton": {
    "spine": "3.7.94",
    "hash": "...",
    "width": 115.19,
    "height": 179.51
  }
}

Commands

• Spine: Preview Spine Animation - Open animation preview
• Spine: Select Files Manually - Manually select atlas and PNG files
• Spine: Refresh - Refresh the explorer view
• Spine: Close Preview - Close the preview panel

Configuration

Settings

• spineVisualizer.assetCollectionPath: Custom path to assetCollection.json (optional)
• spineVisualizer.autoPreview: Automatically preview when opening Spine JSON files

Troubleshooting

Animation not loading

1. Ensure all required files are in the same directory or referenced correctly
2. Check that atlas files reference the correct PNG names
3. Verify PNG files exist at the expected paths
4. Use manual file selection as a fallback

Missing textures

• Verify all PNG files referenced in atlas files are included
• Check file names match exactly (case-sensitive)
• Ensure PNGs are in the same directory as atlas files

Auto-fix missing frames

• The preview will attempt to auto-resolve missing frames by inserting temporary 1x1 placeholder frames into the atlas and retrying the load so you can continue testing.
• When placeholders are added a report is written to the extension Output channel listing the missing frame names and the Spine JSON file(s) that triggered them. Use that report to request updated assets from the art team.

If you prefer not to have placeholders written to disk, run the preview with manual file selection and ensure all referenced PNGs are present.

Performance issues

• Large animations may take time to load
• Consider reducing animation quality or size
• Close other heavy extensions temporarily

Development

Project Structure

spine-visualizer-vscode/
├── src/
│   ├── extension.ts              # Main extension entry point
│   ├── spinePreviewPanel.ts      # Animation preview webview
│   ├── spineExplorerProvider.ts  # Sidebar controls
│   ├── assetResolver.ts          # Asset detection logic
│   └── spineDetector.ts          # Spine JSON detection
├── media/
│   ├── pixi.min.js               # PixiJS library (add manually)
│   └── pixi-spine.js             # Spine runtime (add manually)
├── resources/
│   └── spine-icon.svg            # Activity bar icon
└── package.json

Building

npm install
npm run compile

Testing

npm run test

Release Notes

See CHANGELOG.md for a full history. Summary of current Unreleased changes:

Known Limitations

• Only supports Spine runtime version 3.7+
• Requires PixiJS 5.x or higher
• Large animations (>10MB) may have performance issues
• No support for Spine events/audio in current version

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - See LICENSE file for details

Credits

• Built with PixiJS
• Uses pixi-spine runtime
• Spine is created by Esoteric Software

Support

For issues and feature requests, please use the GitHub issue tracker.