Using the 555-BOOM! Level Editor

Activating the Editor

The editor is entered by clicking the Level Editor button on the main menu screen, or by starting the game with the -e command line option.

The editor menu screen has the following options and shortcut keys. On the Macintosh, the Command key can be used instead of the Control key.

New Level Set: Creates a directory for holding a set of levels. See Creating Level Sets.

New Level (Control-N): Starts editing a new, empty level.

Edit Level (Control-E): Starts editing the currently loaded level. If you have just been playing one of the built-in levels, this will let you edit a copy of that level.

Load Level... (Control-O): Prompts for a level file to open and starts editing that level.

Save Level (Control-S): Saves changes to the current level under its existing file name.

Save Level As... (Control-Shift-S): Prompts for a file name in which to save the current level. Defaults to the previously used file for that level, if any. Note that if you edited a built-in level, you will be prompted for a new filename, so you don't accidentally overwrite the standard level files.

Exit Editor (Control-Q): Takes you back to the main menu screen. Choosing Start Level from there will start playing your level. (But see below for a faster way of testing your level.)

Editor Screen

The editor screen differs from the playing screen by having a toolbar of editing controls in place of the status bar at the bottom.

The editing tools are described briefly here; for more details, see the subsequent sections.

Tool Palette

		Selection Tool - For selecting and moving parts and wires. Shift-click selects multiple items or deselects selected items. Alt-click (Option-click on the Mac) selects wire points only. Dragging selected parts or wire points moves them around. Alt/Option-drag on a connected wire endpoint adds an intermediate point to the wire.

		Addition Tool - For adding parts to the level. Select a part type from the Parts Palette and click where you want it to go.

		Wiring Tool - For adding wires to the level. Select a wire colour from the Wire Palette and click on the points you want to wire together.

		Cutting Tool - For cutting wires and removing wire segments. Click on a wire point to split the wire in two. Click on a wire segment to remove that segment.

Wire Popup: For selecting a colour of wire. Click here to bring up a list of available wire colours. Choosing one of these automatically switches to the Wiring Tool.

Parts Popup: For selecting a type of part to add. Click here to bring up a list of available part types. Choosing one of these automatically switches to the Addition Tool.

Flip Horizontal Flip Vertical Rotate: These buttons change the orientation of the selected parts. Note that only some types of part can be flipped and rotated; using these commands on other parts will have no effect.

Edit Params: Some parts have configurable parameters; clicking this button will open a dialog box for editing them. Note that it only works on one selected part at a time; if more than one part is selected, only one of them will be edited.

Test Level: Temporarily switches the level into playing mode so you can test it. Finishing the level or pressing Escape takes you back to the editor.


Init, Dead: Clicking on these fields will open a dialog box for editing the start time an deadline time. Note that the time is entered in 24 hour format, unlike the way it is displayed during play.

Script: Clicking on this field opens a dialog for defining the sequence of actions that the Tyger follows when the deadline is reached.

Working with Parts

To add parts to the level, select the type of part you want from the Parts palette and click where you want it to go. As long as the addition tool is in use, a new instance of the part will be added for each click.

Using the selection tool, you can select one or more parts and drag them around the screen. Use the Shift key to make multiple selections. (Dragging a rectangle to select multiple parts is not implemented yet.)

To delete parts, select them and press the Backspace or Delete key.

Some types of parts can have their orientation changed using the Flip Horizontal, Flip Vertical and Rotate buttons. Note: The Rotate command works a little differently from what you might expect – if you use it twice, instead of rotating by 180 degrees, it will just change the rotation back to its previous setting. To get other rotations, use it in conjunction with flipping.

Currently only the following parts can be flipped and rotated: Uniselector, Group Selector, Distribution Frame, Relay and Bomb.

Working with Wires

Creating wires

Once you have some parts, you can use the Wiring Tool to connect them together.

