Objectives System

# Objectives System Implementation

Objectives System implemented in SR1936 and later.

Elements of an Objective:

1. Newsitems Entry.
	1. Type must be 'Objective'
	2. Usually created by 'News' or 'WM'
	3. Title/Headline, Body/Detail Wording
	4. If optional to player, include "Accept Objective" reply.  Otherwise it will be treated as mandatory / always on.
	5. Importance (per Chris in d/a2545):
		1. U1 - objectives at priority level 10 (Tutorials)
		2. U2 - objectives at priority level 20 (Secondary)
		3. U3 - objectives at priority level 30 (Primary)
		4. U4 - objectives at priority level 40 (Victory)
2. Event Entry.
	1. Event Type 'Send Objective'
	2. Include News #  (from  A.) and any parameters
	3. (optional) Trigger with condition tests
3. Status of Event.
	1. Once sent, events can have 'Ongoing/Current', 'Success/Complete', or 'Failure' status (0/1/2)
	2. Status is set by Future Conditional Events / Tests using 'Set Objective Status' Event.
	3. Rewards can be given, emails can be sent, Victory triggered, etc by testing for success using conditions

Example:

* Event ID 21: Send Objective Newsitem, ask for Accept.  This event stays FALSE until player accepts objective.
	+ when accepted, Send-Objective Event is marked as TRUE.  No change to status of newsitem.
* Event ID 35: Assign victory points to hex.  Condition check that ID21 is True.  Persist check.
* Event ID 42: Check if Player's region has victory points total >= amount for victory.  Condition check that ID 35 is True.  Persist check, or check on final date.
* Event ID 43: Set Victory for player.  Condition check that ID 42 is True.  Persist Check, or check on final date.
	+ Status becomes either "success" or "Failure"

### Implementation

* Objectives arrive in the Objectives GUI
	+ New Objectives become the focus
	+ If you complete the focus objective it remains the focus
* An objective is a combination of Scripted Events and Newsitems.
* For objectives that should have an ON MAP NOTICE (OMN), the Category should be set to HELP.  This will create the diamond on-map-notice in the locations specified in the objective message.
	+ If the OMN is not to be placed on the region capitals, then XY locations should be specified (parameter type set to CITYNAME) to trigger the locations on the map.  (having the hex name shown in the message with %s is optional)
	+ If the objective should NOT get diamond omn markers, then set category otherwise (ie Economy, Defense, etc)

### Standards

* To create an objective for the player, use an event "Send Objective" that references an "Objective" type newsitem created by newsitem.
	+ The objective will be true immediately unless the "Accept Objective" reply is specified in which case accepting will make it true. Without the option the objective is mandatory/always on.
	+ The newsitem will be ongoing once sent and remain that way until a "set status" event is used.
	+ The newsitem title is shown as the title in the GUI
	+ The newsitem Statuslinewording is shown as the Short Description
	+ The newsitem Wording1 is shown as the full description when ongoing, wording2 when succeded, wording3 when failed
	+ The newsitems support a sound.  Requested, pending.
	+ The newsitems support pause on event.
		- pauses when the objective arrives, not on success/failure
	+ The newsitems support a newspic
		- backend not yet supported
		- One pic per newsitem, displayed when newsitem is originally sent.  No separate success/failure pictures; instead include a picture in a separate success/failure message sent when that happens.
	+ The newsitem priority determines the objective type
		- 10- Tutorial, 20 - Secondary, 30 - Primary, 40 - Victory
	+ d/a 2552 listbox fills with all sent objective newsitems whether ongoing, successful or failed
		- Most recently added becomes focus objective
		- No specific list sort at this time.

### Implementation notes

* All victory conditions are to be converted to Objective events so that all regions always have at least 1 objective.
* New objectives are to arrive in the Objectives GUI
	+ The Titlebar GUI elements need an visual cue when a new message arrives
	+ All Objective news items need to use a common "new objective sound"
		- Objectives with no choices set are "auto-accepted" and become true in the code
		- Objectives with choices should an "accept" choice which sets the objective true and a "reject" button which deletes the objective.
	+ Objectives back end allows specifying if the objective triggers pause and/or pops up.
		- enabling objective pause is to be separate from event pause
* Sounds - There is to be a "new", "completed" and "failed" sound cue for objectives.
* d/a 2552 objectives list
	+ All objectives (d/a 2552 U0) to be used in popup
		- Shows Type objective, status: any, True/false: any.
			* only "unaccepted" objectives are false
			* declining a false objective is the only way to delete one.
* There must be a "focus" objective that is remembered between savegames

## Scenario/Objective system design

* Similar to design of Events system database
	+ DF - we use the scripted events database - using a series of events to create an objective.
		- call newsitems
		- check conditions
* An objective can have multiple conditions required to complete it (no limit under current system; chain conditions)

* Objective conditions can...
	+ Add to a 'points' total
		- GG - If points are used for "true AND checks" they must chain.
		- GG - Don't use points for secondary objectives.
	+ Trigger an event
		- GG: An event can create/define an objective.  DF: mentioned above, a series of events combine to become an objective with newitems, start/end dates, required conditions.
	+ End the game in a win (alone or in combination)
		- DF: victory / loss conditions still required to use them.
	+ End the game in a loss (alone or in combination)
		- DF: victory / loss conditions still required to use them.

* Can be active from Time 0, or turned on / off at certain dates (GG Note)
* Objective condition can turn / off other Objective conditions (GG Note)
* Objectives can be "named" - for player display purposes - In Newsitems (title, body text)

