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.
[!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:
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]
}
Simple Android 2D shooter game sample
The library itself does not depend on Android.
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>")
}
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.
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.
MVI
Intellij IDEA Plugin
for state machine visualization and editionkotlinx.serialization
Compose
sampleLicensed under permissive Boost Software License