Documentation | Quick start | Samples | Install | License | Discussions
KStateMachine is a Kotlin DSL library for creating state machines and statecharts.
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
- Logging - useful for debugging
- Testable - run state machine from specified state
- Well tested - all features are covered by tests
Important
SEE FULL DOCUMENTATION HERE
Note
The library is in a development phase. You are welcome to propose useful features, or contribute to the project. Don't forget to push the ⭐ if you like this project.
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)
}-
Simple 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.
The library consists of 2 components:
kstatemachine- (mandatory) state machine implementation (depends only on Kotlin Standard library)kstatemachine-coroutines- (optional) add-ons for working with coroutines (depends on Kotlin Coroutines library)
Please note that starting from v0.22.0 the library switched to Kotlin Multiplatform and artifact naming has changed.
Add dependencies:
// kotlin
dependencies {
// multiplatform artifacts (starting from 0.22.0)
implementation("io.github.nsk90:kstatemachine:<Tag>")
implementation("io.github.nsk90:kstatemachine-coroutines:<Tag>")
// or JVM/Android artifacts (starting from 0.22.0)
implementation("io.github.nsk90:kstatemachine-jvm:<Tag>")
implementation("io.github.nsk90:kstatemachine-coroutines-jvm:<Tag>")
// or iOS artifacts (starting from 0.22.1)
implementation("io.github.nsk90:kstatemachine-iosarm64:<Tag>")
implementation("io.github.nsk90:kstatemachine-coroutines-iosarm64:<Tag>")
implementation("io.github.nsk90:kstatemachine-iosx64:<Tag>")
implementation("io.github.nsk90:kstatemachine-coroutines-iosx64:<Tag>")
implementation("io.github.nsk90:kstatemachine-iossimulatorarm64:<Tag>")
implementation("io.github.nsk90:kstatemachine-coroutines-iossimulatorarm64:<Tag>")
}// groovy
dependencies {
// multiplatform artifacts
implementation 'io.github.nsk90:kstatemachine:<Tag>'
implementation 'io.github.nsk90:kstatemachine-coroutines:<Tag>' // optional
// etc..
}Where <Tag> is a library version.
You can see official docs about dependencies on multiplatform libraries
Currently, JitPack does not support Kotlin multiplatform artifacts.
So versions starting from 0.22.0 are not available there, use Maven Central instead.
Add the JitPack repository to your build file. Add it in your
root build.gradle at the end of repositories:
// kotlin
repositories {
// ...
maven { url = uri("https://jitpack.io") }
}// groovy
allprojects {
repositories {
// ...
maven { url 'https://jitpack.io' }
}
}Add dependencies:
// kotlin
dependencies {
implementation("com.github.nsk90:kstatemachine:<Tag>")
// note that group is different in second artifact, long group name also works for first artifact but not vise versa
// it is some strange JitPack behaviour
implementation("com.github.nsk90.kstatemachine:kstatemachine-coroutines:<Tag>") // optional
}// groovy
dependencies {
implementation 'com.github.nsk90:kstatemachine:<Tag>'
// note that group is different in second artifact, long group name also works for first artifact but not vise versa
// it is some strange JitPack behaviour
implementation 'com.github.nsk90.kstatemachine:kstatemachine-coroutines:<Tag>' // optional
}Where <Tag> is a library version.
Run ./gradlew build or build with Intellij IDEA.
To run tests from IDE download official Kotest plugin.
Licensed under permissive Boost Software License