As you move the wiring tool around the screen, the cursor changes according to what you're pointing at. When you're hovering over something that you can start or end a wire on, it changes from a reel of wire into a soldering iron.

Start by attaching a wire to a terminal of one of the parts. Move the mouse on to the terminal, and when the soldering iron cursor appears, click and drag. A blob of solder appears on the terminal, and a rubber-band line appears as you move the mouse around. You can click anywhere on the screen to add intermediate corner points to the wire. To finish the wire, click on another terminal (watch for the soldering iron cursor again). The rubber-band disappears and you are ready to start another wire.

You can interrupt the creation of a wire by pressing Escape during the rubber-band phase. This may leave an unconnected wire endpoint; more on how to deal with that in a moment.

Selecting and moving wire points

Using the selection tool, you can select one or more wire points and move them around. You can only move intermediate points or unconnected endpoints in this way – a wire point that's connected to a terminal is "anchored" to that terminal and won't move if you drag it.

Adding and removing wire points

Using the selection tool, if you Alt-click (Option-click on Macintosh) on a wire point and then drag, a new point is inserted into the wire, and you end up dragging the new point. You can use this technique to add extra corner points to a wire. This works with all wire points, including connected or unconnected endpoints.

Pressing Delete with a wire point selected removes that point from the wire. Deleting an intermediate point doesn't break the wire, so the points on either side remain connected together. Deleting the endpoint of a wire disconnects the wire from any terminal it was attached to and shortens the wire. Deleting the second-to-last point of a wire removes the wire altogether.

Extending and connecting unconnected wires

There's no requirement for a wire to start or end at a terminal, although an unconnected wire isn't very useful except as decoration. An unconnected endpoint can be connected to a terminal simply by selecting it and dragging it to the terminal.

You can also use the wiring tool to extend an existing wire or connect two unconnected wire endpoints together. The soldering iron cursor will appear over an unconnected endpoint, allowing you to start laying further wire from it, or to finish a wire by connecting to it. If the new wire has the same colour as the existing wire, they will be merged into a single wire. If it has a different colour, a junction (a part consisting of a single terminal) will be automatically inserted to join the wires.

You can only connect a wire to the end of an existing wire this way, not to one of its intermediate points; to create connections between three or more wires, a junction is needed. However, you can create the illusion of a T-junction between wires by having the wire go to a terminal and then double back on itself. This technique is used in many of the built-in levels.

Selecting Junctions

You'll find that it's impossible to select a junction that has a wire connected to it by clicking on it in the normal way, because you end up selecting the wire endpoint instead. If you then try to drag what you've selected, it won't move.

To overcome this, Control-click on the junction. This selects parts only, ignoring wire points.

Duplicating endpoints while moving a part

Normally, when you move a part, any wire endpoints connected to it also move, so that each of the wires stretches out from the next point back. However, if you Alt-click (Option-click on Macintosh) and drag the part, all the connected endpoints are duplicated, and the wires stretch out from the points where they used to end before.

Connecting a part to existing wires

As well as dragging unconnected wire points onto terminals, you can also drag a part so that a terminal is underneath an unconnected wire point, and a connection will be formed. You can use this technique to replace a connected part with a different part: delete the old part, add new one, and then drag the new one around to "pick up" the dangling wire ends.

Cutting and deleting wires

The cutting tool can be used to cut wires in half and delete parts of wires. The cursor changes according to what you move it over. When over a wire point, it changes to an open pair of wire cutters. If you click there, the wire will be cut into two parts at that point, leaving two unconnected wire endpoints there (you can see this because of the stripped wire ends).

When over a segment of wire between two points, it changes to an open pair of wire cutters with the word DEL underneath. If you click there, that segment of wire will be deleted, leaving any remaining segments with unconnected ends.

You can use the cutting tool together with a junction to connect a wire to the middle of an existing wire. First use the cutting tool to cut the wire at one of its intermediate points. Then select Junction from the parts list and insert one at the point where you cut the wire. The two existing endpoints will connect themselves to the junction, and then you can use the wiring tool to connect further wires to it.

