{"id":15693836,"url":"https://github.com/finger563/webgme-hfsm","last_synced_at":"2025-10-10T21:14:00.577Z","repository":{"id":41094889,"uuid":"87819695","full_name":"finger563/webgme-hfsm","owner":"finger563","description":"Metamodel, visualization, simulation, and code generation for Hierarchical Finite State Machines (HFSMs) following the UML State Machine spec.","archived":false,"fork":false,"pushed_at":"2025-02-22T23:35:14.000Z","size":40267,"stargazers_count":49,"open_issues_count":7,"forks_count":17,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-30T15:08:09.617Z","etag":null,"topics":["code-generators","fsm","hfsm","state-machine","uml","uml-state-machine","webgme","webgme-domain"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/finger563.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["finger563"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"custom":null}},"created_at":"2017-04-10T14:20:31.000Z","updated_at":"2025-02-22T23:35:12.000Z","dependencies_parsed_at":"2024-02-28T06:30:38.973Z","dependency_job_id":"309827e0-4252-4721-b3ad-8ce53ceeda8e","html_url":"https://github.com/finger563/webgme-hfsm","commit_stats":{"total_commits":735,"total_committers":8,"mean_commits":91.875,"dds":0.07346938775510203,"last_synced_commit":"30f88292837a7477c305fe01fe8070e071482896"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finger563%2Fwebgme-hfsm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finger563%2Fwebgme-hfsm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finger563%2Fwebgme-hfsm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finger563%2Fwebgme-hfsm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/finger563","download_url":"https://codeload.github.com/finger563/webgme-hfsm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247517914,"owners_count":20951719,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-generators","fsm","hfsm","state-machine","uml","uml-state-machine","webgme","webgme-domain"],"created_at":"2024-10-03T18:49:32.324Z","updated_at":"2025-10-10T21:13:55.529Z","avatar_url":"https://github.com/finger563.png","language":"C++","funding_links":["https://github.com/sponsors/finger563","https://paypal.me/finger563"],"categories":[],"sub_categories":[],"readme":"# WebGME HFSM\n\n[![license](https://img.shields.io/github/license/mashape/apistatus.svg?maxAge=2592000)](https://opensource.org/licenses/MIT)\n[![Documentation](https://img.shields.io/badge/documentation-wiki-blue.svg?style=flat-square)](https://github.com/finger563/webgme-hfsm/wiki)\n[![npm](https://img.shields.io/npm/v/webgme-hfsm.svg)](https://www.npmjs.com/package/webgme-hfsm)\n[![npm](https://img.shields.io/npm/dm/webgme-hfsm.svg)](https://www.npmjs.com/package/webgme-hfsm)\n[![npm](https://img.shields.io/npm/dt/webgme-hfsm.svg)](https://www.npmjs.com/package/webgme-hfsm)\n\n[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://paypal.me/finger563)\n\nWebGME App for creating Executable Hierarchical Finite State Machines\n(HFSMs). Contains metamodel, visualization, simulation, and code\ngeneration for Hierarchical Finite State Machines (HFSMs) following\nthe UML State Machine specification, see [Wikipedia UML State Machine](https://en.wikipedia.org/wiki/UML_state_machine), [another reference](https://www.uml-diagrams.org/state-machine-diagrams.html), and [the UML specification](http://www.omg.org/spec/UML/).\n\n**Please see the [WIKI](https://github.com/finger563/webgme-hfsm/wiki) for further information, including links to relevant Youtube Videos and specific pages about development process and such.**\n\n\u003c!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc --\u003e\n**Table of Contents**\n\n- [Features](#features)\n- [Description](#description)\n- [Getting Started](#getting-started)\n    - [Setting up the WebGME-HFSM Server](#setting-up-the-webgme-hfsm-server)\n    - [Creating a HFSM](#creating-a-hfsm)\n    - [Simulating a HFSM](#simulating-a-hfsm)\n    - [Code Generation](#code-generation)\n        - [Test Bench Code](#test-bench-code)\n- [Examples](#examples)\n\n\u003c!-- markdown-toc end --\u003e\n\n## Features\n\n* Complete modeling of State Machines following the UML specification\n  including:\n  * States with Hierarchy\n  * Events\n  * Internal Transitions\n  * External Transitions\n  * Local Transitions\n  * Choice Pseudostates\n  * Deep History Pseudostates\n  * Shallow History Pseudostates\n  * Initial States\n  * End States\n* **Interactive model creation**\n  * Positions of states are saved\n  * Code can be edited directly in the model\n  * Simulator automatically updates as model changes\n  * Can use multi-select to move groups of states or to edit attributes of multiple objects (e.g. transition events)\n  * Can auto-select all transitions by `Event`\n  * Can zoom / pan the model to focus on a specific context\n* In-model **interactive simulation** of the HFSM\n  * Highlighting of execution pathways during event handling\n  * Can disable / enable transitions\n  * User can select which guards are true when transitions have guards\n  * Currently active state tree branch shown including all event actions\n  * Simulator informs the user if the model is not well formed\n* In-model **collaborative code attribute editing** for the HFSM (using [the CodeEditor](https://github.com/finger563/webgme-codeeditor))\n* Model transformation plugin to produce executable **C++** code from\n  the HFSM (*with more languages coming soon*!)\n  * Disabled transitions are not generated\n  * Model is checked before being generated\n\n## Description\n\nThis repository contains the plugins, decorators, and visualizers (all\nof which are WebGME Components) and the base and example seeds for\ncreating HFSMs with embedded c/c++ code in each state. The WebGME app\nutilizes the [CodeEditor](https://github.com/finger563/webgme-codeeditor) to allow users to edit the code for the\nmodel as if it were part of an IDE.\n\nTogether these components and (meta-)modeling environment make up the\n*State Machine Domain* for WebGME.\n\nThe [Base seed](./src/seeds/base.webgmex) contains just the `Meta`\ndefinitions for the projects and HFSMs following the UML State Diagram\nspecification and the [Examples Seed](./src/seeds/examples.webgmex)\ncontains a project with three different HFSMs: *simple*, *medium*, and\n*complex*.\n\nHFSMs are trees, where a state may have zero or more substates.\n \nIn this modeling paradigm, `Projects` can contain any number of `State\nMachines`.\n\nState Machines have the following attributes:\n\n* `Includes` : include statements for the HFSM, will be at the top of\n  the generated header\n* `Initialization` : intialization code run at the beginning of the\n  HFSM, before any of the state initialization code.\n* `Declarations` : variable/function/class declarations within the\n  HFSM's `StateMachine` namespace, will be within the generated header\n  file\n* `Definitions` : variable/function/class definitions within the\n  HFSM's `StateMachine` namespace, will be within the generated source\n  file\n  \n## Getting Started\n\n### Setting up the WebGME-HFSM Server\n\n#### Docker\n\nBuild the dockerfile for the webgme-hfsm docker image\n\n``` bash\ndocker build -t webgme-hfsm .\n```\n\nNow run the mongodb docker and the webgme-hfsm docker\n\n``` bash\ndocker run --name mongo -d -p 27017:27017 mongo\ndocker run --name webgme-hfsm -d -p 8081:8081 --link mongo:mongo webgme-hfsm:latest\n```\n\nYou can also use docker-compose:\n\n``` bash\ndocker-compose up -d\n```\n\n#### Native\n\nDependencies:\n* [nodejs ^6.0](https://www.nodejs.org)\n* [mongodb](https://www.mongodb.com)\n\n```bash\ngit clone https://github.com/finger563/webgme-hfsm\ncd webgme-hfsm\nnpm install -g bower # needed for extra package management\nnpm install          # installs the required packages for webgme-hfsm\nnpm start\n```\n\nWhich will run the WebGME-HFSM server on **PORT 8081** of your local\nmachine, accepting connections on all IP addresses available to it.\n\nNote: this requires a mongodb instance running on the machine, which\ncan be started with:\n\n```bash\nmongod --dbpath ${path you want for your database}\n```\n\nOnce the server has been started, you can navigate (in *Chrome*) to \n\n```\nlocalhost:8081\n```\n\nwhere the server is running. Create a WebGME project there from either\nthe `base` or the `examples` seed.\n\n![Creating a new webgme project](https://raw.githubusercontent.com/wiki/finger563/webgme-hfsm/images/new_webgme_project.gif)\n\n### Creating a HFSM\n\nOnce a webgme project has been opened, creat a new HFSM project by dragging in a new component from the left panel.\n\n![Creating a new HFSM project](https://raw.githubusercontent.com/wiki/finger563/webgme-hfsm/images/new_hfsm_project.gif)\n\nDouble click on the project and then drag in a new HFSM component.\n\n![Creating a new HFSM](https://raw.githubusercontent.com/wiki/finger563/webgme-hfsm/images/new_hfsm.gif)\n\nIn addition to editing the HFSM through webgme, the HFSMViz can also be used. Open an HFSM and click on the HFSMViz on the left side of the screen to use this mode.\n\nComponents can be dragged into the visualizer just like in webgme, with addditional operations accessible via the right-click context menu\n\n![Creating and editing an HFSM](https://raw.githubusercontent.com/wiki/finger563/webgme-hfsm/images/hfsmEditing.gif)\n\n### Simulating a HFSM\n\nIn the HFSMViz, the active state of the simulation is highlighted in\nred, and the user can press the event buttons to see how the state\nmachine will react to that event. If any guards need to be evaluated,\na modal dialog will pop up with options for the user to select which\nguard should evaluate to true at that time. The user has the option of\ncanceling the transition by selecting `None`. In the case that the\nguards are associated with exit transitions of a choice pseudostate,\nthe `Default Transition` will be shown as a guard choice with no text.\n\n![Complex state machine simulation](https://raw.githubusercontent.com/wiki/finger563/webgme-hfsm/images/simulation.gif)\n\nThe **HFSMViz** visualizer allows the visualization of the full\nHFSM. It also provides:\n* An interface to see which events will be handled by the HFSM when it\n  is in a selected (or active) state\n* *Simulation* of the HFSM which properly traverses the transitions from\n  the currently active state to the next active state when the user\n  spawns an event into the simulation.\n  * The visualization will even pop up dialogs asking the user which\n    guard condition should be evalutated to true when the HFSM passes\n    through a choice pseudostate or when multiple transitions have the\n    same event trigger and different guards.\n* Drag and drop external transition creation between two nodes of the\n  HFSM\n* *Automatic layout* and routing of the edges and nodes of the HFSM\n  tree\n* *Context menu* allowing the user to: \n  * Toggle the display of a state's children\n  * Set the active state\n  * Auto-arrange selected nodes into a grid\n  * Re-parent selected nodes into the right-clicked node\n  * Add a new element (which can also be done by dragging from the\n    `Part Browser` and dropping onto the visualizer.)\n\n### Code Generation\n\nThe **SoftwareGenerator** plugin supports generation of a `Project`\nand it's `State Machines` into executable code, with the option of\ngenerating test-bench code for interactively testing out the generated\nHFSM and tracing through which actions occur in what order when an\nevent is spawned.\n\nYou can edit the code attributes for the `State Machines`, `States`,\n`Internal Transitions`, and `External Transitions` within the\nCodeEditor visualizer.\n\n#### Test Bench Code\n\nWhen the test code is generated, it generates a `Makefile` which\nbuilds a `test` and `DEBUG` target for each of the `State Machines` in\nthe `Project` from which the plugin was executed. These test bench\ncodes compile in (using a preprocessor define `DEBUG_OUTPUT`) logging\ncode which traces when transitions are fired, which guards are true,\nwhich actions are executed, and which events are in the State\nMachine's event queue.\n\n[![Asciinema recording of interactive test bench](https://asciinema.org/a/kWbxIsIDlQ0ysAlp0ss9X8zJw.png)](https://asciinema.org/a/kWbxIsIDlQ0ysAlp0ss9X8zJw?t=9)\n\n\u003cdetails\u003e\u003csummary\u003eExample Test Bench Output for the Complex Example State Machine\u003c/summary\u003e\u003cp\u003e\n\n```bash\njebKerman@ubuntu  ~/webgme-hfsm/exampleHFSM  make run_Complex_test_DEBUG \nCompiling Complex_test_DEBUG\ng++ -o Complex_test_DEBUG Complex_test.cpp Complex_GeneratedStates.cpp    -O3 -std=c++14 -MD -MP -MF .dep/Complex_test_DEBUG.d  -DDEBUG_OUTPUT\n\nRunning Complex_test_DEBUG\n\n./Complex_test_DEBUG\nINITIAL TRANSITION::ACTION for /3/c/m\nENTRY::Complex::State_1::/3/c/Y\nSerialTask :: initializing State 1\nSelect which event to spawn:\n0. ENDEVENT\n1. EVENT1\n2. EVENT2\n3. EVENT3\n4. EVENT4\n5. INPUTEVENT\n6. None\nselection: 1\n[ EVENT1 ]\nGUARD [ someNumber \u003c someValue ] for INTERNAL TRANSITION:/3/c/Y/t evaluated to TRUE\nAction iterating: 0\nAction iterating: 1\nAction iterating: 2\nAction iterating: 3\nAction iterating: 4\nAction iterating: 5\nAction iterating: 6\nAction iterating: 7\nAction iterating: 8\nAction iterating: 9\nAction iterating: 10\nAction iterating: 11\nAction iterating: 12\nAction iterating: 13\nAction iterating: 14\nAction iterating: 15\nAction iterating: 16\nAction iterating: 17\nAction iterating: 18\nAction iterating: 19\nAction iterating: 20\nAction iterating: 21\nAction iterating: 22\nAction iterating: 23\nAction iterating: 24\nAction iterating: 25\nAction iterating: 26\nAction iterating: 27\nAction iterating: 28\nAction iterating: 29\nAction iterating: 30\nAction iterating: 31\nHandled EVENT1\nSelect which event to spawn:\n0. ENDEVENT\n1. EVENT1\n2. EVENT2\n3. EVENT3\n4. EVENT4\n5. INPUTEVENT\n6. None\nselection: 4\n[ EVENT4 ]\nGUARD [ someTest ] for EXTERNAL TRANSITION:/3/c/I evaluated to TRUE\nNO GUARD on EXTERNAL TRANSITION:/3/c/o\nEXIT::Complex::State_1::/3/c/Y\nExiting State 1\nTRANSITION::ACTION for /3/c/I\nTRANSITION::ACTION for /3/c/o\nENTRY::Complex::State3::/3/c/T\nTRANSITION::ACTION for /3/c/T/I\nENTRY::Complex::State3::ChildState::/3/c/T/W\nSTATE TRANSITION: Complex::State_1-\u003eComplex::State3::ChildState\nHandled EVENT4\nSelect which event to spawn:\n0. ENDEVENT\n1. EVENT1\n2. EVENT2\n3. EVENT3\n4. EVENT4\n5. INPUTEVENT\n6. None\nselection: 1\n[ EVENT1 ]\nNO GUARD on EXTERNAL TRANSITION:/3/c/T/L\nEXIT::Complex::State3::ChildState::/3/c/T/W\nTRANSITION::ACTION for /3/c/T/L\nENTRY::Complex::State3::ChildState2::/3/c/T/0\nSTATE TRANSITION: Complex::State3::ChildState-\u003eComplex::State3::ChildState2\nHandled EVENT1\nSelect which event to spawn:\n0. ENDEVENT\n1. EVENT1\n2. EVENT2\n3. EVENT3\n4. EVENT4\n5. INPUTEVENT\n6. None\nselection: 2\n[ EVENT2 ]\nNO GUARD on EXTERNAL TRANSITION:/3/c/T/j\nEXIT::Complex::State3::ChildState2::/3/c/T/0\nTRANSITION::ACTION for /3/c/T/j\nENTRY::Complex::State3::ChildState3::/3/c/T/w\nSTATE TRANSITION: Complex::State3::ChildState2-\u003eComplex::State3::ChildState3\nHandled EVENT2\nSelect which event to spawn:\n0. ENDEVENT\n1. EVENT1\n2. EVENT2\n3. EVENT3\n4. EVENT4\n5. INPUTEVENT\n6. None\nselection: 3\n[ EVENT3 ]\nNO GUARD on EXTERNAL TRANSITION:/3/c/T/p\nEXIT::Complex::State3::ChildState3::/3/c/T/w\nTRANSITION::ACTION for /3/c/T/p\nENTRY::Complex::State3::ChildState::/3/c/T/W\nSTATE TRANSITION: Complex::State3::ChildState3-\u003eComplex::State3::ChildState\nHandled EVENT3\nSelect which event to spawn:\n0. ENDEVENT\n1. EVENT1\n2. EVENT2\n3. EVENT3\n4. EVENT4\n5. INPUTEVENT\n6. None\nselection: 4\n[ EVENT4 ]\nNO GUARD on EXTERNAL TRANSITION:/3/c/w\nEXIT::Complex::State3::ChildState::/3/c/T/W\nEXIT::Complex::State3::/3/c/T\nTRANSITION::ACTION for /3/c/w\nENTRY::Complex::State_2::/3/c/v\nENTRY::Complex::State_2::ChildState::/3/c/v/K\nSTATE TRANSITION: Complex::State3-\u003eComplex::State_2::Deep_History_Pseudostate\nHandled EVENT4\nSelect which event to spawn:\n0. ENDEVENT\n1. EVENT1\n2. EVENT2\n3. EVENT3\n4. EVENT4\n5. INPUTEVENT\n6. None\nselection: 4\n[ EVENT4 ]\nNO GUARD on EXTERNAL TRANSITION:/3/c/Q\nEXIT::Complex::State_2::ChildState::/3/c/v/K\nEXIT::Complex::State_2::/3/c/v\nTRANSITION::ACTION for /3/c/Q\nENTRY::Complex::State3::/3/c/T\nENTRY::Complex::State3::ChildState::/3/c/T/W\nSTATE TRANSITION: Complex::State_2-\u003eComplex::State3::Deep_History_Pseudostate\nHandled EVENT4\nSelect which event to spawn:\n0. ENDEVENT\n1. EVENT1\n2. EVENT2\n3. EVENT3\n4. EVENT4\n5. INPUTEVENT\n6. None\nselection: 6\n\nFinished\n```\n\n\u003c/p\u003e\u003c/details\u003e\n\n## Examples\n\nExample HFSMs included in the [Examples Seed](./src/seeds/examples.webgmex):\n\n*Simple*:\n![Simple State Machine](https://raw.githubusercontent.com/wiki/finger563/webgme-hfsm/images/simple.png)\n\n*Medium*:\n![Medium State Machine](https://raw.githubusercontent.com/wiki/finger563/webgme-hfsm/images/medium.png)\n\n*Complex*:\n![Complex State Machine](https://raw.githubusercontent.com/wiki/finger563/webgme-hfsm/images/complex.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinger563%2Fwebgme-hfsm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffinger563%2Fwebgme-hfsm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinger563%2Fwebgme-hfsm/lists"}