Custom Skeleton Loader

Custom Skeleton Loader for Slay the Spire 2

Overview

CustomSkeletonLoader is a powerful runtime skeleton replacement tool for Slay the Spire 2 that allows modders to replace in-game Spine skeletal animations with custom assets without modifying game files.

It supports 136+ replaceable skeletons including playable characters, monsters, merchants, backgrounds, UI elements, and visual effects.

The mod features a built-in export toolkit for extracting all official skeleton resources from PCK packages, an intelligent name matching algorithm that handles multiple naming variations, and seamless ModConfig panel integration for debugging and one-click exports.

◈ If this mod has helped you, please click the Endorse button to show your support. :)

Features

1. Custom Skeleton Replacement

This mod automatically scans the ReplaceResources
folder within the mod directory for custom skeleton files (.atlas, .skel, .png) and replaces default game skeletons at runtime using Harmony patches with zero intrusion into the original codebase.

Supported resource types:

• .atlas
• .skel
• .png

Replacement coverage includes:

• Playable Characters: Ironclad, Silent, Defect, NecroBinder, Regent (combat + weapon variants).
• Merchant Variants: All 5 characters with unique shop idle animations.
• Rest Site: Character-specific rest animations (including Osty companion for NecroBinder).
• Character Select: Full selection screen skeletons for all 5 classes.
• Monsters: 90+ enemy types across all acts (bosses, elites, normals).
• Backgrounds: Ceremonial Beast, Treasure Room (Act 1/2/3), Merchant Room, Main Menu, Tezcatara.
• UI Elements: Combat orbs (Dark, Frost, Glass, Lightning, Plasma), MegaCrit logo animation.
• Visual Effects: Boss explosions, laser beams, shield effects, scratch marks, blade slashes, vine tendrils.

2. Skeleton Export Tool

The mod includes a comprehensive built-in export feature accessible via the ModConfig panel that extracts all replaceable Spine skeleton resources from the game's PCK packages as standard file formats suitable for editing.

Export capabilities:

