Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
fb5f61b
ci: update release-preflight check
CoderGamester Aug 5, 2026
0502511
ci: update release-preflight check
CoderGamester Aug 5, 2026
36b60d2
ci: update release-preflight check
CoderGamester Aug 5, 2026
6b79a0a
style: wrap long XML summaries
CoderGamester Aug 10, 2026
f09dc68
fix: correct case of two .meta filenames to match their assets
CoderGamester Aug 10, 2026
b9c50ad
docs: modernize statechart guidance
CoderGamester Aug 12, 2026
a6a06ae
docs: focus agent guidance on durable rules
CoderGamester Aug 13, 2026
f22d348
docs: slim CLAUDE wrappers to @AGENTS.md
CoderGamester Aug 27, 2026
3088fd0
fix(tests): re-point the RCR anchors at the production symbol
CoderGamester Sep 14, 2026
65338a3
feat: add the Statechart Debugger, observability API and Game Flow sa…
CoderGamester Nov 16, 2026
baebdbc
refactor: expose the live chart as the read-only view and keep debugg…
CoderGamester Nov 16, 2026
5ebc77e
feat(debugger): mark the view B graph as display only
CoderGamester Nov 16, 2026
72e3a9c
refactor(debugger): remove the Graph Toolkit view and name views by c…
CoderGamester Nov 16, 2026
1bd081a
chore: prepare release 1.0.0
CoderGamester Nov 16, 2026
02225d4
docs: fold the Editor guide into the package guide
CoderGamester Nov 16, 2026
db16e60
Merge pull request #21 from CoderGamester/feature/statechart-debugger…
CoderGamester Nov 16, 2026
8b635d0
fix(samples): add the Game Flow sample folder meta
CoderGamester Nov 16, 2026
5293ada
Merge pull request #22 from CoderGamester/fix/gameflow-sample-folder-…
CoderGamester Nov 16, 2026
04e20be
chore: date the 1.0.0 release 2026-11-17
CoderGamester Nov 16, 2026
1c23ebe
Merge pull request #23 from CoderGamester/chore/release-1.0.0-date
CoderGamester Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 54 additions & 8 deletions .github/workflows/release-preflight.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ name: release-preflight
on:
pull_request:
branches: [master]
types: [opened, synchronize, reopened, closed]

permissions:
contents: read
Expand All @@ -45,6 +46,7 @@ concurrency:

jobs:
preflight:
if: github.event.action != 'closed'
runs-on: ubuntu-latest
steps:
# `lfs: true` is load-bearing, not a nicety. The default (false) leaves every
Expand All @@ -53,32 +55,76 @@ jobs:
# FETCHABLE from the remote — the exact failure that hit uiservice, where the
# working tree held stubs while the published 1.2.1 had real content.
- name: Check out the package
uses: actions/checkout@v4
uses: actions/checkout@v7
with:
fetch-depth: 0
lfs: true
persist-credentials: false

# The gate logic is shared rather than vendored into six repos, so there is
# one source of truth. `ref` is explicit: actions/checkout defaults to the
# target repo's DEFAULT branch (master), where the tooling does not exist
# yet — omitting it fails with "No such file or directory". Retarget this to
# master once the skill is merged there.
# one source of truth. Pinning its full commit keeps an unchanged package PR
# reproducible when Frameworks/develop advances; the installer performs
# intentional snapshot updates across all package repositories.
- name: Check out the release tooling
uses: actions/checkout@v4
uses: actions/checkout@v7
with:
repository: CoderGamester/Frameworks
ref: develop
# Immutable tooling snapshot. Update intentionally through
# `release.py install-preflight`, never by following a moving branch.
ref: be8c147f3d12d94a4055d556ffdc0a26e077e5ec
path: .release-tooling
sparse-checkout: .claude/skills/unity-package-release/scripts
persist-credentials: false

- name: Assert the release tooling checkout
run: |
test -f .release-tooling/.claude/skills/unity-package-release/scripts/release.py

- name: Set up Python
uses: actions/setup-python@v5
uses: actions/setup-python@v7
with:
python-version: "3.12"

- name: Preflight
run: |
python3 .release-tooling/.claude/skills/unity-package-release/scripts/release.py \
preflight-pr --path . --base "origin/${{ github.base_ref }}"

# GITHUB_TOKEN cannot dispatch into another repository. Add a fine-grained
# FRAMEWORKS_DISPATCH_TOKEN secret (Contents: read/write on Frameworks) to each
# package repository to activate this hand-off. A missing token is reported as
# a warning rather than turning an already-merged release PR red.
notify-release:
if: github.event.action == 'closed' && github.event.pull_request.merged == true
runs-on: ubuntu-latest
steps:
- name: Notify the host release workflow
env:
DISPATCH_TOKEN: ${{ secrets.FRAMEWORKS_DISPATCH_TOKEN }}
PACKAGE_REPOSITORY: ${{ github.event.repository.name }}
run: |
if [ -z "$DISPATCH_TOKEN" ]; then
echo "::warning::FRAMEWORKS_DISPATCH_TOKEN is not configured; skipping host release notification."
exit 0
fi