If you don't get the junction in exactly the right place, select it (using Control if necessary) and move it until it picks up the wire endpoints.

Things that can go wrong

Wire points and terminals are aligned on a 5-pixel grid, which is quite small, and it can be difficult to click on exactly the right spot when adding a wire. The result is often a wire that looks very nearly as though it's connected to a terminal, but isn't quite.

One way to find out whether wires are connected to a part properly is to move the part slightly – all the connected wires should move with it. If one of them doesn't move, then it's not connected. To fix that, just select the endpoint and drag it to where it's meant to be. You'll know when it's connected, because it will stop moving as you drag.

If a circuit isn't behaving the way you think it should, and all the wiring seems to be correct, it's likely that one of your wires isn't connected properly. A useful way to debug such problems is to connect light bulbs temporarily to narrow down the problem, and then carefully examine all the connections around that area.

Hmmm... I think I may have created the world's first dry joint simulator...

Start and Deadline Times

These determine the initial clock setting and the time at which the Tyger will begin is attempt to trigger the bomb. Either of these can be left empty and the level will still work.

If the start time is empty, there will be no timekeeping during play and the deadline can never be reached; in that case, there's no way of "winning" the level, so the user is allowed to advance to the next level simply by pressing N (this is how most of the tutorial levels are set up).

If there is a start time but no deadline, then there is no time limit on the level, and the only way to finish it is to press W to trigger the Tyger into action. This configuration is mainly useful for testing – it's not intended that a level would be set up that way normally.

Tyger Script

The Tyger Script specifies a sequence of actions for the Tyger to follow when the deadline is reached. It consists of a series of commands separated by semicolons. Each command begins with a command letter, which may be followed by a parameter. The commands are:

Command	Parameter
L		Lift the handset
H		Hang up the handset
D	digits	Dial the given sequence of digits
W	no. of milliseconds	Wait the specified amount of time

There is an automatic wait of 250 milliseconds after the L and H commands. The script must not contain any whitespace or other characters.

If no bomb has gone off by the time the Tyger finishes executing the script, then you win the level.

If there is no tyger script, then there is no way to finish the level normally, so use of the N key is allowed.

If there is more than one red phone on the level, the Tyger will pick one of them, probably the first one you added to the level. (A future version may have a command for selecting which phone to use.) If there is no red phone, the tyger script has no effect.

Testing the Level

Pressing Control-T temporarily switches into playing mode so that you can test the level. While in that state, pressing Escape will take you back to the editing screen instead of the main menu.

You'll probably want to leave the level without a deadline in the early stages of development until you've got your circuit debugged. If you give it a start time, you'll be able to watch time go by and get a feel for how long it should take to complete the level. Then you can add a deadline and tyger script to give it a win/lose condition.

Part Types

Uniselector

The Uniselector consists of a 10-position rotary switch stepped by an electromagnet. Although the switch contacts are arranged in a semicircle, the rotor is double-ended, so one of the terminals is always connected. A step occurs each time the coil is de-energised for any reason. Note that this includes things like hanging up a phone as well as dial pulses.

The uniselector can be flipped and rotated.

Group Selector

The Group Selector is similar to the uniselector but has a number of differences. In addition to 10 contacts, it has an eleventh position in which the rotor is not connected to any contact. It also has considerably more complex behaviour thatn the uniselector.

In typical cascaded configuration, the rotor terminal and one of the control terminals are connected together, but there's no requirement for this, and useful effects can be achieved by using them separately.

In operation, the group selector goes through a series of states as follows:

