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.
- 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.
-
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.serializationsupport. -
Testable - run state machine from specified state and enable internal logging
-
Well tested - all features are covered by tests
Important
- See full documentation on website
- KDoc for classes
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 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]
}-
Android 2D shooter game sample
The library itself does not depend on Android.
-
Complex syntax sample shows many syntax variants and library possibilities, so it looks messy
KStateMachine is available on Maven Central and JitPack repositories.
See install 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 with Intellij IDEA.
The library is in development phase. You are welcome to propose useful features and contribute to the project. See CONTRIBUTING file.
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.
- Make publication about using state machines along with
MVI - Create
Intellij IDEA Pluginfor state machine visualization and edition
Licensed under permissive Boost Software License
