/
Featured Blog

# A Tutorial to Machinations Diagrams

Want to learn more about how Machinations Diagrams work? In this tutorial I modelled a resource management game using Machinations diagrams.

Thanks to a feature on Gamasutra by Ernest Adams and Joris Dormans and their book Game Mechanics: Advanced Game Design (Voices That Matter) I discovered the fascinating world of Machinations diagrams. This tool really blew my mind because it provides game designers with a powerful new weapon of choice for analysing, prototyping, communicating and testing game mechanics without having to write a single line of code. That's great because I am not a coder. Even better: I many cases I do not need a coder anymore for a first game mechanic prototype.

I had a first go with Machinations and modelled a simple resource management game. The basic action is to claim tiles of an imaginative game map in order to gather the resources you need to grow your population, food, building materials, tax income and military strength. The aim of the game is to destroy all of your enemy's defence bots, while preventing the enemy from destroying yours.  It's still pretty rough around the edges and I am sure many things could be done in a more elegant way. However, it helped me to learn how the single Machinations elements work together.

How to play:

1. To start click the Run button in the top left corner of the frame.
2. You can then interact with the double-lined elements.
3. Start with building a saw mill, a farm, refurbish houses and then claim your first tile.
4. In the early game grow your population fast and try to keep up the food supply by building farms.
5. You might then want to consider building a factory and kill some of the food stealing evil monkey. Have fun!

## Step-by-step walkthrough

I am going to describe the diagram step by step and also explain the meaning of the different elements I used.

### Claiming a tile

Let's start with the most essential action of the game: claiming tiles to increase your resource income. Each tile contains four types of resources:

1. Derelict houses
2. Fields
3. Wood
4. Iron

Each tile also contains a bad surprise: evil monkeys! More about them later. The "claim tile" converter element in the centre of the diagram is your starting point. It's the triangle pointing right with the vertical line running through it. Elements with a double line are interactive. Clicking on it triggers multiple events:

1. The "claim tile" converter pulls 100 resources from the credits pool and converts them into 20 resources, which move towards the diamond shaped gate element. The "&" next to the converter tells you that its pull mode has been set to pull all. This makes sure that the converter only pulls resource from the credits pool when it contains at least 100 resources.
2. Gates redistribute incoming resources, in this case randomly via the outgoing resource connections, which lead to the four main resource pools for derelict houses, fields, wood, and iron. The numbers next to the resource connections define the maximum number of resources each connection can transport during one interval. In this case between one and five resources can move through each of the four connections leaving the gate. This is because the resources move through a random gate, represented by the dice symbol.
3. Besides valuable resources each tile contains also evil monkeys who will steal your food! The resource connection  that connects the "claim tile" converter with the "evil monkeys" pool transports a random number of evil monkeys when you claim a tile. The connection is labeled "D3" which means that between one and three monkeys emerge from each tile. The "D" stands for "dice". The more tiles you claim, the more evil monkeys will steal food from your storage from time to time.

Let's move on and see what happens with the four basic resources.

### Houses

When you click the "refurbish" converter credits, building materials and derelict houses are pulled from their resource pools. Five derelict houses are then converted into a random number of refurbished ones. The resource connection is labelled "3D2" (the sum of three rolls with a two-sided dice). This let's the converter push a between three and six resources to the "refurbished" pool. The refurbish converter's pull mode has also been set to pull all. Since the converter has three inputs (from the credits, houses and building materials pools) it is important that it only starts to pull resources when all inputs can provide the required number of resources. Lovely empty houses now gather inside the "refurbished" pool. From there they move through another converter into the population pool. People are moving into their new homes. The resource connection between the "refurbished" pool and the "population growth" converter is labeled with "1/3". This means that the "population growth" converter pulls one resource every three intervals. It then turns one refurbished house into two people, or rather two people move into one house. The population pool itself has multiple effects on other parts of the game system:

1. The greater your population, the higher the food consumption per interval. This is done by using a label modifier in form of the dotted red line that connects the population pool with the green resource connection that runs from the food pool to the consumption drain. The initial rate at which food is being consumed per interval is set to zero. Each new inhabitant increases the consumption rate by 0.1. For example, if you have a total population of ten, one food resource is consumed per interval.
2. With your population also your XP points increase. In this case I do not want to move resources from one pool to the other. And this is where the node modifier comes in handy because it links the values of both pool with each other without any exchange of resources. Every new inhabitant increases the XP points by one.
3. Your population also generates tax income. The corresponding label modifier from the population pool targets the resource connection between the tax income source and the credits pool. Each resource inside the population pool increases the tax production by 0.2 per interval. But there is a catch: there has to be food!

### Food

Food is a renewable resource that grows on fields and has to be harvested by farms. If there is no food your population neither moves into refurbished houses nor does it put credits into your pockets. In order to build a farm you need a fixed number of fields, building materials and credits. If you have all the required resources the "build farm" converter turns the incoming resources into one farm. You need to build at least one farm to meet the condition stated on the activator that connects the farms pool with the "food" source. The food source is marked with an asterisk, which means that its activation mode is set to automatic. Once activated resources move automatically to the "food" pool. New food is produced every three intervals in quantities between five and eight. The dotted green label modifier that runs from the "farms" pool to the resource connection increases the food output by two per farm. If the number of resources inside the "food" pool is greater than zero the outgoing state connection activates the "population growth" converter and also the "tax income" source. Furthermore, the "food" pool is connected to the "monkeys steal food" drain that is activated as soon as the number of resources inside the "evil monkeys" pool is greater than zero. If you do not keep those evil monkeys under control they will severely diminish your food resources.

