vscxml User Guide

Complete guide to the vscxml suite for generating, simulating, and designing W3C SCXML state machines.

Overview#

vscxml is a professional development suite that transforms W3C SCXML (State Chart XML) specifications into executable, production-ready code for Java, JavaScript, C#, C, Python, Go, and Structured Text (IEC 61131-3) targets.

The Tools#

vscxml consists of four integrated applications, each available for Windows, macOS, and Linux:

Each tool installs separately and appears in your system's application menu. The VSCXML-Generator-CLI provides the scxml-gen command for terminal use, while the VSCXML-Generator desktop app offers a visual interface for the same functionality.

All tools also integrate with Claude Code and other LLM tools via the MCP Server (49 tools for AI-assisted state machine development).

Why vscxml?#

Workflow#

The recommended workflow for developing state machines:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Visual Editor  │────▶│    Simulator    │────▶│    Generator    │
│  (Design)       │     │  (Test & Debug) │     │  (Build Code)   │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
   Create states         Send events              Output code
   Add transitions       Check behavior           Java/JS/C#/C/
   Define actions        Debug issues             Python/Go

1. Design#

Use the Visual Editor to create your state machine:

• Drag and drop states onto the canvas
• Connect states with transitions
• Add actions for entry, exit, and transitions
• Export to .scxml format

2. Test#

Load your .scxml file in the Simulator:

• Send events and observe state changes
• Inspect variables in the datamodel
• Debug transitions with breakpoints
• Record traces for regression testing

3. Generate#

Use the Code Generator to produce production code:

