Spy and TrapSMTrans

Beware: this tutorial is not for the meek. You need to have at least a little bit of experimental aptitude. If you have worked in science at all, it is a given. Otherwise, follow me closely and I’ll show you the world.

About Spy

Spy is a script that reveals the inner workings of an object. It writes messages out to the monolog.

A script message is a notification about an event. When you kill something, when something sees you, when you pick something up, when you frob something – all of these events cause script messages to be sent.

Spy intecepts all of these messages and writes them out to the monolog in the exact order they are received.

For you, this means that you can cause an event and see what sequence of script messages ensues. Each message means something different, and many messages are not unique to a single event. But there’s usually a single message that you want to catch.

In the following section, I’ll describe an experiment with Spy to show you how you can use it to create custom triggers for just about any sort of event.

Using Spy

Copy the debug version of script.osm out of the developer package into your Thief directory.

Open an experimental level in Dromed and load the script module if you haven’t already done so.

Type “mlog monolog.txt” in the command console.

Create a perishable AI (someone who can die) and put the “Spy” script on it. Give the player a weapon.

Go into game mode and fight the AI to the death. Let the AI hit the player a number of times. When the AI is dead, exit game mode.

Open monolog.txt.

The lines that start with SPY are the script messages. What should you be seeing?

There will likely be several messages. “Damage”, “Slain”, “StartAttack”, and “EndAttack”. AS you can probably guess, the first one is sent when you damage the AI and the second one when you kill it. StartAttack happens at the very beginning of an attack, and EndAttack at the end. An “attack” refers to the raising and swinging of a melee weapon or the aiming and firing of a ranged weapon. Pay special attention to “Alertness”. We’re going to use that message to set up a custom trigger using another script.

As is evident from this example, most message names are self-explanatory. You can repeat this kind of experiment for almost all objects and all kinds of events in the game. Pay special attention to the order of messages; the message in the middle is usually the most important. The thing to remember while doing this kind of experimentation is to restrict your experiment to a single event. More than one event will hopelessly muddle the relationship between a particular event and the script messages that accompany it.

There is a simple rule, taken from science, that determines the order in which you should examine objects in a scenario to find out what makes it tick: go inside out. Start with the center of the scenario. If you want a sign that displays text on focus, start with the sign, not the player; if you want the player to be invincible, start with the player, not the AI. From there, progress to examining the other participants of the scenario, and work that way until you decipher the entire scenario and which script messages affect it.

After having done that, record the data on a piece of paper. You must have a clear conception of a situation before you engineer a method to make it happen.

About TrapSMTrans

After discovering the inner workings of the script message subsystem, it would do well to put them to use. But how?

From the fan’s perspective, the subsystem’s greatest weakness is its lack of a generic trigger that would react to a user-specified script message. Individual triggers must exist exist to accommodate all relevant script messages. Sometimes this is not possible. Think about how many script messages never had a trigger. Moreover, the new scripts occasionally create and send off script messages of their own. The Validator script requires a Validate message with a state parameter, a message that must be sent using a ScrMsgRelay trap.

TrapSMTrans provides a generic trigger. All messages received by the trigger can be converted to TurnOn messages and sent to any trap, visible (lights, buttons, levers, doors) or invisible (metatraps and effects). All that you must know is which object receives the message and which message represents the right event.

Using TrapSMTrans

To demonstrate the use of this script within the context of an unusual script message, consider the aforementioned “Alertness” message. How would one set up a situation where the light in a room goes on when the AI in that room sees the player?

Create the light from OldElecWallLight. Attach the TrapSMTrans script to the AI. Link the AI to the light with ScriptParams. In the Data, type “Alertness”. Go into game mode in a room separate from the AI. Walk up to the AI and watch the light.

When creating generic triggers such as this, keep in mind that you can intercept any message you need to, but you will not be able to get the additional data that may be crucial to that message. Make sure that the messages you use in the trigger are unique to the events you are trying to intercept, or there could be a number of undesirable causes for the effect you are trying to achieve.


The single serious limitation of the system, not incurable, is the length restriction on ScriptParams links (16 characters). Most messages are shorter, however, and this shouldn’t be a problem. If it evolves into an issue, please send the author an email to alert him. Thank you.

About this entry