[Statemachine] More or clearer in depth example docs

[mwpowellhtx]

Need help grasping the docs

The examples seem a bit oversimplified to me. Theoretically, I understand statemachines, so let's start with that. Bottom line, I need help orienting myself to how CBA handles statemachines, the shape of the data being injected into a statemachine.

Some formative thoughts

I do not have anything definitive, only to suggest a more in depth example, with clear states, clear transitions, so we can begin to form a picture what is happening. In particular, I am wondering does the statemachine operate on each element in the array, for starters.

What do the states operate on? What does each transition operate on? From the docs, for instance, I am under the impression that CBA statemachines takes each element in a presented array, and applies the next thing in the statemachine to that element? Is there a start, "initial", I get that much. Or an end, not at all clear from the example, would the units ever relax their alert level, for instance? It can cycle as many times as it needs to? Are the elements selected from the array, i.e. _list#_n? Are they torn from the array, i.e. +(_list#_n), which would be a huge difference, particularly for what I might like to accomplish by it.

And maybe a forum to openly discuss

Would be better if y'all had an actual forum, perhaps. That would be grand; maybe you do, I am unaware of it. i.e. a Discord, Gitter, etc.

References

The examples seem oversimplified to me, not sure I quite grasp what is a state, a transition, so on and so forth. Maybe a slightly more in depth example would be helpful.

• example.sqf
• example.hpp
• Also what it means to raise events, do those states occur akin to statemachine interrupt, along these lines.

[BaerMitUmlaut]

What do the states operate on? What does each transition operate on?

I'm sorry but I'm not sure how this isn't obvious from the example and it's also documented in the function headers. The statemachine operates on the list of elements you define during its creation.

From the docs, for instance, I am under the impression that CBA statemachines takes each element in a presented array, and applies the next thing in the statemachine to that element?

"the next thing"? What thing?

Is there a start, "initial", I get that much.

The first state you add is the start state.

Or an end, not at all clear from the example, would the units ever relax their alert level, for instance?

Not in the example, no. Again, the "not at all clear" confuses me. There are no transitions going from the "Alert" state anywhere else. There's no code lowering the skill again, so why do you expect some hidden magic here? You can add a special end state if you want. In this case, "Alert" is an end state.

Is can cycle as many times as it needs to?

?

Are the elements selected from the array, i.e. _list#_n?

Yes.

Are they torn from the array, i.e. +(_list#_n), which would be a huge difference, particularly for what I might like to accomplish by it.

That doesn't make any sense.

---

That being said, I agree that the state machines should be better documented. Back when they were integrated into CBA, it was not possible to make pull requests to a project's wiki. I'm not sure if that's possible now.

[mwpowellhtx]

@BaerMitUmlaut Appreciate the response.

| "list of anything over which the state machine will run (type needs to support setVariable)"

Are we talking ARRAY of ARRAYs? This would be ideal in my situation. Or strictly objects? namespaces? Things of this sort? For instance, in my case, I've got some data, elements which I want to operate on, in a form as such. I would have to experiment, do arrays support setVariable, if that is the hard requirement, then. Or maybe we translate that to a namespace, or CBA namespace... Just trying to understand the target of each statemachine iteration, cost/barriers getting started with it.

[
  [...]
 , [...]
 , [...]
 , [...]
]

So, to clarify, scope of the running machine is "per element in the ARRAY", let's say.

I gather, then, keys to better understand CBA statemachine are probably the add state and add transition functions. With configuration based, etc, being distillations of the same.

One thing that confuses me, why bother with onState at all, versus onStateEntered or onStateLeaving, versus onTransition, for that matter. The examples do mention, onTransition could be in onStateEntered, rather. I'm not sure what the difference is, timing wise, or side effects. This is where a slightly more illustrative example would be extremely helpful.

[BaerMitUmlaut]

I would have to experiment, do arrays support setVariable, if that is the hard requirement, then.

Or you could just look at the documentation of the command. You cannot use setVariable on an array.

So, to clarify, scope of the running machine is "per element in the ARRAY", let's say.

Yes.

One thing that confuses me, why bother with onState at all, versus onStateEntered or onStateLeaving, versus onTransition, for that matter. The examples do mention, onTransition could be in onStateEntered, rather. I'm not sure what the difference is, timing wise, or side effects. This is where a slightly more illustrative example would be extremely helpful.

onState is executed every time the state machine checks the state of the current element (also called a tick), whether a transition happens or not. With one element in the state machine list, that happens every frame, with two elements every second frame and so on. onStateEntered and onStateLeaving execute side effects regardless of the transition that happens. An example would be the unconscious state in ACE medical, where you want the unit to be in an unconscious animation wether it bled out slowly or suddenly received major damage, which are two different transitions. onTransition happens during the transition, onStateEntered when you are already in the new state, which is also indicated by its tense. They have different use cases as mentioned above, but are exchangable in the example code.

The complete timeline of a state machine tick with a transition: onState -> onStateLeaving -> onTransition -> onStateEntered.

[commy2]

Are we talking ARRAY of ARRAYs?

You can't have a 2d-array as list, because the sub-array elements don't have a namespace in SQF.

[mwpowellhtx]

@commy2 Well, to be clear, not 2D arrays, per se, so much as a predetermined tuple pattern, heterogeneous array shape, in SQF language verbiage.

Appreciate the feedback.

[commy2]

Well, to be clear, not 2D arrays, per se, so much as a predetermined tuple pattern, heterogeneous array shape, in

Those are 2d-arrays. Tuples are not a thing in SQF, so I would avoid using that word.

[mwpowellhtx]

It's a pattern, depends on the lens you use.

[commy2]

No abstraction will get you away from the fact that [[...], [...], ...] is a 2d-array.

[mwpowellhtx]

@commy2 Think outside the box, friend. No, that's not a "2d" array. Arrays are by definition heterogeneous in SQF. Additionally, if you choose to abstract it, can be shaped like anything. That's it. Plain and simple. 🍻

[commy2]

Arrays are not typed, but that is irrelevant. [[]] is a 2d array by virtue of containing only array type elements as members. And to get to the original point, these members have no namespace, thus are not suited to be part of the statemachine list.

[mwpowellhtx]

Example, spec in the form of:

ident = [markerName, markerText];
timer = [duration, startTime, elapsedTime, timeRemaining];
capability = [supplyCap, ammoCap, fuelCap];
queue = [supply, supply, ammo, fuel, ammo, supply, ammo, ...];
productionElem = [ident, timer, [capability, queue]];
production = [productionElem, ...]

Think outside that 2d box... It might prove liberating.

But to be clear, not arguing here for array usage in CBA statemachines. CBA namespaces are perfectly acceptable for that purpose.

[commy2]

I am refering to the example you have here:

[
  [...]
 , [...]
 , [...]
 , [...]
]

This is a 2d-array: an array of array.

[mwpowellhtx]

Yes, in my initial assessment sizing up the cost/barriers to CBA statemachines, would be operating on; i.e. statemachine takes a list of something, apparently supporting get/setVariable:

production = [productionElem, ...]

But since that is not possible, no big deal working with server side CBA namespaces.

Just besides, arrays get deconstructed all the time, the params operator, for instance. From what I know about tuples, that's a prototypical tuples thing to do.

Neither here nor there; CBA statemachines question sorted vis-a-vis CBA namespaces.

[commy2]

Fair enough.