Xorballs reference manual

Introduction

 Xorballs is a puzzle game with balls on a field. The field has a wall around it with a gate on each of four sides. One or more balls will enter through one or more gates and the challenge is to get the ball(s) out through the right gate. You play the game by placing tiles onto the field. When you've placed your tiles, you press the play button in the upper right to start the balls. The placed tiles affect those balls that enter the spots in which the tiles were placed and the goal is to place the tiles such that they have the desired effect on the balls.

Challenge

 A challenge is defined by a description of which balls will enter through which gates and which balls should exit through which gates. This is depicted by a little image in the upper left hand corner. The actual description of the challenge is displayed when you hover the mouse over the image.

In addition to this, an example input is displayed together with the correct output for this input. Getting the correct output for the example input doesn't necessarily mean you pass the challenge. In order to test your solution, other inputs may be tried and if your solution fails any of them, it will be displayed as the new example input.

You can try as many times as you wish and you don't lose anything for trying. Whenever you solve a challenge, the next challenge gets unlocked. An overview of all the challenges is shown on the lower left. It shows which challenges are unlocked and which were completed. You can click on any of the unlocked challenges to try that challenge again. Tile placement is stored per challenge, so any time you go back to an earlier challenge, you will find the field the way you left that challenge last time you tried it.

Ball movement

 When you hit play, the first ball of the example input will start moving into the field. While balls are moving the play button is turned into a stop button. If you press the stop button, all balls will immediately be removed, no further balls will enter and everything will return to its original state. The speed with which the balls move can be adjusted with the slider below the play button.

The side from which an input ball will enter is determined by the arrow on the input ball. Though the arrow indicates the initial moving direction and not the entrance gate.

Input balls enter one at a time and the next input ball only enters after all balls have left the field. This means that if balls keep moving forever, you don't have a correct solution, even if the output is correct.

=
If a ball leaves through a gate, it is considered an output ball and if it runs into a wall it simply disappears without generating any output. The order in which balls from the same input leave the field only matters for balls leaving through the same gate. This means that the output is still considered correct if the order of the output balls differs only between balls of different directions for the same input.

Tile placement

 An unlimited supply of each unlocked tile is available on the left of the screen. You place a tile onto the field by dragging it there from the left. Once a tile is in the field, you can move it somewhere else by dragging it again. Tiles can be removed simply by dragging them anywhere outside the field. If you drag with the right mouse button, a copy of the tile will be created and moved while leaving the original in place. You can select multiple tiles by dragging a box around them. Once selected, you can drag all selected tiles by dragging any one of them. If a tile is placed on top of another tile, the original tile is replaced by the new tile.

Although it is possible to move tiles while balls are moving, this can never be part of the solution to a challenge. A solution is always a single placement of tiles.

Basic tiles

There are 22 basic tiles. As challenges are solved more and more of them are unlocked. The behavior of each one is described below.

Turn left changes the direction of any ball by 90° counter clockwise
Turn right changes the direction of any ball by 90° clockwise
Mirror changes the direction of any ball by 90°; clockwise if the ball was going up or down, counter clockwise if the ball was going left or right
Mirror changes the direction of any ball by 90°; clockwise if the ball was going left or right, counter clockwise if the ball was going up or down
Left directs any ball left
Up directs any ball up
Down directs any ball down
Right directs any ball right
Split. For each ball entering, two balls leave. One takes a 90° clockwise turn and the other takes a 90° counter clockwise turn.
Split left. For each ball entering, two balls leave. One continues in the same direction and the other takes a 90° counter clockwise turn.
3-split. For each ball entering, three balls leave. One continues in the same direction and the others takes a 90° clockwise and counter clockwise turn.
Split right. For each ball entering, two balls leave. One continues in the same direction and the other takes a 90° clockwise turn.
Filter blue leaves blue balls unchanged and removes any other balls
Filter red leaves red balls unchanged and removes any other balls
Filter yellow leaves yellow balls unchanged and removes any other balls
Filter green leaves green balls unchanged and removes any other balls
Paint blue changes the color of any ball to blue
Paint red changes the color of any ball to red
Paint yellow changes the color of any ball to yellow
Paint green changes the color of any ball to green
Alternate These two tiles form a pair. The first makes balls take a counter clockwise turn and then turns into the second. The second makes balls take a clockwise turn and then turns into the first.

