HSTsou / kstatemachine

KStateMachine is a Kotlin DSL library for creating state machines and hierarchical state machines (statecharts).

KStateMachine is a Kotlin DSL library for creating state machines and hierarchical state machines (statecharts).

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
• 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

Quick start sample (finishing traffic light)

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)
}

Samples

• Simple Android 2D shooter game sample

  The library itself does not depend on Android.

  

• Transition on FinishedEvent sample

• Undo transition sample

• 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

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.

Licensed under permissive Boost Software License

Thanks to supporters