KStateMachine

KStateMachine is a powerful Kotlin Multiplatform library with clean DSL syntax for creating
complex state machines
and statecharts driven by
Kotlin Coroutines.

🌏 Overview

📦 Integration features

Kotlin DSL syntax -
declarative and clear state machine structure. Using without DSL is also possible.
Kotlin Coroutines
support -
call suspendable functions within the library.
You can fully use KStateMachine without Kotlin Coroutines dependency if necessary.
Kotlin Multiplatform support
Zero dependency - it is written in pure Kotlin, main library artifact does not depend on any third party libraries
or Android SDK.

⚙️ State management features

Event based - transitions are performed by
processing
incoming events
Reactive - listen for
machine, states,
state groups and
transitions
Guarded
and Conditional transitions - dynamic
target
state which is calculated in a moment of event processing depending on application business logic
Nested states - build
hierarchical state machines
(statecharts)
with cross-level transitions
support
Composed (nested) state machines - use state machines as atomic child states
Pseudo states for additional
logic in machine
behaviour
Typesafe transitions - pass data in
typesafe way
from event to state
Parallel states - avoid a
combinatorial
explosion of
states
Undo transitions - navigate back to previous
state (like stack based FSMs do)
Optional argument passing for
events and
transitions
Export state machine structure
to PlantUML and Mermaid diagrams
Persist (serialize) state machine’s
active
configuration and restore it later. Built-in kotlinx.serialization support.
Testable - run state machine from specified
state and enable internal logging
Well tested - all features are covered
by tests

📄 Documentation

[!IMPORTANT]

See full documentation on website
KDoc for classes

❤️ Sponsors

I highly appreciate that you donate or become a sponsor to support the project.
If you find this project useful you can support it by:

Pushing the ⭐ star-button
Using ❤️github-sponsors button to see supported donation methods

🚀 Quick start sample

🚦Finishing traffic light

stateDiagram-v2
    direction TB
    classDef red fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:black
    classDef yellow fill:yellow,color:black,font-weight:bold,stroke-width:2px,stroke:black
    classDef green fill:green,color:white,font-weight:bold,stroke-width:2px,stroke:black
    [*] --> RedState
    RedState --> YellowState: SwitchEvent
    YellowState --> GreenState: SwitchEvent
    GreenState --> [*]
    class RedState red
    class YellowState yellow
    class GreenState green

// define your Events
object SwitchEvent : Event
// define your States as classes or objects
sealed class States : DefaultState() {
    object RedState : States()
    object YellowState : States()
    // machine finishes when enters [FinalState]
    object GreenState : States(), FinalState
}
fun main() = runBlocking {
    // create state machine and configure its structure in a setup block
    val machine = createStateMachine(scope = this) {
        addInitialState(RedState) {
            // add state listeners
            onEntry {
                println("Enter red")
                // you can call suspendable code if necessary
                delay(10)
            }
            onExit { println("Exit red") }
            // setup transition
            transition<SwitchEvent> {
                targetState = YellowState
                // add transition listener
                onTriggered { println("Transition triggered") }
            }
        }
        addState(YellowState) {
            transition<SwitchEvent>(targetState = GreenState)
        }
        addFinalState(GreenState)
        onFinished { println("Finished") }
    }
    // you can observe state machine changes using [Flow] along with simple listeners
    val statesFlow = machine.activeStatesFlow()
    // you can process events after state machine has been started even from listener callbacks
    machine.processEvent(SwitchEvent) // machine goes to [YellowState]
    machine.processEvent(SwitchEvent) // machine goes to [GreenState]
}

✍️ Publications

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

🧪 Samples

Android 2D shooter game sample

The library itself does not depend on Android.
Compose 2D shooter game sample
Finished state sample
Transition on FinishedEvent sample
FinishedEvent using with DataState sample
Undo transition sample
PlantUML nested states export sample
Mermaid nested states export sample
PlantUML with UmlMetaInfo export sample
PlantUML with ExportMetaInfo unsafe export sample
Inherit transitions by grouping states sample
Minimal sealed classes sample
Usage without Kotlin Coroutines sample
Minimal syntax sample
Guarded transition sample
Cross-level transition sample
Typesafe transition sample
Event recording sample
Complex syntax sample
shows many syntax variants and library possibilities, so it looks messy

💾 Install

KStateMachine is available on Maven Central and JitPack repositories.

See install section in the docs for details.

Maven Central

dependencies {
    // multiplatform artifacts, where <Tag> is a library version.
    implementation("io.github.nsk90:kstatemachine:<Tag>")
    implementation("io.github.nsk90:kstatemachine-coroutines:<Tag>")
    implementation("io.github.nsk90:kstatemachine-serialization:<Tag>")
}

🏗️ Build

Run ./gradlew build or build with Intellij IDEA.

🤝 Contribution

The library is in development phase. You are welcome to propose useful features and contribute to the project.
See CONTRIBUTING file.

🙋 Support

I am open to answer you questions and feature requests. Fill free to use any of communication channels to
give your feedback.

Slack channel or
GitHub discussions - best for questions and discussions
GitHub issues - best for bugs and feature requests

If you use some other platforms to ask questions or mention the library, I recommend adding a link to this
GitHub project or using #kstatemachine tag.