The ConVict Script.
Or, A Novice's Little Helper. Hey! No Talking You!
I. Data-driven victory conditions coding for Thief

The Thief generic Conditions for Victory script ("ConVict") provides a data-driven means for Thief designers and amateur Thief mission builders to specify mission victory conditions, without resort to further scripting code.  It does this by interpreting a set of quest variables as a coded specification of victory conditions.  Since quest variables are a component of the mission file which can be edited using DromEd, no tools other than the editor and a copy of the CONVICT.OSM script file are required.  Support for all of the most common victory conditions in Thief missions is included, and the script is compatible with the existing Thief means of varying victory conditions by difficulty level. Users specify each victory condition with a quest variable indicating the general type of goal (e.g. steal an object, get loot) and one or more additional quest variables indicating the specific target of the goal.  Optionally, additional quest variables may be set to change the
logical sense of the goal (the most important example being to specify an event which constitutes a mission failure, as opposed to the usual goal which is one of several requirements for success).

II. Types of Goal

ConVict supports any number of goals, of several types.  Each goal must be given an ID number from 0 to 31 (inclusive).  The text for goals on the Objectives screen is found in the goals.str entry for the current mission in the intrface.crf resource, indexed by this ID number.  ID numbers should be assigned in the order you want the goals to appear on the Objectives screen, noting that some goals may be skipped on some difficulty levels.  The first ID number can be any whole number the user chooses, but no ID numbers should be skipped.

Once an ID number for the goal is chosen, the goal is created by creating a quest variable named goal_type_n, where n is the actual ID number.  The value of this quest variable indicates the type of goal, chosen from the following list:
 

  • 1. Steal an object.  The goal is counted incomplete again if the object is dropped.
  • 2. Kill a Creature.
  • 3. Get a certain amount of loot.
  • 4. Go to a location. The room archetype of the target room must have the script "WelcomeRoom" on it for this to work. The goal is counted incomplete again if the room is departed.
[Note: In order to use objective 4 – "Go to a location" – you must first create a room brush (refer to tutorial document for creating room brushes).  Then, select that brush and look down at the bottom center of the screen.  Click the "Create" button to bring up the "Room Hierarchy" dialog box.  Then, click the "Add" button and give the room a specific object name, like "EndPoint."  Click the "OK" button, and you’ll notice that your new room type now shows up on the room hierarchy. Highlight that room, then click the "Create" button.  Now, whenever you create a room, you will be creating a room of that type (see the tutorial document for more help with hierarchies and creating objects). Look down at the bottom center of the screen and make a not of the room brush’s number: this is the number you need to use when specifying objective 4 – "Go to a location."]

Each of these goals also requires certain other quest variables to be set to specify the exact target of the action.  If these variables are not created, the goal cannot be satisfied.  For goals of type 1,2, or 4, set the quest variable goal_target_n (where n is again the ID number of the goal) to the object ID of the object to be taken, creature to be killed, or location to be entered.  In each case any object which inherits from the specified object ID in the object hierarchy will count to achieving the goal (so the goal "Kill a servant" would be goal_type_n=1, goal_target_n=–52, since the object ID of the servant archetype is –52).

Goal type 3 (get loot) requires a vector target, since a loot goal can include a total amount of loot, as well as certain amounts in gold, gems, or goods specifically, and may also require specific loot items. Several quest variables may be set to specify the exact loot goal, and all such variables which exist must be satisfied to satisfy the goal.

These variables are as follows:
 

  • goal_loot_n: The variable value is a total amount of loot which must be acquired to satisfy the goal.
  • goal_gold_n: The variable value is an amount in the gold subtotal which must be acquired to satisfy the goal.
  • goal-_gems_n: The variable value is an amount in the gems subtotal which must be acquired to satisfy the goal.
  • goal_goods_n: The variable value is an amount in the goods subtotal which must be acquired to satisfy the goal.
  • goal_special_n: The variable value is a set of bits which must be present in the special accumulator field to satisfy the goal.
The "special" flag of the loot value is a binary quantity which should be set to a unique power of 2 for each loot item which is to be detectable this way.  They object representing the sum of all loot in the player’s inventory will have all of the bits set which were set in any loot item acquired.

Some things to watch out for: any type 1 goal should be for a target that does not combine with other objects of the same type in the player’s inventory.  Objects that combine do not necessarily retain their object ID’s, and the script system cannot easily detect when they go into your inventory.  The only case where such goals are supported is the loot stack, where individual items can be detected by giving them a "special" flag in their loot value.  Note that any goal to take a specific item is a type 3 goal, not a type 1 goal, if that object is loot!

III. Modifying goals

Several additional parameters can be created to change the logical interpretation of the goal by ConVict.  Each of these modifies a particular goal, indicated by ID in the name of the quest variable.
 

  • GOAL_MIN_DIFF_n: Below the difficulty level indicated by the value of this quest variable, the goal effectively does not exist.
  • GOAL_MAX_DIFF_n: Above the indicated difficulty level, the goal does not exist.
  • GOAL_FINAL_n: If this variable exists and is not zero, then when this goal would normally be achieved, if this does not end the mission, then the goal remains incomplete.  This is used for goals which implicitly should only count when all other goals have been achieved, such as "exit the mission area"
  • GOAL_REVERSE_n: If this variable exists and is not zero, reverses the sense of the goal.  When it would normally be achieved, it is marked failed, and it is marked complete only if all other goals are achieved without such a failure having occurred.  This allows you to set goals of the nature "Don’t kill any servants" as opposed to "Kill a servant."
  • GOAL_NO_BREACH_n: is a setting found in many shipping Thief mission files, which is similar to GOAL_REVERSE_n, but has no meaning to ConVict and can be safely ignored.
  • GOAL_IRREVERSIBLE_n: Ordinarily, a completed goal to take an object or go to a location can be marked incomplete again if the object is dropped or the location is left. If this variable exists and is not zero, the goal cannot be set incomplete once it has been completed.  This is frequently the intuitive behavior for "go to a place" goals, such as "break into the mansion."
Before Death came,
The Liars were made to feast apon the hands of the Thieves,
And the Thieves were made to ingest the tounges of thief Liar brothers,
And we praised the Master Builder for His Judgements.
--The Hammer Book of Tenets

Go back to Official Guides & Tutorials