Tiles affecting balls

 When a ball enters the space of a tile, the tile can change the ball's direction and/or color. It can also remove the ball entirely or introduce new balls. When multiple balls enter a tile at the same time, they are processed one by one in the following order:
  1. from the left,
  2. from the bottom,
  3. from the right,
  4. from the top
If multiple balls would leave a tile at the same time in the same direction, instead they leave one by one in the order they were output by the tile.

Custom tiles

 At some point the possibility is unlocked to build custom tiles. Building a custom tile works the same way as solving a challenge. Multiple fields can be created and managed and each field has an associated custom tile that can be placed in any field. The behavior of a custom tile is determined by the output that a certain field generates for given input. But when used as a custom tile all output is considered to be produced instantly the moment a ball enters as input.

3x
The fields that produce the custom tiles are managed on the right side of the screen. One field is always the active field. That is the field that is being manipulated in the main part of the screen. Any other field can be activated by clicking on its row on the right. Above the list of fields there are four buttons:
New inserts a new empty field before the active field
Copy inserts a new field before the active field that is a copy of the active field
Trash removes the active field. If other fields use the custom tile associated with this field, the user will be asked if the field should really be removed. If the user confirms, the associated custom tile will be removed from each field and then the field will be removed.
Move up moves the row of the active field up in the list
Each field row has its associated custom tile on the left. From there you can drag it onto any field. You can even drag it onto the field it is associated with. This allows for recursive solutions and this works as long as the recursion isn't infinite. Infinite recursion is detected and causes a solution to fail.

Each field has a name which can be edited by clicking on it. Just below the four buttons there is a search box. If you enter a text into this box, the list of fields is filter to only show fields which contain the entered text in their name.

Copy/paste

Fields can be copied and pasted between different challenges with Ctrl+C and Ctrl+V or the equivalent key combination of your operating system. Ctrl+C will copy the currently active field and its dependencies onto the clipboard. Ctrl+V will paste the field on the clipboard as a new field into the list of fields. When a field is copied into a challenge that doesn't support all the necessary basic tiles, an incomplete version with just the available tiles will be inserted.

Input

If you want to test a field with input other than the example input you can click on the bar above the example input to change the input mode to custom input. This allows you to choose a color and direction before you hit play.

Stars

 When a challenge is solved, a number of stars is awarded. The number of stars only depends on the number of tiles used to solve the challenge. Tiles used to make a custom tile are counted once, no matter how often the custom tile is used.

Three stars are awarded for a solution that uses the minimal number of tiles necessary in the best known solution. The boundary between one and two stars is determined somewhat arbitrarily per challenge. Four stars are awarded for a solution that uses fewer tiles than the best known solution. If you manage to get four stars for a challenge, please let me know.

The total number of stars collected for all solved challenges is displayed in the upper right.

Export, save, load

Export

Exporting is a way to share a solution with others. When you click the export button, the currently active field and all its dependencies will be encoded into a URL and that URL will be opened in a new window. You can then copy the URL and share it with others. When the URL is loaded, a version of the game loads with just the challenge from which you exported it, showing the exported solution. If changes are made to the solution they will be reflected in the URL which can then be shared again.

Save to file

When you click Save to file, a download will be offered with the entire state of the game. This includes all solved challenges and your solutions to them. You can use the Load from file button to restore the game state from any such file.

Save to Google

When you click Save to Google you will be prompted to sign in with your Google account and allow the game to know you email address. This will then be used to store your game state on the server. When you click Load from Google the game state associated with your email address will be loaded and restored from the server.

Feedback

 If you have anything to share or to ask, please come to the Google+ community.