KStateMachine Visual

The official IntelliJ Platform plugin for the KStateMachine Kotlin library Visualize and navigate state machines straight from your source — no runtime needed

---

---

💾 Install  |  ✨ Features  |  🚀 How it works  |  🗺️ Roadmap  |  🏗️ Build  |  🤝 Contributing  |  💬 Discussions

---

What is KStateMachine Visual?

KStateMachine Visual is the official IDE plugin for the KStateMachine Kotlin library.

It statically analyzes your Kotlin source — including if / when branches that the runtime PlantUML export cannot see — and displays every state machine declared in the currently open file as both:

• a navigable tree of states, substates and transitions, and
• a rendered UML state diagram.

Click any node in the tree to jump to its declaration in the editor. Move the caret in the editor and the matching tree node highlights automatically. Gutter icons next to createStateMachine, state and transition calls give one-click access to the same view. The diagram updates live as you type and can be copied as PlantUML source or exported as PNG / SVG.

Note

The plugin is in early development. Feedback on real-world DSL usage is especially welcome — open an issue or drop into the Slack channel.

---

✨ Features

Capability	KStateMachine Visual
Static parsing of nested DSL — arbitrary depth	✅
Detects states declared inside if / when branches	✅
Tree view with icons per state kind (initial, final, choice, history, data, …)	✅
Bidirectional editor ↔ tree navigation	✅
Rendered PlantUML diagram in-panel (Smetana layout — no Graphviz needed)	✅
PlantUML source view alongside the diagram	✅
Transition arrows resolved from targetState = …	✅
Editor gutter icons next to KStateMachine DSL calls	✅
Live, debounced refresh while typing	✅
Copy PlantUML source / Export diagram as PNG or SVG	✅

---

🚀 How it works

Open any Kotlin file containing a KStateMachine declaration. The KStateMachine tool window shows two tabs that stay in sync with your cursor.

Structure tab — a tree of every machine in the file:

StateMachine traffic  (4 states, 3 transitions)
├─ red  (initial)  (1 transition)
│   ├─ blinking
│   └─ on SwitchEvent  → yellow
├─ yellow  (1 transition)
│   └─ on SwitchEvent  → green
└─ green  (final)

Diagram tab — a rendered PlantUML state chart with the generated PlantUML source shown beneath it in a resizable split.

The parser walks the PSI tree of state { … } and transition { … } lambdas, attributing every nested call to its lexical parent — which is why if / when branches that the runtime PlantUML export can't see are still captured here.

---

💾 Install

From JetBrains Marketplace (once published)

Settings/Preferences → Plugins → Marketplace → search "KStateMachine Visual" → Install

Or visit the Marketplace page and click Install to ….

Manual install from a downloaded archive

1. Grab the latest .zip from the GitHub Releases page, or from the Marketplace versions page.
2. In your IDE: Settings/Preferences → Plugins → ⚙️ → Install plugin from disk…

Compatibility: IntelliJ Platform 2023.3 – 2024.2 (Community or Ultimate), plus other JetBrains IDEs in the same range. Requires the bundled Kotlin and Java plugins.

---

🗺️ Roadmap

Shipped

• Recursive parsing of nested DSL — including states inside if / when branches
• Tree view of state machines in the current file, with icons per state kind
• Bidirectional editor ↔ tree navigation — click a node to jump; move the caret to highlight
• PlantUML state diagram rendered in-panel (Smetana layout, no Graphviz required)
• Transition arrows resolved from targetState = …
• Editor gutter icons next to KStateMachine DSL calls
• Live, debounced refresh while typing
• Copy PlantUML source / Export diagram as PNG or SVG

Planned

• Project-wide tab listing every machine across the project
• Rename refactoring of state names via the tree
• "Find Usages" for states (where is targetState = redState referenced?)
• Inspection: detect unreachable states and missing initial states
• Open generated PlantUML in browser (kroki.io / plantuml.com)
• Live preview balloon inside the editor, anchored to the machine

---

🏗️ Build from source

./gradlew buildPlugin           # produces a marketplace-ready ZIP in build/distributions/
./gradlew runIde                # launch a sandbox IDE with the plugin loaded
./gradlew verifyPlugin          # check the plugin against IntelliJ guidelines

Or open the project in IntelliJ IDEA and run the same tasks from the Gradle tool window.

---

🤝 Contributing

Bug reports, feature requests, and pull requests are welcome. The plugin is in early development — issues that include a minimal reproducible KStateMachine DSL snippet are the most actionable.

---

🙋 Support

Channel	Best for
Slack #kstatemachine	Quick questions, discussion
GitHub Issues	Bug reports & feature requests
GitHub Discussions	Longer-form questions
KStateMachine library repo	Questions about the library itself

---

Maintainer checklist (template setup todos)

• Create a new IntelliJ Platform Plugin Template project.
• Get familiar with the template documentation.
• Adjust the pluginGroup and pluginName, as well as the id and sources package.
• Adjust the plugin description in README (see Tips)
• Review the Legal Agreements.
• Publish a plugin manually for the first time.
• Set the MARKETPLACE_ID in the badges above. You can obtain it once the plugin is published to JetBrains Marketplace.
• Set the Plugin Signing related secrets.
• Set the Deployment Token.
• Click Watch on the IntelliJ Platform Plugin Template repo to get release notifications.

---

Built on the IntelliJ Platform Plugin Template.