KStateMachine

Documentation | KDoc | Sponsors | Quick start | Samples | Install | Contribution | Support | Roadmap | License | Discussions

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.

  <p align="center"> <img src="https://github.com/kstatemachine/android-kstatemachine-sample/blob/main/images/android-app-sample.gif" alt="Android sample app" width="30%" height="30%"/> </p>

• Compose 2D shooter game sample

• Finished state sample

• Transition on FinishedEvent sample

• FinishedEvent using with DataState sample

• [Undo transition sample](./samples/src/commonMain/kotlin/ru/nsk/samples/UndoTransitionSamp