• Extracts complete .atlas files from .spatlas (Godot's compressed format).
• Converts .spskel binary to standard .skel format compatible with Spine editors.
• Exports all associated .png texture pages with correct filenames.
• Handles multi-page texture sets (e.g., necrobinder.png + necrobinder_2.png).
• Automatically creates /unified subdirectories with renamed file sets for easy to view.
• Merges duplicate skeletons (MD5 hash comparison) to reduce redundancy.

Export output structure:
Spine_resource/
├── ironclad/
│ ├── ironclad.atlas
│ ├── ironclad.skel
│ ├── ironclad.png
│ └── unified/
│ ├── ironclad.atlas
│ ├── ironclad.skel
│ └── ironclad.png
├── necrobinder/
│ ├── necrobinder.atlas
│ ├── necrobinder.skel
│ ├── necrobinder.png
│ ├── necrobinder_2.png
│ └── unified/
│ └── ...
└── ... (130+ skeleton directories)

Total export: 136+ skeleton sets with full texture data. Perfect for creating custom skeleton mods or studying official animation structure.

3. Runtime Stability


Stability features:

• Concurrent-Safe Caching: Uses ConcurrentDictionary for thread-safe skeleton data caching with null-value protection (failed loads are never cached).
• Resource Lifecycle Management: Proper GodotObject disposal in try-catch-finally blocks prevents memory leaks on load failures.
• Harmony Non-Intrusive Patching: All replacements use Harmony prefixes/postfixes that preserve original method behavior as fallback.
• Graceful Degradation: Missing or invalid custom files are silently skipped; game continues with default assets.
• Debug Logging System: Configurable verbose logging for troubleshooting (controlled via ModConfig toggle).
• Export Safety: Atomic export operations with duplicate detection prevent corruption; concurrent export requests are queued.
• Path Auto-Resolution: Automatically locates mod directory relative to DLL location—no manual configuration required.

4. Installation

1. Download the latest release from the mod page.
2. Extract the contents into your Slay the Spire 2 mods folder: .../Slay the Spire 2/mods/
3. Install required dependencies:
   • ModConfig – Required for the in-game settings panel and export functionality (Without installation, only basic replacement function is available.).

Mod directory structure:

CustomSkeletonLoader/
├── CustomSkeletonLoader.dll
├── CustomSkeletonLoader.pck
├── CustomSkeletonLoader.json
└── ReplaceResources/
│ (Place custom skeleton files here)
│ ├── ironclad/
│ │ ├── ironclad.atlas
│ │ ├── ironclad.skel
│ │ └── ironclad.png
│ ├── silent/
│ │ └── ...
│ └── ... (other skeleton directories)

——————————————————————————————————————————————————————————————————————

Configuration

All settings are accessible via the in-game ModConfig panel under the "CustomSkeletonLoader" section:

• Enable Debug Logs (Toggle, ON)
• Export All Skeletons (Button) – One-click extraction of all 136+ game skeletons to /Spine_resource folder. Converts Godot formats (.spatlas/.spskel) to standard Spine formats (.atlas/.skel) and exports all PNG textures.
• The Spine files in the /unified folder are only renamed versions for convenient import into editing tools, and are *NOT* intended for actual resource replacement.

Usage

Creating Custom Skeletons

1. Export base game skeletons using the Export button in ModConfig panel.
2. Navigate to exported directory: .../mods/CustomSkeletonLoader/Spine_resource/{skeleton_name}/unified/
3. Edit skeleton files using Spine-compatible tools (e.g., Spine Essential, alternative editors).
4. Place modified files in: .../mods/CustomSkeletonLoader/ReplaceResources/{skeleton_name}/
5. Check if the filenames of the replaced files match the original filenames.
6. Restart the game – skeletons load at runtime during first access (lazy loading).

File Naming Convention

Custom skeleton files must follow this structure inside the ReplaceResources/
directory:

• Directory name: Use the target skeleton identifier
• Atlas file: {name}.atlas
• Skeleton data: {name}.skel
• Texture pages: {name}.png, {name}_2.png, etc. (as referenced by atlas)

Supported naming examples:

ReplaceResources/
├── ironclad/ # Replaces combat Ironclad
│ ├── ironclad.atlas
│ ├── ironclad.skel
│ └── ironclad.png
├── ironclad_merchant/ # Replaces shop Ironclad (auto-matched)
│ ├── ironclad_merchant.atlas
│ ├── ironclad_merchant.skel
│ └── ironclad_merchant.png
├── necrobinder/ # Replaces combat NecroBinder
│ └── ...
├── ceremonial_beast/ # Replaces boss monster
│ └── ...
└── dark_orb/ # Replaces UI orb animation
└── ...

(Supports reading files in subfolders. Smart matching will find your files even with naming variations.)

———————————————————————————————————————————————————————

Troubleshooting
Custom skeletons not loading

1. Verify all three file types exist (.atlas, .skel, .png) in the same directory.
2. Check that PNG filenames exactly match references inside the .atlas file (case-sensitive).
3. Enable Debug Logs in ModConfig and check game log for messages.
4. Confirm ReplaceResources/ is inside the mod folder (not in Spine_resource/)
5. Ensure skeleton directory name matches the target .

Export failing or incomplete

1. Check write permissions for the mod directory.
2. Ensure sufficient disk space (export produces 136+ directories with textures).
3. Verify ModConfig dependency is installed and working.
4. Check game log for export progress messages and error details.

Texture/atlas errors after replacement

1. Validate .atlas file syntax using a text editor (check for corrupted JSON in spatlas conversion).
2. Ensure .skel file version compatibility with your Spine runtime version.
3. Test with original exported files first to confirm replacement pipeline works.
4. Check that all PNG texture pages referenced in atlas exist in the same directory.

Game crashes or performance issues

1. Disable Debug Logs in production (verbose logging impacts performance).
2. Reduce number of simultaneously replaced skeletons to isolate problematic assets.
3. Verify custom skeleton files are not corrupted (test in Spine editor first).
4. Check that .png files are not excessively large (recommend keeping under 2048×2048 per page).

The game freeze after clicking the Export button

• Resources are being exported in the background,Please wait patiently for 10–30 seconds,The export speed depends on your device performance.

Related tools:

• Godot RE Tools – Extract resources from other STS2 mods or game versions for reference.
• Custom Card Texture Loader SG - Load custom card textures with GIF animation support, interactive playback mode, and texture export functionality.

This mod is designed to empower animators and modders with seamless skeleton customization, eliminating the need for complex repacking while providing professional-grade tools for asset extraction and replacement.
Love from STS2 mod creators.
:)