VSCXML: Definitive Feature Matrix

Purpose: Authoritative reference for all targets, execution modes, datamodels, and features. Last Updated: 2026-02-09 Test Verification Date: 2026-02-09 (all numbers verified by actual test execution)

1. TARGETS (Code Generation Platforms)#

2. EXECUTION MODES#

3. DATAMODELS#

3.1 Datamodel Enum Values#

Source: DataModelType.java

3.2 Datamodel Support Matrix (Verified Test Results)#

3.3 ECMAScript Engine Support#

4. VERIFIED TEST RESULTS#

4.1 Java Test Summary#

4.2 JavaScript Test Summary#

4.3 C# Test Summary#

4.4 Go Test Summary#

4.5 Structured Text Test Summary#

5. FEATURE SUPPORT#

5.1 SCXML Core Features#

5.2 Debugging & Tooling Features#

5.3 Runtime APIs (Trace & Executor)#

Cross-target APIs for professional state machine integration.

Trace System#

JSONL Trace Format (Cross-Target Compatible)#

All targets produce identical JSONL format for trace interoperability:

{"timestamp":0,"type":"session_start","session_id":"abc123","scxml_name":"TrafficLight","datamodel":"ecmascript"}
{"timestamp":1234,"type":"state_enter","state_id":"red"}
{"timestamp":2345,"type":"transition","from":"red","to":"green","event":"timer"}
{"timestamp":3456,"type":"state_exit","state_id":"green","invoke_id":"childMachine"}

Executor System#

5.4 Event Introspection API#

Every generated state machine exposes which events it can process and which are currently enabled.

getEnabledEvents() and getEnabledEventsForState(id) evaluate guard conditions at query time. In() predicates compile to O(1) bitset checks, native expressions evaluate directly, and ECMAScript guards use the datamodel engine. The getAllEvents() and getEventsForState(id) methods are static lookups that do not evaluate guards.

5.5 Simulator Support#

6. KEY FILES#

Java Generators#

• TranspilerCodeGenerator.java - Java transpiler

Java Runtime Base Classes#

• TranspiledStateMachine.java - Base class for transpiled machines
• RuntimeStateMachine.java - SCXML interpreter

JavaScript#

• JavaScriptCodeGenerator.java - JS transpiler
• RuntimeInterpreter.js - JS runtime

C##

• CSharpCodeGenerator.java - C# transpiler
• scxml-csharp/src/ScxmlGen.Runtime/ - C# runtime base classes
• scxml-csharp/src/ScxmlGen.Runtime/Datamodel/JintDataModel.cs - ECMAScript via Jint

Python#

• PythonCodeGenerator.java - Python transpiler
• scxml-python/src/scxmlgen/ - Python runtime base classes
• scxml-python/src/scxmlgen/datamodel/ecmascript_datamodel.py - ECMAScript via dukpy

Go#

• GoCodeGenerator.java - Go transpiler
• scxml-go/scxmlgen/ - Go runtime base package
• scxml-go/scxmlgen/datamodel_ecmascript.go - ECMAScript via Goja
• scxml-go/scxmlgen/transpiled_state_machine.go - Base struct for transpiled machines

C Target#

• CTargetEmitter.java - C code generator

Structured Text#

• StructuredTextCodeGenerator.java - IEC 61131-3 ST code generator (FUNCTION_BLOCK output)

Datamodels (Java)#

• RhinoDataModel.java - ECMAScript via Rhino
• GraalJsDataModel.java - ECMAScript via GraalJS
• XPathDataModel.java - XPath 2.0 (Runtime only)
• NullDataModel.java - Null datamodel
• NativeDataModel.java - Native Java (V3 transpiled only)

7. ARCHITECTURE#

Active Components#

XPath Support#

XPath is ONLY supported in Java Runtime (RuntimeStateMachine).

• XPath support: 89.1% compliance (179/201 tests)
• Users needing XPath use the simulator/runtime interpreter
• Transpiled mode does NOT need XPath - this is acceptable
• XPath tests are tracked but don't block the CI build

8. CLI#

The CLI (ScxmlGeneratorCli.java) uses TranspilerCodeGenerator for Java target generation.

9. TEST INFRASTRUCTURE#

10. KEY INSIGHTS FROM TEST VERIFICATION#

1. All ECMAScript combinations achieve 100% compliance (Rhino, GraalJS, Jint, JerryScript, dukpy, Goja)
2. All Null datamodel combinations achieve 100% compliance (Runtime and Transpiled)
3. All native datamodels achieve 100% compliance (native-java, native-js, native-csharp, native-c, native-python, native-go)
4. JavaScript achieves 100% compliance in both Runtime and Transpiled modes
5. C# achieves 100% compliance with Jint ECMAScript engine (200/200 tests)
6. Python achieves 100% compliance with dukpy ECMAScript engine (188/188 tests)
7. Go achieves 100% compliance with Goja ECMAScript engine (209/209 tests)
8. XPath has lower compliance (~89%) but is only needed for Runtime/simulation use cases
9. Structured Text target generates IEC 61131-3 FUNCTION_BLOCK output for CODESYS/TwinCAT PLCs with null and native-st datamodels
10. V1 Compiled can be safely removed - V3 Transpiled is strictly better

11. TEST COMMAND REFERENCE#

Java Tests#

# V3 Transpiled (Rhino) - PRIMARY
./gradlew test --tests "TranspilerW3cTestSuite"

# V3 Transpiled (GraalJS)
./gradlew test --tests "W3cJupiterTestSuite.graalJsTests"

# V3 Transpiled (Null)
./gradlew test --tests "W3cJupiterTestSuite.nullTranspiledTests"

# V3 Native-java
./gradlew test --tests "NativeDataModelTest"

# Runtime (Rhino)
./gradlew test --tests "W3cJupiterTestSuite.runtimeEcmascriptTests"

# Runtime (GraalJS)
./gradlew test --tests "W3cJupiterTestSuite.graalJsRuntimeTests"

# Runtime (XPath)
./gradlew test --tests "W3cJupiterTestSuite.runtimeXpathTests"

# Runtime (Null)
./gradlew test --tests "W3cJupiterTestSuite.runtimeNullTests"

# All tests
./gradlew :scxml-core:test

JavaScript Tests#

cd scxml-js

# Runtime (all datamodels)
node test/run-runtime-tests.js

# Transpiled (all datamodels)
node test/run-tests.cjs

C# Tests#

cd scxml-csharp

# All tests (ECMAScript, Null, Native-CSharp)
dotnet test

Python Tests#

cd scxml-python/tests

# ECMAScript tests (dukpy)
python run_tests.py --datamodel ecmascript

# Null datamodel tests
python run_tests.py --datamodel null

# Single test with verbose output
python run_tests.py --datamodel ecmascript --filter test144 --verbose

Go Tests#

cd scxml-go/tests

# ECMAScript tests (Goja)
go run . -datamodel ecmascript

# Null datamodel tests
go run . -datamodel null

# Native-Go tests
go run . -datamodel native-go

# Single test with verbose output
go run . -datamodel ecmascript -filter test144 -verbose

Structured Text Tests#

cd scxml-st/test

# Null datamodel tests (generate + CODESYS simulation)
python run_tests.py --datamodel null --verbose

# Native-ST tests (uses native-go test sources)
python run_tests.py --datamodel native-st --verbose

# Generate only (no CODESYS required)
python run_tests.py --datamodel null --generate-only --output-dir ./st-output

# Single test
python run_tests.py --datamodel null --filter test_null_basic --verbose

12. RELATED DOCUMENTATION#

• docs/DATAMODELS.md - User documentation for datamodel selection