Using the Level Editor

Here are some notes about using the level editor built into 555-BOOM!

This is for version 0.5, the last submitted competition entry version. Some of the less desirable details of how the editor works may change in a later version, so don't get too attached to its quirks.

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:

New Level: Starts editing a new, empty level.

Edit Level: 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: Prompts for a level file to open and starts editing that level.

Save Level: 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: 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 column of editing controls at the right and no status bar at the bottom. You can use the space bar to hide and show the editing controls, allowing you to edit parts of the level that would otherwise be obscured by them.

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.

Wire Palette: For selecting a colour of wire. Choosing one of these automatically switches to the Wiring Tool.

Parts Palette: For selecting a type of part to add. Choosing one of these automatically switches to the Addition Tool.

Flip Horiz, Flip Vert, 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.

Start Time, Deadline: Clicking on these fields will open a dialog box for editing their values. Note that the time is entered in 24 hour format, unlike the way it is displayed during play.

Tyger 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. (A common mistake is to forget you're still using the addition tool and try to select the part you just added, thereby adding a second unwanted part. I'll try to make this less likely in a future version.)

Using the selection tool, you can select one or more parts and drag them around the screen. (Note: dragging a rectangle to select multiple parts is not implemented yet; you'll have to shift-click.)

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

Some types of parts can have their orientation changed using the Flip Horiz, Flip Vert 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. Start by clicking on a terminal of one of the parts; a rubber-band line will appear 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. 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 intermediate wire points and move them around. However, if you click on a wire point that's within the bounding rectangle of a part, it will select the part instead of the wire point. To overcome this, Alt-click (Option-click on the Mac) on the wire point. This selects wire points only, ignoring parts. (Note: I will probably change the selection priority in a future version so that you don't need to do this.)

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 on a connected wire endpoint and then drag, a new point is inserted into the wire between the endpoint and the next point, and you end up dragging the new point. You can use this technique to add extra corner points to a wire. Note that currently it only works on connected endpoints, not unconnected or intermediate points. (I'll probaby fix this in a future version so that it works on all wire points.)

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.

There's currently no easy way to split a wire in half – you just have to delete back from the end and then add a new wire.

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 extend a wire by clicking on an unconnected endpoint with the wiring tool. The new wire will assume the colour of the wire being extended rather than the colour selected in the wire palette. This is because you're not really adding a new wire, you're just making the existing wire longer.

Note that this only works when you start from the end of an existing wire and the existing end is not connected. You can't start a new wire somewhere else and then finish by connecting it to an existing wire – you'll end up with two separate, unconnected wires, even though they may look like a single wire.

Joining wires together

It's not possible to join a wire directly to another wire (except where extending a wire as described previously). However, you can add a Junction, which is a part consisting of a single terminal, and connect the wires to that.

You can also 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.

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. If you Alt-click and then drag the part, however, 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.

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, left to right and top to bottom.
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.

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.