In this article I’ll describe a tool for generating functions using state machine diagrams.
State machine diagrams are great for modeling systems, which, through various events, change the way they’re working. Mastering state diagrams is very easy and doesn’t need a lot of time, and by also using the tool that’s described here it can produce really satisfying effects. The generator in this post was created to increase the speed of creating function packs and assure their reliability. Before I talk about using the generator, I’ll explain in short what state machine diagrams are and how to model a system using them. The simplest diagram I could think of is this one that describes how doors work. For the moment it doesn’t have any use whatsoever, but with it you can easily see how it works.
According to the picture the door can be open, closed, or locked with a key (these are the 3 possible states that the door can be in). To change the state you need to make a transition (shown on the diagram with arrows). Transitions are triggered by events. Events are described with a text next to the arrows. In more complicated systems the same event might have other influence on the state depending on the current state. The only thing left unexplained is that black dot with its arrow pointing at the “open” state. That’s how you mark which state is that first one (in our case, it’s the “open” state).
Examples of practical application
Now that we know the theory, it’s time to get to a real example. Let’s say we want to make a map, in which, the players will have two game modes to chose from – pvp and pve. The game can only be started if there isn’t already a game in progress. In the pvp game mode the players fight against each other for a fixed number of rounds, if after playing the rounds no one wins then a play-off will begin. If a winner is finally chosen then a message will appear and the game will end. The other way of ending the game is to have all players leave. In the pve mode, the players will fight against waves of mobs and it gets harder each wave. The game ends with a summary of scores when all players die. And also, similarly to the pvp mode, the game can also be ended if all players leave the server. Here are the results of what I made, based on the description above: There are a couple new elements on the diagram. Mainly, the two big states, inside which there are smaller state machines. The new elements are composite states. Their operation is very simple – if you go into that state then you’ll cause the state machine inside of it to start working. As can be observed on the example picture above, if there’s a pvp or pve game in progress then, additionally to that, functions that are responsible for the operation of the smaller state machines will start running. If you exit the composite state and come back to it again then the state machine that is inside of it can act in two different ways. It can either start its operation again if the starting state is marked with a black dot or it can start in the same state as it had when the operation was interrupted if the starting state is marked with a circle with the letter H inside (history state). The use of the history state can be observed below – if a player leaves the game at some point then they can expect to come back and continue from the point where they left off.
How to use the generator
The generator included in this article converts state machine diagrams saved in the .xmi format into a function pack, inside of which the whole logic of transitioning between states is programmed in. Special, empty function files will also be created (ready to get filled with commands) that get called in these situations: causing an event, exiting a state, transitioning between states, entering a state and existing within a state (which called every tick). To generate .xmi files, that the generator will use, you need to use an external program to model the UML diagram. The XMI format is standard for UML diagrams, so many tools for modeling such diagrams should have an “export to XMI” option. One of such tools is ArgoUML – a free program, which you can download HERE.
Super-short instruction for using ArgoUML
The picture above is a screenshot from the ArgoUML program. To start creating a state machine diagram you need to press the button marked on the picture as (1). Model creation comes down to dragging the elements marked as (2), (3) and (4) onto the edit field – elements that you can drag into the edit field but aren’t marked on the picture aren’t supported by the generator, so they should be avoided. To add an event that starts a transition you need to double-click the corresponding arrow and fill in the text box that will pop up. To generate the .xmi file you need to use the option marked on the picture as (5). Besides that it’s worth to save the diagram project, since reading the project from an .xmi file is quite inconvenient in ArgoUML.
Explanation of the generator’s work
- Path to .xmi file generated using ArgoUML (or other similar program).
- Path to location where the functions should be generated.
- Name of the main function pack folder (the one that will sit in the “functions” folder).
- Path leading into the folder specified in field 3.
- Name used as a prefix to generate scoreboard objective names, which will create the program.
After filling in the form, the big button titled “Generate function files” shall be pressed.
Description of files generated by the program
After generating the functions, in the main folder (generated from data given in fields 2, 3 and 4) you’ll find 5 files – _do, _drop, _init, _restart, _stop and 4 folders _states, states, _events, as well as events. In the program there’s a rule that states that files starting with “_” should not be edited. These files are responsible for executing functions at the right times, functions controlling states, as well as those responsible for transitions and events.
- The _init function should only be executed once to create the scoreboard objectives needed for the state machine.
- The opposite of the _init function is the _drop function, which deletes all scoreboard objectives.
- The _restart function should be executed at the state machine entity, using the execute command. This function sets up the initial values of the state machine and it only needs to be ran once..
- The _stop function removes the scoreboard values from the entity it’s executed at.
- The _do function should be called every tick on the state machine entity.
- You don’t need to look into the _state folder (it’s just there so the thing works, nothing too interesting).
- In the _events folder you’ll find event functions, which will occasionally need to be executed at the state machine entity in order to transition between states. Events won’t be able to run on their own. You’ll need to implement when an event should happen yourself.
- In the events folder you can put the commands that need to be ran when an event happens.
- In the states folder there are empty functions that represent states and the transitions that come out of these states. Transition names are constructed according to this example @EVENT_NAME and they represent a transition started by the EVENT_NAME event. In the folders which represent their corresponding states there can appear 3 functions – do – called every tick if the state is active, entry – called when entering the state and exit – called when exiting the state.
IMPORTANT additional comments
-You should avoid naming the states and events using names including white space characters or names starting with “_” or “@”. -When making a model in ArgoUML you need to name the entry states (black dots) and history states (circles with H inside of them). Despite the fact that those names won’t show up on the diagram, the generator is using them.
-Download the generator: UML Statechart to MC Functions -Additional files (examples): additional materials (in this file there’s an ArgoUML project used in the second example along with its .xmi file and the function pack skeleton generated by the program).