KStateMachine is a Kotlin DSL library for creating state machines and hierarchical state machines (statecharts).
Main features are:
- Zero dependency. It is written in pure Kotlin, it does not depend on any other libraries or Android SDK
- Kotlin DSL syntax for defining state machine structure. Using without DSL is also possible
- Backward compatible till Kotlin 1.4
- Event based - transitions are performed by processing incoming events
- Listeners for machine, states, state groups and transitions. Listener callbacks are shipped with information about current transition
- Guarded and Conditional transitions with dynamic target state which is calculated in a moment of event processing depending on application business logic
- Nested states - hierarchical state machines (HSMs) 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 to pass data in typesafe way from event to state
- Parallel states to avoid a combinatorial explosion of states
- Undo transitions for navigating back to previous state
- Argument passing for events and transitions
- Pending events support
- Export state machine structure to PlantUML;
- Built-in logging support
- Testable - you can run state machine from specified state
- Well tested. All features are covered by tests.
The library is currently in a development phase. You are welcome to propose useful features.
Don't forget to push the ⭐ if you like this project.
SEE FULL DOCUMENTATION HERE
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() {
// Create state machine and configure its states in a setup block
val machine = createStateMachine {
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.
Add the dependency:
dependencies {
implementation 'io.github.nsk90:kstatemachine:<Tag>'
}
dependencies {
implementation("io.github.nsk90:kstatemachine:<Tag>")
}
Where <Tag>
is a library version.
Add the JitPack repository to your build file. Add it in your
root build.gradle
at the end of repositories:
// groovy
allprojects {
repositories {
// ...
maven { url 'https://jitpack.io' }
}
}
// kotlin
repositories {
// ...
maven { url = uri("https://jitpack.io") }
}
Add the dependency:
// groovy
dependencies {
implementation 'com.github.nsk90:kstatemachine:<Tag>'
}
// kotlin
dependencies {
implementation("com.github.nsk90:kstatemachine:<Tag>")
}
Where <Tag>
is a library version.
Run ./gradlew build
or build with Intellij IDEA
.
To run tests from IDE download official Kotest plugin.