SOURCES AND RECEPTRONS: A BEGINNER'S GUIDE
This is a tutorial intended to teach some basics of S & R usage. Rather than teach exclusively by specific example, the aim of this guide is to go over briefly the different functions of the Act/React system so that, in theory, you can generalize to get the results that you want. This assumes basic knowledge of DromEd and assumes you have some knowledge of the working within the Object Hierarchy and saving the gamesys. There are several examples at the bottom to get you started once you get past all of the technical stuff.
Special thanks to d0om for answering a couple of my questions on the more elusive receptrons.
SOME GENERAL THINGS YOU SHOULD KNOW
Meta Properties are properties in Thief which have two advantages over what you would normally call "properties." Firstly, Meta Properties can be added and removed a little bit easier and more directly than normal properties. Secondly, a Meta Property can actually be a group of properties put together. This is advantageous because it may save time by assigning an Object a meta property (which contains a group of properties) rather than having to add 6 individual properties to this Object.
You can view a list of the existing Meta Properties in the Object Hierarchy. Open up the Object Hierarchy, then from the drag menu at the top, switch from Archetypes to Meta Properties. Here is a list of all of the Meta Properties used by LGS. To add a new one, click "Add" as you would in adding any other object. Then, assign this new Meta Property its own properties just as you would if you were assigning these properties to a normal object. It will probably be helpful to you to take a look at the existing Meta Properties and see what types of things they do. Some Meta Properties, such as FrobInert, contain only a single property, while others, such as M-PosedCorpse contain half a dozen. S & R can at times rely heavily on Meta Properties so it's useful to know how to use them. However, don't limit yourself to using Meta Properties alone.
Receptrons refer to properties in a strange manner. To see how they are referenced, go to the command window and type in list_props. Then look for a file in your Thief 2 folder called list_props. This has a list of all of the properties and how you can refer to them in a receptron.
ABOUT THE PLAYER
The player becomes an object once the game begins. However, S & R can only affect objects existing at the time its effects are created. In other words, it's difficult to affect Garrett directly with a receptron. There are different methods for getting around this, however.
The first method is to use a conversation. In a conversation, choose an action (such as Add Meta Property) and for the target object type "Player" (no quotes).
The second method is to put a receptron directly on "Garrett" in the object hierarchy and save your gamesys. Find the object "Garrett" in the Object Hierarchy and have a look at it. There are already receptrons in place here, and you can add whatever new ones you like. Note that "Player" is a specific representation of the generalized "Garrett" that manifests once the game actually begins (ie: you go into game mode in DromEd).
There are all different kinds of techniques for using S & R, so don't limit yourself. Remember that you have such useful objects as Emitter Traps, Markers, AI, and Conversations which can enhance your usage of S & R and can help you solve some difficult problems.
A "source" is in a sense a signal. A "receptron" receives a specific signal and creates an effect when it receives that signal.
Open up the Object Hierarchy. Click on the Drag menu and select Act/React Stimuli. Here is a list of all of the sources which LGS used for the Thief games. Notice that some of these sources are "categories." Naturally, anything under a given category is a subclass of that category. For example, a Weaponstim is a general stim (and can be used by itself) while a Bashstim is a specific type of Weaponstim. Here are some definitions, in case they are not self-explanatory:
When doing your own effects, it is best to create an entirely new source or "stim." Click on Stimulus in this part of the Object Hierarchy and click "Add." Type in the name of whatever stim you like. Then, save the gamesys AND the mission you're working on. You have to re-open your mission for this particular change to take effect (dunno why). Make sure you have set the gamesys in your mission (set_gamesys x.gam) before you save and re-open the mission. If you have a new stim to use, whatever new effects you create will in no way affect anything else in the game.
PART 1: SOURCES
Click on an object in your mission and go to its properties. Go to Act/React > Sources. You will now be presented with a window which is blank. This is just a window which will display all of the sources for this object. To add a new one, click "Add." Now you have a new window.
This box is on the right side of your source window. Click on it once you have specified everything else. This box, as well as the EDIT LIFE CYCLE box change depending on what you have specified for the Propogator. I will list each below based upon what you have chosen.
EDIT LIFE CYCLE
This, in a sense, is the "time" factor of the stim. This is the other box at the right side of the window. Like EDIT SHAPE, it varies with the Propogator, so I will again break it down.
PART 2: RECEPTRONS
Receptrons are the effects which are receptive to the stims. I'll go through these effect by effect. To start out with, click on an object and add Act/React > Receptrons. Now, there is window which will list all of the receptrons for that object once you add them. Click "Add."
The Object is the number of the object you are working on. The Stimulus is the stim which you want the current receptron to respond to. Min and max Intensity is the interval of sensitivity for the receptron. It is possible to have a ton of different effects using only one type of stim if you make the sensitivity interval very small for each time the stim is used (try taking a look at all of the different effects in Rogue's Honor that were created with a totalitystim). Now for the complicated part, the Effects.
Permeate into Container: Use on a container to affect all of the objects contained by the container.
FUN WITH S & R
Let's do a few trial effects just to get you more comfortable with the system. We'll start simple.
All of the following assume you have a few roomed air brushes with gen and convict loaded, and that there is a marker with a PlayerFactory. This also assumes you have given the player a sword and some arrows.
THE HOLY SWORD
Create a sword and give it to Garrett. Click on the sword's properties and give it a source.
Select Stimulus > Holystim. Propogator Contact. Intensity (and you can change the power of this) to 2. Edit the Shape. Leave Collision and also select Weapon Swing Low.
That will give the sword a default holy power of 2, which is fairly weak. Let's make it a little more complicated.
Go back in and give the sword a second stim. Make it a Holystim with Propogator Contact. Now set the intensity to 4. Go into Edit Shape. Now choose Weapon Swing Mid.
You see where this is going?
Give the sword a third stim, only this time set the intensity to 6 and select Weapon Swing High. Now you have a sword that damages undead a small amount when you give them a back swing, a moderate amount when you give them a forward swing, and a lot when you give them an overhead chop. Now make some zombies and watch them splatter.
FUN WITH DOORS
The previous exercise used a source. Let's try some receptrons.
Create a metal door somewhere in your room. Stick it in front of a passage if you like. Lock it.
Wooden doors you can break down if you hack them enough with your sword, but metal doors are strong and stalwart. Let's change that. Open up the door's properties and go to Act/React > Receptrons. Click "Add." Fill out the fields so that the object is the door's number, the Stimulus is SlashStim (remember this is what a sword has), and no min or max Intensity. Now go over to Effect. Pull down Slay Object. Check Target Object as "me" and Agent Object as "source."
Now go in game. Chop the door once with your sword. Presto! It opens for you.
Let's try something else. Go back and add another receptron to the metal door. This time, make the Stimulus Pokestim (this is what broadheads have). Have no min or max intensity. For the Effect, put in Destroy Object. Target Object is "me."
Now go in game and shoot the door with your bow. A magic a disappearing door!
THE AUTO DOOR
Delete the last door you made (in the previous exercise) and create 2 new metal doors, side by side. I'll refer to them as Door #1 and Door #2. Doesn't matter which is which.
Go to Door #1 and open up it's properties. Add a receptron. For the Stimulus, put in Pokestim, and have no min or max Intensity. For the Effect, put in Frob Object. For the Target Object, put in the number of Door #2.
Now go in game. Shooting an arrow at Door #1 should open Door #2, and shooting it again should close it.
Let's make this practical. Create a button and place it somewhere close to the doors. Now create an EmitterTrap. Place the EmitterTrap so that it is facing Door #1 and is right in front of it. If you're not sure which direction is which, you'll know very shortly. Now add a ControlDevice link from your button to the EmitterTrap. Go in game, and frob the button. An arrow should fire from the EmitterTrap into Door #1 and then Door #2 should open. If the arrow fires in the wrong direction, simply go back into DromEd and rotate the EmitterTrap 180 degrees.
You may have noticed one problem, however. The EmitterTrap only works once. We can solve that by going to the EmitterTrap's properties and going to S > Scripts. In the second box (where it says Script1) type in "ReloadTweqEmit" (no quotes).
You should have a single button which opens and closes a door for you!
Let's try some stuff with AI guys. Delete both of your doors (from the previous exercise) and create a new metal door right in front of your emitter trap. Now create a guard somewhere in your room. Make the guard blind and deaf by going to his properties and going to AI > Attributes > Vision and AI > Attributes > Hearing and setting them both to Null. Now create a TrolPoint in the AI and another one some distance away. Link the TrolPoints together with a ~AIPatrol and an AIPatrol link (as per the DromEd Basic Tutorial). However, don't add any more properties to the guard.
We're going to be using some properties in a receptron, so as suggested at the beginning of this document, go the DromEd command window and type in list_props. Now search in your Thief2 folder for a file called list_props. Open it up in Notepad and save it as a txt file. Now, we want the guard to be able to patrol. We know the name of the normal property (Does Patrol). Go to Find in Notepad and type in "Does Patrol." It should take you down to an entry that looks like this: AI: Ability Settings\Patrol: Does patrol = AI_Patrol. The part we're interested in is the part to the right of the equals sign, AI_Patrol. Remember this.
Now in DromEd, the button from the previous exercise should still go to the EmitterTrap. Make sure that is still the case. When you press it, an arrow should fire into your new door. Go to the door's properties and add a receptron. Make it for Pokestim again with no min or max intensity. For the effect, choose Set Property. For the Target Object, type in the number of your guard. For the Agent Object, choose "me." Now go to Edit Effect. Type in exactly "AI_Patrol" (no quotes).
Are you wondering why you chose "me" for the Agent Object? What you are doing essentially is copying one property from "me" (the door) to the guard. However, the door does not yet have the property (AI_Patrol) that you specified. We'll fix that.
Open up the door's properties and click Add > AI > Ability Settings > Patrol: Does Patrol and then check the box so it registers as TRUE. It doesn't matter that the door is not an AI… for the purposes of Set Property, the property is there.
Now go in game and frob the button. An arrow should fire into the door, and then the guard should start patrolling.
AI FOOLISHNESS PART 2
Now let's make that guard mean. Go to the door's properties and delete the AI Patrol. Then add this: AI > Attributes > Vision and AI > Attributes > Hearing and set both to Above Average. Now go to the door's receptrons and delete the receptron you had in there before. Add a new one. Set it up as normal for Pokestim with no min or max Intensity. Set the Effect for Set Property with Target Object as your guard and Agent Object as "me" again. However, this time there will be a different Edit Effect. Go to Edit Effect and type in AI_Hearing (you'll find this in the list_props document). Now add a 2nd receptron set up exactly the same as the first, with the one exception being the Edit Effect. On this second receptron, change the edit effect to AI_Vision.
Now go in game and frob the button. Your blind and deaf guard will suddenly become very mean.
AUTO FROB SIGNS
Let's combine everything you've learned so far to make easy auto-frob signs. Up until now, you've been working with concrete, pre-existing stims of the contact variety. No longer.
Delete everything from the previous exercises in your mini-level. Create 3 signs and place them fairly far away from one another inside. It doesn't matter what the signs are, but you'll find them in the Object Hierarchy under Decorative > Sign. For each sign, give them the following properties:
First off, add S> Scripts and type "StdBook" (no quotes) in the first line. Then, add Engine Features > Frob Info and set WorldAction to Script AND FocusScript. Now add Book > Text. Type in the name of a text that you have in your books folder (see the tutorial on books if you don't know how to create one). In short, create a folder called "books" in your Thief 2 folder and a folder inside this one called "English". In the "English" folder place your book str files. You'll need 3 of them, one for each sign. I'll call mine sign1, sign2, and sign3. So anyway, what you add for each sign under Book > Text is the name of the book str file you want associated with it.
Now from here, you should be able to go in game. Try frobbing one of your signs. You should see text appear at the top of your screen just as if you were reading a plaque. Make sure this first step works before moving on. Again, see tutorials on books if you haven't covered them yet.
Now, go into the Object Hierarchy and drag the top menu down from Archetypes to Act/React Stimuli. Hilight Stimulus and then click "Add." Type in the name of a new stimulus. I'll call mine signstim.
Now close out of the Object Hierarchy. In the command window, type:
Now, save your gamesys as sign.gam into your Thief2 folder. Now save your mission also (pick a name).
RE-OPEN your mission. You should see sign.gam indicated in the lower left corner of the editor, and everything should still be in place. You should still have three signs that are set to read like a book when frobbed.
Now create a marker. Click on the marker's properties and go to Act/React > Sources. Add a source. For the stimulus, select your custom stim, the one I called signstim. It should appear at the bottom of the list. If it does not, then you probably did something wrong in the previous steps.
For Propogator, select Radius. For Intensity, choose a number that you like. I'll pick 10.
Now go to Edit Shape. You want the radius to be small, but not too small. Let's set it to 2. For Flags, check None; you don't want this stim limited by terrain. For Dispersion, click None; you want the same intensity present over the entire 2 foot radius.
Now go to Edit Life Cycle. Check No Max Firings under Flags. Make sure both Max Firings and Intensity Slope are set to 0. Now for period, you want something fairly small. Let's say 500. That means the stim will fire twice every second. If you have a lot of radial stims going off in your level at small intervals, you can really affect frame rate in a bad way. However, it should be perfectly all right to have a few moderate stims going off an any one time. This one will be going off constantly, but shouldn't hurt things at all by itself.
Now exit out of the marker's properties and go click on one of your sign's properties. Add a receptron. For the Stimulus, select your custom stim (signstim). Set the min and max Intensity appropriately. Because I chose an Intensity of 10 for my stim (above), I would probably set min to 9 and max to 11.
Now for the effect. Choose Frob Object with the Target Object being "me."
Add a second receptron to this sign. Set it up identically to the first, only this time for an effect choose Teleport Object. For the Target Object, type in the number of the marker on which you put the stim. For the Agent Object, choose "me." Now go to Edit Effect. Heading and Pitch and Bank are not important, but Position is. What you want to do is teleport the marker somewhere very far away. I'll set mine to have a Z value of 200. That means the marker will be teleported 200 feet straight up from the center of the sign. The reason for this is so that the sign does not continue frobbing itself. If that were the case, the sign would be frobbed every 500 milliseconds and the text would never go away!
Okay, one final step. Create a Teleport Trap and place it right next to your sign, or right in your sign (it must be less than two feet from the center of the sign). Now, create a ControlDevice link from the Teleport Trap to the marker with the stim. Now, create a ControlDevice link from the sign to the Teleport Trap.
For each of the signs, repeat this process.
Now your auto-frob signs should work. This is what happens: When you look at the sign, the FocusScript triggers the Teleport Trap. The Teleport Trap teleports in the marker with the stim. The stim will go off. The receptron on the sign will receive the stim. This receptron will simultaneously frob the sign itself and will teleport the marker far up into space. The next time you look at the sign, the same thing will happen. This is a clean and repeatable system that can be used for any number of signs you like. This technique uses one extra object per sign (the Teleport Trap) but is not difficult to set up once you get the hang of it. Remember that you do not need a new marker for each sign. You use the same marker and specify this marker on the receptron of each sign that you add.
GETTING AROUND THE META PROPERTY BUG
Okay, say you want to add a Meta Property to an object, but are concerned about the bug (see the beginning of this doc). Make a custom stim of some sort (follow the steps outlined above). I'll call mine metastim.
Say for a moment you have a guard standing in a room, and when you get to a certain point, you want him to start looking around and searching for you. This is done with a Meta Property called Searcher.
Create a guard in a room. Place a Bounds Trigger in an area where the player will go (remember if you only want it to be triggered by the player, Add Physics > Misc > AI Collides With = False). Now create a metal door and an emitter trap somewhere that the player cannot see or hear. Link the Bounds Trigger to the Emitter Trap via a ControlDevice link (as above). When the player crosses the Bounds Trigger, an arrow should fire from the Emitter Trap into the door.
Now open up the door's properties and add a receptron to it. As above, add one for a Pokestim with no min and max Intensity. Now, ordinarily, you would select Add Meta Property, but we cannot do that because of the bug. Instead, click on Stimulate Object. For the Target Object, select the number of the guard. For Edit Effect, type in metastim (or whatever you called your custom stim). Select Multiply by 0, then for Add, choose an arbitrary number. I'll choose 10. Remember this number.
Now go to your guard. Click on Properties and add a receptron. Make this receptron for metastim (or your custom stim) with a min and max intensity just outside of what you selected before on the door. Because I chose 10 for the Stimulate Object previously, I would probably choose 9 and 11 for the current receptron. Now, for the Effect, choose Add Meta Property. Target Object is Me (although it really doesn't matter what object you type in), Agent Object is "Searcher" (no quotes).
In game, when you cross the Bounds Trigger, an arrow should fire into the door. The door should stimulate the guard, and then the guard should start searching. You could use any Meta Property you like for the guard. If you wanted him to start patrolling, for instance, you would use M-DoesPatrol instead of Searcher. But this should give you a way around the Meta Property bug.
THUS ENDETH THIS TUTORIAL
Remember, be creative and always double check your work. If you can generalize these concepts, almost anything is possible!