Proposed Objective elements:

* Destruction of a Region
	+ can condition check for at war
	+ can condition check for region alive OR dead
* Destruction/annex # Regions
	+ this requires a count variable
	+ this requires a scripted event to "increase/decrease count variable".
	+ (we may want to count other things)
* Taking a capital
	+ we can condition check for hex ownership changes but specifically taking a country capital. - task 17596
* Destroying an HQ Unit (or a specific # of units) - task 17597
	+ need a condition check for testing if a unit # is destroyed OR created (actually built or acquired) -
	+ with this would go a count - "destroy X units by type #, class #, branch #"
		- scripted event - start count.
		- scripted event - add / modify count (including reset to zero)
		- (see task 17601  for thoughts on multiple counts - as it's currently set to only have one count per region available)
* Destroy a specific unit or facility
	+ see destroy HQ unit.
* Score (old SR2020 system)
	+ would need a conditional check - if score 1 is > X
* Unification Vote (old SR2020 system)
* Achieve a technology (Space Race or any other)
	+ condition test required...does region X know tech Y - task 17602
* Take a hex
	+ DF?  take all ownership of a particular BZ / TH?  GG: Yes, possible (at end of day) - task 17603
* Reinforce a hex (enter a hex) with a specific unit, or class, or branch
	+ DF? - What about a BZ or TH?  Count units by unit type, class, branch to complete (i.e. combine your navy into BZ 14 - (27 boats).  GG: Possible, triggered at end of day.  Interim count not necessarily possible.
* Hold a hex
	+ DF? - Modify above - Hold a Hex - in ZOC?  what about ocean hexes.  Can a unit 'be present'?  GG: Just 'hold' owner
* Hold for x continuous days
* Take/hold # of a specific facility of region x
	+ Could also be # of type of a facil, ie military, urban (city), etc
* Destroy # of units of region x
* Destroy # of unit type y of region x (ie aircraft carriers)
	+ DF - requires "destroy unit" conditional check, by type, class, branch etc... (requested above)
	+ DF - requires "counting".  Can do a series of conditional checks if there are not too many items involved.
* Lose # of units, unit class, unit branch, or unit type y (ie to trigger loss)
	+ Destroy or loss can also be restricted to theatre (or battlezone)
* Force region to surrender (MAR or DAR limit hit)
	+ DF - able to be done now...
		- conditional check MAR/DAR "Regional Approval Rating Test"
		- event "surrender" conditional on above check.
* Time limits - can be changed based on achieving other victory elements
* Capture # hexes (from any, or from region x)
	+ DF - task 17604 + counting
* Facility - start construction, complete, pause, etc.  Also, scrap, destroy, remove etc.
* DF? - reserve X units (Pearl Harbor - shore leave)  GG: Can reserve
* DF? - change stance with nation - work to get alliance or declare war.
	+ DF - just start improving their relations via "Change Relationship"?
* DF? - do not take hex - lose if you do - but AI under your control must understand that they should stay away too.
	+ Use a NOT with the above "capture hex".
	+ scripted event required - avoid Hex, BZ, TH for AI ... DF - lower priority.
* DF? - can we 'damage' a facility?  (attempt to destroy some location with bombers)
	+ DF - yes Type 41 - damage facility
* DF? - which OBJ above allows us to take a hex with a specific type of unit?  (change ownership etc. with paratroopers for example.)  Can we do this?
	+ DF - objectives are made up of several scripted events (incl. condition checks).  We can
* DF? - Can objectives be used to wrap back on each other... ?   example?  attack hex A... when you take it, get new OBJ for hex B... if you lose hex A, you get original OBJ to attack hex A again?  (Battle of the Bulge... if one side gains momentum... and pushes back... then how does the other side respond?) - otherwise, how can we simulate a push / pull situation?

## Tutorial / Help System Elements

### Tutorial:

* Tutorial Objectives are created as Objectives -
	+ Send Objective Event, combined with Objective Newsitem
	+ If they should have a map-location OnMapNotice, then use Objective-OMN Newsitems type.

### Help Notices

* Can be in tutorial, or not
* Notices meant to stay until a new one appears, or
* Are created as Emails/Newsitems
	+ Use Send Email Event, combined with Objective Tutorial
	+ If they should have a map-location OnMapNotice, then use Tutorial-OMN Newsitems type.
	+ type:  Tutorial OR Tutorial/OMNews (map-location)
	+ department: Dept could be anything (minister dept), or Help
	+ Category: Help,
	+ Createdby: News.
	+ Importance:  Use importance level to indicate higher/lower: 30 default. < 21 filtered out at normal level.
* Highlight objects can be specified by putting datacode in Panel0/Panel1/Panel2/Panel3 values
	+ to select a specific udef, add udef\*10000.  ie data code 2550 udef 1 is 12550
		- example - 680 udef 7 = 70680
		- example - 530 udef 1 = 10530
		- example - 1961 udef 2 = 20000 + 1691 = 21691
	+ if object is a radiobutton parent, then the udef will be found inside the object.
	+ To select a specific listbox header (for header or listbox fills under a header), add header \*10000000 (ten million)
		- Header numbers start at 1.  This supports 1-9 at present.
		- example - 798 udef 0 header line 4 = 40000798
* Question - can we test for if a D/A has been used/pressed?
	+ You can test for the 'result' of some actions - ie Queue has been added to
	+ Could possibly turn off the button highlight when the highlighted button is pressed
	+ Could possibly turn off/delete the help item when the final highlighted button is pressed, ie automatically.