KStateMachine

KStateMachine is a Kotlin DSL library for creating state machines and statecharts.

Overview

Integration features are:

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, it 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
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
Logging - useful for debugging
Testable - run state machine from specified state
Well tested - all features are covered by tests

Important

SEE FULL DOCUMENTATION HERE

Sponsors ❤

I highly appreciate that you donate or become a sponsor to support the project. Use ❤️ github-sponsors button to see supported methods and push the ⭐ star-button if you like this project.

Quick start sample

Finishing traffic light

stateDiagram-v2
    direction LR
    [*] --> GreenState
    GreenState --> YellowState: SwitchEvent
    YellowState --> RedState: SwitchEvent
    RedState --> [*]

object SwitchEvent : Event

sealed class States : DefaultState() {
    object GreenState : States()
    object YellowState : States()
    object RedState : States(), FinalState // Machine finishes when enters final state
}

fun main() = runBlocking {
    // Create state machine and configure its states in a setup block
    val machine = createStateMachine(this) {
        addInitialState(GreenState) {
            // Add state listeners
            onEntry { println("Enter green") }
            onExit { println("Exit green") }

            // Setup transition
            transition<SwitchEvent> {
                targetState = YellowState
                // Add transition listener
                onTriggered { println("Transition triggered") }
            }
        }

        addState(YellowState) {
            transition<SwitchEvent>(targetState = RedState)
        }

        addFinalState(RedState)

        onFinished { println("Finished") }
    }

    // Now we can process events
    machine.processEvent(SwitchEvent)
    machine.processEvent(SwitchEvent)
}

Samples

Simple Android 2D shooter game sample

The library itself does not depend on Android.
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
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>")
}

Build

Run ./gradlew build or build with Intellij IDEA.

Contribution

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

Thanks to supporters

License

Licensed under permissive Boost Software License

belinwu/kstatemachine