• Select target language (Java, JavaScript, C#, C, Python, Go, or Structured Text)
• Configure options (package name, output path, bundling)
• Generate code ready for your project

AI Integration (MCP)#

vscxml integrates with Claude Code, Claude Desktop, Cursor, and other MCP-compatible AI tools through the @vscxml/mcp server. This gives AI assistants direct access to 49 tools for designing, simulating, generating, and visually editing state machines.

Setup (One Line)#

claude mcp add vscxml -- npx -y @vscxml/mcp

Restart Claude Code after adding. All 49 VSCXML tools become available.

What You Can Do with AI#

The MCP server bridges all three backends (Generator, Simulator, Editor) and provides:

• Design tools — Create and validate SCXML from natural language
• Simulation tools — Run scenarios, set variables, record traces
• Code generation — Generate complete projects for all 7 targets
• Editor integration — Push diagrams, highlight states, add annotations, take screenshots
• Diagram editing — Add/remove states and transitions, set properties, clone states
• Export — SVG, PNG, interactive HTML player

See the MCP Setup Guide for full documentation and all 49 tools.

VSCXML-Generator Desktop App#

The VSCXML-Generator is a visual desktop application for code generation. It provides the same functionality as the CLI but with a graphical interface powered by the built-in code generation server.

Features#

• Visual code generation — Select target, configure options, and generate with a click
• Monaco editor — Built-in SCXML editor with syntax highlighting and validation
• Live preview — See generated code as you edit the SCXML source
• Multiple targets — Switch between Java, JavaScript, C#, C, Python, Go, and Structured Text
• Project generation — Generate complete runnable projects with build files and runtime libraries

How It Works#

The desktop app bundles the VSCXML-Generator-CLI and starts it as a local REST API server. The React-based UI communicates with this server to provide a seamless visual experience.

VSCXML-Generator (Desktop App)
    │
    │  HTTP (localhost)
    ▼
VSCXML-Generator-CLI (REST Server)
    │
    ▼
Generated Code (Java/JS/C#/C/Python/Go/ST)

Installation#

Download installers for your platform from the vscxml website. Each tool installs independently.

System Requirements#

Installation Locations#

Verifying Installation#

After installation, launch each tool from your system's application menu:

• VSCXML-Editor — Opens the visual state machine designer
• VSCXML-Simulator — Opens the interactive testing environment
• VSCXML-Generator-CLI — Opens a terminal shell with the scxml-gen command ready to use
• VSCXML-Generator — Opens the visual code generation desktop app

The scxml-gen Command#

The VSCXML-Generator-CLI installs a shell environment where scxml-gen is available. Launch it from your application menu to see:

╔═══════════════════════════════════════════════════════════════╗
║                 VSCXML Generator CLI Shell                     ║
║         Code Generator for W3C SCXML State Machines           ║
╠═══════════════════════════════════════════════════════════════╣
║  QUICK START:                                                 ║
║    scxml-gen <input.scxml> -t java -o Output.java             ║
║    scxml-gen <input.scxml> -t javascript -o output.js         ║
║    scxml-gen <input.scxml> -t c -o output.c                   ║
║                                                               ║
║  TARGETS: java, javascript, csharp, c, python, go, st        ║
║  OPTIONS: --code-only, --package, --bundle-auto, --help       ║
╚═══════════════════════════════════════════════════════════════╝

MCP Server (AI Integration)#

To use vscxml tools with Claude Code or other AI assistants:

claude mcp add vscxml -- npx -y @vscxml/mcp

See MCP Setup Guide for details.

Your First State Machine#

Let's create a simple traffic light that cycles through red, green, and yellow.

Step 1: Design in the Editor#

1. Launch the VSCXML-Editor
2. Create three states: red, green, yellow
3. Add transitions:
   • red → green on event timer
   • green → yellow on event timer
   • yellow → red on event timer
4. Set red as the initial state
5. Save as traffic.scxml

Step 2: Test in the Simulator#

1. Launch the VSCXML-Simulator from your application menu
2. At the prompt, type: load traffic.scxml
3. Type start — observe "red" becomes active
4. Type send timer — observe transition to "green"
5. Continue sending timer events to cycle through states

Step 3: Generate Code#

Launch the VSCXML Generator and use the command line:

scxml-gen traffic.scxml -t java -o TrafficLight.java

Target Platforms#

vscxml generates optimized code for seven platforms:

Target Comparison#

See Target Platform Overview for detailed comparison.

Datamodels#

The datamodel attribute determines how expressions and data are evaluated.

Choosing a Datamodel#

• Use null when you don't need variables - maximum portability
• Use ecmascript for complex expressions that work on all targets
• Use native-* for type-safe, target-specific code

See Datamodels Guide for detailed comparison.

Advanced Features#

Invoke Children#

Spawn child state machines from within a parent state. The Generator bundles them at compile time:

scxml-gen parent.scxml -t js --bundle-auto -o parent.js

Benefits:

• No runtime SCXML parsing
• Children run as compiled code
• Single output file
• Works offline/embedded

History States#

Restore previous state configurations when re-entering a compound state:

<state id="editor">
  <history id="editorHistory" type="deep"/>
  <state id="editing">...</state>
  <state id="preview">...</state>
</state>

Parallel States#

Run multiple state regions concurrently:

<parallel id="dashboard">
  <state id="clock">...</state>
  <state id="weather">...</state>
  <state id="notifications">...</state>
</parallel>

Delayed Events#

Schedule events for future delivery:

<state id="waiting">
  <onentry>
    <send event="timeout" delay="5s" id="timeoutTimer"/>
  </onentry>
  <onexit>
    <cancel sendid="timeoutTimer"/>
  </onexit>
  <transition event="timeout" target="expired"/>
</state>

Troubleshooting#

Common Issues#

"Unknown event" warning

Events must be declared or use EVT_UNKNOWN for dynamic events.
Solution: Use generated EVT_* constants for O(1) dispatch.

Delayed events not firing

Java: Ensure executor is started and running
JavaScript: Check setTimeout is available
C (bare-metal): Call tick() in main loop

Invoke child not found

Use --bundle-auto to bundle external children at compile time.
Without bundling, external src requires runtime SCXML loading.

Getting Support#

For help with vscxml, consult the documentation:

• Visual Editor Guide
• Simulator Guide
• Generator Guide
• MCP Setup Guide — AI integration troubleshooting
• W3C SCXML Specification

Quick Reference#

SCXML Structure#

<?xml version="1.0" encoding="UTF-8"?>
<scxml xmlns="http://www.w3.org/2005/07/scxml"
       version="1.0"
       datamodel="ecmascript"
       initial="start">

    <datamodel>
        <data id="count" expr="0"/>
    </datamodel>

    <state id="start">
        <onentry>
            <log label="info" expr="'Starting...'"/>
        </onentry>
        <transition event="go" target="running"/>
    </state>

    <state id="running">
        <transition event="stop" target="done"/>
    </state>

    <final id="done"/>
</scxml>

Generated API (All Targets)#

getEnabledEvents() evaluates guard conditions at query time -- In() predicates compile to O(1) bitset checks, native expressions evaluate directly, and ECMAScript guards use the datamodel engine.

Next Steps#

Tool Guides#

• Visual Editor — Complete editor documentation
• Simulator — Testing and debugging guide
• Generator — Code generation reference (CLI + desktop app)
• MCP Setup — AI integration with Claude Code and other LLM tools

Target Guides#

• Java — JVM integration, executors, GraalVM
• JavaScript — React/Vue, runtime interpreter
• C# — .NET 6+, Unity, Jint ECMAScript
• C — Arduino, memory optimization, MISRA
• Python — dukpy ECMAScript, threading
• Go — Goja ECMAScript, goroutines
• Structured Text — IEC 61131-3, CODESYS, TwinCAT

Tutorials#

• Quick Start — Minimal traffic light example
• Traffic Light Tutorial — Interactive tutorial with European-style traffic light
• Arduino Light Switch — Embedded example
• Invoke Feature — Child state machines