Chickensoft.LogicBlocks 5.12.0

dotnet add package Chickensoft.LogicBlocks --version 5.12.0                
NuGet\Install-Package Chickensoft.LogicBlocks -Version 5.12.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Chickensoft.LogicBlocks" Version="5.12.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Chickensoft.LogicBlocks --version 5.12.0                
#r "nuget: Chickensoft.LogicBlocks, 5.12.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Chickensoft.LogicBlocks as a Cake Addin
#addin nuget:?package=Chickensoft.LogicBlocks&version=5.12.0

// Install Chickensoft.LogicBlocks as a Cake Tool
#tool nuget:?package=Chickensoft.LogicBlocks&version=5.12.0                

💡 LogicBlocks

Chickensoft Badge Discord Read the docs line coverage branch coverage

LogicBlocks is a serializable, hierarchical state machine package for C# that works well when targeting ahead-of-time (AOT) environments. LogicBlocks draws inspiration from statecharts, state machines, and blocs.


<p align="center"> <img alt="Chickensoft.LogicBlocks" src="Chickensoft.LogicBlocks/icon.png" width="200"> </p>


Instead of elaborate transition tables, states are simply defined as self-contained class records that read like ordinary code using the state pattern. Logic blocks are designed with performance, adaptability, and error tolerance in mind, making them refactor-friendly and suitable for high performance scenarios (such as games).

Logic blocks grow with your code: you can start with a simple state machine and easily scale it into a nested, hierarchical statechart that represents a more complex system — even while you're working out what the system should be.

Logic blocks are based on statecharts. You may also know them as hierarchical state machines (HSM's).

💡 Example

A logic block is a class that receives inputs, maintains a single state instance, and produces outputs.

Logic blocks enable you to efficiently model complex behaviors[^1].

using Chickensoft.Introspection;

[Meta, LogicBlock(typeof(State), Diagram = true)]
public class LightSwitch : LogicBlock<LightSwitch.State> {
  public override Transition GetInitialState() => To<State.PoweredOff>();

  public static class Input {
    public readonly record struct Toggle;
  }

  public abstract record State : StateLogic<State> {
    public record PoweredOn : State, IGet<Input.Toggle> {
      public Transition On(in Input.Toggle input) => To<PoweredOff>();
    }

    public record PoweredOff : State, IGet<Input.Toggle> {
      public Transition On(in Input.Toggle input) => To<PoweredOn>();
    }
  }

  public static class Output {
    public readonly record struct StatusChanged(bool IsOn);
  }
}

🖼️ Visualizing Logic Blocks

LogicBlocks provides a source generator that can generate UML state diagrams of your code.

stateDiagram-v2

state "LightSwitch State" as Chickensoft_LogicBlocks_DiagramGenerator_Tests_TestCases_LightSwitch_State {
  state "PoweredOn" as Chickensoft_LogicBlocks_DiagramGenerator_Tests_TestCases_LightSwitch_State_PoweredOn
  state "PoweredOff" as Chickensoft_LogicBlocks_DiagramGenerator_Tests_TestCases_LightSwitch_State_PoweredOff
}

Chickensoft_LogicBlocks_DiagramGenerator_Tests_TestCases_LightSwitch_State_PoweredOff --> Chickensoft_LogicBlocks_DiagramGenerator_Tests_TestCases_LightSwitch_State_PoweredOn : Toggle
Chickensoft_LogicBlocks_DiagramGenerator_Tests_TestCases_LightSwitch_State_PoweredOn --> Chickensoft_LogicBlocks_DiagramGenerator_Tests_TestCases_LightSwitch_State_PoweredOff : Toggle

Chickensoft_LogicBlocks_DiagramGenerator_Tests_TestCases_LightSwitch_State_PoweredOff : OnEnter → StatusChanged
Chickensoft_LogicBlocks_DiagramGenerator_Tests_TestCases_LightSwitch_State_PoweredOn : OnEnter → StatusChanged

[*] --> Chickensoft_LogicBlocks_DiagramGenerator_Tests_TestCases_LightSwitch_State_PoweredOff

Generated UML diagrams are placed alongside the code for your logic block with the *.g.puml extension. You can use PlantUML (and/or the PlantUML VSCode Extension) to visualize the generated diagram code.

[!TIP] A diagram explains all of the high level behavior of a state machine in a single picture. Without a diagram, you would have to read and scroll through all the relevant code files to understand the machine (especially if you weren't the author, or forgot how it worked since you had written it).

🤫 Differences from Statecharts

In the interest of convenience, logic blocks have a few subtle differences from statecharts:

  • 💂‍♀️ No explicit guards

    Use conditional logic in an input handler

  • 🪢 Attach/Detach callbacks

    These are an implementation specific detail that are called whenever the state instance changes, as opposed to only being called when the state type hierarchy (i.e., state configuration) changes.

  • 🕰️ No event deferral

    Non-handled inputs are simply discarded. There's nothing to stop you from implementing input buffering on your own, though: you may even use the boxless queue collection that LogicBlocks uses internally.

LogicBlocks also uses different terms for some of the statechart concepts to make them more intuitive or disambiguate them from other C# terminology.

statecharts logic blocks
internal transition self transition
event input
action output

[^1]: Simple behaviors, like the light switch example, are considerably more verbose than they need to be. Logic blocks shine brightest when they're used for things that actually require hierarchical state machines.


Looking for more? Read the ✨ docs! ✨


🐣 Package generated from a 🐤 Chickensoft Template — https://chickensoft.games

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories (2)

Showing the top 2 popular GitHub repositories that depend on Chickensoft.LogicBlocks:

Repository Stars
chickensoft-games/GameDemo
The Chickensoft Game Demo — a fully tested, third-person 3D game built with Godot and C#. Now with saving and loading!
chickensoft-games/GodotEnv
Manage Godot versions and addons from the command line on Windows, macOS, and Linux.
Version Downloads Last updated
5.12.0 257 10/23/2024
5.11.1 84 10/23/2024
5.11.0 195 10/9/2024
5.10.0 139 10/4/2024
5.9.0 175 9/27/2024
5.8.0 181 9/17/2024
5.7.0 63 9/17/2024
5.6.0 241 9/4/2024
5.5.0 231 8/24/2024
5.4.0 189 8/20/2024
5.3.0 331 7/25/2024
5.2.0 50 7/25/2024
5.1.0 746 6/9/2024
5.0.0 114 6/8/2024
4.2.2 471 2/29/2024
4.2.1 2,639 1/5/2024
4.2.0 172 12/29/2023
4.1.0 135 12/27/2023
4.0.0 229 12/23/2023
3.4.0 497 10/27/2023
3.3.0 168 10/25/2023
3.2.0 163 10/18/2023
3.1.0 164 10/14/2023
3.0.0 184 10/7/2023
2.4.1 165 10/1/2023
2.4.0 1,616 8/29/2023
2.3.2 162 8/27/2023
2.3.1 168 8/27/2023
2.3.0 160 8/27/2023
2.2.0 157 8/26/2023
2.1.1 200 8/2/2023
2.1.0 163 7/29/2023
2.0.0 175 7/26/2023
2.0.0-beta.1 99 7/26/2023
1.0.0 199 7/15/2023

LogicBlocks release.