Go State Machine Library

State Machines in Go

Go's type system with generics (Go 1.18+) and interface-based polymorphism provides a clean foundation for state machine implementations. However, hand-writing complex state machines with hierarchical states, parallel regions, and history states requires significant boilerplate that is difficult to maintain as complexity grows.

Existing approaches compared

SCE takes a unique approach in the Go ecosystem: instead of a runtime-configured DSL, you define state machines in W3C SCXML (the international standard for statecharts), and SCE's code generator produces idiomatic Go code at build time. This gives you the full power of the W3C specification -- hierarchical states, parallel regions, history, invoke, delayed events -- with type-safe generated code using Go generics.

How It Works

Step 1: Define your state machine in SCXML

<?xml version="1.0" encoding="UTF-8"?>
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
       name="traffic_light" initial="red">
  <state id="red">
    <transition event="timer" target="green"/>
  </state>
  <state id="green">
    <transition event="timer" target="yellow"/>
  </state>
  <state id="yellow">
    <transition event="timer" target="red"/>
  </state>
</scxml>

Step 2: Generate Go code

# Generate Go state machine (-l go or --language go)
sce-codegen generate --scxml traffic_light.scxml --language go --output-dir ./generated/

The generator produces a Go file containing a State type (iota constants), an Event type, and a Policy struct that implements the StatePolicy[S, E] interface. The Engine[S, E] generic type from sce-go-runtime drives execution.

Step 3: Use in your Go code

package main

import (
    sce "github.com/newmassrael/sce-go-runtime"
    gen "your-module/generated"
)

func main() {
    // Create the policy (generated from SCXML) and engine
    policy := gen.NewTrafficLightPolicy()
    engine := sce.NewEngine[gen.TrafficLightState, gen.TrafficLightEvent](policy)

    engine.Initialize()                                    // Enters "red" state
    engine.ProcessEvent(gen.TrafficLightEventTimer)         // red -> green
    engine.ProcessEvent(gen.TrafficLightEventTimer)         // green -> yellow
    engine.ProcessEvent(gen.TrafficLightEventTimer)         // yellow -> red

    fmt.Println(engine.GetCurrentState() == gen.TrafficLightStateRed) // true
}

ProcessEvent() is a convenience method that combines RaiseExternal() + Step(). For fine-grained control, use them separately:

// Low-level API: queue event, then process explicitly
engine.RaiseExternal(gen.TrafficLightEventTimer, "", "")
engine.Step()

W3C SCXML Features in Go

SCE's Go backend passes all 202 mandatory W3C SCXML conformance tests, supporting the full specification:

Architecture

The Go backend consists of three modules with clear separation of concerns:

The runtime module has zero external dependencies -- it uses only the Go standard library. The Lua engine uses Shopify/go-lua, a pure Go implementation of Lua that requires no C compiler or CGo. This makes the entire stack cross-compilable to any platform Go supports.

Why SCXML for Go?

• Cross-language portability -- the same SCXML file generates C++, Kotlin, Rust, and Go code. Useful for projects with multi-language codebases or microservice architectures.
• Visual tooling -- SCXML can be visualized, simulated, and validated with standard tools. SCE includes a browser-based visualizer.
• Formal specification -- W3C SCXML defines precise semantics for state entry/exit order, event priority, conflict resolution, and parallel state synchronization. No ambiguity.
• Type-safe generics -- generated code uses Go 1.22+ generics with comparable constraints, enabling compile-time type checking for state and event types.
• No CGo -- the entire stack is pure Go, making it easy to cross-compile and deploy anywhere Go runs.

Comparison with Go State Machine Libraries

Getting Started

# Clone the repository
git clone --recursive https://github.com/newmassrael/scxml-core-engine.git
cd scxml-core-engine

# Generate Go state machine from SCXML
sce-codegen generate --scxml your_machine.scxml --language go --output-dir ./generated/

# Run the Go W3C test suite
cd sce-go-tests && go test ./...

The Go runtime (sce-go-runtime/) provides the Engine[S, E] type and StatePolicy[S, E] interface. Test infrastructure is in sce-go-tests/. The code generator produces standalone Go files that depend only on the runtime module.