Objectives

Originally written by Ishtvan on http://forums.thedarkmod.com/topic/4121

Overview

A mapper may add on objectives by setting key/values on a target_tdm_addobjectives entity and triggering it. If you want to add objectives at the very beginning of the map, put in a target_addobjectives and put that entity in as a target of the worldspawn. The worldspawn will trigger it on map start.

Objectives consist of overall objectives, objective components, and boolean relationships for failure and success. A map can have any number of overall objectives, and each objective can have any number of components.

Example

Objective 1 text: "Kidnap Benny and get out to the streets"

Objective 1 Components:

1. Benny is KO'd
2. Benny is at the map exit
3. Player is at the map exit
4. NOT( Benny is dead )

Boolean relationship for Obj. 1 COMPLETION: 1 AND 2 AND 3 AND 4

Boolean relationship for Obj. 1 FAILURE: NOT(4) (If Benny is dead we can't kidnap him alive)

Objective Attributes

• Possible Objective States:

• OBJ_INCOMPLETE
• OBJ_COMPLETE
• OBJ_FAILED
• OBJ_INVALID

• Mandatory: Set to false for optional objective that doesn't fail the mission if you fail it.

• Irreversible: Irreversible objectives lock their state once they're changed to COMPLETE or FAILED. Irreversible components will only change state once and then stay in that state. (Note: There are scriptfunctions to reset irreversible objectives and components if the FM author wants to let them change again for some reason).

• Ongoing: Use this for objectives that should remain successful, but won't be checked off until the end of the mission. For example, "don't blackjack more than two people" is successful at the start of the mission, because you haven't blackjacked anyone yet, but when you KO one person and the KO callback is made to the objective system, and the system then sees that only one person has been KO'd, the system needs some way of knowing not to say "Objective Complete" when you KO that first person, i.e., that this is an ongoing objective.

• Visible: Whether the objective appears in the player's Objectives GUI. Use invalidated and hidden objectives to queue up objectives for later, or hidden but valid objectives as anothe way of scripting events when the player does a certain thing, since objectives can launch an arbitrary script after they're completed.

• Difficulty: This specifies the difficulty level this objectives applies to. When this spawnarg is set (e.g. "obj2_difficulty" "1"), this objective is only visible at difficulty level 1 (="Hard", remember that difficulty level numbers start with 0).

• Enabling Objectives: This is a list of other objectives that must first be completed before this objective can be completed. For example, we shouldn't mark "objective complete" for exiting the mission until all the other mission goals have been completed.

• Completion/Failure scripts: Name of a script to call when this objective is completed or failed. For example, this could be used in campaigns to set up optional objectives in one mission that effect other missions. This feature could also be used as a general scripting aide if the author wants to set up the conditions for something happening using a hidden objective.

Objective Component Attributes

Possible 'Objective Component' Types:

• item (picked up or dropped an inventory item)
• kill (also includes non-living things being destroyed)
• ko
• ai_find_item (not implemented)
• ai_find_body (not implemented)
• alert
• location (Item A at location B, where "A" is any entity that must have the key "objective_ent" set to "1" on it, and location B is a special entity info_objective_location. Later on we may support using the D3 location system as well)
• custom (custom component that is set true/false by a map script)

These components are triggered every N milliseconds by a system clock:

• distance (distance between the origin of entity X and that of entity Y)
• custom_clocked (runs a custom map script that should check something and set the objective)

Specification Methods: Specification methods determine what the objective component is looking for. Does it look at how many AI of a specific team you've KO'd, how many humans, how many overall, or whether you've KO'd an AI with a certain name? Each objective component can have up to two of the following specifiers (Not all components can take two specifiers, and not all specifiers make sense for all component types, future documentation will cover that).

The following apply to both AIs and items:

• none
• name (name of entity)
• overall (overall count of something: kills, loot, kos, etc)
• group (inventory group)
• classname (soft/scripting classname)
• spawnclass (hard / SDK classname)

The following specification methods apply only to AI:

• ai_type (human, beast, undead, bot, etc)
• ai_team (mapper defined team of the AI)
• ai_innocence (For distinguishing noncombatants)

Integer and String Arguments: A component can have an arbitrary number of int and string arguments that are fed in space delimited lists. The type of component and specifier determines which args it will use and what it will do with them. For example, the first integer arg is often used to determine how many times something can happen, e.g., the player is only allowed 4 KOs, or must get 500 loot. Not all events are counted up though. The only things that are counted up are things in the mission statistics like loot and kills, so everything else is pretty much a one shot deal where it happens once. Future documentation will detail which objective events are counted up and which are one shots.

Additional Component Attributes

• not (If this is set, the component is considered NOTed. So if the component is to kill 5 AI, and it's NOTted, it will remain true until 5 AI are killed, then be set to false)
• Irreversible
• clock_interval (For clocked components, this determines how often they are updated)

Conclusion

Using components that combine component types with up to 2 entity arguments and 2 specifier types, plus objectives that are a boolean combination of those components should hopefully allow for a variety of different objectives.