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]
}

🧪 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 MetaInfo 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.

KStateMachine / kstatemachine

readme