Ex Machinis is a multiplayer space game, which takes place in a parallel universe. Within this altered reality, space technologies have rapidly advanced since the 1950’s to the point where extensive interplanetary industries exist to produce materials that drive the human economy back on Earth and Mars. The vast majority of these spacecraft and are unmanned vehicles, which are assembled in space and are controlled terrestrial barons.

As part of the international agreement that drove the colonization of space at the end of the second world war, citizens of the signitor nations are guaranteed access to basic spacecraft which can be used to build profitable businesses. This democratization of space has been the biggest driver behind the rapid growth of extraterrestrial industries and technologies.

It's your birthright to take control of your own remotely piloted spacecraft and build a thriving stellar industry. But this can only be accomplished by programming your spacecraft to efficiently mine, manufacture, and trade materials on the interplanetary economy.


Joining the game

Joining the game is simple and free. When you register with Ex Machinis, you'll receive an email from the registrar listing the addresses of three spacecraft that are under your control. These spacecraft will only respond to communications from the email address you used in your registration form.


Renaming your spacecraft and your company

You’ll notice that each of your spacecraft has a rather generic and unremarkable email address like SN523854@advolition.com. You’ll probably want to give them more memorable name like “hero” or "scout" before proceeding futher.

To rename your spacecraft, simply send the following text in an email to your drone:

<rename>hero</rename>

You’ll actually receive a response from hero@advolition.com confirming the name change. You can now send your instructions to this email address instead of the original!

You can also change your company name at anytime by emailing a rebrand instruction to one of your drones:

<rebrand>Avalon</rebrand>

This will immediately change the name of your company in the company directory.


Sending your first command

Most of the game is played via direct email communications with your spacecraft. When one of your ships receives an email from you it will interpret everything between the <run> </run> brackets as FORTH code and respond to you accordingly via email.

FORTH is an amazingly simple but highly flexible programming language that grows out of a few core interpreter functions. In fact, the version of FORTH, which is currently installed in each of your spacecraft, is described in around 200 lines of game-side C code. We'll be introducing you to components of the FORTH programming language as we proceed through this tutorial.

For now, try sending the following text to one of your spacecraft and see what happens. Just make sure you retain the spaces between the numbers, the plus sign, and the period, which instructs the spacecraft to report the result.

<run>
  2 3 + .
</run>

You'll receive an email from your spacecraft that reports the result of adding two and three together.


Understanding the stack

You may have noticed that FORTH has a strange way of doing math. In FORTH, the numbers come first followed by the operator (2 3 +). This is because FORTH relies on a data stack to transfer values to and from functions.

For example, when you enter "2” and “3” seperatred by a space, FORTH places a 2 and then a 3 on the data stack. You can visualize this as a stack of dishes in which the number 2 plate is laid down first and the number 3 plate is placed on top of it. Consequently, when objects are removed from the stack the topmost value is removed first (3) and then the next value (2).

When you call a FORTH function, like addition (+), it removes the top two values from the stack (2 and 3), adds them together, and returns the result (5) to the stack.

Similarly, calling the print function (.), pulls a value off the stack (5) and adds it the output stream, which is returned to you in an email as "5".

All FORTH functions behave the same way, by removing and adding values to the stack. This is why FORTH is a stack-based language. It’s also why FORTH is a very efficient and intuitive programming language.

Understanding stacks is the key to learning FORTH and programming kick-ass spacecraft in Ex Machinis.


Performing protocols

Every physical action your spacecraft takes will result from calls to predefined protocols. Protocols enable your drones to do things like mine resources, manufacture products, and travel between locations. In many cases, protocols use, deplete, and produce reseources located in your ship's hold.

You can find a complete list of protocols on the website. Right now, your choice of protocols is very limited. That's because we've just created a few simple protocols to test game mechanics. However, as the game matures, the number and complexity of these actions will increase dramatically.

Protocols are invoked by sending your drone a FORTH script that calls upon the "perform" function. This function pulls one or more paramaters from the stack. These paramaters provide the ID for the protocol you want to perform and any other parameters that are required by the protocol.

For example, if you wanted to move your spaceraft (Protocol ID = 5) to Saturn (Object ID = 6) you would send your spacecraft the following message:

<run>
  6 5 perform
</run>

And as quick as that, your spacecraft will be at Saturn! Give it a try and see what happens. You'll notice that your drones always report their current location at the top of every email they send you. This location will now indicate Saturn.

You can use this command to go elsewhere in the solarsystem as well. All you need is the Object ID for your destination. This can be found in the Space Objects table.


Putting it into words

FORTH makes it very easy to define and apply new functions on the run. In FORTH, functions are known as words and they'll be added to you're spacecraft's dictionary as soon as you define them. Once in the dictionary, they can be invoked in any future script you send to your drone.

A FORTH definition consists of a colon followed by the word you're defining and then the values and words that comprise the definition. The definition ends with a semicolon. Here's an example of how you can define a word that returns your spacecraft to Earth (Object ID = 3).

<run>
  : come_home 3 5 perform ;
</run>

Now, whenever you want to call your spacecraft back to Earth you simply need to send it this command.

<run>
  come_home
</run>

Here are some things to keep in mind when defining a new word:

Your word can contain any characters other than white-space characters. This is becuase FORTH uses whitespace to seperate words and numbers from one another.

Because whitespaces seperate words and numbers, it's important to include spaces between all your programming elements, inludein colons and semicolons. In the above example, FORTH will interpret "perform;" as a single word if the space is omitted.

You can pass values to a word by placing them on the stack. In other words, anything that's on the stack when the word is called can be pulled from the stack by one of the words that are called from within the definition.

For example, suppose you wanted to define a more general movement command. You could create a new word uses the last number placed on the stack as the Object ID:

<run>
  : go_there 5 perform ;
</run>

Now you can send your spacecraft to Jupiter (Object ID = 5), or any other location, by placing the destination's object ID on the stack before invoking your new command:

<run>
  5 go_there ( go to Jupiter )
  3 go_there ( go to Earth )
</run>

Getting out of trouble

It's definately possible to break your drone by sending it code that puts it into an endless loop or damages an important part of its memory. In these cases your spacecraft will become completely undresponsive to subsequent <run> commands. However, it's not hard to recover from these situations if you know what to do. Here are two metacommands that can resue you from almost any software crash:

Sending "<abort>" to your spacecraft will cause it to imediately terminate any currently active code, allowing you to break it free from an endless loop.

Sending "<reset>" to your drone will not only stop any active scrpts, it will also reset your spacecraft's internal memory to its "factory setting," erasing any damage you might have done to it's internal memory. This metacommand will also erase any words or variables you defined earlier. But sometimes its good to start with a clean slate.


Learning more about the game

Your spacecraft can perform far more complex computations than those described here. While many of the basic functions have been highlighted in this quick start guide, we’re also developing a more complete Player’s Manual, which will cover every aspect of the game in greater detail. The Player’s Manual is available to our sponsors who support this project with a monthly contribution of $2 or more. If you like what we’re doing with Ex Machinis, please consider following us on Patreon and lending your support to the project.