When developing or debugging automation for VStitcher-CLI, the most effective debugging tool is the Python Playground plugin inside the VStitcher UI.
Python Playground is not a script runner.
It is an interactive command-line interface that allows you to execute individual BwApi operations one at a time, while observing their effect directly in the VStitcher UI.
This makes it an essential bridge between UI behavior and headless VS-CLI execution.
1. What Python Playground Is (and Is Not)
✅ What it is
An interactive Python command interface
Executes one BwApi operation at a time
Communicates directly with the VStitcher backend
Every operation is immediately reflected in the VStitcher UI
Shows rich UI alerts and error dialogs when something goes wrong
❌ What it is not
Not a full script runner
Not a replacement for VS-CLI
Not suitable for batch or headless execution
Think of Python Playground as a live API console for VStitcher.
2. Why Python Playground Is Critical for Debugging
VS-CLI runs headless and provides limited feedback:
No UI context
Limited error visibility
Exit codes without full explanation
Python Playground solves this by allowing you to:
Execute the same API calls used by VS-CLI
See exactly how each call affects the garment
Receive UI error dialogs with more detailed information than CLI logs
Debug API usage before assembling scripts
👉 Rule of thumb:
If something fails or behaves unexpectedly in VS-CLI, reproduce the API calls step-by-step in Python Playground.
3. Opening Python Playground
Launch VStitcher UI
Open a garment (sample garment recommended)
Open the Python Playground plugin
You will see a command input where you can execute Python statements interactively
4. Debugging via Step-by-Step BwApi Calls
Instead of running a full script, you execute each operation individually.
Example: Inspect garment state
BwApi.GarmentColorwaysIds(BwApi.GarmentId())
Result:
Returns IDs of colorways of the active garment
Example: Inspect snapshots
BwApi.GarmentSnapshotIdsEx(BwApi.GarmentId())
Result:
Snapshot list printed
You can visually confirm available snapshots in the UI
Example: Load a snapshot
BwApi.SnapshotLoadEx(
BwApi.GarmentId(), '{"load_snapshot_option":"saved_colorway_and_avatar","sync_snapshot":true}',
BwApi.GarmentSnapshotIdsEx(BwApi.GarmentId())[0]
)
Result:
Snapshot loads
UI updates instantly (materials, avatar, garment state)
Example: Trigger a render/export operation
preset = '{"exportType":"image","fileFormat":"png","width":2000,"height":2000}'
BwApi.RenderExportByPreset(BwApi.GarmentId(), preset, r"C:\TEST\output") Result:
Export triggered
Output appears on disk
UI reflects rendering process
5. Error Handling: Key Advantage Over VS-CLI
When an error occurs in Python Playground:
VStitcher shows a UI alert dialog
The alert often contains:
More context
Clearer error descriptions
Information that never appears in VS-CLI output
This is critical because:
VS-CLI may only return an exit code
Logs may not explain why an API call failed
UI alerts often immediately reveal:
Invalid parameters
Missing snapshots
Invalid state transitions
Incorrect API usage order
6. Typical Debugging Workflow (Recommended)
Step 1 — Identify the failing CLI behavior
Example:
VS-CLI exits with non-zero code
Script produces no output
Rendering fails silently
Step 2 — Break the script into API calls
Instead of running the full script, extract:
Garment open
Snapshot load
Export call
Any state-changing operations
Step 3 — Execute each call in Python Playground
Run one command at a time
Observe UI changes
Confirm expected behavior
Step 4 — Fix API usage
Adjust parameters
Change call order
Validate snapshot existence
Correct preset JSON
Step 5 — Reassemble into VS-CLI script
Once each operation works in Playground, move them back into a Python file and run via VS-CLI.
7. Why Python Playground Reveals Issues Earlier
Problem Type | CLI | Python Playground |
Missing snapshot | Exit code only | UI alert explains issue |
Invalid preset JSON | Silent failure | UI error dialog |
Wrong call order | Hard to diagnose | UI state shows what’s missing |
Unexpected garment state | Invisible | Immediately visible in UI |
8. Key Takeaway
Python Playground is the primary debugging interface for VS-CLI development because:
It executes exactly the same BwApi calls
It allows one operation at a time
It provides immediate visual feedback
It exposes UI error alerts not available in CLI
It dramatically reduces trial-and-error time
👉 Best practice:
Always validate BwApi usage in Python Playground before running scripts in VS-CLI.