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.

SEE WIKI PAGE FOR MORE INFO

Quick 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.

  

• PlantUML nested states export sample

• Inherit transitions by grouping states sample

• Minimal sealed classes sample

• Minimal syntax sample

• Guarded transition sample

• Cross level transition sample

• Typesafe transition sample

• Complex syntax sample shows many syntax variants and library possibilities, so it looks messy

Install

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.

Licensed under the Boost Software License