When a PRState derived object is first created it has no state, which means that none of the added states are the current state. In order to set the current state, use the PRSetState() method like so:

PRSetState("Idle")

The above command sets the object's current state to the "Idle" state added previously. It is a good idea to set the object's initial state after adding all of the states in the Create event. You may also change an object state at any point during your game, typically in response to an event of some kind (like the player pressing a joypad button) or an object collision.

If you need to set no state on an object for whatever reason, call the PRSetState method with noone for the state name parameter:

PRSetState(noone)

This results in no state implementation code being run for that object at every frame update.

There is a convenience method included in PRState that allows you to easily switch from the current object state to the state the object was in prior to the current one. And that method is:

PRSetPreviousState()

This method call simply sets the current state to the object's previous state. All of the same steps that occur when using the PRSetState() method are followed with PRSetPreviousState() as well. See below for more info.

When setting an object state, there are a couple of things that occur. The first is a check that determines whether or not setting that new state from the current state is legal or not. If you haven't defined any "valid from states" for a given state, then setting the new state will always be legal. If setting the new state from the current state is illegal, then the state will not change.

The next thing that happens is that the object's current state implementation method is called with its mode parameter set to PRSTATE_MODE_END. This gives the current state a chance to perform any cleanup code necessary before the new state is set.

And finally, the last thing that happens is that the new states's implementation method is called with its mode parameter set to PRSTATE_MODE_INIT. This is a very convenient time for the state to perform any needed setup code.

Once the above steps have completed, the current object state will have changed to the new desired state.

When setting a state using the PRSetState() method, you can optionally provide up to 3 pieces of data of any type. For example:

PRSetState("Jump", myValue1, myValue2, myValue3)

In the above command, the values in myValue1, myValue2 and myValue3 are passed to PRSetState and stored. In your state implementation method or function, you can query those values via the following methods:

var data1 = PRGetStateData1()
var data2 = PRGetStateData2()
var data3 = PRGetStateData3()

This can be useful if you need certain key pieces of data for your state implementation code to function properly. For example, continuing with our hero character example from earlier, you can issue the following command from your character's "Run" state:

PRSetState("PowerSlide", "Long")

As the "PowerSlide" is a valid state from both the "Walk" and "Run" states, this would be a great way to inform the "PowerSlide" implementation method that it should implement a longer slide when called from the "Run" state. Then, in your "Run" implementation method, you'd query data 1 and react accordingly:

var doLongSlide = (PRGetStateData1() == "Long") ? true : false
if doLongSlide
    // Implment long slide.
else
    // Implment normal slide.

You can print detailed state logging information to the GMS Output Window for your state derived object by turning on the state verbose feature, like so:

PRSetStateVerbose(true)

When debugging your code, this can assist you by showing you what the PRState system is doing with your object. With this feature turned on, each state change attempt will be logged to the output window to tell you which state the object is switching to, which state it came from and the 3 data values for each state.