case "$PACKAGE_REPOSITORY" in
Unity-GameData) package=gamedata ;;
Unity-GoogleSheet-Importer) package=googlesheetimporter ;;
Unity-MobileServices) package=mobileservices ;;
Unity-Services) package=services ;;
Statechart-HFSM) package=statechart ;;
Unity-UiService) package=uiservice ;;
*)
echo "::error::Unknown package repository: $PACKAGE_REPOSITORY"
exit 1
;;
esac

payload=$(printf '{"event_type":"upm-release","client_payload":{"package":"%s","phase":"status"}}' "$package")
curl --fail-with-body --location --request POST \
--url https://api.github.com/repos/CoderGamester/Frameworks/dispatches \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer $DISPATCH_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--data "$payload"
145 changes: 55 additions & 90 deletions AGENTS.md

Large diffs are not rendered by default.

36 changes: 36 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,42 @@ All notable changes to this package will be documented in this file.
The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

## [1.0.0] - 2026-11-17

**New**:
- **Statechart Debugger**: *Tools > GameLovers > Statechart Debugger* shows any running chart live, with Run, Pause and Reset controls and two views that can each be turned on or off: a live chart of nested boxes with parallel regions as lanes, and a state tree with the latest 256 trace steps. The **Copy** menu exports a Mermaid diagram, the active state paths or the trace.
- **Chart view**: `IStatechart.RootRegion` exposes the chart's structure through `IRegionNode`, `IStateNode` and `ITransitionEdge`, and `GetActiveStates` and the allocation-free `IsActive` report which states are active. The view is the live chart itself, so it costs nothing to build.
- **Trace**: `IStatechart.Traced` publishes every event, exit, transition, enter, fault and lifecycle step in execution order as a `StatechartTrace`; nothing is allocated while no one listens.
- **Lifecycle**: a `Statechart(string name, Action<IStateFactory> setup)` constructor, `Name` and `IsRunning`, and `IDisposable` support. `Dispose()` stops the chart for good, cancels token-aware tasks and removes it from the debugger; `Run()` after it throws `ObjectDisposedException`.
- **Cancellable task waits**: `ITaskWaitState.WaitingFor` overloads receive a `CancellationToken` that `Reset()` and `Dispose()` cancel.
- **Game Flow sample**: one statechart drives a small game loop that uses every state kind, with on-screen controls, meant to be watched in the Statechart Debugger.

**Changed**:
- The minimum Unity version is now 6000.0 (was 2022.3); 6000.0.x, 6000.3.x and 6000.6.x are the supported streams.
- Requires UniTask 2.5.11 (was 2.5.10), the first version whose Editor code compiles on Unity 6000.6, and the built-in UIElements module used by the debugger and the sample.
- Events triggered while another event is being processed, for example from an enter callback, are now queued and processed right after it (run to completion) instead of running against the previous state.
- `Reset()` now drops queued events and abandons pending waits and tasks, so their late completion no longer moves the chart.
- `LogsEnabled` now writes one trace line per step, such as `[Statechart 'Player'] Idle -> Jumping on 'Jump'`.
- Null arguments now throw `ArgumentNullException`, and a setup without an initial state throws `InvalidOperationException` instead of `MissingMemberException`.

**Removed**:
- The Editor-only `Statechart.CurrentState`.

**Migration**:
- Replace `CurrentState` with `GetActiveStates`, `IsActive` or the Statechart Debugger.
- Custom `IStatechart` implementations must add the new members: `Name`, `IsRunning`, `RootRegion`, `Traced`, `GetActiveStates`, `IsActive` and `Dispose`.
- Catch `InvalidOperationException` instead of `MissingMemberException` for a setup without an initial state.

**Fixed**:
- A `TaskWait` state whose task throws no longer blocks the chart and its parent splits forever; the fault is logged and the state completes.
- `TaskWait` states now resume the chart on the main thread, and a `Task` completing on the main thread resumes it in the same frame.
- Pausing or resetting the chart from a callback now stops a chain of automatic transitions.
- An action-only event on a nest or split state no longer force-completes the waits inside it.
- Creation stack traces in error logs now start at the code that declared the failing state, and enter-callback errors no longer report themselves as exit errors.

**Docs**:
- Rewrote the README with state kinds, runtime semantics, the observe API, the debugger and the sample.

## [0.9.5] - 2026-08-04

**Changed**:
Expand Down
11 changes: 0 additions & 11 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,12 +1 @@
# Claude Code Guide — Statechart

This package's contributor/agent guide lives in `AGENTS.md`.
Claude Code will automatically import it below.

@AGENTS.md

## Claude-Specific Notes

- Treat `AGENTS.md` as the source of truth.
- If anything in this file appears to conflict with `AGENTS.md`, prefer `AGENTS.md`.
- For user-facing usage, see `README.md`.
8 changes: 8 additions & 0 deletions Editor.meta

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions Editor/AssemblyInfo.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
using System.Runtime.CompilerServices;

