README.md

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

Loading

// 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 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.

🗺️ Roadmap

• Make publication about using state machines along with MVI
• Create Intellij IDEA Plugin for state machine visualization and edition

🏅 Thanks to supporters

🖋️ License

Licensed under permissive Boost Software License