KStateMachine
KStateMachine is a Kotlin DSL library for creating finite state machines (FSM) and hierarchical state machines (HSM).
Overview
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
- Event based - transitions are performed by processing incoming events
- Listeners for machine, states and transitions, all 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
- Typesafe transitions to pass data in typesafe way from event to state
- Parallel states to avoid a combinatorial explosion of states
- Argument passing for events and transitions
- Export state machine structure to PlantUML;
- Built-in logging support
The library is currently in a development phase. You are welcome to propose useful features.
WIKI PAGE FOR MORE INFO
SEEQuick start sample (finishing traffic light)
sealed class Events {
object NextEvent : Event
}
sealed class States {
object GreenState : DefaultState()
object YellowState : DefaultState()
object RedState : DefaultFinalState() // 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<NextEvent> {
targetState = YellowState
// Add transition listener
onTriggered { println("Transition triggered") }
}
}
addState(YellowState) {
transition<NextEvent>(targetState = RedState)
}
addFinalState(RedState)
onFinished { println("Finished") }
}
// Now we can process events
machine.processEvent(NextEvent)
machine.processEvent(NextEvent)
}
Samples
-
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
Install
KStateMachine is available on Maven Central and JitPack repositories.
Maven Central
Add the dependency:
dependencies {
implementation 'io.github.nsk90:kstatemachine:<Tag>'
}
Where <Tag>
is a library version.
JitPack
Add the JitPack repository to your build file. Add it in your
root build.gradle
at the end of repositories:
allprojects {
repositories {
// ...
maven { url 'https://jitpack.io' }
}
}
Add the dependency:
dependencies {
implementation 'com.github.nsk90:kstatemachine:<Tag>'
}
Where <Tag>
is a library version.
Build
Run ./gradlew build
or build with Intellij IDEA
.
To run tests from IDE download official Kotest plugin.