[assembly: InternalsVisibleTo("GameLovers.Statechart.Editor.Tests")]
2 changes: 2 additions & 0 deletions Editor/AssemblyInfo.cs.meta

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

18 changes: 18 additions & 0 deletions Editor/GameLovers.Statechart.Editor.asmdef
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
{
"name": "GameLovers.Statechart.Editor",
"rootNamespace": "",
"references": [
"GameLovers.Statechart"
],
"includePlatforms": [
"Editor"
],
"excludePlatforms": [],
"allowUnsafeCode": false,
"overrideReferences": false,
"precompiledReferences": [],
"autoReferenced": true,
"defineConstraints": [],
"versionDefines": [],
"noEngineReferences": false
}
7 changes: 7 additions & 0 deletions Editor/GameLovers.Statechart.Editor.asmdef.meta

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

158 changes: 158 additions & 0 deletions Editor/LiveChartView.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,158 @@
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UIElements;

// ReSharper disable CheckNamespace

namespace GameLovers.StatechartMachine.Editor
{
/// <summary>
/// The chart drawn as nested boxes. Nest and split states contain their regions, split regions sit side
/// by side as dashed lanes, and every active state is highlighted.
/// </summary>
internal sealed class LiveChartView : VisualElement
{
private const double RecentSeconds = 0.8;

private readonly Dictionary<IStateNode, VisualElement> _elements = new Dictionary<IStateNode, VisualElement>();
private readonly ScrollView _scroll;

internal LiveChartView()
{
AddToClassList("sc-pane");
AddToClassList("sc-pane-live");

var header = new Label("Live chart");
header.AddToClassList("sc-pane-header");
Add(header);

// Vertical only: a bounded width lets each region's boxes wrap onto new rows.
_scroll = new ScrollView(ScrollViewMode.Vertical);
_scroll.AddToClassList("sc-pane-content");
Add(_scroll);
}

/// <summary>Rebuilds the boxes for <paramref name="chart"/>, or clears them when null.</summary>
internal void SetChart(IStatechart chart)
{
_elements.Clear();
_scroll.Clear();

if (chart != null)
{
_scroll.Add(BuildRegion(chart.RootRegion, false));
}
}

/// <summary>Highlights <paramref name="active"/> states and briefly flashes recently entered ones.</summary>
internal void UpdateActive(List<IStateNode> active, IReadOnlyCollection<StatechartTraceRecord> history)
{
var recent = new HashSet<uint>();
var now = Time.realtimeSinceStartupAsDouble;

foreach (var record in history)
{
if (record.Kind == StatechartTraceKind.StateEntered && now - record.Time < RecentSeconds)
{
recent.Add(record.StateId);
}
}

foreach (var pair in _elements)
{
pair.Value.EnableInClassList("sc-active", active.Contains(pair.Key));
pair.Value.EnableInClassList("sc-recent", recent.Contains(pair.Key.Id));
}
}

private VisualElement BuildRegion(IRegionNode region, bool isLane)
{
var container = new VisualElement();

container.AddToClassList("sc-region");
container.EnableInClassList("sc-lane", isLane);

foreach (var state in region.States)
{
container.Add(BuildState(state));
}

return container;
}

private VisualElement BuildState(IStateNode state)
{
var box = new VisualElement { tooltip = $"{state.Path}\n{state.Kind}" };

box.AddToClassList("sc-state");
box.AddToClassList($"sc-kind-{state.Kind.ToString().ToLowerInvariant()}");
_elements[state] = box;

if (state.Kind == StateKind.Initial || state.Kind == StateKind.Final)
{
box.AddToClassList("sc-pseudo");
box.Add(new Label(state.Kind == StateKind.Initial ? "●" : "◉"));
return box;
}

var title = new VisualElement();
title.AddToClassList("sc-state-title");
title.Add(new Label(state.Name) { name = "name" });

if (state.Kind != StateKind.Simple)
{
var badge = new Label(state.Kind.ToString());
badge.AddToClassList("sc-badge");
title.Add(badge);
}

box.Add(title);

if (state.Regions.Count > 0)
{
var regions = new VisualElement();

regions.AddToClassList("sc-regions");
regions.EnableInClassList("sc-regions-split", state.Kind == StateKind.Split);

foreach (var region in state.Regions)
{
regions.Add(BuildRegion(region, state.Kind == StateKind.Split));
}

box.Add(regions);
}

foreach (var edge in state.Transitions)
{
if (edge.Kind == TransitionKind.Automatic && edge.Target != null)
{
continue;
}

var chip = new Label($"{EdgeLabel(edge)} → {edge.Target?.Name ?? "action"}");
chip.AddToClassList("sc-edge");
box.Add(chip);
}

return box;
}

private static string EdgeLabel(ITransitionEdge edge)
{
switch (edge.Kind)
{
case TransitionKind.Event:
return edge.Event.Name;
case TransitionKind.Choice:
return edge.HasCondition ? "if" : "else";
case TransitionKind.Completion:
return "done";
case TransitionKind.Leave:
return "leave";
default:
return "auto";
}
}
}
}
2 changes: 2 additions & 0 deletions Editor/LiveChartView.cs.meta

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading