TriggerBool Tutorial
thanks Microwave Oven

Download the tutorial and TriggerBool files here.
Below is the full readme included with the download.

Ok, folks, here's a little tutorial to get you started with the very powerful and super-complex trigger logic combiner known as TriggerBool, written by me, Microwave. (You know, the guy who wrote TriggerBool ;)

I am assuming that you are familiar with UnrealEd, and know it's basic terminology and how to build your own maps. If you don't, well, you most definitely don't want to even try to mess with TriggerBool. It can smell your fear, and will turn on you in an instant. Basically, if you don't know what triggers are, you'll get lost real fast. To use this script, put the TriggerBool.u file into the UnrealTournamet\system directory. DON'T include it into the EditPackages section of the UnrealTournament.ini or ThAux.ini files. Instead, when you with to include the script into your map, just type "obj load file=TriggerBool.u package=MyLevel" (without the quotes) into the command box at the bottom of the UnrealEd window. This will include the script directly into the level file itself, so you won't need to include the TriggerBool.u file along with your map.

So, what exactly is TriggerBool? Well, aside from having a somewhat unusual name, TriggerBool is a powerful UnrealScript trigger that allows you to combine two trigger inputs, performing simple boolean logic upon the inputs, then outputting a single trigger event based upon the combination of the two inputs. It can be used to reformat triggers, changing a TriggerToggle event to a TriggerControl event. It can invert TriggerControl events, causing a Trigger event to become an UnTrigger event, and vise versa. It can also be used to convert a TriggerToggle event to an "UnTriggerToggle" event (I'll explain what exactly these things are further on).

I suppose you would like a little info on why exactly I wrote this script. Well, the answer is simple. I was designing a map for the excellent UnrealTournament mod known as Thievery, when I ran into a small snag. I was wanting to have an effect where the player could use a set of double doors, and have both of them open at the same time. Now, in regular Unreal, I would have done this effect by using a trigger linked to both doors, and when the player bumps into the trigger, or comes near the doors, the doors would open. With Thievery, the doors *are* triggers, and in order to behave like real-life doors, you have to "frob" the door. ("Frobbing" means to highlight an object with your cross-hairs, and activate the object with your "use" key, just like in Thief 1&2.)

Because Thievery doors behave in this manner, there wasn't an easy way to intercept the trigger command(being as it is internal to the door's script). I had two options to deal with this problem. The first was to subclass the ThDoor mover, and write some custom script to handle this particular incident. The second (and much more elegant method) was to write an advanced trigger function that would allow me to control the doors without disturbing the existing door scripts. My first attempt was to try and chain several triggers together to produce a cascading trigger event to cause the desired double-door effect. That didn't work too good. I then tried linking the doors to each other. That worked, but very poorly. So, after banging my head against the wall for a few minutes, I came upon this most elegant solution. I would make a trigger that would behave in the exact same manner as simple boolean logic circuits (well, I am an electronics tech, so it seemed simple enough of an answer). So, I began coding. Two days later, I was successful in producing a fully functional trigger script that not only would perform my required trick of opening both doors at once, but could also be used for many, many other duties.

I bet you're asking, "Boolean logic circuits? What does that have to do with doors?" Well, Boolean logic is used in every single digital device ever made. Calculators, computers, coffee makers, can openers(well, the real fancy ones do, anyway), cars, cameras, clocks, and so on. It is the founding science behind anything that can do more than just be a fancy paperweight. Boolean logic has been used to solve a plethora of problems, and has done so for quite a while now. Because of this, many problems already have a solution that has been worked out to solve it.

I would like to give more examples of boolean logic used in real life, but since so many people have written extensively on the subject, I leave it up to you to research and learn more on the subject.

So, on to the basic anatomy of the TriggerBool trigger:

The TriggerBool object resides under the Actor->Triggers category in the class browser. Just click it to highlight it, then right-click on your map somewhere to place it. Use as many as you need, they don't cost very much buy 'em :)

When you bring up the properties for the TriggerBool trigger, the only categories you need to be interested in are "Boolean" and "Events". These two menus are where all the action will take place. Everything else is for the most part ignored.

Let's go over the entries in these two menus, starting with "Events" 'cause it's a whole lot simpler.

Under "Events" are two fields:Tag, and Event. The Tag field is the name of the TriggerBool, and it's what other triggers will look for when triggering this trigger (whatta mouthful :) ). The "Events" field is the name of the object(or objects) that will get triggered by this trigger. Simple.

Now for the hard stuff. The "Boolean" menu has 12 different data fields, all of which will effect how TriggerBool operates. I will now list each, and explain what they do.

DefaultTo1: If an incoming event's object tag doesn't match either InputTag field, should the event default to Input 1 or 2? true=Input1, false=Input2.

Input1Tag, Input2Tag: The name to look for when an event comes in, used to differentiate between Inputs.

Data1, Data2: Used to preset the input data when placing the TriggerBool object, for exact state control.

InvertIn1, InvertIn2: Should the data from Inputs 1 and 2 be inverted?

InputType1, InputType2: Comes in two flavors:Toggled or Controlled. More on these later.

InvertOut: Does the same thing as InvertIn, but on the output data.

GateFunc: You get 4 choices: NOT, AND, OR and XOR. You programmer or techie types should recognize these.

OutputType: Four types to choose from:Toggled, Controlled, PassThru or Direct.

What the types of Inputs and Outputs mean:

Toggled: When the output data changes state(from true to false or back), a Trigger event is sent to all objects who's names match the Events tag. When used on an input, every time an event is received, the input data changes. Note that if InvertOut is set to true on a Toggled output, UnTrigger events will be sent instead when the output state changes.

Controlled: A Trigger event is sent when the output changes to true, and an UnTrigger event when the output changes to false.

PassThru: This behaves similar to Controlled, but any time this TriggerBool is triggered or called direct, it's output is sent, regardless of if the actual output data has changed state.

Direct: An odd type. The TriggerBool object will attempt to call the object named in Event using a proprietary function call. Send these type events only to another TriggerBool object. Otherwise, the call will fail. Direct will override any existing data present in the Inputs, but will not affect the Invert status of an input. The usefulness if this type is not quite fully known at this time, but it could come in handy. It's event handling behavior is similar to PassThru.

Now, for what the GateFunc choices do:

Here is a small table to show you how each of these four functions combine the two inputs to produce the output.

(1 = true/Trigger, 0=false/UnTrigger, x=not used/don't care)

Operation	| Input 1 | Input 2 | Output
---------------------------------------------
NOT		|    1    |    x    |    0
	    	|    0    |    x    |    1
---------------------------------------------
AND		|    1    |    1    |    1
	    	|    0    |    1    |    0
	    	|    1    |    0    |    0
	    	|    0    |    0    |    0
---------------------------------------------
OR		|    1    |    1    |    1
	    	|    0    |    1    |    1
	    	|    1    |    0    |    1
	    	|    0    |    0    |    0
---------------------------------------------
XOR		|    1    |    1    |    0
	    	|    0    |    1    |    1
	    	|    1    |    0    |    1
	    	|    0    |    0    |    0

Well, now, if you've made it this far, I'm gonna assume that you actually want to do something with TriggerBool, instead of just reading about it. For this example, I will tell you how to implement a simple set of double doors. Like I said in the introduction, this stuff is for the more advanced mappers, so I'm gonna just skip how to make a basic level, and assume you already have a map prepared, ready to put in some doors.

First, you need to create 2 ThDoor movers in whatever style you wish. Name them each with a unique Tag. Set them to TriggerControlled in their Object category. Now, add 2 ToggleBool actors to the map. I like to place them on either side of the doorway, to make it a little easier to find them. Tag them with a unique name for each. (I like to name mine the same name as my door I'm controlling, but with "Bool" appended to the name.) Now, in the Event value, put the Tag of the doors, one name per TriggerBool.

Then, in the doors' Events, put the *opposite* tag of the TriggerBool. This may be hard to understand so I'll give you a quick example of how to properly setup the Tags and Events:

Tag the doors Door1 and Door2.

Tag the TriggerBools Door1Bool and Door2Bool.

In the Door1 Event, put Door1Bool.

In the Door2 Event, put Door2Bool.

In the Door1Bool Event, put Door2 (its very important that you switch the names around like this)

The Door2Bool Event should be made to be Door1.

So far, it's been simple...it's gonna get harder now... :o

Now, in the Boolean section of the two TriggerBools, set the following fields as specified:

InputType1,InputType2, and OutputType -> Controlled

GateFunc -> AND

everything else should left at the defaults.

For Door1Bool set Input1Tag to Door1 and Input2Tag to Door2. Set InvertIn2 to true.

For Door2Bool set Input1Tag to Door2 and Input2Tag to Door1. Set InvertIn2 to true.

Now when you rebuild your map, then play it, when you frob either door, they both should open at the same time. If they don't, make sure that all fields are set correctly. This technique relies on a type of logic circuit called a "flip-flop". See a book on logic circuits for more in-depth info.

So, now you see how to put the TriggerBool script to use. The double-door trick is just a beginning...experiment with this script, and you will reach new heights in event scripting that were only previously attainable if you could write in UnrealScript.

I would highly recommend getting a book on boolean logic. Even if you don't use this script, the stuff you can learn about boolean logic will useful to you in more places than you could ever imagine.

If you have any questions about how or what something does, just e-mail me at microwav@wmis.net or try to catch me at the ThieveryUT forums.

feedback@chainsawdeath.co.uk