Released	In this state, the the rotor is not connected to any contact. When the control terminals are energised, the switch enters the Seized state.
Seized	In this state, the switch is awaiting dial pulses. A short interruption at the control terminals is interpreted as such and causes the switch to enter the Stepping state.
Stepping	In this state, each short interruption will cause the rotor to step by one place. No connection is made to any of the contacts that are passed over. The switch only remains in this state as long as it receives a steady stream of pulses. If there is no interruption for longer than about 2 pulse intervals, the switch enters the Connected state.
Connected	The rotor terminal is connected to whichever contact the rotor stopped on, and further short interruptions cause no further activity. A long interruption (more than about 2 pulse intervals) causes the rotor to return to its initial position, and the switch returns to the Released state.

Group selectors can be flipped and rotated.

Distribution Frame

A distribution frame is a kind of patch panel. It consists of two rows of terminals with wires connecting each terminal in one row with one of the terminals in the other row. The connections are randomly permuted each time the level is started, so the player is forced to trace the connections each time rather than relying on a solution previously worked out.

Distribution frames can be flipped and rotated. They also have the following editable parameters:

No. of Ways	The number of terminals on each side.
Colour No.	The colour of the wires used to make the connections. The numbers start at 0 and correspond to the entries in the wire palette.
Width	Distance between the sides. Each unit of width is about 40 pixels. If the number of ways is more than about 10, you'll want to increase the width, otherwise the connections become impossible to trace by eye (unless that's the effect you're after, of course).

Relay

Relays currently come with just a simple set of change-over contacts. When the coil is energised, the centre contact moves from one of the fixed contacts to the other.

There are three varieties of relay in the parts palette: a plain one, one that is slow to operate, and one that is slow to release. The operate and release delays can be configured using Edit Params, in units of 50ms, which is the length of a dial pulse interruption. The default delay is 4 units, so a slow-to-release relay with the default setting will remain operated through a train of dial pulses.

A relay with an operating or release delay is indicated visually by a copper slug at the armature or heel end of the winding, respectively.

Relays can be flipped and rotated.

A greater variety of contact configurations may be provided in a future version.

Junction

A Junction is just a single, isolated terminal, used for connecting wires together.

Battery Terminals

Battery Terminals provide a source of power for your circuit. In order for any of the active devices to function, there must be a completed connection from one side to a positive battery terminal, and from the other side to a negative battery terminal.

Try not to allow a short circuit between two battery terminals of opposite polarity. In real life this would blow a fuse somewhere, but probably the simulation will just misbehave.

Light Bulb

Handy all-purpose troubleshooting device. Ultra long-life filament is guaranteed to last for as long as your computer stays up.

Telephones

There are three kinds of telephone – the green ones that the player controls, the red ones that the Tyger controls, and the grey ones that do random things all by themselves.

You can change whether the handset is initially on-hook or off-hook by selecting the phone and pressing the Edit Params button.

Bomb

The Tyger's favoured weapon of mass destruction. A very sensitive device, it will explode the moment power is connected across its terminals. The level will also effectively be ended at that point.

Bombs can be flipped and rotated.

Text

You can use this part to add a one-line string of text to the level. To change the text after the part has been added, select it and press the Edit Params button.

Creating Level Sets

You can save your levels directly in your Mods folder, or somewhere else, and play them individually, but you can also group them into level sets to be played through sequentially.

A new level set is created using the Create Level Set button in the editor menu. It's just a folder named with an extension of ".5bs". A folder named in this way can be selected using the Play Custom Levels command in the main menu to start playing the levels it contains.

Once you've created a level set folder, use the New Level command as before. When you come to save the level, the level set folder will be selected as the default folder to save it in.

Level Naming and Ordering

Levels are played in alphabetical order of their filenames, so you may want to name them starting with 01, 02, etc. to control the ordering. The filename also determines some other things as follows:

If the filename starts with a + sign, it is treated as a tutorial level.
When the level name is displayed, underscores are replaced by spaces, and hyphens are replaced by a colon followed by a space. The + at the beginning of a tutorial level name is replaced by the word "Tutorial".