State machines: a state can transition to itself (#163); check sum 1088

Development.md

@@ -12,7 +12,7 @@ npm run check        # typecheck + lint + format:check + tests, the gate CI runs
                      #   code is lost (tail's is reported), so a red run reads as green
 npm run build        # writes dist/ and regenerates index.html
 ./build.sh           # the same under `set -o pipefail`, for callers that pipe the output
-node tools/seed-e2e.mjs && node tools/e2e.mjs                 # 1085 editor checks, screenshots in /tmp/gm-e2e-*.png
+node tools/seed-e2e.mjs && node tools/e2e.mjs                 # 1088 editor checks, screenshots in /tmp/gm-e2e-*.png
 GM_STEPS=20 node tools/e2e.mjs                                # or 1-12, or 6,20 — a subset while working on one step
 ./e2e.sh start [GM_STEPS]                                     # the same run detached, see below
 ./e2e.sh status                                               # live progress, or the last run's result

State-machines.md

@@ -31,6 +31,12 @@ air at each end. Two transitions between the same pair are pushed apart, so a th
 lies side by side instead of on top of each other. Two arrows the *same* way round are refused
 (`Already connected`), because every transition hangs on the same two ports.
 
+A transition may also lead from a state **back into itself**: after *Make transition*, click the
+same state again. It is drawn as a **loop over the top edge** of the node, and the inspector lists
+it once, under *out*. Taking it **re-enters** the state: `On state exited` and then
+`On state entered` fire for it, which is what it is for (attack again, restart a timer). Only
+states may do this; any other node connected to itself is still refused.
+
 A transition can be **named**. Select a state and the inspector lists its transitions in two
 groups, *out* and *in*, each row with the state at the far end, a name field and a button to
 remove it — that list is also the only way to delete a transition, since the arrow itself cannot
@@ -117,6 +123,8 @@ The rules, all of them worth knowing before wiring a graph on them:
 
 - A `Set state` into the state the machine is **already in** is no move: nothing is written and
   nothing fires. That is what keeps a `Set state` run every frame from firing `entered` every frame.
+  A **transition back into the same state** is the exception: `State transition` along it is a
+  move, so `exited` and `entered` fire for the state, every time it is taken.
 - The **start state counts as entered**. A local machine is entered per instance, right after that
   instance's `On start`; a `global` one is entered **once for the whole run**, before the first
   instance exists, and every instance created with the scene hears that one entry. An instance