README.md

June 15, 2026 · View on GitHub

A powerful Kotlin Multiplatform state machine library with clean DSL syntax
and first-class Kotlin Coroutines support

What is KStateMachine?

KStateMachine lets you model complex application logic as a finite state machine or statechart using an expressive Kotlin DSL. It runs on every Kotlin Multiplatform target, integrates seamlessly with Kotlin Coroutines, and has zero mandatory dependencies.

🚀 Quick Start

Animated traffic light

Animated UML statechart — traffic light state machine

// Events
object SwitchEvent : Event

// States
sealed class States : DefaultState() {
    object RedState : States()
    object YellowState : States()
    object GreenState : States(), FinalState  // machine stops here
}

fun main() = runBlocking {
    val machine = createStateMachine(scope = this) {
        addInitialState(RedState) {
            onEntry { println("🔴 Red — stop!") }
            onExit { println("   leaving red") }

            transition<SwitchEvent> {
                targetState = YellowState
                onTriggered { println("   → switching…") }
            }
        }

        addState(YellowState) {
            onEntry { println("🟡 Yellow — get ready") }
            transition<SwitchEvent>(targetState = GreenState)
        }

        addFinalState(GreenState) {
            onEntry { println("🟢 Green — go!") }
        }

        onFinished { println("✅ Done") }
    }

    machine.processEvent(SwitchEvent) // Red → Yellow
    machine.processEvent(SwitchEvent) // Yellow → Green (finished)
}

Output

🔴 Red — stop!
   → switching…
   leaving red
🟡 Yellow — get ready
🟢 Green — go!
✅ Done

✨ Key Features

Integration

Feature	Description
Kotlin DSL	Declarative, readable structure; plain API also available
Kotlin Coroutines	Suspending functions in listeners and guards; fully optional
Kotlin Multiplatform	JVM, Android, iOS, JS, Wasm, Native
Zero dependencies	Core artifact depends only on the Kotlin stdlib

State management

Feature	Description
Event-based	Transitions fire in response to events
Reactive listeners	Observe machines, states, state groups, and transitions
Guarded & conditional transitions	Dynamic target state computed at runtime
Nested states	Full statechart hierarchy with cross-level transitions
Composed state machines	Embed one machine as a child state of another
Pseudo states	History, redirect, and other behavioural helpers
Typesafe transitions	Carry typed data from event to target state
Parallel states	Run orthogonal regions simultaneously
Fork & Join	Synchronize concurrent orthogonal regions (UML fork/join pseudo-states)
Undo transitions	Navigate back like a stack-based FSM

Tooling

Feature	Description
IntelliJ Plugin	Visualise, navigate, and export state machines directly from your IDE — no runtime needed
Export	Generate PlantUML or Mermaid diagrams from your machine definition
Persist & restore	Two strategies: event recording (full replay) or state snapshot (`captureSavedStateConfig`) — both serialisable via `kotlinx.serialization`
Testing helpers	`startFrom(state)` bypasses normal init, enabling focused unit tests
Library comparison	Side-by-side feature matrix vs FlowRedux, Tinder StateMachine, and Spring State Machine

🔌 IntelliJ IDEA Plugin

KStateMachine Visual is an IntelliJ IDEA plugin that visualizes and navigates your state machines straight from Kotlin source — no runtime required.

Tree view with specialized icons for every state type (initial, final, choice, history, data, parallel)
Bidirectional navigation between the editor and the tree view
Live PlantUML diagram — rendered inline with debounced real-time updates as you type (no Graphviz needed)
Export as SVG or raw PlantUML source
Static analysis — resolves the full DSL tree including states inside conditional branches that runtime export misses

Install: Settings → Plugins → Marketplace → search KStateMachine Visual

See the plugin documentation page for the full feature reference and manual install instructions.

📄 Documentation

Important

Full documentation lives at kstatemachine.github.io/kstatemachine
KDoc for every class: kstatemachine.github.io/kstatemachine/kdoc

❤️ Sponsors

If KStateMachine saves you time, please consider supporting the project:

⭐ Star this repo — it helps others discover it
❤️ GitHub Sponsors — one-time or recurring donations
💛 Open Collective — transparent team funding

🧪 Samples

Full app samples and 20+ runnable focused code samples are listed on the Samples page in the documentation.

Android sample app

✍️ Publications

Integrating State Machines with MVI Architecture in Kotlin for Reactive Android Apps

💾 Install

KStateMachine is published to Maven Central and JitPack.

dependencies {
    // Core (zero dependencies)
    implementation("io.github.nsk90:kstatemachine:<Tag>")

    // + Kotlin Coroutines integration (optional)
    implementation("io.github.nsk90:kstatemachine-coroutines:<Tag>")

    // + kotlinx.serialization for state persistence (optional)
    implementation("io.github.nsk90:kstatemachine-serialization:<Tag>")
}

Replace <Tag> with the current version shown in the Maven Central badge above.
See the full install guide for Gradle Kotlin DSL, Groovy DSL, and JitPack variants.

🏗️ Build

./gradlew build          # build all modules
./gradlew :tests:jvmTest # run all tests (JVM target)

Or open in IntelliJ IDEA and run from there.

🤝 Contribution

The library is in stable phase — but feature proposals and pull requests are welcome!
Please read CONTRIBUTING.md before submitting.

🙋 Support

Channel	Best for
Slack `#kstatemachine`	Questions & discussions
GitHub Discussions	Questions & longer discussions
GitHub Issues	Bug reports & feature requests

When asking on other platforms, include a link to this repo or use the #kstatemachine tag.