Repository files navigation

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

KStateMachine is a powerfulKotlin Multiplatform library with clean DSL syntax for creatingcomplexstate machinesandstatecharts driven byKotlin Coroutines.

• Kotlin DSL syntax -declarative and clear state machine structure. Using without DSL is also possible.
• Kotlin Coroutinessupport -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 librariesor Android SDK.

• Event based -transitions are performed byprocessingincoming events

• Reactive - listen formachine, states,state groups andtransitions

• GuardedandConditional transitions - dynamictargetstate which is calculated in a moment of event processing depending on application business logic

• Nested states - buildhierarchical state machines(statecharts)withcross-level transitionssupport

• Composed (nested) state machines - use state machines as atomic child states

• Pseudo states for additionallogic in machinebehaviour

• Typesafe transitions - pass data intypesafe wayfrom event to state

• Parallel states - avoid acombinatorialexplosion ofstates

• Undo transitions - navigate back to previousstate (like stack based FSMs do)

• Optional argument passing forevents andtransitions

• Export state machine structuretoPlantUML andMermaid diagrams

• Persist (serialize) state machine'sactiveconfiguration and restore it later. Built-inkotlinx.serialization support.

• Testable - run state machine from specifiedstate and enable internal logging

• Well tested - all features are coveredby tests

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

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 Eventsobject SwitchEvent : Event// define your States as classes or objectssealedclassStates :DefaultState() {object RedState : States()object YellowState : States()// machine finishes when enters [FinalState]object GreenState : States(), FinalState}funmain()= runBlocking {// create state machine and configure its structure in a setup blockval 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 listenersval 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]}

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

• 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 sampleshows many syntax variants and library possibilities, so it looks messy

KStateMachine is available onMaven Central andJitPack repositories.

Seeinstall section in the docs for details.

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>")}

Run./gradlew build or build withIntellij IDEA.

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

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

• Slack channel orGitHub 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 alink to thisGitHub project or using#kstatemachine tag.

• CreateIntellij IDEA Plugin for state machine visualization and edition

Licensed under permissiveBoost Software License