### Building materials

Before you can build up your army of attack and defence bots to deal with the evil monkeys and the ever growing threat of an enemy attack you need enough building materials to create a factory. As you already know you need materials for the other buildings as well. So keep the wood flowing in by claiming new tiles! There are no elements in the wood mechanic that I haven't described before, so I keep it short and just summarise the mechanic itself. Each claimed tile contains a random amount of wood. In order to turn the wood into building materials you need at least one saw mill. Saw mills cost credits and wood to build. The more saw mills you build, the more wood is turned into building materials every five intervals. This makes time much more important! Five intervals (= five seconds) can be a long time when you urgently need to refurbish houses to increase your tax income in order to increase your military strength. I also added a converter that turns one wood resource into two building materials. For example, this converter could later be used to implement upgrades that make saw mills work more efficiently and let them produce more building materials per wood resource.

### Factories

Factories produce attack and defence bots. Building factories is straight forward but expensive: besides a lot of credits you need iron and building materials. Once you have built your first factory you can start creating up your bot army. The "iron" pool provides resources for both building factories and attack/defence bots. The interactive "build factory" converter turns five iron resources and 200 credits into one factory. The "factories" pool activates the "build attack bots" and "build defence bots" converter as soon as you have built your first factory. Each factory doubles the number of bots produced per click and also the rate at which they are produced. I use a "queue" pool to delay the actual delivery of the bots (I have not figured out yet how to use the delay element properly). The queue pools' activation modes are set to automatic (*) and their pull modes are set to push any (P). Both the defence bots and attack bots pools are connected to an End Condition: the execution of the diagram stops when the number of resources in any your bot pools equals zero. In that case you have lost the game.

### Attacking and defending

The battle feature is very simple but serves the purpose to add win/lose conditions to the game: you win if you can destroy all of the enemy's defence bots. You lose if the enemy manages to destroy all of your defence bots or if you run out of attack bots while attacking either the evil monkeys or the enemy defence bots.

#### Evil monkeys

Below the diagram's centre you see two interactive gate elements. One is labelled attack evil monkeys, the other attack enemy. You want to deal with the evil monkeys early on in the game, because they continuously steal food and can disrupt the flow of incoming tax credits and population growth. Clicking on the attack evil monkeys element triggers the following events:

1. Two dotted black trigger connections run from the attack button to two resource drains. Since both connections are labelled with asterisks, they activate both drains simultaneously when you click the interactive gate.
2. When activated the drain pulls a random number of evil monkeys into their graves. The red label modifier from the attack bots pool increases the number of killed monkeys by 0.5 per attack bot.
3. Vice versa, a black label modifier runs from the evil monkeys pool to the destroyed attack bots drain. The more evil monkey there are, the more attack bots get destroyed per attack. However, your attack bots are stronger.

#### Fighting the enemy

Attacking the enemy or defending against his attacks has an additional condition attached to it: The label of the red activator that runs from the attack bots pool towards the interactive attack enemy gate sets the condition under which the gate is activated. You need more than 20 attack bots to be able to attack the enemy. However, the enemy also needs more than 20 attack bots before he can attack you. Let's take a closer look at the enemy. In a more advanced iteration of this diagram the enemy would be an artificial player using exactly the same mechanics of tile claiming and resource management. However, to speed things up at this stage I simulated the enemy in a very simple way:

1. The Enemy source automatically produces between one and three bots every ten intervals (= ten seconds).
2. The bots then move through a random gate where each bot has a 50% chance to become either an attack or a defence bot.
3. The enemy's bot pools are also connected to end conditions: if the number of resources in one of the pools equals zero you have won the game.
4. The enemy attack bots pool activates an automatic gate ("enemy is attacking") if the number of attack bots is greater than 20.
5. The "enemy is attacking" gate triggers the "destroyed bots drains" on both sides.
6. As long as the condition for activating the automatic gate is true (the enemy needs more than 20 attack bots) a random number of bots are pulled by the drain every ten intervals and thus get destroyed.

On the one hand this mechanic gives you enough time go get your resource incomes sorted before the enemy attacks, but on the other hand, once the enemy is strong enough, your defence bots will be under constant pressure. If you want to win the game you have to attack yourself! In order to attack the enemy you need 20 attack bots yourself. Only then the "attack enemy" button is being activated by the activator running from the "attack bots" pool to the "attack enemy" button. There is also another option: if you collect enough XP points by growing your population you can upgrade your attack or defence bots. Each upgrade level will cause the enemy to lose two additional bots per round.   That's more or less all there is to this example diagram. I hope you find it useful!

### Latest Jobs

#### Glowstick

Remote
1.18.23
Mid to Senior-Level Unreal Developer - Glowstick

Remote
1.19.23
Senior Producer

#### Night School Studio

Los Angeles, CA, USA
1.09.23
Level Designer / Scripter, Games Studio

#### Fast Travel Games

Hybrid (Stockholm, Sweden)
1.09.23
Social Media / Community Manager
More JobsÂ Â Â

#### Game Developer Job Board

Browse open positions across the game industry or recruit new talent for your studio