KStateMachine **A powerful Kotlin Multiplatform state machine library with clean DSL syntax** **and first-class Kotlin Coroutines support** --- [![Build](https://github.com/KStateMachine/kstatemachine/workflows/Build%20and%20test%20with%20Gradle/badge.svg)](https://github.com/KStateMachine/kstatemachine/actions) [![codecov](https://codecov.io/gh/nsk90/kstatemachine/branch/master/graph/badge.svg?token=IR2JR43FOZ)](https://codecov.io/gh/nsk90/kstatemachine) [![Maven Central](https://img.shields.io/maven-central/v/io.github.nsk90/kstatemachine?logo=sonatype)](https://central.sonatype.com/artifact/io.github.nsk90/kstatemachine) [![JitPack](https://img.shields.io/jitpack/version/io.github.nsk90/kstatemachine?style=flat&logo=jitpack&color=brgreen)](https://jitpack.io/#nsk90/kstatemachine) [![Multiplatform](https://img.shields.io/badge/multiplatform-jvm%20%7C%20android%20%7C%20ios%20%7C%20native%20%7C%20js%20%7C%20wasm-brightgreen)](https://kstatemachine.github.io/kstatemachine/#multiplatform) [![JetBrains Marketplace](https://img.shields.io/jetbrains/plugin/v/32202-kstatemachine-visual?label=IntelliJ%20Plugin&logo=jetbrains)](https://plugins.jetbrains.com/plugin/32202-kstatemachine-visual/) [![Open Collective](https://img.shields.io/badge/open%20collective-kstatemachine-lightblue?logo=opencollective)](https://opencollective.com/kstatemachine) [![Mentioned in Awesome Kotlin](https://awesome.re/mentioned-badge.svg)](https://github.com/KotlinBy/awesome-kotlin) [![Android Arsenal](https://img.shields.io/badge/Android%20Arsenal-kstatemachine-green.svg?style=flat)](https://android-arsenal.com/details/1/8276) [![Slack](https://img.shields.io/badge/slack-kstatemachine-purple?logo=slack)](https://kotlinlang.slack.com/archives/C07DVAEKLM8) [![Share on X](https://img.shields.io/badge/twitter-share-white?logo=x)](https://twitter.com/intent/tweet?text=I%20like%20KStateMachine%20library%20%0A%0Ahttps%3A%2F%2Fgithub.com%2Fkstatemachine%2Fkstatemachine&hashtags=kstatemachine,kotlin,opensource) [![Share on Reddit](https://img.shields.io/badge/reddit-share-red?logo=reddit)](https://www.reddit.com/submit?url=https%3A%2F%2Fgithub.com%2Fkstatemachine%2Fkstatemachine&title=I%20like%20KStateMachine%20library) --- [πŸ“– Documentation](https://kstatemachine.github.io/kstatemachine)  |  [πŸ“š KDoc](https://kstatemachine.github.io/kstatemachine/kdoc/index.html)  |  [πŸ”Œ IntelliJ Plugin](#-intellij-idea-plugin)  |  [πŸš€ Quick Start](#-quick-start)  |  [πŸ§ͺ Samples](#-samples)  |  [πŸ’Ύ Install](#-install)  |  [πŸ’¬ Discussions](https://github.com/kstatemachine/kstatemachine/discussions)  |  [❀️ Sponsors](#-sponsors)
--- ## What is KStateMachine? **KStateMachine** lets you model complex application logic as a [finite state machine](https://en.wikipedia.org/wiki/Finite-state_machine) or [statechart](https://www.sciencedirect.com/science/article/pii/0167642387900359/pdf) using an expressive Kotlin DSL. It runs on every Kotlin Multiplatform target, integrates seamlessly with Kotlin Coroutines, and has **zero mandatory dependencies**. --- ## πŸš€ Quick Start ### Animated traffic light
Animated UML statechart β€” traffic light state machine
```kotlin // Events object SwitchEvent : Event // States sealed class States : DefaultState() { object RedState : States() object YellowState : States() object GreenState : States(), FinalState // machine stops here } fun main() = runBlocking { val machine = createStateMachine(scope = this) { addInitialState(RedState) { onEntry { println("πŸ”΄ Red β€” stop!") } onExit { println(" leaving red") } transition { targetState = YellowState onTriggered { println(" β†’ switching…") } } } addState(YellowState) { onEntry { println("🟑 Yellow β€” get ready") } transition(targetState = GreenState) } addFinalState(GreenState) { onEntry { println("🟒 Green β€” go!") } } onFinished { println("βœ… Done") } } machine.processEvent(SwitchEvent) // Red β†’ Yellow machine.processEvent(SwitchEvent) // Yellow β†’ Green (finished) } ``` ### Output ``` πŸ”΄ Red β€” stop! β†’ switching… leaving red 🟑 Yellow β€” get ready 🟒 Green β€” go! βœ… Done ``` --- ## ✨ Key Features **Integration** | Feature | Description | |------------------------------------------------------------------------------------------------|--------------------------------------------------------------| | [Kotlin DSL](https://kotlinlang.org/docs/type-safe-builders.html) | Declarative, readable structure; plain API also available | | [Kotlin Coroutines](https://kstatemachine.github.io/kstatemachine/pages/multithreading.html) | Suspending functions in listeners and guards; fully optional | | [Kotlin Multiplatform](https://kstatemachine.github.io/kstatemachine/pages/multiplatform.html) | JVM, Android, iOS, JS, Wasm, Native | | Zero dependencies | Core artifact depends only on the Kotlin stdlib | **State management** | Feature | Description | |-------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Event-based](https://kstatemachine.github.io/kstatemachine/pages/events.html) | Transitions fire in response to events | | [Reactive listeners](https://kstatemachine.github.io/kstatemachine/pages/states/states.html#listen-states) | Observe machines, states, state groups, and transitions | | [Guarded & conditional transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html#guarded-transitions) | Dynamic target state computed at runtime | | [Nested states](https://kstatemachine.github.io/kstatemachine/pages/states/states.html#nested-states) | Full statechart hierarchy with [cross-level transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html#cross-level-transitions) | | [Composed state machines](https://kstatemachine.github.io/kstatemachine/pages/states/states.html#composed-nested-state-machines) | Embed one machine as a child state of another | | [Pseudo states](https://kstatemachine.github.io/kstatemachine/pages/states/pseudo_states.html) | History, redirect, and other behavioural helpers | | [Typesafe transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/typesafe_transitions.html) | Carry typed data from event to target state | | [Parallel states](https://kstatemachine.github.io/kstatemachine/pages/states.html#parallel-states) | Run orthogonal regions simultaneously | | [Fork & Join](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html#synchronizing-parallel-regions-join) | Synchronize concurrent orthogonal regions (UML fork/join pseudo-states) | | [Undo transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html#undo-transitions) | Navigate back like a stack-based FSM | **Tooling** | Feature | Description | |-------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| | [IntelliJ Plugin](https://kstatemachine.github.io/kstatemachine/pages/plugin.html) | Visualise, navigate, and export state machines directly from your IDE β€” no runtime needed | | [Export](https://kstatemachine.github.io/kstatemachine/pages/export.html) | Generate [PlantUML](https://plantuml.com/) or [Mermaid](https://mermaid.js.org/) diagrams from your machine definition | | [Persist & restore](https://kstatemachine.github.io/kstatemachine/pages/persistence.html) | Two strategies: **event recording** (full replay) or **state snapshot** (`captureSavedStateConfig`) β€” both serialisable via `kotlinx.serialization` | | [Testing helpers](https://kstatemachine.github.io/kstatemachine/pages/testing.html) | `startFrom(state)` bypasses normal init, enabling focused unit tests | | [Library comparison](https://kstatemachine.github.io/kstatemachine/pages/comparison.html) | Side-by-side feature matrix vs FlowRedux, Tinder StateMachine, and Spring State Machine | --- ## πŸ”Œ IntelliJ IDEA Plugin **[KStateMachine Visual](https://plugins.jetbrains.com/plugin/32202-kstatemachine-visual/)** is an IntelliJ IDEA plugin that visualizes and navigates your state machines straight from Kotlin source β€” no runtime required. - **Tree view** with specialized icons for every state type (initial, final, choice, history, data, parallel) - **Bidirectional navigation** between the editor and the tree view - **Live PlantUML diagram** β€” rendered inline with debounced real-time updates as you type (no Graphviz needed) - **Export** as SVG or raw PlantUML source - **Static analysis** β€” resolves the full DSL tree including states inside conditional branches that runtime export misses **Install:** `Settings β†’ Plugins β†’ Marketplace` β†’ search **KStateMachine Visual** See the [plugin documentation page](https://kstatemachine.github.io/kstatemachine/pages/plugin.html) for the full feature reference and manual install instructions. --- ## πŸ“„ Documentation > [!IMPORTANT] > Full documentation lives at **[kstatemachine.github.io/kstatemachine](https://kstatemachine.github.io/kstatemachine)** > KDoc for every class: **[kstatemachine.github.io/kstatemachine/kdoc](https://kstatemachine.github.io/kstatemachine/kdoc/index.html)** --- ## ❀️ Sponsors If KStateMachine saves you time, please consider supporting the project: - ⭐ **Star this repo** β€” it helps others discover it - ❀️ **[GitHub Sponsors](https://github.com/sponsors/nsk90)** β€” one-time or recurring donations - πŸ’› **[Open Collective](https://opencollective.com/kstatemachine)** β€” transparent team funding --- ## πŸ§ͺ Samples Full app samples and 20+ runnable focused code samples are listed on the **[Samples page](https://kstatemachine.github.io/kstatemachine/pages/samples.html)** in the documentation.

Android sample app

--- ## ✍️ Publications * [Integrating State Machines with MVI Architecture in Kotlin for Reactive Android Apps](https://medium.com/p/7327c3ff34f3) --- ## πŸ’Ύ Install KStateMachine is published to **Maven Central** and **JitPack**. ```kotlin dependencies { // Core (zero dependencies) implementation("io.github.nsk90:kstatemachine:") // + Kotlin Coroutines integration (optional) implementation("io.github.nsk90:kstatemachine-coroutines:") // + kotlinx.serialization for state persistence (optional) implementation("io.github.nsk90:kstatemachine-serialization:") } ``` Replace `` with the current version shown in the Maven Central badge above. See the [full install guide](https://kstatemachine.github.io/kstatemachine/pages/install.html) for Gradle Kotlin DSL, Groovy DSL, and JitPack variants. --- ## πŸ—οΈ Build ```bash ./gradlew build # build all modules ./gradlew :tests:jvmTest # run all tests (JVM target) ``` Or open in IntelliJ IDEA and run from there. --- ## 🀝 Contribution The library is in **stable** phase β€” but feature proposals and pull requests are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before submitting. --- ## πŸ™‹ Support | Channel | Best for | |----------------------------------------------------------------------------------|--------------------------------| | [Slack `#kstatemachine`](https://kotlinlang.slack.com/archives/C07DVAEKLM8) | Questions & discussions | | [GitHub Discussions](https://github.com/kstatemachine/kstatemachine/discussions) | Questions & longer discussions | | [GitHub Issues](https://github.com/KStateMachine/kstatemachine/issues) | Bug reports & feature requests | When asking on other platforms, include a link to this repo or use the `#kstatemachine` tag. --- ## πŸ—ΊοΈ Roadmap - [ ] IntelliJ IDEA plugin β€” state machine visualization and editing --- ## πŸ… Thanks to supporters [![Stargazers](https://reporoster.com/stars/dark/kstatemachine/kstatemachine)](https://github.com/kstatemachine/kstatemachine/stargazers) [![Forkers](https://reporoster.com/forks/dark/kstatemachine/kstatemachine)](https://github.com/kstatemachine/kstatemachine/network/members) --- ## πŸ–‹οΈ License Licensed under the permissive [Boost Software License](./LICENSE).