From 96ae93d969c0927b198edf0cb553a30159b3e79f Mon Sep 17 00:00:00 2001 From: William Emfinger Date: Fri, 4 Sep 2026 23:46:01 -0500 Subject: [PATCH] docs(state_machine): link and embed the HFSM playground The state machine docs described webgme-hfsm and showed a PNG of the example machine. The playground now runs the whole toolchain in a browser, so the docs can show the machine itself instead: the reader can drag states, run the simulator and read the generated C++ without leaving the page or installing anything. Embedded with the same pattern odrive_ascii.rst already uses for its web console -- an "open in a new tab" link above, then the iframe -- and the PNG stays for the PDF build, where a raw HTML block renders as nothing. The second webgme-hfsm reference is anonymous (`__`) so it does not collide with the named target in the intro; the file parses clean. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01E4hRq1q5VGPjNn2dnkkqBy --- doc/en/core/state_machine.rst | 41 +++++++++++++++++++++++++++++++++-- 1 file changed, 39 insertions(+), 2 deletions(-) diff --git a/doc/en/core/state_machine.rst b/doc/en/core/state_machine.rst index f1d9403bd7..7a3c33c7fe 100644 --- a/doc/en/core/state_machine.rst +++ b/doc/en/core/state_machine.rst @@ -9,12 +9,49 @@ generated from webgme-hfsm) can depend on. Code examples for the state_machine API are provided in the `state_machine` example folder. -The example runs the generated code for the following example hsfm (which is -provided and for which the code was generated from webgme-hfsm): +The example runs the generated code for the following example hsfm, which is +provided as a model (``components/state_machine/example/main/Complex.json``) +and generated to C++ as part of the example's build: .. image:: images/complex-hfsm.png :alt: "Complex" example HFSM showing the many of the UML formalisms supported. +.. ------------------------------ Playground ----------------------------------- + +Modeling and generating a state machine +--------------------------------------- + +State machines are modeled and generated with `webgme-hfsm +`__. The **HFSM Playground** runs the +whole toolchain in the browser -- edit the machine, simulate it, and read or +download the generated C++ -- with nothing to install and no server: + +`Open the HFSM Playground in a new tab `_, +or go straight to `this example's machine +`_. + +The playground below is live, not a picture: drag the states, press +**HFSM-Restart** and send events to watch the machine run, or switch to +**Code** to read the C++ it generates. + +.. raw:: html + + + +The same generator runs on the command line, which is how the example builds +its C++ from the model: + +.. code-block:: sh + + npx -p webgme-hfsm hfsm-gen my_machine.json -o generated --no-support + +``--no-support`` leaves out the shared runtime (``state_base.hpp``, the +history states, ``magic_enum.hpp``) because this component already provides +it. See the example's README for how that is wired into CMake. + .. ------------------------------- Example ------------------------------------- .. toctree::