Objectives Manager

Provides an interface for setting and managing the scripted objectives that appear in the scripted objectives panel, underneath the advisor in campaign and battle. With no advisor present, the scripted objectives panel appears in the top-left of the screen (it is displaced down the screen should the advisor appear). Scripted objectives are mainly used by tutorial scripts, but are also used in quest battles to deliver gameplay objectives.

Once a scripted objective is set, with objectives_manager:set_objective, it is down to the script to mark it as complete with objectives_manager:complete_objective or failed with objectives_manager:fail_objective, and to subsequently remove it from the scripted objectives panel with objectives_manager:remove_objective.

The objectives manager also provides an interface for setting up an objectives chain, which allows only one objective from the chain to be shown at a time. This is useful for tutorial scripts which are providing close instruction to the player, allowing them to set up a cooking-recipe series of mini-steps (e.g. "Select your army" / "Open the Recruitment panel" / "Recruit a Unit") which are chained together and can be advanced/rewound.

Note that the battle_manager and campaign_manager both create an objectives manager, and provide passthrough interfaces for its most common functionality, so it should be rare for a battle or campaign script to need to get a handle to an objectives manager, or call functions on it directly.

Loaded in Battle loaded in battle
Loaded in Campaign loaded in campaign
Back to top

Creation

objectives_manager:new()
Creates an objective manager. It should never be necessary for client scripts to call this directly, for an objective manager is automatically set up whenever a battle_manager or campaign_manager is created.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_objectives.lua, line 39

Back to top

Usage

Once an objectives_manager object has been created with objectives_manager:new, functions on it may be called in the form showed below.

Example - Specification:

<objectives_manager_object>:<function_name>(<args>)

Example - Creation and Usage:

local om = objectives_manager:new()                    -- set up automatically by campaign or battle managers
local uic_objectives = om:get_uicomponent()            -- calling a function on the object once created
Back to top

Debug

objectives_manager:set_debug([boolean debug mode])
Sets the objectives manager into debug mode for more verbose output

Parameters:

1

boolean

optional, default value=true

debug mode

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_objectives.lua, line 105

Back to top

UI Component

objectives_manager:get_uicomponent()
Gets a uicomponent handle to the scripted objectives panel

Returns:

  1. uicomponent

defined in ../working_data/script/_lib/lib_objectives.lua, line 154

Back to top

Objectives

objectives_manager:set_objective(string objective key, [number param a], [number param b])
Sets up a scripted objective for the player, which appears in the scripted objectives panel. This objective can then be updated, removed, or marked as completed or failed by the script at a later time.
A key to the scripted_objectives table must be supplied with set_objective, and optionally one or two numeric parameters to show some running count related to the objective. To update these parameter values later, set_objective may be re-called with the same objective key and updated values.

Parameters:

1

string

Objective key, from the scripted_objectives table.

2

number

optional, default value=nil] number param a, First numeric objective parameter. If set, the objective will be presented to the player in the form [objective text]: [param a

First numeric objective parameter. If set, the objective will be presented to the player in the form [objective text]: [param a]. Useful for showing a running count of something related to the objective.

3

number

optional, default value=nil] number param b, Second numeric objective parameter. A value for the first must be set if this is used. If set, the objective will be presented to the player in the form [objective text]: [param a] / [param b

Second numeric objective parameter. A value for the first must be set if this is used. If set, the objective will be presented to the player in the form [objective text]: [param a] / [param b]. Useful for showing a running count of something related to the objective.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_objectives.lua, line 290

objectives_manager:complete_objective(string objective key)
Marks a scripted objective as completed for the player to see. Note that it will remain on the scripted objectives panel until removed with objectives_manager:remove_objective.
Note also that is possible to mark an objective as complete before it has been registered with objectives_manager:set_objective - in this case, it is marked as complete as soon as objectives_manager:set_objective is called.

Parameters:

1

string

Objective key, from the scripted_objectives table.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_objectives.lua, line 350

objectives_manager:fail_objective(string objective key)
Marks a scripted objective as failed for the player to see. Note that it will remain on the scripted objectives panel until removed with objectives_manager:remove_objective.

Parameters:

1

string

Objective key, from the scripted_objectives table.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_objectives.lua, line 383

objectives_manager:remove_objective(string objective key)
Removes a scripted objective from the scripted objectives panel.

Parameters:

1

string

Objective key, from the scripted_objectives table.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_objectives.lua, line 402

Back to top

Objective Chains

Objectives chains allow calling scripts to set up a sequence of objectives that are conceptually linked in such a manner that they are sequentially delivered to the player. This is useful for tutorial scripts which may wish to deliver close support to the player while they are performing a task for the first time e.g. "Open this panel" then "click on that button" then "select that option" and so on. Client scripts can update the status of an objective chain by name, and the objectives manager automatically removes or updates the onscreen objective.

An objective chain may be started with objectives_manager:activate_objective_chain, updated with objectives_manager:update_objective_chain and finally terminated with objectives_manager:end_objective_chain. Only one objective chain may be active at once, so terminate an existing chain before starting a new one.

objectives_manager:activate_objective_chain(
  string chain name,
  string objective key,
  [number number param a],
  [number number param b]
)
Starts a new objective chain. Each objective chain must be given a unique string name, by which the objectives chain is later updated or ended.

Parameters:

1

string

Name for the objective chain. Must not be shared with other objective chain names.

2

string

Objective key, from the scripted_objectives table.

3

number

optional, default value=nil

First numeric objective parameter. See documentation for objectives_manager:set_objective.

4

number

optional, default value=nil

Second numeric objective parameter. See documentation for objectives_manager:set_objective.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_objectives.lua, line 518

objectives_manager:update_objective_chain(
  string chain name,
  string objective key,
  [number number param a],
  [number number param b]
)
Updates an objective chain, either with new parameters for the existing objective or a new objective (in which case the existing objective will be removed).

Parameters:

1

string

Name for the objective chain.

2

string

Objective key, from the scripted_objectives table.

3

number

optional, default value=nil

First numeric objective parameter. See documentation for objectives_manager:set_objective.

4

number

optional, default value=nil

Second numeric objective parameter. See documentation for objectives_manager:set_objective.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_objectives.lua, line 548

objectives_manager:end_objective_chain(
  string chain name,
  string objective key,
  [number number param a],
  [number number param b]
)
Ends an objective chain.

Parameters:

1

string

Name for the objective chain.

2

string

Objective key, from the scripted_objectives table.

3

number

optional, default value=nil

First numeric objective parameter. See documentation for objectives_manager:set_objective.

4

number

optional, default value=nil

Second numeric objective parameter. See documentation for objectives_manager:set_objective.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_objectives.lua, line 597

objectives_manager:reset_objective_chain(string chain name)
Removes this objective chain from the previous objective chains list, which allows it to be triggered again.

Parameters:

1

string

chain name

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_objectives.lua, line 622

Last updated 25/08/2021 12:07:50