search

vvvv / VL-Language

The official repo for the design of the VL programming language
31 stars 0 forks source link

[Proposal] State Machine patching pattern / library #46

Open antongit opened 3 years ago

antongit commented 3 years ago

Introduction

This is a patching pattern and a small library for creating and running State Machines' graphs directly in VL. Related to the Quest #8.

For a long time I was using external Tools like QFSM and contributions like u7angel's amazing Automata UI. But I always thought - how cool will it be to make State Machines directly in VL, without the need for any external editors. We already have nodes and links, why do we need anything else?

And then, I came up with a very simple solution. @gregsn has stripped it down even more and cleaned it up.

This solution is made in plain VL, no magic involved. I hope one day vvvv's UI will support it a bit, reducing some copy-pasting and increasing readability.

The lib was already used in two production-grade projects.

Usage scenarios

The machine can be used in two different ways:

  1. Basic (classic) States are just defined by their names (strings) and the rest of the system is listening to the active string.

  2. Advanced States themselves can contain many different properties, operations and even complete apps, that can run simultaneously or only when the state is active.

How it works

States are represented by Processnodes. Transitions between states are represented by links assigned to operations. To trigger a transition from one state to another a corresponding operation is called. An operation can be called directly (by placing a node) or by sending a string with an operation's name.

How to use it

The lib will be provided as a nuget that should be referenced by your document. For now it's just a single VL.Statemachine.vl document and some examples.

See the provided example patches. A video tutorial is coming soon. Here is the how to in written from.

Basic usage

  1. Reference VL.Statemachine.vl from your document (for now, later it will be a nuget).
  2. Open VL.Statemachine.vl, navigate to Definitions > .Templates.Internal, copy the StateTemplate into your document and rename it. This is one of your states.
  3. Duplicate and rename this state as many times as you need.
  4. Create a class for your machine and place processnodes of your states in it.
  5. Connect them with links and assign the links to operations (which are corresponding to the transitions).
  6. The StateTemplate pre-defines 4 inputs, enable/disable them in the Process node configuration in the Patch Explorer. If your need more inputs, just create another copy of one of the inputs and assign it to a new operation.
  7. One of the states should be configured as Initial (enable the SetAsInitialState in its Process node configuration).
  8. Feed the State Manager to your state machine.
  9. Trigger transitions of the machine by placing the nodes of the corresponding operations or sending the names of operations as strings by using the SendEvent.

State machine class with states and transitions image

State Machine in action StateMachine2

One of the states with two inputs enabled image

Advanced usage

In order to provide properties, operations and/or whole processnodes to the states:

  1. Define a new interface which derives from the IState and add Operations/Inputs/Outputs to it.
  2. Use this interface in some of your states (instead of the default IState).
  3. Use the GetState of the StateManager to get the active state and cast it to your new interface.
  4. If the states are very different from each other, then their operations can by accessed by casting the active state to the particular class (without defining a new interface).

A new Interface image

Main state is implementing the new interface image

Accessing the active state image

Video presentation

The pattern was presented at 13. Worldwide vvvv Meetup (starts at about 2:09): https://youtu.be/2gGPh84y-mU?t=129

Library

VL.Statemachine.zip

Conclusion

This proposal can be seen as a ready-to-use library and as general patching pattern open to any modifications / customizations.

Also inspired by:

bj-rn commented 2 years ago

As a follow up from matrix: Could you add this as a Helppatch? HowTo build a state machine.

If one doesn't already know about it it's pretty hard to find.

YanYas commented 2 years ago

Hi @antongit, @gregsn, In an attempt to build upon you've already done I started making a Statmachine patch with a little demo in the spirit of your own. The main issues I tried to answer were:

  1. Making it easier to setup the statemachine
  2. Making classes that could be potentially be used with different gui
  3. The state has a name used a key by the state graph, but doesn't need to be a string. It could be an enum, another class, maybe even a delegate.

It isn't finished though: I need to figure out how to make the state graph aware of new nodes. I'll setup a repo for it sometime. Feedback welcome,

H

HaStateMachine.zip .

domjancik commented 3 months ago

Hi, here is an updated version that works with latest gamma 6.6.

There were some changes regarding VL Type reflection that broke the previous version.

VL.Statemachine.VVVVGamma6.6.zip