Spine Animation Visualizer for VS Code

A VS Code extension that allows you to preview and test Spine animations directly in your editor, with audio synchronization, bone inspection, and visual filters.

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
• Audio Waveform & Markers (v1.5.0): Attach audio clips to the timeline with a visual waveform canvas! Click and drag to scrub/select audio regions, and watch the playhead sync perfectly with the animation playback.
• Bone & Slot Inspector (v1.4.0): Click any bone in the canvas to inspect its name, world position, parent bone, and attached slots; Ctrl+Click to jump directly to the bone definition in the Spine JSON
• Visual Filters (v1.4.0): Apply Blur, Brightness, Contrast, and Desaturate filters; toggle Spine's built-in clipping/masking on or off to match game rendering

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 includes on-screen controls:

• Zoom In / Zoom Out: Increase or decrease the display scale
• Fit to Screen: Automatically scale and center the animation
• Reset View: Reset zoom and centering to defaults
• Settings (S): Opens the Settings panel with all feature toggles
• Ctrl + Mouse Wheel: Quick zoom

Keyboard Shortcuts

Audio Waveform & Markers (v1.5.0)

Attach audio clips to specific points in the animation timeline with a rich, interactive waveform canvas.

How to use the Audio panel

1. Click the 🔊 icon in the bottom control bar to toggle the audio panel.
2. Click + Add to pick an MP3, WAV, or OGG file from the file picker.
3. The Waveform Canvas will automatically draw the audio's waveform above the timeline.
4. Interactive Scrubbing: Click and drag across the waveform to instantly set the Start and Duration of your clip.
5. The selected audio region is highlighted in blue on the waveform.
6. Press the ▶ (Play) button next to the filename on the panel to preview the clip independently, or press play on the main animation timeline to watch the red playhead sync perfectly to your animation playback.

Audio Tips

• Yellow dots on the animation timeline show where each marker fires — hover to see the name, click the timeline dot to preview.
• The entire audio panel can be collapsed using the 🔊 button to save screen real estate.
• Audio context is initialized on first play/user gesture (browser security requirement).

Bone & Slot Inspector (v1.4.0)

Inspect any bone in the rendered skeleton to see its properties and navigate to its JSON definition.

How to Use

1. Open Settings and enable Bone & Slot Inspector, or press I
2. A blue hint bar appears: "Click a bone to inspect"
3. Click anywhere on the canvas — the nearest bone is highlighted
4. The inspector card shows:
   • Bone name and world position
   • Parent bone
   • All attached slots and their current attachment names
5. Click Open Bone in JSON in the card, or Ctrl+Click on the canvas, to jump to that bone's definition in the source JSON

Visual Filters & Masking (v1.4.0)

Apply PIXI rendering filters to the animation to match game-engine rendering conditions.

All filters are toggled from the Settings panel. Multiple filters can be active simultaneously.

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
• If you prefer not to have placeholders written to disk, use manual file selection and ensure all referenced PNGs are present

Audio not playing

• Audio requires a user gesture to start (browser security policy) — press Play or Space first
• Make sure the audio file is a valid MP3, WAV, or OGG
• If the trigger time is beyond the animation duration, move the slider within range

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
│   └── utils/
│       ├── spinePreviewPanel.ts        # Animation preview webview (all 3 new features)
│       ├── spineExplorerProvider.ts    # Sidebar animation/skin controls
│       ├── assetResolver.ts            # Asset detection logic
│       ├── spineDetector.ts            # Spine JSON detection
│       └── missingFrameResolver.ts     # Auto-fix missing atlas frames
├── 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 the full version history.

Known Limitations

• Only supports Spine runtime version 3.7+
• Requires PixiJS 5.x or higher
• Large animations (>10MB) may have performance issues
• Bone inspector click radius scales with zoom — at very small scales, click closer to the bone root

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.