Here is a short list of topics that will be covered in this guide:

1. Functions
   
2. Variables
   
3. Events
   
4. Common Functions
   
5. Sample Programs

Simply put, functions can be executed and they produce a result. A function can have several inputs or no input at all.

Below you can see an armoured door has 2 functions that we can drag into the programming area. First one opens the door and the second one closes it. The opening function takes a parameter as input that indicates which direction we want the door to be opened.


Inputs of a function is on the left. Outputs of a function are on the right. Just like in reading/writing, we have this left to right progression.

Objects in Mechanica have several functions. Ligts, for example, can turn on or off, can change brightness, can change their color as well. Mining equipment and fabricators can usually turn on or off. Overall, we can do a lot of useful things if we know when and how to trigger these functions to run.

Variables store data. We can use them as inputs for our functions, or the result of a function can be stored into a variable. Usually they indicate the state of the object. Below is an example where you can see the variables of a switch object in the programming area.


As you can see, variables have "Type"s. It is a common practice for programming languages to have types associated with their variables. You don't want to mix your apples with your oranges. Sometimes it is necessary to convert them from one type to another, but we will get into that later. For user friendliness, types are all color-coded. It means that a variable will only go into a function if the color of the variable is matching the color of the function's input.

Here is a list of types for variables in Mechanica:

1. Bool
   
2. Percentage
   
3. Number
   
4. Text
   
5. Color

It represents smallest logical variable, a bit. It is either one or zero, usually interpreted as True or False respectively.
Type Color: RED

It represents a value between 0% and 100%. It is not a number, since numbers can go beyond 100.
Type Color: GRAY

It represents a numeric value. Negative values go as well. It does not have to be an integer.
Type Color: BLUE

It represents a string that contains a finite amount of characters.
Type Color: GREEN

It represents the color. There are several available colors to choose from.

• White
  
• Red
  
• Orange
  
• Yellow
  
• Green
  
• Cyan
  
• Blue
  
• Purple
  
• Pink
  
• Black

Type Color: ORANGE

The most important aspect of the programming in Mechanica is events. It is very important to have a good understanding of event mechanisms if you want to do your own programming.

They are "trigger"s. They initiate the functions they are tied to when the event happens.

Some objects do not have events, but most functional objects do. A timer can tell when it is a new day, when an hour has passed, etc. A miner can tell if it was a successful or unsuccessful mining attempt. A laser tripwire can tell when it is tripped.

I think it would be best to start using programming examples. Let's say you want to make a self closing door. You will need a laser tripwire, a doorframe and a door for this. Set them up like in the screenshot.


When done, use the programming tool to link the tripwire with the door (left click while looking at tripwire and drag to the middle of door, this is how you link objects so it's important to remember). Then you can simply press 'E' while looking at the tripwire. We are good to go!

Now, under the list of events, you should see On Laser Tripped. Drag it to the programming area. Under the list of linked objects, you should be able to see the door and its functions. Find "Close Door" function and link them like below.


This way you will be able to ENTER through the door and it will shut behind you immediately after you go through. If you have done all of the above, you might have noticed that you can enter with this configuration but you can not exit because you trip the laser and it shuts the door to your face. Well, wouldn't it be nice to have just enough delay to let you outside before shutting the door behind you? Then you need to enter the world of common functions!

In Mechanica, there are several useful functions that are all shared by programmable objects. They can be accessed by right-clicking the programming area. From the context menu that pops up, you can find all the common functions categorized.

I will try to cover the ones currently listed under Common Functions => Execution Control because I consider them to be most useful and easy to learn.


If you want your program to do different things based on a boolean variable, branch is what you need. Below is a fun little example. You take an on/off switch, place it anywhere, then start programming it. Now you need your program to be ran whenever the state is switched to either on or off. So you start by dragging "On switch on or off" to the programming area. Then you will need to check the current state of the switch so you drag "Is switch on" from variables section. When you do that, you right click an empty part of the programming area and select Common Functions => Execution Control => Branch. This will add a branch function. Tie the event invoked into "Run" of this Branch, and the Is Switch On variable into the condition of it. All you need to do now is to set colors on each condition. I choose red when its off, green when its on.


And voila!



One of the most useful common function. You don't always want things to happen as soon as the events trigger. Usually you need a delay in between. So wait does exactly that. If you did the self closing door example, now is the perfect time to expand your programming with a delay between laser tripped and door closed.


As you can see, the door will now let you get out before closing behind you. For different programs you can change the number below which indicates how many seconds the function will cause to delay the following function.


If you want something to happen non-stop, then you need intervals. I would not recommend to go too crazy with the interval and set it to run every 0.01 seconds. It usually messes with the logic, or it could be a bug, either way I recommend at least 0.5 seconds between each execution.

For example, if you want a light to blink every second, now you can use an interval to trigger a branch which takes "Is On" variable of the light and sets it to the opposite.




Similar to interval, but it needs to be triggered by an event and it only executes for a given number of times. If you make a program where during one of the repetitions it triggers the same repeat function, it scraps the old one and just starts over. So I suggest that if you need loops within loops, just use additional repeat blocks.

These are some very useful and easy to do programs.


There is no point for an Auto-Miner to keep trying if the resources are exhausted. To save the batteries on them, we can do this tiny program.




If you have your furnace right next to your auto-miners, you might have seen the terrible sight of having your furnace ran out of fuel while miners just keep going and pile of ores all over the place. With this little program you can tell your miners to stop mining if your furnace is not going to function.


Interval is 10 seconds since it takes about 15 seconds for a miner to finish working on an ore. So every 10 seconds we check for 2 things, furnace has fuel, furnace is on. If those conditions are met, we don't need to do anything. If any of them fails though, we can tell the furnace to shut down its linked miners.



You can arrange a laser tripwire on an incinerator like so:


Then after linking the two objects, you can write this simple program to have incinerator to start burning only when there is an object being fed into it.


The logic here isn't perfect, but it covers majority of the cases.