StateMachine - A PureMVC / AS3 Utility

[puremvc]

This utility provides a simple yet effective Finite State Machine implementation, which allows the definition of discrete states, and the valid transitions to other states available from any given state, and the actions which trigger the transitions.

A mechanism is provided for defining the entire state machine in XML and having a fully populated StateMachine injected into the PureMVC app.

Standard and MultiCore versions are included.

The utility has historically been located here: http://trac.puremvc.org/Utility_AS3_StateMachine
The project has been moved here: https://github.com/PureMVC/puremvc-as3-util-statemachine/wiki

Standard and MultiCore versions are included.

The authors are Neil Manuell and Cliff Hall.

[puremvc]

If you happened to download this utility within the last 24 hours, you probably found that the /bin folder with the compiled SWC files was missing. Sorry about that. Download again and you should be set, though you may need to clear your browser's cache.

-=Cliff>

[Hyakugei]

Just a quick note to say - wow, nice work! I'm really looking forward to my next project where i can spend some time with this utility.

Wonderful work. Thank you, to all the authors.

[Neil Manuell]

cool, let us know of any problems / solutions / additions that may pop up

[gjastrab]

In the release notes under the State Representation section one of the points is:

The entering notification for a State carries a reference in the body to the state we are entering as well, in case you've sub-classed State to pass data.

Do you have an example of how this would be done?  How would you get your new state class to be registered, by overriding FSMInjector::createState to instantiate your class instead of StateMachine's State class?

This would be my top feature request: an elegant way to specify subclasses for individual states w/o needing to override createState (maybe a user doesn't want all of the states to be represented by the extended State class, only certain ones).  Perhaps something could be cleverly done w/ XML namespaces to specify the class to use...

(abbreviated fsm example)

Code:

<fsm xmlns:sub="com.my.namespace.to.state.class.ExtendedStateClass">
  <state name="Normal State">...</state>
  <sub:state name="Extended State 1">...</sub:state>
  <sub:state name="Extended State 2">...</sub:state>
</fsm>

This way you wouldn't have to type out the entire state class multiple times:
More Verbose Way

Code:

<fsm>
  <state name="Normal State">...</state>
  <state name="Extended State 1" stateClass="com.my.namespace.to.state.class.ExtendedStateClass">...</state>
  <state name="Extended State 2" stateClass="com.my.namespace.to.state.class.ExtendedStateClass">...</state>
</fsm>

[puremvc]

Yes, currently you'd need to subclass FSMInjector as you described.

I like your suggestion, though.

I think the latter version of your suggested examples is the right way to go. Overloading the xml namespace identifier will (IMHO) be confusing to most, harder to parse, and more prone to error. And we have E4X for parsing. Imagine doing it to java and having to use some horrible xml parser there to programmatically rip it apart. (BTW, if you happen to be doing just that in java now, go look up XOM, its the best).

-=Cliff>

[gjastrab]

Hm, wasn't thinking about having to port when suggesting that, but would it really be that difficult?  I was just concerned w/ having to re-enter the potentially long namespace for the subclassed State multiple times.  I much prefer the first method, and parsing it is easy!

Using the following XML:

Code:

var fsm:XML = <fsm xmlns:sub1="com.SubState1" xmlns:sub2="com.SubState2">
  <state name="Normal State" />
  <sub1:state name="Sub Classed 1" />
  <sub2:state name="Sub Classed 2" />
</fsm>

Parsing:

Code:

var namespaces:Array = fsm.namespaceDeclarations();
for each(var ns:Namespace in namespaces) {
  // get class reference for ns.uri
  // store it in a hash under key ns.prefix
  trace("Prefix '" + ns.prefix + "' is for class => " + ns.uri);
}

for each( var state:XML in fsm.children() ) {
  var stateNS:Namespace = state.namespace();
  if(stateNS == null) { /* USE regular State class */ }
  else {
    trace("Need to use class w/ NS: " + stateNS.prefix);
    // something like
    var stateClass:Class = stateRefs[stateNS.prefix];
    state = new stateClass();
  }
}

[Neil Manuell]

I agree with cliff that the namespace option is, lets say a little specialised, for general use... I think it may scare off quite a few people.  The verbose declaration is simple and obvious, though not as elegant, though I may have a play with this idea.

[Neil Manuell]

by the way, how would you ensure that the state classes get compiled?
if you are typing to interfaces and defining class paths as strings, there is no guaranteeing that they will.

I usually wrap my getDefinitionByName method in a factory that explicitly declares all the classes to be compiled for that factory, then pass the factory where it is needed.

However, this is just another class, another piece of tramp data, and another complication...

oh, and merry xmas

[puremvc]

As soon as I walked away from that last post, this was the next thing that came to mind. I think your closing thought is key, it is another complication. Whether is worth that complication to implement is questionable.



-=Cliff>

[Neil Manuell]

i think that its definitely worth documenting as a way of extending the utility... that gives the user a choice

[puremvc]

Sure. Perhaps a demo that overrides FSM and injects custom state classes. But I'm not entirely sure just yet that State should have subclasses. That means any actor handling the State object needs to know that custom State subclass. I have reservations about that coupling.

Before recommending that I'd like to think through the problem a bit more.

If anyone would like to throw out example scenarios here that use subclasses and arguments for it, please do.

In the meantime, some more research of other statemachine implementations might be in order to inform us further. There are a lot of takes on this problem out there and what is here is extremely simple and usable. I'd hate to make it more complicated than it is if we don't have to.

-=Cliff> 

[gjastrab]

I don't have a particular need to subclass state, but was just exploring how this would be done in response to the bullet in the release notes I originally quoted.

If there was a body Object on the State that would allow me to pass data into the notification that is initiating an ACTION to another State, then the problem of having to send the StateMachine.ACTION notification, and then respond later after an ENTERING or CHANGED notification to send data would be solved.  That is the primary feature request I have right now for this utility.

[gjastrab]

oh, and merry xmas

And merry xmas to everyone as well.

[cambiata]

Hi!

Is the State Machine solution suitable for handling asset/media loading? (mp3 files, images...) If so, should the loading be regarded as a state or as an action between two states?

Regards!  / Jonas